--- /dev/null
+Contributors to the Python Documentation
+----------------------------------------
+
+This file 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.
+
+* Aahz
+* Michael Abbott
+* Steve Alexander
+* Jim Ahlstrom
+* Fred Allen
+* A. Amoroso
+* Pehr Anderson
+* Oliver Andrich
+* Jesús Cea Avión
+* Daniel Barclay
+* Chris Barker
+* Don Bashford
+* Anthony Baxter
+* Bennett Benson
+* Jonathan Black
+* Robin Boerdijk
+* Michal Bozon
+* Aaron Brancotti
+* Georg Brandl
+* Keith Briggs
+* 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.
+* Jeff Epler
+* Michael Ernst
+* Blame Andy Eskilsson
+* Carey Evans
+* Martijn Faassen
+* Carl Feynman
+* Hernán Martínez Foffani
+* Stefan Franke
+* Jim Fulton
+* Peter Funk
+* Lele Gaifax
+* Matthew Gallagher
+* 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
+* 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
+* Detlef Lannert
+* Piers Lauder
+* Glyph Lefkowitz
+* Marc-André Lemburg
+* Ulf A. Lindgren
+* Everett Lipman
+* Mirko Liss
+* Martin von Löwis
+* Fredrik Lundh
+* Jeff MacDonald
+* John Machin
+* Andrew MacIntyre
+* Vladimir Marangozov
+* Vincent Marchetti
+* Laura Matson
+* Daniel May
+* Doug Mennella
+* Paolo Milani
+* Skip Montanaro
+* Paul Moore
+* Ross Moore
+* Sjoerd Mullender
+* Dale Nagata
+* Ng Pheng Siong
+* Koray Oner
+* Tomas Oppelstrup
+* Denis S. Otkidach
+* Zooko O'Whielacronx
+* William Park
+* Joonas Paalasmaa
+* Harri Pasanen
+* Bo Peng
+* Tim Peters
+* Christopher Petrilli
+* Justin D. Pettit
+* Chris Phoenix
+* François Pinard
+* Paul Prescod
+* Eric S. Raymond
+* Edward K. Ream
+* Sean Reifschneider
+* Bernhard Reiter
+* Armin Rigo
+* Wes Rishel
+* Jim Roskind
+* Guido van Rossum
+* Donald Wallace Rouse II
+* Nick Russo
+* Chris Ryland
+* Constantina S.
+* Hugh Sasse
+* Bob Savage
+* Scott Schram
+* Neil Schemenauer
+* Barry Scott
+* Joakim Sernbrant
+* Justin Sheehy
+* Michael Simcich
+* Ionel Simionescu
+* 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
+* Ville Vainio
+* Martijn Vries
+* Charles G. Waldman
+* Greg Ward
+* Barry Warsaw
+* Corran Webster
+* Glyn Webster
+* Bob Weiner
+* Eddy Welbourne
+* Mats Wichmann
+* Gerry Wiener
+* Timothy Wild
+* Collin Winter
+* Blake Winton
+* Dan Wolfe
+* Steven Work
+* Thomas Wouters
+* Ka-Ping Yee
+* Rory Yorke
+* Moshe Zadka
+* Milan Zamazal
+* Cheng Zhang
--- /dev/null
+#
+# Makefile for Python documentation
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+
+# You can set these variables from the command line.
+PYTHON ?= python
+SVNROOT ?= http://svn.python.org/projects
+SPHINXOPTS ?=
+
+ALLSPHINXOPTS = -b$(BUILDER) -dbuild/doctrees $(SPHINXOPTS) . build/$(BUILDER)
+
+.PHONY: help checkout update build html web htmlhelp clean
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " web to make file usable by Sphinx.web"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+
+checkout:
+ @if [ ! -d tools/sphinx ]; then \
+ echo "Checking out Sphinx..."; \
+ svn checkout $(SVNROOT)/doctools/trunk/sphinx tools/sphinx; \
+ fi
+ @if [ ! -d tools/docutils ]; then \
+ echo "Checking out Docutils..."; \
+ svn checkout $(SVNROOT)/external/docutils-0.4/docutils tools/docutils; \
+ fi
+ @if [ ! -d tools/pygments ]; then \
+ echo "Checking out Pygments..."; \
+ svn checkout $(SVNROOT)/external/Pygments-0.8.1/pygments tools/pygments; \
+ fi
+
+update:
+ svn update tools/sphinx
+ svn update tools/docutils
+ svn update tools/pygments
+
+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."
+
+web: BUILDER = web
+web: build
+ @echo "Build finished; now you can run"
+ @echo " PYTHONPATH=tools $(PYTHON) -m sphinx.web build/web"
+ @echo "to start the server."
+
+htmlhelp: BUILDER = htmlhelp
+htmlhelp: build
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ "build/hhp/pydoc.hhp project file."
+
+clean:
+ -rm -rf build/*
+ -rm -rf tools/sphinx
--- /dev/null
+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 install Python 2.5 or higher; the toolset used to build the docs are
+written in Python. The toolset used to build the documentation is called
+*Sphinx*, it is not included in this tree, but maintained separately in the
+Python Subversion repository. Also needed are Jinja, a templating engine
+(included in Sphinx as a Subversion external), 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.
+
+ * "web", which builds files usable with the Sphinx.web application (used to
+ serve the docs online at http://docs.python.org/).
+
+ * "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.
+
+A "make update" updates the Subversion checkouts in `tools/`.
+
+
+Without make
+------------
+
+You'll need to checkout the Sphinx package to the `tools/` directory::
+
+ svn co http://svn.python.org/projects/doctools/trunk/sphinx tools/sphinx
+
+Then, you need to install Docutils 0.4 (the SVN snapshot won't work), either
+by checking it out via ::
+
+ svn co http://svn.python.org/projects/external/docutils-0.4/docutils tools/docutils
+
+or by installing it from http://docutils.sf.net/.
+
+You can optionally also install Pygments, either as a checkout via ::
+
+ svn co http://svn.python.org/projects/external/Pygments-0.8.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, web or htmlhelp (for explanations see the make
+targets above).
+
+
+Contributing
+============
+
+For bugs in the content, the online version at http://docs.python.org/ has a
+"suggest change" facility that can be used to correct errors in the source text
+and submit them as a patch to the maintainers.
+
+Bugs in the toolset should be reported in the Python bug tracker at
+http://bugs.python.org/.
+
+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-2007 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.
+----------------------------------------------------------------------
--- /dev/null
+To do
+=====
+
+* split very large files and add toctrees
+* finish "Documenting Python"
+* care about XXX comments
--- /dev/null
+=====================
+About these documents
+=====================
+
+
+These documents are generated from `reStructuredText
+<http://docutils.sf.net/rst.html>`_ sources by *Sphinx*, a document processor
+specifically written for the Python documentation.
+
+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 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!
--- /dev/null
+.. _reporting-bugs:
+
+************************
+Reporting Bugs in Python
+************************
+
+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.
+
+If you find errors in the documentation, please use either the "Add a comment"
+or the "Suggest a change" features of the relevant page in the most recent
+online documentation at http://docs.python.org/.
+
+All other bug reports 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. If you don't already have a tracker account, select the
+"Register" link in the sidebar and undergo the registration procedure.
+Otherwise, if you're not logged in, enter your credentials and select "Login".
+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 "Change Note" field, describe the problem in detail, including what you
+expected to happen and what did happen. Be sure to include whether any
+extension modules were involved, and what hardware and software platform you
+were using (including version information as appropriate).
+
+Each bug report will be assigned to a developer who will determine what needs to
+be done to correct the problem. You will receive an update each time action is
+taken on the bug.
+
+
+.. seealso::
+
+ `How to Report Bugs Effectively <http://www-mice.cs.ucl.ac.uk/multimedia/software/documentation/ReportingBugs.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://www.mozilla.org/quality/bug-writing-guidelines.html>`_
+ Information about writing a good bug report. Some of this is specific to the
+ Mozilla project, but describes general good practices.
+
--- /dev/null
+.. 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.
+
+
+.. _object:
+
+Object Protocol
+===============
+
+
+.. cfunction:: int PyObject_Print(PyObject *o, FILE *fp, int flags)
+
+ Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags argument
+ is used to enable certain printing options. The only option currently supported
+ is :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
+ instead of the :func:`repr`.
+
+
+.. cfunction:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
+
+ Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
+ is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
+ always succeeds.
+
+
+.. cfunction:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
+
+ Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
+ value on success, or *NULL* on failure. This is the equivalent of the Python
+ expression ``o.attr_name``.
+
+
+.. cfunction:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
+
+ Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
+ is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
+ always succeeds.
+
+
+.. cfunction:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
+
+ Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
+ value on success, or *NULL* on failure. This is the equivalent of the Python
+ expression ``o.attr_name``.
+
+
+.. cfunction:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
+
+ Set the value of the attribute named *attr_name*, for object *o*, to the value
+ *v*. Returns ``-1`` on failure. This is the equivalent of the Python statement
+ ``o.attr_name = v``.
+
+
+.. cfunction:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
+
+ Set the value of the attribute named *attr_name*, for object *o*, to the value
+ *v*. Returns ``-1`` on failure. This is the equivalent of the Python statement
+ ``o.attr_name = v``.
+
+
+.. cfunction:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
+
+ Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
+ This is the equivalent of the Python statement: ``del o.attr_name``.
+
+
+.. cfunction:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
+
+ Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
+ This is the equivalent of the Python statement ``del o.attr_name``.
+
+
+.. cfunction:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
+
+ Compare the values of *o1* and *o2* using the operation specified by *opid*,
+ which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
+ :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
+ ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of
+ the Python expression ``o1 op o2``, where ``op`` is the operator corresponding
+ to *opid*. Returns the value of the comparison on success, or *NULL* on failure.
+
+
+.. cfunction:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
+
+ Compare the values of *o1* and *o2* using the operation specified by *opid*,
+ which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
+ :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
+ ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error,
+ ``0`` if the result is false, ``1`` otherwise. This is the equivalent of the
+ Python expression ``o1 op o2``, where ``op`` is the operator corresponding to
+ *opid*.
+
+
+.. cfunction:: int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result)
+
+ .. index:: builtin: cmp
+
+ Compare the values of *o1* and *o2* using a routine provided by *o1*, if one
+ exists, otherwise with a routine provided by *o2*. The result of the comparison
+ is returned in *result*. Returns ``-1`` on failure. This is the equivalent of
+ the Python statement ``result = cmp(o1, o2)``.
+
+
+.. cfunction:: int PyObject_Compare(PyObject *o1, PyObject *o2)
+
+ .. index:: builtin: cmp
+
+ Compare the values of *o1* and *o2* using a routine provided by *o1*, if one
+ exists, otherwise with a routine provided by *o2*. Returns the result of the
+ comparison on success. On error, the value returned is undefined; use
+ :cfunc:`PyErr_Occurred` to detect an error. This is equivalent to the Python
+ expression ``cmp(o1, o2)``.
+
+
+.. cfunction:: PyObject* PyObject_Repr(PyObject *o)
+
+ .. index:: builtin: repr
+
+ Compute a string representation of object *o*. Returns the string
+ representation on success, *NULL* on failure. This is the equivalent of the
+ Python expression ``repr(o)``. Called by the :func:`repr` built-in function and
+ by reverse quotes.
+
+
+.. cfunction:: PyObject* PyObject_Str(PyObject *o)
+
+ .. index:: builtin: str
+
+ Compute a string representation of object *o*. Returns the string
+ representation on success, *NULL* on failure. This is the equivalent of the
+ Python expression ``str(o)``. Called by the :func:`str` built-in function and
+ by the :keyword:`print` statement.
+
+
+.. cfunction:: PyObject* PyObject_Unicode(PyObject *o)
+
+ .. index:: builtin: unicode
+
+ Compute a Unicode string representation of object *o*. Returns the Unicode
+ string representation on success, *NULL* on failure. This is the equivalent of
+ the Python expression ``unicode(o)``. Called by the :func:`unicode` built-in
+ function.
+
+
+.. cfunction:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
+
+ Returns ``1`` if *inst* is an instance of the class *cls* or a subclass of
+ *cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception. If
+ *cls* is a type object rather than a class object, :cfunc:`PyObject_IsInstance`
+ returns ``1`` if *inst* is of type *cls*. If *cls* is a tuple, the check will
+ be done against every entry in *cls*. The result will be ``1`` when at least one
+ of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a
+ class instance and *cls* is neither a type object, nor a class object, nor a
+ tuple, *inst* must have a :attr:`__class__` attribute --- the class relationship
+ of the value of that attribute with *cls* will be used to determine the result
+ of this function.
+
+ .. versionadded:: 2.1
+
+ .. versionchanged:: 2.2
+ Support for a tuple as the second argument added.
+
+Subclass determination is done in a fairly straightforward way, but includes a
+wrinkle that implementors of extensions to the class system may want to be aware
+of. If :class:`A` and :class:`B` are class objects, :class:`B` is a subclass of
+:class:`A` if it inherits from :class:`A` either directly or indirectly. If
+either is not a class object, a more general mechanism is used to determine the
+class relationship of the two objects. When testing if *B* is a subclass of
+*A*, if *A* is *B*, :cfunc:`PyObject_IsSubclass` returns true. If *A* and *B*
+are different objects, *B*'s :attr:`__bases__` attribute is searched in a
+depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute
+is considered sufficient for this determination.
+
+
+.. cfunction:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
+
+ Returns ``1`` if the class *derived* is identical to or derived from the class
+ *cls*, otherwise returns ``0``. In case of an error, returns ``-1``. If *cls*
+ is a tuple, the check will be done against every entry in *cls*. The result will
+ be ``1`` when at least one of the checks returns ``1``, otherwise it will be
+ ``0``. If either *derived* or *cls* is not an actual class object (or tuple),
+ this function uses the generic algorithm described above.
+
+ .. versionadded:: 2.1
+
+ .. versionchanged:: 2.3
+ Older versions of Python did not support a tuple as the second argument.
+
+
+.. cfunction:: int PyCallable_Check(PyObject *o)
+
+ Determine if the object *o* is callable. Return ``1`` if the object is callable
+ and ``0`` otherwise. This function always succeeds.
+
+
+.. cfunction:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
+
+ .. index:: builtin: apply
+
+ Call a callable Python object *callable_object*, with arguments given by the
+ tuple *args*, and named arguments given by the dictionary *kw*. If no named
+ arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an
+ empty tuple if no arguments are needed. Returns the result of the call on
+ success, or *NULL* on failure. This is the equivalent of the Python expression
+ ``apply(callable_object, args, kw)`` or ``callable_object(*args, **kw)``.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
+
+ .. index:: builtin: apply
+
+ Call a callable Python object *callable_object*, with arguments given by the
+ tuple *args*. If no arguments are needed, then *args* may be *NULL*. Returns
+ the result of the call on success, or *NULL* on failure. This is the equivalent
+ of the Python expression ``apply(callable_object, args)`` or
+ ``callable_object(*args)``.
+
+
+.. cfunction:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...)
+
+ .. index:: builtin: apply
+
+ Call a callable Python object *callable*, with a variable number of C arguments.
+ The C arguments are described using a :cfunc:`Py_BuildValue` style format
+ string. The format may be *NULL*, indicating that no arguments are provided.
+ Returns the result of the call on success, or *NULL* on failure. This is the
+ equivalent of the Python expression ``apply(callable, args)`` or
+ ``callable(*args)``. Note that if you only pass :ctype:`PyObject \*` args,
+ :cfunc:`PyObject_CallFunctionObjArgs` is a faster alternative.
+
+
+.. cfunction:: PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)
+
+ Call the method named *method* of object *o* with a variable number of C
+ arguments. The C arguments are described by a :cfunc:`Py_BuildValue` format
+ string that should produce a tuple. The format may be *NULL*, indicating that
+ no arguments are provided. Returns the result of the call on success, or *NULL*
+ on failure. This is the equivalent of the Python expression ``o.method(args)``.
+ Note that if you only pass :ctype:`PyObject \*` args,
+ :cfunc:`PyObject_CallMethodObjArgs` is a faster alternative.
+
+
+.. cfunction:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
+
+ Call a callable Python object *callable*, with a variable number of
+ :ctype:`PyObject\*` arguments. The arguments are provided as a variable number
+ of parameters followed by *NULL*. Returns the result of the call on success, or
+ *NULL* on failure.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
+
+ Calls a method of the object *o*, where the name of the method is given as a
+ Python string object in *name*. It is called with a variable number of
+ :ctype:`PyObject\*` arguments. The arguments are provided as a variable number
+ of parameters followed by *NULL*. Returns the result of the call on success, or
+ *NULL* on failure.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: long PyObject_Hash(PyObject *o)
+
+ .. index:: builtin: hash
+
+ Compute and return the hash value of an object *o*. On failure, return ``-1``.
+ This is the equivalent of the Python expression ``hash(o)``.
+
+
+.. cfunction:: int PyObject_IsTrue(PyObject *o)
+
+ Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise.
+ This is equivalent to the Python expression ``not not o``. On failure, return
+ ``-1``.
+
+
+.. cfunction:: int PyObject_Not(PyObject *o)
+
+ Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise.
+ This is equivalent to the Python expression ``not o``. On failure, return
+ ``-1``.
+
+
+.. cfunction:: PyObject* PyObject_Type(PyObject *o)
+
+ .. index:: builtin: type
+
+ When *o* is non-*NULL*, returns a type object corresponding to the object type
+ of object *o*. On failure, raises :exc:`SystemError` and returns *NULL*. This
+ is equivalent to the Python expression ``type(o)``. This function increments the
+ reference count of the return value. There's really no reason to use this
+ function instead of the common expression ``o->ob_type``, which returns a
+ pointer of type :ctype:`PyTypeObject\*`, except when the incremented reference
+ count is needed.
+
+
+.. cfunction:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
+
+ Return true if the object *o* is of type *type* or a subtype of *type*. Both
+ parameters must be non-*NULL*.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: Py_ssize_t PyObject_Length(PyObject *o)
+ Py_ssize_t PyObject_Size(PyObject *o)
+
+ .. index:: builtin: len
+
+ Return the length of object *o*. If the object *o* provides either the sequence
+ and mapping protocols, the sequence length is returned. On error, ``-1`` is
+ returned. This is the equivalent to the Python expression ``len(o)``.
+
+
+.. cfunction:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
+
+ Return element of *o* corresponding to the object *key* or *NULL* on failure.
+ This is the equivalent of the Python expression ``o[key]``.
+
+
+.. cfunction:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
+
+ Map the object *key* to the value *v*. Returns ``-1`` on failure. This is the
+ equivalent of the Python statement ``o[key] = v``.
+
+
+.. cfunction:: int PyObject_DelItem(PyObject *o, PyObject *key)
+
+ Delete the mapping for *key* from *o*. Returns ``-1`` on failure. This is the
+ equivalent of the Python statement ``del o[key]``.
+
+
+.. cfunction:: int PyObject_AsFileDescriptor(PyObject *o)
+
+ Derives a file-descriptor from a Python object. If the object is an integer or
+ long integer, its value is returned. If not, the object's :meth:`fileno` method
+ is called if it exists; the method must return an integer or long integer, which
+ is returned as the file descriptor value. Returns ``-1`` on failure.
+
+
+.. cfunction:: PyObject* PyObject_Dir(PyObject *o)
+
+ This is equivalent to the Python expression ``dir(o)``, returning a (possibly
+ empty) list of strings appropriate for the object argument, or *NULL* if there
+ was an error. If the argument is *NULL*, this is like the Python ``dir()``,
+ returning the names of the current locals; in this case, if no execution frame
+ is active then *NULL* is returned but :cfunc:`PyErr_Occurred` will return false.
+
+
+.. cfunction:: PyObject* PyObject_GetIter(PyObject *o)
+
+ This is equivalent to the Python expression ``iter(o)``. It returns a new
+ iterator for the object argument, or the object itself if the object is already
+ an iterator. Raises :exc:`TypeError` and returns *NULL* if the object cannot be
+ iterated.
+
+
+.. _number:
+
+Number Protocol
+===============
+
+
+.. cfunction:: int PyNumber_Check(PyObject *o)
+
+ Returns ``1`` if the object *o* provides numeric protocols, and false otherwise.
+ This function always succeeds.
+
+
+.. cfunction:: PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)
+
+ Returns the result of adding *o1* and *o2*, or *NULL* on failure. This is the
+ equivalent of the Python expression ``o1 + o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)
+
+ Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. This is
+ the equivalent of the Python expression ``o1 - o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)
+
+ Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. This is
+ the equivalent of the Python expression ``o1 * o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Divide(PyObject *o1, PyObject *o2)
+
+ Returns the result of dividing *o1* by *o2*, or *NULL* on failure. This is the
+ equivalent of the Python expression ``o1 / o2``.
+
+
+.. cfunction:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
+
+ Return the floor of *o1* divided by *o2*, or *NULL* on failure. This is
+ equivalent to the "classic" division of integers.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
+
+ Return a reasonable approximation for the mathematical value of *o1* divided by
+ *o2*, or *NULL* on failure. The return value is "approximate" because binary
+ floating point numbers are approximate; it is not possible to represent all real
+ numbers in base two. This function can return a floating point value when
+ passed two integers.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)
+
+ Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. This is
+ the equivalent of the Python expression ``o1 % o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)
+
+ .. index:: builtin: divmod
+
+ See the built-in function :func:`divmod`. Returns *NULL* on failure. This is
+ the equivalent of the Python expression ``divmod(o1, o2)``.
+
+
+.. cfunction:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)
+
+ .. index:: builtin: pow
+
+ See the built-in function :func:`pow`. Returns *NULL* on failure. This is the
+ equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is optional.
+ If *o3* is to be ignored, pass :cdata:`Py_None` in its place (passing *NULL* for
+ *o3* would cause an illegal memory access).
+
+
+.. cfunction:: PyObject* PyNumber_Negative(PyObject *o)
+
+ Returns the negation of *o* on success, or *NULL* on failure. This is the
+ equivalent of the Python expression ``-o``.
+
+
+.. cfunction:: PyObject* PyNumber_Positive(PyObject *o)
+
+ Returns *o* on success, or *NULL* on failure. This is the equivalent of the
+ Python expression ``+o``.
+
+
+.. cfunction:: PyObject* PyNumber_Absolute(PyObject *o)
+
+ .. index:: builtin: abs
+
+ Returns the absolute value of *o*, or *NULL* on failure. This is the equivalent
+ of the Python expression ``abs(o)``.
+
+
+.. cfunction:: PyObject* PyNumber_Invert(PyObject *o)
+
+ Returns the bitwise negation of *o* on success, or *NULL* on failure. This is
+ the equivalent of the Python expression ``~o``.
+
+
+.. cfunction:: PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)
+
+ Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
+ failure. This is the equivalent of the Python expression ``o1 << o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)
+
+ Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
+ failure. This is the equivalent of the Python expression ``o1 >> o2``.
+
+
+.. cfunction:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2)
+
+ Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure.
+ This is the equivalent of the Python expression ``o1 & o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)
+
+ Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
+ failure. This is the equivalent of the Python expression ``o1 ^ o2``.
+
+
+.. cfunction:: PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)
+
+ Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure.
+ This is the equivalent of the Python expression ``o1 | o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
+
+ Returns the result of adding *o1* and *o2*, or *NULL* on failure. The operation
+ is done *in-place* when *o1* supports it. This is the equivalent of the Python
+ statement ``o1 += o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)
+
+ Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. The
+ operation is done *in-place* when *o1* supports it. This is the equivalent of
+ the Python statement ``o1 -= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)
+
+ Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. The
+ operation is done *in-place* when *o1* supports it. This is the equivalent of
+ the Python statement ``o1 *= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2)
+
+ Returns the result of dividing *o1* by *o2*, or *NULL* on failure. The
+ operation is done *in-place* when *o1* supports it. This is the equivalent of
+ the Python statement ``o1 /= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
+
+ Returns the mathematical floor of dividing *o1* by *o2*, or *NULL* on failure.
+ The operation is done *in-place* when *o1* supports it. This is the equivalent
+ of the Python statement ``o1 //= o2``.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
+
+ Return a reasonable approximation for the mathematical value of *o1* divided by
+ *o2*, or *NULL* on failure. The return value is "approximate" because binary
+ floating point numbers are approximate; it is not possible to represent all real
+ numbers in base two. This function can return a floating point value when
+ passed two integers. The operation is done *in-place* when *o1* supports it.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
+
+ Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. The
+ operation is done *in-place* when *o1* supports it. This is the equivalent of
+ the Python statement ``o1 %= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)
+
+ .. index:: builtin: pow
+
+ See the built-in function :func:`pow`. Returns *NULL* on failure. The operation
+ is done *in-place* when *o1* supports it. This is the equivalent of the Python
+ statement ``o1 **= o2`` when o3 is :cdata:`Py_None`, or an in-place variant of
+ ``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :cdata:`Py_None`
+ in its place (passing *NULL* for *o3* would cause an illegal memory access).
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)
+
+ Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
+ failure. The operation is done *in-place* when *o1* supports it. This is the
+ equivalent of the Python statement ``o1 <<= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)
+
+ Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
+ failure. The operation is done *in-place* when *o1* supports it. This is the
+ equivalent of the Python statement ``o1 >>= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)
+
+ Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure. The
+ operation is done *in-place* when *o1* supports it. This is the equivalent of
+ the Python statement ``o1 &= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)
+
+ Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
+ failure. The operation is done *in-place* when *o1* supports it. This is the
+ equivalent of the Python statement ``o1 ^= o2``.
+
+
+.. cfunction:: PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)
+
+ Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure. The
+ operation is done *in-place* when *o1* supports it. This is the equivalent of
+ the Python statement ``o1 |= o2``.
+
+
+.. cfunction:: int PyNumber_Coerce(PyObject **p1, PyObject **p2)
+
+ .. index:: builtin: coerce
+
+ This function takes the addresses of two variables of type :ctype:`PyObject\*`.
+ If the objects pointed to by ``*p1`` and ``*p2`` have the same type, increment
+ their reference count and return ``0`` (success). If the objects can be
+ converted to a common numeric type, replace ``*p1`` and ``*p2`` by their
+ converted value (with 'new' reference counts), and return ``0``. If no
+ conversion is possible, or if some other error occurs, return ``-1`` (failure)
+ and don't increment the reference counts. The call ``PyNumber_Coerce(&o1,
+ &o2)`` is equivalent to the Python statement ``o1, o2 = coerce(o1, o2)``.
+
+
+.. cfunction:: PyObject* PyNumber_Int(PyObject *o)
+
+ .. index:: builtin: int
+
+ Returns the *o* converted to an integer object on success, or *NULL* on failure.
+ If the argument is outside the integer range a long object will be returned
+ instead. This is the equivalent of the Python expression ``int(o)``.
+
+
+.. cfunction:: PyObject* PyNumber_Long(PyObject *o)
+
+ .. index:: builtin: long
+
+ Returns the *o* converted to a long integer object on success, or *NULL* on
+ failure. This is the equivalent of the Python expression ``long(o)``.
+
+
+.. cfunction:: PyObject* PyNumber_Float(PyObject *o)
+
+ .. index:: builtin: float
+
+ Returns the *o* converted to a float object on success, or *NULL* on failure.
+ This is the equivalent of the Python expression ``float(o)``.
+
+
+.. cfunction:: PyObject* PyNumber_Index(PyObject *o)
+
+ Returns the *o* converted to a Python int or long on success or *NULL* with a
+ TypeError exception raised on failure.
+
+ .. versionadded:: 2.5
+
+
+.. cfunction:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
+
+ Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an
+ integer. If *o* can be converted to a Python int or long but the attempt to
+ convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the
+ *exc* argument is the type of exception that will be raised (usually
+ :exc:`IndexError` or :exc:`OverflowError`). If *exc* is *NULL*, then the
+ exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative
+ integer or *PY_SSIZE_T_MAX* for a positive integer.
+
+ .. versionadded:: 2.5
+
+
+.. cfunction:: int PyIndex_Check(PyObject *o)
+
+ Returns True if *o* is an index integer (has the nb_index slot of the
+ tp_as_number structure filled in).
+
+ .. versionadded:: 2.5
+
+
+.. _sequence:
+
+Sequence Protocol
+=================
+
+
+.. cfunction:: int PySequence_Check(PyObject *o)
+
+ Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
+ This function always succeeds.
+
+
+.. cfunction:: Py_ssize_t PySequence_Size(PyObject *o)
+
+ .. index:: builtin: len
+
+ Returns the number of objects in sequence *o* on success, and ``-1`` on failure.
+ For objects that do not provide sequence protocol, this is equivalent to the
+ Python expression ``len(o)``.
+
+
+.. cfunction:: Py_ssize_t PySequence_Length(PyObject *o)
+
+ Alternate name for :cfunc:`PySequence_Size`.
+
+
+.. cfunction:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)
+
+ Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
+ This is the equivalent of the Python expression ``o1 + o2``.
+
+
+.. cfunction:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)
+
+ Return the result of repeating sequence object *o* *count* times, or *NULL* on
+ failure. This is the equivalent of the Python expression ``o * count``.
+
+
+.. cfunction:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)
+
+ Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
+ The operation is done *in-place* when *o1* supports it. This is the equivalent
+ of the Python expression ``o1 += o2``.
+
+
+.. cfunction:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)
+
+ Return the result of repeating sequence object *o* *count* times, or *NULL* on
+ failure. The operation is done *in-place* when *o* supports it. This is the
+ equivalent of the Python expression ``o *= count``.
+
+
+.. cfunction:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)
+
+ Return the *i*th element of *o*, or *NULL* on failure. This is the equivalent of
+ the Python expression ``o[i]``.
+
+
+.. cfunction:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
+
+ Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on
+ failure. This is the equivalent of the Python expression ``o[i1:i2]``.
+
+
+.. cfunction:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
+
+ Assign object *v* to the *i*th element of *o*. Returns ``-1`` on failure. This
+ is the equivalent of the Python statement ``o[i] = v``. This function *does
+ not* steal a reference to *v*.
+
+
+.. cfunction:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)
+
+ Delete the *i*th element of object *o*. Returns ``-1`` on failure. This is the
+ equivalent of the Python statement ``del o[i]``.
+
+
+.. cfunction:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
+
+ Assign the sequence object *v* to the slice in sequence object *o* from *i1* to
+ *i2*. This is the equivalent of the Python statement ``o[i1:i2] = v``.
+
+
+.. cfunction:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
+
+ Delete the slice in sequence object *o* from *i1* to *i2*. Returns ``-1`` on
+ failure. This is the equivalent of the Python statement ``del o[i1:i2]``.
+
+
+.. cfunction:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)
+
+ Return the number of occurrences of *value* in *o*, that is, return the number
+ of keys for which ``o[key] == value``. On failure, return ``-1``. This is
+ equivalent to the Python expression ``o.count(value)``.
+
+
+.. cfunction:: int PySequence_Contains(PyObject *o, PyObject *value)
+
+ Determine if *o* contains *value*. If an item in *o* is equal to *value*,
+ return ``1``, otherwise return ``0``. On error, return ``-1``. This is
+ equivalent to the Python expression ``value in o``.
+
+
+.. cfunction:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)
+
+ Return the first index *i* for which ``o[i] == value``. On error, return
+ ``-1``. This is equivalent to the Python expression ``o.index(value)``.
+
+
+.. cfunction:: PyObject* PySequence_List(PyObject *o)
+
+ Return a list object with the same contents as the arbitrary sequence *o*. The
+ returned list is guaranteed to be new.
+
+
+.. cfunction:: PyObject* PySequence_Tuple(PyObject *o)
+
+ .. index:: builtin: tuple
+
+ Return a tuple object with the same contents as the arbitrary sequence *o* or
+ *NULL* on failure. If *o* is a tuple, a new reference will be returned,
+ otherwise a tuple will be constructed with the appropriate contents. This is
+ equivalent to the Python expression ``tuple(o)``.
+
+
+.. cfunction:: PyObject* PySequence_Fast(PyObject *o, const char *m)
+
+ Returns the sequence *o* as a tuple, unless it is already a tuple or list, in
+ which case *o* is returned. Use :cfunc:`PySequence_Fast_GET_ITEM` to access the
+ members of the result. Returns *NULL* on failure. If the object is not a
+ sequence, raises :exc:`TypeError` with *m* as the message text.
+
+
+.. cfunction:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)
+
+ Return the *i*th element of *o*, assuming that *o* was returned by
+ :cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
+
+
+.. cfunction:: PyObject** PySequence_Fast_ITEMS(PyObject *o)
+
+ Return the underlying array of PyObject pointers. Assumes that *o* was returned
+ by :cfunc:`PySequence_Fast` and *o* is not *NULL*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)
+
+ Return the *i*th element of *o* or *NULL* on failure. Macro form of
+ :cfunc:`PySequence_GetItem` but without checking that
+ :cfunc:`PySequence_Check(o)` is true and without adjustment for negative
+ indices.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
+
+ Returns the length of *o*, assuming that *o* was returned by
+ :cfunc:`PySequence_Fast` and that *o* is not *NULL*. The size can also be
+ gotten by calling :cfunc:`PySequence_Size` on *o*, but
+ :cfunc:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list
+ or tuple.
+
+
+.. _mapping:
+
+Mapping Protocol
+================
+
+
+.. cfunction:: int PyMapping_Check(PyObject *o)
+
+ Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. This
+ function always succeeds.
+
+
+.. cfunction:: Py_ssize_t PyMapping_Length(PyObject *o)
+
+ .. index:: builtin: len
+
+ Returns the number of keys in object *o* on success, and ``-1`` on failure. For
+ objects that do not provide mapping protocol, this is equivalent to the Python
+ expression ``len(o)``.
+
+
+.. cfunction:: int PyMapping_DelItemString(PyObject *o, char *key)
+
+ Remove the mapping for object *key* from the object *o*. Return ``-1`` on
+ failure. This is equivalent to the Python statement ``del o[key]``.
+
+
+.. cfunction:: int PyMapping_DelItem(PyObject *o, PyObject *key)
+
+ Remove the mapping for object *key* from the object *o*. Return ``-1`` on
+ failure. This is equivalent to the Python statement ``del o[key]``.
+
+
+.. cfunction:: int PyMapping_HasKeyString(PyObject *o, char *key)
+
+ On success, return ``1`` if the mapping object has the key *key* and ``0``
+ otherwise. This is equivalent to the Python expression ``o.has_key(key)``.
+ This function always succeeds.
+
+
+.. cfunction:: int PyMapping_HasKey(PyObject *o, PyObject *key)
+
+ Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. This
+ is equivalent to the Python expression ``o.has_key(key)``. This function always
+ succeeds.
+
+
+.. cfunction:: PyObject* PyMapping_Keys(PyObject *o)
+
+ On success, return a list of the keys in object *o*. On failure, return *NULL*.
+ This is equivalent to the Python expression ``o.keys()``.
+
+
+.. cfunction:: PyObject* PyMapping_Values(PyObject *o)
+
+ On success, return a list of the values in object *o*. On failure, return
+ *NULL*. This is equivalent to the Python expression ``o.values()``.
+
+
+.. cfunction:: PyObject* PyMapping_Items(PyObject *o)
+
+ On success, return a list of the items in object *o*, where each item is a tuple
+ containing a key-value pair. On failure, return *NULL*. This is equivalent to
+ the Python expression ``o.items()``.
+
+
+.. cfunction:: PyObject* PyMapping_GetItemString(PyObject *o, char *key)
+
+ Return element of *o* corresponding to the object *key* or *NULL* on failure.
+ This is the equivalent of the Python expression ``o[key]``.
+
+
+.. cfunction:: int PyMapping_SetItemString(PyObject *o, char *key, PyObject *v)
+
+ Map the object *key* to the value *v* in object *o*. Returns ``-1`` on failure.
+ This is the equivalent of the Python statement ``o[key] = v``.
+
+
+.. _iterator:
+
+Iterator Protocol
+=================
+
+.. versionadded:: 2.2
+
+There are only a couple of functions specifically for working with iterators.
+
+
+.. cfunction:: int PyIter_Check(PyObject *o)
+
+ Return true if the object *o* supports the iterator protocol.
+
+
+.. cfunction:: PyObject* PyIter_Next(PyObject *o)
+
+ Return the next value from the iteration *o*. If the object is an iterator,
+ this retrieves the next value from the iteration, and returns *NULL* with no
+ exception set if there are no remaining items. If the object is not an
+ iterator, :exc:`TypeError` is raised, or if there is an error in retrieving the
+ item, returns *NULL* and passes along the exception.
+
+To write a loop which iterates over an iterator, the C code should look
+something like this::
+
+ PyObject *iterator = PyObject_GetIter(obj);
+ PyObject *item;
+
+ if (iterator == NULL) {
+ /* propagate error */
+ }
+
+ while (item = PyIter_Next(iterator)) {
+ /* do something with item */
+ ...
+ /* release reference when done */
+ Py_DECREF(item);
+ }
+
+ Py_DECREF(iterator);
+
+ if (PyErr_Occurred()) {
+ /* propagate error */
+ }
+ else {
+ /* continue doing useful work */
+ }
+
+
+.. _abstract-buffer:
+
+Buffer Protocol
+===============
+
+
+.. cfunction:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
+
+ Returns a pointer to a read-only memory location useable as character- based
+ input. The *obj* argument must support the single-segment character buffer
+ interface. On success, returns ``0``, sets *buffer* to the memory location and
+ *buffer_len* to the buffer length. Returns ``-1`` and sets a :exc:`TypeError`
+ on error.
+
+ .. versionadded:: 1.6
+
+
+.. cfunction:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
+
+ Returns a pointer to a read-only memory location containing arbitrary data. The
+ *obj* argument must support the single-segment readable buffer interface. On
+ success, returns ``0``, sets *buffer* to the memory location and *buffer_len* to
+ the buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error.
+
+ .. versionadded:: 1.6
+
+
+.. cfunction:: int PyObject_CheckReadBuffer(PyObject *o)
+
+ Returns ``1`` if *o* supports the single-segment readable buffer interface.
+ Otherwise returns ``0``.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
+
+ Returns a pointer to a writeable memory location. The *obj* argument must
+ support the single-segment, character buffer interface. On success, returns
+ ``0``, sets *buffer* to the memory location and *buffer_len* to the buffer
+ length. Returns ``-1`` and sets a :exc:`TypeError` on error.
+
+ .. versionadded:: 1.6
+
--- /dev/null
+.. highlightlang:: c
+
+
+.. _concrete:
+
+**********************
+Concrete Objects Layer
+**********************
+
+The functions in this chapter are specific to certain Python object types.
+Passing them an object of the wrong type is not a good idea; if you receive an
+object from a Python program and you are not sure that it has the right type,
+you must perform a type check first; for example, to check that an object is a
+dictionary, use :cfunc:`PyDict_Check`. The chapter is structured like the
+"family tree" of Python object types.
+
+.. warning::
+
+ While the functions described in this chapter carefully check the type of the
+ objects which are passed in, many of them do not check for *NULL* being passed
+ instead of a valid object. Allowing *NULL* to be passed in can cause memory
+ access violations and immediate termination of the interpreter.
+
+
+.. _fundamental:
+
+Fundamental Objects
+===================
+
+This section describes Python type objects and the singleton object ``None``.
+
+
+.. _typeobjects:
+
+Type Objects
+------------
+
+.. index:: object: type
+
+
+.. ctype:: PyTypeObject
+
+ The C structure of the objects used to describe built-in types.
+
+
+.. cvar:: PyObject* PyType_Type
+
+ .. index:: single: TypeType (in module types)
+
+ This is the type object for type objects; it is the same object as ``type`` and
+ ``types.TypeType`` in the Python layer.
+
+
+.. cfunction:: int PyType_Check(PyObject *o)
+
+ Return true if the object *o* is a type object, including instances of types
+ derived from the standard type object. Return false in all other cases.
+
+
+.. cfunction:: int PyType_CheckExact(PyObject *o)
+
+ Return true if the object *o* is a type object, but not a subtype of the
+ standard type object. Return false in all other cases.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: int PyType_HasFeature(PyObject *o, int feature)
+
+ Return true if the type object *o* sets the feature *feature*. Type features
+ are denoted by single bit flags.
+
+
+.. cfunction:: int PyType_IS_GC(PyObject *o)
+
+ Return true if the type object includes support for the cycle detector; this
+ tests the type flag :const:`Py_TPFLAGS_HAVE_GC`.
+
+ .. versionadded:: 2.0
+
+
+.. cfunction:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
+
+ Return true if *a* is a subtype of *b*.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: int PyType_Ready(PyTypeObject *type)
+
+ Finalize a type object. This should be called on all type objects to finish
+ their initialization. This function is responsible for adding inherited slots
+ from a type's base class. Return ``0`` on success, or return ``-1`` and sets an
+ exception on error.
+
+ .. versionadded:: 2.2
+
+
+.. _noneobject:
+
+The None Object
+---------------
+
+.. index:: object: None
+
+Note that the :ctype:`PyTypeObject` for ``None`` is not directly exposed in the
+Python/C API. Since ``None`` is a singleton, testing for object identity (using
+``==`` in C) is sufficient. There is no :cfunc:`PyNone_Check` function for the
+same reason.
+
+
+.. cvar:: PyObject* Py_None
+
+ The Python ``None`` object, denoting lack of value. This object has no methods.
+ It needs to be treated just like any other object with respect to reference
+ counts.
+
+
+.. cmacro:: Py_RETURN_NONE
+
+ Properly handle returning :cdata:`Py_None` from within a C function.
+
+ .. versionadded:: 2.4
+
+
+.. _numericobjects:
+
+Numeric Objects
+===============
+
+.. index:: object: numeric
+
+
+.. _intobjects:
+
+Plain Integer Objects
+---------------------
+
+.. index:: object: integer
+
+
+.. ctype:: PyIntObject
+
+ This subtype of :ctype:`PyObject` represents a Python integer object.
+
+
+.. cvar:: PyTypeObject PyInt_Type
+
+ .. index:: single: IntType (in modules types)
+
+ This instance of :ctype:`PyTypeObject` represents the Python plain integer type.
+ This is the same object as ``int`` and ``types.IntType``.
+
+
+.. cfunction:: int PyInt_Check(PyObject *o)
+
+ Return true if *o* is of type :cdata:`PyInt_Type` or a subtype of
+ :cdata:`PyInt_Type`.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyInt_CheckExact(PyObject *o)
+
+ Return true if *o* is of type :cdata:`PyInt_Type`, but not a subtype of
+ :cdata:`PyInt_Type`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyInt_FromString(char *str, char **pend, int base)
+
+ Return a new :ctype:`PyIntObject` or :ctype:`PyLongObject` based on the string
+ value in *str*, which is interpreted according to the radix in *base*. If
+ *pend* is non-*NULL*, ``*pend`` will point to the first character in *str* which
+ follows the representation of the number. If *base* is ``0``, the radix will be
+ determined based on the leading characters of *str*: if *str* starts with
+ ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix
+ 8 will be used; otherwise radix 10 will be used. If *base* is not ``0``, it
+ must be between ``2`` and ``36``, inclusive. Leading spaces are ignored. If
+ there are no digits, :exc:`ValueError` will be raised. If the string represents
+ a number too large to be contained within the machine's :ctype:`long int` type
+ and overflow warnings are being suppressed, a :ctype:`PyLongObject` will be
+ returned. If overflow warnings are not being suppressed, *NULL* will be
+ returned in this case.
+
+
+.. cfunction:: PyObject* PyInt_FromLong(long ival)
+
+ Create a new integer object with a value of *ival*.
+
+ The current implementation keeps an array of integer objects for all integers
+ between ``-5`` and ``256``, when you create an int in that range you actually
+ just get back a reference to the existing object. So it should be possible to
+ change the value of ``1``. I suspect the behaviour of Python in this case is
+ undefined. :-)
+
+
+.. cfunction:: PyObject* PyInt_FromSsize_t(Py_ssize_t ival)
+
+ Create a new integer object with a value of *ival*. If the value exceeds
+ ``LONG_MAX``, a long integer object is returned.
+
+ .. versionadded:: 2.5
+
+
+.. cfunction:: long PyInt_AsLong(PyObject *io)
+
+ Will first attempt to cast the object to a :ctype:`PyIntObject`, if it is not
+ already one, and then return its value. If there is an error, ``-1`` is
+ returned, and the caller should check ``PyErr_Occurred()`` to find out whether
+ there was an error, or whether the value just happened to be -1.
+
+
+.. cfunction:: long PyInt_AS_LONG(PyObject *io)
+
+ Return the value of the object *io*. No error checking is performed.
+
+
+.. cfunction:: unsigned long PyInt_AsUnsignedLongMask(PyObject *io)
+
+ Will first attempt to cast the object to a :ctype:`PyIntObject` or
+ :ctype:`PyLongObject`, if it is not already one, and then return its value as
+ unsigned long. This function does not check for overflow.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: unsigned PY_LONG_LONG PyInt_AsUnsignedLongLongMask(PyObject *io)
+
+ Will first attempt to cast the object to a :ctype:`PyIntObject` or
+ :ctype:`PyLongObject`, if it is not already one, and then return its value as
+ unsigned long long, without checking for overflow.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: Py_ssize_t PyInt_AsSsize_t(PyObject *io)
+
+ Will first attempt to cast the object to a :ctype:`PyIntObject` or
+ :ctype:`PyLongObject`, if it is not already one, and then return its value as
+ :ctype:`Py_ssize_t`.
+
+ .. versionadded:: 2.5
+
+
+.. cfunction:: long PyInt_GetMax()
+
+ .. index:: single: LONG_MAX
+
+ Return the system's idea of the largest integer it can handle
+ (:const:`LONG_MAX`, as defined in the system header files).
+
+
+.. _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
+
+
+.. _longobjects:
+
+Long Integer Objects
+--------------------
+
+.. index:: object: long integer
+
+
+.. ctype:: PyLongObject
+
+ This subtype of :ctype:`PyObject` represents a Python long integer object.
+
+
+.. cvar:: PyTypeObject PyLong_Type
+
+ .. index:: single: LongType (in modules types)
+
+ This instance of :ctype:`PyTypeObject` represents the Python long integer type.
+ This is the same object as ``long`` and ``types.LongType``.
+
+
+.. cfunction:: int PyLong_Check(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyLongObject` or a subtype of
+ :ctype:`PyLongObject`.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyLong_CheckExact(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyLongObject`, but not a subtype of
+ :ctype:`PyLongObject`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyLong_FromLong(long v)
+
+ Return a new :ctype:`PyLongObject` object from *v*, or *NULL* on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
+
+ Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long`, or
+ *NULL* on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
+
+ Return a new :ctype:`PyLongObject` object from a C :ctype:`long long`, or *NULL*
+ on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)
+
+ Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long long`,
+ or *NULL* on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromDouble(double v)
+
+ Return a new :ctype:`PyLongObject` object from the integer part of *v*, or
+ *NULL* on failure.
+
+
+.. cfunction:: PyObject* PyLong_FromString(char *str, char **pend, int base)
+
+ Return a new :ctype:`PyLongObject` based on the string value in *str*, which is
+ interpreted according to the radix in *base*. If *pend* is non-*NULL*,
+ ``*pend`` will point to the first character in *str* which follows the
+ representation of the number. If *base* is ``0``, the radix will be determined
+ based on the leading characters of *str*: if *str* starts with ``'0x'`` or
+ ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix 8 will be
+ used; otherwise radix 10 will be used. If *base* is not ``0``, it must be
+ between ``2`` and ``36``, inclusive. Leading spaces are ignored. If there are
+ no digits, :exc:`ValueError` will be raised.
+
+
+.. cfunction:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
+
+ Convert a sequence of Unicode digits to a Python long integer value. The first
+ parameter, *u*, points to the first character of the Unicode string, *length*
+ gives the number of characters, and *base* is the radix for the conversion. The
+ radix must be in the range [2, 36]; if it is out of range, :exc:`ValueError`
+ will be raised.
+
+ .. versionadded:: 1.6
+
+
+.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)
+
+ Create a Python integer or long integer from the pointer *p*. The pointer value
+ can be retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.
+
+ .. versionadded:: 1.5.2
+
+ .. versionchanged:: 2.5
+ If the integer is larger than LONG_MAX, a positive long integer is returned.
+
+
+.. cfunction:: long PyLong_AsLong(PyObject *pylong)
+
+ .. index::
+ single: LONG_MAX
+ single: OverflowError (built-in exception)
+
+ Return a C :ctype:`long` representation of the contents of *pylong*. If
+ *pylong* is greater than :const:`LONG_MAX`, an :exc:`OverflowError` is raised.
+
+
+.. cfunction:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
+
+ .. index::
+ single: ULONG_MAX
+ single: OverflowError (built-in exception)
+
+ Return a C :ctype:`unsigned long` representation of the contents of *pylong*.
+ If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is
+ raised.
+
+
+.. cfunction:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
+
+ Return a C :ctype:`long long` from a Python long integer. If *pylong* cannot be
+ represented as a :ctype:`long long`, an :exc:`OverflowError` will be raised.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
+
+ Return a C :ctype:`unsigned long long` from a Python long integer. If *pylong*
+ cannot be represented as an :ctype:`unsigned long long`, an :exc:`OverflowError`
+ will be raised if the value is positive, or a :exc:`TypeError` will be raised if
+ the value is negative.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
+
+ Return a C :ctype:`unsigned long` from a Python long integer, without checking
+ for overflow.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
+
+ Return a C :ctype:`unsigned long long` from a Python long integer, without
+ checking for overflow.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: double PyLong_AsDouble(PyObject *pylong)
+
+ Return a C :ctype:`double` representation of the contents of *pylong*. If
+ *pylong* cannot be approximately represented as a :ctype:`double`, an
+ :exc:`OverflowError` exception is raised and ``-1.0`` will be returned.
+
+
+.. cfunction:: void* PyLong_AsVoidPtr(PyObject *pylong)
+
+ Convert a Python integer or long integer *pylong* to a C :ctype:`void` pointer.
+ If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This
+ is only assured to produce a usable :ctype:`void` pointer for values created
+ with :cfunc:`PyLong_FromVoidPtr`.
+
+ .. versionadded:: 1.5.2
+
+ .. versionchanged:: 2.5
+ For values outside 0..LONG_MAX, both signed and unsigned integers are acccepted.
+
+
+.. _floatobjects:
+
+Floating Point Objects
+----------------------
+
+.. index:: object: floating point
+
+
+.. ctype:: PyFloatObject
+
+ This subtype of :ctype:`PyObject` represents a Python floating point object.
+
+
+.. cvar:: PyTypeObject PyFloat_Type
+
+ .. index:: single: FloatType (in modules types)
+
+ This instance of :ctype:`PyTypeObject` represents the Python floating point
+ type. This is the same object as ``float`` and ``types.FloatType``.
+
+
+.. cfunction:: int PyFloat_Check(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyFloatObject` or a subtype of
+ :ctype:`PyFloatObject`.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyFloat_CheckExact(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyFloatObject`, but not a subtype of
+ :ctype:`PyFloatObject`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyFloat_FromString(PyObject *str, char **pend)
+
+ Create a :ctype:`PyFloatObject` object based on the string value in *str*, or
+ *NULL* on failure. The *pend* argument is ignored. It remains only for
+ backward compatibility.
+
+
+.. cfunction:: PyObject* PyFloat_FromDouble(double v)
+
+ Create a :ctype:`PyFloatObject` object from *v*, or *NULL* on failure.
+
+
+.. cfunction:: double PyFloat_AsDouble(PyObject *pyfloat)
+
+ Return a C :ctype:`double` representation of the contents of *pyfloat*. If
+ *pyfloat* is not a Python floating point object but has a :meth:`__float__`
+ method, this method will first be called to convert *pyfloat* into a float.
+
+
+.. cfunction:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
+
+ Return a C :ctype:`double` representation of the contents of *pyfloat*, but
+ without error checking.
+
+
+.. _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)
+
+ Return a new :ctype:`PyComplexObject` object from *real* and *imag*.
+
+
+.. cfunction:: double PyComplex_RealAsDouble(PyObject *op)
+
+ Return the real part of *op* as a C :ctype:`double`.
+
+
+.. cfunction:: double PyComplex_ImagAsDouble(PyObject *op)
+
+ Return the imaginary part of *op* as a C :ctype:`double`.
+
+
+.. cfunction:: Py_complex PyComplex_AsCComplex(PyObject *op)
+
+ Return the :ctype:`Py_complex` value of the complex number *op*.
+
+ .. versionchanged:: 2.6
+ If *op* is not a Python complex number object but has a :meth:`__complex__`
+ method, this method will first be called to convert *op* to a Python complex
+ number object.
+
+
+.. _sequenceobjects:
+
+Sequence Objects
+================
+
+.. index:: object: sequence
+
+Generic operations on sequence objects were discussed in the previous chapter;
+this section deals with the specific kinds of sequence objects that are
+intrinsic to the Python language.
+
+
+.. _stringobjects:
+
+String Objects
+--------------
+
+These functions raise :exc:`TypeError` when expecting a string parameter and are
+called with a non-string parameter.
+
+.. index:: object: string
+
+
+.. ctype:: PyStringObject
+
+ This subtype of :ctype:`PyObject` represents a Python string object.
+
+
+.. cvar:: PyTypeObject PyString_Type
+
+ .. index:: single: StringType (in module types)
+
+ This instance of :ctype:`PyTypeObject` represents the Python string type; it is
+ the same object as ``str`` and ``types.StringType`` in the Python layer. .
+
+
+.. cfunction:: int PyString_Check(PyObject *o)
+
+ Return true if the object *o* is a string object or an instance of a subtype of
+ the string type.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyString_CheckExact(PyObject *o)
+
+ Return true if the object *o* is a string object, but not an instance of a
+ subtype of the string type.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyString_FromString(const char *v)
+
+ Return a new string object with a copy of the string *v* as value on success,
+ and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be
+ checked.
+
+
+.. cfunction:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)
+
+ Return a new string object with a copy of the string *v* as value and length
+ *len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of the
+ string are uninitialized.
+
+
+.. cfunction:: PyObject* PyString_FromFormat(const char *format, ...)
+
+ Take a C :cfunc:`printf`\ -style *format* string and a variable number of
+ arguments, calculate the size of the resulting Python string and return a string
+ with the values formatted into it. The variable arguments must be C types and
+ must correspond exactly to the format characters in the *format* string. The
+ following format characters are allowed:
+
+ .. % This should be exactly the same as the table in PyErr_Format.
+ .. % One should just refer to the other.
+ .. % The descriptions for %zd and %zu are wrong, but the truth is complicated
+ .. % because not all compilers support the %z width modifier -- we fake it
+ .. % when necessary via interpolating PY_FORMAT_SIZE_T.
+ .. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
+
+ +-------------------+---------------+--------------------------------+
+ | Format Characters | Type | Comment |
+ +===================+===============+================================+
+ | :attr:`%%` | *n/a* | The literal % character. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%c` | int | A single character, |
+ | | | represented as an C int. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%d` | int | Exactly equivalent to |
+ | | | ``printf("%d")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%u` | unsigned int | Exactly equivalent to |
+ | | | ``printf("%u")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%ld` | long | Exactly equivalent to |
+ | | | ``printf("%ld")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%lu` | unsigned long | Exactly equivalent to |
+ | | | ``printf("%lu")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%zd` | Py_ssize_t | Exactly equivalent to |
+ | | | ``printf("%zd")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%zu` | size_t | Exactly equivalent to |
+ | | | ``printf("%zu")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%i` | int | Exactly equivalent to |
+ | | | ``printf("%i")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%x` | int | Exactly equivalent to |
+ | | | ``printf("%x")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%s` | char\* | A null-terminated C character |
+ | | | array. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%p` | void\* | The hex representation of a C |
+ | | | pointer. Mostly equivalent to |
+ | | | ``printf("%p")`` except that |
+ | | | it is guaranteed to start with |
+ | | | the literal ``0x`` regardless |
+ | | | of what the platform's |
+ | | | ``printf`` yields. |
+ +-------------------+---------------+--------------------------------+
+
+ An unrecognized format character causes all the rest of the format string to be
+ copied as-is to the result string, and any extra arguments discarded.
+
+
+.. cfunction:: PyObject* PyString_FromFormatV(const char *format, va_list vargs)
+
+ Identical to :func:`PyString_FromFormat` except that it takes exactly two
+ arguments.
+
+
+.. cfunction:: Py_ssize_t PyString_Size(PyObject *string)
+
+ Return the length of the string in string object *string*.
+
+
+.. cfunction:: Py_ssize_t PyString_GET_SIZE(PyObject *string)
+
+ Macro form of :cfunc:`PyString_Size` but without error checking.
+
+
+.. cfunction:: char* PyString_AsString(PyObject *string)
+
+ Return a NUL-terminated representation of the contents of *string*. The pointer
+ refers to the internal buffer of *string*, not a copy. The data must not be
+ modified in any way, unless the string was just created using
+ ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If
+ *string* is a Unicode object, this function computes the default encoding of
+ *string* and operates on that. If *string* is not a string object at all,
+ :cfunc:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`.
+
+
+.. cfunction:: char* PyString_AS_STRING(PyObject *string)
+
+ Macro form of :cfunc:`PyString_AsString` but without error checking. Only
+ string objects are supported; no Unicode objects should be passed.
+
+
+.. cfunction:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
+
+ Return a NUL-terminated representation of the contents of the object *obj*
+ through the output variables *buffer* and *length*.
+
+ The function accepts both string and Unicode objects as input. For Unicode
+ objects it returns the default encoded version of the object. If *length* is
+ *NULL*, the resulting buffer may not contain NUL characters; if it does, the
+ function returns ``-1`` and a :exc:`TypeError` is raised.
+
+ The buffer refers to an internal string buffer of *obj*, not a copy. The data
+ must not be modified in any way, unless the string was just created using
+ ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If
+ *string* is a Unicode object, this function computes the default encoding of
+ *string* and operates on that. If *string* is not a string object at all,
+ :cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.
+
+
+.. cfunction:: void PyString_Concat(PyObject **string, PyObject *newpart)
+
+ Create a new string object in *\*string* containing the contents of *newpart*
+ appended to *string*; the caller will own the new reference. The reference to
+ the old value of *string* will be stolen. If the new string cannot be created,
+ the old reference to *string* will still be discarded and the value of
+ *\*string* will be set to *NULL*; the appropriate exception will be set.
+
+
+.. cfunction:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)
+
+ Create a new string object in *\*string* containing the contents of *newpart*
+ appended to *string*. This version decrements the reference count of *newpart*.
+
+
+.. cfunction:: int _PyString_Resize(PyObject **string, Py_ssize_t newsize)
+
+ A way to resize a string object even though it is "immutable". Only use this to
+ build up a brand new string object; don't use this if the string may already be
+ known in other parts of the code. It is an error to call this function if the
+ refcount on the input string object is not one. Pass the address of an existing
+ string object as an lvalue (it may be written into), and the new size desired.
+ On success, *\*string* holds the resized string object and ``0`` is returned;
+ the address in *\*string* may differ from its input value. If the reallocation
+ fails, the original string object at *\*string* is deallocated, *\*string* is
+ set to *NULL*, a memory exception is set, and ``-1`` is returned.
+
+
+.. cfunction:: PyObject* PyString_Format(PyObject *format, PyObject *args)
+
+ Return a new string object from *format* and *args*. Analogous to ``format %
+ args``. The *args* argument must be a tuple.
+
+
+.. cfunction:: void PyString_InternInPlace(PyObject **string)
+
+ Intern the argument *\*string* in place. The argument must be the address of a
+ pointer variable pointing to a Python string object. If there is an existing
+ interned string that is the same as *\*string*, it sets *\*string* to it
+ (decrementing the reference count of the old string object and incrementing the
+ reference count of the interned string object), otherwise it leaves *\*string*
+ alone and interns it (incrementing its reference count). (Clarification: even
+ though there is a lot of talk about reference counts, think of this function as
+ reference-count-neutral; you own the object after the call if and only if you
+ owned it before the call.)
+
+
+.. cfunction:: PyObject* PyString_InternFromString(const char *v)
+
+ A combination of :cfunc:`PyString_FromString` and
+ :cfunc:`PyString_InternInPlace`, returning either a new string object that has
+ been interned, or a new ("owned") reference to an earlier interned string object
+ with the same value.
+
+
+.. cfunction:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
+
+ Create an object by decoding *size* bytes of the encoded buffer *s* using the
+ codec registered for *encoding*. *encoding* and *errors* have the same meaning
+ as the parameters of the same name in the :func:`unicode` built-in function.
+ The codec to be used is looked up using the Python codec registry. Return
+ *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)
+
+ Decode a string object by passing it to the codec registered for *encoding* and
+ return the result as Python object. *encoding* and *errors* have the same
+ meaning as the parameters of the same name in the string :meth:`encode` method.
+ The codec to be used is looked up using the Python codec registry. Return *NULL*
+ if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
+
+ Encode the :ctype:`char` buffer of the given size by passing it to the codec
+ registered for *encoding* and return a Python object. *encoding* and *errors*
+ have the same meaning as the parameters of the same name in the string
+ :meth:`encode` method. The codec to be used is looked up using the Python codec
+ registry. Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
+
+ Encode a string object using the codec registered for *encoding* and return the
+ result as Python object. *encoding* and *errors* have the same meaning as the
+ parameters of the same name in the string :meth:`encode` method. The codec to be
+ used is looked up using the Python codec registry. Return *NULL* if an exception
+ was raised by the codec.
+
+
+.. _unicodeobjects:
+
+Unicode Objects
+---------------
+
+.. sectionauthor:: Marc-Andre Lemburg <mal@lemburg.com>
+
+
+These are the basic Unicode object types used for the Unicode implementation in
+Python:
+
+.. % --- Unicode Type -------------------------------------------------------
+
+
+.. ctype:: Py_UNICODE
+
+ This type represents the storage type which is used by Python internally as
+ basis for holding Unicode ordinals. Python's default builds use a 16-bit type
+ for :ctype:`Py_UNICODE` and store Unicode values internally as UCS2. It is also
+ possible to build a UCS4 version of Python (most recent Linux distributions come
+ with UCS4 builds of Python). These builds then use a 32-bit type for
+ :ctype:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms
+ where :ctype:`wchar_t` is available and compatible with the chosen Python
+ Unicode build variant, :ctype:`Py_UNICODE` is a typedef alias for
+ :ctype:`wchar_t` to enhance native platform compatibility. On all other
+ platforms, :ctype:`Py_UNICODE` is a typedef alias for either :ctype:`unsigned
+ short` (UCS2) or :ctype:`unsigned long` (UCS4).
+
+Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep
+this in mind when writing extensions or interfaces.
+
+
+.. ctype:: PyUnicodeObject
+
+ This subtype of :ctype:`PyObject` represents a Python Unicode object.
+
+
+.. cvar:: PyTypeObject PyUnicode_Type
+
+ This instance of :ctype:`PyTypeObject` represents the Python Unicode type. It
+ is exposed to Python code as ``unicode`` and ``types.UnicodeType``.
+
+The following APIs are really C macros and can be used to do fast checks and to
+access internal read-only data of Unicode objects:
+
+
+.. cfunction:: int PyUnicode_Check(PyObject *o)
+
+ Return true if the object *o* is a Unicode object or an instance of a Unicode
+ subtype.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyUnicode_CheckExact(PyObject *o)
+
+ Return true if the object *o* is a Unicode object, but not an instance of a
+ subtype.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
+
+ Return the size of the object. *o* has to be a :ctype:`PyUnicodeObject` (not
+ checked).
+
+
+.. cfunction:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)
+
+ Return the size of the object's internal buffer in bytes. *o* has to be a
+ :ctype:`PyUnicodeObject` (not checked).
+
+
+.. cfunction:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)
+
+ Return a pointer to the internal :ctype:`Py_UNICODE` buffer of the object. *o*
+ has to be a :ctype:`PyUnicodeObject` (not checked).
+
+
+.. cfunction:: const char* PyUnicode_AS_DATA(PyObject *o)
+
+ Return a pointer to the internal buffer of the object. *o* has to be a
+ :ctype:`PyUnicodeObject` (not checked).
+
+Unicode provides many different character properties. The most often needed ones
+are available through these macros which are mapped to C functions depending on
+the Python configuration.
+
+.. % --- Unicode character properties ---------------------------------------
+
+
+.. cfunction:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)
+
+ Return 1 or 0 depending on whether *ch* is a whitespace character.
+
+
+.. cfunction:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)
+
+ Return 1 or 0 depending on whether *ch* is a lowercase character.
+
+
+.. cfunction:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)
+
+ Return 1 or 0 depending on whether *ch* is an uppercase character.
+
+
+.. cfunction:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)
+
+ Return 1 or 0 depending on whether *ch* is a titlecase character.
+
+
+.. cfunction:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)
+
+ Return 1 or 0 depending on whether *ch* is a linebreak character.
+
+
+.. cfunction:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)
+
+ Return 1 or 0 depending on whether *ch* is a decimal character.
+
+
+.. cfunction:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)
+
+ Return 1 or 0 depending on whether *ch* is a digit character.
+
+
+.. cfunction:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)
+
+ Return 1 or 0 depending on whether *ch* is a numeric character.
+
+
+.. cfunction:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)
+
+ Return 1 or 0 depending on whether *ch* is an alphabetic character.
+
+
+.. cfunction:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)
+
+ Return 1 or 0 depending on whether *ch* is an alphanumeric character.
+
+These APIs can be used for fast direct character conversions:
+
+
+.. cfunction:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)
+
+ Return the character *ch* converted to lower case.
+
+
+.. cfunction:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)
+
+ Return the character *ch* converted to upper case.
+
+
+.. cfunction:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)
+
+ Return the character *ch* converted to title case.
+
+
+.. cfunction:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch)
+
+ Return the character *ch* converted to a decimal positive integer. Return
+ ``-1`` if this is not possible. This macro does not raise exceptions.
+
+
+.. cfunction:: int Py_UNICODE_TODIGIT(Py_UNICODE ch)
+
+ Return the character *ch* converted to a single digit integer. Return ``-1`` if
+ this is not possible. This macro does not raise exceptions.
+
+
+.. cfunction:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch)
+
+ Return the character *ch* converted to a double. Return ``-1.0`` if this is not
+ possible. This macro does not raise exceptions.
+
+To create Unicode objects and access their basic sequence properties, use these
+APIs:
+
+.. % --- Plain Py_UNICODE ---------------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
+
+ Create a Unicode Object from the Py_UNICODE buffer *u* of the given size. *u*
+ may be *NULL* which causes the contents to be undefined. It is the user's
+ responsibility to fill in the needed data. The buffer is copied into the new
+ object. If the buffer is not *NULL*, the return value might be a shared object.
+ Therefore, modification of the resulting Unicode object is only allowed when *u*
+ is *NULL*.
+
+
+.. cfunction:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
+
+ Return a read-only pointer to the Unicode object's internal :ctype:`Py_UNICODE`
+ buffer, *NULL* if *unicode* is not a Unicode object.
+
+
+.. cfunction:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
+
+ Return the length of the Unicode object.
+
+
+.. cfunction:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
+
+ Coerce an encoded object *obj* to an Unicode object and return a reference with
+ incremented refcount.
+
+ String and other char buffer compatible objects are decoded according to the
+ given encoding and using the error handling defined by errors. Both can be
+ *NULL* to have the interface use the default values (see the next section for
+ details).
+
+ All other objects, including Unicode objects, cause a :exc:`TypeError` to be
+ set.
+
+ The API returns *NULL* if there was an error. The caller is responsible for
+ decref'ing the returned objects.
+
+
+.. cfunction:: PyObject* PyUnicode_FromObject(PyObject *obj)
+
+ Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used
+ throughout the interpreter whenever coercion to Unicode is needed.
+
+If the platform supports :ctype:`wchar_t` and provides a header file wchar.h,
+Python can interface directly to this type using the following functions.
+Support is optimized if Python's own :ctype:`Py_UNICODE` type is identical to
+the system's :ctype:`wchar_t`.
+
+.. % --- wchar_t support for platforms which support it ---------------------
+
+
+.. cfunction:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
+
+ Create a Unicode object from the :ctype:`wchar_t` buffer *w* of the given size.
+ Return *NULL* on failure.
+
+
+.. cfunction:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)
+
+ Copy the Unicode object contents into the :ctype:`wchar_t` buffer *w*. At most
+ *size* :ctype:`wchar_t` characters are copied (excluding a possibly trailing
+ 0-termination character). Return the number of :ctype:`wchar_t` characters
+ copied or -1 in case of an error. Note that the resulting :ctype:`wchar_t`
+ string may or may not be 0-terminated. It is the responsibility of the caller
+ to make sure that the :ctype:`wchar_t` string is 0-terminated in case this is
+ required by the application.
+
+
+.. _builtincodecs:
+
+Built-in Codecs
+^^^^^^^^^^^^^^^
+
+Python provides a set of builtin codecs which are written in C for speed. All of
+these codecs are directly usable via the following functions.
+
+Many of the following APIs take two arguments encoding and errors. These
+parameters encoding and errors have the same semantics as the ones of the
+builtin unicode() Unicode object constructor.
+
+Setting encoding to *NULL* causes the default encoding to be used which is
+ASCII. The file system calls should use :cdata:`Py_FileSystemDefaultEncoding`
+as the encoding for file names. This variable should be treated as read-only: On
+some systems, it will be a pointer to a static string, on others, it will change
+at run-time (such as when the application invokes setlocale).
+
+Error handling is set by errors which may also be set to *NULL* meaning to use
+the default handling defined for the codec. Default error handling for all
+builtin codecs is "strict" (:exc:`ValueError` is raised).
+
+The codecs all use a similar interface. Only deviation from the following
+generic ones are documented for simplicity.
+
+These are the generic codec APIs:
+
+.. % --- Generic Codecs -----------------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
+
+ Create a Unicode object by decoding *size* bytes of the encoded string *s*.
+ *encoding* and *errors* have the same meaning as the parameters of the same name
+ in the :func:`unicode` builtin function. The codec to be used is looked up
+ using the Python codec registry. Return *NULL* if an exception was raised by
+ the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)
+
+ Encode the :ctype:`Py_UNICODE` buffer of the given size and return a Python
+ string object. *encoding* and *errors* have the same meaning as the parameters
+ of the same name in the Unicode :meth:`encode` method. The codec to be used is
+ looked up using the Python codec registry. Return *NULL* if an exception was
+ raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
+
+ Encode a Unicode object and return the result as Python string object.
+ *encoding* and *errors* have the same meaning as the parameters of the same name
+ in the Unicode :meth:`encode` method. The codec to be used is looked up using
+ the Python codec registry. Return *NULL* if an exception was raised by the
+ codec.
+
+These are the UTF-8 codec APIs:
+
+.. % --- UTF-8 Codecs -------------------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
+
+ Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string
+ *s*. Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
+
+ If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF8`. If
+ *consumed* is not *NULL*, trailing incomplete UTF-8 byte sequences will not be
+ treated as an error. Those bytes will not be decoded and the number of bytes
+ that have been decoded will be stored in *consumed*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+
+ Encode the :ctype:`Py_UNICODE` buffer of the given size using UTF-8 and return a
+ Python string object. Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
+
+ Encode a Unicode objects using UTF-8 and return the result as Python string
+ object. Error handling is "strict". Return *NULL* if an exception was raised
+ by the codec.
+
+These are the UTF-16 codec APIs:
+
+.. % --- UTF-16 Codecs ------------------------------------------------------ */
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
+
+ Decode *length* bytes from a UTF-16 encoded buffer string and return the
+ corresponding Unicode object. *errors* (if non-*NULL*) defines the error
+ handling. It defaults to "strict".
+
+ If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte
+ order::
+
+ *byteorder == -1: little endian
+ *byteorder == 0: native order
+ *byteorder == 1: big endian
+
+ and then switches if the first two bytes of the input data are a byte order mark
+ (BOM) and the specified byte order is native order. This BOM is not copied into
+ the resulting Unicode string. After completion, *\*byteorder* is set to the
+ current byte order at the.
+
+ If *byteorder* is *NULL*, the codec starts in native order mode.
+
+ Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
+
+ If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeUTF16`. If
+ *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeUTF16Stateful` will not treat
+ trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a
+ split surrogate pair) as an error. Those bytes will not be decoded and the
+ number of bytes that have been decoded will be stored in *consumed*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
+
+ Return a Python string object holding the UTF-16 encoded value of the Unicode
+ data in *s*. If *byteorder* is not ``0``, output is written according to the
+ following byte order::
+
+ byteorder == -1: little endian
+ byteorder == 0: native byte order (writes a BOM mark)
+ byteorder == 1: big endian
+
+ If byteorder is ``0``, the output string will always start with the Unicode BOM
+ mark (U+FEFF). In the other two modes, no BOM mark is prepended.
+
+ If *Py_UNICODE_WIDE* is defined, a single :ctype:`Py_UNICODE` value may get
+ represented as a surrogate pair. If it is not defined, each :ctype:`Py_UNICODE`
+ values is interpreted as an UCS-2 character.
+
+ Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
+
+ Return a Python string using the UTF-16 encoding in native byte order. The
+ string always starts with a BOM mark. Error handling is "strict". Return
+ *NULL* if an exception was raised by the codec.
+
+These are the "Unicode Escape" codec APIs:
+
+.. % --- Unicode-Escape Codecs ----------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
+
+ Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded
+ string *s*. Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
+
+ Encode the :ctype:`Py_UNICODE` buffer of the given size using Unicode-Escape and
+ return a Python string object. Return *NULL* if an exception was raised by the
+ codec.
+
+
+.. cfunction:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
+
+ Encode a Unicode objects using Unicode-Escape and return the result as Python
+ string object. Error handling is "strict". Return *NULL* if an exception was
+ raised by the codec.
+
+These are the "Raw Unicode Escape" codec APIs:
+
+.. % --- Raw-Unicode-Escape Codecs ------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
+
+ Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape
+ encoded string *s*. Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+
+ Encode the :ctype:`Py_UNICODE` buffer of the given size using Raw-Unicode-Escape
+ and return a Python string object. Return *NULL* if an exception was raised by
+ the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
+
+ Encode a Unicode objects using Raw-Unicode-Escape and return the result as
+ Python string object. Error handling is "strict". Return *NULL* if an exception
+ was raised by the codec.
+
+These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 Unicode
+ordinals and only these are accepted by the codecs during encoding.
+
+.. % --- Latin-1 Codecs -----------------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
+
+ Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string
+ *s*. Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+
+ Encode the :ctype:`Py_UNICODE` buffer of the given size using Latin-1 and return
+ a Python string object. Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
+
+ Encode a Unicode objects using Latin-1 and return the result as Python string
+ object. Error handling is "strict". Return *NULL* if an exception was raised
+ by the codec.
+
+These are the ASCII codec APIs. Only 7-bit ASCII data is accepted. All other
+codes generate errors.
+
+.. % --- ASCII Codecs -------------------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
+
+ Create a Unicode object by decoding *size* bytes of the ASCII encoded string
+ *s*. Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+
+ Encode the :ctype:`Py_UNICODE` buffer of the given size using ASCII and return a
+ Python string object. Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
+
+ Encode a Unicode objects using ASCII and return the result as Python string
+ object. Error handling is "strict". Return *NULL* if an exception was raised
+ by the codec.
+
+These are the mapping codec APIs:
+
+.. % --- Character Map Codecs -----------------------------------------------
+
+This codec is special in that it can be used to implement many different codecs
+(and this is in fact what was done to obtain most of the standard codecs
+included in the :mod:`encodings` package). The codec uses mapping to encode and
+decode characters.
+
+Decoding mappings must map single string characters to single Unicode
+characters, integers (which are then interpreted as Unicode ordinals) or None
+(meaning "undefined mapping" and causing an error).
+
+Encoding mappings must map single Unicode characters to single string
+characters, integers (which are then interpreted as Latin-1 ordinals) or None
+(meaning "undefined mapping" and causing an error).
+
+The mapping objects provided must only support the __getitem__ mapping
+interface.
+
+If a character lookup fails with a LookupError, the character is copied as-is
+meaning that its ordinal value will be interpreted as Unicode or Latin-1 ordinal
+resp. Because of this, mappings only need to contain those mappings which map
+characters to different code points.
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)
+
+ Create a Unicode object by decoding *size* bytes of the encoded string *s* using
+ the given *mapping* object. Return *NULL* if an exception was raised by the
+ codec. If *mapping* is *NULL* latin-1 decoding will be done. Else it can be a
+ dictionary mapping byte or a unicode string, which is treated as a lookup table.
+ Byte values greater that the length of the string and U+FFFE "characters" are
+ treated as "undefined mapping".
+
+ .. versionchanged:: 2.4
+ Allowed unicode string as mapping argument.
+
+
+.. cfunction:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)
+
+ Encode the :ctype:`Py_UNICODE` buffer of the given size using the given
+ *mapping* object and return a Python string object. Return *NULL* if an
+ exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
+
+ Encode a Unicode objects using the given *mapping* object and return the result
+ as Python string object. Error handling is "strict". Return *NULL* if an
+ exception was raised by the codec.
+
+The following codec API is special in that maps Unicode to Unicode.
+
+
+.. cfunction:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)
+
+ Translate a :ctype:`Py_UNICODE` buffer of the given length by applying a
+ character mapping *table* to it and return the resulting Unicode object. Return
+ *NULL* when an exception was raised by the codec.
+
+ The *mapping* table must map Unicode ordinal integers to Unicode ordinal
+ integers or None (causing deletion of the character).
+
+ Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries
+ and sequences work well. Unmapped character ordinals (ones which cause a
+ :exc:`LookupError`) are left untouched and are copied as-is.
+
+These are the MBCS codec APIs. They are currently only available on Windows and
+use the Win32 MBCS converters to implement the conversions. Note that MBCS (or
+DBCS) is a class of encodings, not just one. The target encoding is defined by
+the user settings on the machine running the codec.
+
+.. % --- MBCS codecs for Windows --------------------------------------------
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)
+
+ Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*.
+ Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)
+
+ If *consumed* is *NULL*, behave like :cfunc:`PyUnicode_DecodeMBCS`. If
+ *consumed* is not *NULL*, :cfunc:`PyUnicode_DecodeMBCSStateful` will not decode
+ trailing lead byte and the number of bytes that have been decoded will be stored
+ in *consumed*.
+
+ .. versionadded:: 2.5
+
+
+.. cfunction:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
+
+ Encode the :ctype:`Py_UNICODE` buffer of the given size using MBCS and return a
+ Python string object. Return *NULL* if an exception was raised by the codec.
+
+
+.. cfunction:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
+
+ Encode a Unicode objects using MBCS and return the result as Python string
+ object. Error handling is "strict". Return *NULL* if an exception was raised
+ by the codec.
+
+.. % --- Methods & Slots ----------------------------------------------------
+
+
+.. _unicodemethodsandslots:
+
+Methods and Slot Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following APIs are capable of handling Unicode objects and strings on input
+(we refer to them as strings in the descriptions) and return Unicode objects or
+integers as appropriate.
+
+They all return *NULL* or ``-1`` if an exception occurs.
+
+
+.. cfunction:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)
+
+ Concat two strings giving a new Unicode string.
+
+
+.. cfunction:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)
+
+ Split a string giving a list of Unicode strings. If sep is *NULL*, splitting
+ will be done at all whitespace substrings. Otherwise, splits occur at the given
+ separator. At most *maxsplit* splits will be done. If negative, no limit is
+ set. Separators are not included in the resulting list.
+
+
+.. cfunction:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)
+
+ Split a Unicode string at line breaks, returning a list of Unicode strings.
+ CRLF is considered to be one line break. If *keepend* is 0, the Line break
+ characters are not included in the resulting strings.
+
+
+.. cfunction:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)
+
+ Translate a string by applying a character mapping table to it and return the
+ resulting Unicode object.
+
+ The mapping table must map Unicode ordinal integers to Unicode ordinal integers
+ or None (causing deletion of the character).
+
+ Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries
+ and sequences work well. Unmapped character ordinals (ones which cause a
+ :exc:`LookupError`) are left untouched and are copied as-is.
+
+ *errors* has the usual meaning for codecs. It may be *NULL* which indicates to
+ use the default error handling.
+
+
+.. cfunction:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
+
+ Join a sequence of strings using the given separator and return the resulting
+ Unicode string.
+
+
+.. cfunction:: int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
+
+ Return 1 if *substr* matches *str*[*start*:*end*] at the given tail end
+ (*direction* == -1 means to do a prefix match, *direction* == 1 a suffix match),
+ 0 otherwise. Return ``-1`` if an error occurred.
+
+
+.. cfunction:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
+
+ Return the first position of *substr* in *str*[*start*:*end*] using the given
+ *direction* (*direction* == 1 means to do a forward search, *direction* == -1 a
+ backward search). The return value is the index of the first match; a value of
+ ``-1`` indicates that no match was found, and ``-2`` indicates that an error
+ occurred and an exception has been set.
+
+
+.. cfunction:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
+
+ Return the number of non-overlapping occurrences of *substr* in
+ ``str[start:end]``. Return ``-1`` if an error occurred.
+
+
+.. cfunction:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
+
+ Replace at most *maxcount* occurrences of *substr* in *str* with *replstr* and
+ return the resulting Unicode object. *maxcount* == -1 means replace all
+ occurrences.
+
+
+.. cfunction:: int PyUnicode_Compare(PyObject *left, PyObject *right)
+
+ Compare two strings and return -1, 0, 1 for less than, equal, and greater than,
+ respectively.
+
+
+.. cfunction:: int PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)
+
+ Rich compare two unicode strings and return one of the following:
+
+ * ``NULL`` in case an exception was raised
+ * :const:`Py_True` or :const:`Py_False` for successful comparisons
+ * :const:`Py_NotImplemented` in case the type combination is unknown
+
+ Note that :const:`Py_EQ` and :const:`Py_NE` comparisons can cause a
+ :exc:`UnicodeWarning` in case the conversion of the arguments to Unicode fails
+ with a :exc:`UnicodeDecodeError`.
+
+ Possible values for *op* are :const:`Py_GT`, :const:`Py_GE`, :const:`Py_EQ`,
+ :const:`Py_NE`, :const:`Py_LT`, and :const:`Py_LE`.
+
+
+.. cfunction:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args)
+
+ Return a new string object from *format* and *args*; this is analogous to
+ ``format % args``. The *args* argument must be a tuple.
+
+
+.. cfunction:: int PyUnicode_Contains(PyObject *container, PyObject *element)
+
+ Check whether *element* is contained in *container* and return true or false
+ accordingly.
+
+ *element* has to coerce to a one element Unicode string. ``-1`` is returned if
+ there was an error.
+
+
+.. _bufferobjects:
+
+Buffer Objects
+--------------
+
+.. sectionauthor:: Greg Stein <gstein@lyra.org>
+
+
+.. 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.
+
+.. index:: single: PyBufferProcs
+
+More information on the 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.
+
+
+.. 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.
+
+
+.. 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.
+
+
+.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
+
+ Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable.
+
+
+.. 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.
+
+
+.. _tupleobjects:
+
+Tuple Objects
+-------------
+
+.. index:: object: tuple
+
+
+.. ctype:: PyTupleObject
+
+ This subtype of :ctype:`PyObject` represents a Python tuple object.
+
+
+.. cvar:: PyTypeObject PyTuple_Type
+
+ .. index:: single: TupleType (in module types)
+
+ This instance of :ctype:`PyTypeObject` represents the Python tuple type; it is
+ the same object as ``tuple`` and ``types.TupleType`` in the Python layer..
+
+
+.. cfunction:: int PyTuple_Check(PyObject *p)
+
+ Return true if *p* is a tuple object or an instance of a subtype of the tuple
+ type.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyTuple_CheckExact(PyObject *p)
+
+ Return true if *p* is a tuple object, but not an instance of a subtype of the
+ tuple type.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyTuple_New(Py_ssize_t len)
+
+ Return a new tuple object of size *len*, or *NULL* on failure.
+
+
+.. cfunction:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
+
+ Return a new tuple object of size *n*, or *NULL* on failure. The tuple values
+ are initialized to the subsequent *n* C arguments pointing to Python objects.
+ ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyTuple_Size(PyObject *p)
+
+ Take a pointer to a tuple object, and return the size of that tuple.
+
+
+.. cfunction:: int PyTuple_GET_SIZE(PyObject *p)
+
+ Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
+ no error checking is performed.
+
+
+.. cfunction:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
+
+ Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
+ out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
+
+
+.. cfunction:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
+
+ Like :cfunc:`PyTuple_GetItem`, but does no checking of its arguments.
+
+
+.. cfunction:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
+
+ Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
+ as a new tuple.
+
+
+.. cfunction:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
+
+ Insert a reference to object *o* at position *pos* of the tuple pointed to by
+ *p*. Return ``0`` on success.
+
+ .. note::
+
+ This function "steals" a reference to *o*.
+
+
+.. cfunction:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
+
+ Like :cfunc:`PyTuple_SetItem`, but does no error checking, and should *only* be
+ used to fill in brand new tuples.
+
+ .. note::
+
+ This function "steals" a reference to *o*.
+
+
+.. cfunction:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
+
+ Can be used to resize a tuple. *newsize* will be the new length of the tuple.
+ Because tuples are *supposed* to be immutable, this should only be used if there
+ is only one reference to the object. Do *not* use this if the tuple may already
+ be known to some other part of the code. The tuple will always grow or shrink
+ at the end. Think of this as destroying the old tuple and creating a new one,
+ only more efficiently. Returns ``0`` on success. Client code should never
+ assume that the resulting value of ``*p`` will be the same as before calling
+ this function. If the object referenced by ``*p`` is replaced, the original
+ ``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to *NULL*, and
+ raises :exc:`MemoryError` or :exc:`SystemError`.
+
+ .. versionchanged:: 2.2
+ Removed unused third parameter, *last_is_sticky*.
+
+
+.. _listobjects:
+
+List Objects
+------------
+
+.. index:: object: list
+
+
+.. ctype:: PyListObject
+
+ This subtype of :ctype:`PyObject` represents a Python list object.
+
+
+.. cvar:: PyTypeObject PyList_Type
+
+ .. index:: single: ListType (in module types)
+
+ This instance of :ctype:`PyTypeObject` represents the Python list type. This is
+ the same object as ``list`` and ``types.ListType`` in the Python layer.
+
+
+.. cfunction:: int PyList_Check(PyObject *p)
+
+ Return true if *p* is a list object or an instance of a subtype of the list
+ type.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyList_CheckExact(PyObject *p)
+
+ Return true if *p* is a list object, but not an instance of a subtype of the
+ list type.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyList_New(Py_ssize_t len)
+
+ Return a new list of length *len* on success, or *NULL* on failure.
+
+ .. note::
+
+ If *length* is greater than zero, the returned list object's items are set to
+ ``NULL``. Thus you cannot use abstract API functions such as
+ :cfunc:`PySequence_SetItem` or expose the object to Python code before setting
+ all items to a real object with :cfunc:`PyList_SetItem`.
+
+
+.. cfunction:: Py_ssize_t PyList_Size(PyObject *list)
+
+ .. index:: builtin: len
+
+ Return the length of the list object in *list*; this is equivalent to
+ ``len(list)`` on a list object.
+
+
+.. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
+
+ Macro form of :cfunc:`PyList_Size` without error checking.
+
+
+.. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
+
+ Return the object at position *pos* in the list pointed to by *p*. The position
+ must be positive, indexing from the end of the list is not supported. If *pos*
+ is out of bounds, return *NULL* and set an :exc:`IndexError` exception.
+
+
+.. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
+
+ Macro form of :cfunc:`PyList_GetItem` without error checking.
+
+
+.. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
+
+ Set the item at index *index* in list to *item*. Return ``0`` on success or
+ ``-1`` on failure.
+
+ .. note::
+
+ This function "steals" a reference to *item* and discards a reference to an item
+ already in the list at the affected position.
+
+
+.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
+
+ Macro form of :cfunc:`PyList_SetItem` without error checking. This is normally
+ only used to fill in new lists where there is no previous content.
+
+ .. note::
+
+ This function "steals" a reference to *item*, and, unlike
+ :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that it
+ being replaced; any reference in *list* at position *i* will be leaked.
+
+
+.. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
+
+ Insert the item *item* into list *list* in front of index *index*. Return ``0``
+ if successful; return ``-1`` and set an exception if unsuccessful. Analogous to
+ ``list.insert(index, item)``.
+
+
+.. cfunction:: int PyList_Append(PyObject *list, PyObject *item)
+
+ Append the object *item* at the end of list *list*. Return ``0`` if successful;
+ return ``-1`` and set an exception if unsuccessful. Analogous to
+ ``list.append(item)``.
+
+
+.. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
+
+ Return a list of the objects in *list* containing the objects *between* *low*
+ and *high*. Return *NULL* and set an exception if unsuccessful. Analogous to
+ ``list[low:high]``.
+
+
+.. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
+
+ Set the slice of *list* between *low* and *high* to the contents of *itemlist*.
+ Analogous to ``list[low:high] = itemlist``. The *itemlist* may be *NULL*,
+ indicating the assignment of an empty list (slice deletion). Return ``0`` on
+ success, ``-1`` on failure.
+
+
+.. cfunction:: int PyList_Sort(PyObject *list)
+
+ Sort the items of *list* in place. Return ``0`` on success, ``-1`` on failure.
+ This is equivalent to ``list.sort()``.
+
+
+.. cfunction:: int PyList_Reverse(PyObject *list)
+
+ Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on
+ failure. This is the equivalent of ``list.reverse()``.
+
+
+.. cfunction:: PyObject* PyList_AsTuple(PyObject *list)
+
+ .. index:: builtin: tuple
+
+ Return a new tuple object containing the contents of *list*; equivalent to
+ ``tuple(list)``.
+
+
+.. _mapobjects:
+
+Mapping Objects
+===============
+
+.. index:: object: mapping
+
+
+.. _dictobjects:
+
+Dictionary Objects
+------------------
+
+.. index:: object: dictionary
+
+
+.. ctype:: PyDictObject
+
+ This subtype of :ctype:`PyObject` represents a Python dictionary object.
+
+
+.. cvar:: PyTypeObject PyDict_Type
+
+ .. index::
+ single: DictType (in module types)
+ single: DictionaryType (in module types)
+
+ This instance of :ctype:`PyTypeObject` represents the Python dictionary type.
+ This is exposed to Python programs as ``dict`` and ``types.DictType``.
+
+
+.. cfunction:: int PyDict_Check(PyObject *p)
+
+ Return true if *p* is a dict object or an instance of a subtype of the dict
+ type.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyDict_CheckExact(PyObject *p)
+
+ Return true if *p* is a dict object, but not an instance of a subtype of the
+ dict type.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: PyObject* PyDict_New()
+
+ Return a new empty dictionary, or *NULL* on failure.
+
+
+.. cfunction:: PyObject* PyDictProxy_New(PyObject *dict)
+
+ Return a proxy object for a mapping which enforces read-only behavior. This is
+ normally used to create a proxy to prevent modification of the dictionary for
+ non-dynamic class types.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: void PyDict_Clear(PyObject *p)
+
+ Empty an existing dictionary of all key-value pairs.
+
+
+.. cfunction:: int PyDict_Contains(PyObject *p, PyObject *key)
+
+ Determine if dictionary *p* contains *key*. If an item in *p* is matches *key*,
+ return ``1``, otherwise return ``0``. On error, return ``-1``. This is
+ equivalent to the Python expression ``key in p``.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: PyObject* PyDict_Copy(PyObject *p)
+
+ Return a new dictionary that contains the same key-value pairs as *p*.
+
+ .. versionadded:: 1.6
+
+
+.. cfunction:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
+
+ Insert *value* into the dictionary *p* with a key of *key*. *key* must be
+ hashable; if it isn't, :exc:`TypeError` will be raised. Return ``0`` on success
+ or ``-1`` on failure.
+
+
+.. cfunction:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
+
+ .. index:: single: PyString_FromString()
+
+ Insert *value* into the dictionary *p* using *key* as a key. *key* should be a
+ :ctype:`char\*`. The key object is created using ``PyString_FromString(key)``.
+ Return ``0`` on success or ``-1`` on failure.
+
+
+.. cfunction:: int PyDict_DelItem(PyObject *p, PyObject *key)
+
+ Remove the entry in dictionary *p* with key *key*. *key* must be hashable; if it
+ isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1`` on
+ failure.
+
+
+.. cfunction:: int PyDict_DelItemString(PyObject *p, char *key)
+
+ Remove the entry in dictionary *p* which has a key specified by the string
+ *key*. Return ``0`` on success or ``-1`` on failure.
+
+
+.. cfunction:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
+
+ Return the object from dictionary *p* which has a key *key*. Return *NULL* if
+ the key *key* is not present, but *without* setting an exception.
+
+
+.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
+
+ This is the same as :cfunc:`PyDict_GetItem`, but *key* is specified as a
+ :ctype:`char\*`, rather than a :ctype:`PyObject\*`.
+
+
+.. cfunction:: PyObject* PyDict_Items(PyObject *p)
+
+ Return a :ctype:`PyListObject` containing all the items from the dictionary, as
+ in the dictionary method :meth:`dict.items`.
+
+
+.. cfunction:: PyObject* PyDict_Keys(PyObject *p)
+
+ Return a :ctype:`PyListObject` containing all the keys from the dictionary, as
+ in the dictionary method :meth:`dict.keys`.
+
+
+.. cfunction:: PyObject* PyDict_Values(PyObject *p)
+
+ Return a :ctype:`PyListObject` containing all the values from the dictionary
+ *p*, as in the dictionary method :meth:`dict.values`.
+
+
+.. cfunction:: Py_ssize_t PyDict_Size(PyObject *p)
+
+ .. index:: builtin: len
+
+ Return the number of items in the dictionary. This is equivalent to ``len(p)``
+ on a dictionary.
+
+
+.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
+
+ Iterate over all key-value pairs in the dictionary *p*. The :ctype:`int`
+ referred to by *ppos* must be initialized to ``0`` prior to the first call to
+ this function to start the iteration; the function returns true for each pair in
+ the dictionary, and false once all pairs have been reported. The parameters
+ *pkey* and *pvalue* should either point to :ctype:`PyObject\*` variables that
+ will be filled in with each key and value, respectively, or may be *NULL*. Any
+ references returned through them are borrowed. *ppos* should not be altered
+ during iteration. Its value represents offsets within the internal dictionary
+ structure, and since the structure is sparse, the offsets are not consecutive.
+
+ For example::
+
+ PyObject *key, *value;
+ Py_ssize_t pos = 0;
+
+ while (PyDict_Next(self->dict, &pos, &key, &value)) {
+ /* do something interesting with the values... */
+ ...
+ }
+
+ The dictionary *p* should not be mutated during iteration. It is safe (since
+ Python 2.1) to modify the values of the keys as you iterate over the dictionary,
+ but only so long as the set of keys does not change. For example::
+
+ PyObject *key, *value;
+ Py_ssize_t pos = 0;
+
+ while (PyDict_Next(self->dict, &pos, &key, &value)) {
+ int i = PyInt_AS_LONG(value) + 1;
+ PyObject *o = PyInt_FromLong(i);
+ if (o == NULL)
+ return -1;
+ if (PyDict_SetItem(self->dict, key, o) < 0) {
+ Py_DECREF(o);
+ return -1;
+ }
+ Py_DECREF(o);
+ }
+
+
+.. cfunction:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
+
+ Iterate over mapping object *b* adding key-value pairs to dictionary *a*. *b*
+ may be a dictionary, or any object supporting :func:`PyMapping_Keys` and
+ :func:`PyObject_GetItem`. If *override* is true, existing pairs in *a* will be
+ replaced if a matching key is found in *b*, otherwise pairs will only be added
+ if there is not a matching key in *a*. Return ``0`` on success or ``-1`` if an
+ exception was raised.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: int PyDict_Update(PyObject *a, PyObject *b)
+
+ This is the same as ``PyDict_Merge(a, b, 1)`` in C, or ``a.update(b)`` in
+ Python. Return ``0`` on success or ``-1`` if an exception was raised.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
+
+ Update or merge into dictionary *a*, from the key-value pairs in *seq2*. *seq2*
+ must be an iterable object producing iterable objects of length 2, viewed as
+ key-value pairs. In case of duplicate keys, the last wins if *override* is
+ true, else the first wins. Return ``0`` on success or ``-1`` if an exception was
+ raised. Equivalent Python (except for the return value)::
+
+ def PyDict_MergeFromSeq2(a, seq2, override):
+ for key, value in seq2:
+ if override or key not in a:
+ a[key] = value
+
+ .. versionadded:: 2.2
+
+
+.. _otherobjects:
+
+Other Objects
+=============
+
+
+.. _classobjects:
+
+Class 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.
+
+
+.. _fileobjects:
+
+File Objects
+------------
+
+.. index:: object: file
+
+Python's built-in file objects are implemented entirely on the :ctype:`FILE\*`
+support from the C standard library. This is an implementation detail and may
+change in future releases of Python.
+
+
+.. ctype:: PyFileObject
+
+ This subtype of :ctype:`PyObject` represents a Python file object.
+
+
+.. cvar:: PyTypeObject PyFile_Type
+
+ .. index:: single: FileType (in module types)
+
+ This instance of :ctype:`PyTypeObject` represents the Python file type. This is
+ exposed to Python programs as ``file`` and ``types.FileType``.
+
+
+.. cfunction:: int PyFile_Check(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyFileObject` or a subtype of
+ :ctype:`PyFileObject`.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyFile_CheckExact(PyObject *p)
+
+ Return true if its argument is a :ctype:`PyFileObject`, but not a subtype of
+ :ctype:`PyFileObject`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyFile_FromString(char *filename, char *mode)
+
+ .. index:: single: fopen()
+
+ On success, return a new file object that is opened on the file given by
+ *filename*, with a file mode given by *mode*, where *mode* has the same
+ semantics as the standard C routine :cfunc:`fopen`. On failure, return *NULL*.
+
+
+.. cfunction:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))
+
+ Create a new :ctype:`PyFileObject` from the already-open standard C file
+ pointer, *fp*. The function *close* will be called when the file should be
+ closed. Return *NULL* on failure.
+
+
+.. cfunction:: FILE* PyFile_AsFile(PyObject *p)
+
+ Return the file object associated with *p* as a :ctype:`FILE\*`.
+
+
+.. cfunction:: PyObject* PyFile_GetLine(PyObject *p, int n)
+
+ .. index:: single: EOFError (built-in exception)
+
+ Equivalent to ``p.readline([n])``, this function reads one line from the
+ object *p*. *p* may be a file object or any object with a :meth:`readline`
+ method. If *n* is ``0``, exactly one line is read, regardless of the length of
+ the line. If *n* is greater than ``0``, no more than *n* bytes will be read
+ from the file; a partial line can be returned. In both cases, an empty string
+ is returned if the end of the file is reached immediately. If *n* is less than
+ ``0``, however, one line is read regardless of length, but :exc:`EOFError` is
+ raised if the end of the file is reached immediately.
+
+
+.. cfunction:: PyObject* PyFile_Name(PyObject *p)
+
+ Return the name of the file specified by *p* as a string object.
+
+
+.. cfunction:: void PyFile_SetBufSize(PyFileObject *p, int n)
+
+ .. index:: single: setvbuf()
+
+ Available on systems with :cfunc:`setvbuf` only. This should only be called
+ immediately after file object creation.
+
+
+.. cfunction:: int PyFile_Encoding(PyFileObject *p, char *enc)
+
+ Set the file's encoding for Unicode output to *enc*. Return 1 on success and 0
+ on failure.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: int PyFile_SoftSpace(PyObject *p, int newflag)
+
+ .. index:: single: softspace (file attribute)
+
+ This function exists for internal use by the interpreter. Set the
+ :attr:`softspace` attribute of *p* to *newflag* and return the previous value.
+ *p* does not have to be a file object for this function to work properly; any
+ object is supported (thought its only interesting if the :attr:`softspace`
+ attribute can be set). This function clears any errors, and will return ``0``
+ as the previous value if the attribute either does not exist or if there were
+ errors in retrieving it. There is no way to detect errors from this function,
+ but doing so should not be needed.
+
+
+.. cfunction:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
+
+ .. index:: single: Py_PRINT_RAW
+
+ Write object *obj* to file object *p*. The only supported flag for *flags* is
+ :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
+ instead of the :func:`repr`. Return ``0`` on success or ``-1`` on failure; the
+ appropriate exception will be set.
+
+
+.. cfunction:: int PyFile_WriteString(const char *s, PyObject *p)
+
+ Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on
+ failure; the appropriate exception will be set.
+
+
+.. _instanceobjects:
+
+Instance Objects
+----------------
+
+.. 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.
+
+
+.. _function-objects:
+
+Function Objects
+----------------
+
+.. index:: object: function
+
+There are a few functions specific to Python functions.
+
+
+.. ctype:: PyFunctionObject
+
+ The C structure used for functions.
+
+
+.. cvar:: PyTypeObject PyFunction_Type
+
+ .. index:: single: MethodType (in module types)
+
+ This is an instance of :ctype:`PyTypeObject` and represents the Python function
+ type. It is exposed to Python programmers as ``types.FunctionType``.
+
+
+.. cfunction:: int PyFunction_Check(PyObject *o)
+
+ Return true if *o* is a function object (has type :cdata:`PyFunction_Type`).
+ The parameter must not be *NULL*.
+
+
+.. cfunction:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
+
+ Return a new function object associated with the code object *code*. *globals*
+ must be a dictionary with the global variables accessible to the function.
+
+ The function's docstring, name and *__module__* are retrieved from the code
+ object, the argument defaults and closure are set to *NULL*.
+
+
+.. cfunction:: PyObject* PyFunction_GetCode(PyObject *op)
+
+ Return the code object associated with the function object *op*.
+
+
+.. cfunction:: PyObject* PyFunction_GetGlobals(PyObject *op)
+
+ Return the globals dictionary associated with the function object *op*.
+
+
+.. cfunction:: PyObject* PyFunction_GetModule(PyObject *op)
+
+ Return the *__module__* attribute of the function object *op*. This is normally
+ a string containing the module name, but can be set to any other object by
+ Python code.
+
+
+.. cfunction:: PyObject* PyFunction_GetDefaults(PyObject *op)
+
+ Return the argument default values of the function object *op*. This can be a
+ tuple of arguments or *NULL*.
+
+
+.. cfunction:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
+
+ Set the argument default values for the function object *op*. *defaults* must be
+ *Py_None* or a tuple.
+
+ Raises :exc:`SystemError` and returns ``-1`` on failure.
+
+
+.. cfunction:: PyObject* PyFunction_GetClosure(PyObject *op)
+
+ Return the closure associated with the function object *op*. This can be *NULL*
+ or a tuple of cell objects.
+
+
+.. cfunction:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
+
+ Set the closure associated with the function object *op*. *closure* must be
+ *Py_None* or a tuple of cell objects.
+
+ Raises :exc:`SystemError` and returns ``-1`` on failure.
+
+
+.. _method-objects:
+
+Method Objects
+--------------
+
+.. index:: object: method
+
+There are some useful functions that are useful for working with method objects.
+
+
+.. cvar:: PyTypeObject PyMethod_Type
+
+ .. index:: single: MethodType (in module types)
+
+ This instance of :ctype:`PyTypeObject` represents the Python method type. This
+ is exposed to Python programs as ``types.MethodType``.
+
+
+.. cfunction:: int PyMethod_Check(PyObject *o)
+
+ Return true if *o* is a method object (has type :cdata:`PyMethod_Type`). The
+ parameter must not be *NULL*.
+
+
+.. cfunction:: PyObject* PyMethod_New(PyObject *func, PyObject *self, PyObject *class)
+
+ Return a new method object, with *func* being any callable object; this is the
+ function that will be called when the method is called. If this method should
+ be bound to an instance, *self* should be the instance and *class* should be the
+ class of *self*, otherwise *self* should be *NULL* and *class* should be the
+ class which provides the unbound method..
+
+
+.. cfunction:: PyObject* PyMethod_Class(PyObject *meth)
+
+ Return the class object from which the method *meth* was created; if this was
+ created from an instance, it will be the class of the instance.
+
+
+.. cfunction:: PyObject* PyMethod_GET_CLASS(PyObject *meth)
+
+ Macro version of :cfunc:`PyMethod_Class` which avoids error checking.
+
+
+.. cfunction:: PyObject* PyMethod_Function(PyObject *meth)
+
+ Return the function object associated with the method *meth*.
+
+
+.. cfunction:: PyObject* PyMethod_GET_FUNCTION(PyObject *meth)
+
+ Macro version of :cfunc:`PyMethod_Function` which avoids error checking.
+
+
+.. cfunction:: PyObject* PyMethod_Self(PyObject *meth)
+
+ Return the instance associated with the method *meth* if it is bound, otherwise
+ return *NULL*.
+
+
+.. cfunction:: PyObject* PyMethod_GET_SELF(PyObject *meth)
+
+ Macro version of :cfunc:`PyMethod_Self` which avoids error checking.
+
+
+.. _moduleobjects:
+
+Module Objects
+--------------
+
+.. index:: object: module
+
+There are only a few functions special to module objects.
+
+
+.. cvar:: PyTypeObject PyModule_Type
+
+ .. index:: single: ModuleType (in module types)
+
+ This instance of :ctype:`PyTypeObject` represents the Python module type. This
+ is exposed to Python programs as ``types.ModuleType``.
+
+
+.. cfunction:: int PyModule_Check(PyObject *p)
+
+ Return true if *p* is a module object, or a subtype of a module object.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyModule_CheckExact(PyObject *p)
+
+ Return true if *p* is a module object, but not a subtype of
+ :cdata:`PyModule_Type`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyModule_New(const char *name)
+
+ .. index::
+ single: __name__ (module attribute)
+ single: __doc__ (module attribute)
+ single: __file__ (module attribute)
+
+ Return a new module object with the :attr:`__name__` attribute set to *name*.
+ Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in;
+ the caller is responsible for providing a :attr:`__file__` attribute.
+
+
+.. cfunction:: PyObject* PyModule_GetDict(PyObject *module)
+
+ .. index:: single: __dict__ (module attribute)
+
+ Return the dictionary object that implements *module*'s namespace; this object
+ is the same as the :attr:`__dict__` attribute of the module object. This
+ function never fails. It is recommended extensions use other
+ :cfunc:`PyModule_\*` and :cfunc:`PyObject_\*` functions rather than directly
+ manipulate a module's :attr:`__dict__`.
+
+
+.. cfunction:: char* PyModule_GetName(PyObject *module)
+
+ .. index::
+ single: __name__ (module attribute)
+ single: SystemError (built-in exception)
+
+ Return *module*'s :attr:`__name__` value. If the module does not provide one,
+ or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.
+
+
+.. cfunction:: char* PyModule_GetFilename(PyObject *module)
+
+ .. index::
+ single: __file__ (module attribute)
+ single: SystemError (built-in exception)
+
+ Return the name of the file from which *module* was loaded using *module*'s
+ :attr:`__file__` attribute. If this is not defined, or if it is not a string,
+ raise :exc:`SystemError` and return *NULL*.
+
+
+.. cfunction:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
+
+ Add an object to *module* as *name*. This is a convenience function which can
+ be used from the module's initialization function. This steals a reference to
+ *value*. Return ``-1`` on error, ``0`` on success.
+
+ .. versionadded:: 2.0
+
+
+.. cfunction:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
+
+ Add an integer constant to *module* as *name*. This convenience function can be
+ used from the module's initialization function. Return ``-1`` on error, ``0`` on
+ success.
+
+ .. versionadded:: 2.0
+
+
+.. cfunction:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
+
+ Add a string constant to *module* as *name*. This convenience function can be
+ used from the module's initialization function. The string *value* must be
+ null-terminated. Return ``-1`` on error, ``0`` on success.
+
+ .. versionadded:: 2.0
+
+
+.. _iterator-objects:
+
+Iterator Objects
+----------------
+
+Python provides two general-purpose iterator objects. The first, a sequence
+iterator, works with an arbitrary sequence supporting the :meth:`__getitem__`
+method. The second works with a callable object and a sentinel value, calling
+the callable for each item in the sequence, and ending the iteration when the
+sentinel value is returned.
+
+
+.. cvar:: PyTypeObject PySeqIter_Type
+
+ Type object for iterator objects returned by :cfunc:`PySeqIter_New` and the
+ one-argument form of the :func:`iter` built-in function for built-in sequence
+ types.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: int PySeqIter_Check(op)
+
+ Return true if the type of *op* is :cdata:`PySeqIter_Type`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PySeqIter_New(PyObject *seq)
+
+ Return an iterator that works with a general sequence object, *seq*. The
+ iteration ends when the sequence raises :exc:`IndexError` for the subscripting
+ operation.
+
+ .. versionadded:: 2.2
+
+
+.. cvar:: PyTypeObject PyCallIter_Type
+
+ Type object for iterator objects returned by :cfunc:`PyCallIter_New` and the
+ two-argument form of the :func:`iter` built-in function.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: int PyCallIter_Check(op)
+
+ Return true if the type of *op* is :cdata:`PyCallIter_Type`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)
+
+ Return a new iterator. The first parameter, *callable*, can be any Python
+ callable object that can be called with no parameters; each call to it should
+ return the next item in the iteration. When *callable* returns a value equal to
+ *sentinel*, the iteration will be terminated.
+
+ .. versionadded:: 2.2
+
+
+.. _descriptor-objects:
+
+Descriptor Objects
+------------------
+
+"Descriptors" are objects that describe some attribute of an object. They are
+found in the dictionary of type objects.
+
+
+.. cvar:: PyTypeObject PyProperty_Type
+
+ The type object for the built-in descriptor types.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: int PyDescr_IsData(PyObject *descr)
+
+ Return true if the descriptor objects *descr* describes a data attribute, or
+ false if it describes a method. *descr* must be a descriptor object; there is
+ no error checking.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyWrapper_New(PyObject *, PyObject *)
+
+ .. versionadded:: 2.2
+
+
+.. _slice-objects:
+
+Slice Objects
+-------------
+
+
+.. cvar:: PyTypeObject PySlice_Type
+
+ .. index:: single: SliceType (in module types)
+
+ The type object for slice objects. This is the same as ``slice`` and
+ ``types.SliceType``.
+
+
+.. cfunction:: int PySlice_Check(PyObject *ob)
+
+ Return true if *ob* is a slice object; *ob* must not be *NULL*.
+
+
+.. cfunction:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)
+
+ Return a new slice object with the given values. The *start*, *stop*, and
+ *step* parameters are used as the values of the slice object attributes of the
+ same names. Any of the values may be *NULL*, in which case the ``None`` will be
+ used for the corresponding attribute. Return *NULL* if the new object could not
+ be allocated.
+
+
+.. cfunction:: int PySlice_GetIndices(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
+
+ Retrieve the start, stop and step indices from the slice object *slice*,
+ assuming a sequence of length *length*. Treats indices greater than *length* as
+ errors.
+
+ Returns 0 on success and -1 on error with no exception set (unless one of the
+ indices was not :const:`None` and failed to be converted to an integer, in which
+ case -1 is returned with an exception set).
+
+ You probably do not want to use this function. If you want to use slice objects
+ in versions of Python prior to 2.3, you would probably do well to incorporate
+ the source of :cfunc:`PySlice_GetIndicesEx`, suitably renamed, in the source of
+ your extension.
+
+
+.. cfunction:: int PySlice_GetIndicesEx(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)
+
+ Usable replacement for :cfunc:`PySlice_GetIndices`. Retrieve the start, stop,
+ and step indices from the slice object *slice* assuming a sequence of length
+ *length*, and store the length of the slice in *slicelength*. Out of bounds
+ indices are clipped in a manner consistent with the handling of normal slices.
+
+ Returns 0 on success and -1 on error with exception set.
+
+ .. versionadded:: 2.3
+
+
+.. _weakrefobjects:
+
+Weak Reference Objects
+----------------------
+
+Python supports *weak references* as first-class objects. There are two
+specific object types which directly implement weak references. The first is a
+simple reference object, and the second acts as a proxy for the original object
+as much as it can.
+
+
+.. cfunction:: int PyWeakref_Check(ob)
+
+ Return true if *ob* is either a reference or proxy object.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: int PyWeakref_CheckRef(ob)
+
+ Return true if *ob* is a reference object.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: int PyWeakref_CheckProxy(ob)
+
+ Return true if *ob* is a proxy object.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)
+
+ Return a weak reference object for the object *ob*. This will always return
+ a new reference, but is not guaranteed to create a new object; an existing
+ reference object may be returned. The second parameter, *callback*, can be a
+ callable object that receives notification when *ob* is garbage collected; it
+ should accept a single parameter, which will be the weak reference object
+ itself. *callback* may also be ``None`` or *NULL*. If *ob* is not a
+ weakly-referencable object, or if *callback* is not callable, ``None``, or
+ *NULL*, this will return *NULL* and raise :exc:`TypeError`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
+
+ Return a weak reference proxy object for the object *ob*. This will always
+ return a new reference, but is not guaranteed to create a new object; an
+ existing proxy object may be returned. The second parameter, *callback*, can
+ be a callable object that receives notification when *ob* is garbage
+ collected; it should accept a single parameter, which will be the weak
+ reference object itself. *callback* may also be ``None`` or *NULL*. If *ob*
+ is not a weakly-referencable object, or if *callback* is not callable,
+ ``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyWeakref_GetObject(PyObject *ref)
+
+ Return the referenced object from a weak reference, *ref*. If the referent is
+ no longer live, returns ``None``.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)
+
+ Similar to :cfunc:`PyWeakref_GetObject`, but implemented as a macro that does no
+ error checking.
+
+ .. versionadded:: 2.2
+
+
+.. _cobjects:
+
+CObjects
+--------
+
+.. index:: object: CObject
+
+Refer to *Extending and Embedding the Python Interpreter*, section 1.12,
+"Providing a C API for an Extension Module," for more information on using these
+objects.
+
+
+.. 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.
+
+
+.. _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.
+
+
+.. _gen-objects:
+
+Generator Objects
+-----------------
+
+Generator objects are what Python uses to implement generator iterators. They
+are normally created by iterating over a function that yields values, rather
+than explicitly calling :cfunc:`PyGen_New`.
+
+
+.. ctype:: PyGenObject
+
+ The C structure used for generator objects.
+
+
+.. cvar:: PyTypeObject PyGen_Type
+
+ The type object corresponding to generator objects
+
+
+.. cfunction:: int PyGen_Check(ob)
+
+ Return true if *ob* is a generator object; *ob* must not be *NULL*.
+
+
+.. cfunction:: int PyGen_CheckExact(ob)
+
+ Return true if *ob*'s type is *PyGen_Type* is a generator object; *ob* must not
+ be *NULL*.
+
+
+.. cfunction:: PyObject* PyGen_New(PyFrameObject *frame)
+
+ Create and return a new generator object based on the *frame* object. A
+ reference to *frame* is stolen by this function. The parameter must not be
+ *NULL*.
+
+
+.. _datetimeobjects:
+
+DateTime Objects
+----------------
+
+Various date and time objects are supplied by the :mod:`datetime` module.
+Before using any of these functions, the header file :file:`datetime.h` must be
+included in your source (note that this is not included by :file:`Python.h`),
+and the macro :cfunc:`PyDateTime_IMPORT` must be invoked. The macro puts a
+pointer to a C structure into a static variable, ``PyDateTimeAPI``, that is
+used by the following macros.
+
+Type-check macros:
+
+
+.. cfunction:: int PyDate_Check(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_DateType` or a subtype of
+ :cdata:`PyDateTime_DateType`. *ob* must not be *NULL*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDate_CheckExact(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_DateType`. *ob* must not be
+ *NULL*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_Check(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType` or a subtype of
+ :cdata:`PyDateTime_DateTimeType`. *ob* must not be *NULL*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_CheckExact(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType`. *ob* must not
+ be *NULL*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyTime_Check(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_TimeType` or a subtype of
+ :cdata:`PyDateTime_TimeType`. *ob* must not be *NULL*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyTime_CheckExact(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_TimeType`. *ob* must not be
+ *NULL*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDelta_Check(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_DeltaType` or a subtype of
+ :cdata:`PyDateTime_DeltaType`. *ob* must not be *NULL*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDelta_CheckExact(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_DeltaType`. *ob* must not be
+ *NULL*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyTZInfo_Check(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType` or a subtype of
+ :cdata:`PyDateTime_TZInfoType`. *ob* must not be *NULL*.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyTZInfo_CheckExact(PyObject *ob)
+
+ Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType`. *ob* must not be
+ *NULL*.
+
+ .. versionadded:: 2.4
+
+Macros to create objects:
+
+
+.. cfunction:: PyObject* PyDate_FromDate(int year, int month, int day)
+
+ Return a ``datetime.date`` object with the specified year, month and day.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
+
+ Return a ``datetime.datetime`` object with the specified year, month, day, hour,
+ minute, second and microsecond.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
+
+ Return a ``datetime.time`` object with the specified hour, minute, second and
+ microsecond.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
+
+ Return a ``datetime.timedelta`` object representing the given number of days,
+ seconds and microseconds. Normalization is performed so that the resulting
+ number of microseconds and seconds lie in the ranges documented for
+ ``datetime.timedelta`` objects.
+
+ .. versionadded:: 2.4
+
+Macros to extract fields from date objects. The argument must be an instance of
+:cdata:`PyDateTime_Date`, including subclasses (such as
+:cdata:`PyDateTime_DateTime`). The argument must not be *NULL*, and the type is
+not checked:
+
+
+.. cfunction:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
+
+ Return the year, as a positive int.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
+
+ Return the month, as an int from 1 through 12.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
+
+ Return the day, as an int from 1 through 31.
+
+ .. versionadded:: 2.4
+
+Macros to extract fields from datetime objects. The argument must be an
+instance of :cdata:`PyDateTime_DateTime`, including subclasses. The argument
+must not be *NULL*, and the type is not checked:
+
+
+.. cfunction:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
+
+ Return the hour, as an int from 0 through 23.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
+
+ Return the minute, as an int from 0 through 59.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
+
+ Return the second, as an int from 0 through 59.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
+
+ Return the microsecond, as an int from 0 through 999999.
+
+ .. versionadded:: 2.4
+
+Macros to extract fields from time objects. The argument must be an instance of
+:cdata:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*,
+and the type is not checked:
+
+
+.. cfunction:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
+
+ Return the hour, as an int from 0 through 23.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
+
+ Return the minute, as an int from 0 through 59.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
+
+ Return the second, as an int from 0 through 59.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
+
+ Return the microsecond, as an int from 0 through 999999.
+
+ .. versionadded:: 2.4
+
+Macros for the convenience of modules implementing the DB API:
+
+
+.. cfunction:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
+
+ Create and return a new ``datetime.datetime`` object given an argument tuple
+ suitable for passing to ``datetime.datetime.fromtimestamp()``.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: PyObject* PyDate_FromTimestamp(PyObject *args)
+
+ Create and return a new ``datetime.date`` object given an argument tuple
+ suitable for passing to ``datetime.date.fromtimestamp()``.
+
+ .. versionadded:: 2.4
+
+
+.. _setobjects:
+
+Set Objects
+-----------
+
+.. sectionauthor:: Raymond D. Hettinger <python@rcn.com>
+
+
+.. index::
+ object: set
+ object: frozenset
+
+.. versionadded:: 2.5
+
+This section details the public API for :class:`set` and :class:`frozenset`
+objects. Any functionality not listed below is best accessed using the either
+the abstract object protocol (including :cfunc:`PyObject_CallMethod`,
+:cfunc:`PyObject_RichCompareBool`, :cfunc:`PyObject_Hash`,
+:cfunc:`PyObject_Repr`, :cfunc:`PyObject_IsTrue`, :cfunc:`PyObject_Print`, and
+:cfunc:`PyObject_GetIter`) or the abstract number protocol (including
+:cfunc:`PyNumber_And`, :cfunc:`PyNumber_Subtract`, :cfunc:`PyNumber_Or`,
+:cfunc:`PyNumber_Xor`, :cfunc:`PyNumber_InPlaceAnd`,
+:cfunc:`PyNumber_InPlaceSubtract`, :cfunc:`PyNumber_InPlaceOr`, and
+:cfunc:`PyNumber_InPlaceXor`).
+
+
+.. ctype:: PySetObject
+
+ This subtype of :ctype:`PyObject` is used to hold the internal data for both
+ :class:`set` and :class:`frozenset` objects. It is like a :ctype:`PyDictObject`
+ in that it is a fixed size for small sets (much like tuple storage) and will
+ point to a separate, variable sized block of memory for medium and large sized
+ sets (much like list storage). None of the fields of this structure should be
+ considered public and are subject to change. All access should be done through
+ the documented API rather than by manipulating the values in the structure.
+
+
+.. cvar:: PyTypeObject PySet_Type
+
+ This is an instance of :ctype:`PyTypeObject` representing the Python
+ :class:`set` type.
+
+
+.. cvar:: PyTypeObject PyFrozenSet_Type
+
+ This is an instance of :ctype:`PyTypeObject` representing the Python
+ :class:`frozenset` type.
+
+The following type check macros work on pointers to any Python object. Likewise,
+the constructor functions work with any iterable Python object.
+
+
+.. cfunction:: int PyAnySet_Check(PyObject *p)
+
+ Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
+ instance of a subtype.
+
+
+.. cfunction:: int PyAnySet_CheckExact(PyObject *p)
+
+ Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
+ not an instance of a subtype.
+
+
+.. cfunction:: int PyFrozenSet_CheckExact(PyObject *p)
+
+ Return true if *p* is a :class:`frozenset` object but not an instance of a
+ subtype.
+
+
+.. cfunction:: PyObject* PySet_New(PyObject *iterable)
+
+ Return a new :class:`set` containing objects returned by the *iterable*. The
+ *iterable* may be *NULL* to create a new empty set. Return the new set on
+ success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is not
+ actually iterable. The constructor is also useful for copying a set
+ (``c=set(s)``).
+
+
+.. cfunction:: PyObject* PyFrozenSet_New(PyObject *iterable)
+
+ Return a new :class:`frozenset` containing objects returned by the *iterable*.
+ The *iterable* may be *NULL* to create a new empty frozenset. Return the new
+ set on success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is
+ not actually iterable.
+
+The following functions and macros are available for instances of :class:`set`
+or :class:`frozenset` or instances of their subtypes.
+
+
+.. cfunction:: int PySet_Size(PyObject *anyset)
+
+ .. index:: builtin: len
+
+ Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
+ ``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a
+ :class:`set`, :class:`frozenset`, or an instance of a subtype.
+
+
+.. cfunction:: int PySet_GET_SIZE(PyObject *anyset)
+
+ Macro form of :cfunc:`PySet_Size` without error checking.
+
+
+.. cfunction:: int PySet_Contains(PyObject *anyset, PyObject *key)
+
+ Return 1 if found, 0 if not found, and -1 if an error is encountered. Unlike
+ the Python :meth:`__contains__` method, this function does not automatically
+ convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if
+ the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
+ :class:`set`, :class:`frozenset`, or an instance of a subtype.
+
+The following functions are available for instances of :class:`set` or its
+subtypes but not for instances of :class:`frozenset` or its subtypes.
+
+
+.. cfunction:: int PySet_Add(PyObject *set, PyObject *key)
+
+ Add *key* to a :class:`set` instance. Does not apply to :class:`frozenset`
+ instances. Return 0 on success or -1 on failure. Raise a :exc:`TypeError` if
+ the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow.
+ Raise a :exc:`SystemError` if *set* is an not an instance of :class:`set` or its
+ subtype.
+
+
+.. cfunction:: int PySet_Discard(PyObject *set, PyObject *key)
+
+ Return 1 if found and removed, 0 if not found (no action taken), and -1 if an
+ error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a
+ :exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`discard`
+ method, this function does not automatically convert unhashable sets into
+ temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an not an
+ instance of :class:`set` or its subtype.
+
+
+.. cfunction:: PyObject* PySet_Pop(PyObject *set)
+
+ Return a new reference to an arbitrary object in the *set*, and removes the
+ object from the *set*. Return *NULL* on failure. Raise :exc:`KeyError` if the
+ set is empty. Raise a :exc:`SystemError` if *set* is an not an instance of
+ :class:`set` or its subtype.
+
+
+.. cfunction:: int PySet_Clear(PyObject *set)
+
+ Empty an existing set of all elements.
+
--- /dev/null
+.. highlightlang:: c
+
+
+.. _exceptionhandling:
+
+******************
+Exception Handling
+******************
+
+The functions described in this chapter will let you handle and raise Python
+exceptions. It is important to understand some of the basics of Python
+exception handling. It works somewhat like the Unix :cdata:`errno` variable:
+there is a global indicator (per thread) of the last error that occurred. Most
+functions don't clear this on success, but will set it to indicate the cause of
+the error on failure. Most functions also return an error indicator, usually
+*NULL* if they are supposed to return a pointer, or ``-1`` if they return an
+integer (exception: the :cfunc:`PyArg_\*` functions return ``1`` for success and
+``0`` for failure).
+
+When a function must fail because some function it called failed, it generally
+doesn't set the error indicator; the function it called already set it. It is
+responsible for either handling the error and clearing the exception or
+returning after cleaning up any resources it holds (such as object references or
+memory allocations); it should *not* continue normally if it is not prepared to
+handle the error. If returning due to an error, it is important to indicate to
+the caller that an error has been set. If the error is not handled or carefully
+propagated, additional calls into the Python/C API may not behave as intended
+and may fail in mysterious ways.
+
+.. index::
+ single: exc_type (in module sys)
+ single: exc_value (in module sys)
+ single: exc_traceback (in module sys)
+
+The error indicator consists of three Python objects corresponding to the
+Python variables ``sys.exc_type``, ``sys.exc_value`` and ``sys.exc_traceback``.
+API functions exist to interact with the error indicator in various ways. There
+is a separate error indicator for each thread.
+
+.. % XXX Order of these should be more thoughtful.
+.. % Either alphabetical or some kind of structure.
+
+
+.. cfunction:: void PyErr_Print()
+
+ Print a standard traceback to ``sys.stderr`` and clear the error indicator.
+ Call this function only when the error indicator is set. (Otherwise it will
+ cause a fatal error!)
+
+
+.. cfunction:: PyObject* PyErr_Occurred()
+
+ Test whether the error indicator is set. If set, return the exception *type*
+ (the first argument to the last call to one of the :cfunc:`PyErr_Set\*`
+ functions or to :cfunc:`PyErr_Restore`). If not set, return *NULL*. You do not
+ own a reference to the return value, so you do not need to :cfunc:`Py_DECREF`
+ it.
+
+ .. note::
+
+ Do not compare the return value to a specific exception; use
+ :cfunc:`PyErr_ExceptionMatches` instead, shown below. (The comparison could
+ easily fail since the exception may be an instance instead of a class, in the
+ case of a class exception, or it may the a subclass of the expected exception.)
+
+
+.. cfunction:: int PyErr_ExceptionMatches(PyObject *exc)
+
+ Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This
+ should only be called when an exception is actually set; a memory access
+ violation will occur if no exception has been raised.
+
+
+.. cfunction:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
+
+ Return true if the *given* exception matches the exception in *exc*. If *exc*
+ is a class object, this also returns true when *given* is an instance of a
+ subclass. If *exc* is a tuple, all exceptions in the tuple (and recursively in
+ subtuples) are searched for a match. If *given* is *NULL*, a memory access
+ violation will occur.
+
+
+.. cfunction:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
+
+ Under certain circumstances, the values returned by :cfunc:`PyErr_Fetch` below
+ can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
+ not an instance of the same class. This function can be used to instantiate
+ the class in that case. If the values are already normalized, nothing happens.
+ The delayed normalization is implemented to improve performance.
+
+
+.. cfunction:: void PyErr_Clear()
+
+ Clear the error indicator. If the error indicator is not set, there is no
+ effect.
+
+
+.. cfunction:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
+
+ Retrieve the error indicator into three variables whose addresses are passed.
+ If the error indicator is not set, set all three variables to *NULL*. If it is
+ set, it will be cleared and you own a reference to each object retrieved. The
+ value and traceback object may be *NULL* even when the type object is not.
+
+ .. note::
+
+ This function is normally only used by code that needs to handle exceptions or
+ by code that needs to save and restore the error indicator temporarily.
+
+
+.. cfunction:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
+
+ Set the error indicator from the three objects. If the error indicator is
+ already set, it is cleared first. If the objects are *NULL*, the error
+ indicator is cleared. Do not pass a *NULL* type and non-*NULL* value or
+ traceback. The exception type should be a class. Do not pass an invalid
+ exception type or value. (Violating these rules will cause subtle problems
+ later.) This call takes away a reference to each object: you must own a
+ reference to each object before the call and after the call you no longer own
+ these references. (If you don't understand this, don't use this function. I
+ warned you.)
+
+ .. note::
+
+ This function is normally only used by code that needs to save and restore the
+ error indicator temporarily; use :cfunc:`PyErr_Fetch` to save the current
+ exception state.
+
+
+.. cfunction:: void PyErr_SetString(PyObject *type, const char *message)
+
+ This is the most common way to set the error indicator. The first argument
+ specifies the exception type; it is normally one of the standard exceptions,
+ e.g. :cdata:`PyExc_RuntimeError`. You need not increment its reference count.
+ The second argument is an error message; it is converted to a string object.
+
+
+.. cfunction:: void PyErr_SetObject(PyObject *type, PyObject *value)
+
+ This function is similar to :cfunc:`PyErr_SetString` but lets you specify an
+ arbitrary Python object for the "value" of the exception.
+
+
+.. cfunction:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
+
+ This function sets the error indicator and returns *NULL*. *exception* should be
+ a Python exception (class, not an instance). *format* should be a string,
+ containing format codes, similar to :cfunc:`printf`. The ``width.precision``
+ before a format code is parsed, but the width part is ignored.
+
+ .. % This should be exactly the same as the table in PyString_FromFormat.
+ .. % One should just refer to the other.
+ .. % The descriptions for %zd and %zu are wrong, but the truth is complicated
+ .. % because not all compilers support the %z width modifier -- we fake it
+ .. % when necessary via interpolating PY_FORMAT_SIZE_T.
+ .. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
+
+ +-------------------+---------------+--------------------------------+
+ | Format Characters | Type | Comment |
+ +===================+===============+================================+
+ | :attr:`%%` | *n/a* | The literal % character. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%c` | int | A single character, |
+ | | | represented as an C int. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%d` | int | Exactly equivalent to |
+ | | | ``printf("%d")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%u` | unsigned int | Exactly equivalent to |
+ | | | ``printf("%u")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%ld` | long | Exactly equivalent to |
+ | | | ``printf("%ld")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%lu` | unsigned long | Exactly equivalent to |
+ | | | ``printf("%lu")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%zd` | Py_ssize_t | Exactly equivalent to |
+ | | | ``printf("%zd")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%zu` | size_t | Exactly equivalent to |
+ | | | ``printf("%zu")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%i` | int | Exactly equivalent to |
+ | | | ``printf("%i")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%x` | int | Exactly equivalent to |
+ | | | ``printf("%x")``. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%s` | char\* | A null-terminated C character |
+ | | | array. |
+ +-------------------+---------------+--------------------------------+
+ | :attr:`%p` | void\* | The hex representation of a C |
+ | | | pointer. Mostly equivalent to |
+ | | | ``printf("%p")`` except that |
+ | | | it is guaranteed to start with |
+ | | | the literal ``0x`` regardless |
+ | | | of what the platform's |
+ | | | ``printf`` yields. |
+ +-------------------+---------------+--------------------------------+
+
+ An unrecognized format character causes all the rest of the format string to be
+ copied as-is to the result string, and any extra arguments discarded.
+
+
+.. cfunction:: void PyErr_SetNone(PyObject *type)
+
+ This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
+
+
+.. cfunction:: int PyErr_BadArgument()
+
+ This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
+ *message* indicates that a built-in operation was invoked with an illegal
+ argument. It is mostly for internal use.
+
+
+.. cfunction:: PyObject* PyErr_NoMemory()
+
+ This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL*
+ so an object allocation function can write ``return PyErr_NoMemory();`` when it
+ runs out of memory.
+
+
+.. cfunction:: PyObject* PyErr_SetFromErrno(PyObject *type)
+
+ .. index:: single: strerror()
+
+ This is a convenience function to raise an exception when a C library function
+ has returned an error and set the C variable :cdata:`errno`. It constructs a
+ tuple object whose first item is the integer :cdata:`errno` value and whose
+ second item is the corresponding error message (gotten from :cfunc:`strerror`),
+ and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
+ :cdata:`errno` value is :const:`EINTR`, indicating an interrupted system call,
+ this calls :cfunc:`PyErr_CheckSignals`, and if that set the error indicator,
+ leaves it set to that. The function always returns *NULL*, so a wrapper
+ function around a system call can write ``return PyErr_SetFromErrno(type);``
+ when the system call returns an error.
+
+
+.. cfunction:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
+
+ Similar to :cfunc:`PyErr_SetFromErrno`, with the additional behavior that if
+ *filename* is not *NULL*, it is passed to the constructor of *type* as a third
+ parameter. In the case of exceptions such as :exc:`IOError` and :exc:`OSError`,
+ this is used to define the :attr:`filename` attribute of the exception instance.
+
+
+.. cfunction:: PyObject* PyErr_SetFromWindowsErr(int ierr)
+
+ This is a convenience function to raise :exc:`WindowsError`. If called with
+ *ierr* of :cdata:`0`, the error code returned by a call to :cfunc:`GetLastError`
+ is used instead. It calls the Win32 function :cfunc:`FormatMessage` to retrieve
+ the Windows description of error code given by *ierr* or :cfunc:`GetLastError`,
+ then it constructs a tuple object whose first item is the *ierr* value and whose
+ second item is the corresponding error message (gotten from
+ :cfunc:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
+ object)``. This function always returns *NULL*. Availability: Windows.
+
+
+.. cfunction:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
+
+ Similar to :cfunc:`PyErr_SetFromWindowsErr`, with an additional parameter
+ specifying the exception type to be raised. Availability: Windows.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
+
+ Similar to :cfunc:`PyErr_SetFromWindowsErr`, with the additional behavior that
+ if *filename* is not *NULL*, it is passed to the constructor of
+ :exc:`WindowsError` as a third parameter. Availability: Windows.
+
+
+.. cfunction:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename)
+
+ Similar to :cfunc:`PyErr_SetFromWindowsErrWithFilename`, with an additional
+ parameter specifying the exception type to be raised. Availability: Windows.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: void PyErr_BadInternalCall()
+
+ This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
+ *message* indicates that an internal operation (e.g. a Python/C API function)
+ was invoked with an illegal argument. It is mostly for internal use.
+
+
+.. cfunction:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)
+
+ Issue a warning message. The *category* argument is a warning category (see
+ below) or *NULL*; the *message* argument is a message string. *stacklevel* is a
+ positive number giving a number of stack frames; the warning will be issued from
+ the currently executing line of code in that stack frame. A *stacklevel* of 1
+ is the function calling :cfunc:`PyErr_WarnEx`, 2 is the function above that,
+ and so forth.
+
+ This function normally prints a warning message to *sys.stderr*; however, it is
+ also possible that the user has specified that warnings are to be turned into
+ errors, and in that case this will raise an exception. It is also possible that
+ the function raises an exception because of a problem with the warning machinery
+ (the implementation imports the :mod:`warnings` module to do the heavy lifting).
+ The return value is ``0`` if no exception is raised, or ``-1`` if an exception
+ is raised. (It is not possible to determine whether a warning message is
+ actually printed, nor what the reason is for the exception; this is
+ intentional.) If an exception is raised, the caller should do its normal
+ exception handling (for example, :cfunc:`Py_DECREF` owned references and return
+ an error value).
+
+ Warning categories must be subclasses of :cdata:`Warning`; the default warning
+ category is :cdata:`RuntimeWarning`. The standard Python warning categories are
+ available as global variables whose names are ``PyExc_`` followed by the Python
+ exception name. These have the type :ctype:`PyObject\*`; they are all class
+ objects. Their names are :cdata:`PyExc_Warning`, :cdata:`PyExc_UserWarning`,
+ :cdata:`PyExc_UnicodeWarning`, :cdata:`PyExc_DeprecationWarning`,
+ :cdata:`PyExc_SyntaxWarning`, :cdata:`PyExc_RuntimeWarning`, and
+ :cdata:`PyExc_FutureWarning`. :cdata:`PyExc_Warning` is a subclass of
+ :cdata:`PyExc_Exception`; the other warning categories are subclasses of
+ :cdata:`PyExc_Warning`.
+
+ For information about warning control, see the documentation for the
+ :mod:`warnings` module and the :option:`-W` option in the command line
+ documentation. There is no C API for warning control.
+
+
+.. cfunction:: int PyErr_Warn(PyObject *category, char *message)
+
+ Issue a warning message. The *category* argument is a warning category (see
+ below) or *NULL*; the *message* argument is a message string. The warning will
+ appear to be issued from the function calling :cfunc:`PyErr_Warn`, equivalent to
+ calling :cfunc:`PyErr_WarnEx` with a *stacklevel* of 1.
+
+ Deprecated; use :cfunc:`PyErr_WarnEx` instead.
+
+
+.. cfunction:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
+
+ Issue a warning message with explicit control over all warning attributes. This
+ is a straightforward wrapper around the Python function
+ :func:`warnings.warn_explicit`, see there for more information. The *module*
+ and *registry* arguments may be set to *NULL* to get the default effect
+ described there.
+
+
+.. cfunction:: int PyErr_CheckSignals()
+
+ .. index::
+ module: signal
+ single: SIGINT
+ single: KeyboardInterrupt (built-in exception)
+
+ This function interacts with Python's signal handling. It checks whether a
+ signal has been sent to the processes and if so, invokes the corresponding
+ signal handler. If the :mod:`signal` module is supported, this can invoke a
+ signal handler written in Python. In all cases, the default effect for
+ :const:`SIGINT` is to raise the :exc:`KeyboardInterrupt` exception. If an
+ exception is raised the error indicator is set and the function returns ``-1``;
+ otherwise the function returns ``0``. The error indicator may or may not be
+ cleared if it was previously set.
+
+
+.. cfunction:: void PyErr_SetInterrupt()
+
+ .. index::
+ single: SIGINT
+ single: KeyboardInterrupt (built-in exception)
+
+ This function simulates the effect of a :const:`SIGINT` signal arriving --- the
+ next time :cfunc:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will
+ be raised. It may be called without holding the interpreter lock.
+
+ .. % XXX This was described as obsolete, but is used in
+ .. % thread.interrupt_main() (used from IDLE), so it's still needed.
+
+
+.. cfunction:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
+
+ This utility function creates and returns a new exception object. The *name*
+ argument must be the name of the new exception, a C string of the form
+ ``module.class``. The *base* and *dict* arguments are normally *NULL*. This
+ creates a class object derived from :exc:`Exception` (accessible in C as
+ :cdata:`PyExc_Exception`).
+
+ The :attr:`__module__` attribute of the new class is set to the first part (up
+ to the last dot) of the *name* argument, and the class name is set to the last
+ part (after the last dot). The *base* argument can be used to specify alternate
+ base classes; it can either be only one class or a tuple of classes. The *dict*
+ argument can be used to specify a dictionary of class variables and methods.
+
+
+.. cfunction:: void PyErr_WriteUnraisable(PyObject *obj)
+
+ This utility function prints a warning message to ``sys.stderr`` when an
+ exception has been set but it is impossible for the interpreter to actually
+ raise the exception. It is used, for example, when an exception occurs in an
+ :meth:`__del__` method.
+
+ The function is called with a single argument *obj* that identifies the context
+ in which the unraisable exception occurred. The repr of *obj* will be printed in
+ the warning message.
+
+
+.. _standardexceptions:
+
+Standard Exceptions
+===================
+
+All standard Python exceptions are available as global variables whose names are
+``PyExc_`` followed by the Python exception name. These have the type
+:ctype:`PyObject\*`; they are all class objects. For completeness, here are all
+the variables:
+
++------------------------------------+----------------------------+----------+
+| C Name | Python Name | Notes |
++====================================+============================+==========+
+| :cdata:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_Exception` | :exc:`Exception` | \(1) |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_StandardError` | :exc:`StandardError` | \(1) |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_LookupError` | :exc:`LookupError` | \(1) |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_AssertionError` | :exc:`AssertionError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_AttributeError` | :exc:`AttributeError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_EOFError` | :exc:`EOFError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_IOError` | :exc:`IOError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_ImportError` | :exc:`ImportError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_IndexError` | :exc:`IndexError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_KeyError` | :exc:`KeyError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_MemoryError` | :exc:`MemoryError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_NameError` | :exc:`NameError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_OSError` | :exc:`OSError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_OverflowError` | :exc:`OverflowError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_SystemError` | :exc:`SystemError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_SystemExit` | :exc:`SystemExit` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_TypeError` | :exc:`TypeError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_ValueError` | :exc:`ValueError` | |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) |
++------------------------------------+----------------------------+----------+
+| :cdata:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
++------------------------------------+----------------------------+----------+
+
+.. index::
+ single: PyExc_BaseException
+ single: PyExc_Exception
+ single: PyExc_StandardError
+ single: PyExc_ArithmeticError
+ single: PyExc_LookupError
+ single: PyExc_AssertionError
+ single: PyExc_AttributeError
+ single: PyExc_EOFError
+ single: PyExc_EnvironmentError
+ single: PyExc_FloatingPointError
+ single: PyExc_IOError
+ single: PyExc_ImportError
+ single: PyExc_IndexError
+ single: PyExc_KeyError
+ single: PyExc_KeyboardInterrupt
+ single: PyExc_MemoryError
+ single: PyExc_NameError
+ single: PyExc_NotImplementedError
+ single: PyExc_OSError
+ single: PyExc_OverflowError
+ single: PyExc_ReferenceError
+ single: PyExc_RuntimeError
+ single: PyExc_SyntaxError
+ single: PyExc_SystemError
+ single: PyExc_SystemExit
+ single: PyExc_TypeError
+ single: PyExc_ValueError
+ single: PyExc_WindowsError
+ single: PyExc_ZeroDivisionError
+
+Notes:
+
+(1)
+ This is a base class for other standard exceptions.
+
+(2)
+ This is the same as :exc:`weakref.ReferenceError`.
+
+(3)
+ Only defined on Windows; protect code that uses this by testing that the
+ preprocessor macro ``MS_WINDOWS`` is defined.
+
+(4)
+ .. versionadded:: 2.5
+
+
+Deprecation of String Exceptions
+================================
+
+.. index:: single: BaseException (built-in exception)
+
+All exceptions built into Python or provided in the standard library are derived
+from :exc:`BaseException`.
+
+String exceptions are still supported in the interpreter to allow existing code
+to run unmodified, but this will also change in a future release.
+
--- /dev/null
+.. _c-api-index:
+
+##################################
+ Python/C API Reference Manual
+##################################
+
+:Release: |version|
+:Date: |today|
+
+This manual documents the API used by C and C++ programmers who want to write
+extension modules or embed Python. It is a companion to :ref:`extending-index`,
+which describes the general principles of extension writing but does not
+document the API functions in detail.
+
+.. warning::
+
+ The current version of this document is somewhat incomplete. However, most of
+ the important functions, types and structures are described.
+
+
+.. toctree::
+ :maxdepth: 2
+
+ intro.rst
+ veryhigh.rst
+ refcounting.rst
+ exceptions.rst
+ utilities.rst
+ abstract.rst
+ concrete.rst
+ init.rst
+ memory.rst
+ newtypes.rst
--- /dev/null
+.. highlightlang:: c
+
+
+.. _initialization:
+
+*****************************************
+Initialization, Finalization, and Threads
+*****************************************
+
+
+.. cfunction:: void Py_Initialize()
+
+ .. index::
+ single: Py_SetProgramName()
+ single: PyEval_InitThreads()
+ single: PyEval_ReleaseLock()
+ single: PyEval_AcquireLock()
+ single: modules (in module sys)
+ single: path (in module sys)
+ module: __builtin__
+ module: __main__
+ module: sys
+ triple: module; search; path
+ single: PySys_SetArgv()
+ single: Py_Finalize()
+
+ Initialize the Python interpreter. In an application embedding Python, this
+ should be called before using any other Python/C API functions; with the
+ exception of :cfunc:`Py_SetProgramName`, :cfunc:`PyEval_InitThreads`,
+ :cfunc:`PyEval_ReleaseLock`, and :cfunc:`PyEval_AcquireLock`. This initializes
+ the table of loaded modules (``sys.modules``), and creates the fundamental
+ modules :mod:`__builtin__`, :mod:`__main__` and :mod:`sys`. It also initializes
+ the module search path (``sys.path``). It does not set ``sys.argv``; use
+ :cfunc:`PySys_SetArgv` for that. This is a no-op when called for a second time
+ (without calling :cfunc:`Py_Finalize` first). There is no return value; it is a
+ fatal error if the initialization fails.
+
+
+.. cfunction:: void Py_InitializeEx(int initsigs)
+
+ This function works like :cfunc:`Py_Initialize` if *initsigs* is 1. If
+ *initsigs* is 0, it skips initialization registration of signal handlers, which
+ might be useful when Python is embedded.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: int Py_IsInitialized()
+
+ Return true (nonzero) when the Python interpreter has been initialized, false
+ (zero) if not. After :cfunc:`Py_Finalize` is called, this returns false until
+ :cfunc:`Py_Initialize` is called again.
+
+
+.. cfunction:: void Py_Finalize()
+
+ Undo all initializations made by :cfunc:`Py_Initialize` and subsequent use of
+ Python/C API functions, and destroy all sub-interpreters (see
+ :cfunc:`Py_NewInterpreter` below) that were created and not yet destroyed since
+ the last call to :cfunc:`Py_Initialize`. Ideally, this frees all memory
+ allocated by the Python interpreter. This is a no-op when called for a second
+ time (without calling :cfunc:`Py_Initialize` again first). There is no return
+ value; errors during finalization are ignored.
+
+ This function is provided for a number of reasons. An embedding application
+ might want to restart Python without having to restart the application itself.
+ An application that has loaded the Python interpreter from a dynamically
+ loadable library (or DLL) might want to free all memory allocated by Python
+ before unloading the DLL. During a hunt for memory leaks in an application a
+ developer might want to free all memory allocated by Python before exiting from
+ the application.
+
+ **Bugs and caveats:** The destruction of modules and objects in modules is done
+ in random order; this may cause destructors (:meth:`__del__` methods) to fail
+ when they depend on other objects (even functions) or modules. Dynamically
+ loaded extension modules loaded by Python are not unloaded. Small amounts of
+ memory allocated by the Python interpreter may not be freed (if you find a leak,
+ please report it). Memory tied up in circular references between objects is not
+ freed. Some memory allocated by extension modules may not be freed. Some
+ extensions may not work properly if their initialization routine is called more
+ than once; this can happen if an application calls :cfunc:`Py_Initialize` and
+ :cfunc:`Py_Finalize` more than once.
+
+
+.. cfunction:: PyThreadState* Py_NewInterpreter()
+
+ .. index::
+ module: __builtin__
+ module: __main__
+ module: sys
+ single: stdout (in module sys)
+ single: stderr (in module sys)
+ single: stdin (in module sys)
+
+ Create a new sub-interpreter. This is an (almost) totally separate environment
+ for the execution of Python code. In particular, the new interpreter has
+ separate, independent versions of all imported modules, including the
+ fundamental modules :mod:`__builtin__`, :mod:`__main__` and :mod:`sys`. The
+ table of loaded modules (``sys.modules``) and the module search path
+ (``sys.path``) are also separate. The new environment has no ``sys.argv``
+ variable. It has new standard I/O stream file objects ``sys.stdin``,
+ ``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying
+ :ctype:`FILE` structures in the C library).
+
+ The return value points to the first thread state created in the new
+ sub-interpreter. This thread state is made in the current thread state.
+ Note that no actual thread is created; see the discussion of thread states
+ below. If creation of the new interpreter is unsuccessful, *NULL* is
+ returned; no exception is set since the exception state is stored in the
+ current thread state and there may not be a current thread state. (Like all
+ other Python/C API functions, the global interpreter lock must be held before
+ calling this function and is still held when it returns; however, unlike most
+ other Python/C API functions, there needn't be a current thread state on
+ entry.)
+
+ .. index::
+ single: Py_Finalize()
+ single: Py_Initialize()
+
+ Extension modules are shared between (sub-)interpreters as follows: the first
+ time a particular extension is imported, it is initialized normally, and a
+ (shallow) copy of its module's dictionary is squirreled away. When the same
+ extension is imported by another (sub-)interpreter, a new module is initialized
+ and filled with the contents of this copy; the extension's ``init`` function is
+ not called. Note that this is different from what happens when an extension is
+ imported after the interpreter has been completely re-initialized by calling
+ :cfunc:`Py_Finalize` and :cfunc:`Py_Initialize`; in that case, the extension's
+ ``initmodule`` function *is* called again.
+
+ .. index:: single: close() (in module os)
+
+ **Bugs and caveats:** Because sub-interpreters (and the main interpreter) are
+ part of the same process, the insulation between them isn't perfect --- for
+ example, using low-level file operations like :func:`os.close` they can
+ (accidentally or maliciously) affect each other's open files. Because of the
+ way extensions are shared between (sub-)interpreters, some extensions may not
+ work properly; this is especially likely when the extension makes use of
+ (static) global variables, or when the extension manipulates its module's
+ dictionary after its initialization. It is possible to insert objects created
+ in one sub-interpreter into a namespace of another sub-interpreter; this should
+ be done with great care to avoid sharing user-defined functions, methods,
+ instances or classes between sub-interpreters, since import operations executed
+ by such objects may affect the wrong (sub-)interpreter's dictionary of loaded
+ modules. (XXX This is a hard-to-fix bug that will be addressed in a future
+ release.)
+
+ Also note that the use of this functionality is incompatible with extension
+ modules such as PyObjC and ctypes that use the :cfunc:`PyGILState_\*` APIs (and
+ this is inherent in the way the :cfunc:`PyGILState_\*` functions work). Simple
+ things may work, but confusing behavior will always be near.
+
+
+.. cfunction:: void Py_EndInterpreter(PyThreadState *tstate)
+
+ .. index:: single: Py_Finalize()
+
+ Destroy the (sub-)interpreter represented by the given thread state. The given
+ thread state must be the current thread state. See the discussion of thread
+ states below. When the call returns, the current thread state is *NULL*. All
+ thread states associated with this interpreter are destroyed. (The global
+ interpreter lock must be held before calling this function and is still held
+ when it returns.) :cfunc:`Py_Finalize` will destroy all sub-interpreters that
+ haven't been explicitly destroyed at that point.
+
+
+.. cfunction:: void Py_SetProgramName(char *name)
+
+ .. index::
+ single: Py_Initialize()
+ single: main()
+ single: Py_GetPath()
+
+ This function should be called before :cfunc:`Py_Initialize` is called for
+ the first time, if it is called at all. It tells the interpreter the value
+ of the ``argv[0]`` argument to the :cfunc:`main` function of the program.
+ This is used by :cfunc:`Py_GetPath` and some other functions below to find
+ the Python run-time libraries relative to the interpreter executable. The
+ default value is ``'python'``. The argument should point to a
+ zero-terminated character string in static storage whose contents will not
+ change for the duration of the program's execution. No code in the Python
+ interpreter will change the contents of this storage.
+
+
+.. cfunction:: char* Py_GetProgramName()
+
+ .. index:: single: Py_SetProgramName()
+
+ Return the program name set with :cfunc:`Py_SetProgramName`, or the default.
+ The returned string points into static storage; the caller should not modify its
+ value.
+
+
+.. cfunction:: char* Py_GetPrefix()
+
+ Return the *prefix* for installed platform-independent files. This is derived
+ through a number of complicated rules from the program name set with
+ :cfunc:`Py_SetProgramName` and some environment variables; for example, if the
+ program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The
+ returned string points into static storage; the caller should not modify its
+ value. This corresponds to the :makevar:`prefix` variable in the top-level
+ :file:`Makefile` and the :option:`--prefix` argument to the :program:`configure`
+ script at build time. The value is available to Python code as ``sys.prefix``.
+ It is only useful on Unix. See also the next function.
+
+
+.. cfunction:: char* Py_GetExecPrefix()
+
+ Return the *exec-prefix* for installed platform-*dependent* files. This is
+ derived through a number of complicated rules from the program name set with
+ :cfunc:`Py_SetProgramName` and some environment variables; for example, if the
+ program name is ``'/usr/local/bin/python'``, the exec-prefix is
+ ``'/usr/local'``. The returned string points into static storage; the caller
+ should not modify its value. This corresponds to the :makevar:`exec_prefix`
+ variable in the top-level :file:`Makefile` and the :option:`--exec-prefix`
+ argument to the :program:`configure` script at build time. The value is
+ available to Python code as ``sys.exec_prefix``. It is only useful on Unix.
+
+ Background: The exec-prefix differs from the prefix when platform dependent
+ files (such as executables and shared libraries) are installed in a different
+ directory tree. In a typical installation, platform dependent files may be
+ installed in the :file:`/usr/local/plat` subtree while platform independent may
+ be installed in :file:`/usr/local`.
+
+ Generally speaking, a platform is a combination of hardware and software
+ families, e.g. Sparc machines running the Solaris 2.x operating system are
+ considered the same platform, but Intel machines running Solaris 2.x are another
+ platform, and Intel machines running Linux are yet another platform. Different
+ major revisions of the same operating system generally also form different
+ platforms. Non-Unix operating systems are a different story; the installation
+ strategies on those systems are so different that the prefix and exec-prefix are
+ meaningless, and set to the empty string. Note that compiled Python bytecode
+ files are platform independent (but not independent from the Python version by
+ which they were compiled!).
+
+ System administrators will know how to configure the :program:`mount` or
+ :program:`automount` programs to share :file:`/usr/local` between platforms
+ while having :file:`/usr/local/plat` be a different filesystem for each
+ platform.
+
+
+.. cfunction:: char* Py_GetProgramFullPath()
+
+ .. index::
+ single: Py_SetProgramName()
+ single: executable (in module sys)
+
+ Return the full program name of the Python executable; this is computed as a
+ side-effect of deriving the default module search path from the program name
+ (set by :cfunc:`Py_SetProgramName` above). The returned string points into
+ static storage; the caller should not modify its value. The value is available
+ to Python code as ``sys.executable``.
+
+
+.. cfunction:: char* Py_GetPath()
+
+ .. index::
+ triple: module; search; path
+ single: path (in module sys)
+
+ Return the default module search path; this is computed from the program name
+ (set by :cfunc:`Py_SetProgramName` above) and some environment variables. The
+ returned string consists of a series of directory names separated by a platform
+ dependent delimiter character. The delimiter character is ``':'`` on Unix and
+ Mac OS X, ``';'`` on Windows. The returned string points into static storage;
+ the caller should not modify its value. The value is available to Python code
+ as the list ``sys.path``, which may be modified to change the future search path
+ for loaded modules.
+
+ .. % XXX should give the exact rules
+
+
+.. cfunction:: const char* Py_GetVersion()
+
+ Return the version of this Python interpreter. This is a string that looks
+ something like ::
+
+ "1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
+
+ .. index:: single: version (in module sys)
+
+ The first word (up to the first space character) is the current Python version;
+ the first three characters are the major and minor version separated by a
+ period. The returned string points into static storage; the caller should not
+ modify its value. The value is available to Python code as ``sys.version``.
+
+
+.. cfunction:: const char* Py_GetBuildNumber()
+
+ Return a string representing the Subversion revision that this Python executable
+ was built from. This number is a string because it may contain a trailing 'M'
+ if Python was built from a mixed revision source tree.
+
+ .. versionadded:: 2.5
+
+
+.. cfunction:: const char* Py_GetPlatform()
+
+ .. index:: single: platform (in module sys)
+
+ Return the platform identifier for the current platform. On Unix, this is
+ formed from the "official" name of the operating system, converted to lower
+ case, followed by the major revision number; e.g., for Solaris 2.x, which is
+ also known as SunOS 5.x, the value is ``'sunos5'``. On Mac OS X, it is
+ ``'darwin'``. On Windows, it is ``'win'``. The returned string points into
+ static storage; the caller should not modify its value. The value is available
+ to Python code as ``sys.platform``.
+
+
+.. cfunction:: const char* Py_GetCopyright()
+
+ Return the official copyright string for the current Python version, for example
+
+ ``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``
+
+ .. index:: single: copyright (in module sys)
+
+ The returned string points into static storage; the caller should not modify its
+ value. The value is available to Python code as ``sys.copyright``.
+
+
+.. cfunction:: const char* Py_GetCompiler()
+
+ Return an indication of the compiler used to build the current Python version,
+ in square brackets, for example::
+
+ "[GCC 2.7.2.2]"
+
+ .. index:: single: version (in module sys)
+
+ The returned string points into static storage; the caller should not modify its
+ value. The value is available to Python code as part of the variable
+ ``sys.version``.
+
+
+.. cfunction:: const char* Py_GetBuildInfo()
+
+ Return information about the sequence number and build date and time of the
+ current Python interpreter instance, for example ::
+
+ "#67, Aug 1 1997, 22:34:28"
+
+ .. index:: single: version (in module sys)
+
+ The returned string points into static storage; the caller should not modify its
+ value. The value is available to Python code as part of the variable
+ ``sys.version``.
+
+
+.. cfunction:: void PySys_SetArgv(int argc, char **argv)
+
+ .. index::
+ single: main()
+ single: Py_FatalError()
+ single: argv (in module sys)
+
+ Set ``sys.argv`` based on *argc* and *argv*. These parameters are similar to
+ those passed to the program's :cfunc:`main` function with the difference that
+ the first entry should refer to the script file to be executed rather than the
+ executable hosting the Python interpreter. If there isn't a script that will be
+ run, the first entry in *argv* can be an empty string. If this function fails
+ to initialize ``sys.argv``, a fatal condition is signalled using
+ :cfunc:`Py_FatalError`.
+
+ .. % XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
+ .. % check w/ Guido.
+
+.. % XXX Other PySys thingies (doesn't really belong in this chapter)
+
+
+.. _threads:
+
+Thread State and the Global Interpreter Lock
+============================================
+
+.. index::
+ single: global interpreter lock
+ single: interpreter lock
+ single: lock, interpreter
+
+The Python interpreter is not fully thread safe. In order to support
+multi-threaded Python programs, there's a global lock that must be held by the
+current thread before it can safely access Python objects. Without the lock,
+even the simplest operations could cause problems in a multi-threaded program:
+for example, when two threads simultaneously increment the reference count of
+the same object, the reference count could end up being incremented only once
+instead of twice.
+
+.. index:: single: setcheckinterval() (in module sys)
+
+Therefore, the rule exists that only the thread that has acquired the global
+interpreter lock may operate on Python objects or call Python/C API functions.
+In order to support multi-threaded Python programs, the interpreter regularly
+releases and reacquires the lock --- by default, every 100 bytecode instructions
+(this can be changed with :func:`sys.setcheckinterval`). The lock is also
+released and reacquired around potentially blocking I/O operations like reading
+or writing a file, so that other threads can run while the thread that requests
+the I/O is waiting for the I/O operation to complete.
+
+.. index::
+ single: PyThreadState
+ single: PyThreadState
+
+The Python interpreter needs to keep some bookkeeping information separate per
+thread --- for this it uses a data structure called :ctype:`PyThreadState`.
+There's one global variable, however: the pointer to the current
+:ctype:`PyThreadState` structure. While most thread packages have a way to
+store "per-thread global data," Python's internal platform independent thread
+abstraction doesn't support this yet. Therefore, the current thread state must
+be manipulated explicitly.
+
+This is easy enough in most cases. Most code manipulating the global
+interpreter lock has the following simple structure::
+
+ Save the thread state in a local variable.
+ Release the interpreter lock.
+ ...Do some blocking I/O operation...
+ Reacquire the interpreter lock.
+ Restore the thread state from the local variable.
+
+This is so common that a pair of macros exists to simplify it::
+
+ Py_BEGIN_ALLOW_THREADS
+ ...Do some blocking I/O operation...
+ Py_END_ALLOW_THREADS
+
+.. index::
+ single: Py_BEGIN_ALLOW_THREADS
+ single: Py_END_ALLOW_THREADS
+
+The :cmacro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a
+hidden local variable; the :cmacro:`Py_END_ALLOW_THREADS` macro closes the
+block. Another advantage of using these two macros is that when Python is
+compiled without thread support, they are defined empty, thus saving the thread
+state and lock manipulations.
+
+When thread support is enabled, the block above expands to the following code::
+
+ PyThreadState *_save;
+
+ _save = PyEval_SaveThread();
+ ...Do some blocking I/O operation...
+ PyEval_RestoreThread(_save);
+
+Using even lower level primitives, we can get roughly the same effect as
+follows::
+
+ PyThreadState *_save;
+
+ _save = PyThreadState_Swap(NULL);
+ PyEval_ReleaseLock();
+ ...Do some blocking I/O operation...
+ PyEval_AcquireLock();
+ PyThreadState_Swap(_save);
+
+.. index::
+ single: PyEval_RestoreThread()
+ single: errno
+ single: PyEval_SaveThread()
+ single: PyEval_ReleaseLock()
+ single: PyEval_AcquireLock()
+
+There are some subtle differences; in particular, :cfunc:`PyEval_RestoreThread`
+saves and restores the value of the global variable :cdata:`errno`, since the
+lock manipulation does not guarantee that :cdata:`errno` is left alone. Also,
+when thread support is disabled, :cfunc:`PyEval_SaveThread` and
+:cfunc:`PyEval_RestoreThread` don't manipulate the lock; in this case,
+:cfunc:`PyEval_ReleaseLock` and :cfunc:`PyEval_AcquireLock` are not available.
+This is done so that dynamically loaded extensions compiled with thread support
+enabled can be loaded by an interpreter that was compiled with disabled thread
+support.
+
+The global interpreter lock is used to protect the pointer to the current thread
+state. When releasing the lock and saving the thread state, the current thread
+state pointer must be retrieved before the lock is released (since another
+thread could immediately acquire the lock and store its own thread state in the
+global variable). Conversely, when acquiring the lock and restoring the thread
+state, the lock must be acquired before storing the thread state pointer.
+
+Why am I going on with so much detail about this? Because when threads are
+created from C, they don't have the global interpreter lock, nor is there a
+thread state data structure for them. Such threads must bootstrap themselves
+into existence, by first creating a thread state data structure, then acquiring
+the lock, and finally storing their thread state pointer, before they can start
+using the Python/C API. When they are done, they should reset the thread state
+pointer, release the lock, and finally free their thread state data structure.
+
+Beginning with version 2.3, threads can now take advantage of the
+:cfunc:`PyGILState_\*` functions to do all of the above automatically. The
+typical idiom for calling into Python from a C thread is now::
+
+ PyGILState_STATE gstate;
+ gstate = PyGILState_Ensure();
+
+ /* Perform Python actions here. */
+ result = CallSomeFunction();
+ /* evaluate result */
+
+ /* Release the thread. No Python API allowed beyond this point. */
+ PyGILState_Release(gstate);
+
+Note that the :cfunc:`PyGILState_\*` functions assume there is only one global
+interpreter (created automatically by :cfunc:`Py_Initialize`). Python still
+supports the creation of additional interpreters (using
+:cfunc:`Py_NewInterpreter`), but mixing multiple interpreters and the
+:cfunc:`PyGILState_\*` API is unsupported.
+
+
+.. ctype:: PyInterpreterState
+
+ This data structure represents the state shared by a number of cooperating
+ threads. Threads belonging to the same interpreter share their module
+ administration and a few other internal items. There are no public members in
+ this structure.
+
+ Threads belonging to different interpreters initially share nothing, except
+ process state like available memory, open file descriptors and such. The global
+ interpreter lock is also shared by all threads, regardless of to which
+ interpreter they belong.
+
+
+.. ctype:: PyThreadState
+
+ This data structure represents the state of a single thread. The only public
+ data member is :ctype:`PyInterpreterState \*`:attr:`interp`, which points to
+ this thread's interpreter state.
+
+
+.. cfunction:: void PyEval_InitThreads()
+
+ .. index::
+ single: PyEval_ReleaseLock()
+ single: PyEval_ReleaseThread()
+ single: PyEval_SaveThread()
+ single: PyEval_RestoreThread()
+
+ Initialize and acquire the global interpreter lock. It should be called in the
+ main thread before creating a second thread or engaging in any other thread
+ operations such as :cfunc:`PyEval_ReleaseLock` or
+ ``PyEval_ReleaseThread(tstate)``. It is not needed before calling
+ :cfunc:`PyEval_SaveThread` or :cfunc:`PyEval_RestoreThread`.
+
+ .. index:: single: Py_Initialize()
+
+ This is a no-op when called for a second time. It is safe to call this function
+ before calling :cfunc:`Py_Initialize`.
+
+ .. index:: module: thread
+
+ When only the main thread exists, no lock operations are needed. This is a
+ common situation (most Python programs do not use threads), and the lock
+ operations slow the interpreter down a bit. Therefore, the lock is not created
+ initially. This situation is equivalent to having acquired the lock: when
+ there is only a single thread, all object accesses are safe. Therefore, when
+ this function initializes the lock, it also acquires it. Before the Python
+ :mod:`thread` module creates a new thread, knowing that either it has the lock
+ or the lock hasn't been created yet, it calls :cfunc:`PyEval_InitThreads`. When
+ this call returns, it is guaranteed that the lock has been created and that the
+ calling thread has acquired it.
+
+ It is **not** safe to call this function when it is unknown which thread (if
+ any) currently has the global interpreter lock.
+
+ This function is not available when thread support is disabled at compile time.
+
+
+.. cfunction:: int PyEval_ThreadsInitialized()
+
+ Returns a non-zero value if :cfunc:`PyEval_InitThreads` has been called. This
+ function can be called without holding the lock, and therefore can be used to
+ avoid calls to the locking API when running single-threaded. This function is
+ not available when thread support is disabled at compile time.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: void PyEval_AcquireLock()
+
+ Acquire the global interpreter lock. The lock must have been created earlier.
+ If this thread already has the lock, a deadlock ensues. This function is not
+ available when thread support is disabled at compile time.
+
+
+.. cfunction:: void PyEval_ReleaseLock()
+
+ Release the global interpreter lock. The lock must have been created earlier.
+ This function is not available when thread support is disabled at compile time.
+
+
+.. cfunction:: void PyEval_AcquireThread(PyThreadState *tstate)
+
+ Acquire the global interpreter lock and set the current thread state to
+ *tstate*, which should not be *NULL*. The lock must have been created earlier.
+ If this thread already has the lock, deadlock ensues. This function is not
+ available when thread support is disabled at compile time.
+
+
+.. cfunction:: void PyEval_ReleaseThread(PyThreadState *tstate)
+
+ Reset the current thread state to *NULL* and release the global interpreter
+ lock. The lock must have been created earlier and must be held by the current
+ thread. The *tstate* argument, which must not be *NULL*, is only used to check
+ that it represents the current thread state --- if it isn't, a fatal error is
+ reported. This function is not available when thread support is disabled at
+ compile time.
+
+
+.. cfunction:: PyThreadState* PyEval_SaveThread()
+
+ Release the interpreter lock (if it has been created and thread support is
+ enabled) and reset the thread state to *NULL*, returning the previous thread
+ state (which is not *NULL*). If the lock has been created, the current thread
+ must have acquired it. (This function is available even when thread support is
+ disabled at compile time.)
+
+
+.. cfunction:: void PyEval_RestoreThread(PyThreadState *tstate)
+
+ Acquire the interpreter lock (if it has been created and thread support is
+ enabled) and set the thread state to *tstate*, which must not be *NULL*. If the
+ lock has been created, the current thread must not have acquired it, otherwise
+ deadlock ensues. (This function is available even when thread support is
+ disabled at compile time.)
+
+The following macros are normally used without a trailing semicolon; look for
+example usage in the Python source distribution.
+
+
+.. cmacro:: Py_BEGIN_ALLOW_THREADS
+
+ This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();``.
+ Note that it contains an opening brace; it must be matched with a following
+ :cmacro:`Py_END_ALLOW_THREADS` macro. See above for further discussion of this
+ macro. It is a no-op when thread support is disabled at compile time.
+
+
+.. cmacro:: Py_END_ALLOW_THREADS
+
+ This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it contains
+ a closing brace; it must be matched with an earlier
+ :cmacro:`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of
+ this macro. It is a no-op when thread support is disabled at compile time.
+
+
+.. cmacro:: Py_BLOCK_THREADS
+
+ This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to
+ :cmacro:`Py_END_ALLOW_THREADS` without the closing brace. It is a no-op when
+ thread support is disabled at compile time.
+
+
+.. cmacro:: Py_UNBLOCK_THREADS
+
+ This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to
+ :cmacro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable
+ declaration. It is a no-op when thread support is disabled at compile time.
+
+All of the following functions are only available when thread support is enabled
+at compile time, and must be called only when the interpreter lock has been
+created.
+
+
+.. cfunction:: PyInterpreterState* PyInterpreterState_New()
+
+ Create a new interpreter state object. The interpreter lock need not be held,
+ but may be held if it is necessary to serialize calls to this function.
+
+
+.. cfunction:: void PyInterpreterState_Clear(PyInterpreterState *interp)
+
+ Reset all information in an interpreter state object. The interpreter lock must
+ be held.
+
+
+.. cfunction:: void PyInterpreterState_Delete(PyInterpreterState *interp)
+
+ Destroy an interpreter state object. The interpreter lock need not be held.
+ The interpreter state must have been reset with a previous call to
+ :cfunc:`PyInterpreterState_Clear`.
+
+
+.. cfunction:: PyThreadState* PyThreadState_New(PyInterpreterState *interp)
+
+ Create a new thread state object belonging to the given interpreter object. The
+ interpreter lock need not be held, but may be held if it is necessary to
+ serialize calls to this function.
+
+
+.. cfunction:: void PyThreadState_Clear(PyThreadState *tstate)
+
+ Reset all information in a thread state object. The interpreter lock must be
+ held.
+
+
+.. cfunction:: void PyThreadState_Delete(PyThreadState *tstate)
+
+ Destroy a thread state object. The interpreter lock need not be held. The
+ thread state must have been reset with a previous call to
+ :cfunc:`PyThreadState_Clear`.
+
+
+.. cfunction:: PyThreadState* PyThreadState_Get()
+
+ Return the current thread state. The interpreter lock must be held. When the
+ current thread state is *NULL*, this issues a fatal error (so that the caller
+ needn't check for *NULL*).
+
+
+.. cfunction:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate)
+
+ Swap the current thread state with the thread state given by the argument
+ *tstate*, which may be *NULL*. The interpreter lock must be held.
+
+
+.. cfunction:: PyObject* PyThreadState_GetDict()
+
+ Return a dictionary in which extensions can store thread-specific state
+ information. Each extension should use a unique key to use to store state in
+ the dictionary. It is okay to call this function when no current thread state
+ is available. If this function returns *NULL*, no exception has been raised and
+ the caller should assume no current thread state is available.
+
+ .. versionchanged:: 2.3
+ Previously this could only be called when a current thread is active, and *NULL*
+ meant that an exception was raised.
+
+
+.. cfunction:: int PyThreadState_SetAsyncExc(long id, PyObject *exc)
+
+ Asynchronously raise an exception in a thread. The *id* argument is the thread
+ id of the target thread; *exc* is the exception object to be raised. This
+ function does not steal any references to *exc*. To prevent naive misuse, you
+ must write your own C extension to call this. Must be called with the GIL held.
+ Returns the number of thread states modified; this is normally one, but will be
+ zero if the thread id isn't found. If *exc* is :const:`NULL`, the pending
+ exception (if any) for the thread is cleared. This raises no exceptions.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: PyGILState_STATE PyGILState_Ensure()
+
+ Ensure that the current thread is ready to call the Python C API regardless of
+ the current state of Python, or of its thread lock. This may be called as many
+ times as desired by a thread as long as each call is matched with a call to
+ :cfunc:`PyGILState_Release`. In general, other thread-related APIs may be used
+ between :cfunc:`PyGILState_Ensure` and :cfunc:`PyGILState_Release` calls as long
+ as the thread state is restored to its previous state before the Release(). For
+ example, normal usage of the :cmacro:`Py_BEGIN_ALLOW_THREADS` and
+ :cmacro:`Py_END_ALLOW_THREADS` macros is acceptable.
+
+ The return value is an opaque "handle" to the thread state when
+ :cfunc:`PyGILState_Acquire` was called, and must be passed to
+ :cfunc:`PyGILState_Release` to ensure Python is left in the same state. Even
+ though recursive calls are allowed, these handles *cannot* be shared - each
+ unique call to :cfunc:`PyGILState_Ensure` must save the handle for its call to
+ :cfunc:`PyGILState_Release`.
+
+ When the function returns, the current thread will hold the GIL. Failure is a
+ fatal error.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: void PyGILState_Release(PyGILState_STATE)
+
+ Release any resources previously acquired. After this call, Python's state will
+ be the same as it was prior to the corresponding :cfunc:`PyGILState_Ensure` call
+ (but generally this state will be unknown to the caller, hence the use of the
+ GILState API.)
+
+ Every call to :cfunc:`PyGILState_Ensure` must be matched by a call to
+ :cfunc:`PyGILState_Release` on the same thread.
+
+ .. versionadded:: 2.3
+
+
+.. _profiling:
+
+Profiling and Tracing
+=====================
+
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+The Python interpreter provides some low-level support for attaching profiling
+and execution tracing facilities. These are used for profiling, debugging, and
+coverage analysis tools.
+
+Starting with Python 2.2, the implementation of this facility was substantially
+revised, and an interface from C was added. This C interface allows the
+profiling or tracing code to avoid the overhead of calling through Python-level
+callable objects, making a direct C function call instead. The essential
+attributes of the facility have not changed; the interface allows trace
+functions to be installed per-thread, and the basic events reported to the trace
+function are the same as had been reported to the Python-level trace functions
+in previous versions.
+
+
+.. ctype:: int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)
+
+ The type of the trace function registered using :cfunc:`PyEval_SetProfile` and
+ :cfunc:`PyEval_SetTrace`. The first parameter is the object passed to the
+ registration function as *obj*, *frame* is the frame object to which the event
+ pertains, *what* is one of the constants :const:`PyTrace_CALL`,
+ :const:`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`,
+ :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, or
+ :const:`PyTrace_C_RETURN`, and *arg* depends on the value of *what*:
+
+ +------------------------------+--------------------------------------+
+ | Value of *what* | Meaning of *arg* |
+ +==============================+======================================+
+ | :const:`PyTrace_CALL` | Always *NULL*. |
+ +------------------------------+--------------------------------------+
+ | :const:`PyTrace_EXCEPTION` | Exception information as returned by |
+ | | :func:`sys.exc_info`. |
+ +------------------------------+--------------------------------------+
+ | :const:`PyTrace_LINE` | Always *NULL*. |
+ +------------------------------+--------------------------------------+
+ | :const:`PyTrace_RETURN` | Value being returned to the caller. |
+ +------------------------------+--------------------------------------+
+ | :const:`PyTrace_C_CALL` | Name of function being called. |
+ +------------------------------+--------------------------------------+
+ | :const:`PyTrace_C_EXCEPTION` | Always *NULL*. |
+ +------------------------------+--------------------------------------+
+ | :const:`PyTrace_C_RETURN` | Always *NULL*. |
+ +------------------------------+--------------------------------------+
+
+
+.. cvar:: int PyTrace_CALL
+
+ The value of the *what* parameter to a :ctype:`Py_tracefunc` function when a new
+ call to a function or method is being reported, or a new entry into a generator.
+ Note that the creation of the iterator for a generator function is not reported
+ as there is no control transfer to the Python bytecode in the corresponding
+ frame.
+
+
+.. cvar:: int PyTrace_EXCEPTION
+
+ The value of the *what* parameter to a :ctype:`Py_tracefunc` function when an
+ exception has been raised. The callback function is called with this value for
+ *what* when after any bytecode is processed after which the exception becomes
+ set within the frame being executed. The effect of this is that as exception
+ propagation causes the Python stack to unwind, the callback is called upon
+ return to each frame as the exception propagates. Only trace functions receives
+ these events; they are not needed by the profiler.
+
+
+.. cvar:: int PyTrace_LINE
+
+ The value passed as the *what* parameter to a trace function (but not a
+ profiling function) when a line-number event is being reported.
+
+
+.. cvar:: int PyTrace_RETURN
+
+ The value for the *what* parameter to :ctype:`Py_tracefunc` functions when a
+ call is returning without propagating an exception.
+
+
+.. cvar:: int PyTrace_C_CALL
+
+ The value for the *what* parameter to :ctype:`Py_tracefunc` functions when a C
+ function is about to be called.
+
+
+.. cvar:: int PyTrace_C_EXCEPTION
+
+ The value for the *what* parameter to :ctype:`Py_tracefunc` functions when a C
+ function has thrown an exception.
+
+
+.. cvar:: int PyTrace_C_RETURN
+
+ The value for the *what* parameter to :ctype:`Py_tracefunc` functions when a C
+ function has returned.
+
+
+.. cfunction:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)
+
+ Set the profiler function to *func*. The *obj* parameter is passed to the
+ function as its first parameter, and may be any Python object, or *NULL*. If
+ the profile function needs to maintain state, using a different value for *obj*
+ for each thread provides a convenient and thread-safe place to store it. The
+ profile function is called for all monitored events except the line-number
+ events.
+
+
+.. cfunction:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)
+
+ Set the tracing function to *func*. This is similar to
+ :cfunc:`PyEval_SetProfile`, except the tracing function does receive line-number
+ events.
+
+
+.. _advanced-debugging:
+
+Advanced Debugger Support
+=========================
+
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+These functions are only intended to be used by advanced debugging tools.
+
+
+.. cfunction:: PyInterpreterState* PyInterpreterState_Head()
+
+ Return the interpreter state object at the head of the list of all such objects.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)
+
+ Return the next interpreter state object after *interp* from the list of all
+ such objects.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp)
+
+ Return the a pointer to the first :ctype:`PyThreadState` object in the list of
+ threads associated with the interpreter *interp*.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyThreadState* PyThreadState_Next(PyThreadState *tstate)
+
+ Return the next thread state object after *tstate* from the list of all such
+ objects belonging to the same :ctype:`PyInterpreterState` object.
+
+ .. versionadded:: 2.2
+
--- /dev/null
+.. highlightlang:: c
+
+
+.. _api-intro:
+
+************
+Introduction
+************
+
+The Application Programmer's Interface to Python gives C and C++ programmers
+access to the Python interpreter at a variety of levels. The API is equally
+usable from C++, but for brevity it is generally referred to as the Python/C
+API. There are two fundamentally different reasons for using the Python/C API.
+The first reason is to write *extension modules* for specific purposes; these
+are C modules that extend the Python interpreter. This is probably the most
+common use. The second reason is to use Python as a component in a larger
+application; this technique is generally referred to as :dfn:`embedding` Python
+in an application.
+
+Writing an extension module is a relatively well-understood process, where a
+"cookbook" approach works well. There are several tools that automate the
+process to some extent. While people have embedded Python in other
+applications since its early existence, the process of embedding Python is less
+straightforward than writing an extension.
+
+Many API functions are useful independent of whether you're embedding or
+extending Python; moreover, most applications that embed Python will need to
+provide a custom extension as well, so it's probably a good idea to become
+familiar with writing an extension before attempting to embed Python in a real
+application.
+
+
+.. _api-includes:
+
+Include Files
+=============
+
+All function, type and macro definitions needed to use the Python/C API are
+included in your code by the following line::
+
+ #include "Python.h"
+
+This implies inclusion of the following standard headers: ``<stdio.h>``,
+``<string.h>``, ``<errno.h>``, ``<limits.h>``, and ``<stdlib.h>`` (if
+available).
+
+.. warning::
+
+ Since Python may define some pre-processor definitions which affect the standard
+ headers on some systems, you *must* include :file:`Python.h` before any standard
+ headers are included.
+
+All user visible names defined by Python.h (except those defined by the included
+standard headers) have one of the prefixes ``Py`` or ``_Py``. Names beginning
+with ``_Py`` are for internal use by the Python implementation and should not be
+used by extension writers. Structure member names do not have a reserved prefix.
+
+**Important:** user code should never define names that begin with ``Py`` or
+``_Py``. This confuses the reader, and jeopardizes the portability of the user
+code to future Python versions, which may define additional names beginning with
+one of these prefixes.
+
+The header files are typically installed with Python. On Unix, these are
+located in the directories :file:`{prefix}/include/pythonversion/` and
+:file:`{exec_prefix}/include/pythonversion/`, where :envvar:`prefix` and
+:envvar:`exec_prefix` are defined by the corresponding parameters to Python's
+:program:`configure` script and *version* is ``sys.version[:3]``. On Windows,
+the headers are installed in :file:`{prefix}/include`, where :envvar:`prefix` is
+the installation directory specified to the installer.
+
+To include the headers, place both directories (if different) on your compiler's
+search path for includes. Do *not* place the parent directories on the search
+path and then use ``#include <pythonX.Y/Python.h>``; this will break on
+multi-platform builds since the platform independent headers under
+:envvar:`prefix` include the platform specific headers from
+:envvar:`exec_prefix`.
+
+C++ users should note that though the API is defined entirely using C, the
+header files do properly declare the entry points to be ``extern "C"``, so there
+is no need to do anything special to use the API from C++.
+
+
+.. _api-objects:
+
+Objects, Types and Reference Counts
+===================================
+
+.. index:: object: type
+
+Most Python/C API functions have one or more arguments as well as a return value
+of type :ctype:`PyObject\*`. This type is a pointer to an opaque data type
+representing an arbitrary Python object. Since all Python object types are
+treated the same way by the Python language in most situations (e.g.,
+assignments, scope rules, and argument passing), it is only fitting that they
+should be represented by a single C type. Almost all Python objects live on the
+heap: you never declare an automatic or static variable of type
+:ctype:`PyObject`, only pointer variables of type :ctype:`PyObject\*` can be
+declared. The sole exception are the type objects; since these must never be
+deallocated, they are typically static :ctype:`PyTypeObject` objects.
+
+All Python objects (even Python integers) have a :dfn:`type` and a
+:dfn:`reference count`. An object's type determines what kind of object it is
+(e.g., an integer, a list, or a user-defined function; there are many more as
+explained in :ref:`types`). For each of the well-known types there is a macro
+to check whether an object is of that type; for instance, ``PyList_Check(a)`` is
+true if (and only if) the object pointed to by *a* is a Python list.
+
+
+.. _api-refcounts:
+
+Reference Counts
+----------------
+
+The reference count is important because today's computers have a finite (and
+often severely limited) memory size; it counts how many different places there
+are that have a reference to an object. Such a place could be another object,
+or a global (or static) C variable, or a local variable in some C function.
+When an object's reference count becomes zero, the object is deallocated. If
+it contains references to other objects, their reference count is decremented.
+Those other objects may be deallocated in turn, if this decrement makes their
+reference count become zero, and so on. (There's an obvious problem with
+objects that reference each other here; for now, the solution is "don't do
+that.")
+
+.. index::
+ single: Py_INCREF()
+ single: Py_DECREF()
+
+Reference counts are always manipulated explicitly. The normal way is to use
+the macro :cfunc:`Py_INCREF` to increment an object's reference count by one,
+and :cfunc:`Py_DECREF` to decrement it by one. The :cfunc:`Py_DECREF` macro
+is considerably more complex than the incref one, since it must check whether
+the reference count becomes zero and then cause the object's deallocator to be
+called. The deallocator is a function pointer contained in the object's type
+structure. The type-specific deallocator takes care of decrementing the
+reference counts for other objects contained in the object if this is a compound
+object type, such as a list, as well as performing any additional finalization
+that's needed. There's no chance that the reference count can overflow; at
+least as many bits are used to hold the reference count as there are distinct
+memory locations in virtual memory (assuming ``sizeof(long) >= sizeof(char*)``).
+Thus, the reference count increment is a simple operation.
+
+It is not necessary to increment an object's reference count for every local
+variable that contains a pointer to an object. In theory, the object's
+reference count goes up by one when the variable is made to point to it and it
+goes down by one when the variable goes out of scope. However, these two
+cancel each other out, so at the end the reference count hasn't changed. The
+only real reason to use the reference count is to prevent the object from being
+deallocated as long as our variable is pointing to it. If we know that there
+is at least one other reference to the object that lives at least as long as
+our variable, there is no need to increment the reference count temporarily.
+An important situation where this arises is in objects that are passed as
+arguments to C functions in an extension module that are called from Python;
+the call mechanism guarantees to hold a reference to every argument for the
+duration of the call.
+
+However, a common pitfall is to extract an object from a list and hold on to it
+for a while without incrementing its reference count. Some other operation might
+conceivably remove the object from the list, decrementing its reference count
+and possible deallocating it. The real danger is that innocent-looking
+operations may invoke arbitrary Python code which could do this; there is a code
+path which allows control to flow back to the user from a :cfunc:`Py_DECREF`, so
+almost any operation is potentially dangerous.
+
+A safe approach is to always use the generic operations (functions whose name
+begins with ``PyObject_``, ``PyNumber_``, ``PySequence_`` or ``PyMapping_``).
+These operations always increment the reference count of the object they return.
+This leaves the caller with the responsibility to call :cfunc:`Py_DECREF` when
+they are done with the result; this soon becomes second nature.
+
+
+.. _api-refcountdetails:
+
+Reference Count Details
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The reference count behavior of functions in the Python/C API is best explained
+in terms of *ownership of references*. Ownership pertains to references, never
+to objects (objects are not owned: they are always shared). "Owning a
+reference" means being responsible for calling Py_DECREF on it when the
+reference is no longer needed. Ownership can also be transferred, meaning that
+the code that receives ownership of the reference then becomes responsible for
+eventually decref'ing it by calling :cfunc:`Py_DECREF` or :cfunc:`Py_XDECREF`
+when it's no longer needed---or passing on this responsibility (usually to its
+caller). When a function passes ownership of a reference on to its caller, the
+caller is said to receive a *new* reference. When no ownership is transferred,
+the caller is said to *borrow* the reference. Nothing needs to be done for a
+borrowed reference.
+
+Conversely, when a calling function passes it a reference to an object, there
+are two possibilities: the function *steals* a reference to the object, or it
+does not. *Stealing a reference* means that when you pass a reference to a
+function, that function assumes that it now owns that reference, and you are not
+responsible for it any longer.
+
+.. index::
+ single: PyList_SetItem()
+ single: PyTuple_SetItem()
+
+Few functions steal references; the two notable exceptions are
+:cfunc:`PyList_SetItem` and :cfunc:`PyTuple_SetItem`, which steal a reference
+to the item (but not to the tuple or list into which the item is put!). These
+functions were designed to steal a reference because of a common idiom for
+populating a tuple or list with newly created objects; for example, the code to
+create the tuple ``(1, 2, "three")`` could look like this (forgetting about
+error handling for the moment; a better way to code this is shown below)::
+
+ PyObject *t;
+
+ t = PyTuple_New(3);
+ PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
+ PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
+ PyTuple_SetItem(t, 2, PyString_FromString("three"));
+
+Here, :cfunc:`PyInt_FromLong` returns a new reference which is immediately
+stolen by :cfunc:`PyTuple_SetItem`. When you want to keep using an object
+although the reference to it will be stolen, use :cfunc:`Py_INCREF` to grab
+another reference before calling the reference-stealing function.
+
+Incidentally, :cfunc:`PyTuple_SetItem` is the *only* way to set tuple items;
+:cfunc:`PySequence_SetItem` and :cfunc:`PyObject_SetItem` refuse to do this
+since tuples are an immutable data type. You should only use
+:cfunc:`PyTuple_SetItem` for tuples that you are creating yourself.
+
+Equivalent code for populating a list can be written using :cfunc:`PyList_New`
+and :cfunc:`PyList_SetItem`.
+
+However, in practice, you will rarely use these ways of creating and populating
+a tuple or list. There's a generic function, :cfunc:`Py_BuildValue`, that can
+create most common objects from C values, directed by a :dfn:`format string`.
+For example, the above two blocks of code could be replaced by the following
+(which also takes care of the error checking)::
+
+ PyObject *tuple, *list;
+
+ tuple = Py_BuildValue("(iis)", 1, 2, "three");
+ list = Py_BuildValue("[iis]", 1, 2, "three");
+
+It is much more common to use :cfunc:`PyObject_SetItem` and friends with items
+whose references you are only borrowing, like arguments that were passed in to
+the function you are writing. In that case, their behaviour regarding reference
+counts is much saner, since you don't have to increment a reference count so you
+can give a reference away ("have it be stolen"). For example, this function
+sets all items of a list (actually, any mutable sequence) to a given item::
+
+ int
+ set_all(PyObject *target, PyObject *item)
+ {
+ int i, n;
+
+ n = PyObject_Length(target);
+ if (n < 0)
+ return -1;
+ for (i = 0; i < n; i++) {
+ PyObject *index = PyInt_FromLong(i);
+ if (!index)
+ return -1;
+ if (PyObject_SetItem(target, index, item) < 0)
+ return -1;
+ Py_DECREF(index);
+ }
+ return 0;
+ }
+
+.. index:: single: set_all()
+
+The situation is slightly different for function return values. While passing
+a reference to most functions does not change your ownership responsibilities
+for that reference, many functions that return a reference to an object give
+you ownership of the reference. The reason is simple: in many cases, the
+returned object is created on the fly, and the reference you get is the only
+reference to the object. Therefore, the generic functions that return object
+references, like :cfunc:`PyObject_GetItem` and :cfunc:`PySequence_GetItem`,
+always return a new reference (the caller becomes the owner of the reference).
+
+It is important to realize that whether you own a reference returned by a
+function depends on which function you call only --- *the plumage* (the type of
+the object passed as an argument to the function) *doesn't enter into it!*
+Thus, if you extract an item from a list using :cfunc:`PyList_GetItem`, you
+don't own the reference --- but if you obtain the same item from the same list
+using :cfunc:`PySequence_GetItem` (which happens to take exactly the same
+arguments), you do own a reference to the returned object.
+
+.. index::
+ single: PyList_GetItem()
+ single: PySequence_GetItem()
+
+Here is an example of how you could write a function that computes the sum of
+the items in a list of integers; once using :cfunc:`PyList_GetItem`, and once
+using :cfunc:`PySequence_GetItem`. ::
+
+ long
+ sum_list(PyObject *list)
+ {
+ int i, n;
+ long total = 0;
+ PyObject *item;
+
+ n = PyList_Size(list);
+ if (n < 0)
+ return -1; /* Not a list */
+ for (i = 0; i < n; i++) {
+ item = PyList_GetItem(list, i); /* Can't fail */
+ if (!PyInt_Check(item)) continue; /* Skip non-integers */
+ total += PyInt_AsLong(item);
+ }
+ return total;
+ }
+
+.. index:: single: sum_list()
+
+::
+
+ long
+ sum_sequence(PyObject *sequence)
+ {
+ int i, n;
+ long total = 0;
+ PyObject *item;
+ n = PySequence_Length(sequence);
+ if (n < 0)
+ return -1; /* Has no length */
+ for (i = 0; i < n; i++) {
+ item = PySequence_GetItem(sequence, i);
+ if (item == NULL)
+ return -1; /* Not a sequence, or other failure */
+ if (PyInt_Check(item))
+ total += PyInt_AsLong(item);
+ Py_DECREF(item); /* Discard reference ownership */
+ }
+ return total;
+ }
+
+.. index:: single: sum_sequence()
+
+
+.. _api-types:
+
+Types
+-----
+
+There are few other data types that play a significant role in the Python/C
+API; most are simple C types such as :ctype:`int`, :ctype:`long`,
+:ctype:`double` and :ctype:`char\*`. A few structure types are used to
+describe static tables used to list the functions exported by a module or the
+data attributes of a new object type, and another is used to describe the value
+of a complex number. These will be discussed together with the functions that
+use them.
+
+
+.. _api-exceptions:
+
+Exceptions
+==========
+
+The Python programmer only needs to deal with exceptions if specific error
+handling is required; unhandled exceptions are automatically propagated to the
+caller, then to the caller's caller, and so on, until they reach the top-level
+interpreter, where they are reported to the user accompanied by a stack
+traceback.
+
+.. index:: single: PyErr_Occurred()
+
+For C programmers, however, error checking always has to be explicit. All
+functions in the Python/C API can raise exceptions, unless an explicit claim is
+made otherwise in a function's documentation. In general, when a function
+encounters an error, it sets an exception, discards any object references that
+it owns, and returns an error indicator --- usually *NULL* or ``-1``. A few
+functions return a Boolean true/false result, with false indicating an error.
+Very few functions return no explicit error indicator or have an ambiguous
+return value, and require explicit testing for errors with
+:cfunc:`PyErr_Occurred`.
+
+.. index::
+ single: PyErr_SetString()
+ single: PyErr_Clear()
+
+Exception state is maintained in per-thread storage (this is equivalent to
+using global storage in an unthreaded application). A thread can be in one of
+two states: an exception has occurred, or not. The function
+:cfunc:`PyErr_Occurred` can be used to check for this: it returns a borrowed
+reference to the exception type object when an exception has occurred, and
+*NULL* otherwise. There are a number of functions to set the exception state:
+:cfunc:`PyErr_SetString` is the most common (though not the most general)
+function to set the exception state, and :cfunc:`PyErr_Clear` clears the
+exception state.
+
+.. index::
+ single: exc_type (in module sys)
+ single: exc_value (in module sys)
+ single: exc_traceback (in module sys)
+
+The full exception state consists of three objects (all of which can be
+*NULL*): the exception type, the corresponding exception value, and the
+traceback. These have the same meanings as the Python objects
+``sys.exc_type``, ``sys.exc_value``, and ``sys.exc_traceback``; however, they
+are not the same: the Python objects represent the last exception being handled
+by a Python :keyword:`try` ... :keyword:`except` statement, while the C level
+exception state only exists while an exception is being passed on between C
+functions until it reaches the Python bytecode interpreter's main loop, which
+takes care of transferring it to ``sys.exc_type`` and friends.
+
+.. index:: single: exc_info() (in module sys)
+
+Note that starting with Python 1.5, the preferred, thread-safe way to access the
+exception state from Python code is to call the function :func:`sys.exc_info`,
+which returns the per-thread exception state for Python code. Also, the
+semantics of both ways to access the exception state have changed so that a
+function which catches an exception will save and restore its thread's exception
+state so as to preserve the exception state of its caller. This prevents common
+bugs in exception handling code caused by an innocent-looking function
+overwriting the exception being handled; it also reduces the often unwanted
+lifetime extension for objects that are referenced by the stack frames in the
+traceback.
+
+As a general principle, a function that calls another function to perform some
+task should check whether the called function raised an exception, and if so,
+pass the exception state on to its caller. It should discard any object
+references that it owns, and return an error indicator, but it should *not* set
+another exception --- that would overwrite the exception that was just raised,
+and lose important information about the exact cause of the error.
+
+.. index:: single: sum_sequence()
+
+A simple example of detecting exceptions and passing them on is shown in the
+:cfunc:`sum_sequence` example above. It so happens that that example doesn't
+need to clean up any owned references when it detects an error. The following
+example function shows some error cleanup. First, to remind you why you like
+Python, we show the equivalent Python code::
+
+ def incr_item(dict, key):
+ try:
+ item = dict[key]
+ except KeyError:
+ item = 0
+ dict[key] = item + 1
+
+.. index:: single: incr_item()
+
+Here is the corresponding C code, in all its glory::
+
+ int
+ incr_item(PyObject *dict, PyObject *key)
+ {
+ /* Objects all initialized to NULL for Py_XDECREF */
+ PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
+ int rv = -1; /* Return value initialized to -1 (failure) */
+
+ item = PyObject_GetItem(dict, key);
+ if (item == NULL) {
+ /* Handle KeyError only: */
+ if (!PyErr_ExceptionMatches(PyExc_KeyError))
+ goto error;
+
+ /* Clear the error and use zero: */
+ PyErr_Clear();
+ item = PyInt_FromLong(0L);
+ if (item == NULL)
+ goto error;
+ }
+ const_one = PyInt_FromLong(1L);
+ if (const_one == NULL)
+ goto error;
+
+ incremented_item = PyNumber_Add(item, const_one);
+ if (incremented_item == NULL)
+ goto error;
+
+ if (PyObject_SetItem(dict, key, incremented_item) < 0)
+ goto error;
+ rv = 0; /* Success */
+ /* Continue with cleanup code */
+
+ error:
+ /* Cleanup code, shared by success and failure path */
+
+ /* Use Py_XDECREF() to ignore NULL references */
+ Py_XDECREF(item);
+ Py_XDECREF(const_one);
+ Py_XDECREF(incremented_item);
+
+ return rv; /* -1 for error, 0 for success */
+ }
+
+.. index:: single: incr_item()
+
+.. index::
+ single: PyErr_ExceptionMatches()
+ single: PyErr_Clear()
+ single: Py_XDECREF()
+
+This example represents an endorsed use of the :keyword:`goto` statement in C!
+It illustrates the use of :cfunc:`PyErr_ExceptionMatches` and
+:cfunc:`PyErr_Clear` to handle specific exceptions, and the use of
+:cfunc:`Py_XDECREF` to dispose of owned references that may be *NULL* (note the
+``'X'`` in the name; :cfunc:`Py_DECREF` would crash when confronted with a
+*NULL* reference). It is important that the variables used to hold owned
+references are initialized to *NULL* for this to work; likewise, the proposed
+return value is initialized to ``-1`` (failure) and only set to success after
+the final call made is successful.
+
+
+.. _api-embedding:
+
+Embedding Python
+================
+
+The one important task that only embedders (as opposed to extension writers) of
+the Python interpreter have to worry about is the initialization, and possibly
+the finalization, of the Python interpreter. Most functionality of the
+interpreter can only be used after the interpreter has been initialized.
+
+.. index::
+ single: Py_Initialize()
+ module: __builtin__
+ module: __main__
+ module: sys
+ module: exceptions
+ triple: module; search; path
+ single: path (in module sys)
+
+The basic initialization function is :cfunc:`Py_Initialize`. This initializes
+the table of loaded modules, and creates the fundamental modules
+:mod:`__builtin__`, :mod:`__main__`, :mod:`sys`, and :mod:`exceptions`. It also
+initializes the module search path (``sys.path``).
+
+.. index:: single: PySys_SetArgv()
+
+:cfunc:`Py_Initialize` does not set the "script argument list" (``sys.argv``).
+If this variable is needed by Python code that will be executed later, it must
+be set explicitly with a call to ``PySys_SetArgv(argc, argv)`` subsequent to
+the call to :cfunc:`Py_Initialize`.
+
+On most systems (in particular, on Unix and Windows, although the details are
+slightly different), :cfunc:`Py_Initialize` calculates the module search path
+based upon its best guess for the location of the standard Python interpreter
+executable, assuming that the Python library is found in a fixed location
+relative to the Python interpreter executable. In particular, it looks for a
+directory named :file:`lib/python{X.Y}` relative to the parent directory
+where the executable named :file:`python` is found on the shell command search
+path (the environment variable :envvar:`PATH`).
+
+For instance, if the Python executable is found in
+:file:`/usr/local/bin/python`, it will assume that the libraries are in
+:file:`/usr/local/lib/python{X.Y}`. (In fact, this particular path is also
+the "fallback" location, used when no executable file named :file:`python` is
+found along :envvar:`PATH`.) The user can override this behavior by setting the
+environment variable :envvar:`PYTHONHOME`, or insert additional directories in
+front of the standard path by setting :envvar:`PYTHONPATH`.
+
+.. index::
+ single: Py_SetProgramName()
+ single: Py_GetPath()
+ single: Py_GetPrefix()
+ single: Py_GetExecPrefix()
+ single: Py_GetProgramFullPath()
+
+The embedding application can steer the search by calling
+``Py_SetProgramName(file)`` *before* calling :cfunc:`Py_Initialize`. Note that
+:envvar:`PYTHONHOME` still overrides this and :envvar:`PYTHONPATH` is still
+inserted in front of the standard path. An application that requires total
+control has to provide its own implementation of :cfunc:`Py_GetPath`,
+:cfunc:`Py_GetPrefix`, :cfunc:`Py_GetExecPrefix`, and
+:cfunc:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`).
+
+.. index:: single: Py_IsInitialized()
+
+Sometimes, it is desirable to "uninitialize" Python. For instance, the
+application may want to start over (make another call to
+:cfunc:`Py_Initialize`) or the application is simply done with its use of
+Python and wants to free memory allocated by Python. This can be accomplished
+by calling :cfunc:`Py_Finalize`. The function :cfunc:`Py_IsInitialized` returns
+true if Python is currently in the initialized state. More information about
+these functions is given in a later chapter. Notice that :cfunc:`Py_Finalize`
+does *not* free all memory allocated by the Python interpreter, e.g. memory
+allocated by extension modules currently cannot be released.
+
+
+.. _api-debugging:
+
+Debugging Builds
+================
+
+Python can be built with several macros to enable extra checks of the
+interpreter and extension modules. These checks tend to add a large amount of
+overhead to the runtime so they are not enabled by default.
+
+A full list of the various types of debugging builds is in the file
+:file:`Misc/SpecialBuilds.txt` in the Python source distribution. Builds are
+available that support tracing of reference counts, debugging the memory
+allocator, or low-level profiling of the main interpreter loop. Only the most
+frequently-used builds will be described in the remainder of this section.
+
+Compiling the interpreter with the :cmacro:`Py_DEBUG` macro defined produces
+what is generally meant by "a debug build" of Python. :cmacro:`Py_DEBUG` is
+enabled in the Unix build by adding :option:`--with-pydebug` to the
+:file:`configure` command. It is also implied by the presence of the
+not-Python-specific :cmacro:`_DEBUG` macro. When :cmacro:`Py_DEBUG` is enabled
+in the Unix build, compiler optimization is disabled.
+
+In addition to the reference count debugging described below, the following
+extra checks are performed:
+
+* Extra checks are added to the object allocator.
+
+* Extra checks are added to the parser and compiler.
+
+* Downcasts from wide types to narrow types are checked for loss of information.
+
+* A number of assertions are added to the dictionary and set implementations.
+ In addition, the set object acquires a :meth:`test_c_api` method.
+
+* Sanity checks of the input arguments are added to frame creation.
+
+* The storage for long ints is initialized with a known invalid pattern to catch
+ reference to uninitialized digits.
+
+* Low-level tracing and extra exception checking are added to the runtime
+ virtual machine.
+
+* Extra checks are added to the memory arena implementation.
+
+* Extra debugging is added to the thread module.
+
+There may be additional checks not mentioned here.
+
+Defining :cmacro:`Py_TRACE_REFS` enables reference tracing. When defined, a
+circular doubly linked list of active objects is maintained by adding two extra
+fields to every :ctype:`PyObject`. Total allocations are tracked as well. Upon
+exit, all existing references are printed. (In interactive mode this happens
+after every statement run by the interpreter.) Implied by :cmacro:`Py_DEBUG`.
+
+Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source distribution
+for more detailed information.
+
--- /dev/null
+.. highlightlang:: c
+
+
+.. _memory:
+
+*****************
+Memory Management
+*****************
+
+.. sectionauthor:: Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>
+
+
+
+.. _memoryoverview:
+
+Overview
+========
+
+Memory management in Python involves a private heap containing all Python
+objects and data structures. The management of this private heap is ensured
+internally by the *Python memory manager*. The Python memory manager has
+different components which deal with various dynamic storage management aspects,
+like sharing, segmentation, preallocation or caching.
+
+At the lowest level, a raw memory allocator ensures that there is enough room in
+the private heap for storing all Python-related data by interacting with the
+memory manager of the operating system. On top of the raw memory allocator,
+several object-specific allocators operate on the same heap and implement
+distinct memory management policies adapted to the peculiarities of every object
+type. For example, integer objects are managed differently within the heap than
+strings, tuples or dictionaries because integers imply different storage
+requirements and speed/space tradeoffs. The Python memory manager thus delegates
+some of the work to the object-specific allocators, but ensures that the latter
+operate within the bounds of the private heap.
+
+It is important to understand that the management of the Python heap is
+performed by the interpreter itself and that the user has no control over it,
+even if she regularly manipulates object pointers to memory blocks inside that
+heap. The allocation of heap space for Python objects and other internal
+buffers is performed on demand by the Python memory manager through the Python/C
+API functions listed in this document.
+
+.. index::
+ single: malloc()
+ single: calloc()
+ single: realloc()
+ single: free()
+
+To avoid memory corruption, extension writers should never try to operate on
+Python objects with the functions exported by the C library: :cfunc:`malloc`,
+:cfunc:`calloc`, :cfunc:`realloc` and :cfunc:`free`. This will result in mixed
+calls between the C allocator and the Python memory manager with fatal
+consequences, because they implement different algorithms and operate on
+different heaps. However, one may safely allocate and release memory blocks
+with the C library allocator for individual purposes, as shown in the following
+example::
+
+ PyObject *res;
+ char *buf = (char *) malloc(BUFSIZ); /* for I/O */
+
+ if (buf == NULL)
+ return PyErr_NoMemory();
+ ...Do some I/O operation involving buf...
+ res = PyString_FromString(buf);
+ free(buf); /* malloc'ed */
+ return res;
+
+In this example, the memory request for the I/O buffer is handled by the C
+library allocator. The Python memory manager is involved only in the allocation
+of the string object returned as a result.
+
+In most situations, however, it is recommended to allocate memory from the
+Python heap specifically because the latter is under control of the Python
+memory manager. For example, this is required when the interpreter is extended
+with new object types written in C. Another reason for using the Python heap is
+the desire to *inform* the Python memory manager about the memory needs of the
+extension module. Even when the requested memory is used exclusively for
+internal, highly-specific purposes, delegating all memory requests to the Python
+memory manager causes the interpreter to have a more accurate image of its
+memory footprint as a whole. Consequently, under certain circumstances, the
+Python memory manager may or may not trigger appropriate actions, like garbage
+collection, memory compaction or other preventive procedures. Note that by using
+the C library allocator as shown in the previous example, the allocated memory
+for the I/O buffer escapes completely the Python memory manager.
+
+
+.. _memoryinterface:
+
+Memory Interface
+================
+
+The following function sets, modeled after the ANSI C standard, but specifying
+behavior when requesting zero bytes, are available for allocating and releasing
+memory from the Python heap:
+
+
+.. cfunction:: void* PyMem_Malloc(size_t n)
+
+ Allocates *n* bytes and returns a pointer of type :ctype:`void\*` to the
+ allocated memory, or *NULL* if the request fails. Requesting zero bytes returns
+ a distinct non-*NULL* pointer if possible, as if :cfunc:`PyMem_Malloc(1)` had
+ been called instead. The memory will not have been initialized in any way.
+
+
+.. cfunction:: void* PyMem_Realloc(void *p, size_t n)
+
+ Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
+ unchanged to the minimum of the old and the new sizes. If *p* is *NULL*, the
+ call is equivalent to :cfunc:`PyMem_Malloc(n)`; else if *n* is equal to zero,
+ the memory block is resized but is not freed, and the returned pointer is
+ non-*NULL*. Unless *p* is *NULL*, it must have been returned by a previous call
+ to :cfunc:`PyMem_Malloc` or :cfunc:`PyMem_Realloc`. If the request fails,
+ :cfunc:`PyMem_Realloc` returns *NULL* and *p* remains a valid pointer to the
+ previous memory area.
+
+
+.. cfunction:: void PyMem_Free(void *p)
+
+ Frees the memory block pointed to by *p*, which must have been returned by a
+ previous call to :cfunc:`PyMem_Malloc` or :cfunc:`PyMem_Realloc`. Otherwise, or
+ if :cfunc:`PyMem_Free(p)` has been called before, undefined behavior occurs. If
+ *p* is *NULL*, no operation is performed.
+
+The following type-oriented macros are provided for convenience. Note that
+*TYPE* refers to any C type.
+
+
+.. cfunction:: TYPE* PyMem_New(TYPE, size_t n)
+
+ Same as :cfunc:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of
+ memory. Returns a pointer cast to :ctype:`TYPE\*`. The memory will not have
+ been initialized in any way.
+
+
+.. cfunction:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)
+
+ Same as :cfunc:`PyMem_Realloc`, but the memory block is resized to ``(n *
+ sizeof(TYPE))`` bytes. Returns a pointer cast to :ctype:`TYPE\*`. On return,
+ *p* will be a pointer to the new memory area, or *NULL* in the event of failure.
+
+
+.. cfunction:: void PyMem_Del(void *p)
+
+ Same as :cfunc:`PyMem_Free`.
+
+In addition, the following macro sets are provided for calling the Python memory
+allocator directly, without involving the C API functions listed above. However,
+note that their use does not preserve binary compatibility across Python
+versions and is therefore deprecated in extension modules.
+
+:cfunc:`PyMem_MALLOC`, :cfunc:`PyMem_REALLOC`, :cfunc:`PyMem_FREE`.
+
+:cfunc:`PyMem_NEW`, :cfunc:`PyMem_RESIZE`, :cfunc:`PyMem_DEL`.
+
+
+.. _memoryexamples:
+
+Examples
+========
+
+Here is the example from section :ref:`memoryoverview`, rewritten so that the
+I/O buffer is allocated from the Python heap by using the first function set::
+
+ PyObject *res;
+ char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */
+
+ if (buf == NULL)
+ return PyErr_NoMemory();
+ /* ...Do some I/O operation involving buf... */
+ res = PyString_FromString(buf);
+ PyMem_Free(buf); /* allocated with PyMem_Malloc */
+ return res;
+
+The same code using the type-oriented function set::
+
+ PyObject *res;
+ char *buf = PyMem_New(char, BUFSIZ); /* for I/O */
+
+ if (buf == NULL)
+ return PyErr_NoMemory();
+ /* ...Do some I/O operation involving buf... */
+ res = PyString_FromString(buf);
+ PyMem_Del(buf); /* allocated with PyMem_New */
+ return res;
+
+Note that in the two examples above, the buffer is always manipulated via
+functions belonging to the same set. Indeed, it is required to use the same
+memory API family for a given memory block, so that the risk of mixing different
+allocators is reduced to a minimum. The following code sequence contains two
+errors, one of which is labeled as *fatal* because it mixes two different
+allocators operating on different heaps. ::
+
+ char *buf1 = PyMem_New(char, BUFSIZ);
+ char *buf2 = (char *) malloc(BUFSIZ);
+ char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
+ ...
+ PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */
+ free(buf2); /* Right -- allocated via malloc() */
+ free(buf1); /* Fatal -- should be PyMem_Del() */
+
+In addition to the functions aimed at handling raw memory blocks from the Python
+heap, objects in Python are allocated and released with :cfunc:`PyObject_New`,
+:cfunc:`PyObject_NewVar` and :cfunc:`PyObject_Del`.
+
+These will be explained in the next chapter on defining and implementing new
+object types in C.
+
--- /dev/null
+.. highlightlang:: c
+
+
+.. _newtypes:
+
+*****************************
+Object Implementation Support
+*****************************
+
+This chapter describes the functions, types, and macros used when defining new
+object types.
+
+
+.. _allocating-objects:
+
+Allocating Objects on the Heap
+==============================
+
+
+.. cfunction:: PyObject* _PyObject_New(PyTypeObject *type)
+
+
+.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
+
+
+.. 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.
+
+
+.. 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.
+
+
+.. 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.
+
+
+.. _common-structs:
+
+Common Object Structures
+========================
+
+There are a large number of structures which are used in the definition of
+object types for Python. This section describes these structures and how they
+are used.
+
+All Python objects ultimately share a small number of fields at the beginning of
+the object's representation in memory. These are represented by the
+:ctype:`PyObject` and :ctype:`PyVarObject` types, which are defined, in turn, by
+the expansions of some macros also used, whether directly or indirectly, in the
+definition of all other Python objects.
+
+
+.. ctype:: PyObject
+
+ All object types are extensions of this type. This is a type which contains the
+ information Python needs to treat a pointer to an object as an object. In a
+ normal "release" build, it contains only the objects reference count and a
+ pointer to the corresponding type object. It corresponds to the fields defined
+ by the expansion of the ``PyObject_HEAD`` macro.
+
+
+.. ctype:: PyVarObject
+
+ This is an extension of :ctype:`PyObject` that adds the :attr:`ob_size` field.
+ This is only used for objects that have some notion of *length*. This type does
+ not often appear in the Python/C API. It corresponds to the fields defined by
+ the expansion of the ``PyObject_VAR_HEAD`` macro.
+
+These macros are used in the definition of :ctype:`PyObject` and
+:ctype:`PyVarObject`:
+
+
+.. cmacro:: PyObject_HEAD
+
+ This is a macro which expands to the declarations of the fields of the
+ :ctype:`PyObject` type; it is used when declaring new types which represent
+ objects without a varying length. The specific fields it expands to depend on
+ the definition of :cmacro:`Py_TRACE_REFS`. By default, that macro is not
+ defined, and :cmacro:`PyObject_HEAD` expands to::
+
+ Py_ssize_t ob_refcnt;
+ PyTypeObject *ob_type;
+
+ When :cmacro:`Py_TRACE_REFS` is defined, it expands to::
+
+ PyObject *_ob_next, *_ob_prev;
+ Py_ssize_t ob_refcnt;
+ PyTypeObject *ob_type;
+
+
+.. cmacro:: PyObject_VAR_HEAD
+
+ This is a macro which expands to the declarations of the fields of the
+ :ctype:`PyVarObject` type; it is used when declaring new types which represent
+ objects with a length that varies from instance to instance. This macro always
+ expands to::
+
+ PyObject_HEAD
+ Py_ssize_t ob_size;
+
+ Note that :cmacro:`PyObject_HEAD` is part of the expansion, and that its own
+ expansion varies depending on the definition of :cmacro:`Py_TRACE_REFS`.
+
+PyObject_HEAD_INIT
+
+
+.. ctype:: PyCFunction
+
+ Type of the functions used to implement most Python callables in C. Functions of
+ this type take two :ctype:`PyObject\*` parameters and return one such value. If
+ the return value is *NULL*, an exception shall have been set. If not *NULL*,
+ the return value is interpreted as the return value of the function as exposed
+ in Python. The function must return a new reference.
+
+
+.. ctype:: PyMethodDef
+
+ Structure used to describe a method of an extension type. This structure has
+ four fields:
+
+ +------------------+-------------+-------------------------------+
+ | Field | C Type | Meaning |
+ +==================+=============+===============================+
+ | :attr:`ml_name` | char \* | name of the method |
+ +------------------+-------------+-------------------------------+
+ | :attr:`ml_meth` | PyCFunction | pointer to the C |
+ | | | implementation |
+ +------------------+-------------+-------------------------------+
+ | :attr:`ml_flags` | int | flag bits indicating how the |
+ | | | call should be constructed |
+ +------------------+-------------+-------------------------------+
+ | :attr:`ml_doc` | char \* | points to the contents of the |
+ | | | docstring |
+ +------------------+-------------+-------------------------------+
+
+The :attr:`ml_meth` is a C function pointer. The functions may be of different
+types, but they always return :ctype:`PyObject\*`. If the function is not of
+the :ctype:`PyCFunction`, the compiler will require a cast in the method table.
+Even though :ctype:`PyCFunction` defines the first parameter as
+:ctype:`PyObject\*`, it is common that the method implementation uses a the
+specific C type of the *self* object.
+
+The :attr:`ml_flags` field is a bitfield which can include the following flags.
+The individual flags indicate either a calling convention or a binding
+convention. Of the calling convention flags, only :const:`METH_VARARGS` and
+:const:`METH_KEYWORDS` can be combined (but note that :const:`METH_KEYWORDS`
+alone is equivalent to ``METH_VARARGS | METH_KEYWORDS``). Any of the calling
+convention flags can be combined with a binding flag.
+
+
+.. data:: METH_VARARGS
+
+ This is the typical calling convention, where the methods have the type
+ :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values. The
+ first one is the *self* object for methods; for module functions, it has the
+ value given to :cfunc:`Py_InitModule4` (or *NULL* if :cfunc:`Py_InitModule` was
+ used). The second parameter (often called *args*) is a tuple object
+ representing all arguments. This parameter is typically processed using
+ :cfunc:`PyArg_ParseTuple` or :cfunc:`PyArg_UnpackTuple`.
+
+
+.. data:: METH_KEYWORDS
+
+ Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`. The
+ function expects three parameters: *self*, *args*, and a dictionary of all the
+ keyword arguments. The flag is typically combined with :const:`METH_VARARGS`,
+ and the parameters are typically processed using
+ :cfunc:`PyArg_ParseTupleAndKeywords`.
+
+
+.. data:: METH_NOARGS
+
+ Methods without parameters don't need to check whether arguments are given if
+ they are listed with the :const:`METH_NOARGS` flag. They need to be of type
+ :ctype:`PyCFunction`. When used with object methods, the first parameter is
+ typically named ``self`` and will hold a reference to the object instance. In
+ all cases the second parameter will be *NULL*.
+
+
+.. data:: METH_O
+
+ Methods with a single object argument can be listed with the :const:`METH_O`
+ flag, instead of invoking :cfunc:`PyArg_ParseTuple` with a ``"O"`` argument.
+ They have the type :ctype:`PyCFunction`, with the *self* parameter, and a
+ :ctype:`PyObject\*` parameter representing the single argument.
+
+
+.. data:: METH_OLDARGS
+
+ This calling convention is deprecated. The method must be of type
+ :ctype:`PyCFunction`. The second argument is *NULL* if no arguments are given,
+ a single object if exactly one argument is given, and a tuple of objects if more
+ than one argument is given. There is no way for a function using this
+ convention to distinguish between a call with multiple arguments and a call with
+ a tuple as the only argument.
+
+These two constants are not used to indicate the calling convention but the
+binding when use with methods of classes. These may not be used for functions
+defined for modules. At most one of these flags may be set for any given
+method.
+
+
+.. data:: METH_CLASS
+
+ .. index:: builtin: classmethod
+
+ The method will be passed the type object as the first parameter rather than an
+ instance of the type. This is used to create *class methods*, similar to what
+ is created when using the :func:`classmethod` built-in function.
+
+ .. versionadded:: 2.3
+
+
+.. data:: METH_STATIC
+
+ .. index:: builtin: staticmethod
+
+ The method will be passed *NULL* as the first parameter rather than an instance
+ of the type. This is used to create *static methods*, similar to what is
+ created when using the :func:`staticmethod` built-in function.
+
+ .. versionadded:: 2.3
+
+One other constant controls whether a method is loaded in place of another
+definition with the same method name.
+
+
+.. data:: METH_COEXIST
+
+ The method will be loaded in place of existing definitions. Without
+ *METH_COEXIST*, the default is to skip repeated definitions. Since slot
+ wrappers are loaded before the method table, the existence of a *sq_contains*
+ slot, for example, would generate a wrapped method named :meth:`__contains__`
+ and preclude the loading of a corresponding PyCFunction with the same name.
+ With the flag defined, the PyCFunction will be loaded in place of the wrapper
+ object and will co-exist with the slot. This is helpful because calls to
+ PyCFunctions are optimized more than wrapper object calls.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name)
+
+ Return a bound method object for an extension type implemented in C. This can
+ be useful in the implementation of a :attr:`tp_getattro` or :attr:`tp_getattr`
+ handler that does not use the :cfunc:`PyObject_GenericGetAttr` function.
+
+
+.. _type-structs:
+
+Type Objects
+============
+
+Perhaps one of the most important structures of the Python object system is the
+structure that defines a new type: the :ctype:`PyTypeObject` structure. Type
+objects can be handled using any of the :cfunc:`PyObject_\*` or
+:cfunc:`PyType_\*` functions, but do not offer much that's interesting to most
+Python applications. These objects are fundamental to how objects behave, so
+they are very important to the interpreter itself and to any extension module
+that implements new types.
+
+Type objects are fairly large compared to most of the standard types. The reason
+for the size is that each type object stores a large number of values, mostly C
+function pointers, each of which implements a small part of the type's
+functionality. The fields of the type object are examined in detail in this
+section. The fields will be described in the order in which they occur in the
+structure.
+
+Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
+intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor,
+freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc,
+cmpfunc, reprfunc, hashfunc
+
+The structure definition for :ctype:`PyTypeObject` can be found in
+:file:`Include/object.h`. For convenience of reference, this repeats the
+definition found there:
+
+.. literalinclude:: ../includes/typestruct.h
+
+
+The type object structure extends the :ctype:`PyVarObject` structure. The
+:attr:`ob_size` field is used for dynamic types (created by :func:`type_new`,
+usually called from a class statement). Note that :cdata:`PyType_Type` (the
+metatype) initializes :attr:`tp_itemsize`, which means that its instances (i.e.
+type objects) *must* have the :attr:`ob_size` field.
+
+
+.. cmember:: PyObject* PyObject._ob_next
+ PyObject* PyObject._ob_prev
+
+ These fields are only present when the macro ``Py_TRACE_REFS`` is defined.
+ Their initialization to *NULL* is taken care of by the ``PyObject_HEAD_INIT``
+ macro. For statically allocated objects, these fields always remain *NULL*.
+ For dynamically allocated objects, these two fields are used to link the object
+ into a doubly-linked list of *all* live objects on the heap. This could be used
+ for various debugging purposes; currently the only use is to print the objects
+ that are still alive at the end of a run when the environment variable
+ :envvar:`PYTHONDUMPREFS` is set.
+
+ These fields are not inherited by subtypes.
+
+
+.. cmember:: Py_ssize_t PyObject.ob_refcnt
+
+ This is the type object's reference count, initialized to ``1`` by the
+ ``PyObject_HEAD_INIT`` macro. Note that for statically allocated type objects,
+ the type's instances (objects whose :attr:`ob_type` points back to the type) do
+ *not* count as references. But for dynamically allocated type objects, the
+ instances *do* count as references.
+
+ This field is not inherited by subtypes.
+
+
+.. cmember:: PyTypeObject* PyObject.ob_type
+
+ This is the type's type, in other words its metatype. It is initialized by the
+ argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be
+ ``&PyType_Type``. However, for dynamically loadable extension modules that must
+ be usable on Windows (at least), the compiler complains that this is not a valid
+ initializer. Therefore, the convention is to pass *NULL* to the
+ ``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the
+ start of the module's initialization function, before doing anything else. This
+ is typically done like this::
+
+ Foo_Type.ob_type = &PyType_Type;
+
+ This should be done before any instances of the type are created.
+ :cfunc:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so,
+ initializes it: in Python 2.2, it is set to ``&PyType_Type``; in Python 2.2.1
+ and later it is initialized to the :attr:`ob_type` field of the base class.
+ :cfunc:`PyType_Ready` will not change this field if it is non-zero.
+
+ In Python 2.2, this field is not inherited by subtypes. In 2.2.1, and in 2.3
+ and beyond, it is inherited by subtypes.
+
+
+.. cmember:: Py_ssize_t PyVarObject.ob_size
+
+ For statically allocated type objects, this should be initialized to zero. For
+ dynamically allocated type objects, this field has a special internal meaning.
+
+ This field is not inherited by subtypes.
+
+
+.. cmember:: char* PyTypeObject.tp_name
+
+ Pointer to a NUL-terminated string containing the name of the type. For types
+ that are accessible as module globals, the string should be the full module
+ name, followed by a dot, followed by the type name; for built-in types, it
+ should be just the type name. If the module is a submodule of a package, the
+ full package name is part of the full module name. For example, a type named
+ :class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P`
+ should have the :attr:`tp_name` initializer ``"P.Q.M.T"``.
+
+ For dynamically allocated type objects, this should just be the type name, and
+ the module name explicitly stored in the type dict as the value for key
+ ``'__module__'``.
+
+ For statically allocated type objects, the tp_name field should contain a dot.
+ Everything before the last dot is made accessible as the :attr:`__module__`
+ attribute, and everything after the last dot is made accessible as the
+ :attr:`__name__` attribute.
+
+ If no dot is present, the entire :attr:`tp_name` field is made accessible as the
+ :attr:`__name__` attribute, and the :attr:`__module__` attribute is undefined
+ (unless explicitly set in the dictionary, as explained above). This means your
+ type will be impossible to pickle.
+
+ This field is not inherited by subtypes.
+
+
+.. cmember:: Py_ssize_t PyTypeObject.tp_basicsize
+ Py_ssize_t PyTypeObject.tp_itemsize
+
+ These fields allow calculating the size in bytes of instances of the type.
+
+ There are two kinds of types: types with fixed-length instances have a zero
+ :attr:`tp_itemsize` field, types with variable-length instances have a non-zero
+ :attr:`tp_itemsize` field. For a type with fixed-length instances, all
+ instances have the same size, given in :attr:`tp_basicsize`.
+
+ For a type with variable-length instances, the instances must have an
+ :attr:`ob_size` field, and the instance size is :attr:`tp_basicsize` plus N
+ times :attr:`tp_itemsize`, where N is the "length" of the object. The value of
+ N is typically stored in the instance's :attr:`ob_size` field. There are
+ exceptions: for example, long ints use a negative :attr:`ob_size` to indicate a
+ negative number, and N is ``abs(ob_size)`` there. Also, the presence of an
+ :attr:`ob_size` field in the instance layout doesn't mean that the instance
+ structure is variable-length (for example, the structure for the list type has
+ fixed-length instances, yet those instances have a meaningful :attr:`ob_size`
+ field).
+
+ The basic size includes the fields in the instance declared by the macro
+ :cmacro:`PyObject_HEAD` or :cmacro:`PyObject_VAR_HEAD` (whichever is used to
+ declare the instance struct) and this in turn includes the :attr:`_ob_prev` and
+ :attr:`_ob_next` fields if they are present. This means that the only correct
+ way to get an initializer for the :attr:`tp_basicsize` is to use the
+ :keyword:`sizeof` operator on the struct used to declare the instance layout.
+ The basic size does not include the GC header size (this is new in Python 2.2;
+ in 2.1 and 2.0, the GC header size was included in :attr:`tp_basicsize`).
+
+ These fields are inherited separately by subtypes. If the base type has a
+ non-zero :attr:`tp_itemsize`, it is generally not safe to set
+ :attr:`tp_itemsize` to a different non-zero value in a subtype (though this
+ depends on the implementation of the base type).
+
+ A note about alignment: if the variable items require a particular alignment,
+ this should be taken care of by the value of :attr:`tp_basicsize`. Example:
+ suppose a type implements an array of ``double``. :attr:`tp_itemsize` is
+ ``sizeof(double)``. It is the programmer's responsibility that
+ :attr:`tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the
+ alignment requirement for ``double``).
+
+
+.. cmember:: destructor PyTypeObject.tp_dealloc
+
+ A pointer to the instance destructor function. This function must be defined
+ unless the type guarantees that its instances will never be deallocated (as is
+ the case for the singletons ``None`` and ``Ellipsis``).
+
+ The destructor function is called by the :cfunc:`Py_DECREF` and
+ :cfunc:`Py_XDECREF` macros when the new reference count is zero. At this point,
+ the instance is still in existence, but there are no references to it. The
+ destructor function should free all references which the instance owns, free all
+ memory buffers owned by the instance (using the freeing function corresponding
+ to the allocation function used to allocate the buffer), and finally (as its
+ last action) call the type's :attr:`tp_free` function. If the type is not
+ subtypable (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is
+ permissible to call the object deallocator directly instead of via
+ :attr:`tp_free`. The object deallocator should be the one used to allocate the
+ instance; this is normally :cfunc:`PyObject_Del` if the instance was allocated
+ using :cfunc:`PyObject_New` or :cfunc:`PyObject_VarNew`, or
+ :cfunc:`PyObject_GC_Del` if the instance was allocated using
+ :cfunc:`PyObject_GC_New` or :cfunc:`PyObject_GC_VarNew`.
+
+ This field is inherited by subtypes.
+
+
+.. cmember:: printfunc PyTypeObject.tp_print
+
+ An optional pointer to the instance print function.
+
+ The print function is only called when the instance is printed to a *real* file;
+ when it is printed to a pseudo-file (like a :class:`StringIO` instance), the
+ instance's :attr:`tp_repr` or :attr:`tp_str` function is called to convert it to
+ a string. These are also called when the type's :attr:`tp_print` field is
+ *NULL*. A type should never implement :attr:`tp_print` in a way that produces
+ different output than :attr:`tp_repr` or :attr:`tp_str` would.
+
+ The print function is called with the same signature as :cfunc:`PyObject_Print`:
+ ``int tp_print(PyObject *self, FILE *file, int flags)``. The *self* argument is
+ the instance to be printed. The *file* argument is the stdio file to which it
+ is to be printed. The *flags* argument is composed of flag bits. The only flag
+ bit currently defined is :const:`Py_PRINT_RAW`. When the :const:`Py_PRINT_RAW`
+ flag bit is set, the instance should be printed the same way as :attr:`tp_str`
+ would format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance
+ should be printed the same was as :attr:`tp_repr` would format it. It should
+ return ``-1`` and set an exception condition when an error occurred during the
+ comparison.
+
+ It is possible that the :attr:`tp_print` field will be deprecated. In any case,
+ it is recommended not to define :attr:`tp_print`, but instead to rely on
+ :attr:`tp_repr` and :attr:`tp_str` for printing.
+
+ This field is inherited by subtypes.
+
+
+.. cmember:: getattrfunc PyTypeObject.tp_getattr
+
+ An optional pointer to the get-attribute-string function.
+
+ This field is deprecated. When it is defined, it should point to a function
+ that acts the same as the :attr:`tp_getattro` function, but taking a C string
+ instead of a Python string object to give the attribute name. The signature is
+ the same as for :cfunc:`PyObject_GetAttrString`.
+
+ This field is inherited by subtypes together with :attr:`tp_getattro`: a subtype
+ inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when
+ the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*.
+
+
+.. cmember:: setattrfunc PyTypeObject.tp_setattr
+
+ An optional pointer to the set-attribute-string function.
+
+ This field is deprecated. When it is defined, it should point to a function
+ that acts the same as the :attr:`tp_setattro` function, but taking a C string
+ instead of a Python string object to give the attribute name. The signature is
+ the same as for :cfunc:`PyObject_SetAttrString`.
+
+ This field is inherited by subtypes together with :attr:`tp_setattro`: a subtype
+ inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when
+ the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*.
+
+
+.. cmember:: cmpfunc PyTypeObject.tp_compare
+
+ An optional pointer to the three-way comparison function.
+
+ The signature is the same as for :cfunc:`PyObject_Compare`. The function should
+ return ``1`` if *self* greater than *other*, ``0`` if *self* is equal to
+ *other*, and ``-1`` if *self* less than *other*. It should return ``-1`` and
+ set an exception condition when an error occurred during the comparison.
+
+ This field is inherited by subtypes together with :attr:`tp_richcompare` and
+ :attr:`tp_hash`: a subtypes inherits all three of :attr:`tp_compare`,
+ :attr:`tp_richcompare`, and :attr:`tp_hash` when the subtype's
+ :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*.
+
+
+.. cmember:: reprfunc PyTypeObject.tp_repr
+
+ .. index:: builtin: repr
+
+ An optional pointer to a function that implements the built-in function
+ :func:`repr`.
+
+ The signature is the same as for :cfunc:`PyObject_Repr`; it must return a string
+ or a Unicode object. Ideally, this function should return a string that, when
+ passed to :func:`eval`, given a suitable environment, returns an object with the
+ same value. If this is not feasible, it should return a string starting with
+ ``'<'`` and ending with ``'>'`` from which both the type and the value of the
+ object can be deduced.
+
+ When this field is not set, a string of the form ``<%s object at %p>`` is
+ returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's
+ memory address.
+
+ This field is inherited by subtypes.
+
+.. cmember:: PyNumberMethods *tp_as_number;
+
+ XXX
+
+.. cmember:: PySequenceMethods *tp_as_sequence;
+
+ XXX
+
+.. cmember:: PyMappingMethods *tp_as_mapping;
+
+ XXX
+
+
+.. cmember:: hashfunc PyTypeObject.tp_hash
+
+ .. index:: builtin: hash
+
+ An optional pointer to a function that implements the built-in function
+ :func:`hash`.
+
+ The signature is the same as for :cfunc:`PyObject_Hash`; it must return a C
+ long. The value ``-1`` should not be returned as a normal return value; when an
+ error occurs during the computation of the hash value, the function should set
+ an exception and return ``-1``.
+
+ When this field is not set, two possibilities exist: if the :attr:`tp_compare`
+ and :attr:`tp_richcompare` fields are both *NULL*, a default hash value based on
+ the object's address is returned; otherwise, a :exc:`TypeError` is raised.
+
+ This field is inherited by subtypes together with :attr:`tp_richcompare` and
+ :attr:`tp_compare`: a subtypes inherits all three of :attr:`tp_compare`,
+ :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's
+ :attr:`tp_compare`, :attr:`tp_richcompare` and :attr:`tp_hash` are all *NULL*.
+
+
+.. cmember:: ternaryfunc PyTypeObject.tp_call
+
+ An optional pointer to a function that implements calling the object. This
+ should be *NULL* if the object is not callable. The signature is the same as
+ for :cfunc:`PyObject_Call`.
+
+ This field is inherited by subtypes.
+
+
+.. cmember:: reprfunc PyTypeObject.tp_str
+
+ An optional pointer to a function that implements the built-in operation
+ :func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls the
+ constructor for that type. This constructor calls :cfunc:`PyObject_Str` to do
+ the actual work, and :cfunc:`PyObject_Str` will call this handler.)
+
+ The signature is the same as for :cfunc:`PyObject_Str`; it must return a string
+ or a Unicode object. This function should return a "friendly" string
+ representation of the object, as this is the representation that will be used by
+ the print statement.
+
+ When this field is not set, :cfunc:`PyObject_Repr` is called to return a string
+ representation.
+
+ This field is inherited by subtypes.
+
+
+.. cmember:: getattrofunc PyTypeObject.tp_getattro
+
+ An optional pointer to the get-attribute function.
+
+ The signature is the same as for :cfunc:`PyObject_GetAttr`. It is usually
+ convenient to set this field to :cfunc:`PyObject_GenericGetAttr`, which
+ implements the normal way of looking for object attributes.
+
+ This field is inherited by subtypes together with :attr:`tp_getattr`: a subtype
+ inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when
+ the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*.
+
+
+.. cmember:: setattrofunc PyTypeObject.tp_setattro
+
+ An optional pointer to the set-attribute function.
+
+ The signature is the same as for :cfunc:`PyObject_SetAttr`. It is usually
+ convenient to set this field to :cfunc:`PyObject_GenericSetAttr`, which
+ implements the normal way of setting object attributes.
+
+ This field is inherited by subtypes together with :attr:`tp_setattr`: a subtype
+ inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when
+ the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*.
+
+
+.. cmember:: PyBufferProcs* PyTypeObject.tp_as_buffer
+
+ Pointer to an additional structure that contains fields relevant only to objects
+ which implement the buffer interface. These fields are documented in
+ :ref:`buffer-structs`.
+
+ The :attr:`tp_as_buffer` field is not inherited, but the contained fields are
+ inherited individually.
+
+
+.. cmember:: long PyTypeObject.tp_flags
+
+ This field is a bit mask of various flags. Some flags indicate variant
+ semantics for certain situations; others are used to indicate that certain
+ fields in the type object (or in the extension structures referenced via
+ :attr:`tp_as_number`, :attr:`tp_as_sequence`, :attr:`tp_as_mapping`, and
+ :attr:`tp_as_buffer`) that were historically not always present are valid; if
+ such a flag bit is clear, the type fields it guards must not be accessed and
+ must be considered to have a zero or *NULL* value instead.
+
+ Inheritance of this field is complicated. Most flag bits are inherited
+ individually, i.e. if the base type has a flag bit set, the subtype inherits
+ this flag bit. The flag bits that pertain to extension structures are strictly
+ inherited if the extension structure is inherited, i.e. the base type's value of
+ the flag bit is copied into the subtype together with a pointer to the extension
+ structure. The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with
+ the :attr:`tp_traverse` and :attr:`tp_clear` fields, i.e. if the
+ :const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the
+ :attr:`tp_traverse` and :attr:`tp_clear` fields in the subtype exist (as
+ indicated by the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit) and have *NULL*
+ values.
+
+ The following bit masks are currently defined; these can be or-ed together using
+ the ``|`` operator to form the value of the :attr:`tp_flags` field. The macro
+ :cfunc:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and
+ checks whether ``tp->tp_flags & f`` is non-zero.
+
+
+ .. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
+
+ If this bit is set, the :ctype:`PyBufferProcs` struct referenced by
+ :attr:`tp_as_buffer` has the :attr:`bf_getcharbuffer` field.
+
+
+ .. data:: Py_TPFLAGS_HAVE_SEQUENCE_IN
+
+ If this bit is set, the :ctype:`PySequenceMethods` struct referenced by
+ :attr:`tp_as_sequence` has the :attr:`sq_contains` field.
+
+
+ .. data:: Py_TPFLAGS_GC
+
+ This bit is obsolete. The bit it used to name is no longer in use. The symbol
+ is now defined as zero.
+
+
+ .. data:: Py_TPFLAGS_HAVE_INPLACEOPS
+
+ If this bit is set, the :ctype:`PySequenceMethods` struct referenced by
+ :attr:`tp_as_sequence` and the :ctype:`PyNumberMethods` structure referenced by
+ :attr:`tp_as_number` contain the fields for in-place operators. In particular,
+ this means that the :ctype:`PyNumberMethods` structure has the fields
+ :attr:`nb_inplace_add`, :attr:`nb_inplace_subtract`,
+ :attr:`nb_inplace_multiply`, :attr:`nb_inplace_divide`,
+ :attr:`nb_inplace_remainder`, :attr:`nb_inplace_power`,
+ :attr:`nb_inplace_lshift`, :attr:`nb_inplace_rshift`, :attr:`nb_inplace_and`,
+ :attr:`nb_inplace_xor`, and :attr:`nb_inplace_or`; and the
+ :ctype:`PySequenceMethods` struct has the fields :attr:`sq_inplace_concat` and
+ :attr:`sq_inplace_repeat`.
+
+
+ .. data:: Py_TPFLAGS_CHECKTYPES
+
+ If this bit is set, the binary and ternary operations in the
+ :ctype:`PyNumberMethods` structure referenced by :attr:`tp_as_number` accept
+ arguments of arbitrary object types, and do their own type conversions if
+ needed. If this bit is clear, those operations require that all arguments have
+ the current type as their type, and the caller is supposed to perform a coercion
+ operation first. This applies to :attr:`nb_add`, :attr:`nb_subtract`,
+ :attr:`nb_multiply`, :attr:`nb_divide`, :attr:`nb_remainder`, :attr:`nb_divmod`,
+ :attr:`nb_power`, :attr:`nb_lshift`, :attr:`nb_rshift`, :attr:`nb_and`,
+ :attr:`nb_xor`, and :attr:`nb_or`.
+
+
+ .. data:: Py_TPFLAGS_HAVE_RICHCOMPARE
+
+ If this bit is set, the type object has the :attr:`tp_richcompare` field, as
+ well as the :attr:`tp_traverse` and the :attr:`tp_clear` fields.
+
+
+ .. data:: Py_TPFLAGS_HAVE_WEAKREFS
+
+ If this bit is set, the :attr:`tp_weaklistoffset` field is defined. Instances
+ of a type are weakly referenceable if the type's :attr:`tp_weaklistoffset` field
+ has a value greater than zero.
+
+
+ .. data:: Py_TPFLAGS_HAVE_ITER
+
+ If this bit is set, the type object has the :attr:`tp_iter` and
+ :attr:`tp_iternext` fields.
+
+
+ .. data:: Py_TPFLAGS_HAVE_CLASS
+
+ If this bit is set, the type object has several new fields defined starting in
+ Python 2.2: :attr:`tp_methods`, :attr:`tp_members`, :attr:`tp_getset`,
+ :attr:`tp_base`, :attr:`tp_dict`, :attr:`tp_descr_get`, :attr:`tp_descr_set`,
+ :attr:`tp_dictoffset`, :attr:`tp_init`, :attr:`tp_alloc`, :attr:`tp_new`,
+ :attr:`tp_free`, :attr:`tp_is_gc`, :attr:`tp_bases`, :attr:`tp_mro`,
+ :attr:`tp_cache`, :attr:`tp_subclasses`, and :attr:`tp_weaklist`.
+
+
+ .. data:: Py_TPFLAGS_HEAPTYPE
+
+ This bit is set when the type object itself is allocated on the heap. In this
+ case, the :attr:`ob_type` field of its instances is considered a reference to
+ the type, and the type object is INCREF'ed when a new instance is created, and
+ DECREF'ed when an instance is destroyed (this does not apply to instances of
+ subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or
+ DECREF'ed).
+
+
+ .. data:: Py_TPFLAGS_BASETYPE
+
+ This bit is set when the type can be used as the base type of another type. If
+ this bit is clear, the type cannot be subtyped (similar to a "final" class in
+ Java).
+
+
+ .. data:: Py_TPFLAGS_READY
+
+ This bit is set when the type object has been fully initialized by
+ :cfunc:`PyType_Ready`.
+
+
+ .. data:: Py_TPFLAGS_READYING
+
+ This bit is set while :cfunc:`PyType_Ready` is in the process of initializing
+ the type object.
+
+
+ .. data:: Py_TPFLAGS_HAVE_GC
+
+ This bit is set when the object supports garbage collection. If this bit
+ is set, instances must be created using :cfunc:`PyObject_GC_New` and
+ destroyed using :cfunc:`PyObject_GC_Del`. More information in section
+ :ref:`supporting-cycle-detection`. This bit also implies that the
+ GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in
+ the type object; but those fields also exist when
+ :const:`Py_TPFLAGS_HAVE_GC` is clear but
+ :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` is set.
+
+
+ .. data:: Py_TPFLAGS_DEFAULT
+
+ This is a bitmask of all the bits that pertain to the existence of certain
+ fields in the type object and its extension structures. Currently, it includes
+ the following bits: :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`,
+ :const:`Py_TPFLAGS_HAVE_SEQUENCE_IN`, :const:`Py_TPFLAGS_HAVE_INPLACEOPS`,
+ :const:`Py_TPFLAGS_HAVE_RICHCOMPARE`, :const:`Py_TPFLAGS_HAVE_WEAKREFS`,
+ :const:`Py_TPFLAGS_HAVE_ITER`, and :const:`Py_TPFLAGS_HAVE_CLASS`.
+
+
+.. cmember:: char* PyTypeObject.tp_doc
+
+ An optional pointer to a NUL-terminated C string giving the docstring for this
+ type object. This is exposed as the :attr:`__doc__` attribute on the type and
+ instances of the type.
+
+ This field is *not* inherited by subtypes.
+
+The following three fields only exist if the
+:const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit is set.
+
+
+.. cmember:: traverseproc PyTypeObject.tp_traverse
+
+ An optional pointer to a traversal function for the garbage collector. This is
+ only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. More information
+ about Python's garbage collection scheme can be found in section
+ :ref:`supporting-cycle-detection`.
+
+ The :attr:`tp_traverse` pointer is used by the garbage collector to detect
+ reference cycles. A typical implementation of a :attr:`tp_traverse` function
+ simply calls :cfunc:`Py_VISIT` on each of the instance's members that are Python
+ objects. For exampe, this is function :cfunc:`local_traverse` from the
+ :mod:`thread` extension module::
+
+ static int
+ local_traverse(localobject *self, visitproc visit, void *arg)
+ {
+ Py_VISIT(self->args);
+ Py_VISIT(self->kw);
+ Py_VISIT(self->dict);
+ return 0;
+ }
+
+ Note that :cfunc:`Py_VISIT` is called only on those members that can participate
+ in reference cycles. Although there is also a ``self->key`` member, it can only
+ be *NULL* or a Python string and therefore cannot be part of a reference cycle.
+
+ On the other hand, even if you know a member can never be part of a cycle, as a
+ debugging aid you may want to visit it anyway just so the :mod:`gc` module's
+ :func:`get_referents` function will include it.
+
+ Note that :cfunc:`Py_VISIT` requires the *visit* and *arg* parameters to
+ :cfunc:`local_traverse` to have these specific names; don't name them just
+ anything.
+
+ This field is inherited by subtypes together with :attr:`tp_clear` and the
+ :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
+ :attr:`tp_clear` are all inherited from the base type if they are all zero in
+ the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
+ bit set.
+
+
+.. cmember:: inquiry PyTypeObject.tp_clear
+
+ An optional pointer to a clear function for the garbage collector. This is only
+ used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set.
+
+ The :attr:`tp_clear` member function is used to break reference cycles in cyclic
+ garbage detected by the garbage collector. Taken together, all :attr:`tp_clear`
+ functions in the system must combine to break all reference cycles. This is
+ subtle, and if in any doubt supply a :attr:`tp_clear` function. For example,
+ the tuple type does not implement a :attr:`tp_clear` function, because it's
+ possible to prove that no reference cycle can be composed entirely of tuples.
+ Therefore the :attr:`tp_clear` functions of other types must be sufficient to
+ break any cycle containing a tuple. This isn't immediately obvious, and there's
+ rarely a good reason to avoid implementing :attr:`tp_clear`.
+
+ Implementations of :attr:`tp_clear` should drop the instance's references to
+ those of its members that may be Python objects, and set its pointers to those
+ members to *NULL*, as in the following example::
+
+ static int
+ local_clear(localobject *self)
+ {
+ Py_CLEAR(self->key);
+ Py_CLEAR(self->args);
+ Py_CLEAR(self->kw);
+ Py_CLEAR(self->dict);
+ return 0;
+ }
+
+ The :cfunc:`Py_CLEAR` macro should be used, because clearing references is
+ delicate: the reference to the contained object must not be decremented until
+ after the pointer to the contained object is set to *NULL*. This is because
+ decrementing the reference count may cause the contained object to become trash,
+ triggering a chain of reclamation activity that may include invoking arbitrary
+ Python code (due to finalizers, or weakref callbacks, associated with the
+ contained object). If it's possible for such code to reference *self* again,
+ it's important that the pointer to the contained object be *NULL* at that time,
+ so that *self* knows the contained object can no longer be used. The
+ :cfunc:`Py_CLEAR` macro performs the operations in a safe order.
+
+ Because the goal of :attr:`tp_clear` functions is to break reference cycles,
+ it's not necessary to clear contained objects like Python strings or Python
+ integers, which can't participate in reference cycles. On the other hand, it may
+ be convenient to clear all contained Python objects, and write the type's
+ :attr:`tp_dealloc` function to invoke :attr:`tp_clear`.
+
+ More information about Python's garbage collection scheme can be found in
+ section :ref:`supporting-cycle-detection`.
+
+ This field is inherited by subtypes together with :attr:`tp_traverse` and the
+ :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
+ :attr:`tp_clear` are all inherited from the base type if they are all zero in
+ the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
+ bit set.
+
+
+.. cmember:: richcmpfunc PyTypeObject.tp_richcompare
+
+ An optional pointer to the rich comparison function.
+
+ The signature is the same as for :cfunc:`PyObject_RichCompare`. The function
+ should return the result of the comparison (usually ``Py_True`` or
+ ``Py_False``). If the comparison is undefined, it must return
+ ``Py_NotImplemented``, if another error occurred it must return ``NULL`` and set
+ an exception condition.
+
+ This field is inherited by subtypes together with :attr:`tp_compare` and
+ :attr:`tp_hash`: a subtype inherits all three of :attr:`tp_compare`,
+ :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's
+ :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*.
+
+ The following constants are defined to be used as the third argument for
+ :attr:`tp_richcompare` and for :cfunc:`PyObject_RichCompare`:
+
+ +----------------+------------+
+ | Constant | Comparison |
+ +================+============+
+ | :const:`Py_LT` | ``<`` |
+ +----------------+------------+
+ | :const:`Py_LE` | ``<=`` |
+ +----------------+------------+
+ | :const:`Py_EQ` | ``==`` |
+ +----------------+------------+
+ | :const:`Py_NE` | ``!=`` |
+ +----------------+------------+
+ | :const:`Py_GT` | ``>`` |
+ +----------------+------------+
+ | :const:`Py_GE` | ``>=`` |
+ +----------------+------------+
+
+The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit is
+set.
+
+
+.. cmember:: long PyTypeObject.tp_weaklistoffset
+
+ If the instances of this type are weakly referenceable, this field is greater
+ than zero and contains the offset in the instance structure of the weak
+ reference list head (ignoring the GC header, if present); this offset is used by
+ :cfunc:`PyObject_ClearWeakRefs` and the :cfunc:`PyWeakref_\*` functions. The
+ instance structure needs to include a field of type :ctype:`PyObject\*` which is
+ initialized to *NULL*.
+
+ Do not confuse this field with :attr:`tp_weaklist`; that is the list head for
+ weak references to the type object itself.
+
+ This field is inherited by subtypes, but see the rules listed below. A subtype
+ may override this offset; this means that the subtype uses a different weak
+ reference list head than the base type. Since the list head is always found via
+ :attr:`tp_weaklistoffset`, this should not be a problem.
+
+ When a type defined by a class statement has no :attr:`__slots__` declaration,
+ and none of its base types are weakly referenceable, the type is made weakly
+ referenceable by adding a weak reference list head slot to the instance layout
+ and setting the :attr:`tp_weaklistoffset` of that slot's offset.
+
+ When a type's :attr:`__slots__` declaration contains a slot named
+ :attr:`__weakref__`, that slot becomes the weak reference list head for
+ instances of the type, and the slot's offset is stored in the type's
+ :attr:`tp_weaklistoffset`.
+
+ When a type's :attr:`__slots__` declaration does not contain a slot named
+ :attr:`__weakref__`, the type inherits its :attr:`tp_weaklistoffset` from its
+ base type.
+
+The next two fields only exist if the :const:`Py_TPFLAGS_HAVE_CLASS` flag bit is
+set.
+
+
+.. cmember:: getiterfunc PyTypeObject.tp_iter
+
+ An optional pointer to a function that returns an iterator for the object. Its
+ presence normally signals that the instances of this type are iterable (although
+ sequences may be iterable without this function, and classic instances always
+ have this function, even if they don't define an :meth:`__iter__` method).
+
+ This function has the same signature as :cfunc:`PyObject_GetIter`.
+
+ This field is inherited by subtypes.
+
+
+.. cmember:: iternextfunc PyTypeObject.tp_iternext
+
+ An optional pointer to a function that returns the next item in an iterator, or
+ raises :exc:`StopIteration` when the iterator is exhausted. Its presence
+ normally signals that the instances of this type are iterators (although classic
+ instances always have this function, even if they don't define a :meth:`next`
+ method).
+
+ Iterator types should also define the :attr:`tp_iter` function, and that
+ function should return the iterator instance itself (not a new iterator
+ instance).
+
+ This function has the same signature as :cfunc:`PyIter_Next`.
+
+ This field is inherited by subtypes.
+
+The next fields, up to and including :attr:`tp_weaklist`, only exist if the
+:const:`Py_TPFLAGS_HAVE_CLASS` flag bit is set.
+
+
+.. cmember:: struct PyMethodDef* PyTypeObject.tp_methods
+
+ An optional pointer to a static *NULL*-terminated array of :ctype:`PyMethodDef`
+ structures, declaring regular methods of this type.
+
+ For each entry in the array, an entry is added to the type's dictionary (see
+ :attr:`tp_dict` below) containing a method descriptor.
+
+ This field is not inherited by subtypes (methods are inherited through a
+ different mechanism).
+
+
+.. cmember:: struct PyMemberDef* PyTypeObject.tp_members
+
+ An optional pointer to a static *NULL*-terminated array of :ctype:`PyMemberDef`
+ structures, declaring regular data members (fields or slots) of instances of
+ this type.
+
+ For each entry in the array, an entry is added to the type's dictionary (see
+ :attr:`tp_dict` below) containing a member descriptor.
+
+ This field is not inherited by subtypes (members are inherited through a
+ different mechanism).
+
+
+.. cmember:: struct PyGetSetDef* PyTypeObject.tp_getset
+
+ An optional pointer to a static *NULL*-terminated array of :ctype:`PyGetSetDef`
+ structures, declaring computed attributes of instances of this type.
+
+ For each entry in the array, an entry is added to the type's dictionary (see
+ :attr:`tp_dict` below) containing a getset descriptor.
+
+ This field is not inherited by subtypes (computed attributes are inherited
+ through a different mechanism).
+
+ Docs for PyGetSetDef (XXX belong elsewhere)::
+
+ typedef PyObject *(*getter)(PyObject *, void *);
+ typedef int (*setter)(PyObject *, PyObject *, void *);
+
+ typedef struct PyGetSetDef {
+ char *name; /* attribute name */
+ getter get; /* C function to get the attribute */
+ setter set; /* C function to set the attribute */
+ char *doc; /* optional doc string */
+ void *closure; /* optional additional data for getter and setter */
+ } PyGetSetDef;
+
+
+.. cmember:: PyTypeObject* PyTypeObject.tp_base
+
+ An optional pointer to a base type from which type properties are inherited. At
+ this level, only single inheritance is supported; multiple inheritance require
+ dynamically creating a type object by calling the metatype.
+
+ This field is not inherited by subtypes (obviously), but it defaults to
+ ``&PyBaseObject_Type`` (which to Python programmers is known as the type
+ :class:`object`).
+
+
+.. cmember:: PyObject* PyTypeObject.tp_dict
+
+ The type's dictionary is stored here by :cfunc:`PyType_Ready`.
+
+ This field should normally be initialized to *NULL* before PyType_Ready is
+ called; it may also be initialized to a dictionary containing initial attributes
+ for the type. Once :cfunc:`PyType_Ready` has initialized the type, extra
+ attributes for the type may be added to this dictionary only if they don't
+ correspond to overloaded operations (like :meth:`__add__`).
+
+ This field is not inherited by subtypes (though the attributes defined in here
+ are inherited through a different mechanism).
+
+
+.. cmember:: descrgetfunc PyTypeObject.tp_descr_get
+
+ An optional pointer to a "descriptor get" function.
+
+ The function signature is ::
+
+ PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
+
+ XXX blah, blah.
+
+ This field is inherited by subtypes.
+
+
+.. cmember:: descrsetfunc PyTypeObject.tp_descr_set
+
+ An optional pointer to a "descriptor set" function.
+
+ The function signature is ::
+
+ int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
+
+ This field is inherited by subtypes.
+
+ XXX blah, blah.
+
+
+.. cmember:: long PyTypeObject.tp_dictoffset
+
+ If the instances of this type have a dictionary containing instance variables,
+ this field is non-zero and contains the offset in the instances of the type of
+ the instance variable dictionary; this offset is used by
+ :cfunc:`PyObject_GenericGetAttr`.
+
+ Do not confuse this field with :attr:`tp_dict`; that is the dictionary for
+ attributes of the type object itself.
+
+ If the value of this field is greater than zero, it specifies the offset from
+ the start of the instance structure. If the value is less than zero, it
+ specifies the offset from the *end* of the instance structure. A negative
+ offset is more expensive to use, and should only be used when the instance
+ structure contains a variable-length part. This is used for example to add an
+ instance variable dictionary to subtypes of :class:`str` or :class:`tuple`. Note
+ that the :attr:`tp_basicsize` field should account for the dictionary added to
+ the end in that case, even though the dictionary is not included in the basic
+ object layout. On a system with a pointer size of 4 bytes,
+ :attr:`tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is
+ at the very end of the structure.
+
+ The real dictionary offset in an instance can be computed from a negative
+ :attr:`tp_dictoffset` as follows::
+
+ dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
+ if dictoffset is not aligned on sizeof(void*):
+ round up to sizeof(void*)
+
+ where :attr:`tp_basicsize`, :attr:`tp_itemsize` and :attr:`tp_dictoffset` are
+ taken from the type object, and :attr:`ob_size` is taken from the instance. The
+ absolute value is taken because long ints use the sign of :attr:`ob_size` to
+ store the sign of the number. (There's never a need to do this calculation
+ yourself; it is done for you by :cfunc:`_PyObject_GetDictPtr`.)
+
+ This field is inherited by subtypes, but see the rules listed below. A subtype
+ may override this offset; this means that the subtype instances store the
+ dictionary at a difference offset than the base type. Since the dictionary is
+ always found via :attr:`tp_dictoffset`, this should not be a problem.
+
+ When a type defined by a class statement has no :attr:`__slots__` declaration,
+ and none of its base types has an instance variable dictionary, a dictionary
+ slot is added to the instance layout and the :attr:`tp_dictoffset` is set to
+ that slot's offset.
+
+ When a type defined by a class statement has a :attr:`__slots__` declaration,
+ the type inherits its :attr:`tp_dictoffset` from its base type.
+
+ (Adding a slot named :attr:`__dict__` to the :attr:`__slots__` declaration does
+ not have the expected effect, it just causes confusion. Maybe this should be
+ added as a feature just like :attr:`__weakref__` though.)
+
+
+.. cmember:: initproc PyTypeObject.tp_init
+
+ An optional pointer to an instance initialization function.
+
+ This function corresponds to the :meth:`__init__` method of classes. Like
+ :meth:`__init__`, it is possible to create an instance without calling
+ :meth:`__init__`, and it is possible to reinitialize an instance by calling its
+ :meth:`__init__` method again.
+
+ The function signature is ::
+
+ int tp_init(PyObject *self, PyObject *args, PyObject *kwds)
+
+ The self argument is the instance to be initialized; the *args* and *kwds*
+ arguments represent positional and keyword arguments of the call to
+ :meth:`__init__`.
+
+ The :attr:`tp_init` function, if not *NULL*, is called when an instance is
+ created normally by calling its type, after the type's :attr:`tp_new` function
+ has returned an instance of the type. If the :attr:`tp_new` function returns an
+ instance of some other type that is not a subtype of the original type, no
+ :attr:`tp_init` function is called; if :attr:`tp_new` returns an instance of a
+ subtype of the original type, the subtype's :attr:`tp_init` is called. (VERSION
+ NOTE: described here is what is implemented in Python 2.2.1 and later. In
+ Python 2.2, the :attr:`tp_init` of the type of the object returned by
+ :attr:`tp_new` was always called, if not *NULL*.)
+
+ This field is inherited by subtypes.
+
+
+.. cmember:: allocfunc PyTypeObject.tp_alloc
+
+ An optional pointer to an instance allocation function.
+
+ The function signature is ::
+
+ PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems)
+
+ The purpose of this function is to separate memory allocation from memory
+ initialization. It should return a pointer to a block of memory of adequate
+ length for the instance, suitably aligned, and initialized to zeros, but with
+ :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument. If
+ the type's :attr:`tp_itemsize` is non-zero, the object's :attr:`ob_size` field
+ should be initialized to *nitems* and the length of the allocated memory block
+ should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of
+ ``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block
+ should be :attr:`tp_basicsize`.
+
+ Do not use this function to do any other instance initialization, not even to
+ allocate additional memory; that should be done by :attr:`tp_new`.
+
+ This field is inherited by static subtypes, but not by dynamic subtypes
+ (subtypes created by a class statement); in the latter, this field is always set
+ to :cfunc:`PyType_GenericAlloc`, to force a standard heap allocation strategy.
+ That is also the recommended value for statically defined types.
+
+
+.. cmember:: newfunc PyTypeObject.tp_new
+
+ An optional pointer to an instance creation function.
+
+ If this function is *NULL* for a particular type, that type cannot be called to
+ create new instances; presumably there is some other way to create instances,
+ like a factory function.
+
+ The function signature is ::
+
+ PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)
+
+ The subtype argument is the type of the object being created; the *args* and
+ *kwds* arguments represent positional and keyword arguments of the call to the
+ type. Note that subtype doesn't have to equal the type whose :attr:`tp_new`
+ function is called; it may be a subtype of that type (but not an unrelated
+ type).
+
+ The :attr:`tp_new` function should call ``subtype->tp_alloc(subtype, nitems)``
+ to allocate space for the object, and then do only as much further
+ initialization as is absolutely necessary. Initialization that can safely be
+ ignored or repeated should be placed in the :attr:`tp_init` handler. A good
+ rule of thumb is that for immutable types, all initialization should take place
+ in :attr:`tp_new`, while for mutable types, most initialization should be
+ deferred to :attr:`tp_init`.
+
+ This field is inherited by subtypes, except it is not inherited by static types
+ whose :attr:`tp_base` is *NULL* or ``&PyBaseObject_Type``. The latter exception
+ is a precaution so that old extension types don't become callable simply by
+ being linked with Python 2.2.
+
+
+.. cmember:: destructor PyTypeObject.tp_free
+
+ An optional pointer to an instance deallocation function.
+
+ The signature of this function has changed slightly: in Python 2.2 and 2.2.1,
+ its signature is :ctype:`destructor`::
+
+ void tp_free(PyObject *)
+
+ In Python 2.3 and beyond, its signature is :ctype:`freefunc`::
+
+ void tp_free(void *)
+
+ The only initializer that is compatible with both versions is ``_PyObject_Del``,
+ whose definition has suitably adapted in Python 2.3.
+
+ This field is inherited by static subtypes, but not by dynamic subtypes
+ (subtypes created by a class statement); in the latter, this field is set to a
+ deallocator suitable to match :cfunc:`PyType_GenericAlloc` and the value of the
+ :const:`Py_TPFLAGS_HAVE_GC` flag bit.
+
+
+.. cmember:: inquiry PyTypeObject.tp_is_gc
+
+ An optional pointer to a function called by the garbage collector.
+
+ The garbage collector needs to know whether a particular object is collectible
+ or not. Normally, it is sufficient to look at the object's type's
+ :attr:`tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit. But
+ some types have a mixture of statically and dynamically allocated instances, and
+ the statically allocated instances are not collectible. Such types should
+ define this function; it should return ``1`` for a collectible instance, and
+ ``0`` for a non-collectible instance. The signature is ::
+
+ int tp_is_gc(PyObject *self)
+
+ (The only example of this are types themselves. The metatype,
+ :cdata:`PyType_Type`, defines this function to distinguish between statically
+ and dynamically allocated types.)
+
+ This field is inherited by subtypes. (VERSION NOTE: in Python 2.2, it was not
+ inherited. It is inherited in 2.2.1 and later versions.)
+
+
+.. cmember:: PyObject* PyTypeObject.tp_bases
+
+ Tuple of base types.
+
+ This is set for types created by a class statement. It should be *NULL* for
+ statically defined types.
+
+ This field is not inherited.
+
+
+.. cmember:: PyObject* PyTypeObject.tp_mro
+
+ Tuple containing the expanded set of base types, starting with the type itself
+ and ending with :class:`object`, in Method Resolution Order.
+
+ This field is not inherited; it is calculated fresh by :cfunc:`PyType_Ready`.
+
+
+.. cmember:: PyObject* PyTypeObject.tp_cache
+
+ Unused. Not inherited. Internal use only.
+
+
+.. cmember:: PyObject* PyTypeObject.tp_subclasses
+
+ List of weak references to subclasses. Not inherited. Internal use only.
+
+
+.. cmember:: PyObject* PyTypeObject.tp_weaklist
+
+ Weak reference list head, for weak references to this type object. Not
+ inherited. Internal use only.
+
+The remaining fields are only defined if the feature test macro
+:const:`COUNT_ALLOCS` is defined, and are for internal use only. They are
+documented here for completeness. None of these fields are inherited by
+subtypes.
+
+
+.. cmember:: Py_ssize_t PyTypeObject.tp_allocs
+
+ Number of allocations.
+
+
+.. cmember:: Py_ssize_t PyTypeObject.tp_frees
+
+ Number of frees.
+
+
+.. cmember:: Py_ssize_t PyTypeObject.tp_maxalloc
+
+ Maximum simultaneously allocated objects.
+
+
+.. cmember:: PyTypeObject* PyTypeObject.tp_next
+
+ Pointer to the next type object with a non-zero :attr:`tp_allocs` field.
+
+Also, note that, in a garbage collected Python, tp_dealloc may be called from
+any Python thread, not just the thread which created the object (if the object
+becomes part of a refcount cycle, that cycle might be collected by a garbage
+collection on any thread). This is not a problem for Python API calls, since
+the thread on which tp_dealloc is called will own the Global Interpreter Lock
+(GIL). However, if the object being destroyed in turn destroys objects from some
+other C or C++ library, care should be taken to ensure that destroying those
+objects on the thread which called tp_dealloc will not violate any assumptions
+of the library.
+
+
+.. _mapping-structs:
+
+Mapping Object Structures
+=========================
+
+
+.. ctype:: PyMappingMethods
+
+ Structure used to hold pointers to the functions used to implement the mapping
+ protocol for an extension type.
+
+
+.. _number-structs:
+
+Number Object Structures
+========================
+
+
+.. ctype:: PyNumberMethods
+
+ Structure used to hold pointers to the functions an extension type uses to
+ implement the number protocol.
+
+
+.. _sequence-structs:
+
+Sequence Object Structures
+==========================
+
+
+.. ctype:: PySequenceMethods
+
+ Structure used to hold pointers to the functions which an object uses to
+ implement the sequence protocol.
+
+
+.. _buffer-structs:
+
+Buffer Object Structures
+========================
+
+.. sectionauthor:: Greg J. Stein <greg@lyra.org>
+
+
+The buffer interface exports a model where an object can expose its internal
+data as a set of chunks of data, where each chunk is specified as a
+pointer/length pair. These chunks are called :dfn:`segments` and are presumed
+to be non-contiguous in memory.
+
+If an object does not export the buffer interface, then its :attr:`tp_as_buffer`
+member in the :ctype:`PyTypeObject` structure should be *NULL*. Otherwise, the
+:attr:`tp_as_buffer` will point to a :ctype:`PyBufferProcs` structure.
+
+.. note::
+
+ It is very important that your :ctype:`PyTypeObject` structure uses
+ :const:`Py_TPFLAGS_DEFAULT` for the value of the :attr:`tp_flags` member rather
+ than ``0``. This tells the Python runtime that your :ctype:`PyBufferProcs`
+ structure contains the :attr:`bf_getcharbuffer` slot. Older versions of Python
+ did not have this member, so a new Python interpreter using an old extension
+ needs to be able to test for its presence before using it.
+
+
+.. ctype:: PyBufferProcs
+
+ Structure used to hold the function pointers which define an implementation of
+ the buffer protocol.
+
+ The first slot is :attr:`bf_getreadbuffer`, of type :ctype:`getreadbufferproc`.
+ If this slot is *NULL*, then the object does not support reading from the
+ internal data. This is non-sensical, so implementors should fill this in, but
+ callers should test that the slot contains a non-*NULL* value.
+
+ The next slot is :attr:`bf_getwritebuffer` having type
+ :ctype:`getwritebufferproc`. This slot may be *NULL* if the object does not
+ allow writing into its returned buffers.
+
+ The third slot is :attr:`bf_getsegcount`, with type :ctype:`getsegcountproc`.
+ This slot must not be *NULL* and is used to inform the caller how many segments
+ the object contains. Simple objects such as :ctype:`PyString_Type` and
+ :ctype:`PyBuffer_Type` objects contain a single segment.
+
+ .. index:: single: PyType_HasFeature()
+
+ The last slot is :attr:`bf_getcharbuffer`, of type :ctype:`getcharbufferproc`.
+ This slot will only be present if the :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`
+ flag is present in the :attr:`tp_flags` field of the object's
+ :ctype:`PyTypeObject`. Before using this slot, the caller should test whether it
+ is present by using the :cfunc:`PyType_HasFeature` function. If the flag is
+ present, :attr:`bf_getcharbuffer` may be *NULL*, indicating that the object's
+ contents cannot be used as *8-bit characters*. The slot function may also raise
+ an error if the object's contents cannot be interpreted as 8-bit characters.
+ For example, if the object is an array which is configured to hold floating
+ point values, an exception may be raised if a caller attempts to use
+ :attr:`bf_getcharbuffer` to fetch a sequence of 8-bit characters. This notion of
+ exporting the internal buffers as "text" is used to distinguish between objects
+ that are binary in nature, and those which have character-based content.
+
+ .. note::
+
+ The current policy seems to state that these characters may be multi-byte
+ characters. This implies that a buffer size of *N* does not mean there are *N*
+ characters present.
+
+
+.. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
+
+ Flag bit set in the type structure to indicate that the :attr:`bf_getcharbuffer`
+ slot is known. This being set does not indicate that the object supports the
+ buffer interface or that the :attr:`bf_getcharbuffer` slot is non-*NULL*.
+
+
+.. ctype:: Py_ssize_t (*readbufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)
+
+ Return a pointer to a readable segment of the buffer in ``*ptrptr``. This
+ function is allowed to raise an exception, in which case it must return ``-1``.
+ The *segment* which is specified must be zero or positive, and strictly less
+ than the number of segments returned by the :attr:`bf_getsegcount` slot
+ function. On success, it returns the length of the segment, and sets
+ ``*ptrptr`` to a pointer to that memory.
+
+
+.. ctype:: Py_ssize_t (*writebufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)
+
+ Return a pointer to a writable memory buffer in ``*ptrptr``, and the length of
+ that segment as the function return value. The memory buffer must correspond to
+ buffer segment *segment*. Must return ``-1`` and set an exception on error.
+ :exc:`TypeError` should be raised if the object only supports read-only buffers,
+ and :exc:`SystemError` should be raised when *segment* specifies a segment that
+ doesn't exist.
+
+ .. % Why doesn't it raise ValueError for this one?
+ .. % GJS: because you shouldn't be calling it with an invalid
+ .. % segment. That indicates a blatant programming error in the C
+ .. % code.
+
+
+.. ctype:: Py_ssize_t (*segcountproc) (PyObject *self, Py_ssize_t *lenp)
+
+ Return the number of memory segments which comprise the buffer. If *lenp* is
+ not *NULL*, the implementation must report the sum of the sizes (in bytes) of
+ all segments in ``*lenp``. The function cannot fail.
+
+
+.. ctype:: Py_ssize_t (*charbufferproc) (PyObject *self, Py_ssize_t segment, const char **ptrptr)
+
+ Return the size of the segment *segment* that *ptrptr* is set to. ``*ptrptr``
+ is set to the memory buffer. Returns ``-1`` on error.
+
+
+.. _supporting-iteration:
+
+Supporting the Iterator Protocol
+================================
+
+
+.. _supporting-cycle-detection:
+
+Supporting Cyclic Garbage Collection
+====================================
+
+Python's support for detecting and collecting garbage which involves circular
+references requires support from object types which are "containers" for other
+objects which may also be containers. Types which do not store references to
+other objects, or which only store references to atomic types (such as numbers
+or strings), do not need to provide any explicit support for garbage collection.
+
+.. An example showing the use of these interfaces can be found in "Supporting the
+.. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)".
+
+To create a container type, the :attr:`tp_flags` field of the type object must
+include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
+:attr:`tp_traverse` handler. If instances of the type are mutable, a
+:attr:`tp_clear` implementation must also be provided.
+
+
+.. data:: Py_TPFLAGS_HAVE_GC
+
+ Objects with a type with this flag set must conform with the rules documented
+ here. For convenience these objects will be referred to as container objects.
+
+Constructors for container types must conform to two rules:
+
+#. The memory for the object must be allocated using :cfunc:`PyObject_GC_New` or
+ :cfunc:`PyObject_GC_VarNew`.
+
+#. Once all the fields which may contain references to other containers are
+ initialized, it must call :cfunc:`PyObject_GC_Track`.
+
+
+.. cfunction:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
+
+ Analogous to :cfunc:`PyObject_New` but for container objects with the
+ :const:`Py_TPFLAGS_HAVE_GC` flag set.
+
+
+.. cfunction:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
+
+ Analogous to :cfunc:`PyObject_NewVar` but for container objects with the
+ :const:`Py_TPFLAGS_HAVE_GC` flag set.
+
+
+.. cfunction:: PyVarObject * PyObject_GC_Resize(PyVarObject *op, Py_ssize_t)
+
+ Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the resized
+ object or *NULL* on failure.
+
+
+.. cfunction:: void PyObject_GC_Track(PyObject *op)
+
+ Adds the object *op* to the set of container objects tracked by the collector.
+ The collector can run at unexpected times so objects must be valid while being
+ tracked. This should be called once all the fields followed by the
+ :attr:`tp_traverse` handler become valid, usually near the end of the
+ constructor.
+
+
+.. cfunction:: void _PyObject_GC_TRACK(PyObject *op)
+
+ A macro version of :cfunc:`PyObject_GC_Track`. It should not be used for
+ extension modules.
+
+Similarly, the deallocator for the object must conform to a similar pair of
+rules:
+
+#. Before fields which refer to other containers are invalidated,
+ :cfunc:`PyObject_GC_UnTrack` must be called.
+
+#. The object's memory must be deallocated using :cfunc:`PyObject_GC_Del`.
+
+
+.. cfunction:: void PyObject_GC_Del(void *op)
+
+ Releases memory allocated to an object using :cfunc:`PyObject_GC_New` or
+ :cfunc:`PyObject_GC_NewVar`.
+
+
+.. cfunction:: void PyObject_GC_UnTrack(void *op)
+
+ Remove the object *op* from the set of container objects tracked by the
+ collector. Note that :cfunc:`PyObject_GC_Track` can be called again on this
+ object to add it back to the set of tracked objects. The deallocator
+ (:attr:`tp_dealloc` handler) should call this for the object before any of the
+ fields used by the :attr:`tp_traverse` handler become invalid.
+
+
+.. cfunction:: void _PyObject_GC_UNTRACK(PyObject *op)
+
+ A macro version of :cfunc:`PyObject_GC_UnTrack`. It should not be used for
+ extension modules.
+
+The :attr:`tp_traverse` handler accepts a function parameter of this type:
+
+
+.. ctype:: int (*visitproc)(PyObject *object, void *arg)
+
+ Type of the visitor function passed to the :attr:`tp_traverse` handler. The
+ function should be called with an object to traverse as *object* and the third
+ parameter to the :attr:`tp_traverse` handler as *arg*. The Python core uses
+ several visitor functions to implement cyclic garbage detection; it's not
+ expected that users will need to write their own visitor functions.
+
+The :attr:`tp_traverse` handler must have the following type:
+
+
+.. ctype:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
+
+ Traversal function for a container object. Implementations must call the
+ *visit* function for each object directly contained by *self*, with the
+ parameters to *visit* being the contained object and the *arg* value passed to
+ the handler. The *visit* function must not be called with a *NULL* object
+ argument. If *visit* returns a non-zero value that value should be returned
+ immediately.
+
+To simplify writing :attr:`tp_traverse` handlers, a :cfunc:`Py_VISIT` macro is
+provided. In order to use this macro, the :attr:`tp_traverse` implementation
+must name its arguments exactly *visit* and *arg*:
+
+
+.. cfunction:: void Py_VISIT(PyObject *o)
+
+ Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns a
+ non-zero value, then return it. Using this macro, :attr:`tp_traverse` handlers
+ look like::
+
+ static int
+ my_traverse(Noddy *self, visitproc visit, void *arg)
+ {
+ Py_VISIT(self->foo);
+ Py_VISIT(self->bar);
+ return 0;
+ }
+
+ .. versionadded:: 2.4
+
+The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL* if
+the object is immutable.
+
+
+.. ctype:: int (*inquiry)(PyObject *self)
+
+ Drop references that may have created reference cycles. Immutable objects do
+ not have to define this method since they can never directly create reference
+ cycles. Note that the object must still be valid after calling this method
+ (don't just call :cfunc:`Py_DECREF` on a reference). The collector will call
+ this method if it detects that this object is involved in a reference cycle.
+
--- /dev/null
+.. highlightlang:: c
+
+
+.. _countingrefs:
+
+******************
+Reference Counting
+******************
+
+The macros in this section are used for managing reference counts of Python
+objects.
+
+
+.. cfunction:: void Py_INCREF(PyObject *o)
+
+ Increment the reference count for object *o*. The object must not be *NULL*; if
+ you aren't sure that it isn't *NULL*, use :cfunc:`Py_XINCREF`.
+
+
+.. cfunction:: void Py_XINCREF(PyObject *o)
+
+ Increment the reference count for object *o*. The object may be *NULL*, in
+ which case the macro has no effect.
+
+
+.. cfunction:: void Py_DECREF(PyObject *o)
+
+ Decrement the reference count for object *o*. The object must not be *NULL*; if
+ you aren't sure that it isn't *NULL*, use :cfunc:`Py_XDECREF`. If the reference
+ count reaches zero, the object's type's deallocation function (which must not be
+ *NULL*) is invoked.
+
+ .. warning::
+
+ The deallocation function can cause arbitrary Python code to be invoked (e.g.
+ when a class instance with a :meth:`__del__` method is deallocated). While
+ exceptions in such code are not propagated, the executed code has free access to
+ all Python global variables. This means that any object that is reachable from
+ a global variable should be in a consistent state before :cfunc:`Py_DECREF` is
+ invoked. For example, code to delete an object from a list should copy a
+ reference to the deleted object in a temporary variable, update the list data
+ structure, and then call :cfunc:`Py_DECREF` for the temporary variable.
+
+
+.. cfunction:: void Py_XDECREF(PyObject *o)
+
+ Decrement the reference count for object *o*. The object may be *NULL*, in
+ which case the macro has no effect; otherwise the effect is the same as for
+ :cfunc:`Py_DECREF`, and the same warning applies.
+
+
+.. cfunction:: void Py_CLEAR(PyObject *o)
+
+ Decrement the reference count for object *o*. The object may be *NULL*, in
+ which case the macro has no effect; otherwise the effect is the same as for
+ :cfunc:`Py_DECREF`, except that the argument is also set to *NULL*. The warning
+ for :cfunc:`Py_DECREF` does not apply with respect to the object passed because
+ the macro carefully uses a temporary variable and sets the argument to *NULL*
+ before decrementing its reference count.
+
+ It is a good idea to use this macro whenever decrementing the value of a
+ variable that might be traversed during garbage collection.
+
+ .. versionadded:: 2.4
+
+The following functions are for runtime dynamic embedding of Python:
+``Py_IncRef(PyObject \*o)``, `Py_DecRef(PyObject \*o)``. They are
+simply exported function versions of :cfunc:`Py_XINCREF` and
+:cfunc:`Py_XDECREF`, respectively.
+
+The following functions or macros are only for use within the interpreter core:
+:cfunc:`_Py_Dealloc`, :cfunc:`_Py_ForgetReference`, :cfunc:`_Py_NewReference`,
+as well as the global variable :cdata:`_Py_RefTotal`.
+
--- /dev/null
+.. highlightlang:: c
+
+
+.. _utilities:
+
+*********
+Utilities
+*********
+
+The functions in this chapter perform various utility tasks, ranging from
+helping C code be more portable across platforms, using Python modules from C,
+and parsing function arguments and constructing Python values from C values.
+
+
+.. _os:
+
+Operating System Utilities
+==========================
+
+
+.. cfunction:: int Py_FdIsInteractive(FILE *fp, const char *filename)
+
+ Return true (nonzero) if the standard I/O file *fp* with name *filename* is
+ deemed interactive. This is the case for files for which ``isatty(fileno(fp))``
+ is true. If the global flag :cdata:`Py_InteractiveFlag` is true, this function
+ also returns true if the *filename* pointer is *NULL* or if the name is equal to
+ one of the strings ``'<stdin>'`` or ``'???'``.
+
+
+.. cfunction:: long PyOS_GetLastModificationTime(char *filename)
+
+ Return the time of last modification of the file *filename*. The result is
+ encoded in the same way as the timestamp returned by the standard C library
+ function :cfunc:`time`.
+
+
+.. cfunction:: void PyOS_AfterFork()
+
+ Function to update some internal state after a process fork; this should be
+ called in the new process if the Python interpreter will continue to be used.
+ If a new executable is loaded into the new process, this function does not need
+ to be called.
+
+
+.. cfunction:: int PyOS_CheckStack()
+
+ Return true when the interpreter runs out of stack space. This is a reliable
+ check, but is only available when :const:`USE_STACKCHECK` is defined (currently
+ on Windows using the Microsoft Visual C++ compiler). :const:`USE_STACKCHECK`
+ will be defined automatically; you should never change the definition in your
+ own code.
+
+
+.. cfunction:: PyOS_sighandler_t PyOS_getsig(int i)
+
+ Return the current signal handler for signal *i*. This is a thin wrapper around
+ either :cfunc:`sigaction` or :cfunc:`signal`. Do not call those functions
+ directly! :ctype:`PyOS_sighandler_t` is a typedef alias for :ctype:`void
+ (\*)(int)`.
+
+
+.. cfunction:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
+
+ Set the signal handler for signal *i* to be *h*; return the old signal handler.
+ This is a thin wrapper around either :cfunc:`sigaction` or :cfunc:`signal`. Do
+ not call those functions directly! :ctype:`PyOS_sighandler_t` is a typedef
+ alias for :ctype:`void (\*)(int)`.
+
+
+.. _processcontrol:
+
+Process Control
+===============
+
+
+.. cfunction:: void Py_FatalError(const char *message)
+
+ .. index:: single: abort()
+
+ Print a fatal error message and kill the process. No cleanup is performed.
+ This function should only be invoked when a condition is detected that would
+ make it dangerous to continue using the Python interpreter; e.g., when the
+ object administration appears to be corrupted. On Unix, the standard C library
+ function :cfunc:`abort` is called which will attempt to produce a :file:`core`
+ file.
+
+
+.. cfunction:: void Py_Exit(int status)
+
+ .. index::
+ single: Py_Finalize()
+ single: exit()
+
+ Exit the current process. This calls :cfunc:`Py_Finalize` and then calls the
+ standard C library function ``exit(status)``.
+
+
+.. cfunction:: int Py_AtExit(void (*func) ())
+
+ .. index::
+ single: Py_Finalize()
+ single: cleanup functions
+
+ Register a cleanup function to be called by :cfunc:`Py_Finalize`. The cleanup
+ function will be called with no arguments and should return no value. At most
+ 32 cleanup functions can be registered. When the registration is successful,
+ :cfunc:`Py_AtExit` returns ``0``; on failure, it returns ``-1``. The cleanup
+ function registered last is called first. Each cleanup function will be called
+ at most once. Since Python's internal finalization will have completed before
+ the cleanup function, no Python APIs should be called by *func*.
+
+
+.. _importing:
+
+Importing Modules
+=================
+
+
+.. cfunction:: PyObject* PyImport_ImportModule(const char *name)
+
+ .. index::
+ single: package variable; __all__
+ single: __all__ (package variable)
+
+ This is a simplified interface to :cfunc:`PyImport_ImportModuleEx` below,
+ leaving the *globals* and *locals* arguments set to *NULL*. When the *name*
+ argument contains a dot (when it specifies a submodule of a package), the
+ *fromlist* argument is set to the list ``['*']`` so that the return value is the
+ named module rather than the top-level package containing it as would otherwise
+ be the case. (Unfortunately, this has an additional side effect when *name* in
+ fact specifies a subpackage instead of a submodule: the submodules specified in
+ the package's ``__all__`` variable are loaded.) Return a new reference to the
+ imported module, or *NULL* with an exception set on failure. Before Python 2.4,
+ the module may still be created in the failure case --- examine ``sys.modules``
+ to find out. Starting with Python 2.4, a failing import of a module no longer
+ leaves the module in ``sys.modules``.
+
+ .. versionchanged:: 2.4
+ failing imports remove incomplete module objects.
+
+ .. index:: single: modules (in module sys)
+
+
+.. cfunction:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
+
+ .. index:: builtin: __import__
+
+ Import a module. This is best described by referring to the built-in Python
+ function :func:`__import__`, as the standard :func:`__import__` function calls
+ this function directly.
+
+ The return value is a new reference to the imported module or top-level package,
+ or *NULL* with an exception set on failure (before Python 2.4, the module may
+ still be created in this case). Like for :func:`__import__`, the return value
+ when a submodule of a package was requested is normally the top-level package,
+ unless a non-empty *fromlist* was given.
+
+ .. versionchanged:: 2.4
+ failing imports remove incomplete module objects.
+
+
+.. cfunction:: PyObject* PyImport_Import(PyObject *name)
+
+ .. index::
+ module: rexec
+ module: ihooks
+
+ This is a higher-level interface that calls the current "import hook function".
+ It invokes the :func:`__import__` function from the ``__builtins__`` of the
+ current globals. This means that the import is done using whatever import hooks
+ are installed in the current environment, e.g. by :mod:`rexec` or :mod:`ihooks`.
+
+
+.. cfunction:: PyObject* PyImport_ReloadModule(PyObject *m)
+
+ .. index:: builtin: reload
+
+ Reload a module. This is best described by referring to the built-in Python
+ function :func:`reload`, as the standard :func:`reload` function calls this
+ function directly. Return a new reference to the reloaded module, or *NULL*
+ with an exception set on failure (the module still exists in this case).
+
+
+.. cfunction:: PyObject* PyImport_AddModule(const char *name)
+
+ Return the module object corresponding to a module name. The *name* argument
+ may be of the form ``package.module``. First check the modules dictionary if
+ there's one there, and if not, create a new one and insert it in the modules
+ dictionary. Return *NULL* with an exception set on failure.
+
+ .. note::
+
+ This function does not load or import the module; if the module wasn't already
+ loaded, you will get an empty module object. Use :cfunc:`PyImport_ImportModule`
+ or one of its variants to import a module. Package structures implied by a
+ dotted name for *name* are not created if not already present.
+
+
+.. cfunction:: PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)
+
+ .. index:: builtin: compile
+
+ Given a module name (possibly of the form ``package.module``) and a code object
+ read from a Python bytecode file or obtained from the built-in function
+ :func:`compile`, load the module. Return a new reference to the module object,
+ or *NULL* with an exception set if an error occurred. Before Python 2.4, the
+ module could still be created in error cases. Starting with Python 2.4, *name*
+ is removed from ``sys.modules`` in error cases, and even if *name* was already
+ in ``sys.modules`` on entry to :cfunc:`PyImport_ExecCodeModule`. Leaving
+ incompletely initialized modules in ``sys.modules`` is dangerous, as imports of
+ such modules have no way to know that the module object is an unknown (and
+ probably damaged with respect to the module author's intents) state.
+
+ This function will reload the module if it was already imported. See
+ :cfunc:`PyImport_ReloadModule` for the intended way to reload a module.
+
+ If *name* points to a dotted name of the form ``package.module``, any package
+ structures not already created will still not be created.
+
+ .. versionchanged:: 2.4
+ *name* is removed from ``sys.modules`` in error cases.
+
+
+.. cfunction:: long PyImport_GetMagicNumber()
+
+ Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and
+ :file:`.pyo` files). The magic number should be present in the first four bytes
+ of the bytecode file, in little-endian byte order.
+
+
+.. cfunction:: PyObject* PyImport_GetModuleDict()
+
+ Return the dictionary used for the module administration (a.k.a.
+ ``sys.modules``). Note that this is a per-interpreter variable.
+
+
+.. cfunction:: void _PyImport_Init()
+
+ Initialize the import mechanism. For internal use only.
+
+
+.. cfunction:: void PyImport_Cleanup()
+
+ Empty the module table. For internal use only.
+
+
+.. cfunction:: void _PyImport_Fini()
+
+ Finalize the import mechanism. For internal use only.
+
+
+.. cfunction:: PyObject* _PyImport_FindExtension(char *, char *)
+
+ For internal use only.
+
+
+.. cfunction:: PyObject* _PyImport_FixupExtension(char *, char *)
+
+ For internal use only.
+
+
+.. cfunction:: int PyImport_ImportFrozenModule(char *name)
+
+ Load a frozen module named *name*. Return ``1`` for success, ``0`` if the
+ module is not found, and ``-1`` with an exception set if the initialization
+ failed. To access the imported module on a successful load, use
+ :cfunc:`PyImport_ImportModule`. (Note the misnomer --- this function would
+ reload the module if it was already imported.)
+
+
+.. ctype:: struct _frozen
+
+ .. index:: single: freeze utility
+
+ This is the structure type definition for frozen module descriptors, as
+ generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the
+ Python source distribution). Its definition, found in :file:`Include/import.h`,
+ is::
+
+ struct _frozen {
+ char *name;
+ unsigned char *code;
+ int size;
+ };
+
+
+.. cvar:: struct _frozen* PyImport_FrozenModules
+
+ This pointer is initialized to point to an array of :ctype:`struct _frozen`
+ records, terminated by one whose members are all *NULL* or zero. When a frozen
+ module is imported, it is searched in this table. Third-party code could play
+ tricks with this to provide a dynamically created collection of frozen modules.
+
+
+.. cfunction:: int PyImport_AppendInittab(char *name, void (*initfunc)(void))
+
+ Add a single module to the existing table of built-in modules. This is a
+ convenience wrapper around :cfunc:`PyImport_ExtendInittab`, returning ``-1`` if
+ the table could not be extended. The new module can be imported by the name
+ *name*, and uses the function *initfunc* as the initialization function called
+ on the first attempted import. This should be called before
+ :cfunc:`Py_Initialize`.
+
+
+.. ctype:: struct _inittab
+
+ Structure describing a single entry in the list of built-in modules. Each of
+ these structures gives the name and initialization function for a module built
+ into the interpreter. Programs which embed Python may use an array of these
+ structures in conjunction with :cfunc:`PyImport_ExtendInittab` to provide
+ additional built-in modules. The structure is defined in
+ :file:`Include/import.h` as::
+
+ struct _inittab {
+ char *name;
+ void (*initfunc)(void);
+ };
+
+
+.. cfunction:: int PyImport_ExtendInittab(struct _inittab *newtab)
+
+ Add a collection of modules to the table of built-in modules. The *newtab*
+ array must end with a sentinel entry which contains *NULL* for the :attr:`name`
+ field; failure to provide the sentinel value can result in a memory fault.
+ Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
+ extend the internal table. In the event of failure, no modules are added to the
+ internal table. This should be called before :cfunc:`Py_Initialize`.
+
+
+.. _marshalling-utils:
+
+Data marshalling support
+========================
+
+These routines allow C code to work with serialized objects using the same data
+format as the :mod:`marshal` module. There are functions to write data into the
+serialization format, and additional functions that can be used to read the data
+back. Files used to store marshalled data must be opened in binary mode.
+
+Numeric values are stored with the least significant byte first.
+
+The module supports two versions of the data format: version 0 is the historical
+version, version 1 (new in Python 2.4) shares interned strings in the file, and
+upon unmarshalling. *Py_MARSHAL_VERSION* indicates the current file format
+(currently 1).
+
+
+.. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
+
+ Marshal a :ctype:`long` integer, *value*, to *file*. This will only write the
+ least-significant 32 bits of *value*; regardless of the size of the native
+ :ctype:`long` type.
+
+ .. versionchanged:: 2.4
+ *version* indicates the file format.
+
+
+.. cfunction:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
+
+ Marshal a Python object, *value*, to *file*.
+
+ .. versionchanged:: 2.4
+ *version* indicates the file format.
+
+
+.. cfunction:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
+
+ Return a string object containing the marshalled representation of *value*.
+
+ .. versionchanged:: 2.4
+ *version* indicates the file format.
+
+
+The following functions allow marshalled values to be read back in.
+
+XXX What about error detection? It appears that reading past the end of the
+file will always result in a negative numeric value (where that's relevant), but
+it's not clear that negative values won't be handled properly when there's no
+error. What's the right way to tell? Should only non-negative values be written
+using these routines?
+
+
+.. cfunction:: long PyMarshal_ReadLongFromFile(FILE *file)
+
+ Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened for
+ reading. Only a 32-bit value can be read in using this function, regardless of
+ the native size of :ctype:`long`.
+
+
+.. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file)
+
+ Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened for
+ reading. Only a 16-bit value can be read in using this function, regardless of
+ the native size of :ctype:`short`.
+
+
+.. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
+
+ Return a Python object from the data stream in a :ctype:`FILE\*` opened for
+ reading. On error, sets the appropriate exception (:exc:`EOFError` or
+ :exc:`TypeError`) and returns *NULL*.
+
+
+.. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
+
+ Return a Python object from the data stream in a :ctype:`FILE\*` opened for
+ reading. Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function assumes
+ that no further objects will be read from the file, allowing it to aggressively
+ load file data into memory so that the de-serialization can operate from data in
+ memory rather than reading a byte at a time from the file. Only use these
+ variant if you are certain that you won't be reading anything else from the
+ file. On error, sets the appropriate exception (:exc:`EOFError` or
+ :exc:`TypeError`) and returns *NULL*.
+
+
+.. cfunction:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
+
+ Return a Python object from the data stream in a character buffer containing
+ *len* bytes pointed to by *string*. On error, sets the appropriate exception
+ (:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
+
+
+.. _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 object) [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]
+ 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.
+
+``z`` (string 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 or ``None`` or any read buffer compatible object) [const char \*, int]
+ This is to ``s#`` as ``z`` is to ``s``.
+
+``u`` (Unicode object) [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 object) [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 object 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 object 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 object 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 object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
+ 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) [char]
+ Convert a Python integer to a tiny int, stored in a C :ctype:`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.
+
+``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 \*, int]
+ 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:`int` is set to the length of the buffer. Only
+ single-segment buffer objects are accepted; :exc:`TypeError` is raised for all
+ others.
+
+``(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. Clearly, ``:`` 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.
+
+
+.. 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
+
+
+.. 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.
+
+
+.. _string-conversion:
+
+String conversion and formatting
+================================
+
+Functions for number conversion and formatted string output.
+
+
+.. cfunction:: int PyOS_snprintf(char *str, size_t size, const char *format, ...)
+
+ Output not more than *size* bytes to *str* according to the format string
+ *format* and the extra arguments. See the Unix man page :manpage:`snprintf(2)`.
+
+
+.. cfunction:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
+
+ Output not more than *size* bytes to *str* according to the format string
+ *format* and the variable argument list *va*. Unix man page
+ :manpage:`vsnprintf(2)`.
+
+:cfunc:`PyOS_snprintf` and :cfunc:`PyOS_vsnprintf` wrap the Standard C library
+functions :cfunc:`snprintf` and :cfunc:`vsnprintf`. Their purpose is to
+guarantee consistent behavior in corner cases, which the Standard C functions do
+not.
+
+The wrappers ensure that *str*[*size*-1] is always ``'\0'`` upon return. They
+never write more than *size* bytes (including the trailing ``'\0'`` into str.
+Both functions require that ``str != NULL``, ``size > 0`` and ``format !=
+NULL``.
+
+If the platform doesn't have :cfunc:`vsnprintf` and the buffer size needed to
+avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a
+*Py_FatalError*.
+
+The return value (*rv*) for these functions should be interpreted as follows:
+
+* When ``0 <= rv < size``, the output conversion was successful and *rv*
+ characters were written to *str* (excluding the trailing ``'\0'`` byte at
+ *str*[*rv*]).
+
+* When ``rv >= size``, the output conversion was truncated and a buffer with
+ ``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\0'``
+ in this case.
+
+* When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\0'`` in
+ this case too, but the rest of *str* is undefined. The exact cause of the error
+ depends on the underlying platform.
+
+The following functions provide locale-independent string to number conversions.
+
+
+.. cfunction:: double PyOS_ascii_strtod(const char *nptr, char **endptr)
+
+ Convert a string to a :ctype:`double`. This function behaves like the Standard C
+ function :cfunc:`strtod` does in the C locale. It does this without changing the
+ current locale, since that would not be thread-safe.
+
+ :cfunc:`PyOS_ascii_strtod` should typically be used for reading configuration
+ files or other non-user input that should be locale independent.
+
+ .. versionadded:: 2.4
+
+ See the Unix man page :manpage:`strtod(2)` for details.
+
+
+.. cfunction:: char * PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)
+
+ Convert a :ctype:`double` to a string using the ``'.'`` as the decimal
+ separator. *format* is a :cfunc:`printf`\ -style format string specifying the
+ number format. Allowed conversion characters are ``'e'``, ``'E'``, ``'f'``,
+ ``'F'``, ``'g'`` and ``'G'``.
+
+ The return value is a pointer to *buffer* with the converted string or NULL if
+ the conversion failed.
+
+ .. versionadded:: 2.4
+
+
+.. cfunction:: double PyOS_ascii_atof(const char *nptr)
+
+ Convert a string to a :ctype:`double` in a locale-independent way.
+
+ .. versionadded:: 2.4
+
+ See the Unix man page :manpage:`atof(2)` for details.
+
--- /dev/null
+.. highlightlang:: c
+
+
+.. _veryhigh:
+
+*************************
+The Very High Level Layer
+*************************
+
+The functions in this chapter will let you execute Python source code given in a
+file or a buffer, but they will not let you interact in a more detailed way with
+the interpreter.
+
+Several of these functions accept a start symbol from the grammar as a
+parameter. The available start symbols are :const:`Py_eval_input`,
+:const:`Py_file_input`, and :const:`Py_single_input`. These are described
+following the functions which accept them as parameters.
+
+Note also that several of these functions take :ctype:`FILE\*` parameters. On
+particular issue which needs to be handled carefully is that the :ctype:`FILE`
+structure for different C libraries can be different and incompatible. Under
+Windows (at least), it is possible for dynamically linked extensions to actually
+use different libraries, so care should be taken that :ctype:`FILE\*` parameters
+are only passed to these functions if it is certain that they were created by
+the same library that the Python runtime is using.
+
+
+.. cfunction:: int Py_Main(int argc, char **argv)
+
+ The main program for the standard interpreter. This is made available for
+ programs which embed Python. The *argc* and *argv* parameters should be
+ prepared exactly as those which are passed to a C program's :cfunc:`main`
+ function. It is important to note that the argument list may be modified (but
+ the contents of the strings pointed to by the argument list are not). The return
+ value will be the integer passed to the :func:`sys.exit` function, ``1`` if the
+ interpreter exits due to an exception, or ``2`` if the parameter list does not
+ represent a valid Python command line.
+
+
+.. cfunction:: int PyRun_AnyFile(FILE *fp, const char *filename)
+
+ This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving
+ *closeit* set to ``0`` and *flags* set to *NULL*.
+
+
+.. cfunction:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
+
+ This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving
+ the *closeit* argument set to ``0``.
+
+
+.. cfunction:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)
+
+ This is a simplified interface to :cfunc:`PyRun_AnyFileExFlags` below, leaving
+ the *flags* argument set to *NULL*.
+
+
+.. cfunction:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
+
+ If *fp* refers to a file associated with an interactive device (console or
+ terminal input or Unix pseudo-terminal), return the value of
+ :cfunc:`PyRun_InteractiveLoop`, otherwise return the result of
+ :cfunc:`PyRun_SimpleFile`. If *filename* is *NULL*, this function uses
+ ``"???"`` as the filename.
+
+
+.. cfunction:: int PyRun_SimpleString(const char *command)
+
+ This is a simplified interface to :cfunc:`PyRun_SimpleStringFlags` below,
+ leaving the *PyCompilerFlags\** argument set to NULL.
+
+
+.. cfunction:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)
+
+ Executes the Python source code from *command* in the :mod:`__main__` module
+ according to the *flags* argument. If :mod:`__main__` does not already exist, it
+ is created. Returns ``0`` on success or ``-1`` if an exception was raised. If
+ there was an error, there is no way to get the exception information. For the
+ meaning of *flags*, see below.
+
+
+.. cfunction:: int PyRun_SimpleFile(FILE *fp, const char *filename)
+
+ This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below,
+ leaving *closeit* set to ``0`` and *flags* set to *NULL*.
+
+
+.. cfunction:: int PyRun_SimpleFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
+
+ This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below,
+ leaving *closeit* set to ``0``.
+
+
+.. cfunction:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)
+
+ This is a simplified interface to :cfunc:`PyRun_SimpleFileExFlags` below,
+ leaving *flags* set to *NULL*.
+
+
+.. cfunction:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
+
+ Similar to :cfunc:`PyRun_SimpleStringFlags`, but the Python source code is read
+ from *fp* instead of an in-memory string. *filename* should be the name of the
+ file. If *closeit* is true, the file is closed before PyRun_SimpleFileExFlags
+ returns.
+
+
+.. cfunction:: int PyRun_InteractiveOne(FILE *fp, const char *filename)
+
+ This is a simplified interface to :cfunc:`PyRun_InteractiveOneFlags` below,
+ leaving *flags* set to *NULL*.
+
+
+.. cfunction:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
+
+ Read and execute a single statement from a file associated with an interactive
+ device according to the *flags* argument. If *filename* is *NULL*, ``"???"`` is
+ used instead. The user will be prompted using ``sys.ps1`` and ``sys.ps2``.
+ Returns ``0`` when the input was executed successfully, ``-1`` if there was an
+ exception, or an error code from the :file:`errcode.h` include file distributed
+ as part of Python if there was a parse error. (Note that :file:`errcode.h` is
+ not included by :file:`Python.h`, so must be included specifically if needed.)
+
+
+.. cfunction:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)
+
+ This is a simplified interface to :cfunc:`PyRun_InteractiveLoopFlags` below,
+ leaving *flags* set to *NULL*.
+
+
+.. cfunction:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
+
+ Read and execute statements from a file associated with an interactive device
+ until EOF is reached. If *filename* is *NULL*, ``"???"`` is used instead. The
+ user will be prompted using ``sys.ps1`` and ``sys.ps2``. Returns ``0`` at EOF.
+
+
+.. cfunction:: struct _node* PyParser_SimpleParseString(const char *str, int start)
+
+ This is a simplified interface to
+ :cfunc:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set
+ to *NULL* and *flags* set to ``0``.
+
+
+.. cfunction:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags)
+
+ This is a simplified interface to
+ :cfunc:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set
+ to *NULL*.
+
+
+.. cfunction:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags)
+
+ Parse Python source code from *str* using the start token *start* according to
+ the *flags* argument. The result can be used to create a code object which can
+ be evaluated efficiently. This is useful if a code fragment must be evaluated
+ many times.
+
+
+.. cfunction:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)
+
+ This is a simplified interface to :cfunc:`PyParser_SimpleParseFileFlags` below,
+ leaving *flags* set to ``0``
+
+
+.. cfunction:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)
+
+ Similar to :cfunc:`PyParser_SimpleParseStringFlagsFilename`, but the Python
+ source code is read from *fp* instead of an in-memory string.
+
+
+.. cfunction:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
+
+ This is a simplified interface to :cfunc:`PyRun_StringFlags` below, leaving
+ *flags* set to *NULL*.
+
+
+.. cfunction:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
+
+ Execute Python source code from *str* in the context specified by the
+ dictionaries *globals* and *locals* with the compiler flags specified by
+ *flags*. The parameter *start* specifies the start token that should be used to
+ parse the source code.
+
+ Returns the result of executing the code as a Python object, or *NULL* if an
+ exception was raised.
+
+
+.. cfunction:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
+
+ This is a simplified interface to :cfunc:`PyRun_FileExFlags` below, leaving
+ *closeit* set to ``0`` and *flags* set to *NULL*.
+
+
+.. cfunction:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
+
+ This is a simplified interface to :cfunc:`PyRun_FileExFlags` below, leaving
+ *flags* set to *NULL*.
+
+
+.. cfunction:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
+
+ This is a simplified interface to :cfunc:`PyRun_FileExFlags` below, leaving
+ *closeit* set to ``0``.
+
+
+.. cfunction:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
+
+ Similar to :cfunc:`PyRun_StringFlags`, but the Python source code is read from
+ *fp* instead of an in-memory string. *filename* should be the name of the file.
+ If *closeit* is true, the file is closed before :cfunc:`PyRun_FileExFlags`
+ returns.
+
+
+.. cfunction:: PyObject* Py_CompileString(const char *str, const char *filename, int start)
+
+ This is a simplified interface to :cfunc:`Py_CompileStringFlags` below, leaving
+ *flags* set to *NULL*.
+
+
+.. cfunction:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)
+
+ Parse and compile the Python source code in *str*, returning the resulting code
+ object. The start token is given by *start*; this can be used to constrain the
+ code which can be compiled and should be :const:`Py_eval_input`,
+ :const:`Py_file_input`, or :const:`Py_single_input`. The filename specified by
+ *filename* is used to construct the code object and may appear in tracebacks or
+ :exc:`SyntaxError` exception messages. This returns *NULL* if the code cannot
+ be parsed or compiled.
+
+
+.. cvar:: int Py_eval_input
+
+ .. index:: single: Py_CompileString()
+
+ The start symbol from the Python grammar for isolated expressions; for use with
+ :cfunc:`Py_CompileString`.
+
+
+.. cvar:: int Py_file_input
+
+ .. index:: single: Py_CompileString()
+
+ The start symbol from the Python grammar for sequences of statements as read
+ from a file or other source; for use with :cfunc:`Py_CompileString`. This is
+ the symbol to use when compiling arbitrarily long Python source code.
+
+
+.. cvar:: int Py_single_input
+
+ .. index:: single: Py_CompileString()
+
+ The start symbol from the Python grammar for a single statement; for use with
+ :cfunc:`Py_CompileString`. This is the symbol used for the interactive
+ interpreter loop.
+
+
+.. ctype:: struct PyCompilerFlags
+
+ This is the structure used to hold compiler flags. In cases where code is only
+ being compiled, it is passed as ``int flags``, and in cases where code is being
+ executed, it is passed as ``PyCompilerFlags *flags``. In this case, ``from
+ __future__ import`` can modify *flags*.
+
+ Whenever ``PyCompilerFlags *flags`` is *NULL*, :attr:`cf_flags` is treated as
+ equal to ``0``, and any modification due to ``from __future__ import`` is
+ discarded. ::
+
+ struct PyCompilerFlags {
+ int cf_flags;
+ }
+
+
+.. cvar:: int CO_FUTURE_DIVISION
+
+ This bit can be set in *flags* to cause division operator ``/`` to be
+ interpreted as "true division" according to :pep:`238`.
+
--- /dev/null
+# -*- coding: utf-8 -*-
+#
+# Python documentation build configuration file
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+
+# The default replacements for |version| and |release|.
+# If 'auto', Sphinx looks for the Include/patchlevel.h file in the current Python
+# source tree and replaces the values accordingly.
+#
+# The short X.Y version.
+# version = '2.6'
+version = 'auto'
+# The full version, including alpha/beta/rc tags.
+# release = '2.6a0'
+release = 'auto'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# The base URL for download links.
+download_base_url = 'http://docs.python.org/ftp/python/doc/'
+
+# List of files that shouldn't be included in the build.
+unused_files = [
+ 'whatsnew/2.0.rst',
+ 'whatsnew/2.1.rst',
+ 'whatsnew/2.2.rst',
+ 'whatsnew/2.3.rst',
+ 'whatsnew/2.4.rst',
+ 'whatsnew/2.5.rst',
+ 'maclib/scrap.rst',
+ 'library/xmllib.rst',
+ 'library/xml.etree.rst',
+]
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+last_updated_format = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+use_smartypants = True
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True
--- /dev/null
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ Python Documentation contents
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+.. toctree::
+
+ whatsnew/2.6.rst
+ tutorial/index.rst
+ reference/index.rst
+ library/index.rst
+ extending/index.rst
+ c-api/index.rst
+ distutils/index.rst
+ install/index.rst
+ documenting/index.rst
+ howto/index.rst
+
+ about.rst
+ bugs.rst
+ copyright.rst
+ license.rst
--- /dev/null
+*********
+Copyright
+*********
+
+Python and this documentation is:
+
+Copyright © 2001-2007 Python Software Foundation. All rights reserved.
+
+Copyright © 2000 BeOpen.com. All rights reserved.
+
+Copyright © 1995-2000 Corporation for National Research Initiatives. All rights
+reserved.
+
+Copyright © 1991-1995 Stichting Mathematisch Centrum. All rights reserved.
+
+-------
+
+See :ref:`history-and-license` for complete license and permissions information.
+
--- /dev/null
+# Created by Skip Montanaro <skip@mojam.com>.
+
+# Format:
+# function ':' type ':' [param name] ':' [refcount effect] ':' [comment]
+# If the param name slot is empty, that line corresponds to the function's
+# return value, otherwise it's the type of the named parameter.
+
+# The first line of a function block gives type/refcount information for the
+# function's return value. Successive lines with the same function name
+# correspond to the function's parameter list and appear in the order the
+# parameters appear in the function's prototype.
+
+# For readability, each function's lines are surrounded by a blank line.
+# The blocks are sorted alphabetically by function name.
+
+# Refcount behavior is given for all PyObject* types: 0 (no change), +1
+# (increment) and -1 (decrement). A blank refcount field indicates the
+# parameter or function value is not a PyObject* and is therefore not
+# subject to reference counting. A special case for the value "null"
+# (without quotes) is used for functions which return a PyObject* type but
+# always return NULL. This is used by some of the PyErr_*() functions, in
+# particular.
+
+# XXX NOTE: the 0/+1/-1 refcount information for arguments is
+# confusing! Much more useful would be to indicate whether the
+# function "steals" a reference to the argument or not. Take for
+# example PyList_SetItem(list, i, item). This lists as a 0 change for
+# both the list and the item arguments. However, in fact it steals a
+# reference to the item argument!
+
+# The parameter names are as they appear in the API manual, not the source
+# code.
+
+PyBool_FromLong:PyObject*::+1:
+PyBool_FromLong:long:v:0:
+
+PyBuffer_FromObject:PyObject*::+1:
+PyBuffer_FromObject:PyObject*:base:+1:
+PyBuffer_FromObject:int:offset::
+PyBuffer_FromObject:int:size::
+
+PyBuffer_FromReadWriteObject:PyObject*::+1:
+PyBuffer_FromReadWriteObject:PyObject*:base:+1:
+PyBuffer_FromReadWriteObject:int:offset::
+PyBuffer_FromReadWriteObject:int:size::
+
+PyBuffer_FromMemory:PyObject*::+1:
+PyBuffer_FromMemory:void*:ptr::
+PyBuffer_FromMemory:int:size::
+
+PyBuffer_FromReadWriteMemory:PyObject*::+1:
+PyBuffer_FromReadWriteMemory:void*:ptr::
+PyBuffer_FromReadWriteMemory:int:size::
+
+PyBuffer_New:PyObject*::+1:
+PyBuffer_New:int:size::
+
+PyCObject_AsVoidPtr:void*:::
+PyCObject_AsVoidPtr:PyObject*:self:0:
+
+PyCObject_FromVoidPtr:PyObject*::+1:
+PyCObject_FromVoidPtr:void*:cobj::
+PyCObject_FromVoidPtr::void (* destr)(void* )::
+
+PyCObject_FromVoidPtrAndDesc:PyObject*::+1:
+PyCObject_FromVoidPtrAndDesc:void*:cobj::
+PyCObject_FromVoidPtrAndDesc:void*:desc::
+PyCObject_FromVoidPtrAndDesc:void(*)(void*,void*):destr::
+
+PyCObject_GetDesc:void*:::
+PyCObject_GetDesc:PyObject*:self:0:
+
+PyCell_New:PyObject*::+1:
+PyCell_New:PyObject*:ob:0:
+
+PyCell_GET:PyObject*::0:
+PyCell_GET:PyObject*:ob:0:
+
+PyCell_Get:PyObject*::+1:
+PyCell_Get:PyObject*:cell:0:
+
+PyCell_SET:void:::
+PyCell_SET:PyObject*:cell:0:
+PyCell_SET:PyObject*:value:0:
+
+PyCell_Set:int:::
+PyCell_Set:PyObject*:cell:0:
+PyCell_Set:PyObject*:value:0:
+
+PyCallIter_New:PyObject*::+1:
+PyCallIter_New:PyObject*:callable::
+PyCallIter_New:PyObject*:sentinel::
+
+PyCallable_Check:int:::
+PyCallable_Check:PyObject*:o:0:
+
+PyComplex_AsCComplex:Py_complex:::
+PyComplex_AsCComplex:PyObject*:op:0:
+
+PyComplex_Check:int:::
+PyComplex_Check:PyObject*:p:0:
+
+PyComplex_FromCComplex:PyObject*::+1:
+PyComplex_FromCComplex::Py_complex v::
+
+PyComplex_FromDoubles:PyObject*::+1:
+PyComplex_FromDoubles::double real::
+PyComplex_FromDoubles::double imag::
+
+PyComplex_ImagAsDouble:double:::
+PyComplex_ImagAsDouble:PyObject*:op:0:
+
+PyComplex_RealAsDouble:double:::
+PyComplex_RealAsDouble:PyObject*:op:0:
+
+PyDate_FromDate:PyObject*::+1:
+PyDate_FromDate:int:year::
+PyDate_FromDate:int:month::
+PyDate_FromDate:int:day::
+
+PyDate_FromTimestamp:PyObject*::+1:
+PyDate_FromTimestamp:PyObject*:args:0:
+
+PyDateTime_FromDateAndTime:PyObject*::+1:
+PyDateTime_FromDateAndTime:int:year::
+PyDateTime_FromDateAndTime:int:month::
+PyDateTime_FromDateAndTime:int:day::
+PyDateTime_FromDateAndTime:int:hour::
+PyDateTime_FromDateAndTime:int:minute::
+PyDateTime_FromDateAndTime:int:second::
+PyDateTime_FromDateAndTime:int:usecond::
+
+PyDateTime_FromTimestamp:PyObject*::+1:
+PyDateTime_FromTimestamp:PyObject*:args:0:
+
+PyDelta_FromDSU:PyObject*::+1:
+PyDelta_FromDSU:int:days::
+PyDelta_FromDSU:int:seconds::
+PyDelta_FromDSU:int:useconds::
+
+PyDescr_NewClassMethod:PyObject*::+1:
+PyDescr_NewClassMethod:PyTypeObject*:type::
+PyDescr_NewClassMethod:PyMethodDef*:method::
+
+PyDescr_NewGetSet:PyObject*::+1:
+PyDescr_NewGetSet:PyTypeObject*:type::
+PyDescr_NewGetSet:PyGetSetDef*:getset::
+
+PyDescr_NewMember:PyObject*::+1:
+PyDescr_NewMember:PyTypeObject*:type::
+PyDescr_NewMember:PyMemberDef*:member::
+
+PyDescr_NewMethod:PyObject*::+1:
+PyDescr_NewMethod:PyTypeObject*:type::
+PyDescr_NewMethod:PyMethodDef*:meth::
+
+PyDescr_NewWrapper:PyObject*::+1:
+PyDescr_NewWrapper:PyTypeObject*:type::
+PyDescr_NewWrapper:struct wrapperbase*:base::
+PyDescr_NewWrapper:void*:wrapped::
+
+PyDict_Check:int:::
+PyDict_Check:PyObject*:p:0:
+
+PyDict_Clear:void:::
+PyDict_Clear:PyObject*:p:0:
+
+PyDict_DelItem:int:::
+PyDict_DelItem:PyObject*:p:0:
+PyDict_DelItem:PyObject*:key:0:
+
+PyDict_DelItemString:int:::
+PyDict_DelItemString:PyObject*:p:0:
+PyDict_DelItemString:char*:key::
+
+PyDict_GetItem:PyObject*::0:0
+PyDict_GetItem:PyObject*:p:0:
+PyDict_GetItem:PyObject*:key:0:
+
+PyDict_GetItemString:PyObject*::0:
+PyDict_GetItemString:PyObject*:p:0:
+PyDict_GetItemString:char*:key::
+
+PyDict_Items:PyObject*::+1:
+PyDict_Items:PyObject*:p:0:
+
+PyDict_Keys:PyObject*::+1:
+PyDict_Keys:PyObject*:p:0:
+
+PyDict_New:PyObject*::+1:
+
+PyDict_Copy:PyObject*::+1:
+PyDict_Copy:PyObject*:p:0:
+
+PyDict_Next:int:::
+PyDict_Next:PyObject*:p:0:
+PyDict_Next:int:ppos::
+PyDict_Next:PyObject**:pkey:0:
+PyDict_Next:PyObject**:pvalue:0:
+
+PyDict_SetItem:int:::
+PyDict_SetItem:PyObject*:p:0:
+PyDict_SetItem:PyObject*:key:+1:
+PyDict_SetItem:PyObject*:val:+1:
+
+PyDict_SetItemString:int:::
+PyDict_SetItemString:PyObject*:p:0:
+PyDict_SetItemString:char*:key::
+PyDict_SetItemString:PyObject*:val:+1:
+
+PyDict_Size:int:::
+PyDict_Size:PyObject*:p::
+
+PyDict_Values:PyObject*::+1:
+PyDict_Values:PyObject*:p:0:
+
+PyDictProxy_New:PyObject*::+1:
+PyDictProxy_New:PyObject*:dict:0:
+
+PyErr_BadArgument:int:::
+
+PyErr_BadInternalCall:void:::
+
+PyErr_CheckSignals:int:::
+
+PyErr_Clear:void:::
+
+PyErr_ExceptionMatches:int:::
+PyErr_ExceptionMatches:PyObject*:exc:0:
+
+PyErr_Fetch:void:::
+PyErr_Fetch:PyObject**:ptype:0:
+PyErr_Fetch:PyObject**:pvalue:0:
+PyErr_Fetch:PyObject**:ptraceback:0:
+
+PyErr_GivenExceptionMatches:int:::
+PyErr_GivenExceptionMatches:PyObject*:given:0:
+PyErr_GivenExceptionMatches:PyObject*:exc:0:
+
+PyErr_NewException:PyObject*::+1:
+PyErr_NewException:char*:name::
+PyErr_NewException:PyObject*:base:0:
+PyErr_NewException:PyObject*:dict:0:
+
+PyErr_NoMemory:PyObject*::null:
+
+PyErr_NormalizeException:void:::
+PyErr_NormalizeException:PyObject**:exc::???
+PyErr_NormalizeException:PyObject**:val::???
+PyErr_NormalizeException:PyObject**:tb::???
+
+PyErr_Occurred:PyObject*::0:
+
+PyErr_Print:void:::
+
+PyErr_Restore:void:::
+PyErr_Restore:PyObject*:type:-1:
+PyErr_Restore:PyObject*:value:-1:
+PyErr_Restore:PyObject*:traceback:-1:
+
+PyErr_SetExcFromWindowsErr:PyObject*::null:
+PyErr_SetExcFromWindowsErr:PyObject*:type:0:
+PyErr_SetExcFromWindowsErr:int:ierr::
+
+PyErr_SetExcFromWindowsErrWithFilename:PyObject*::null:
+PyErr_SetExcFromWindowsErrWithFilename:PyObject*:type:0:
+PyErr_SetExcFromWindowsErrWithFilename:int:ierr::
+PyErr_SetExcFromWindowsErrWithFilename:char*:filename::
+
+PyErr_SetFromErrno:PyObject*::null:
+PyErr_SetFromErrno:PyObject*:type:0:
+
+PyErr_SetFromErrnoWithFilename:PyObject*::null:
+PyErr_SetFromErrnoWithFilename:PyObject*:type:0:
+PyErr_SetFromErrnoWithFilename:char*:filename::
+
+PyErr_SetFromWindowsErr:PyObject*::null:
+PyErr_SetFromWindowsErr:int:ierr::
+
+PyErr_SetFromWindowsErrWithFilename:PyObject*::null:
+PyErr_SetFromWindowsErrWithFilename:int:ierr::
+PyErr_SetFromWindowsErrWithFilename:char*:filename::
+
+PyErr_SetInterrupt:void:::
+
+PyErr_SetNone:void:::
+PyErr_SetNone:PyObject*:type:+1:
+
+PyErr_SetObject:void:::
+PyErr_SetObject:PyObject*:type:+1:
+PyErr_SetObject:PyObject*:value:+1:
+
+PyErr_SetString:void:::
+PyErr_SetString:PyObject*:type:+1:
+PyErr_SetString:char*:message::
+
+PyErr_Format:PyObject*::null:
+PyErr_Format:PyObject*:exception:+1:
+PyErr_Format:char*:format::
+PyErr_Format::...::
+
+PyErr_Warn:int:::
+PyErr_Warn:PyObject*:category:0:
+PyErr_Warn:char*:message::
+
+PyErr_WarnEx:int:::
+PyErr_WarnEx:PyObject*:category:0:
+PyErr_WarnEx:const char*:message::
+PyErr_WarnEx:Py_ssize_t:stack_level::
+
+PyEval_AcquireLock:void:::
+
+PyEval_AcquireThread:void:::
+PyEval_AcquireThread:PyThreadState*:tstate::
+
+PyEval_InitThreads:void:::
+
+PyEval_ReleaseLock:void:::
+
+PyEval_ReleaseThread:void:::
+PyEval_ReleaseThread:PyThreadState*:tstate::
+
+PyEval_RestoreThread:void:::
+PyEval_RestoreThread:PyThreadState*:tstate::
+
+PyEval_SaveThread:PyThreadState*:::
+
+PyEval_EvalCode:PyObject*::+1:
+PyEval_EvalCode:PyCodeObject*:co:0:
+PyEval_EvalCode:PyObject*:globals:0:
+PyEval_EvalCode:PyObject*:locals:0:
+
+PyFile_AsFile:FILE*:::
+PyFile_AsFile:PyFileObject*:p:0:
+
+PyFile_Check:int:::
+PyFile_Check:PyObject*:p:0:
+
+PyFile_FromFile:PyObject*::+1:
+PyFile_FromFile:FILE*:fp::
+PyFile_FromFile:char*:name::
+PyFile_FromFile:char*:mode::
+PyFile_FromFile:int(*:close)::
+
+PyFile_FromString:PyObject*::+1:
+PyFile_FromString:char*:name::
+PyFile_FromString:char*:mode::
+
+PyFile_GetLine:PyObject*::+1:
+PyFile_GetLine:PyObject*:p::
+PyFile_GetLine:int:n::
+
+PyFile_Name:PyObject*::0:
+PyFile_Name:PyObject*:p:0:
+
+PyFile_SetBufSize:void:::
+PyFile_SetBufSize:PyFileObject*:p:0:
+PyFile_SetBufSize:int:n::
+
+PyFile_SoftSpace:int:::
+PyFile_SoftSpace:PyFileObject*:p:0:
+PyFile_SoftSpace:int:newflag::
+
+PyFile_WriteObject:int:::
+PyFile_WriteObject:PyObject*:obj:0:
+PyFile_WriteObject:PyFileObject*:p:0:
+PyFile_WriteObject:int:flags::
+
+PyFile_WriteString:int:::
+PyFile_WriteString:const char*:s::
+PyFile_WriteString:PyFileObject*:p:0:
+PyFile_WriteString:int:flags::
+
+PyFloat_AS_DOUBLE:double:::
+PyFloat_AS_DOUBLE:PyObject*:pyfloat:0:
+
+PyFloat_AsDouble:double:::
+PyFloat_AsDouble:PyObject*:pyfloat:0:
+
+PyFloat_Check:int:::
+PyFloat_Check:PyObject*:p:0:
+
+PyFloat_FromDouble:PyObject*::+1:
+PyFloat_FromDouble:double:v::
+
+PyFloat_FromString:PyObject*::+1:
+PyFloat_FromString:PyObject*:str:0:
+PyFloat_FromString:char**:pend:0:ignored
+
+PyFrozenSet_New:PyObject*::+1:
+PyFrozenSet_New:PyObject*:iterable:0:
+
+PyFunction_GetClosure:PyObject*::0:
+PyFunction_GetClosure:PyObject*:op:0:
+
+PyFunction_GetCode:PyObject*::0:
+PyFunction_GetCode:PyObject*:op:0:
+
+PyFunction_GetDefaults:PyObject*::0:
+PyFunction_GetDefaults:PyObject*:op:0:
+
+PyFunction_GetGlobals:PyObject*::0:
+PyFunction_GetGlobals:PyObject*:op:0:
+
+PyFunction_GetModule:PyObject*::0:
+PyFunction_GetModule:PyObject*:op:0:
+
+PyFunction_New:PyObject*::+1:
+PyFunction_New:PyObject*:code:+1:
+PyFunction_New:PyObject*:globals:+1:
+
+PyFunction_SetClosure:int:::
+PyFunction_SetClosure:PyObject*:op:0:
+PyFunction_SetClosure:PyObject*:closure:+1:
+
+PyFunction_SetDefaults:int:::
+PyFunction_SetDefaults:PyObject*:op:0:
+PyFunction_SetDefaults:PyObject*:defaults:+1:
+
+PyGen_New:PyObject*::+1:
+PyGen_New:PyFrameObject*:frame:0:
+
+Py_InitModule:PyObject*::0:
+Py_InitModule:char*:name::
+Py_InitModule:PyMethodDef[]:methods::
+
+Py_InitModule3:PyObject*::0:
+Py_InitModule3:char*:name::
+Py_InitModule3:PyMethodDef[]:methods::
+Py_InitModule3:char*:doc::
+
+Py_InitModule4:PyObject*::0:
+Py_InitModule4:char*:name::
+Py_InitModule4:PyMethodDef[]:methods::
+Py_InitModule4:char*:doc::
+Py_InitModule4:PyObject*:self::
+Py_InitModule4:int:apiver::usually provided by Py_InitModule or Py_InitModule3
+
+PyImport_AddModule:PyObject*::0:reference borrowed from sys.modules
+PyImport_AddModule:char*:name::
+
+PyImport_Cleanup:void:::
+
+PyImport_ExecCodeModule:PyObject*::+1:
+PyImport_ExecCodeModule:char*:name::
+PyImport_ExecCodeModule:PyObject*:co:0:
+
+PyImport_GetMagicNumber:long:::
+
+PyImport_GetModuleDict:PyObject*::0:
+
+PyImport_Import:PyObject*::+1:
+PyImport_Import:PyObject*:name:0:
+
+PyImport_ImportFrozenModule:int:::
+PyImport_ImportFrozenModule:char*:::
+
+PyImport_ImportModule:PyObject*::+1:
+PyImport_ImportModule:char*:name::
+
+PyImport_ImportModuleEx:PyObject*::+1:
+PyImport_ImportModuleEx:char*:name::
+PyImport_ImportModuleEx:PyObject*:globals:0:???
+PyImport_ImportModuleEx:PyObject*:locals:0:???
+PyImport_ImportModuleEx:PyObject*:fromlist:0:???
+
+PyImport_ReloadModule:PyObject*::+1:
+PyImport_ReloadModule:PyObject*:m:0:
+
+PyInstance_New:PyObject*::+1:
+PyInstance_New:PyObject*:klass:+1:
+PyInstance_New:PyObject*:arg:0:
+PyInstance_New:PyObject*:kw:0:
+
+PyInstance_NewRaw:PyObject*::+1:
+PyInstance_NewRaw:PyObject*:klass:+1:
+PyInstance_NewRaw:PyObject*:dict:+1:
+
+PyInt_AS_LONG:long:::
+PyInt_AS_LONG:PyIntObject*:io:0:
+
+PyInt_AsLong:long:::
+PyInt_AsLong:PyObject*:io:0:
+
+PyInt_Check:int:::
+PyInt_Check:PyObject*:op:0:
+
+PyInt_FromLong:PyObject*::+1:
+PyInt_FromLong:long:ival::
+
+PyInt_FromString:PyObject*::+1:
+PyInt_FromString:char*:str:0:
+PyInt_FromString:char**:pend:0:
+PyInt_FromString:int:base:0:
+
+PyInt_FromSsize_t:PyObject*::+1:
+PyInt_FromSsize_t:Py_ssize_t:ival::
+
+PyInt_GetMax:long:::
+
+PyInterpreterState_Clear:void:::
+PyInterpreterState_Clear:PyInterpreterState*:interp::
+
+PyInterpreterState_Delete:void:::
+PyInterpreterState_Delete:PyInterpreterState*:interp::
+
+PyInterpreterState_New:PyInterpreterState*:::
+
+PyIter_Check:int:o:0:
+
+PyIter_Next:PyObject*::+1:
+PyIter_Next:PyObject*:o:0:
+
+PyList_Append:int:::
+PyList_Append:PyObject*:list:0:
+PyList_Append:PyObject*:item:+1:
+
+PyList_AsTuple:PyObject*::+1:
+PyList_AsTuple:PyObject*:list:0:
+
+PyList_Check:int:::
+PyList_Check:PyObject*:p:0:
+
+PyList_GET_ITEM:PyObject*::0:
+PyList_GET_ITEM:PyObject*:list:0:
+PyList_GET_ITEM:int:i:0:
+
+PyList_GET_SIZE:int:::
+PyList_GET_SIZE:PyObject*:list:0:
+
+PyList_GetItem:PyObject*::0:
+PyList_GetItem:PyObject*:list:0:
+PyList_GetItem:int:index::
+
+PyList_GetSlice:PyObject*::+1:
+PyList_GetSlice:PyObject*:list:0:
+PyList_GetSlice:int:low::
+PyList_GetSlice:int:high::
+
+PyList_Insert:int:::
+PyList_Insert:PyObject*:list:0:
+PyList_Insert:int:index::
+PyList_Insert:PyObject*:item:+1:
+
+PyList_New:PyObject*::+1:
+PyList_New:int:len::
+
+PyList_Reverse:int:::
+PyList_Reverse:PyObject*:list:0:
+
+PyList_SET_ITEM:void:::
+PyList_SET_ITEM:PyObject*:list:0:
+PyList_SET_ITEM:int:i::
+PyList_SET_ITEM:PyObject*:o:0:
+
+PyList_SetItem:int:::
+PyList_SetItem:PyObject*:list:0:
+PyList_SetItem:int:index::
+PyList_SetItem:PyObject*:item:0:
+
+PyList_SetSlice:int:::
+PyList_SetSlice:PyObject*:list:0:
+PyList_SetSlice:int:low::
+PyList_SetSlice:int:high::
+PyList_SetSlice:PyObject*:itemlist:0:but increfs its elements?
+
+PyList_Size:int:::
+PyList_Size:PyObject*:list:0:
+
+PyList_Sort:int:::
+PyList_Sort:PyObject*:list:0:
+
+PyLong_AsDouble:double:::
+PyLong_AsDouble:PyObject*:pylong:0:
+
+PyLong_AsLong:long:::
+PyLong_AsLong:PyObject*:pylong:0:
+
+PyLong_AsUnsignedLong:unsigned long:::
+PyLong_AsUnsignedLong:PyObject*:pylong:0:
+
+PyLong_Check:int:::
+PyLong_Check:PyObject*:p:0:
+
+PyLong_FromDouble:PyObject*::+1:
+PyLong_FromDouble:double:v::
+
+PyLong_FromLong:PyObject*::+1:
+PyLong_FromLong:long:v::
+
+PyLong_FromLongLong:PyObject*::+1:
+PyLong_FromLongLong:long long:v::
+
+PyLong_FromUnsignedLongLong:PyObject*::+1:
+PyLong_FromUnsignedLongLong:unsigned long long:v::
+
+PyLong_FromString:PyObject*::+1:
+PyLong_FromString:char*:str::
+PyLong_FromString:char**:pend::
+PyLong_FromString:int:base::
+
+PyLong_FromUnicode:PyObject*::+1:
+PyLong_FromUnicode:Py_UNICODE:u::
+PyLong_FromUnicode:int:length::
+PyLong_FromUnicode:int:base::
+
+PyLong_FromUnsignedLong:PyObject*::+1:
+PyLong_FromUnsignedLong:unsignedlong:v::
+
+PyLong_FromVoidPtr:PyObject*::+1:
+PyLong_FromVoidPtr:void*:p::
+
+PyMapping_Check:int:::
+PyMapping_Check:PyObject*:o:0:
+
+PyMapping_DelItem:int:::
+PyMapping_DelItem:PyObject*:o:0:
+PyMapping_DelItem:PyObject*:key:0:
+
+PyMapping_DelItemString:int:::
+PyMapping_DelItemString:PyObject*:o:0:
+PyMapping_DelItemString:char*:key::
+
+PyMapping_GetItemString:PyObject*::+1:
+PyMapping_GetItemString:PyObject*:o:0:
+PyMapping_GetItemString:char*:key::
+
+PyMapping_HasKey:int:::
+PyMapping_HasKey:PyObject*:o:0:
+PyMapping_HasKey:PyObject*:key::
+
+PyMapping_HasKeyString:int:::
+PyMapping_HasKeyString:PyObject*:o:0:
+PyMapping_HasKeyString:char*:key::
+
+PyMapping_Items:PyObject*::+1:
+PyMapping_Items:PyObject*:o:0:
+
+PyMapping_Keys:PyObject*::+1:
+PyMapping_Keys:PyObject*:o:0:
+
+PyMapping_Length:int:::
+PyMapping_Length:PyObject*:o:0:
+
+PyMapping_SetItemString:int:::
+PyMapping_SetItemString:PyObject*:o:0:
+PyMapping_SetItemString:char*:key::
+PyMapping_SetItemString:PyObject*:v:+1:
+
+PyMapping_Values:PyObject*::+1:
+PyMapping_Values:PyObject*:o:0:
+
+PyMarshal_ReadLastObjectFromFile:PyObject*::+1:
+PyMarshal_ReadLastObjectFromFile:FILE*:file::
+
+PyMarshal_ReadObjectFromFile:PyObject*::+1:
+PyMarshal_ReadObjectFromFile:FILE*:file::
+
+PyMarshal_ReadObjectFromString:PyObject*::+1:
+PyMarshal_ReadObjectFromString:char*:string::
+PyMarshal_ReadObjectFromString:int:len::
+
+PyMarshal_WriteObjectToString:PyObject*::+1:
+PyMarshal_WriteObjectToString:PyObject*:value:0:
+
+PyMethod_Class:PyObject*::0:
+PyMethod_Class:PyObject*:im:0:
+
+PyMethod_Function:PyObject*::0:
+PyMethod_Function:PyObject*:im:0:
+
+PyMethod_GET_CLASS:PyObject*::0:
+PyMethod_GET_CLASS:PyObject*:im:0:
+
+PyMethod_GET_FUNCTION:PyObject*::0:
+PyMethod_GET_FUNCTION:PyObject*:im:0:
+
+PyMethod_GET_SELF:PyObject*::0:
+PyMethod_GET_SELF:PyObject*:im:0:
+
+PyMethod_New:PyObject*::+1:
+PyMethod_New:PyObject*:func:0:
+PyMethod_New:PyObject*:self:0:
+PyMethod_New:PyObject*:class:0:
+
+PyMethod_Self:PyObject*::0:
+PyMethod_Self:PyObject*:im:0:
+
+PyModule_GetDict:PyObject*::0:
+PyModule_GetDict::PyObject* module:0:
+
+PyModule_GetFilename:char*:::
+PyModule_GetFilename:PyObject*:module:0:
+
+PyModule_GetName:char*:::
+PyModule_GetName:PyObject*:module:0:
+
+PyModule_New:PyObject*::+1:
+PyModule_New::char* name::
+
+PyNumber_Absolute:PyObject*::+1:
+PyNumber_Absolute:PyObject*:o:0:
+
+PyNumber_Add:PyObject*::+1:
+PyNumber_Add:PyObject*:o1:0:
+PyNumber_Add:PyObject*:o2:0:
+
+PyNumber_And:PyObject*::+1:
+PyNumber_And:PyObject*:o1:0:
+PyNumber_And:PyObject*:o2:0:
+
+PyNumber_Check:PyObject*:o:0:
+PyNumber_Check:int:::
+
+PyNumber_Coerce:int:::
+PyNumber_Coerce:PyObject**:p1:+1:
+PyNumber_Coerce:PyObject**:p2:+1:
+
+PyNumber_Divide:PyObject*::+1:
+PyNumber_Divide:PyObject*:o1:0:
+PyNumber_Divide:PyObject*:o2:0:
+
+PyNumber_Divmod:PyObject*::+1:
+PyNumber_Divmod:PyObject*:o1:0:
+PyNumber_Divmod:PyObject*:o2:0:
+
+PyNumber_Float:PyObject*::+1:
+PyNumber_Float:PyObject*:o:0:
+
+PyNumber_FloorDivide:PyObject*::+1:
+PyNumber_FloorDivide:PyObject*:v:0:
+PyNumber_FloorDivide:PyObject*:w:0:
+
+PyNumber_InPlaceAdd:PyObject*::+1:
+PyNumber_InPlaceAdd:PyObject*:v:0:
+PyNumber_InPlaceAdd:PyObject*:w:0:
+
+PyNumber_InPlaceAnd:PyObject*::+1:
+PyNumber_InPlaceAnd:PyObject*:v:0:
+PyNumber_InPlaceAnd:PyObject*:w:0:
+
+PyNumber_InPlaceDivide:PyObject*::+1:
+PyNumber_InPlaceDivide:PyObject*:v:0:
+PyNumber_InPlaceDivide:PyObject*:w:0:
+
+PyNumber_InPlaceFloorDivide:PyObject*::+1:
+PyNumber_InPlaceFloorDivide:PyObject*:v:0:
+PyNumber_InPlaceFloorDivide:PyObject*:w:0:
+
+PyNumber_InPlaceLshift:PyObject*::+1:
+PyNumber_InPlaceLshift:PyObject*:v:0:
+PyNumber_InPlaceLshift:PyObject*:w:0:
+
+PyNumber_InPlaceMultiply:PyObject*::+1:
+PyNumber_InPlaceMultiply:PyObject*:v:0:
+PyNumber_InPlaceMultiply:PyObject*:w:0:
+
+PyNumber_InPlaceOr:PyObject*::+1:
+PyNumber_InPlaceOr:PyObject*:v:0:
+PyNumber_InPlaceOr:PyObject*:w:0:
+
+PyNumber_InPlacePower:PyObject*::+1:
+PyNumber_InPlacePower:PyObject*:v:0:
+PyNumber_InPlacePower:PyObject*:w:0:
+PyNumber_InPlacePower:PyObject*:z:0:
+
+PyNumber_InPlaceRemainder:PyObject*::+1:
+PyNumber_InPlaceRemainder:PyObject*:v:0:
+PyNumber_InPlaceRemainder:PyObject*:w:0:
+
+PyNumber_InPlaceRshift:PyObject*::+1:
+PyNumber_InPlaceRshift:PyObject*:v:0:
+PyNumber_InPlaceRshift:PyObject*:w:0:
+
+PyNumber_InPlaceSubtract:PyObject*::+1:
+PyNumber_InPlaceSubtract:PyObject*:v:0:
+PyNumber_InPlaceSubtract:PyObject*:w:0:
+
+PyNumber_InPlaceTrueDivide:PyObject*::+1:
+PyNumber_InPlaceTrueDivide:PyObject*:v:0:
+PyNumber_InPlaceTrueDivide:PyObject*:w:0:
+
+PyNumber_InPlaceXor:PyObject*::+1:
+PyNumber_InPlaceXor:PyObject*:v:0:
+PyNumber_InPlaceXor:PyObject*:w:0:
+
+PyNumber_Int:PyObject*::+1:
+PyNumber_Int:PyObject*:o:0:
+
+PyNumber_Invert:PyObject*::+1:
+PyNumber_Invert:PyObject*:o:0:
+
+PyNumber_Long:PyObject*::+1:
+PyNumber_Long:PyObject*:o:0:
+
+PyNumber_Lshift:PyObject*::+1:
+PyNumber_Lshift:PyObject*:o1:0:
+PyNumber_Lshift:PyObject*:o2:0:
+
+PyNumber_Multiply:PyObject*::+1:
+PyNumber_Multiply:PyObject*:o1:0:
+PyNumber_Multiply:PyObject*:o2:0:
+
+PyNumber_Negative:PyObject*::+1:
+PyNumber_Negative:PyObject*:o:0:
+
+PyNumber_Or:PyObject*::+1:
+PyNumber_Or:PyObject*:o1:0:
+PyNumber_Or:PyObject*:o2:0:
+
+PyNumber_Positive:PyObject*::+1:
+PyNumber_Positive:PyObject*:o:0:
+
+PyNumber_Power:PyObject*::+1:
+PyNumber_Power:PyObject*:o1:0:
+PyNumber_Power:PyObject*:o2:0:
+PyNumber_Power:PyObject*:o3:0:
+
+PyNumber_Remainder:PyObject*::+1:
+PyNumber_Remainder:PyObject*:o1:0:
+PyNumber_Remainder:PyObject*:o2:0:
+
+PyNumber_Rshift:PyObject*::+1:
+PyNumber_Rshift:PyObject*:o1:0:
+PyNumber_Rshift:PyObject*:o2:0:
+
+PyNumber_Subtract:PyObject*::+1:
+PyNumber_Subtract:PyObject*:o1:0:
+PyNumber_Subtract:PyObject*:o2:0:
+
+PyNumber_TrueDivide:PyObject*::+1:
+PyNumber_TrueDivide:PyObject*:v:0:
+PyNumber_TrueDivide:PyObject*:w:0:
+
+PyNumber_Xor:PyObject*::+1:
+PyNumber_Xor:PyObject*:o1:0:
+PyNumber_Xor:PyObject*:o2:0:
+
+PyOS_GetLastModificationTime:long:::
+PyOS_GetLastModificationTime:char*:filename::
+
+PyObject_AsFileDescriptor:int:::
+PyObject_AsFileDescriptor:PyObject*:o:0:
+
+PyObject_Call:PyObject*::+1:
+PyObject_Call:PyObject*:callable_object:0:
+PyObject_Call:PyObject*:args:0:
+PyObject_Call:PyObject*:kw:0:
+
+PyObject_CallFunction:PyObject*::+1:
+PyObject_CallFunction:PyObject*:callable_object:0:
+PyObject_CallFunction:char*:format::
+PyObject_CallFunction::...::
+
+PyObject_CallFunctionObjArgs:PyObject*::+1:
+PyObject_CallFunctionObjArgs:PyObject*:callable:0:
+PyObject_CallFunctionObjArgs::...::
+
+PyObject_CallMethod:PyObject*::+1:
+PyObject_CallMethod:PyObject*:o:0:
+PyObject_CallMethod:char*:m::
+PyObject_CallMethod:char*:format::
+PyObject_CallMethod::...::
+
+PyObject_CallMethodObjArgs:PyObject*::+1:
+PyObject_CallMethodObjArgs:PyObject*:o:0:
+PyObject_CallMethodObjArgs:char*:name::
+PyObject_CallMethodObjArgs::...::
+
+PyObject_CallObject:PyObject*::+1:
+PyObject_CallObject:PyObject*:callable_object:0:
+PyObject_CallObject:PyObject*:args:0:
+
+PyObject_Cmp:int:::
+PyObject_Cmp:PyObject*:o1:0:
+PyObject_Cmp:PyObject*:o2:0:
+PyObject_Cmp:int*:result::
+
+PyObject_Compare:int:::
+PyObject_Compare:PyObject*:o1:0:
+PyObject_Compare:PyObject*:o2:0:
+
+PyObject_DelAttr:int:::
+PyObject_DelAttr:PyObject*:o:0:
+PyObject_DelAttr:PyObject*:attr_name:0:
+
+PyObject_DelAttrString:int:::
+PyObject_DelAttrString:PyObject*:o:0:
+PyObject_DelAttrString:char*:attr_name::
+
+PyObject_DelItem:int:::
+PyObject_DelItem:PyObject*:o:0:
+PyObject_DelItem:PyObject*:key:0:
+
+PyObject_Dir:PyObject*::+1:
+PyObject_Dir:PyObject*:o:0:
+
+PyObject_GetAttr:PyObject*::+1:
+PyObject_GetAttr:PyObject*:o:0:
+PyObject_GetAttr:PyObject*:attr_name:0:
+
+PyObject_GetAttrString:PyObject*::+1:
+PyObject_GetAttrString:PyObject*:o:0:
+PyObject_GetAttrString:char*:attr_name::
+
+PyObject_GetItem:PyObject*::+1:
+PyObject_GetItem:PyObject*:o:0:
+PyObject_GetItem:PyObject*:key:0:
+
+PyObject_GetIter:PyObject*::+1:
+PyObject_GetIter:PyObject*:o:0:
+
+PyObject_HasAttr:int:::
+PyObject_HasAttr:PyObject*:o:0:
+PyObject_HasAttr:PyObject*:attr_name:0:
+
+PyObject_HasAttrString:int:::
+PyObject_HasAttrString:PyObject*:o:0:
+PyObject_HasAttrString:char*:attr_name:0:
+
+PyObject_Hash:int:::
+PyObject_Hash:PyObject*:o:0:
+
+PyObject_IsTrue:int:::
+PyObject_IsTrue:PyObject*:o:0:
+
+PyObject_Init:PyObject*::0:
+PyObject_Init:PyObject*:op:0:
+
+PyObject_InitVar:PyVarObject*::0:
+PyObject_InitVar:PyVarObject*:op:0:
+
+PyObject_Length:int:::
+PyObject_Length:PyObject*:o:0:
+
+PyObject_NEW:PyObject*::+1:
+
+PyObject_New:PyObject*::+1:
+
+PyObject_NEW_VAR:PyObject*::+1:
+
+PyObject_NewVar:PyObject*::+1:
+
+PyObject_Print:int:::
+PyObject_Print:PyObject*:o:0:
+PyObject_Print:FILE*:fp::
+PyObject_Print:int:flags::
+
+PyObject_Repr:PyObject*::+1:
+PyObject_Repr:PyObject*:o:0:
+
+PyObject_RichCompare:PyObject*::+1:
+PyObject_RichCompare:PyObject*:o1:0:
+PyObject_RichCompare:PyObject*:o2:0:
+PyObject_RichCompare:int:opid::
+
+PyObject_RichCompareBool:int:::
+PyObject_RichCompareBool:PyObject*:o1:0:
+PyObject_RichCompareBool:PyObject*:o2:0:
+PyObject_RichCompareBool:int:opid::
+
+PyObject_SetAttr:int:::
+PyObject_SetAttr:PyObject*:o:0:
+PyObject_SetAttr:PyObject*:attr_name:0:
+PyObject_SetAttr:PyObject*:v:+1:
+
+PyObject_SetAttrString:int:::
+PyObject_SetAttrString:PyObject*:o:0:
+PyObject_SetAttrString:char*:attr_name::
+PyObject_SetAttrString:PyObject*:v:+1:
+
+PyObject_SetItem:int:::
+PyObject_SetItem:PyObject*:o:0:
+PyObject_SetItem:PyObject*:key:0:
+PyObject_SetItem:PyObject*:v:+1:
+
+PyObject_Str:PyObject*::+1:
+PyObject_Str:PyObject*:o:0:
+
+PyObject_Type:PyObject*::+1:
+PyObject_Type:PyObject*:o:0:
+
+PyObject_Unicode:PyObject*::+1:
+PyObject_Unicode:PyObject*:o:0:
+
+PyParser_SimpleParseFile:struct _node*:::
+PyParser_SimpleParseFile:FILE*:fp::
+PyParser_SimpleParseFile:char*:filename::
+PyParser_SimpleParseFile:int:start::
+
+PyParser_SimpleParseString:struct _node*:::
+PyParser_SimpleParseString:char*:str::
+PyParser_SimpleParseString:int:start::
+
+PyRun_AnyFile:int:::
+PyRun_AnyFile:FILE*:fp::
+PyRun_AnyFile:char*:filename::
+
+PyRun_File:PyObject*::+1:??? -- same as eval_code2()
+PyRun_File:FILE*:fp::
+PyRun_File:char*:filename::
+PyRun_File:int:start::
+PyRun_File:PyObject*:globals:0:
+PyRun_File:PyObject*:locals:0:
+
+PyRun_FileEx:PyObject*::+1:??? -- same as eval_code2()
+PyRun_FileEx:FILE*:fp::
+PyRun_FileEx:char*:filename::
+PyRun_FileEx:int:start::
+PyRun_FileEx:PyObject*:globals:0:
+PyRun_FileEx:PyObject*:locals:0:
+PyRun_FileEx:int:closeit::
+
+PyRun_FileFlags:PyObject*::+1:??? -- same as eval_code2()
+PyRun_FileFlags:FILE*:fp::
+PyRun_FileFlags:char*:filename::
+PyRun_FileFlags:int:start::
+PyRun_FileFlags:PyObject*:globals:0:
+PyRun_FileFlags:PyObject*:locals:0:
+PyRun_FileFlags:PyCompilerFlags*:flags::
+
+PyRun_FileExFlags:PyObject*::+1:??? -- same as eval_code2()
+PyRun_FileExFlags:FILE*:fp::
+PyRun_FileExFlags:char*:filename::
+PyRun_FileExFlags:int:start::
+PyRun_FileExFlags:PyObject*:globals:0:
+PyRun_FileExFlags:PyObject*:locals:0:
+PyRun_FileExFlags:int:closeit::
+PyRun_FileExFlags:PyCompilerFlags*:flags::
+
+PyRun_InteractiveLoop:int:::
+PyRun_InteractiveLoop:FILE*:fp::
+PyRun_InteractiveLoop:char*:filename::
+
+PyRun_InteractiveOne:int:::
+PyRun_InteractiveOne:FILE*:fp::
+PyRun_InteractiveOne:char*:filename::
+
+PyRun_SimpleFile:int:::
+PyRun_SimpleFile:FILE*:fp::
+PyRun_SimpleFile:char*:filename::
+
+PyRun_SimpleString:int:::
+PyRun_SimpleString:char*:command::
+
+PyRun_String:PyObject*::+1:??? -- same as eval_code2()
+PyRun_String:char*:str::
+PyRun_String:int:start::
+PyRun_String:PyObject*:globals:0:
+PyRun_String:PyObject*:locals:0:
+
+PyRun_StringFlags:PyObject*::+1:??? -- same as eval_code2()
+PyRun_StringFlags:char*:str::
+PyRun_StringFlags:int:start::
+PyRun_StringFlags:PyObject*:globals:0:
+PyRun_StringFlags:PyObject*:locals:0:
+PyRun_StringFlags:PyCompilerFlags*:flags::
+
+PySeqIter_New:PyObject*::+1:
+PySeqIter_New:PyObject*:seq::
+
+PySequence_Check:int:::
+PySequence_Check:PyObject*:o:0:
+
+PySequence_Concat:PyObject*::+1:
+PySequence_Concat:PyObject*:o1:0:
+PySequence_Concat:PyObject*:o2:0:
+
+PySequence_Count:int:::
+PySequence_Count:PyObject*:o:0:
+PySequence_Count:PyObject*:value:0:
+
+PySequence_DelItem:int:::
+PySequence_DelItem:PyObject*:o:0:
+PySequence_DelItem:int:i::
+
+PySequence_DelSlice:int:::
+PySequence_DelSlice:PyObject*:o:0:
+PySequence_DelSlice:int:i1::
+PySequence_DelSlice:int:i2::
+
+PySequence_Fast:PyObject*::+1:
+PySequence_Fast:PyObject*:v:0:
+PySequence_Fast:const char*:m::
+
+PySequence_Fast_GET_ITEM:PyObject*::0:
+PySequence_Fast_GET_ITEM:PyObject*:o:0:
+PySequence_Fast_GET_ITEM:int:i::
+
+PySequence_GetItem:PyObject*::+1:
+PySequence_GetItem:PyObject*:o:0:
+PySequence_GetItem:int:i::
+
+PySequence_GetSlice:PyObject*::+1:
+PySequence_GetSlice:PyObject*:o:0:
+PySequence_GetSlice:int:i1::
+PySequence_GetSlice:int:i2::
+
+PySequence_In:int:::
+PySequence_In:PyObject*:o:0:
+PySequence_In:PyObject*:value:0:
+
+PySequence_Index:int:::
+PySequence_Index:PyObject*:o:0:
+PySequence_Index:PyObject*:value:0:
+
+PySequence_InPlaceConcat:PyObject*::+1:
+PySequence_InPlaceConcat:PyObject*:s:0:
+PySequence_InPlaceConcat:PyObject*:o:0:
+
+PySequence_InPlaceRepeat:PyObject*::+1:
+PySequence_InPlaceRepeat:PyObject*:s:0:
+PySequence_InPlaceRepeat:PyObject*:o:0:
+
+PySequence_ITEM:PyObject*::+1:
+PySequence_ITEM:PyObject*:o:0:
+PySequence_ITEM:int:i::
+
+PySequence_Repeat:PyObject*::+1:
+PySequence_Repeat:PyObject*:o:0:
+PySequence_Repeat:int:count::
+
+PySequence_SetItem:int:::
+PySequence_SetItem:PyObject*:o:0:
+PySequence_SetItem:int:i::
+PySequence_SetItem:PyObject*:v:+1:
+
+PySequence_SetSlice:int:::
+PySequence_SetSlice:PyObject*:o:0:
+PySequence_SetSlice:int:i1::
+PySequence_SetSlice:int:i2::
+PySequence_SetSlice:PyObject*:v:+1:
+
+PySequence_List:PyObject*::+1:
+PySequence_List:PyObject*:o:0:
+
+PySequence_Tuple:PyObject*::+1:
+PySequence_Tuple:PyObject*:o:0:
+
+PySet_Append:int:::
+PySet_Append:PyObject*:set:0:
+PySet_Append:PyObject*:key:+1:
+
+PySet_Contains:int:::
+PySet_Contains:PyObject*:anyset:0:
+PySet_Contains:PyObject*:key:0:
+
+PySet_Discard:int:::
+PySet_Discard:PyObject*:set:0:
+PySet_Discard:PyObject*:key:-1:no effect if key not found
+
+PySet_New:PyObject*::+1:
+PySet_New:PyObject*:iterable:0:
+
+PySet_Pop:PyObject*::+1:or returns NULL and raises KeyError if set is empty
+PySet_Pop:PyObject*:set:0:
+
+PySet_Size:int:::
+PySet_Size:PyObject*:anyset:0:
+
+PySlice_Check:int:::
+PySlice_Check:PyObject*:ob:0:
+
+PySlice_New:PyObject*::+1:
+PySlice_New:PyObject*:start:0:
+PySlice_New:PyObject*:stop:0:
+PySlice_New:PyObject*:step:0:
+
+PyString_AS_STRING:char*:::
+PyString_AS_STRING:PyObject*:string:0:
+
+PyString_AsDecodedObject:PyObject*::+1:
+PyString_AsDecodedObject:PyObject*:str:0:
+PyString_AsDecodedObject:const char*:encoding::
+PyString_AsDecodedObject:const char*:errors::
+
+PyString_AsEncodedObject:PyObject*::+1:
+PyString_AsEncodedObject:PyObject*:str:0:
+PyString_AsEncodedObject:const char*:encoding::
+PyString_AsEncodedObject:const char*:errors::
+
+PyString_AsString:char*:::
+PyString_AsString:PyObject*:string:0:
+
+PyString_AsStringAndSize:int:::
+PyString_AsStringAndSize:PyObject*:obj:0:
+PyString_AsStringAndSize:char**:buffer::
+PyString_AsStringAndSize:int*:length::
+
+PyString_Check:int:::
+PyString_Check:PyObject*:o:0:
+
+PyString_Concat:void:::
+PyString_Concat:PyObject**:string:0:??? -- replaces w/ new string or NULL
+PyString_Concat:PyObject*:newpart:0:
+
+PyString_ConcatAndDel:void:::
+PyString_ConcatAndDel:PyObject**:string:0:??? -- replaces w/ new string or NULL
+PyString_ConcatAndDel:PyObject*:newpart:-1:
+
+PyString_Format:PyObject*::+1:
+PyString_Format:PyObject*:format:0:
+PyString_Format:PyObject*:args:0:
+
+PyString_FromString:PyObject*::+1:
+PyString_FromString:const char*:v::
+
+PyString_FromStringAndSize:PyObject*::+1:
+PyString_FromStringAndSize:const char*:v::
+PyString_FromStringAndSize:int:len::
+
+PyString_FromFormat:PyObject*::+1:
+PyString_FromFormat:const char*:format::
+PyString_FromFormat::...::
+
+PyString_FromFormatV:PyObject*::+1:
+PyString_FromFormatV:const char*:format::
+PyString_FromFormatV:va_list:vargs::
+
+PyString_GET_SIZE:int:::
+PyString_GET_SIZE:PyObject*:string:0:
+
+PyString_InternFromString:PyObject*::+1:
+PyString_InternFromString:const char*:v::
+
+PyString_InternInPlace:void:::
+PyString_InternInPlace:PyObject**:string:+1:???
+
+PyString_Size:int:::
+PyString_Size:PyObject*:string:0:
+
+PyString_Decode:PyObject*::+1:
+PyString_Decode:const char*:s::
+PyString_Decode:int:size::
+PyString_Decode:const char*:encoding::
+PyString_Decode:const char*:errors::
+
+PyString_Encode:PyObject*::+1:
+PyString_Encode:const char*:s::
+PyString_Encode:int:size::
+PyString_Encode:const char*:encoding::
+PyString_Encode:const char*:errors::
+
+PyString_AsEncodedString:PyObject*::+1:
+PyString_AsEncodedString:PyObject*:str::
+PyString_AsEncodedString:const char*:encoding::
+PyString_AsEncodedString:const char*:errors::
+
+PySys_SetArgv:int:::
+PySys_SetArgv:int:argc::
+PySys_SetArgv:char**:argv::
+
+PyThreadState_Clear:void:::
+PyThreadState_Clear:PyThreadState*:tstate::
+
+PyThreadState_Delete:void:::
+PyThreadState_Delete:PyThreadState*:tstate::
+
+PyThreadState_Get:PyThreadState*:::
+
+PyThreadState_GetDict:PyObject*::0:
+
+PyThreadState_New:PyThreadState*:::
+PyThreadState_New:PyInterpreterState*:interp::
+
+PyThreadState_Swap:PyThreadState*:::
+PyThreadState_Swap:PyThreadState*:tstate::
+
+PyTime_FromTime:PyObject*::+1:
+PyTime_FromTime:int:hour::
+PyTime_FromTime:int:minute::
+PyTime_FromTime:int:second::
+PyTime_FromTime:int:usecond::
+
+PyTuple_Check:int:::
+PyTuple_Check:PyObject*:p:0:
+
+PyTuple_GET_ITEM:PyObject*::0:
+PyTuple_GET_ITEM:PyTupleObject*:p:0:
+PyTuple_GET_ITEM:int:pos::
+
+PyTuple_GetItem:PyObject*::0:
+PyTuple_GetItem:PyTupleObject*:p:0:
+PyTuple_GetItem:int:pos::
+
+PyTuple_GetSlice:PyObject*::+1:
+PyTuple_GetSlice:PyTupleObject*:p:0:
+PyTuple_GetSlice:int:low::
+PyTuple_GetSlice:int:high::
+
+PyTuple_New:PyObject*::+1:
+PyTuple_New:int:len::
+
+PyTuple_Pack:PyObject*::+1:
+PyTuple_Pack:int:len::
+PyTuple_Pack:PyObject*:...:0:
+
+PyTuple_SET_ITEM:void:::
+PyTuple_SET_ITEM:PyTupleObject*:p:0:
+PyTuple_SET_ITEM:int:pos::
+PyTuple_SET_ITEM:PyObject*:o:0:
+
+PyTuple_SetItem:int:::
+PyTuple_SetItem:PyTupleObject*:p:0:
+PyTuple_SetItem:int:pos::
+PyTuple_SetItem:PyObject*:o:0:
+
+PyTuple_Size:int:::
+PyTuple_Size:PyTupleObject*:p:0:
+
+PyType_GenericAlloc:PyObject*::+1:
+PyType_GenericAlloc:PyObject*:type:0:
+PyType_GenericAlloc:int:nitems:0:
+
+PyType_GenericNew:PyObject*::+1:
+PyType_GenericNew:PyObject*:type:0:
+PyType_GenericNew:PyObject*:args:0:
+PyType_GenericNew:PyObject*:kwds:0:
+
+PyUnicode_Check:int:::
+PyUnicode_Check:PyObject*:o:0:
+
+PyUnicode_GET_SIZE:int:::
+PyUnicode_GET_SIZE:PyObject*:o:0:
+
+PyUnicode_GET_DATA_SIZE:int:::
+PyUnicode_GET_DATA_SIZE:PyObject*:o:0:
+
+PyUnicode_AS_UNICODE:Py_UNICODE*:::
+PyUnicode_AS_UNICODE:PyObject*:o:0:
+
+PyUnicode_AS_DATA:const char*:::
+PyUnicode_AS_DATA:PyObject*:o:0:
+
+Py_UNICODE_ISSPACE:int:::
+Py_UNICODE_ISSPACE:Py_UNICODE:ch::
+
+Py_UNICODE_ISLOWER:int:::
+Py_UNICODE_ISLOWER:Py_UNICODE:ch::
+
+Py_UNICODE_ISUPPER:int:::
+Py_UNICODE_ISUPPER:Py_UNICODE:ch::
+
+Py_UNICODE_ISTITLE:int:::
+Py_UNICODE_ISTITLE:Py_UNICODE:ch::
+
+Py_UNICODE_ISLINEBREAK:int:::
+Py_UNICODE_ISLINEBREAK:Py_UNICODE:ch::
+
+Py_UNICODE_ISDECIMAL:int:::
+Py_UNICODE_ISDECIMAL:Py_UNICODE:ch::
+
+Py_UNICODE_ISDIGIT:int:::
+Py_UNICODE_ISDIGIT:Py_UNICODE:ch::
+
+Py_UNICODE_ISNUMERIC:int:::
+Py_UNICODE_ISNUMERIC:Py_UNICODE:ch::
+
+Py_UNICODE_TOLOWER:Py_UNICODE:::
+Py_UNICODE_TOLOWER:Py_UNICODE:ch::
+
+Py_UNICODE_TOUPPER:Py_UNICODE:::
+Py_UNICODE_TOUPPER:Py_UNICODE:ch::
+
+Py_UNICODE_TOTITLE:Py_UNICODE:::
+Py_UNICODE_TOTITLE:Py_UNICODE:ch::
+
+Py_UNICODE_TODECIMAL:int:::
+Py_UNICODE_TODECIMAL:Py_UNICODE:ch::
+
+Py_UNICODE_TODIGIT:int:::
+Py_UNICODE_TODIGIT:Py_UNICODE:ch::
+
+Py_UNICODE_TONUMERIC:double:::
+Py_UNICODE_TONUMERIC:Py_UNICODE:ch::
+
+PyUnicode_FromUnicode:PyObject*::+1:
+PyUnicode_FromUnicode:const Py_UNICODE*:u::
+PyUnicode_FromUnicode:int:size::
+
+PyUnicode_AsUnicode:Py_UNICODE*:::
+PyUnicode_AsUnicode:PyObject :*unicode:0:
+
+PyUnicode_GetSize:int:::
+PyUnicode_GetSize:PyObject :*unicode:0:
+
+PyUnicode_FromObject:PyObject*::+1:
+PyUnicode_FromObject:PyObject*:*obj:0:
+
+PyUnicode_FromEncodedObject:PyObject*::+1:
+PyUnicode_FromEncodedObject:PyObject*:*obj:0:
+PyUnicode_FromEncodedObject:const char*:encoding::
+PyUnicode_FromEncodedObject:const char*:errors::
+
+PyUnicode_FromWideChar:PyObject*::+1:
+PyUnicode_FromWideChar:const wchar_t*:w::
+PyUnicode_FromWideChar:int:size::
+
+PyUnicode_AsWideChar:int:::
+PyUnicode_AsWideChar:PyObject*:*unicode:0:
+PyUnicode_AsWideChar:wchar_t*:w::
+PyUnicode_AsWideChar:int:size::
+
+PyUnicode_Decode:PyObject*::+1:
+PyUnicode_Decode:const char*:s::
+PyUnicode_Decode:int:size::
+PyUnicode_Decode:const char*:encoding::
+PyUnicode_Decode:const char*:errors::
+
+PyUnicode_DecodeUTF16Stateful:PyObject*::+1:
+PyUnicode_DecodeUTF16Stateful:const char*:s::
+PyUnicode_DecodeUTF16Stateful:int:size::
+PyUnicode_DecodeUTF16Stateful:const char*:errors::
+PyUnicode_DecodeUTF16Stateful:int*:byteorder::
+PyUnicode_DecodeUTF16Stateful:int*:consumed::
+
+PyUnicode_DecodeUTF8Stateful:PyObject*::+1:
+PyUnicode_DecodeUTF8Stateful:const char*:s::
+PyUnicode_DecodeUTF8Stateful:int:size::
+PyUnicode_DecodeUTF8Stateful:const char*:errors::
+PyUnicode_DecodeUTF8Stateful:int*:consumed::
+
+PyUnicode_Encode:PyObject*::+1:
+PyUnicode_Encode:const Py_UNICODE*:s::
+PyUnicode_Encode:int:size::
+PyUnicode_Encode:const char*:encoding::
+PyUnicode_Encode:const char*:errors::
+
+PyUnicode_AsEncodedString:PyObject*::+1:
+PyUnicode_AsEncodedString:PyObject*:unicode::
+PyUnicode_AsEncodedString:const char*:encoding::
+PyUnicode_AsEncodedString:const char*:errors::
+
+PyUnicode_DecodeUTF8:PyObject*::+1:
+PyUnicode_DecodeUTF8:const char*:s::
+PyUnicode_DecodeUTF8:int:size::
+PyUnicode_DecodeUTF8:const char*:errors::
+
+PyUnicode_EncodeUTF8:PyObject*::+1:
+PyUnicode_EncodeUTF8:const Py_UNICODE*:s::
+PyUnicode_EncodeUTF8:int:size::
+PyUnicode_EncodeUTF8:const char*:errors::
+
+PyUnicode_AsUTF8String:PyObject*::+1:
+PyUnicode_AsUTF8String:PyObject*:unicode::
+
+PyUnicode_DecodeUTF16:PyObject*::+1:
+PyUnicode_DecodeUTF16:const char*:s::
+PyUnicode_DecodeUTF16:int:size::
+PyUnicode_DecodeUTF16:const char*:errors::
+PyUnicode_DecodeUTF16:int*:byteorder::
+
+PyUnicode_EncodeUTF16:PyObject*::+1:
+PyUnicode_EncodeUTF16:const Py_UNICODE*:s::
+PyUnicode_EncodeUTF16:int:size::
+PyUnicode_EncodeUTF16:const char*:errors::
+PyUnicode_EncodeUTF16:int:byteorder::
+
+PyUnicode_AsUTF16String:PyObject*::+1:
+PyUnicode_AsUTF16String:PyObject*:unicode::
+
+PyUnicode_DecodeUnicodeEscape:PyObject*::+1:
+PyUnicode_DecodeUnicodeEscape:const char*:s::
+PyUnicode_DecodeUnicodeEscape:int:size::
+PyUnicode_DecodeUnicodeEscape:const char*:errors::
+
+PyUnicode_EncodeUnicodeEscape:PyObject*::+1:
+PyUnicode_EncodeUnicodeEscape:const Py_UNICODE*:s::
+PyUnicode_EncodeUnicodeEscape:int:size::
+PyUnicode_EncodeUnicodeEscape:const char*:errors::
+
+PyUnicode_AsUnicodeEscapeString:PyObject*::+1:
+PyUnicode_AsUnicodeEscapeString:PyObject*:unicode::
+
+PyUnicode_DecodeRawUnicodeEscape:PyObject*::+1:
+PyUnicode_DecodeRawUnicodeEscape:const char*:s::
+PyUnicode_DecodeRawUnicodeEscape:int:size::
+PyUnicode_DecodeRawUnicodeEscape:const char*:errors::
+
+PyUnicode_EncodeRawUnicodeEscape:PyObject*::+1:
+PyUnicode_EncodeRawUnicodeEscape:const Py_UNICODE*:s::
+PyUnicode_EncodeRawUnicodeEscape:int:size::
+PyUnicode_EncodeRawUnicodeEscape:const char*:errors::
+
+PyUnicode_AsRawUnicodeEscapeString:PyObject*::+1:
+PyUnicode_AsRawUnicodeEscapeString:PyObject*:unicode::
+
+PyUnicode_DecodeLatin1:PyObject*::+1:
+PyUnicode_DecodeLatin1:const char*:s::
+PyUnicode_DecodeLatin1:int:size::
+PyUnicode_DecodeLatin1:const char*:errors::
+
+PyUnicode_EncodeLatin1:PyObject*::+1:
+PyUnicode_EncodeLatin1:const Py_UNICODE*:s::
+PyUnicode_EncodeLatin1:int:size::
+PyUnicode_EncodeLatin1:const char*:errors::
+
+PyUnicode_AsLatin1String:PyObject*::+1:
+PyUnicode_AsLatin1String:PyObject*:unicode::
+
+PyUnicode_DecodeASCII:PyObject*::+1:
+PyUnicode_DecodeASCII:const char*:s::
+PyUnicode_DecodeASCII:int:size::
+PyUnicode_DecodeASCII:const char*:errors::
+
+PyUnicode_EncodeASCII:PyObject*::+1:
+PyUnicode_EncodeASCII:const Py_UNICODE*:s::
+PyUnicode_EncodeASCII:int:size::
+PyUnicode_EncodeASCII:const char*:errors::
+
+PyUnicode_AsASCIIString:PyObject*::+1:
+PyUnicode_AsASCIIString:PyObject*:unicode::
+
+PyUnicode_DecodeCharmap:PyObject*::+1:
+PyUnicode_DecodeCharmap:const char*:s::
+PyUnicode_DecodeCharmap:int:size::
+PyUnicode_DecodeCharmap:PyObject*:mapping:0:
+PyUnicode_DecodeCharmap:const char*:errors::
+
+PyUnicode_EncodeCharmap:PyObject*::+1:
+PyUnicode_EncodeCharmap:const Py_UNICODE*:s::
+PyUnicode_EncodeCharmap:int:size::
+PyUnicode_EncodeCharmap:PyObject*:mapping:0:
+PyUnicode_EncodeCharmap:const char*:errors::
+
+PyUnicode_AsCharmapString:PyObject*::+1:
+PyUnicode_AsCharmapString:PyObject*:unicode:0:
+PyUnicode_AsCharmapString:PyObject*:mapping:0:
+
+PyUnicode_TranslateCharmap:PyObject*::+1:
+PyUnicode_TranslateCharmap:const Py_UNICODE*:s::
+PyUnicode_TranslateCharmap:int:size::
+PyUnicode_TranslateCharmap:PyObject*:table:0:
+PyUnicode_TranslateCharmap:const char*:errors::
+
+PyUnicode_DecodeMBCS:PyObject*::+1:
+PyUnicode_DecodeMBCS:const char*:s::
+PyUnicode_DecodeMBCS:int:size::
+PyUnicode_DecodeMBCS:const char*:errors::
+
+PyUnicode_EncodeMBCS:PyObject*::+1:
+PyUnicode_EncodeMBCS:const Py_UNICODE*:s::
+PyUnicode_EncodeMBCS:int:size::
+PyUnicode_EncodeMBCS:const char*:errors::
+
+PyUnicode_AsMBCSString:PyObject*::+1:
+PyUnicode_AsMBCSString:PyObject*:unicode::
+
+PyUnicode_Concat:PyObject*::+1:
+PyUnicode_Concat:PyObject*:left:0:
+PyUnicode_Concat:PyObject*:right:0:
+
+PyUnicode_Split:PyObject*::+1:
+PyUnicode_Split:PyObject*:left:0:
+PyUnicode_Split:PyObject*:right:0:
+PyUnicode_Split:int:maxsplit::
+
+PyUnicode_Splitlines:PyObject*::+1:
+PyUnicode_Splitlines:PyObject*:s:0:
+PyUnicode_Splitlines:int:maxsplit::
+
+PyUnicode_Translate:PyObject*::+1:
+PyUnicode_Translate:PyObject*:str:0:
+PyUnicode_Translate:PyObject*:table:0:
+PyUnicode_Translate:const char*:errors::
+
+PyUnicode_Join:PyObject*::+1:
+PyUnicode_Join:PyObject*:separator:0:
+PyUnicode_Join:PyObject*:seq:0:
+
+PyUnicode_Tailmatch:PyObject*::+1:
+PyUnicode_Tailmatch:PyObject*:str:0:
+PyUnicode_Tailmatch:PyObject*:substr:0:
+PyUnicode_Tailmatch:int:start::
+PyUnicode_Tailmatch:int:end::
+PyUnicode_Tailmatch:int:direction::
+
+PyUnicode_Find:int:::
+PyUnicode_Find:PyObject*:str:0:
+PyUnicode_Find:PyObject*:substr:0:
+PyUnicode_Find:int:start::
+PyUnicode_Find:int:end::
+PyUnicode_Find:int:direction::
+
+PyUnicode_Count:int:::
+PyUnicode_Count:PyObject*:str:0:
+PyUnicode_Count:PyObject*:substr:0:
+PyUnicode_Count:int:start::
+PyUnicode_Count:int:end::
+
+PyUnicode_Replace:PyObject*::+1:
+PyUnicode_Replace:PyObject*:str:0:
+PyUnicode_Replace:PyObject*:substr:0:
+PyUnicode_Replace:PyObject*:replstr:0:
+PyUnicode_Replace:int:maxcount::
+
+PyUnicode_Compare:int:::
+PyUnicode_Compare:PyObject*:left:0:
+PyUnicode_Compare:PyObject*:right:0:
+
+PyUnicode_Format:PyObject*::+1:
+PyUnicode_Format:PyObject*:format:0:
+PyUnicode_Format:PyObject*:args:0:
+
+PyUnicode_Contains:int:::
+PyUnicode_Contains:PyObject*:container:0:
+PyUnicode_Contains:PyObject*:element:0:
+
+PyWeakref_GET_OBJECT:PyObject*::0:
+PyWeakref_GET_OBJECT:PyObject*:ref:0:
+
+PyWeakref_GetObject:PyObject*::0:
+PyWeakref_GetObject:PyObject*:ref:0:
+
+PyWeakref_NewProxy:PyObject*::+1:
+PyWeakref_NewProxy:PyObject*:ob:0:
+PyWeakref_NewProxy:PyObject*:callback:0:
+
+PyWeakref_NewRef:PyObject*::+1:
+PyWeakref_NewRef:PyObject*:ob:0:
+PyWeakref_NewRef:PyObject*:callback:0:
+
+PyWrapper_New:PyObject*::+1:
+PyWrapper_New:PyObject*:d:0:
+PyWrapper_New:PyObject*:self:0:
+
+Py_AtExit:int:::
+Py_AtExit:void (*)():func::
+
+Py_BuildValue:PyObject*::+1:
+Py_BuildValue:char*:format::
+
+Py_CompileString:PyObject*::+1:
+Py_CompileString:char*:str::
+Py_CompileString:char*:filename::
+Py_CompileString:int:start::
+
+Py_CompileStringFlags:PyObject*::+1:
+Py_CompileStringFlags:char*:str::
+Py_CompileStringFlags:char*:filename::
+Py_CompileStringFlags:int:start::
+Py_CompileStringFlags:PyCompilerFlags*:flags::
+
+Py_DECREF:void:::
+Py_DECREF:PyObject*:o:-1:
+
+Py_EndInterpreter:void:::
+Py_EndInterpreter:PyThreadState*:tstate::
+
+Py_Exit:void:::
+Py_Exit:int:status::
+
+Py_FatalError:void:::
+Py_FatalError:char*:message::
+
+Py_FdIsInteractive:int:::
+Py_FdIsInteractive:FILE*:fp::
+Py_FdIsInteractive:char*:filename::
+
+Py_Finalize:void:::
+
+Py_FindMethod:PyObject*::+1:
+Py_FindMethod:PyMethodDef[]:methods::
+Py_FindMethod:PyObject*:self:+1:
+Py_FindMethod:char*:name::
+
+Py_GetBuildInfoconst:char*:::
+
+Py_GetCompilerconst:char*:::
+
+Py_GetCopyrightconst:char*:::
+
+Py_GetExecPrefix:char*:::
+
+Py_GetPath:char*:::
+
+Py_GetPlatformconst:char*:::
+
+Py_GetPrefix:char*:::
+
+Py_GetProgramFullPath:char*:::
+
+Py_GetProgramName:char*:::
+
+Py_GetVersionconst:char*:::
+
+Py_INCREF:void:::
+Py_INCREF:PyObject*:o:+1:
+
+Py_Initialize:void:::
+
+Py_IsInitialized:int:::
+
+Py_NewInterpreter:PyThreadState*:::
+
+Py_SetProgramName:void:::
+Py_SetProgramName:char*:name::
+
+Py_XDECREF:void:::
+Py_XDECREF:PyObject*:o:-1:if o is not NULL
+
+Py_XINCREF:void:::
+Py_XINCREF:PyObject*:o:+1:if o is not NULL
+
+_PyImport_FindExtension:PyObject*::0:??? see PyImport_AddModule
+_PyImport_FindExtension:char*:::
+_PyImport_FindExtension:char*:::
+
+_PyImport_Fini:void:::
+
+_PyImport_FixupExtension:PyObject*:::???
+_PyImport_FixupExtension:char*:::
+_PyImport_FixupExtension:char*:::
+
+_PyImport_Init:void:::
+
+_PyObject_Del:void:::
+_PyObject_Del:PyObject*:op:0:
+
+_PyObject_New:PyObject*::+1:
+_PyObject_New:PyTypeObject*:type:0:
+
+_PyObject_NewVar:PyObject*::+1:
+_PyObject_NewVar:PyTypeObject*:type:0:
+_PyObject_NewVar:int:size::
+
+_PyString_Resize:int:::
+_PyString_Resize:PyObject**:string:+1:
+_PyString_Resize:int:newsize::
+
+_PyTuple_Resize:int:::
+_PyTuple_Resize:PyTupleObject**:p:+1:
+_PyTuple_Resize:int:new::
+
+_Py_c_diff:Py_complex:::
+_Py_c_diff:Py_complex:left::
+_Py_c_diff:Py_complex:right::
+
+_Py_c_neg:Py_complex:::
+_Py_c_neg:Py_complex:complex::
+
+_Py_c_pow:Py_complex:::
+_Py_c_pow:Py_complex:num::
+_Py_c_pow:Py_complex:exp::
+
+_Py_c_prod:Py_complex:::
+_Py_c_prod:Py_complex:left::
+_Py_c_prod:Py_complex:right::
+
+_Py_c_quot:Py_complex:::
+_Py_c_quot:Py_complex:dividend::
+_Py_c_quot:Py_complex:divisor::
+
+_Py_c_sum:Py_complex:::
+_Py_c_sum:Py_complex:left::
+_Py_c_sum:Py_complex:right::
--- /dev/null
+.. _api-reference:
+
+*************
+API Reference
+*************
+
+
+:mod:`distutils.core` --- Core Distutils functionality
+======================================================
+
+.. module:: distutils.core
+ :synopsis: The core Distutils functionality
+
+
+The :mod:`distutils.core` module is the only module that needs to be installed
+to use the Distutils. It provides the :func:`setup` (which is called from the
+setup script). Indirectly provides the :class:`distutils.dist.Distribution` and
+:class:`distutils.cmd.Command` class.
+
+
+.. function:: setup(arguments)
+
+ The basic do-everything function that does most everything you could ever ask
+ for from a Distutils method. See XXXXX
+
+ The setup function takes a large number of arguments. These are laid out in the
+ following table.
+
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | argument name | value | type |
+ +====================+================================+=============================================================+
+ | *name* | The name of the package | a string |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *version* | The version number of the | See :mod:`distutils.version` |
+ | | package | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *description* | A single line describing the | a string |
+ | | package | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *long_description* | Longer description of the | a string |
+ | | package | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *author* | The name of the package author | a string |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *author_email* | The email address of the | a string |
+ | | package author | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *maintainer* | The name of the current | a string |
+ | | maintainer, if different from | |
+ | | the author | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *maintainer_email* | The email address of the | |
+ | | current maintainer, if | |
+ | | different from the author | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *url* | A URL for the package | a URL |
+ | | (homepage) | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *download_url* | A URL to download the package | a URL |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *packages* | A list of Python packages that | a list of strings |
+ | | distutils will manipulate | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *py_modules* | A list of Python modules that | a list of strings |
+ | | distutils will manipulate | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *scripts* | A list of standalone script | a list of strings |
+ | | files to be built and | |
+ | | installed | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *ext_modules* | A list of Python extensions to | A list of instances of |
+ | | be built | :class:`distutils.core.Extension` |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *classifiers* | A list of categories for the | The list of available |
+ | | package | categorizations is at |
+ | | | http://cheeseshop.python.org/pypi?:action=list_classifiers. |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *distclass* | the :class:`Distribution` | A subclass of |
+ | | class to use | :class:`distutils.core.Distribution` |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *script_name* | The name of the setup.py | a string |
+ | | script - defaults to | |
+ | | ``sys.argv[0]`` | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *script_args* | Arguments to supply to the | a list of strings |
+ | | setup script | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *options* | default options for the setup | a string |
+ | | script | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *license* | The license for the package | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *keywords* | Descriptive meta-data. See | |
+ | | :pep:`314` | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *platforms* | | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+ | *cmdclass* | A mapping of command names to | a dictionary |
+ | | :class:`Command` subclasses | |
+ +--------------------+--------------------------------+-------------------------------------------------------------+
+
+
+.. function:: run_setup(script_name[, script_args=None, stop_after='run'])
+
+ Run a setup script in a somewhat controlled environment, and return the
+ :class:`distutils.dist.Distribution` instance that drives things. This is
+ useful if you need to find out the distribution meta-data (passed as keyword
+ args from *script* to :func:`setup`), or the contents of the config files or
+ command-line.
+
+ *script_name* is a file that will be run with :func:`execfile` ``sys.argv[0]``
+ will be replaced with *script* for the duration of the call. *script_args* is a
+ list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args*
+ for the duration of the call.
+
+ *stop_after* tells :func:`setup` when to stop processing; possible values:
+
+ +---------------+---------------------------------------------+
+ | value | description |
+ +===============+=============================================+
+ | *init* | Stop after the :class:`Distribution` |
+ | | instance has been created and populated |
+ | | with the keyword arguments to :func:`setup` |
+ +---------------+---------------------------------------------+
+ | *config* | Stop after config files have been parsed |
+ | | (and their data stored in the |
+ | | :class:`Distribution` instance) |
+ +---------------+---------------------------------------------+
+ | *commandline* | Stop after the command-line |
+ | | (``sys.argv[1:]`` or *script_args*) have |
+ | | been parsed (and the data stored in the |
+ | | :class:`Distribution` instance.) |
+ +---------------+---------------------------------------------+
+ | *run* | Stop after all commands have been run (the |
+ | | same as if :func:`setup` had been called |
+ | | in the usual way). This is the default |
+ | | value. |
+ +---------------+---------------------------------------------+
+
+In addition, the :mod:`distutils.core` module exposed a number of classes that
+live elsewhere.
+
+* :class:`Extension` from :mod:`distutils.extension`
+
+* :class:`Command` from :mod:`distutils.cmd`
+
+* :class:`Distribution` from :mod:`distutils.dist`
+
+A short description of each of these follows, but see the relevant module for
+the full reference.
+
+
+.. class:: Extension
+
+ The Extension class describes a single C or C++extension module in a setup
+ script. It accepts the following keyword arguments in its constructor
+
+ +------------------------+--------------------------------+---------------------------+
+ | argument name | value | type |
+ +========================+================================+===========================+
+ | *name* | the full name of the | string |
+ | | extension, including any | |
+ | | packages --- ie. *not* a | |
+ | | filename or pathname, but | |
+ | | Python dotted name | |
+ +------------------------+--------------------------------+---------------------------+
+ | *sources* | list of source filenames, | string |
+ | | relative to the distribution | |
+ | | root (where the setup script | |
+ | | lives), in Unix form (slash- | |
+ | | separated) for portability. | |
+ | | Source files may be C, C++, | |
+ | | SWIG (.i), platform-specific | |
+ | | resource files, or whatever | |
+ | | else is recognized by the | |
+ | | :command:`build_ext` command | |
+ | | as source for a Python | |
+ | | extension. | |
+ +------------------------+--------------------------------+---------------------------+
+ | *include_dirs* | list of directories to search | string |
+ | | for C/C++ header files (in | |
+ | | Unix form for portability) | |
+ +------------------------+--------------------------------+---------------------------+
+ | *define_macros* | list of macros to define; each | (string,string) tuple or |
+ | | macro is defined using a | (name,``None``) |
+ | | 2-tuple, where 'value' is | |
+ | | either the string to define it | |
+ | | to or ``None`` to define it | |
+ | | without a particular value | |
+ | | (equivalent of ``#define FOO`` | |
+ | | in source or :option:`-DFOO` | |
+ | | on Unix C compiler command | |
+ | | line) | |
+ +------------------------+--------------------------------+---------------------------+
+ | *undef_macros* | list of macros to undefine | string |
+ | | explicitly | |
+ +------------------------+--------------------------------+---------------------------+
+ | *library_dirs* | list of directories to search | string |
+ | | for C/C++ libraries at link | |
+ | | time | |
+ +------------------------+--------------------------------+---------------------------+
+ | *libraries* | list of library names (not | string |
+ | | filenames or paths) to link | |
+ | | against | |
+ +------------------------+--------------------------------+---------------------------+
+ | *runtime_library_dirs* | list of directories to search | string |
+ | | for C/C++ libraries at run | |
+ | | time (for shared extensions, | |
+ | | this is when the extension is | |
+ | | loaded) | |
+ +------------------------+--------------------------------+---------------------------+
+ | *extra_objects* | list of extra files to link | string |
+ | | with (eg. object files not | |
+ | | implied by 'sources', static | |
+ | | library that must be | |
+ | | explicitly specified, binary | |
+ | | resource files, etc.) | |
+ +------------------------+--------------------------------+---------------------------+
+ | *extra_compile_args* | any extra platform- and | string |
+ | | compiler-specific information | |
+ | | to use when compiling the | |
+ | | source files in 'sources'. For | |
+ | | platforms and compilers where | |
+ | | a command line makes sense, | |
+ | | this is typically a list of | |
+ | | command-line arguments, but | |
+ | | for other platforms it could | |
+ | | be anything. | |
+ +------------------------+--------------------------------+---------------------------+
+ | *extra_link_args* | any extra platform- and | string |
+ | | compiler-specific information | |
+ | | to use when linking object | |
+ | | files together to create the | |
+ | | extension (or to create a new | |
+ | | static Python interpreter). | |
+ | | Similar interpretation as for | |
+ | | 'extra_compile_args'. | |
+ +------------------------+--------------------------------+---------------------------+
+ | *export_symbols* | list of symbols to be exported | string |
+ | | from a shared extension. Not | |
+ | | used on all platforms, and not | |
+ | | generally necessary for Python | |
+ | | extensions, which typically | |
+ | | export exactly one symbol: | |
+ | | ``init`` + extension_name. | |
+ +------------------------+--------------------------------+---------------------------+
+ | *depends* | list of files that the | string |
+ | | extension depends on | |
+ +------------------------+--------------------------------+---------------------------+
+ | *language* | extension language (i.e. | string |
+ | | ``'c'``, ``'c++'``, | |
+ | | ``'objc'``). Will be detected | |
+ | | from the source extensions if | |
+ | | not provided. | |
+ +------------------------+--------------------------------+---------------------------+
+
+
+.. class:: Distribution
+
+ A :class:`Distribution` describes how to build, install and package up a Python
+ software package.
+
+ See the :func:`setup` function for a list of keyword arguments accepted by the
+ Distribution constructor. :func:`setup` creates a Distribution instance.
+
+
+.. class:: Command
+
+ A :class:`Command` class (or rather, an instance of one of its subclasses)
+ implement a single distutils command.
+
+
+:mod:`distutils.ccompiler` --- CCompiler base class
+===================================================
+
+.. module:: distutils.ccompiler
+ :synopsis: Abstract CCompiler class
+
+
+This module provides the abstract base class for the :class:`CCompiler`
+classes. A :class:`CCompiler` instance can be used for all the compile and
+link steps needed to build a single project. Methods are provided to set
+options for the compiler --- macro definitions, include directories, link path,
+libraries and the like.
+
+This module provides the following functions.
+
+
+.. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)
+
+ Generate linker options for searching library directories and linking with
+ specific libraries. *libraries* and *library_dirs* are, respectively, lists of
+ library names (not filenames!) and search directories. Returns a list of
+ command-line options suitable for use with some compiler (depending on the two
+ format strings passed in).
+
+
+.. function:: gen_preprocess_options(macros, include_dirs)
+
+ Generate C pre-processor options (:option:`-D`, :option:`-U`, :option:`-I`) as
+ used by at least two types of compilers: the typical Unix compiler and Visual
+ C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)``
+ means undefine (:option:`-U`) macro *name*, and ``(name, value)`` means define
+ (:option:`-D`) macro *name* to *value*. *include_dirs* is just a list of
+ directory names to be added to the header file search path (:option:`-I`).
+ Returns a list of command-line options suitable for either Unix compilers or
+ Visual C++.
+
+
+.. function:: get_default_compiler(osname, platform)
+
+ Determine the default compiler to use for the given platform.
+
+ *osname* should be one of the standard Python OS names (i.e. the ones returned
+ by ``os.name``) and *platform* the common value returned by ``sys.platform`` for
+ the platform in question.
+
+ The default values are ``os.name`` and ``sys.platform`` in case the parameters
+ are not given.
+
+
+.. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)
+
+ Factory function to generate an instance of some CCompiler subclass for the
+ supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg.
+ ``'posix'``, ``'nt'``), and *compiler* defaults to the default compiler for
+ that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the
+ default compilers are "traditional Unix interface" (:class:`UnixCCompiler`
+ class) and Visual C++(:class:`MSVCCompiler` class). Note that it's perfectly
+ possible to ask for a Unix compiler object under Windows, and a Microsoft
+ compiler object under Unix---if you supply a value for *compiler*, *plat* is
+ ignored.
+
+ .. % Is the posix/nt only thing still true? Mac OS X seems to work, and
+ .. % returns a UnixCCompiler instance. How to document this... hmm.
+
+
+.. function:: show_compilers()
+
+ Print list of available compilers (used by the :option:`--help-compiler` options
+ to :command:`build`, :command:`build_ext`, :command:`build_clib`).
+
+
+.. class:: CCompiler([verbose=0, dry_run=0, force=0])
+
+ The abstract base class :class:`CCompiler` defines the interface that must be
+ implemented by real compiler classes. The class also has some utility methods
+ used by several compiler classes.
+
+ The basic idea behind a compiler abstraction class is that each instance can be
+ used for all the compile/link steps in building a single project. Thus,
+ attributes common to all of those compile and link steps --- include
+ directories, macros to define, libraries to link against, etc. --- are
+ attributes of the compiler instance. To allow for variability in how individual
+ files are treated, most of those attributes may be varied on a per-compilation
+ or per-link basis.
+
+ The constructor for each subclass creates an instance of the Compiler object.
+ Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the
+ steps) and *force* (rebuild everything, regardless of dependencies). All of
+ these flags default to ``0`` (off). Note that you probably don't want to
+ instantiate :class:`CCompiler` or one of its subclasses directly - use the
+ :func:`distutils.CCompiler.new_compiler` factory function instead.
+
+ The following methods allow you to manually alter compiler options for the
+ instance of the Compiler class.
+
+
+ .. method:: CCompiler.add_include_dir(dir)
+
+ Add *dir* to the list of directories that will be searched for header files.
+ The compiler is instructed to search directories in the order in which they are
+ supplied by successive calls to :meth:`add_include_dir`.
+
+
+ .. method:: CCompiler.set_include_dirs(dirs)
+
+ Set the list of directories that will be searched to *dirs* (a list of strings).
+ Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to
+ :meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`.
+ This does not affect any list of standard include directories that the compiler
+ may search by default.
+
+
+ .. method:: CCompiler.add_library(libname)
+
+ Add *libname* to the list of libraries that will be included in all links driven
+ by this compiler object. Note that *libname* should \*not\* be the name of a
+ file containing a library, but the name of the library itself: the actual
+ filename will be inferred by the linker, the compiler, or the compiler class
+ (depending on the platform).
+
+ The linker will be instructed to link against libraries in the order they were
+ supplied to :meth:`add_library` and/or :meth:`set_libraries`. It is perfectly
+ valid to duplicate library names; the linker will be instructed to link against
+ libraries as many times as they are mentioned.
+
+
+ .. method:: CCompiler.set_libraries(libnames)
+
+ Set the list of libraries to be included in all links driven by this compiler
+ object to *libnames* (a list of strings). This does not affect any standard
+ system libraries that the linker may include by default.
+
+
+ .. method:: CCompiler.add_library_dir(dir)
+
+ Add *dir* to the list of directories that will be searched for libraries
+ specified to :meth:`add_library` and :meth:`set_libraries`. The linker will be
+ instructed to search for libraries in the order they are supplied to
+ :meth:`add_library_dir` and/or :meth:`set_library_dirs`.
+
+
+ .. method:: CCompiler.set_library_dirs(dirs)
+
+ Set the list of library search directories to *dirs* (a list of strings). This
+ does not affect any standard library search path that the linker may search by
+ default.
+
+
+ .. method:: CCompiler.add_runtime_library_dir(dir)
+
+ Add *dir* to the list of directories that will be searched for shared libraries
+ at runtime.
+
+
+ .. method:: CCompiler.set_runtime_library_dirs(dirs)
+
+ Set the list of directories to search for shared libraries at runtime to *dirs*
+ (a list of strings). This does not affect any standard search path that the
+ runtime linker may search by default.
+
+
+ .. method:: CCompiler.define_macro(name[, value=None])
+
+ Define a preprocessor macro for all compilations driven by this compiler object.
+ The optional parameter *value* should be a string; if it is not supplied, then
+ the macro will be defined without an explicit value and the exact outcome
+ depends on the compiler used (XXX true? does ANSI say anything about this?)
+
+
+ .. method:: CCompiler.undefine_macro(name)
+
+ Undefine a preprocessor macro for all compilations driven by this compiler
+ object. If the same macro is defined by :meth:`define_macro` and
+ undefined by :meth:`undefine_macro` the last call takes precedence
+ (including multiple redefinitions or undefinitions). If the macro is
+ redefined/undefined on a per-compilation basis (ie. in the call to
+ :meth:`compile`), then that takes precedence.
+
+
+ .. method:: CCompiler.add_link_object(object)
+
+ Add *object* to the list of object files (or analogues, such as explicitly named
+ library files or the output of "resource compilers") to be included in every
+ link driven by this compiler object.
+
+
+ .. method:: CCompiler.set_link_objects(objects)
+
+ Set the list of object files (or analogues) to be included in every link to
+ *objects*. This does not affect any standard object files that the linker may
+ include by default (such as system libraries).
+
+ The following methods implement methods for autodetection of compiler options,
+ providing some functionality similar to GNU :program:`autoconf`.
+
+
+ .. method:: CCompiler.detect_language(sources)
+
+ Detect the language of a given file, or list of files. Uses the instance
+ attributes :attr:`language_map` (a dictionary), and :attr:`language_order` (a
+ list) to do the job.
+
+
+ .. method:: CCompiler.find_library_file(dirs, lib[, debug=0])
+
+ Search the specified list of directories for a static or shared library file
+ *lib* and return the full path to that file. If *debug* is true, look for a
+ debugging version (if that makes sense on the current platform). Return
+ ``None`` if *lib* wasn't found in any of the specified directories.
+
+
+ .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None])
+
+ Return a boolean indicating whether *funcname* is supported on the current
+ platform. The optional arguments can be used to augment the compilation
+ environment by providing additional include files and paths and libraries and
+ paths.
+
+
+ .. method:: CCompiler.library_dir_option(dir)
+
+ Return the compiler option to add *dir* to the list of directories searched for
+ libraries.
+
+
+ .. method:: CCompiler.library_option(lib)
+
+ Return the compiler option to add *dir* to the list of libraries linked into the
+ shared library or executable.
+
+
+ .. method:: CCompiler.runtime_library_dir_option(dir)
+
+ Return the compiler option to add *dir* to the list of directories searched for
+ runtime libraries.
+
+
+ .. method:: CCompiler.set_executables(**args)
+
+ Define the executables (and options for them) that will be run to perform the
+ various stages of compilation. The exact set of executables that may be
+ specified here depends on the compiler class (via the 'executables' class
+ attribute), but most will have:
+
+ +--------------+------------------------------------------+
+ | attribute | description |
+ +==============+==========================================+
+ | *compiler* | the C/C++ compiler |
+ +--------------+------------------------------------------+
+ | *linker_so* | linker used to create shared objects and |
+ | | libraries |
+ +--------------+------------------------------------------+
+ | *linker_exe* | linker used to create binary executables |
+ +--------------+------------------------------------------+
+ | *archiver* | static library creator |
+ +--------------+------------------------------------------+
+
+ On platforms with a command-line (Unix, DOS/Windows), each of these is a string
+ that will be split into executable name and (optional) list of arguments.
+ (Splitting the string is done similarly to how Unix shells operate: words are
+ delimited by spaces, but quotes and backslashes can override this. See
+ :func:`distutils.util.split_quoted`.)
+
+ The following methods invoke stages in the build process.
+
+
+ .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])
+
+ Compile one or more source files. Generates object files (e.g. transforms a
+ :file:`.c` file to a :file:`.o` file.)
+
+ *sources* must be a list of filenames, most likely C/C++ files, but in reality
+ anything that can be handled by a particular compiler and compiler class (eg.
+ :class:`MSVCCompiler` can handle resource files in *sources*). Return a list of
+ object filenames, one per source filename in *sources*. Depending on the
+ implementation, not all source files will necessarily be compiled, but all
+ corresponding object filenames will be returned.
+
+ If *output_dir* is given, object files will be put under it, while retaining
+ their original path component. That is, :file:`foo/bar.c` normally compiles to
+ :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then
+ it would compile to :file:`build/foo/bar.o`.
+
+ *macros*, if given, must be a list of macro definitions. A macro definition is
+ either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines
+ a macro; if the value is ``None``, the macro is defined without an explicit
+ value. The 1-tuple case undefines a macro. Later
+ definitions/redefinitions/undefinitions take precedence.
+
+ *include_dirs*, if given, must be a list of strings, the directories to add to
+ the default include file search path for this compilation only.
+
+ *debug* is a boolean; if true, the compiler will be instructed to output debug
+ symbols in (or alongside) the object file(s).
+
+ *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms
+ that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most
+ likely lists of strings: extra command-line arguments to prepend/append to the
+ compiler command line. On other platforms, consult the implementation class
+ documentation. In any event, they are intended as an escape hatch for those
+ occasions when the abstract compiler framework doesn't cut the mustard.
+
+ *depends*, if given, is a list of filenames that all targets depend on. If a
+ source file is older than any file in depends, then the source file will be
+ recompiled. This supports dependency tracking, but only at a coarse
+ granularity.
+
+ Raises :exc:`CompileError` on failure.
+
+
+ .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])
+
+ Link a bunch of stuff together to create a static library file. The "bunch of
+ stuff" consists of the list of object files supplied as *objects*, the extra
+ object files supplied to :meth:`add_link_object` and/or
+ :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or
+ :meth:`set_libraries`, and the libraries supplied as *libraries* (if any).
+
+ *output_libname* should be a library name, not a filename; the filename will be
+ inferred from the library name. *output_dir* is the directory where the library
+ file will be put. XXX defaults to what?
+
+ *debug* is a boolean; if true, debugging information will be included in the
+ library (note that on most platforms, it is the compile step where this matters:
+ the *debug* flag is included here just for consistency).
+
+ *target_lang* is the target language for which the given objects are being
+ compiled. This allows specific linkage time treatment of certain languages.
+
+ Raises :exc:`LibError` on failure.
+
+
+ .. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
+
+ Link a bunch of stuff together to create an executable or shared library file.
+
+ The "bunch of stuff" consists of the list of object files supplied as *objects*.
+ *output_filename* should be a filename. If *output_dir* is supplied,
+ *output_filename* is relative to it (i.e. *output_filename* can provide
+ directory components if needed).
+
+ *libraries* is a list of libraries to link against. These are library names,
+ not filenames, since they're translated into filenames in a platform-specific
+ way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on
+ DOS/Windows). However, they can include a directory component, which means the
+ linker will look in that specific directory rather than searching all the normal
+ locations.
+
+ *library_dirs*, if supplied, should be a list of directories to search for
+ libraries that were specified as bare library names (ie. no directory
+ component). These are on top of the system default and those supplied to
+ :meth:`add_library_dir` and/or :meth:`set_library_dirs`. *runtime_library_dirs*
+ is a list of directories that will be embedded into the shared library and used
+ to search for other shared libraries that \*it\* depends on at run-time. (This
+ may only be relevant on Unix.)
+
+ *export_symbols* is a list of symbols that the shared library will export.
+ (This appears to be relevant only on Windows.)
+
+ *debug* is as for :meth:`compile` and :meth:`create_static_lib`, with the
+ slight distinction that it actually matters on most platforms (as opposed to
+ :meth:`create_static_lib`, which includes a *debug* flag mostly for form's
+ sake).
+
+ *extra_preargs* and *extra_postargs* are as for :meth:`compile` (except of
+ course that they supply command-line arguments for the particular linker being
+ used).
+
+ *target_lang* is the target language for which the given objects are being
+ compiled. This allows specific linkage time treatment of certain languages.
+
+ Raises :exc:`LinkError` on failure.
+
+
+ .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])
+
+ Link an executable. *output_progname* is the name of the file executable, while
+ *objects* are a list of object filenames to link in. Other arguments are as for
+ the :meth:`link` method.
+
+
+ .. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
+
+ Link a shared library. *output_libname* is the name of the output library,
+ while *objects* is a list of object filenames to link in. Other arguments are
+ as for the :meth:`link` method.
+
+
+ .. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
+
+ Link a shared object. *output_filename* is the name of the shared object that
+ will be created, while *objects* is a list of object filenames to link in.
+ Other arguments are as for the :meth:`link` method.
+
+
+ .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])
+
+ Preprocess a single C/C++ source file, named in *source*. Output will be written
+ to file named *output_file*, or *stdout* if *output_file* not supplied.
+ *macros* is a list of macro definitions as for :meth:`compile`, which will
+ augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`.
+ *include_dirs* is a list of directory names that will be added to the default
+ list, in the same way as :meth:`add_include_dir`.
+
+ Raises :exc:`PreprocessError` on failure.
+
+ The following utility methods are defined by the :class:`CCompiler` class, for
+ use by the various concrete subclasses.
+
+
+ .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir=''])
+
+ Returns the filename of the executable for the given *basename*. Typically for
+ non-Windows platforms this is the same as the basename, while Windows will get
+ a :file:`.exe` added.
+
+
+ .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])
+
+ Returns the filename for the given library name on the current platform. On Unix
+ a library with *lib_type* of ``'static'`` will typically be of the form
+ :file:`liblibname.a`, while a *lib_type* of ``'dynamic'`` will be of the form
+ :file:`liblibname.so`.
+
+
+ .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir=''])
+
+ Returns the name of the object files for the given source files.
+ *source_filenames* should be a list of filenames.
+
+
+ .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir=''])
+
+ Returns the name of a shared object file for the given file name *basename*.
+
+
+ .. method:: CCompiler.execute(func, args[, msg=None, level=1])
+
+ Invokes :func:`distutils.util.execute` This method invokes a Python function
+ *func* with the given arguments *args*, after logging and taking into account
+ the *dry_run* flag. XXX see also.
+
+
+ .. method:: CCompiler.spawn(cmd)
+
+ Invokes :func:`distutils.util.spawn`. This invokes an external process to run
+ the given command. XXX see also.
+
+
+ .. method:: CCompiler.mkpath(name[, mode=511])
+
+ Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any
+ missing ancestor directories. XXX see also.
+
+
+ .. method:: CCompiler.move_file(src, dst)
+
+ Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. XXX see
+ also.
+
+
+ .. method:: CCompiler.announce(msg[, level=1])
+
+ Write a message using :func:`distutils.log.debug`. XXX see also.
+
+
+ .. method:: CCompiler.warn(msg)
+
+ Write a warning message *msg* to standard error.
+
+
+ .. method:: CCompiler.debug_print(msg)
+
+ If the *debug* flag is set on this :class:`CCompiler` instance, print *msg* to
+ standard output, otherwise do nothing.
+
+.. % \subsection{Compiler-specific modules}
+.. %
+.. % The following modules implement concrete subclasses of the abstract
+.. % \class{CCompiler} class. They should not be instantiated directly, but should
+.. % be created using \function{distutils.ccompiler.new_compiler()} factory
+.. % function.
+
+
+:mod:`distutils.unixccompiler` --- Unix C Compiler
+==================================================
+
+.. module:: distutils.unixccompiler
+ :synopsis: UNIX C Compiler
+
+
+This module provides the :class:`UnixCCompiler` class, a subclass of
+:class:`CCompiler` that handles the typical Unix-style command-line C compiler:
+
+* macros defined with :option:`-Dname[=value]`
+
+* macros undefined with :option:`-Uname`
+
+* include search directories specified with :option:`-Idir`
+
+* libraries specified with :option:`-llib`
+
+* library search directories specified with :option:`-Ldir`
+
+* compile handled by :program:`cc` (or similar) executable with :option:`-c`
+ option: compiles :file:`.c` to :file:`.o`
+
+* link static library handled by :program:`ar` command (possibly with
+ :program:`ranlib`)
+
+* link shared library handled by :program:`cc` :option:`-shared`
+
+
+:mod:`distutils.msvccompiler` --- Microsoft Compiler
+====================================================
+
+.. module:: distutils.msvccompiler
+ :synopsis: Microsoft Compiler
+
+
+This module provides :class:`MSVCCompiler`, an implementation of the abstract
+:class:`CCompiler` class for Microsoft Visual Studio. Typically, extension
+modules need to be compiled with the same compiler that was used to compile
+Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python
+2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium
+binaries are created using the Platform SDK.
+
+:class:`MSVCCompiler` will normally choose the right compiler, linker etc. on
+its own. To override this choice, the environment variables *DISTUTILS_USE_SDK*
+and *MSSdk* must be both set. *MSSdk* indicates that the current environment has
+been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables
+had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates
+that the distutils user has made an explicit choice to override the compiler
+selection by :class:`MSVCCompiler`.
+
+
+:mod:`distutils.bcppcompiler` --- Borland Compiler
+==================================================
+
+.. module:: distutils.bcppcompiler
+
+
+This module provides :class:`BorlandCCompiler`, an subclass of the abstract
+:class:`CCompiler` class for the Borland C++ compiler.
+
+
+:mod:`distutils.cygwincompiler` --- Cygwin Compiler
+===================================================
+
+.. module:: distutils.cygwinccompiler
+
+
+This module provides the :class:`CygwinCCompiler` class, a subclass of
+:class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to
+Windows. It also contains the Mingw32CCompiler class which handles the mingw32
+port of GCC (same as cygwin in no-cygwin mode).
+
+
+:mod:`distutils.emxccompiler` --- OS/2 EMX Compiler
+===================================================
+
+.. module:: distutils.emxccompiler
+ :synopsis: OS/2 EMX Compiler support
+
+
+This module provides the EMXCCompiler class, a subclass of
+:class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2.
+
+
+:mod:`distutils.mwerkscompiler` --- Metrowerks CodeWarrior support
+==================================================================
+
+.. module:: distutils.mwerkscompiler
+ :synopsis: Metrowerks CodeWarrior support
+
+
+Contains :class:`MWerksCompiler`, an implementation of the abstract
+:class:`CCompiler` class for MetroWerks CodeWarrior on the pre-Mac OS X
+Macintosh. Needs work to support CW on Windows or Mac OS X.
+
+.. % \subsection{Utility modules}
+.. %
+.. % The following modules all provide general utility functions. They haven't
+.. % all been documented yet.
+
+
+:mod:`distutils.archive_util` --- Archiving utilities
+======================================================
+
+.. module:: distutils.archive_util
+ :synopsis: Utility functions for creating archive files (tarballs, zip files, ...)
+
+
+This module provides a few functions for creating archive files, such as
+tarballs or zipfiles.
+
+
+.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])
+
+ Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of
+ the file to create, minus any format-specific extension; *format* is the
+ archive format: one of ``zip``, ``tar``, ``ztar``, or ``gztar``. *root_dir* is
+ a directory that will be the root directory of the archive; ie. we typically
+ ``chdir`` into *root_dir* before creating the archive. *base_dir* is the
+ directory where we start archiving from; ie. *base_dir* will be the common
+ prefix of all files and directories in the archive. *root_dir* and *base_dir*
+ both default to the current directory. Returns the name of the archive file.
+
+ .. warning::
+
+ This should be changed to support bz2 files
+
+
+.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])
+
+ 'Create an (optional compressed) archive as a tar file from all files in and
+ under *base_dir*. *compress* must be ``'gzip'`` (the default), ``'compress'``,
+ ``'bzip2'``, or ``None``. Both :program:`tar` and the compression utility named
+ by *compress* must be on the default program search path, so this is probably
+ Unix-specific. The output tar file will be named :file:`base_dir.tar`,
+ possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2`
+ or :file:`.Z`). Return the output filename.
+
+ .. warning::
+
+ This should be replaced with calls to the :mod:`tarfile` module.
+
+
+.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])
+
+ Create a zip file from all files in and under *base_dir*. The output zip file
+ will be named *base_dir* + :file:`.zip`. Uses either the :mod:`zipfile` Python
+ module (if available) or the InfoZIP :file:`zip` utility (if installed and
+ found on the default search path). If neither tool is available, raises
+ :exc:`DistutilsExecError`. Returns the name of the output zip file.
+
+
+:mod:`distutils.dep_util` --- Dependency checking
+=================================================
+
+.. module:: distutils.dep_util
+ :synopsis: Utility functions for simple dependency checking
+
+
+This module provides functions for performing simple, timestamp-based
+dependency of files and groups of files; also, functions based entirely on such
+timestamp dependency analysis.
+
+
+.. function:: newer(source, target)
+
+ Return true if *source* exists and is more recently modified than *target*, or
+ if *source* exists and *target* doesn't. Return false if both exist and *target*
+ is the same age or newer than *source*. Raise :exc:`DistutilsFileError` if
+ *source* does not exist.
+
+
+.. function:: newer_pairwise(sources, targets)
+
+ Walk two filename lists in parallel, testing if each source is newer than its
+ corresponding target. Return a pair of lists (*sources*, *targets*) where
+ source is newer than target, according to the semantics of :func:`newer`
+
+ .. % % equivalent to a listcomp...
+
+
+.. function:: newer_group(sources, target[, missing='error'])
+
+ Return true if *target* is out-of-date with respect to any file listed in
+ *sources* In other words, if *target* exists and is newer than every file in
+ *sources*, return false; otherwise return true. *missing* controls what we do
+ when a source file is missing; the default (``'error'``) is to blow up with an
+ :exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently
+ drop any missing source files; if it is ``'newer'``, any missing source files
+ make us assume that *target* is out-of-date (this is handy in "dry-run" mode:
+ it'll make you pretend to carry out commands that wouldn't work because inputs
+ are missing, but that doesn't matter because you're not actually going to run
+ the commands).
+
+
+:mod:`distutils.dir_util` --- Directory tree operations
+=======================================================
+
+.. module:: distutils.dir_util
+ :synopsis: Utility functions for operating on directories and directory trees
+
+
+This module provides functions for operating on directories and trees of
+directories.
+
+
+.. function:: mkpath(name[, mode=0777, verbose=0, dry_run=0])
+
+ Create a directory and any missing ancestor directories. If the directory
+ already exists (or if *name* is the empty string, which means the current
+ directory, which of course exists), then do nothing. Raise
+ :exc:`DistutilsFileError` if unable to create some directory along the way (eg.
+ some sub-path exists, but is a file rather than a directory). If *verbose* is
+ true, print a one-line summary of each mkdir to stdout. Return the list of
+ directories actually created.
+
+
+.. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0])
+
+ Create all the empty directories under *base_dir* needed to put *files* there.
+ *base_dir* is just the a name of a directory which doesn't necessarily exist
+ yet; *files* is a list of filenames to be interpreted relative to *base_dir*.
+ *base_dir* + the directory portion of every file in *files* will be created if
+ it doesn't already exist. *mode*, *verbose* and *dry_run* flags are as for
+ :func:`mkpath`.
+
+
+.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])
+
+ Copy an entire directory tree *src* to a new location *dst*. Both *src* and
+ *dst* must be directory names. If *src* is not a directory, raise
+ :exc:`DistutilsFileError`. If *dst* does not exist, it is created with
+ :func:`mkpath`. The end result of the copy is that every file in *src* is
+ copied to *dst*, and directories under *src* are recursively copied to *dst*.
+ Return the list of files that were copied or might have been copied, using their
+ output name. The return value is unaffected by *update* or *dry_run*: it is
+ simply the list of all files under *src*, with the names changed to be under
+ *dst*.
+
+ *preserve_mode* and *preserve_times* are the same as for :func:`copy_file` in
+ :mod:`distutils.file_util`; note that they only apply to regular files, not to
+ directories. If *preserve_symlinks* is true, symlinks will be copied as
+ symlinks (on platforms that support them!); otherwise (the default), the
+ destination of the symlink will be copied. *update* and *verbose* are the same
+ as for :func:`copy_file`.
+
+
+.. function:: remove_tree(directory[, verbose=0, dry_run=0])
+
+ Recursively remove *directory* and all files and directories underneath it. Any
+ errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
+ true).
+
+**\*\*** Some of this could be replaced with the shutil module? **\*\***
+
+
+:mod:`distutils.file_util` --- Single file operations
+=====================================================
+
+.. module:: distutils.file_util
+ :synopsis: Utility functions for operating on single files
+
+
+This module contains some utility functions for operating on individual files.
+
+
+.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])
+
+ Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there
+ with the same name; otherwise, it must be a filename. (If the file exists, it
+ will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the
+ file's mode (type and permission bits, or whatever is analogous on the
+ current platform) is copied. If *preserve_times* is true (the default), the
+ last-modified and last-access times are copied as well. If *update* is true,
+ *src* will only be copied if *dst* does not exist, or if *dst* does exist but
+ is older than *src*.
+
+ *link* allows you to make hard links (using :func:`os.link`) or symbolic links
+ (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or
+ ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link*
+ on systems that don't support it: :func:`copy_file` doesn't check if hard or
+ symbolic linking is available. It uses :func:`_copy_file_contents` to copy file
+ contents.
+
+ Return a tuple ``(dest_name, copied)``: *dest_name* is the actual name of the
+ output file, and *copied* is true if the file was copied (or would have been
+ copied, if *dry_run* true).
+
+ .. % XXX if the destination file already exists, we clobber it if
+ .. % copying, but blow up if linking. Hmmm. And I don't know what
+ .. % macostools.copyfile() does. Should definitely be consistent, and
+ .. % should probably blow up if destination exists and we would be
+ .. % changing it (ie. it's not already a hard/soft link to src OR
+ .. % (not update) and (src newer than dst)).
+
+
+.. function:: move_file(src, dst[, verbose, dry_run])
+
+ Move file *src* to *dst*. If *dst* is a directory, the file will be moved into
+ it with the same name; otherwise, *src* is just renamed to *dst*. Returns the
+ new full name of the file.
+
+ .. warning::
+
+ Handles cross-device moves on Unix using :func:`copy_file`. What about other
+ systems???
+
+
+.. function:: write_file(filename, contents)
+
+ Create a file called *filename* and write *contents* (a sequence of strings
+ without line terminators) to it.
+
+
+:mod:`distutils.util` --- Miscellaneous other utility functions
+===============================================================
+
+.. module:: distutils.util
+ :synopsis: Miscellaneous other utility functions
+
+
+This module contains other assorted bits and pieces that don't fit into any
+other utility module.
+
+
+.. function:: get_platform()
+
+ Return a string that identifies the current platform. This is used mainly to
+ distinguish platform-specific build directories and platform-specific built
+ distributions. Typically includes the OS name and version and the architecture
+ (as supplied by 'os.uname()'), although the exact information included depends
+ on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only
+ runs on SGI hardware), but for Linux the kernel version isn't particularly
+ important.
+
+ Examples of returned values:
+
+ * ``linux-i586``
+ * ``linux-alpha``
+ * ``solaris-2.6-sun4u``
+ * ``irix-5.3``
+ * ``irix64-6.2``
+
+ For non-POSIX platforms, currently just returns ``sys.platform``.
+
+ .. % XXX isn't this also provided by some other non-distutils module?
+
+
+.. function:: convert_path(pathname)
+
+ Return 'pathname' as a name that will work on the native filesystem, i.e. split
+ it on '/' and put it back together again using the current directory separator.
+ Needed because filenames in the setup script are always supplied in Unix style,
+ and have to be converted to the local convention before we can actually use them
+ in the filesystem. Raises :exc:`ValueError` on non-Unix-ish systems if
+ *pathname* either starts or ends with a slash.
+
+
+.. function:: change_root(new_root, pathname)
+
+ Return *pathname* with *new_root* prepended. If *pathname* is relative, this is
+ equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making
+ *pathname* relative and then joining the two, which is tricky on DOS/Windows.
+
+
+.. function:: check_environ()
+
+ Ensure that 'os.environ' has all the environment variables we guarantee that
+ users can use in config files, command-line options, etc. Currently this
+ includes:
+
+ * :envvar:`HOME` - user's home directory (Unix only)
+ * :envvar:`PLAT` - description of the current platform, including hardware and
+ OS (see :func:`get_platform`)
+
+
+.. function:: subst_vars(s, local_vars)
+
+ Perform shell/Perl-style variable substitution on *s*. Every occurrence of
+ ``$`` followed by a name is considered a variable, and variable is substituted
+ by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's
+ not in *local_vars*. *os.environ* is first checked/augmented to guarantee that
+ it contains certain values: see :func:`check_environ`. Raise :exc:`ValueError`
+ for any variables not found in either *local_vars* or ``os.environ``.
+
+ Note that this is not a fully-fledged string interpolation function. A valid
+ ``$variable`` can consist only of upper and lower case letters, numbers and an
+ underscore. No { } or ( ) style quoting is available.
+
+
+.. function:: grok_environment_error(exc[, prefix='error: '])
+
+ Generate a useful error message from an :exc:`EnvironmentError` (:exc:`IOError`
+ or :exc:`OSError`) exception object. Handles Python 1.5.1 and later styles,
+ and does what it can to deal with exception objects that don't have a filename
+ (which happens when the error is due to a two-file operation, such as
+ :func:`rename` or :func:`link`). Returns the error message as a string
+ prefixed with *prefix*.
+
+
+.. function:: split_quoted(s)
+
+ Split a string up according to Unix shell-like rules for quotes and backslashes.
+ In short: words are delimited by spaces, as long as those spaces are not escaped
+ by a backslash, or inside a quoted string. Single and double quotes are
+ equivalent, and the quote characters can be backslash-escaped. The backslash is
+ stripped from any two-character escape sequence, leaving only the escaped
+ character. The quote characters are stripped from any quoted string. Returns a
+ list of words.
+
+ .. % Should probably be moved into the standard library.
+
+
+.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0])
+
+ Perform some action that affects the outside world (for instance, writing to the
+ filesystem). Such actions are special because they are disabled by the
+ *dry_run* flag. This method takes care of all that bureaucracy for you; all
+ you have to do is supply the function to call and an argument tuple for it (to
+ embody the "external action" being performed), and an optional message to print.
+
+
+.. function:: strtobool(val)
+
+ Convert a string representation of truth to true (1) or false (0).
+
+ True values are ``y``, ``yes``, ``t``, ``true``, ``on`` and ``1``; false values
+ are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``. Raises
+ :exc:`ValueError` if *val* is anything else.
+
+
+.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])
+
+ Byte-compile a collection of Python source files to either :file:`.pyc` or
+ :file:`.pyo` files in the same directory. *py_files* is a list of files to
+ compile; any files that don't end in :file:`.py` are silently skipped.
+ *optimize* must be one of the following:
+
+ * ``0`` - don't optimize (generate :file:`.pyc`)
+ * ``1`` - normal optimization (like ``python -O``)
+ * ``2`` - extra optimization (like ``python -OO``)
+
+ If *force* is true, all files are recompiled regardless of timestamps.
+
+ The source filename encoded in each bytecode file defaults to the filenames
+ listed in *py_files*; you can modify these with *prefix* and *basedir*.
+ *prefix* is a string that will be stripped off of each source filename, and
+ *base_dir* is a directory name that will be prepended (after *prefix* is
+ stripped). You can supply either or both (or neither) of *prefix* and
+ *base_dir*, as you wish.
+
+ If *dry_run* is true, doesn't actually do anything that would affect the
+ filesystem.
+
+ Byte-compilation is either done directly in this interpreter process with the
+ standard :mod:`py_compile` module, or indirectly by writing a temporary script
+ and executing it. Normally, you should let :func:`byte_compile` figure out to
+ use direct compilation or not (see the source for details). The *direct* flag
+ is used by the script generated in indirect mode; unless you know what you're
+ doing, leave it set to ``None``.
+
+
+.. function:: rfc822_escape(header)
+
+ Return a version of *header* escaped for inclusion in an :rfc:`822` header, by
+ ensuring there are 8 spaces space after each newline. Note that it does no other
+ modification of the string.
+
+ .. % this _can_ be replaced
+
+.. % \subsection{Distutils objects}
+
+
+:mod:`distutils.dist` --- The Distribution class
+================================================
+
+.. module:: distutils.dist
+ :synopsis: Provides the Distribution class, which represents the module distribution being
+ built/installed/distributed
+
+
+This module provides the :class:`Distribution` class, which represents the
+module distribution being built/installed/distributed.
+
+
+:mod:`distutils.extension` --- The Extension class
+==================================================
+
+.. module:: distutils.extension
+ :synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup
+ scripts
+
+
+This module provides the :class:`Extension` class, used to describe C/C++
+extension modules in setup scripts.
+
+.. % \subsection{Ungrouped modules}
+.. % The following haven't been moved into a more appropriate section yet.
+
+
+:mod:`distutils.debug` --- Distutils debug mode
+===============================================
+
+.. module:: distutils.debug
+ :synopsis: Provides the debug flag for distutils
+
+
+This module provides the DEBUG flag.
+
+
+:mod:`distutils.errors` --- Distutils exceptions
+================================================
+
+.. module:: distutils.errors
+ :synopsis: Provides standard distutils exceptions
+
+
+Provides exceptions used by the Distutils modules. Note that Distutils modules
+may raise standard exceptions; in particular, SystemExit is usually raised for
+errors that are obviously the end-user's fault (eg. bad command-line arguments).
+
+This module is safe to use in ``from ... import *`` mode; it only exports
+symbols whose names start with ``Distutils`` and end with ``Error``.
+
+
+:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module
+===========================================================================
+
+.. module:: distutils.fancy_getopt
+ :synopsis: Additional getopt functionality
+
+
+This module provides a wrapper around the standard :mod:`getopt` module that
+provides the following additional features:
+
+* short and long options are tied together
+
+* options have help strings, so :func:`fancy_getopt` could potentially create a
+ complete usage summary
+
+* options set attributes of a passed-in object
+
+* boolean options can have "negative aliases" --- eg. if :option:`--quiet` is
+ the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the
+ command line sets *verbose* to false.
+
+**\*\*** Should be replaced with :mod:`optik` (which is also now known as
+:mod:`optparse` in Python 2.3 and later). **\*\***
+
+
+.. function:: fancy_getopt(options, negative_opt, object, args)
+
+ Wrapper function. *options* is a list of ``(long_option, short_option,
+ help_string)`` 3-tuples as described in the constructor for
+ :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names
+ to option names, both the key and value should be in the *options* list.
+ *object* is an object which will be used to store values (see the :meth:`getopt`
+ method of the :class:`FancyGetopt` class). *args* is the argument list. Will use
+ ``sys.argv[1:]`` if you pass ``None`` as *args*.
+
+
+.. function:: wrap_text(text, width)
+
+ Wraps *text* to less than *width* wide.
+
+ .. warning::
+
+ Should be replaced with :mod:`textwrap` (which is available in Python 2.3 and
+ later).
+
+
+.. class:: FancyGetopt([option_table=None])
+
+ The option_table is a list of 3-tuples: ``(long_option, short_option,
+ help_string)``
+
+ If an option takes an argument, its *long_option* should have ``'='`` appended;
+ *short_option* should just be a single character, no ``':'`` in any case.
+ *short_option* should be ``None`` if a *long_option* doesn't have a
+ corresponding *short_option*. All option tuples must have long options.
+
+The :class:`FancyGetopt` class provides the following methods:
+
+
+.. method:: FancyGetopt.getopt([args=None, object=None])
+
+ Parse command-line options in args. Store as attributes on *object*.
+
+ If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``. If *object* is
+ ``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores
+ option values there, and returns a tuple ``(args, object)``. If *object* is
+ supplied, it is modified in place and :func:`getopt` just returns *args*; in
+ both cases, the returned *args* is a modified copy of the passed-in *args* list,
+ which is left untouched.
+
+ .. % and args returned are?
+
+
+.. method:: FancyGetopt.get_option_order()
+
+ Returns the list of ``(option, value)`` tuples processed by the previous run of
+ :meth:`getopt` Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called
+ yet.
+
+
+.. method:: FancyGetopt.generate_help([header=None])
+
+ Generate help text (a list of strings, one per suggested line of output) from
+ the option table for this :class:`FancyGetopt` object.
+
+ If supplied, prints the supplied *header* at the top of the help.
+
+
+:mod:`distutils.filelist` --- The FileList class
+================================================
+
+.. module:: distutils.filelist
+ :synopsis: The FileList class, used for poking about the file system and building lists of
+ files.
+
+
+This module provides the :class:`FileList` class, used for poking about the
+filesystem and building lists of files.
+
+
+:mod:`distutils.log` --- Simple PEP 282-style logging
+=====================================================
+
+.. module:: distutils.log
+ :synopsis: A simple logging mechanism, 282-style
+
+
+.. warning::
+
+ Should be replaced with standard :mod:`logging` module.
+
+.. % \subsubsection{\module{} --- }
+.. % \declaremodule{standard}{distutils.magic}
+.. % \modulesynopsis{ }
+
+
+:mod:`distutils.spawn` --- Spawn a sub-process
+==============================================
+
+.. module:: distutils.spawn
+ :synopsis: Provides the spawn() function
+
+
+This module provides the :func:`spawn` function, a front-end to various
+platform-specific functions for launching another program in a sub-process.
+Also provides :func:`find_executable` to search the path for a given executable
+name.
+
+
+:mod:`distutils.sysconfig` --- System configuration information
+===============================================================
+
+.. module:: distutils.sysconfig
+ :synopsis: Low-level access to configuration information of the Python interpreter.
+.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+.. moduleauthor:: Greg Ward <gward@python.net>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+The :mod:`distutils.sysconfig` module provides access to Python's low-level
+configuration information. The specific configuration variables available
+depend heavily on the platform and configuration. The specific variables depend
+on the build process for the specific version of Python being run; the variables
+are those found in the :file:`Makefile` and configuration header that are
+installed with Python on Unix systems. The configuration header is called
+:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h`
+for earlier versions of Python.
+
+Some additional functions are provided which perform some useful manipulations
+for other parts of the :mod:`distutils` package.
+
+
+.. data:: PREFIX
+
+ The result of ``os.path.normpath(sys.prefix)``.
+
+
+.. data:: EXEC_PREFIX
+
+ The result of ``os.path.normpath(sys.exec_prefix)``.
+
+
+.. function:: get_config_var(name)
+
+ Return the value of a single variable. This is equivalent to
+ ``get_config_vars().get(name)``.
+
+
+.. function:: get_config_vars(...)
+
+ Return a set of variable definitions. If there are no arguments, this returns a
+ dictionary mapping names of configuration variables to values. If arguments are
+ provided, they should be strings, and the return value will be a sequence giving
+ the associated values. If a given name does not have a corresponding value,
+ ``None`` will be included for that variable.
+
+
+.. function:: get_config_h_filename()
+
+ Return the full path name of the configuration header. For Unix, this will be
+ the header generated by the :program:`configure` script; for other platforms the
+ header will have been supplied directly by the Python source distribution. The
+ file is a platform-specific text file.
+
+
+.. function:: get_makefile_filename()
+
+ Return the full path name of the :file:`Makefile` used to build Python. For
+ Unix, this will be a file generated by the :program:`configure` script; the
+ meaning for other platforms will vary. The file is a platform-specific text
+ file, if it exists. This function is only useful on POSIX platforms.
+
+
+.. function:: get_python_inc([plat_specific[, prefix]])
+
+ Return the directory for either the general or platform-dependent C include
+ files. If *plat_specific* is true, the platform-dependent include directory is
+ returned; if false or omitted, the platform-independent directory is returned.
+ If *prefix* is given, it is used as either the prefix instead of
+ :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
+ *plat_specific* is true.
+
+
+.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]])
+
+ Return the directory for either the general or platform-dependent library
+ installation. If *plat_specific* is true, the platform-dependent include
+ directory is returned; if false or omitted, the platform-independent directory
+ is returned. If *prefix* is given, it is used as either the prefix instead of
+ :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
+ *plat_specific* is true. If *standard_lib* is true, the directory for the
+ standard library is returned rather than the directory for the installation of
+ third-party extensions.
+
+The following function is only intended for use within the :mod:`distutils`
+package.
+
+
+.. function:: customize_compiler(compiler)
+
+ Do any platform-specific customization of a
+ :class:`distutils.ccompiler.CCompiler` instance.
+
+ This function is only needed on Unix at this time, but should be called
+ consistently to support forward-compatibility. It inserts the information that
+ varies across Unix flavors and is stored in Python's :file:`Makefile`. This
+ information includes the selected compiler, compiler and linker options, and the
+ extension used by the linker for shared objects.
+
+This function is even more special-purpose, and should only be used from
+Python's own build procedures.
+
+
+.. function:: set_python_build()
+
+ Inform the :mod:`distutils.sysconfig` module that it is being used as part of
+ the build process for Python. This changes a lot of relative locations for
+ files, allowing them to be located in the build area rather than in an installed
+ Python.
+
+
+:mod:`distutils.text_file` --- The TextFile class
+=================================================
+
+.. module:: distutils.text_file
+ :synopsis: provides the TextFile class, a simple interface to text files
+
+
+This module provides the :class:`TextFile` class, which gives an interface to
+text files that (optionally) takes care of stripping comments, ignoring blank
+lines, and joining lines with backslashes.
+
+
+.. class:: TextFile([filename=None, file=None, **options])
+
+ This class provides a file-like object that takes care of all the things you
+ commonly want to do when processing a text file that has some line-by-line
+ syntax: strip comments (as long as ``#`` is your comment character), skip blank
+ lines, join adjacent lines by escaping the newline (ie. backslash at end of
+ line), strip leading and/or trailing whitespace. All of these are optional and
+ independently controllable.
+
+ The class provides a :meth:`warn` method so you can generate warning messages
+ that report physical line number, even if the logical line in question spans
+ multiple physical lines. Also provides :meth:`unreadline` for implementing
+ line-at-a-time lookahead.
+
+ :class:`TextFile` instances are create with either *filename*, *file*, or both.
+ :exc:`RuntimeError` is raised if both are ``None``. *filename* should be a
+ string, and *file* a file object (or something that provides :meth:`readline`
+ and :meth:`close` methods). It is recommended that you supply at least
+ *filename*, so that :class:`TextFile` can include it in warning messages. If
+ *file* is not supplied, :class:`TextFile` creates its own using the
+ :func:`open` built-in function.
+
+ The options are all boolean, and affect the values returned by :meth:`readline`
+
+ +------------------+--------------------------------+---------+
+ | option name | description | default |
+ +==================+================================+=========+
+ | *strip_comments* | strip from ``'#'`` to end-of- | true |
+ | | line, as well as any | |
+ | | whitespace leading up to the | |
+ | | ``'#'``\ ---unless it is | |
+ | | escaped by a backslash | |
+ +------------------+--------------------------------+---------+
+ | *lstrip_ws* | strip leading whitespace from | false |
+ | | each line before returning it | |
+ +------------------+--------------------------------+---------+
+ | *rstrip_ws* | strip trailing whitespace | true |
+ | | (including line terminator!) | |
+ | | from each line before | |
+ | | returning it. | |
+ +------------------+--------------------------------+---------+
+ | *skip_blanks* | skip lines that are empty | true |
+ | | \*after\* stripping comments | |
+ | | and whitespace. (If both | |
+ | | lstrip_ws and rstrip_ws are | |
+ | | false, then some lines may | |
+ | | consist of solely whitespace: | |
+ | | these will \*not\* be skipped, | |
+ | | even if *skip_blanks* is | |
+ | | true.) | |
+ +------------------+--------------------------------+---------+
+ | *join_lines* | if a backslash is the last | false |
+ | | non-newline character on a | |
+ | | line after stripping comments | |
+ | | and whitespace, join the | |
+ | | following line to it to form | |
+ | | one logical line; if N | |
+ | | consecutive lines end with a | |
+ | | backslash, then N+1 physical | |
+ | | lines will be joined to form | |
+ | | one logical line. | |
+ +------------------+--------------------------------+---------+
+ | *collapse_join* | strip leading whitespace from | false |
+ | | lines that are joined to their | |
+ | | predecessor; only matters if | |
+ | | ``(join_lines and not | |
+ | | lstrip_ws)`` | |
+ +------------------+--------------------------------+---------+
+
+ Note that since *rstrip_ws* can strip the trailing newline, the semantics of
+ :meth:`readline` must differ from those of the builtin file object's
+ :meth:`readline` method! In particular, :meth:`readline` returns ``None`` for
+ end-of-file: an empty string might just be a blank line (or an all-whitespace
+ line), if *rstrip_ws* is true but *skip_blanks* is not.
+
+
+ .. method:: TextFile.open(filename)
+
+ Open a new file *filename*. This overrides any *file* or *filename* constructor
+ arguments.
+
+
+ .. method:: TextFile.close()
+
+ Close the current file and forget everything we know about it (including the
+ filename and the current line number).
+
+
+ .. method:: TextFile.warn(msg[,line=None])
+
+ Print (to stderr) a warning message tied to the current logical line in the
+ current file. If the current logical line in the file spans multiple physical
+ lines, the warning refers to the whole range, such as ``"lines 3-5"``. If
+ *line* is supplied, it overrides the current line number; it may be a list or
+ tuple to indicate a range of physical lines, or an integer for a single
+ physical line.
+
+
+ .. method:: TextFile.readline()
+
+ Read and return a single logical line from the current file (or from an internal
+ buffer if lines have previously been "unread" with :meth:`unreadline`). If the
+ *join_lines* option is true, this may involve reading multiple physical lines
+ concatenated into a single string. Updates the current line number, so calling
+ :meth:`warn` after :meth:`readline` emits a warning about the physical line(s)
+ just read. Returns ``None`` on end-of-file, since the empty string can occur
+ if *rstrip_ws* is true but *strip_blanks* is not.
+
+
+ .. method:: TextFile.readlines()
+
+ Read and return the list of all logical lines remaining in the current file.
+ This updates the current line number to the last line of the file.
+
+
+ .. method:: TextFile.unreadline(line)
+
+ Push *line* (a string) onto an internal buffer that will be checked by future
+ :meth:`readline` calls. Handy for implementing a parser with line-at-a-time
+ lookahead. Note that lines that are "unread" with :meth:`unreadline` are not
+ subsequently re-cleansed (whitespace stripped, or whatever) when read with
+ :meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call
+ to :meth:`readline`, the lines will be returned most in most recent first order.
+
+
+:mod:`distutils.version` --- Version number classes
+===================================================
+
+.. module:: distutils.version
+ :synopsis: implements classes that represent module version numbers.
+
+
+.. % todo
+.. % \section{Distutils Commands}
+.. %
+.. % This part of Distutils implements the various Distutils commands, such
+.. % as \code{build}, \code{install} \&c. Each command is implemented as a
+.. % separate module, with the command name as the name of the module.
+
+
+:mod:`distutils.cmd` --- Abstract base class for Distutils commands
+===================================================================
+
+.. module:: distutils.cmd
+ :synopsis: This module provides the abstract base class Command. This class is subclassed
+ by the modules in the distutils.command subpackage.
+
+
+This module supplies the abstract base class :class:`Command`.
+
+
+.. class:: Command(dist)
+
+ Abstract base class for defining command classes, the "worker bees" of the
+ Distutils. A useful analogy for command classes is to think of them as
+ subroutines with local variables called *options*. The options are declared in
+ :meth:`initialize_options` and defined (given their final values) in
+ :meth:`finalize_options`, both of which must be defined by every command class.
+ The distinction between the two is necessary because option values might come
+ from the outside world (command line, config file, ...), and any options
+ dependent on other options must be computed after these outside influences have
+ been processed --- hence :meth:`finalize_options`. The body of the subroutine,
+ where it does all its work based on the values of its options, is the
+ :meth:`run` method, which must also be implemented by every command class.
+
+ The class constructor takes a single argument *dist*, a :class:`Distribution`
+ instance.
+
+
+:mod:`distutils.command` --- Individual Distutils commands
+==========================================================
+
+.. module:: distutils.command
+ :synopsis: This subpackage contains one module for each standard Distutils command.
+
+
+.. % \subsubsection{Individual Distutils commands}
+.. % todo
+
+
+:mod:`distutils.command.bdist` --- Build a binary installer
+===========================================================
+
+.. module:: distutils.command.bdist
+ :synopsis: Build a binary installer for a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers
+=============================================================================
+
+.. module:: distutils.command.bdist_packager
+ :synopsis: Abstract base class for packagers
+
+
+.. % todo
+
+
+:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer
+================================================================
+
+.. module:: distutils.command.bdist_dumb
+ :synopsis: Build a "dumb" installer - a simple archive of files
+
+
+.. % todo
+
+
+:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
+=================================================================================
+
+.. module:: distutils.command.bdist_msi
+ :synopsis: Build a binary distribution as a Windows MSI file
+
+
+.. % todo
+
+
+:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
+===========================================================================================
+
+.. module:: distutils.command.bdist_rpm
+ :synopsis: Build a binary distribution as a Redhat RPM and SRPM
+
+
+.. % todo
+
+
+:mod:`distutils.command.bdist_wininst` --- Build a Windows installer
+====================================================================
+
+.. module:: distutils.command.bdist_wininst
+ :synopsis: Build a Windows installer
+
+
+.. % todo
+
+
+:mod:`distutils.command.sdist` --- Build a source distribution
+==============================================================
+
+.. module:: distutils.command.sdist
+ :synopsis: Build a source distribution
+
+
+.. % todo
+
+
+:mod:`distutils.command.build` --- Build all files of a package
+===============================================================
+
+.. module:: distutils.command.build
+ :synopsis: Build all files of a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.build_clib` --- Build any C libraries in a package
+==========================================================================
+
+.. module:: distutils.command.build_clib
+ :synopsis: Build any C libraries in a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.build_ext` --- Build any extensions in a package
+========================================================================
+
+.. module:: distutils.command.build_ext
+ :synopsis: Build any extensions in a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package
+===========================================================================
+
+.. module:: distutils.command.build_py
+ :synopsis: Build the .py/.pyc files of a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.build_scripts` --- Build the scripts of a package
+=========================================================================
+
+.. module:: distutils.command.build_scripts
+ :synopsis: Build the scripts of a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.clean` --- Clean a package build area
+=============================================================
+
+.. module:: distutils.command.clean
+ :synopsis: Clean a package build area
+
+
+.. % todo
+
+
+:mod:`distutils.command.config` --- Perform package configuration
+=================================================================
+
+.. module:: distutils.command.config
+ :synopsis: Perform package configuration
+
+
+.. % todo
+
+
+:mod:`distutils.command.install` --- Install a package
+======================================================
+
+.. module:: distutils.command.install
+ :synopsis: Install a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.install_data` --- Install data files from a package
+===========================================================================
+
+.. module:: distutils.command.install_data
+ :synopsis: Install data files from a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package
+======================================================================================
+
+.. module:: distutils.command.install_headers
+ :synopsis: Install C/C++ header files from a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.install_lib` --- Install library files from a package
+=============================================================================
+
+.. module:: distutils.command.install_lib
+ :synopsis: Install library files from a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.install_scripts` --- Install script files from a package
+================================================================================
+
+.. module:: distutils.command.install_scripts
+ :synopsis: Install script files from a package
+
+
+.. % todo
+
+
+:mod:`distutils.command.register` --- Register a module with the Python Package Index
+=====================================================================================
+
+.. module:: distutils.command.register
+ :synopsis: Register a module with the Python Package Index
+
+
+The ``register`` command registers the package with the Python Package Index.
+This is described in more detail in :pep:`301`.
+
+.. % todo
+
+
+Creating a new Distutils command
+================================
+
+This section outlines the steps to create a new Distutils command.
+
+A new command lives in a module in the :mod:`distutils.command` package. There
+is a sample template in that directory called :file:`command_template`. Copy
+this file to a new module with the same name as the new command you're
+implementing. This module should implement a class with the same name as the
+module (and the command). So, for instance, to create the command
+``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
+:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
+it so that it's implementing the class :class:`peel_banana`, a subclass of
+:class:`distutils.cmd.Command`.
+
+Subclasses of :class:`Command` must define the following methods.
+
+
+.. method:: Command.initialize_options()(S)
+
+ et default values for all the options that this command supports. Note that
+ these defaults may be overridden by other commands, by the setup script, by
+ config files, or by the command-line. Thus, this is not the place to code
+ dependencies between options; generally, :meth:`initialize_options`
+ implementations are just a bunch of ``self.foo = None`` assignments.
+
+
+.. method:: Command.finalize_options()
+
+ Set final values for all the options that this command supports. This is
+ always called as late as possible, ie. after any option assignments from the
+ command-line or from other commands have been done. Thus, this is the place
+ to to code option dependencies: if *foo* depends on *bar*, then it is safe to
+ set *foo* from *bar* as long as *foo* still has the same value it was
+ assigned in :meth:`initialize_options`.
+
+
+.. method:: Command.run()
+
+ A command's raison d'etre: carry out the action it exists to perform, controlled
+ by the options initialized in :meth:`initialize_options`, customized by other
+ commands, the setup script, the command-line, and config files, and finalized in
+ :meth:`finalize_options`. All terminal output and filesystem interaction should
+ be done by :meth:`run`.
+
+*sub_commands* formalizes the notion of a "family" of commands, eg. ``install``
+as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The
+parent of a family of commands defines *sub_commands* as a class attribute; it's
+a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string
+and *predicate* an unbound method, a string or None. *predicate* is a method of
+the parent command that determines whether the corresponding command is
+applicable in the current situation. (Eg. we ``install_headers`` is only
+applicable if we have any C header files to install.) If *predicate* is None,
+that command is always applicable.
+
+*sub_commands* is usually defined at the \*end\* of a class, because predicates
+can be unbound methods, so they must already have been defined. The canonical
+example is the :command:`install` command.
--- /dev/null
+.. _built-dist:
+
+****************************
+Creating Built Distributions
+****************************
+
+A "built distribution" is what you're probably used to thinking of either as a
+"binary package" or an "installer" (depending on your background). It's not
+necessarily binary, though, because it might contain only Python source code
+and/or byte-code; and we don't call it a package, because that word is already
+spoken for in Python. (And "installer" is a term specific to the world of
+mainstream desktop systems.)
+
+A built distribution is how you make life as easy as possible for installers of
+your module distribution: for users of RPM-based Linux systems, it's a binary
+RPM; for Windows users, it's an executable installer; for Debian-based Linux
+users, it's a Debian package; and so forth. Obviously, no one person will be
+able to create built distributions for every platform under the sun, so the
+Distutils are designed to enable module developers to concentrate on their
+specialty---writing code and creating source distributions---while an
+intermediary species called *packagers* springs up to turn source distributions
+into built distributions for as many platforms as there are packagers.
+
+Of course, the module developer could be his own packager; or the packager could
+be a volunteer "out there" somewhere who has access to a platform which the
+original developer does not; or it could be software periodically grabbing new
+source distributions and turning them into built distributions for as many
+platforms as the software has access to. Regardless of who they are, a packager
+uses the setup script and the :command:`bdist` command family to generate built
+distributions.
+
+As a simple example, if I run the following command in the Distutils source
+tree::
+
+ python setup.py bdist
+
+then the Distutils builds my module distribution (the Distutils itself in this
+case), does a "fake" installation (also in the :file:`build` directory), and
+creates the default type of built distribution for my platform. The default
+format for built distributions is a "dumb" tar file on Unix, and a simple
+executable installer on Windows. (That tar file is considered "dumb" because it
+has to be unpacked in a specific location to work.)
+
+Thus, the above command on a Unix system creates
+:file:`Distutils-1.0.{plat}.tar.gz`; unpacking this tarball from the right place
+installs the Distutils just as though you had downloaded the source distribution
+and run ``python setup.py install``. (The "right place" is either the root of
+the filesystem or Python's :file:`{prefix}` directory, depending on the options
+given to the :command:`bdist_dumb` command; the default is to make dumb
+distributions relative to :file:`{prefix}`.)
+
+Obviously, for pure Python distributions, this isn't any simpler than just
+running ``python setup.py install``\ ---but for non-pure distributions, which
+include extensions that would need to be compiled, it can mean the difference
+between someone being able to use your extensions or not. And creating "smart"
+built distributions, such as an RPM package or an executable installer for
+Windows, is far more convenient for users even if your distribution doesn't
+include any extensions.
+
+The :command:`bdist` command has a :option:`--formats` option, similar to the
+:command:`sdist` command, which you can use to select the types of built
+distribution to generate: for example, ::
+
+ python setup.py bdist --format=zip
+
+would, when run on a Unix system, create :file:`Distutils-1.0.{plat}.zip`\
+---again, this archive would be unpacked from the root directory to install the
+Distutils.
+
+The available formats for built distributions are:
+
++-------------+------------------------------+---------+
+| Format | Description | Notes |
++=============+==============================+=========+
+| ``gztar`` | gzipped tar file | (1),(3) |
+| | (:file:`.tar.gz`) | |
++-------------+------------------------------+---------+
+| ``ztar`` | compressed tar file | \(3) |
+| | (:file:`.tar.Z`) | |
++-------------+------------------------------+---------+
+| ``tar`` | tar file (:file:`.tar`) | \(3) |
++-------------+------------------------------+---------+
+| ``zip`` | zip file (:file:`.zip`) | \(4) |
++-------------+------------------------------+---------+
+| ``rpm`` | RPM | \(5) |
++-------------+------------------------------+---------+
+| ``pkgtool`` | Solaris :program:`pkgtool` | |
++-------------+------------------------------+---------+
+| ``sdux`` | HP-UX :program:`swinstall` | |
++-------------+------------------------------+---------+
+| ``rpm`` | RPM | \(5) |
++-------------+------------------------------+---------+
+| ``wininst`` | self-extracting ZIP file for | (2),(4) |
+| | Windows | |
++-------------+------------------------------+---------+
+
+Notes:
+
+(1)
+ default on Unix
+
+(2)
+ default on Windows
+
+ **\*\*** to-do! **\*\***
+
+(3)
+ requires external utilities: :program:`tar` and possibly one of :program:`gzip`,
+ :program:`bzip2`, or :program:`compress`
+
+(4)
+ requires either external :program:`zip` utility or :mod:`zipfile` module (part
+ of the standard Python library since Python 1.6)
+
+(5)
+ requires external :program:`rpm` utility, version 3.0.4 or better (use ``rpm
+ --version`` to find out which version you have)
+
+You don't have to use the :command:`bdist` command with the :option:`--formats`
+option; you can also use the command that directly implements the format you're
+interested in. Some of these :command:`bdist` "sub-commands" actually generate
+several similar formats; for instance, the :command:`bdist_dumb` command
+generates all the "dumb" archive formats (``tar``, ``ztar``, ``gztar``, and
+``zip``), and :command:`bdist_rpm` generates both binary and source RPMs. The
+:command:`bdist` sub-commands, and the formats generated by each, are:
+
++--------------------------+-----------------------+
+| Command | Formats |
++==========================+=======================+
+| :command:`bdist_dumb` | tar, ztar, gztar, zip |
++--------------------------+-----------------------+
+| :command:`bdist_rpm` | rpm, srpm |
++--------------------------+-----------------------+
+| :command:`bdist_wininst` | wininst |
++--------------------------+-----------------------+
+
+The following sections give details on the individual :command:`bdist_\*`
+commands.
+
+
+.. _creating-dumb:
+
+Creating dumb built distributions
+=================================
+
+**\*\*** Need to document absolute vs. prefix-relative packages here, but first
+I have to implement it! **\*\***
+
+
+.. _creating-rpms:
+
+Creating RPM packages
+=====================
+
+The RPM format is used by many popular Linux distributions, including Red Hat,
+SuSE, and Mandrake. If one of these (or any of the other RPM-based Linux
+distributions) is your usual environment, creating RPM packages for other users
+of that same distribution is trivial. Depending on the complexity of your module
+distribution and differences between Linux distributions, you may also be able
+to create RPMs that work on different RPM-based distributions.
+
+The usual way to create an RPM of your module distribution is to run the
+:command:`bdist_rpm` command::
+
+ python setup.py bdist_rpm
+
+or the :command:`bdist` command with the :option:`--format` option::
+
+ python setup.py bdist --formats=rpm
+
+The former allows you to specify RPM-specific options; the latter allows you to
+easily specify multiple formats in one run. If you need to do both, you can
+explicitly specify multiple :command:`bdist_\*` commands and their options::
+
+ python setup.py bdist_rpm --packager="John Doe <jdoe@example.org>" \
+ bdist_wininst --target_version="2.0"
+
+Creating RPM packages is driven by a :file:`.spec` file, much as using the
+Distutils is driven by the setup script. To make your life easier, the
+:command:`bdist_rpm` command normally creates a :file:`.spec` file based on the
+information you supply in the setup script, on the command line, and in any
+Distutils configuration files. Various options and sections in the
+:file:`.spec` file are derived from options in the setup script as follows:
+
++------------------------------------------+----------------------------------------------+
+| RPM :file:`.spec` file option or section | Distutils setup script option |
++==========================================+==============================================+
+| Name | :option:`name` |
++------------------------------------------+----------------------------------------------+
+| Summary (in preamble) | :option:`description` |
++------------------------------------------+----------------------------------------------+
+| Version | :option:`version` |
++------------------------------------------+----------------------------------------------+
+| Vendor | :option:`author` and :option:`author_email`, |
+| | or --- & :option:`maintainer` and |
+| | :option:`maintainer_email` |
++------------------------------------------+----------------------------------------------+
+| Copyright | :option:`licence` |
++------------------------------------------+----------------------------------------------+
+| Url | :option:`url` |
++------------------------------------------+----------------------------------------------+
+| %description (section) | :option:`long_description` |
++------------------------------------------+----------------------------------------------+
+
+Additionally, there are many options in :file:`.spec` files that don't have
+corresponding options in the setup script. Most of these are handled through
+options to the :command:`bdist_rpm` command as follows:
+
++-------------------------------+-----------------------------+-------------------------+
+| RPM :file:`.spec` file option | :command:`bdist_rpm` option | default value |
+| or section | | |
++===============================+=============================+=========================+
+| Release | :option:`release` | "1" |
++-------------------------------+-----------------------------+-------------------------+
+| Group | :option:`group` | "Development/Libraries" |
++-------------------------------+-----------------------------+-------------------------+
+| Vendor | :option:`vendor` | (see above) |
++-------------------------------+-----------------------------+-------------------------+
+| Packager | :option:`packager` | (none) |
++-------------------------------+-----------------------------+-------------------------+
+| Provides | :option:`provides` | (none) |
++-------------------------------+-----------------------------+-------------------------+
+| Requires | :option:`requires` | (none) |
++-------------------------------+-----------------------------+-------------------------+
+| Conflicts | :option:`conflicts` | (none) |
++-------------------------------+-----------------------------+-------------------------+
+| Obsoletes | :option:`obsoletes` | (none) |
++-------------------------------+-----------------------------+-------------------------+
+| Distribution | :option:`distribution_name` | (none) |
++-------------------------------+-----------------------------+-------------------------+
+| BuildRequires | :option:`build_requires` | (none) |
++-------------------------------+-----------------------------+-------------------------+
+| Icon | :option:`icon` | (none) |
++-------------------------------+-----------------------------+-------------------------+
+
+Obviously, supplying even a few of these options on the command-line would be
+tedious and error-prone, so it's usually best to put them in the setup
+configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If
+you distribute or package many Python module distributions, you might want to
+put options that apply to all of them in your personal Distutils configuration
+file (:file:`~/.pydistutils.cfg`).
+
+There are three steps to building a binary RPM package, all of which are
+handled automatically by the Distutils:
+
+#. create a :file:`.spec` file, which describes the package (analogous to the
+ Distutils setup script; in fact, much of the information in the setup script
+ winds up in the :file:`.spec` file)
+
+#. create the source RPM
+
+#. create the "binary" RPM (which may or may not contain binary code, depending
+ on whether your module distribution contains Python extensions)
+
+Normally, RPM bundles the last two steps together; when you use the Distutils,
+all three steps are typically bundled together.
+
+If you wish, you can separate these three steps. You can use the
+:option:`--spec-only` option to make :command:`bdist_rpm` just create the
+:file:`.spec` file and exit; in this case, the :file:`.spec` file will be
+written to the "distribution directory"---normally :file:`dist/`, but
+customizable with the :option:`--dist-dir` option. (Normally, the :file:`.spec`
+file winds up deep in the "build tree," in a temporary directory created by
+:command:`bdist_rpm`.)
+
+.. % \XXX{this isn't implemented yet---is it needed?!}
+.. % You can also specify a custom \file{.spec} file with the
+.. % \longprogramopt{spec-file} option; used in conjunction with
+.. % \longprogramopt{spec-only}, this gives you an opportunity to customize
+.. % the \file{.spec} file manually:
+.. %
+.. % \ begin{verbatim}
+.. % > python setup.py bdist_rpm --spec-only
+.. % # ...edit dist/FooBar-1.0.spec
+.. % > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec
+.. % \ end{verbatim}
+.. %
+.. % (Although a better way to do this is probably to override the standard
+.. % \command{bdist\_rpm} command with one that writes whatever else you want
+.. % to the \file{.spec} file.)
+
+
+.. _creating-wininst:
+
+Creating Windows Installers
+===========================
+
+Executable installers are the natural format for binary distributions on
+Windows. They display a nice graphical user interface, display some information
+about the module distribution to be installed taken from the metadata in the
+setup script, let the user select a few options, and start or cancel the
+installation.
+
+Since the metadata is taken from the setup script, creating Windows installers
+is usually as easy as running::
+
+ python setup.py bdist_wininst
+
+or the :command:`bdist` command with the :option:`--formats` option::
+
+ python setup.py bdist --formats=wininst
+
+If you have a pure module distribution (only containing pure Python modules and
+packages), the resulting installer will be version independent and have a name
+like :file:`foo-1.0.win32.exe`. These installers can even be created on Unix or
+Mac OS platforms.
+
+If you have a non-pure distribution, the extensions can only be created on a
+Windows platform, and will be Python version dependent. The installer filename
+will reflect this and now has the form :file:`foo-1.0.win32-py2.0.exe`. You
+have to create a separate installer for every Python version you want to
+support.
+
+The installer will try to compile pure modules into bytecode after installation
+on the target system in normal and optimizing mode. If you don't want this to
+happen for some reason, you can run the :command:`bdist_wininst` command with
+the :option:`--no-target-compile` and/or the :option:`--no-target-optimize`
+option.
+
+By default the installer will display the cool "Python Powered" logo when it is
+run, but you can also supply your own bitmap which must be a Windows
+:file:`.bmp` file with the :option:`--bitmap` option.
+
+The installer will also display a large title on the desktop background window
+when it is run, which is constructed from the name of your distribution and the
+version number. This can be changed to another text by using the
+:option:`--title` option.
+
+The installer file will be written to the "distribution directory" --- normally
+:file:`dist/`, but customizable with the :option:`--dist-dir` option.
+
+
+.. _postinstallation-script:
+
+The Postinstallation script
+---------------------------
+
+Starting with Python 2.3, a postinstallation script can be specified which the
+:option:`--install-script` option. The basename of the script must be
+specified, and the script filename must also be listed in the scripts argument
+to the setup function.
+
+This script will be run at installation time on the target system after all the
+files have been copied, with ``argv[1]`` set to :option:`-install`, and again at
+uninstallation time before the files are removed with ``argv[1]`` set to
+:option:`-remove`.
+
+The installation script runs embedded in the windows installer, every output
+(``sys.stdout``, ``sys.stderr``) is redirected into a buffer and will be
+displayed in the GUI after the script has finished.
+
+Some functions especially useful in this context are available as additional
+built-in functions in the installation script.
+
+
+.. function:: directory_created(path)
+ file_created(path)
+
+ These functions should be called when a directory or file is created by the
+ postinstall script at installation time. It will register *path* with the
+ uninstaller, so that it will be removed when the distribution is uninstalled.
+ To be safe, directories are only removed if they are empty.
+
+
+.. function:: get_special_folder_path(csidl_string)
+
+ This function can be used to retrieve special folder locations on Windows like
+ the Start Menu or the Desktop. It returns the full path to the folder.
+ *csidl_string* must be one of the following strings::
+
+ "CSIDL_APPDATA"
+
+ "CSIDL_COMMON_STARTMENU"
+ "CSIDL_STARTMENU"
+
+ "CSIDL_COMMON_DESKTOPDIRECTORY"
+ "CSIDL_DESKTOPDIRECTORY"
+
+ "CSIDL_COMMON_STARTUP"
+ "CSIDL_STARTUP"
+
+ "CSIDL_COMMON_PROGRAMS"
+ "CSIDL_PROGRAMS"
+
+ "CSIDL_FONTS"
+
+ If the folder cannot be retrieved, :exc:`OSError` is raised.
+
+ Which folders are available depends on the exact Windows version, and probably
+ also the configuration. For details refer to Microsoft's documentation of the
+ :cfunc:`SHGetSpecialFolderPath` function.
+
+
+.. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]])
+
+ This function creates a shortcut. *target* is the path to the program to be
+ started by the shortcut. *description* is the description of the shortcut.
+ *filename* is the title of the shortcut that the user will see. *arguments*
+ specifies the command line arguments, if any. *workdir* is the working directory
+ for the program. *iconpath* is the file containing the icon for the shortcut,
+ and *iconindex* is the index of the icon in the file *iconpath*. Again, for
+ details consult the Microsoft documentation for the :class:`IShellLink`
+ interface.
+
+
--- /dev/null
+.. _reference:
+
+*****************
+Command Reference
+*****************
+
+.. % \section{Building modules: the \protect\command{build} command family}
+.. % \label{build-cmds}
+.. % \subsubsection{\protect\command{build}}
+.. % \label{build-cmd}
+.. % \subsubsection{\protect\command{build\_py}}
+.. % \label{build-py-cmd}
+.. % \subsubsection{\protect\command{build\_ext}}
+.. % \label{build-ext-cmd}
+.. % \subsubsection{\protect\command{build\_clib}}
+.. % \label{build-clib-cmd}
+
+
+.. _install-cmd:
+
+Installing modules: the :command:`install` command family
+=========================================================
+
+The install command ensures that the build commands have been run and then runs
+the subcommands :command:`install_lib`, :command:`install_data` and
+:command:`install_scripts`.
+
+.. % \subsubsection{\protect\command{install\_lib}}
+.. % \label{install-lib-cmd}
+
+
+.. _install-data-cmd:
+
+:command:`install_data`
+-----------------------
+
+This command installs all data files provided with the distribution.
+
+
+.. _install-scripts-cmd:
+
+:command:`install_scripts`
+--------------------------
+
+This command installs all (Python) scripts in the distribution.
+
+.. % \subsection{Cleaning up: the \protect\command{clean} command}
+.. % \label{clean-cmd}
+
+
+.. _sdist-cmd:
+
+Creating a source distribution: the :command:`sdist` command
+============================================================
+
+**\*\*** fragment moved down from above: needs context! **\*\***
+
+The manifest template commands are:
+
++-------------------------------------------+-----------------------------------------------+
+| Command | Description |
++===========================================+===============================================+
+| :command:`include pat1 pat2 ...` | include all files matching any of the listed |
+| | patterns |
++-------------------------------------------+-----------------------------------------------+
+| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed |
+| | patterns |
++-------------------------------------------+-----------------------------------------------+
+| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
+| ...` | the listed patterns |
++-------------------------------------------+-----------------------------------------------+
+| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
+| ...` | the listed patterns |
++-------------------------------------------+-----------------------------------------------+
+| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree |
+| | matching --- & any of the listed patterns |
++-------------------------------------------+-----------------------------------------------+
+| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree |
+| | matching --- & any of the listed patterns |
++-------------------------------------------+-----------------------------------------------+
+| :command:`prune dir` | exclude all files under *dir* |
++-------------------------------------------+-----------------------------------------------+
+| :command:`graft dir` | include all files under *dir* |
++-------------------------------------------+-----------------------------------------------+
+
+The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of
+regular filename characters, ``?`` matches any single regular filename
+character, and ``[range]`` matches any of the characters in *range* (e.g.,
+``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename
+character" is platform-specific: on Unix it is anything except slash; on Windows
+anything except backslash or colon; on Mac OS 9 anything except colon.
+
+**\*\*** Windows support not there yet **\*\***
+
+.. % \section{Creating a built distribution: the
+.. % \protect\command{bdist} command family}
+.. % \label{bdist-cmds}
+
+.. % \subsection{\protect\command{bdist}}
+.. % \subsection{\protect\command{bdist\_dumb}}
+.. % \subsection{\protect\command{bdist\_rpm}}
+.. % \subsection{\protect\command{bdist\_wininst}}
+
+
--- /dev/null
+.. _setup-config:
+
+************************************
+Writing the Setup Configuration File
+************************************
+
+Often, it's not possible to write down everything needed to build a distribution
+*a priori*: you may need to get some information from the user, or from the
+user's system, in order to proceed. As long as that information is fairly
+simple---a list of directories to search for C header files or libraries, for
+example---then providing a configuration file, :file:`setup.cfg`, for users to
+edit is a cheap and easy way to solicit it. Configuration files also let you
+provide default values for any command option, which the installer can then
+override either on the command-line or by editing the config file.
+
+The setup configuration file is a useful middle-ground between the setup script
+---which, ideally, would be opaque to installers [#]_---and the command-line to
+the setup script, which is outside of your control and entirely up to the
+installer. In fact, :file:`setup.cfg` (and any other Distutils configuration
+files present on the target system) are processed after the contents of the
+setup script, but before the command-line. This has several useful
+consequences:
+
+.. % (If you have more advanced needs, such as determining which extensions
+.. % to build based on what capabilities are present on the target system,
+.. % then you need the Distutils ``auto-configuration'' facility. This
+.. % started to appear in Distutils 0.9 but, as of this writing, isn't mature
+.. % or stable enough yet for real-world use.)
+
+* installers can override some of what you put in :file:`setup.py` by editing
+ :file:`setup.cfg`
+
+* you can provide non-standard defaults for options that are not easily set in
+ :file:`setup.py`
+
+* installers can override anything in :file:`setup.cfg` using the command-line
+ options to :file:`setup.py`
+
+The basic syntax of the configuration file is simple::
+
+ [command]
+ option=value
+ ...
+
+where *command* is one of the Distutils commands (e.g. :command:`build_py`,
+:command:`install`), and *option* is one of the options that command supports.
+Any number of options can be supplied for each command, and any number of
+command sections can be included in the file. Blank lines are ignored, as are
+comments, which run from a ``'#'`` character until the end of the line. Long
+option values can be split across multiple lines simply by indenting the
+continuation lines.
+
+You can find out the list of options supported by a particular command with the
+universal :option:`--help` option, e.g. ::
+
+ > python setup.py --help build_ext
+ [...]
+ Options for 'build_ext' command:
+ --build-lib (-b) directory for compiled extension modules
+ --build-temp (-t) directory for temporary files (build by-products)
+ --inplace (-i) ignore build-lib and put compiled extensions into the
+ source directory alongside your pure Python modules
+ --include-dirs (-I) list of directories to search for header files
+ --define (-D) C preprocessor macros to define
+ --undef (-U) C preprocessor macros to undefine
+ --swig-opts list of SWIG command line options
+ [...]
+
+Note that an option spelled :option:`--foo-bar` on the command-line is spelled
+:option:`foo_bar` in configuration files.
+
+For example, say you want your extensions to be built "in-place"---that is, you
+have an extension :mod:`pkg.ext`, and you want the compiled extension file
+(:file:`ext.so` on Unix, say) to be put in the same source directory as your
+pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`. You can always use the
+:option:`--inplace` option on the command-line to ensure this::
+
+ python setup.py build_ext --inplace
+
+But this requires that you always specify the :command:`build_ext` command
+explicitly, and remember to provide :option:`--inplace`. An easier way is to
+"set and forget" this option, by encoding it in :file:`setup.cfg`, the
+configuration file for this distribution::
+
+ [build_ext]
+ inplace=1
+
+This will affect all builds of this module distribution, whether or not you
+explicitly specify :command:`build_ext`. If you include :file:`setup.cfg` in
+your source distribution, it will also affect end-user builds---which is
+probably a bad idea for this option, since always building extensions in-place
+would break installation of the module distribution. In certain peculiar cases,
+though, modules are built right in their installation directory, so this is
+conceivably a useful ability. (Distributing extensions that expect to be built
+in their installation directory is almost always a bad idea, though.)
+
+Another example: certain commands take a lot of options that don't change from
+run to run; for example, :command:`bdist_rpm` needs to know everything required
+to generate a "spec" file for creating an RPM distribution. Some of this
+information comes from the setup script, and some is automatically generated by
+the Distutils (such as the list of files installed). But some of it has to be
+supplied as options to :command:`bdist_rpm`, which would be very tedious to do
+on the command-line for every run. Hence, here is a snippet from the Distutils'
+own :file:`setup.cfg`::
+
+ [bdist_rpm]
+ release = 1
+ packager = Greg Ward <gward@python.net>
+ doc_files = CHANGES.txt
+ README.txt
+ USAGE.txt
+ doc/
+ examples/
+
+Note that the :option:`doc_files` option is simply a whitespace-separated string
+split across multiple lines for readability.
+
+
+.. seealso::
+
+ :ref:`inst-config-syntax` in "Installing Python Modules"
+ More information on the configuration files is available in the manual for
+ system administrators.
+
+
+.. rubric:: Footnotes
+
+.. [#] This ideal probably won't be achieved until auto-configuration is fully
+ supported by the Distutils.
+
--- /dev/null
+.. _examples:
+
+********
+Examples
+********
+
+This chapter provides a number of basic examples to help get started with
+distutils. Additional information about using distutils can be found in the
+Distutils Cookbook.
+
+
+.. seealso::
+
+ `Distutils Cookbook <http://www.python.org/cgi-bin/moinmoin/DistutilsCookbook>`_
+ Collection of recipes showing how to achieve more control over distutils.
+
+
+.. _pure-mod:
+
+Pure Python distribution (by module)
+====================================
+
+If you're just distributing a couple of modules, especially if they don't live
+in a particular package, you can specify them individually using the
+:option:`py_modules` option in the setup script.
+
+In the simplest case, you'll have two files to worry about: a setup script and
+the single module you're distributing, :file:`foo.py` in this example::
+
+ <root>/
+ setup.py
+ foo.py
+
+(In all diagrams in this section, *<root>* will refer to the distribution root
+directory.) A minimal setup script to describe this situation would be::
+
+ from distutils.core import setup
+ setup(name='foo',
+ version='1.0',
+ py_modules=['foo'],
+ )
+
+Note that the name of the distribution is specified independently with the
+:option:`name` option, and there's no rule that says it has to be the same as
+the name of the sole module in the distribution (although that's probably a good
+convention to follow). However, the distribution name is used to generate
+filenames, so you should stick to letters, digits, underscores, and hyphens.
+
+Since :option:`py_modules` is a list, you can of course specify multiple
+modules, eg. if you're distributing modules :mod:`foo` and :mod:`bar`, your
+setup might look like this::
+
+ <root>/
+ setup.py
+ foo.py
+ bar.py
+
+and the setup script might be ::
+
+ from distutils.core import setup
+ setup(name='foobar',
+ version='1.0',
+ py_modules=['foo', 'bar'],
+ )
+
+You can put module source files into another directory, but if you have enough
+modules to do that, it's probably easier to specify modules by package rather
+than listing them individually.
+
+
+.. _pure-pkg:
+
+Pure Python distribution (by package)
+=====================================
+
+If you have more than a couple of modules to distribute, especially if they are
+in multiple packages, it's probably easier to specify whole packages rather than
+individual modules. This works even if your modules are not in a package; you
+can just tell the Distutils to process modules from the root package, and that
+works the same as any other package (except that you don't have to have an
+:file:`__init__.py` file).
+
+The setup script from the last example could also be written as ::
+
+ from distutils.core import setup
+ setup(name='foobar',
+ version='1.0',
+ packages=[''],
+ )
+
+(The empty string stands for the root package.)
+
+If those two files are moved into a subdirectory, but remain in the root
+package, e.g.::
+
+ <root>/
+ setup.py
+ src/ foo.py
+ bar.py
+
+then you would still specify the root package, but you have to tell the
+Distutils where source files in the root package live::
+
+ from distutils.core import setup
+ setup(name='foobar',
+ version='1.0',
+ package_dir={'': 'src'},
+ packages=[''],
+ )
+
+More typically, though, you will want to distribute multiple modules in the same
+package (or in sub-packages). For example, if the :mod:`foo` and :mod:`bar`
+modules belong in package :mod:`foobar`, one way to layout your source tree is
+::
+
+ <root>/
+ setup.py
+ foobar/
+ __init__.py
+ foo.py
+ bar.py
+
+This is in fact the default layout expected by the Distutils, and the one that
+requires the least work to describe in your setup script::
+
+ from distutils.core import setup
+ setup(name='foobar',
+ version='1.0',
+ packages=['foobar'],
+ )
+
+If you want to put modules in directories not named for their package, then you
+need to use the :option:`package_dir` option again. For example, if the
+:file:`src` directory holds modules in the :mod:`foobar` package::
+
+ <root>/
+ setup.py
+ src/
+ __init__.py
+ foo.py
+ bar.py
+
+an appropriate setup script would be ::
+
+ from distutils.core import setup
+ setup(name='foobar',
+ version='1.0',
+ package_dir={'foobar': 'src'},
+ packages=['foobar'],
+ )
+
+Or, you might put modules from your main package right in the distribution
+root::
+
+ <root>/
+ setup.py
+ __init__.py
+ foo.py
+ bar.py
+
+in which case your setup script would be ::
+
+ from distutils.core import setup
+ setup(name='foobar',
+ version='1.0',
+ package_dir={'foobar': ''},
+ packages=['foobar'],
+ )
+
+(The empty string also stands for the current directory.)
+
+If you have sub-packages, they must be explicitly listed in :option:`packages`,
+but any entries in :option:`package_dir` automatically extend to sub-packages.
+(In other words, the Distutils does *not* scan your source tree, trying to
+figure out which directories correspond to Python packages by looking for
+:file:`__init__.py` files.) Thus, if the default layout grows a sub-package::
+
+ <root>/
+ setup.py
+ foobar/
+ __init__.py
+ foo.py
+ bar.py
+ subfoo/
+ __init__.py
+ blah.py
+
+then the corresponding setup script would be ::
+
+ from distutils.core import setup
+ setup(name='foobar',
+ version='1.0',
+ packages=['foobar', 'foobar.subfoo'],
+ )
+
+(Again, the empty string in :option:`package_dir` stands for the current
+directory.)
+
+
+.. _single-ext:
+
+Single extension module
+=======================
+
+Extension modules are specified using the :option:`ext_modules` option.
+:option:`package_dir` has no effect on where extension source files are found;
+it only affects the source for pure Python modules. The simplest case, a
+single extension module in a single C source file, is::
+
+ <root>/
+ setup.py
+ foo.c
+
+If the :mod:`foo` extension belongs in the root package, the setup script for
+this could be ::
+
+ from distutils.core import setup
+ from distutils.extension import Extension
+ setup(name='foobar',
+ version='1.0',
+ ext_modules=[Extension('foo', ['foo.c'])],
+ )
+
+If the extension actually belongs in a package, say :mod:`foopkg`, then
+
+With exactly the same source tree layout, this extension can be put in the
+:mod:`foopkg` package simply by changing the name of the extension::
+
+ from distutils.core import setup
+ from distutils.extension import Extension
+ setup(name='foobar',
+ version='1.0',
+ ext_modules=[Extension('foopkg.foo', ['foo.c'])],
+ )
+
+.. % \section{Multiple extension modules}
+.. % \label{multiple-ext}
+
+.. % \section{Putting it all together}
+
+
--- /dev/null
+.. _extending:
+
+*******************
+Extending Distutils
+*******************
+
+Distutils can be extended in various ways. Most extensions take the form of new
+commands or replacements for existing commands. New commands may be written to
+support new types of platform-specific packaging, for example, while
+replacements for existing commands may be made to modify details of how the
+command operates on a package.
+
+Most extensions of the distutils are made within :file:`setup.py` scripts that
+want to modify existing commands; many simply add a few file extensions that
+should be copied into packages in addition to :file:`.py` files as a
+convenience.
+
+Most distutils command implementations are subclasses of the :class:`Command`
+class from :mod:`distutils.cmd`. New commands may directly inherit from
+:class:`Command`, while replacements often derive from :class:`Command`
+indirectly, directly subclassing the command they are replacing. Commands are
+required to derive from :class:`Command`.
+
+.. % \section{Extending existing commands}
+.. % \label{extend-existing}
+
+.. % \section{Writing new commands}
+.. % \label{new-commands}
+.. % \XXX{Would an uninstall command be a good example here?}
+
+
+Integrating new commands
+========================
+
+There are different ways to integrate new command implementations into
+distutils. The most difficult is to lobby for the inclusion of the new features
+in distutils itself, and wait for (and require) a version of Python that
+provides that support. This is really hard for many reasons.
+
+The most common, and possibly the most reasonable for most needs, is to include
+the new implementations with your :file:`setup.py` script, and cause the
+:func:`distutils.core.setup` function use them::
+
+ from distutils.command.build_py import build_py as _build_py
+ from distutils.core import setup
+
+ class build_py(_build_py):
+ """Specialized Python source builder."""
+
+ # implement whatever needs to be different...
+
+ setup(cmdclass={'build_py': build_py},
+ ...)
+
+This approach is most valuable if the new implementations must be used to use a
+particular package, as everyone interested in the package will need to have the
+new command implementation.
+
+Beginning with Python 2.4, a third option is available, intended to allow new
+commands to be added which can support existing :file:`setup.py` scripts without
+requiring modifications to the Python installation. This is expected to allow
+third-party extensions to provide support for additional packaging systems, but
+the commands can be used for anything distutils commands can be used for. A new
+configuration option, :option:`command_packages` (command-line option
+:option:`--command-packages`), can be used to specify additional packages to be
+searched for modules implementing commands. Like all distutils options, this
+can be specified on the command line or in a configuration file. This option
+can only be set in the ``[global]`` section of a configuration file, or before
+any commands on the command line. If set in a configuration file, it can be
+overridden from the command line; setting it to an empty string on the command
+line causes the default to be used. This should never be set in a configuration
+file provided with a package.
+
+This new option can be used to add any number of packages to the list of
+packages searched for command implementations; multiple package names should be
+separated by commas. When not specified, the search is only performed in the
+:mod:`distutils.command` package. When :file:`setup.py` is run with the option
+:option:`--command-packages` :option:`distcmds,buildcmds`, however, the packages
+:mod:`distutils.command`, :mod:`distcmds`, and :mod:`buildcmds` will be searched
+in that order. New commands are expected to be implemented in modules of the
+same name as the command by classes sharing the same name. Given the example
+command line option above, the command :command:`bdist_openpkg` could be
+implemented by the class :class:`distcmds.bdist_openpkg.bdist_openpkg` or
+:class:`buildcmds.bdist_openpkg.bdist_openpkg`.
+
+
+Adding new distribution types
+=============================
+
+Commands that create distributions (files in the :file:`dist/` directory) need
+to add ``(command, filename)`` pairs to ``self.distribution.dist_files`` so that
+:command:`upload` can upload it to PyPI. The *filename* in the pair contains no
+path information, only the name of the file itself. In dry-run mode, pairs
+should still be added to represent what would have been created.
+
+
--- /dev/null
+.. _distutils-index:
+
+###############################
+ Distributing Python Modules
+###############################
+
+:Authors: Greg Ward, Anthony Baxter
+:Email: distutils-sig@python.org
+:Release: |version|
+:Date: |today|
+
+This document describes the Python Distribution Utilities ("Distutils") from
+the module developer's point of view, describing how to use the Distutils to
+make Python modules and extensions easily available to a wider audience with
+very little overhead for build/release/install mechanics.
+
+.. toctree::
+ :maxdepth: 2
+
+ introduction.rst
+ setupscript.rst
+ configfile.rst
+ sourcedist.rst
+ builtdist.rst
+ packageindex.rst
+ uploading.rst
+ examples.rst
+ extending.rst
+ commandref.rst
+ apiref.rst
--- /dev/null
+.. _distutils-intro:
+
+****************************
+An Introduction to Distutils
+****************************
+
+This document covers using the Distutils to distribute your Python modules,
+concentrating on the role of developer/distributor: if you're looking for
+information on installing Python modules, you should refer to the
+:ref:`install-index` chapter.
+
+
+.. _distutils-concepts:
+
+Concepts & Terminology
+======================
+
+Using the Distutils is quite simple, both for module developers and for
+users/administrators installing third-party modules. As a developer, your
+responsibilities (apart from writing solid, well-documented and well-tested
+code, of course!) are:
+
+* write a setup script (:file:`setup.py` by convention)
+
+* (optional) write a setup configuration file
+
+* create a source distribution
+
+* (optional) create one or more built (binary) distributions
+
+Each of these tasks is covered in this document.
+
+Not all module developers have access to a multitude of platforms, so it's not
+always feasible to expect them to create a multitude of built distributions. It
+is hoped that a class of intermediaries, called *packagers*, will arise to
+address this need. Packagers will take source distributions released by module
+developers, build them on one or more platforms, and release the resulting built
+distributions. Thus, users on the most popular platforms will be able to
+install most popular Python module distributions in the most natural way for
+their platform, without having to run a single setup script or compile a line of
+code.
+
+
+.. _distutils-simple-example:
+
+A Simple Example
+================
+
+The setup script is usually quite simple, although since it's written in Python,
+there are no arbitrary limits to what you can do with it, though you should be
+careful about putting arbitrarily expensive operations in your setup script.
+Unlike, say, Autoconf-style configure scripts, the setup script may be run
+multiple times in the course of building and installing your module
+distribution.
+
+If all you want to do is distribute a module called :mod:`foo`, contained in a
+file :file:`foo.py`, then your setup script can be as simple as this::
+
+ from distutils.core import setup
+ setup(name='foo',
+ version='1.0',
+ py_modules=['foo'],
+ )
+
+Some observations:
+
+* most information that you supply to the Distutils is supplied as keyword
+ arguments to the :func:`setup` function
+
+* those keyword arguments fall into two categories: package metadata (name,
+ version number) and information about what's in the package (a list of pure
+ Python modules, in this case)
+
+* modules are specified by module name, not filename (the same will hold true
+ for packages and extensions)
+
+* it's recommended that you supply a little more metadata, in particular your
+ name, email address and a URL for the project (see section :ref:`setup-script`
+ for an example)
+
+To create a source distribution for this module, you would create a setup
+script, :file:`setup.py`, containing the above code, and run::
+
+ python setup.py sdist
+
+which will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
+containing your setup script :file:`setup.py`, and your module :file:`foo.py`.
+The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and
+will unpack into a directory :file:`foo-1.0`.
+
+If an end-user wishes to install your :mod:`foo` module, all she has to do is
+download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the
+:file:`foo-1.0` directory---run ::
+
+ python setup.py install
+
+which will ultimately copy :file:`foo.py` to the appropriate directory for
+third-party modules in their Python installation.
+
+This simple example demonstrates some fundamental concepts of the Distutils.
+First, both developers and installers have the same basic user interface, i.e.
+the setup script. The difference is which Distutils *commands* they use: the
+:command:`sdist` command is almost exclusively for module developers, while
+:command:`install` is more often for installers (although most developers will
+want to install their own code occasionally).
+
+If you want to make things really easy for your users, you can create one or
+more built distributions for them. For instance, if you are running on a
+Windows machine, and want to make things easy for other Windows users, you can
+create an executable installer (the most appropriate type of built distribution
+for this platform) with the :command:`bdist_wininst` command. For example::
+
+ python setup.py bdist_wininst
+
+will create an executable installer, :file:`foo-1.0.win32.exe`, in the current
+directory.
+
+Other useful built distribution formats are RPM, implemented by the
+:command:`bdist_rpm` command, Solaris :program:`pkgtool`
+(:command:`bdist_pkgtool`), and HP-UX :program:`swinstall`
+(:command:`bdist_sdux`). For example, the following command will create an RPM
+file called :file:`foo-1.0.noarch.rpm`::
+
+ python setup.py bdist_rpm
+
+(The :command:`bdist_rpm` command uses the :command:`rpm` executable, therefore
+this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or
+Mandrake Linux.)
+
+You can find out what distribution formats are available at any time by running
+::
+
+ python setup.py bdist --help-formats
+
+
+.. _python-terms:
+
+General Python terminology
+==========================
+
+If you're reading this document, you probably have a good idea of what modules,
+extensions, and so forth are. Nevertheless, just to be sure that everyone is
+operating from a common starting point, we offer the following glossary of
+common Python terms:
+
+module
+ the basic unit of code reusability in Python: a block of code imported by some
+ other code. Three types of modules concern us here: pure Python modules,
+ extension modules, and packages.
+
+pure Python module
+ a module written in Python and contained in a single :file:`.py` file (and
+ possibly associated :file:`.pyc` and/or :file:`.pyo` files). Sometimes referred
+ to as a "pure module."
+
+extension module
+ a module written in the low-level language of the Python implementation: C/C++
+ for Python, Java for Jython. Typically contained in a single dynamically
+ loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python
+ extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python
+ extensions on Windows, or a Java class file for Jython extensions. (Note that
+ currently, the Distutils only handles C/C++ extensions for Python.)
+
+package
+ a module that contains other modules; typically contained in a directory in the
+ filesystem and distinguished from other directories by the presence of a file
+ :file:`__init__.py`.
+
+root package
+ the root of the hierarchy of packages. (This isn't really a package, since it
+ doesn't have an :file:`__init__.py` file. But we have to call it something.)
+ The vast majority of the standard library is in the root package, as are many
+ small, standalone third-party modules that don't belong to a larger module
+ collection. Unlike regular packages, modules in the root package can be found in
+ many directories: in fact, every directory listed in ``sys.path`` contributes
+ modules to the root package.
+
+
+.. _distutils-term:
+
+Distutils-specific terminology
+==============================
+
+The following terms apply more specifically to the domain of distributing Python
+modules using the Distutils:
+
+module distribution
+ a collection of Python modules distributed together as a single downloadable
+ resource and meant to be installed *en masse*. Examples of some well-known
+ module distributions are Numeric Python, PyXML, PIL (the Python Imaging
+ Library), or mxBase. (This would be called a *package*, except that term is
+ already taken in the Python context: a single module distribution may contain
+ zero, one, or many Python packages.)
+
+pure module distribution
+ a module distribution that contains only pure Python modules and packages.
+ Sometimes referred to as a "pure distribution."
+
+non-pure module distribution
+ a module distribution that contains at least one extension module. Sometimes
+ referred to as a "non-pure distribution."
+
+distribution root
+ the top-level directory of your source tree (or source distribution); the
+ directory where :file:`setup.py` exists. Generally :file:`setup.py` will be
+ run from this directory.
+
+
--- /dev/null
+.. _package-index:
+
+**********************************
+Registering with the Package Index
+**********************************
+
+The Python Package Index (PyPI) holds meta-data describing distributions
+packaged with distutils. The distutils command :command:`register` is used to
+submit your distribution's meta-data to the index. It is invoked as follows::
+
+ python setup.py register
+
+Distutils will respond with the following prompt::
+
+ running register
+ We need to know who you are, so please choose either:
+ 1. use your existing login,
+ 2. register as a new user,
+ 3. have the server generate a new password for you (and email it to you), or
+ 4. quit
+ Your selection [default 1]:
+
+Note: if your username and password are saved locally, you will not see this
+menu.
+
+If you have not registered with PyPI, then you will need to do so now. You
+should choose option 2, and enter your details as required. Soon after
+submitting your details, you will receive an email which will be used to confirm
+your registration.
+
+Once you are registered, you may choose option 1 from the menu. You will be
+prompted for your PyPI username and password, and :command:`register` will then
+submit your meta-data to the index.
+
+You may submit any number of versions of your distribution to the index. If you
+alter the meta-data for a particular version, you may submit it again and the
+index will be updated.
+
+PyPI holds a record for each (name, version) combination submitted. The first
+user to submit information for a given name is designated the Owner of that
+name. They may submit changes through the :command:`register` command or through
+the web interface. They may also designate other users as Owners or Maintainers.
+Maintainers may edit the package information, but not designate other Owners or
+Maintainers.
+
+By default PyPI will list all versions of a given package. To hide certain
+versions, the Hidden property should be set to yes. This must be edited through
+the web interface.
+
+
+.. _pypirc:
+
+The .pypirc file
+================
+
+The format of the :file:`.pypirc` file is formated as follows::
+
+ [server-login]
+ repository: <repository-url>
+ username: <username>
+ password: <password>
+
+*repository* can be ommitted and defaults to ``http://www.python.org/pypi``.
+
+
--- /dev/null
+.. _setup-script:
+
+************************
+Writing the Setup Script
+************************
+
+The setup script is the centre of all activity in building, distributing, and
+installing modules using the Distutils. The main purpose of the setup script is
+to describe your module distribution to the Distutils, so that the various
+commands that operate on your modules do the right thing. As we saw in section
+:ref:`distutils-simple-example` above, the setup script consists mainly of a call to
+:func:`setup`, and most information supplied to the Distutils by the module
+developer is supplied as keyword arguments to :func:`setup`.
+
+Here's a slightly more involved example, which we'll follow for the next couple
+of sections: the Distutils' own setup script. (Keep in mind that although the
+Distutils are included with Python 1.6 and later, they also have an independent
+existence so that Python 1.5.2 users can use them to install other module
+distributions. The Distutils' own setup script, shown here, is used to install
+the package into Python 1.5.2.) ::
+
+ #!/usr/bin/env python
+
+ from distutils.core import setup
+
+ setup(name='Distutils',
+ version='1.0',
+ description='Python Distribution Utilities',
+ author='Greg Ward',
+ author_email='gward@python.net',
+ url='http://www.python.org/sigs/distutils-sig/',
+ packages=['distutils', 'distutils.command'],
+ )
+
+There are only two differences between this and the trivial one-file
+distribution presented in section :ref:`distutils-simple-example`: more metadata, and the
+specification of pure Python modules by package, rather than by module. This is
+important since the Distutils consist of a couple of dozen modules split into
+(so far) two packages; an explicit list of every module would be tedious to
+generate and difficult to maintain. For more information on the additional
+meta-data, see section :ref:`meta-data`.
+
+Note that any pathnames (files or directories) supplied in the setup script
+should be written using the Unix convention, i.e. slash-separated. The
+Distutils will take care of converting this platform-neutral representation into
+whatever is appropriate on your current platform before actually using the
+pathname. This makes your setup script portable across operating systems, which
+of course is one of the major goals of the Distutils. In this spirit, all
+pathnames in this document are slash-separated. (Mac OS 9 programmers should
+keep in mind that the *absence* of a leading slash indicates a relative path,
+the opposite of the Mac OS convention with colons.)
+
+This, of course, only applies to pathnames given to Distutils functions. If
+you, for example, use standard Python functions such as :func:`glob.glob` or
+:func:`os.listdir` to specify files, you should be careful to write portable
+code instead of hardcoding path separators::
+
+ glob.glob(os.path.join('mydir', 'subdir', '*.html'))
+ os.listdir(os.path.join('mydir', 'subdir'))
+
+
+.. _listing-packages:
+
+Listing whole packages
+======================
+
+The :option:`packages` option tells the Distutils to process (build, distribute,
+install, etc.) all pure Python modules found in each package mentioned in the
+:option:`packages` list. In order to do this, of course, there has to be a
+correspondence between package names and directories in the filesystem. The
+default correspondence is the most obvious one, i.e. package :mod:`distutils` is
+found in the directory :file:`distutils` relative to the distribution root.
+Thus, when you say ``packages = ['foo']`` in your setup script, you are
+promising that the Distutils will find a file :file:`foo/__init__.py` (which
+might be spelled differently on your system, but you get the idea) relative to
+the directory where your setup script lives. If you break this promise, the
+Distutils will issue a warning but still process the broken package anyways.
+
+If you use a different convention to lay out your source directory, that's no
+problem: you just have to supply the :option:`package_dir` option to tell the
+Distutils about your convention. For example, say you keep all Python source
+under :file:`lib`, so that modules in the "root package" (i.e., not in any
+package at all) are in :file:`lib`, modules in the :mod:`foo` package are in
+:file:`lib/foo`, and so forth. Then you would put ::
+
+ package_dir = {'': 'lib'}
+
+in your setup script. The keys to this dictionary are package names, and an
+empty package name stands for the root package. The values are directory names
+relative to your distribution root. In this case, when you say ``packages =
+['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists.
+
+Another possible convention is to put the :mod:`foo` package right in
+:file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc. This would be
+written in the setup script as ::
+
+ package_dir = {'foo': 'lib'}
+
+A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly
+applies to all packages below *package*, so the :mod:`foo.bar` case is
+automatically handled here. In this example, having ``packages = ['foo',
+'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and
+:file:`lib/bar/__init__.py`. (Keep in mind that although :option:`package_dir`
+applies recursively, you must explicitly list all packages in
+:option:`packages`: the Distutils will *not* recursively scan your source tree
+looking for any directory with an :file:`__init__.py` file.)
+
+
+.. _listing-modules:
+
+Listing individual modules
+==========================
+
+For a small module distribution, you might prefer to list all modules rather
+than listing packages---especially the case of a single module that goes in the
+"root package" (i.e., no package at all). This simplest case was shown in
+section :ref:`distutils-simple-example`; here is a slightly more involved example::
+
+ py_modules = ['mod1', 'pkg.mod2']
+
+This describes two modules, one of them in the "root" package, the other in the
+:mod:`pkg` package. Again, the default package/directory layout implies that
+these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and
+that :file:`pkg/__init__.py` exists as well. And again, you can override the
+package/directory correspondence using the :option:`package_dir` option.
+
+
+.. _describing-extensions:
+
+Describing extension modules
+============================
+
+Just as writing Python extension modules is a bit more complicated than writing
+pure Python modules, describing them to the Distutils is a bit more complicated.
+Unlike pure modules, it's not enough just to list modules or packages and expect
+the Distutils to go out and find the right files; you have to specify the
+extension name, source file(s), and any compile/link requirements (include
+directories, libraries to link with, etc.).
+
+.. % XXX read over this section
+
+All of this is done through another keyword argument to :func:`setup`, the
+:option:`ext_modules` option. :option:`ext_modules` is just a list of
+:class:`Extension` instances, each of which describes a single extension module.
+Suppose your distribution includes a single extension, called :mod:`foo` and
+implemented by :file:`foo.c`. If no additional instructions to the
+compiler/linker are needed, describing this extension is quite simple::
+
+ Extension('foo', ['foo.c'])
+
+The :class:`Extension` class can be imported from :mod:`distutils.core` along
+with :func:`setup`. Thus, the setup script for a module distribution that
+contains only this one extension and nothing else might be::
+
+ from distutils.core import setup, Extension
+ setup(name='foo',
+ version='1.0',
+ ext_modules=[Extension('foo', ['foo.c'])],
+ )
+
+The :class:`Extension` class (actually, the underlying extension-building
+machinery implemented by the :command:`build_ext` command) supports a great deal
+of flexibility in describing Python extensions, which is explained in the
+following sections.
+
+
+Extension names and packages
+----------------------------
+
+The first argument to the :class:`Extension` constructor is always the name of
+the extension, including any package names. For example, ::
+
+ Extension('foo', ['src/foo1.c', 'src/foo2.c'])
+
+describes an extension that lives in the root package, while ::
+
+ Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
+
+describes the same extension in the :mod:`pkg` package. The source files and
+resulting object code are identical in both cases; the only difference is where
+in the filesystem (and therefore where in Python's namespace hierarchy) the
+resulting extension lives.
+
+If you have a number of extensions all in the same package (or all under the
+same base package), use the :option:`ext_package` keyword argument to
+:func:`setup`. For example, ::
+
+ setup(...
+ ext_package='pkg',
+ ext_modules=[Extension('foo', ['foo.c']),
+ Extension('subpkg.bar', ['bar.c'])],
+ )
+
+will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
+:mod:`pkg.subpkg.bar`.
+
+
+Extension source files
+----------------------
+
+The second argument to the :class:`Extension` constructor is a list of source
+files. Since the Distutils currently only support C, C++, and Objective-C
+extensions, these are normally C/C++/Objective-C source files. (Be sure to use
+appropriate extensions to distinguish C++\ source files: :file:`.cc` and
+:file:`.cpp` seem to be recognized by both Unix and Windows compilers.)
+
+However, you can also include SWIG interface (:file:`.i`) files in the list; the
+:command:`build_ext` command knows how to deal with SWIG extensions: it will run
+SWIG on the interface file and compile the resulting C/C++ file into your
+extension.
+
+**\*\*** SWIG support is rough around the edges and largely untested! **\*\***
+
+This warning notwithstanding, options to SWIG can be currently passed like
+this::
+
+ setup(...
+ ext_modules=[Extension('_foo', ['foo.i'],
+ swig_opts=['-modern', '-I../include'])],
+ py_modules=['foo'],
+ )
+
+Or on the commandline like this::
+
+ > python setup.py build_ext --swig-opts="-modern -I../include"
+
+On some platforms, you can include non-source files that are processed by the
+compiler and included in your extension. Currently, this just means Windows
+message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for
+Visual C++. These will be compiled to binary resource (:file:`.res`) files and
+linked into the executable.
+
+
+Preprocessor options
+--------------------
+
+Three optional arguments to :class:`Extension` will help if you need to specify
+include directories to search or preprocessor macros to define/undefine:
+``include_dirs``, ``define_macros``, and ``undef_macros``.
+
+For example, if your extension requires header files in the :file:`include`
+directory under your distribution root, use the ``include_dirs`` option::
+
+ Extension('foo', ['foo.c'], include_dirs=['include'])
+
+You can specify absolute directories there; if you know that your extension will
+only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get
+away with ::
+
+ Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
+
+You should avoid this sort of non-portable usage if you plan to distribute your
+code: it's probably better to write C code like ::
+
+ #include <X11/Xlib.h>
+
+If you need to include header files from some other Python extension, you can
+take advantage of the fact that header files are installed in a consistent way
+by the Distutils :command:`install_header` command. For example, the Numerical
+Python header files are installed (on a standard Unix installation) to
+:file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ
+according to your platform and Python installation.) Since the Python include
+directory---\ :file:`/usr/local/include/python1.5` in this case---is always
+included in the search path when building Python extensions, the best approach
+is to write C code like ::
+
+ #include <Numerical/arrayobject.h>
+
+If you must put the :file:`Numerical` include directory right into your header
+search path, though, you can find that directory using the Distutils
+:mod:`distutils.sysconfig` module::
+
+ from distutils.sysconfig import get_python_inc
+ incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
+ setup(...,
+ Extension(..., include_dirs=[incdir]),
+ )
+
+Even though this is quite portable---it will work on any Python installation,
+regardless of platform---it's probably easier to just write your C code in the
+sensible way.
+
+You can define and undefine pre-processor macros with the ``define_macros`` and
+``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)``
+tuples, where ``name`` is the name of the macro to define (a string) and
+``value`` is its value: either a string or ``None``. (Defining a macro ``FOO``
+to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with
+most compilers, this sets ``FOO`` to the string ``1``.) ``undef_macros`` is
+just a list of macros to undefine.
+
+For example::
+
+ Extension(...,
+ define_macros=[('NDEBUG', '1'),
+ ('HAVE_STRFTIME', None)],
+ undef_macros=['HAVE_FOO', 'HAVE_BAR'])
+
+is the equivalent of having this at the top of every C source file::
+
+ #define NDEBUG 1
+ #define HAVE_STRFTIME
+ #undef HAVE_FOO
+ #undef HAVE_BAR
+
+
+Library options
+---------------
+
+You can also specify the libraries to link against when building your extension,
+and the directories to search for those libraries. The ``libraries`` option is
+a list of libraries to link against, ``library_dirs`` is a list of directories
+to search for libraries at link-time, and ``runtime_library_dirs`` is a list of
+directories to search for shared (dynamically loaded) libraries at run-time.
+
+For example, if you need to link against libraries known to be in the standard
+library search path on target systems ::
+
+ Extension(...,
+ libraries=['gdbm', 'readline'])
+
+If you need to link with libraries in a non-standard location, you'll have to
+include the location in ``library_dirs``::
+
+ Extension(...,
+ library_dirs=['/usr/X11R6/lib'],
+ libraries=['X11', 'Xt'])
+
+(Again, this sort of non-portable construct should be avoided if you intend to
+distribute your code.)
+
+**\*\*** Should mention clib libraries here or somewhere else! **\*\***
+
+
+Other options
+-------------
+
+There are still some other options which can be used to handle special cases.
+
+The :option:`extra_objects` option is a list of object files to be passed to the
+linker. These files must not have extensions, as the default extension for the
+compiler is used.
+
+:option:`extra_compile_args` and :option:`extra_link_args` can be used to
+specify additional command line options for the respective compiler and linker
+command lines.
+
+:option:`export_symbols` is only useful on Windows. It can contain a list of
+symbols (functions or variables) to be exported. This option is not needed when
+building compiled extensions: Distutils will automatically add ``initmodule``
+to the list of exported symbols.
+
+
+Relationships between Distributions and Packages
+================================================
+
+A distribution may relate to packages in three specific ways:
+
+#. It can require packages or modules.
+
+#. It can provide packages or modules.
+
+#. It can obsolete packages or modules.
+
+These relationships can be specified using keyword arguments to the
+:func:`distutils.core.setup` function.
+
+Dependencies on other Python modules and packages can be specified by supplying
+the *requires* keyword argument to :func:`setup`. The value must be a list of
+strings. Each string specifies a package that is required, and optionally what
+versions are sufficient.
+
+To specify that any version of a module or package is required, the string
+should consist entirely of the module or package name. Examples include
+``'mymodule'`` and ``'xml.parsers.expat'``.
+
+If specific versions are required, a sequence of qualifiers can be supplied in
+parentheses. Each qualifier may consist of a comparison operator and a version
+number. The accepted comparison operators are::
+
+ < > ==
+ <= >= !=
+
+These can be combined by using multiple qualifiers separated by commas (and
+optional whitespace). In this case, all of the qualifiers must be matched; a
+logical AND is used to combine the evaluations.
+
+Let's look at a bunch of examples:
+
++-------------------------+----------------------------------------------+
+| Requires Expression | Explanation |
++=========================+==============================================+
+| ``==1.0`` | Only version ``1.0`` is compatible |
++-------------------------+----------------------------------------------+
+| ``>1.0, !=1.5.1, <2.0`` | Any version after ``1.0`` and before ``2.0`` |
+| | is compatible, except ``1.5.1`` |
++-------------------------+----------------------------------------------+
+
+Now that we can specify dependencies, we also need to be able to specify what we
+provide that other distributions can require. This is done using the *provides*
+keyword argument to :func:`setup`. The value for this keyword is a list of
+strings, each of which names a Python module or package, and optionally
+identifies the version. If the version is not specified, it is assumed to match
+that of the distribution.
+
+Some examples:
+
++---------------------+----------------------------------------------+
+| Provides Expression | Explanation |
++=====================+==============================================+
+| ``mypkg`` | Provide ``mypkg``, using the distribution |
+| | version |
++---------------------+----------------------------------------------+
+| ``mypkg (1.1)`` | Provide ``mypkg`` version 1.1, regardless of |
+| | the distribution version |
++---------------------+----------------------------------------------+
+
+A package can declare that it obsoletes other packages using the *obsoletes*
+keyword argument. The value for this is similar to that of the *requires*
+keyword: a list of strings giving module or package specifiers. Each specifier
+consists of a module or package name optionally followed by one or more version
+qualifiers. Version qualifiers are given in parentheses after the module or
+package name.
+
+The versions identified by the qualifiers are those that are obsoleted by the
+distribution being described. If no qualifiers are given, all versions of the
+named module or package are understood to be obsoleted.
+
+
+Installing Scripts
+==================
+
+So far we have been dealing with pure and non-pure Python modules, which are
+usually not run by themselves but imported by scripts.
+
+Scripts are files containing Python source code, intended to be started from the
+command line. Scripts don't require Distutils to do anything very complicated.
+The only clever feature is that if the first line of the script starts with
+``#!`` and contains the word "python", the Distutils will adjust the first line
+to refer to the current interpreter location. By default, it is replaced with
+the current interpreter location. The :option:`--executable` (or :option:`-e`)
+option will allow the interpreter path to be explicitly overridden.
+
+The :option:`scripts` option simply is a list of files to be handled in this
+way. From the PyXML setup script::
+
+ setup(...
+ scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
+ )
+
+
+Installing Package Data
+=======================
+
+Often, additional files need to be installed into a package. These files are
+often data that's closely related to the package's implementation, or text files
+containing documentation that might be of interest to programmers using the
+package. These files are called :dfn:`package data`.
+
+Package data can be added to packages using the ``package_data`` keyword
+argument to the :func:`setup` function. The value must be a mapping from
+package name to a list of relative path names that should be copied into the
+package. The paths are interpreted as relative to the directory containing the
+package (information from the ``package_dir`` mapping is used if appropriate);
+that is, the files are expected to be part of the package in the source
+directories. They may contain glob patterns as well.
+
+The path names may contain directory portions; any necessary directories will be
+created in the installation.
+
+For example, if a package should contain a subdirectory with several data files,
+the files can be arranged like this in the source tree::
+
+ setup.py
+ src/
+ mypkg/
+ __init__.py
+ module.py
+ data/
+ tables.dat
+ spoons.dat
+ forks.dat
+
+The corresponding call to :func:`setup` might be::
+
+ setup(...,
+ packages=['mypkg'],
+ package_dir={'mypkg': 'src/mypkg'},
+ package_data={'mypkg': ['data/*.dat']},
+ )
+
+.. versionadded:: 2.4
+
+
+Installing Additional Files
+===========================
+
+The :option:`data_files` option can be used to specify additional files needed
+by the module distribution: configuration files, message catalogs, data files,
+anything which doesn't fit in the previous categories.
+
+:option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the
+following way::
+
+ setup(...
+ data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
+ ('config', ['cfg/data.cfg']),
+ ('/etc/init.d', ['init-script'])]
+ )
+
+Note that you can specify the directory names where the data files will be
+installed, but you cannot rename the data files themselves.
+
+Each (*directory*, *files*) pair in the sequence specifies the installation
+directory and the files to install there. If *directory* is a relative path, it
+is interpreted relative to the installation prefix (Python's ``sys.prefix`` for
+pure-Python packages, ``sys.exec_prefix`` for packages that contain extension
+modules). Each file name in *files* is interpreted relative to the
+:file:`setup.py` script at the top of the package source distribution. No
+directory information from *files* is used to determine the final location of
+the installed file; only the name of the file is used.
+
+You can specify the :option:`data_files` options as a simple sequence of files
+without specifying a target directory, but this is not recommended, and the
+:command:`install` command will print a warning in this case. To install data
+files directly in the target directory, an empty string should be given as the
+directory.
+
+
+.. _meta-data:
+
+Additional meta-data
+====================
+
+The setup script may include additional meta-data beyond the name and version.
+This information includes:
+
++----------------------+---------------------------+-----------------+--------+
+| Meta-Data | Description | Value | Notes |
++======================+===========================+=================+========+
+| ``name`` | name of the package | short string | \(1) |
++----------------------+---------------------------+-----------------+--------+
+| ``version`` | version of this release | short string | (1)(2) |
++----------------------+---------------------------+-----------------+--------+
+| ``author`` | package author's name | short string | \(3) |
++----------------------+---------------------------+-----------------+--------+
+| ``author_email`` | email address of the | email address | \(3) |
+| | package author | | |
++----------------------+---------------------------+-----------------+--------+
+| ``maintainer`` | package maintainer's name | short string | \(3) |
++----------------------+---------------------------+-----------------+--------+
+| ``maintainer_email`` | email address of the | email address | \(3) |
+| | package maintainer | | |
++----------------------+---------------------------+-----------------+--------+
+| ``url`` | home page for the package | URL | \(1) |
++----------------------+---------------------------+-----------------+--------+
+| ``description`` | short, summary | short string | |
+| | description of the | | |
+| | package | | |
++----------------------+---------------------------+-----------------+--------+
+| ``long_description`` | longer description of the | long string | |
+| | package | | |
++----------------------+---------------------------+-----------------+--------+
+| ``download_url`` | location where the | URL | \(4) |
+| | package may be downloaded | | |
++----------------------+---------------------------+-----------------+--------+
+| ``classifiers`` | a list of classifiers | list of strings | \(4) |
++----------------------+---------------------------+-----------------+--------+
+
+Notes:
+
+(1)
+ These fields are required.
+
+(2)
+ It is recommended that versions take the form *major.minor[.patch[.sub]]*.
+
+(3)
+ Either the author or the maintainer must be identified.
+
+(4)
+ These fields should not be used if your package is to be compatible with Python
+ versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website
+ <http://www.python.org/pypi>`_.
+
+'short string'
+ A single line of text, not more than 200 characters.
+
+'long string'
+ Multiple lines of plain text in reStructuredText format (see
+ http://docutils.sf.net/).
+
+'list of strings'
+ See below.
+
+None of the string values may be Unicode.
+
+Encoding the version information is an art in itself. Python packages generally
+adhere to the version format *major.minor[.patch][sub]*. The major number is 0
+for initial, experimental releases of software. It is incremented for releases
+that represent major milestones in a package. The minor number is incremented
+when important new features are added to the package. The patch number
+increments when bug-fix releases are made. Additional trailing version
+information is sometimes used to indicate sub-releases. These are
+"a1,a2,...,aN" (for alpha releases, where functionality and API may change),
+"b1,b2,...,bN" (for beta releases, which only fix bugs) and "pr1,pr2,...,prN"
+(for final pre-release release testing). Some examples:
+
+0.1.0
+ the first, experimental release of a package
+
+1.0.1a2
+ the second alpha release of the first patch version of 1.0
+
+:option:`classifiers` are specified in a python list::
+
+ setup(...
+ classifiers=[
+ 'Development Status :: 4 - Beta',
+ 'Environment :: Console',
+ 'Environment :: Web Environment',
+ 'Intended Audience :: End Users/Desktop',
+ 'Intended Audience :: Developers',
+ 'Intended Audience :: System Administrators',
+ 'License :: OSI Approved :: Python Software Foundation License',
+ 'Operating System :: MacOS :: MacOS X',
+ 'Operating System :: Microsoft :: Windows',
+ 'Operating System :: POSIX',
+ 'Programming Language :: Python',
+ 'Topic :: Communications :: Email',
+ 'Topic :: Office/Business',
+ 'Topic :: Software Development :: Bug Tracking',
+ ],
+ )
+
+If you wish to include classifiers in your :file:`setup.py` file and also wish
+to remain backwards-compatible with Python releases prior to 2.2.3, then you can
+include the following code fragment in your :file:`setup.py` before the
+:func:`setup` call. ::
+
+ # patch distutils if it can't cope with the "classifiers" or
+ # "download_url" keywords
+ from sys import version
+ if version < '2.2.3':
+ from distutils.dist import DistributionMetadata
+ DistributionMetadata.classifiers = None
+ DistributionMetadata.download_url = None
+
+
+Debugging the setup script
+==========================
+
+Sometimes things go wrong, and the setup script doesn't do what the developer
+wants.
+
+Distutils catches any exceptions when running the setup script, and print a
+simple error message before the script is terminated. The motivation for this
+behaviour is to not confuse administrators who don't know much about Python and
+are trying to install a package. If they get a big long traceback from deep
+inside the guts of Distutils, they may think the package or the Python
+installation is broken because they don't read all the way down to the bottom
+and see that it's a permission problem.
+
+On the other hand, this doesn't help the developer to find the cause of the
+failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set
+to anything except an empty string, and distutils will now print detailed
+information what it is doing, and prints the full traceback in case an exception
+occurs.
+
+
--- /dev/null
+.. _source-dist:
+
+******************************
+Creating a Source Distribution
+******************************
+
+As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command
+to create a source distribution. In the simplest case, ::
+
+ python setup.py sdist
+
+(assuming you haven't specified any :command:`sdist` options in the setup script
+or config file), :command:`sdist` creates the archive of the default format for
+the current platform. The default format is a gzip'ed tar file
+(:file:`.tar.gz`) on Unix, and ZIP file on Windows.
+
+You can specify as many formats as you like using the :option:`--formats`
+option, for example::
+
+ python setup.py sdist --formats=gztar,zip
+
+to create a gzipped tarball and a zip file. The available formats are:
+
++-----------+-------------------------+---------+
+| Format | Description | Notes |
++===========+=========================+=========+
+| ``zip`` | zip file (:file:`.zip`) | (1),(3) |
++-----------+-------------------------+---------+
+| ``gztar`` | gzip'ed tar file | (2),(4) |
+| | (:file:`.tar.gz`) | |
++-----------+-------------------------+---------+
+| ``bztar`` | bzip2'ed tar file | \(4) |
+| | (:file:`.tar.bz2`) | |
++-----------+-------------------------+---------+
+| ``ztar`` | compressed tar file | \(4) |
+| | (:file:`.tar.Z`) | |
++-----------+-------------------------+---------+
+| ``tar`` | tar file (:file:`.tar`) | \(4) |
++-----------+-------------------------+---------+
+
+Notes:
+
+(1)
+ default on Windows
+
+(2)
+ default on Unix
+
+(3)
+ requires either external :program:`zip` utility or :mod:`zipfile` module (part
+ of the standard Python library since Python 1.6)
+
+(4)
+ requires external utilities: :program:`tar` and possibly one of :program:`gzip`,
+ :program:`bzip2`, or :program:`compress`
+
+
+.. _manifest:
+
+Specifying the files to distribute
+==================================
+
+If you don't supply an explicit list of files (or instructions on how to
+generate one), the :command:`sdist` command puts a minimal default set into the
+source distribution:
+
+* all Python source files implied by the :option:`py_modules` and
+ :option:`packages` options
+
+* all C source files mentioned in the :option:`ext_modules` or
+ :option:`libraries` options (
+
+ **\*\*** getting C library sources currently broken---no
+ :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***)
+
+* scripts identified by the :option:`scripts` option
+
+* anything that looks like a test script: :file:`test/test\*.py` (currently, the
+ Distutils don't do anything with test scripts except include them in source
+ distributions, but in the future there will be a standard for testing Python
+ module distributions)
+
+* :file:`README.txt` (or :file:`README`), :file:`setup.py` (or whatever you
+ called your setup script), and :file:`setup.cfg`
+
+Sometimes this is enough, but usually you will want to specify additional files
+to distribute. The typical way to do this is to write a *manifest template*,
+called :file:`MANIFEST.in` by default. The manifest template is just a list of
+instructions for how to generate your manifest file, :file:`MANIFEST`, which is
+the exact list of files to include in your source distribution. The
+:command:`sdist` command processes this template and generates a manifest based
+on its instructions and what it finds in the filesystem.
+
+If you prefer to roll your own manifest file, the format is simple: one filename
+per line, regular files (or symlinks to them) only. If you do supply your own
+:file:`MANIFEST`, you must specify everything: the default set of files
+described above does not apply in this case.
+
+The manifest template has one command per line, where each command specifies a
+set of files to include or exclude from the source distribution. For an
+example, again we turn to the Distutils' own manifest template::
+
+ include *.txt
+ recursive-include examples *.txt *.py
+ prune examples/sample?/build
+
+The meanings should be fairly clear: include all files in the distribution root
+matching :file:`\*.txt`, all files anywhere under the :file:`examples` directory
+matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching
+:file:`examples/sample?/build`. All of this is done *after* the standard
+include set, so you can exclude files from the standard set with explicit
+instructions in the manifest template. (Or, you can use the
+:option:`--no-defaults` option to disable the standard set entirely.) There are
+several other commands available in the manifest template mini-language; see
+section :ref:`sdist-cmd`.
+
+The order of commands in the manifest template matters: initially, we have the
+list of default files as described above, and each command in the template adds
+to or removes from that list of files. Once we have fully processed the
+manifest template, we remove files that should not be included in the source
+distribution:
+
+* all files in the Distutils "build" tree (default :file:`build/`)
+
+* all files in directories named :file:`RCS`, :file:`CVS` or :file:`.svn`
+
+Now we have our complete list of files, which is written to the manifest for
+future reference, and then used to build the source distribution archive(s).
+
+You can disable the default set of included files with the
+:option:`--no-defaults` option, and you can disable the standard exclude set
+with :option:`--no-prune`.
+
+Following the Distutils' own manifest template, let's trace how the
+:command:`sdist` command builds the list of files to include in the Distutils
+source distribution:
+
+#. include all Python source files in the :file:`distutils` and
+ :file:`distutils/command` subdirectories (because packages corresponding to
+ those two directories were mentioned in the :option:`packages` option in the
+ setup script---see section :ref:`setup-script`)
+
+#. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard
+ files)
+
+#. include :file:`test/test\*.py` (standard files)
+
+#. include :file:`\*.txt` in the distribution root (this will find
+ :file:`README.txt` a second time, but such redundancies are weeded out later)
+
+#. include anything matching :file:`\*.txt` or :file:`\*.py` in the sub-tree
+ under :file:`examples`,
+
+#. exclude all files in the sub-trees starting at directories matching
+ :file:`examples/sample?/build`\ ---this may exclude files included by the
+ previous two steps, so it's important that the ``prune`` command in the manifest
+ template comes after the ``recursive-include`` command
+
+#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS` and
+ :file:`.svn` directories
+
+Just like in the setup script, file and directory names in the manifest template
+should always be slash-separated; the Distutils will take care of converting
+them to the standard representation on your platform. That way, the manifest
+template is portable across operating systems.
+
+
+.. _manifest-options:
+
+Manifest-related options
+========================
+
+The normal course of operations for the :command:`sdist` command is as follows:
+
+* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in`
+ and create the manifest
+
+* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
+ with just the default file set
+
+* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more
+ recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading
+ :file:`MANIFEST.in`
+
+* use the list of files now in :file:`MANIFEST` (either just generated or read
+ in) to create the source distribution archive(s)
+
+There are a couple of options that modify this behaviour. First, use the
+:option:`--no-defaults` and :option:`--no-prune` to disable the standard
+"include" and "exclude" sets.
+
+Second, you might want to force the manifest to be regenerated---for example, if
+you have added or removed files or directories that match an existing pattern in
+the manifest template, you should regenerate the manifest::
+
+ python setup.py sdist --force-manifest
+
+Or, you might just want to (re)generate the manifest, but not create a source
+distribution::
+
+ python setup.py sdist --manifest-only
+
+:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a
+shortcut for :option:`--manifest-only`, and :option:`-f` for
+:option:`--force-manifest`.
+
+
--- /dev/null
+.. _package-upload:
+
+***************************************
+Uploading Packages to the Package Index
+***************************************
+
+.. versionadded:: 2.5
+
+The Python Package Index (PyPI) not only stores the package info, but also the
+package data if the author of the package wishes to. The distutils command
+:command:`upload` pushes the distribution files to PyPI.
+
+The command is invoked immediately after building one or more distribution
+files. For example, the command ::
+
+ python setup.py sdist bdist_wininst upload
+
+will cause the source distribution and the Windows installer to be uploaded to
+PyPI. Note that these will be uploaded even if they are built using an earlier
+invocation of :file:`setup.py`, but that only distributions named on the command
+line for the invocation including the :command:`upload` command are uploaded.
+
+The :command:`upload` command uses the username, password, and repository URL
+from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this
+file).
+
+You can use the :option:`--sign` option to tell :command:`upload` to sign each
+uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must
+be available for execution on the system :envvar:`PATH`. You can also specify
+which key to use for signing using the :option:`--identity=*name*` option.
+
+Other :command:`upload` options include :option:`--repository=*url*` (which
+lets you override the repository setting from :file:`$HOME/.pypirc`), and
+:option:`--show-response` (which displays the full response text from the PyPI
+server for help in debugging upload problems).
+
+
--- /dev/null
+.. highlightlang:: rest
+
+Differences to the LaTeX markup
+===============================
+
+Though the markup language is different, most of the concepts and markup types
+of the old LaTeX docs have been kept -- environments as reST directives, inline
+commands as reST roles and so forth.
+
+However, there are some differences in the way these work, partly due to the
+differences in the markup languages, partly due to improvements in Sphinx. This
+section lists these differences, in order to give those familiar with the old
+format a quick overview of what they might run into.
+
+Inline markup
+-------------
+
+These changes have been made to inline markup:
+
+* **Cross-reference roles**
+
+ Most of the following semantic roles existed previously as inline commands,
+ but didn't do anything except formatting the content as code. Now, they
+ cross-reference to known targets (some names have also been shortened):
+
+ | *mod* (previously *refmodule* or *module*)
+ | *func* (previously *function*)
+ | *data* (new)
+ | *const*
+ | *class*
+ | *meth* (previously *method*)
+ | *attr* (previously *member*)
+ | *exc* (previously *exception*)
+ | *cdata*
+ | *cfunc* (previously *cfunction*)
+ | *cmacro* (previously *csimplemacro*)
+ | *ctype*
+
+ Also different is the handling of *func* and *meth*: while previously
+ parentheses were added to the callable name (like ``\func{str()}``), they are
+ now appended by the build system -- appending them in the source will result
+ in double parentheses. This also means that ``:func:`str(object)``` will not
+ work as expected -- use ````str(object)```` instead!
+
+* **Inline commands implemented as directives**
+
+ These were inline commands in LaTeX, but are now directives in reST:
+
+ | *deprecated*
+ | *versionadded*
+ | *versionchanged*
+
+ These are used like so::
+
+ .. deprecated:: 2.5
+ Reason of deprecation.
+
+ Also, no period is appended to the text for *versionadded* and
+ *versionchanged*.
+
+ | *note*
+ | *warning*
+
+ These are used like so::
+
+ .. note::
+
+ Content of note.
+
+* **Otherwise changed commands**
+
+ The *samp* command previously formatted code and added quotation marks around
+ it. The *samp* role, however, features a new highlighting system just like
+ *file* does:
+
+ ``:samp:`open({filename}, {mode})``` results in :samp:`open({filename}, {mode})`
+
+* **Dropped commands**
+
+ These were commands in LaTeX, but are not available as roles:
+
+ | *bfcode*
+ | *character* (use :samp:`\`\`'c'\`\``)
+ | *citetitle* (use ```Title <URL>`_``)
+ | *code* (use ````code````)
+ | *email* (just write the address in body text)
+ | *filenq*
+ | *filevar* (use the ``{...}`` highlighting feature of *file*)
+ | *programopt*, *longprogramopt* (use *option*)
+ | *ulink* (use ```Title <URL>`_``)
+ | *url* (just write the URL in body text)
+ | *var* (use ``*var*``)
+ | *infinity*, *plusminus* (use the Unicode character)
+ | *shortversion*, *version* (use the ``|version|`` and ``|release|`` substitutions)
+ | *emph*, *strong* (use the reST markup)
+
+* **Backslash escaping**
+
+ In reST, a backslash must be escaped in normal text, and in the content of
+ roles. However, in code literals and literal blocks, it must not be escaped.
+ Example: ``:file:`C:\\Temp\\my.tmp``` vs. ````open("C:\Temp\my.tmp")````.
+
+
+Information units
+-----------------
+
+Information units (*...desc* environments) have been made reST directives.
+These changes to information units should be noted:
+
+* **New names**
+
+ "desc" has been removed from every name. Additionally, these directives have
+ new names:
+
+ | *cfunction* (previously *cfuncdesc*)
+ | *cmacro* (previously *csimplemacrodesc*)
+ | *exception* (previously *excdesc*)
+ | *function* (previously *funcdesc*)
+ | *attribute* (previously *memberdesc*)
+
+ The *classdesc\** and *excclassdesc* environments have been dropped, the
+ *class* and *exception* directives support classes documented with and without
+ constructor arguments.
+
+* **Multiple objects**
+
+ The equivalent of the *...line* commands is::
+
+ .. function:: do_foo(bar)
+ do_bar(baz)
+
+ Description of the functions.
+
+ IOW, just give one signatures per line, at the same indentation level.
+
+* **Arguments**
+
+ There is no *optional* command. Just give function signatures like they
+ should appear in the output::
+
+ .. function:: open(filename[, mode[, buffering]])
+
+ Description.
+
+ Note: markup in the signature is not supported.
+
+* **Indexing**
+
+ The *...descni* environments have been dropped. To mark an information unit
+ as unsuitable for index entry generation, use the *noindex* option like so::
+
+ .. function:: foo_*
+ :noindex:
+
+ Description.
+
+* **New information unit**
+
+ There is a new generic information unit called "describe" which can be used
+ to document things that are not covered by the other units::
+
+ .. describe:: a == b
+
+ The equals operator.
+
+
+Structure
+---------
+
+The LaTeX docs were split in several toplevel manuals. Now, all files
+are part of the same documentation tree, as indicated by the *toctree*
+directives in the sources. Every *toctree* directive embeds other files
+as subdocuments of the current file (this structure is not necessarily
+mirrored in the filesystem layout). The toplevel file is
+:file:`contents.rst`.
+
+However, most of the old directory structure has been kept, with the
+directories renamed as follows:
+
+* :file:`api` -> :file:`c-api`
+* :file:`dist` -> :file:`distutils`, with the single TeX file split up
+* :file:`doc` -> :file:`documenting`
+* :file:`ext` -> :file:`extending`
+* :file:`inst` -> :file:`installing`
+* :file:`lib` -> :file:`library`
+* :file:`mac` -> merged into :file:`library`, with `mac/using.tex`
+ moved to `howto/pythonmac.rst`
+* :file:`ref` -> :file:`reference`
+* :file:`tut` -> :file:`tutorial`, with the single TeX file split up
+
+
+.. XXX more (index-generating, production lists, ...)
--- /dev/null
+.. _documenting-index:
+
+######################
+ Documenting Python
+######################
+
+
+The Python language has a substantial body of documentation, much of it
+contributed by various authors. The markup used for the Python documentation is
+`reStructuredText`_, developed by the `docutils`_ project, amended by custom
+directives and using a toolset named *Sphinx* to postprocess the HTML output.
+
+This document describes the style guide for our documentation, the custom
+reStructuredText markup introduced to support Python documentation and how it
+should be used, as well as the Sphinx build system.
+
+.. _reStructuredText: http://docutils.sf.net/rst.html
+.. _docutils: http://docutils.sf.net/
+
+If you're interested in contributing to Python's documentation, there's no need
+to write reStructuredText if you're not so inclined; plain text contributions
+are more than welcome as well.
+
+.. toctree::
+
+ intro.rst
+ style.rst
+ rest.rst
+ markup.rst
+ fromlatex.rst
+ sphinx.rst
+
+.. XXX add credits, thanks etc.
+
--- /dev/null
+Introduction
+============
+
+Python's documentation has long been considered to be good for a free
+programming language. There are a number of reasons for this, the most
+important being the early commitment of Python's creator, Guido van Rossum, to
+providing documentation on the language and its libraries, and the continuing
+involvement of the user community in providing assistance for creating and
+maintaining documentation.
+
+The involvement of the community takes many forms, from authoring to bug reports
+to just plain complaining when the documentation could be more complete or
+easier to use.
+
+This document is aimed at authors and potential authors of documentation for
+Python. More specifically, it is for people contributing to the standard
+documentation and developing additional documents using the same tools as the
+standard documents. This guide will be less useful for authors using the Python
+documentation tools for topics other than Python, and less useful still for
+authors not using the tools at all.
+
+If your interest is in contributing to the Python documentation, but you don't
+have the time or inclination to learn reStructuredText and the markup structures
+documented here, there's a welcoming place for you among the Python contributors
+as well. Any time you feel that you can clarify existing documentation or
+provide documentation that's missing, the existing documentation team will
+gladly work with you to integrate your text, dealing with the markup for you.
+Please don't let the material in this document stand between the documentation
+and your desire to help out!
\ No newline at end of file
--- /dev/null
+.. highlightlang:: rest
+
+Additional Markup Constructs
+============================
+
+Sphinx adds a lot of new directives and interpreted text roles to standard reST
+markup. This section contains the reference material for these facilities.
+Documentation for "standard" reST constructs is not included here, though
+they are used in the Python documentation.
+
+File-wide metadata
+------------------
+
+reST has the concept of "field lists"; these are a sequence of fields marked up
+like this::
+
+ :Field name: Field content
+
+A field list at the very top of a file is parsed as the "docinfo", which in
+normal documents can be used to record the author, date of publication and
+other metadata. In Sphinx, the docinfo is used as metadata, too, but not
+displayed in the output.
+
+At the moment, only one metadata field is recognized:
+
+``nocomments``
+ If set, the web application won't display a comment form for a page generated
+ from this source file.
+
+
+Meta-information markup
+-----------------------
+
+.. describe:: sectionauthor
+
+ Identifies the author of the current section. The argument should include
+ the author's name such that it can be used for presentation (though it isn't)
+ and email address. The domain name portion of the address should be lower
+ case. Example::
+
+ .. sectionauthor:: Guido van Rossum <guido@python.org>
+
+ Currently, this markup isn't reflected in the output in any way, but it helps
+ keep track of contributions.
+
+
+Module-specific markup
+----------------------
+
+The markup described in this section is used to provide information about a
+module being documented. Each module should be documented in its own file.
+Normally this markup appears after the title heading of that file; a typical
+file might start like this::
+
+ :mod:`parrot` -- Dead parrot access
+ ===================================
+
+ .. module:: parrot
+ :platform: Unix, Windows
+ :synopsis: Analyze and reanimate dead parrots.
+ .. moduleauthor:: Eric Cleese <eric@python.invalid>
+ .. moduleauthor:: John Idle <john@python.invalid>
+
+As you can see, the module-specific markup consists of two directives, the
+``module`` directive and the ``moduleauthor`` directive.
+
+.. describe:: module
+
+ This directive marks the beginning of the description of a module (or package
+ submodule, in which case the name should be fully qualified, including the
+ package name).
+
+ The ``platform`` option, if present, is a comma-separated list of the
+ platforms on which the module is available (if it is available on all
+ platforms, the option should be omitted). The keys are short identifiers;
+ examples that are in use include "IRIX", "Mac", "Windows", and "Unix". It is
+ important to use a key which has already been used when applicable.
+
+ The ``synopsis`` option should consist of one sentence describing the
+ module's purpose -- it is currently only used in the Global Module Index.
+
+.. describe:: moduleauthor
+
+ The ``moduleauthor`` directive, which can appear multiple times, names the
+ authors of the module code, just like ``sectionauthor`` names the author(s)
+ of a piece of documentation. It too does not result in any output currently.
+
+
+.. note::
+
+ It is important to make the section title of a module-describing file
+ meaningful since that value will be inserted in the table-of-contents trees
+ in overview files.
+
+
+Information units
+-----------------
+
+There are a number of directives used to describe specific features provided by
+modules. Each directive requires one or more signatures to provide basic
+information about what is being described, and the content should be the
+description. The basic version makes entries in the general index; if no index
+entry is desired, you can give the directive option flag ``:noindex:``. The
+following example shows all of the features of this directive type::
+
+ .. function:: spam(eggs)
+ ham(eggs)
+ :noindex:
+
+ Spam or ham the foo.
+
+The signatures of object methods or data attributes should always include the
+type name (``.. method:: FileInput.input(...)``), even if it is obvious from the
+context which type they belong to; this is to enable consistent
+cross-references. If you describe methods belonging to an abstract protocol,
+such as "context managers", include a (pseudo-)type name too to make the
+index entries more informative.
+
+The directives are:
+
+.. describe:: cfunction
+
+ Describes a C function. The signature should be given as in C, e.g.::
+
+ .. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+ This is also used to describe function-like preprocessor macros. The names
+ of the arguments should be given so they may be used in the description.
+
+ Note that you don't have to backslash-escape asterisks in the signature,
+ as it is not parsed by the reST inliner.
+
+.. describe:: cmember
+
+ Describes a C struct member. Example signature::
+
+ .. cmember:: PyObject* PyTypeObject.tp_bases
+
+ The text of the description should include the range of values allowed, how
+ the value should be interpreted, and whether the value can be changed.
+ References to structure members in text should use the ``member`` role.
+
+.. describe:: cmacro
+
+ Describes a "simple" C macro. Simple macros are macros which are used
+ for code expansion, but which do not take arguments so cannot be described as
+ functions. This is not to be used for simple constant definitions. Examples
+ of its use in the Python documentation include :cmacro:`PyObject_HEAD` and
+ :cmacro:`Py_BEGIN_ALLOW_THREADS`.
+
+.. describe:: ctype
+
+ Describes a C type. The signature should just be the type name.
+
+.. describe:: cvar
+
+ Describes a global C variable. The signature should include the type, such
+ as::
+
+ .. cvar:: PyObject* PyClass_Type
+
+.. describe:: data
+
+ Describes global data in a module, including both variables and values used
+ as "defined constants." Class and object attributes are not documented
+ using this environment.
+
+.. describe:: exception
+
+ Describes an exception class. The signature can, but need not include
+ parentheses with constructor arguments.
+
+.. describe:: function
+
+ Describes a module-level function. The signature should include the
+ parameters, enclosing optional parameters in brackets. Default values can be
+ given if it enhances clarity. For example::
+
+ .. function:: Timer.repeat([repeat=3[, number=1000000]])
+
+ Object methods are not documented using this directive. Bound object methods
+ placed in the module namespace as part of the public interface of the module
+ are documented using this, as they are equivalent to normal functions for
+ most purposes.
+
+ The description should include information about the parameters required and
+ how they are used (especially whether mutable objects passed as parameters
+ are modified), side effects, and possible exceptions. A small example may be
+ provided.
+
+.. describe:: class
+
+ Describes a class. The signature can include parentheses with parameters
+ which will be shown as the constructor arguments.
+
+.. describe:: attribute
+
+ Describes an object data attribute. The description should include
+ information about the type of the data to be expected and whether it may be
+ changed directly.
+
+.. describe:: method
+
+ Describes an object method. The parameters should not include the ``self``
+ parameter. The description should include similar information to that
+ described for ``function``.
+
+.. describe:: opcode
+
+ Describes a Python bytecode instruction.
+
+
+There is also a generic version of these directives:
+
+.. describe:: describe
+
+ This directive produces the same formatting as the specific ones explained
+ above but does not create index entries or cross-referencing targets. It is
+ used, for example, to describe the directives in this document. Example::
+
+ .. describe:: opcode
+
+ Describes a Python bytecode instruction.
+
+
+Showing code examples
+---------------------
+
+Examples of Python source code or interactive sessions are represented using
+standard reST literal blocks. They are started by a ``::`` at the end of the
+preceding paragraph and delimited by indentation.
+
+Representing an interactive session requires including the prompts and output
+along with the Python code. No special markup is required for interactive
+sessions. After the last line of input or output presented, there should not be
+an "unused" primary prompt; this is an example of what *not* to do::
+
+ >>> 1 + 1
+ 2
+ >>>
+
+Syntax highlighting is handled in a smart way:
+
+* There is a "highlighting language" for each source file. Per default,
+ this is ``'python'`` as the majority of files will have to highlight Python
+ snippets.
+
+* Within Python highlighting mode, interactive sessions are recognized
+ automatically and highlighted appropriately.
+
+* The highlighting language can be changed using the ``highlightlang``
+ directive, used as follows::
+
+ .. highlightlang:: c
+
+ This language is used until the next ``highlightlang`` directive is
+ encountered.
+
+* The valid values for the highlighting language are:
+
+ * ``python`` (the default)
+ * ``c``
+ * ``rest``
+ * ``none`` (no highlighting)
+
+* If highlighting with the current language fails, the block is not highlighted
+ in any way.
+
+Longer displays of verbatim text may be included by storing the example text in
+an external file containing only plain text. The file may be included using the
+``literalinclude`` directive. [1]_ For example, to include the Python source file
+:file:`example.py`, use::
+
+ .. literalinclude:: example.py
+
+The file name is relative to the current file's path. Documentation-specific
+include files should be placed in the ``Doc/includes`` subdirectory.
+
+
+Inline markup
+-------------
+
+As said before, Sphinx uses interpreted text roles to insert semantic markup in
+documents.
+
+Variable names are an exception, they should be marked simply with ``*var*``.
+
+For all other roles, you have to write ``:rolename:`content```.
+
+The following roles refer to objects in modules and are possibly hyperlinked if
+a matching identifier is found:
+
+.. describe:: mod
+
+ The name of a module; a dotted name may be used. This should also be used for
+ package names.
+
+.. describe:: func
+
+ The name of a Python function; dotted names may be used. The role text
+ should include trailing parentheses to enhance readability. The parentheses
+ are stripped when searching for identifiers.
+
+.. describe:: data
+
+ The name of a module-level variable.
+
+.. describe:: const
+
+ The name of a "defined" constant. This may be a C-language ``#define``
+ or a Python variable that is not intended to be changed.
+
+.. describe:: class
+
+ A class name; a dotted name may be used.
+
+.. describe:: meth
+
+ The name of a method of an object. The role text should include the type
+ name, method name and the trailing parentheses. A dotted name may be used.
+
+.. describe:: attr
+
+ The name of a data attribute of an object.
+
+.. describe:: exc
+
+ The name of an exception. A dotted name may be used.
+
+The name enclosed in this markup can include a module name and/or a class name.
+For example, ``:func:`filter``` could refer to a function named ``filter`` in
+the current module, or the built-in function of that name. In contrast,
+``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo``
+module.
+
+A similar heuristic is used to determine whether the name is an attribute of
+the currently documented class.
+
+The following roles create cross-references to C-language constructs if they
+are defined in the API documentation:
+
+.. describe:: cdata
+
+ The name of a C-language variable.
+
+.. describe:: cfunc
+
+ The name of a C-language function. Should include trailing parentheses.
+
+.. describe:: cmacro
+
+ The name of a "simple" C macro, as defined above.
+
+.. describe:: ctype
+
+ The name of a C-language type.
+
+
+The following role does possibly create a cross-reference, but does not refer
+to objects:
+
+.. describe:: token
+
+ The name of a grammar token (used in the reference manual to create links
+ between production displays).
+
+---------
+
+The following roles don't do anything special except formatting the text
+in a different style:
+
+.. describe:: command
+
+ The name of an OS-level command, such as ``rm``.
+
+.. describe:: dfn
+
+ Mark the defining instance of a term in the text. (No index entries are
+ generated.)
+
+.. describe:: envvar
+
+ An environment variable. Index entries are generated.
+
+.. describe:: file
+
+ The name of a file or directory. Within the contents, you can use curly
+ braces to indicate a "variable" part, for example::
+
+ ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
+
+ In the built documentation, the ``x`` will be displayed differently to
+ indicate that it is to be replaced by the Python minor version.
+
+.. describe:: guilabel
+
+ Labels presented as part of an interactive user interface should be marked
+ using ``guilabel``. This includes labels from text-based interfaces such as
+ those created using :mod:`curses` or other text-based libraries. Any label
+ used in the interface should be marked with this role, including button
+ labels, window titles, field names, menu and menu selection names, and even
+ values in selection lists.
+
+.. describe:: kbd
+
+ Mark a sequence of keystrokes. What form the key sequence takes may depend
+ on platform- or application-specific conventions. When there are no relevant
+ conventions, the names of modifier keys should be spelled out, to improve
+ accessibility for new users and non-native speakers. For example, an
+ *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without
+ reference to a specific application or platform, the same sequence should be
+ marked as ``:kbd:`Control-x Control-f```.
+
+.. describe:: keyword
+
+ The name of a keyword in a programming language.
+
+.. describe:: mailheader
+
+ The name of an RFC 822-style mail header. This markup does not imply that
+ the header is being used in an email message, but can be used to refer to any
+ header of the same "style." This is also used for headers defined by the
+ various MIME specifications. The header name should be entered in the same
+ way it would normally be found in practice, with the camel-casing conventions
+ being preferred where there is more than one common usage. For example:
+ ``:mailheader:`Content-Type```.
+
+.. describe:: makevar
+
+ The name of a :command:`make` variable.
+
+.. describe:: manpage
+
+ A reference to a Unix manual page including the section,
+ e.g. ``:manpage:`ls(1)```.
+
+.. describe:: menuselection
+
+ Menu selections should be marked using the ``menuselection`` role. This is
+ used to mark a complete sequence of menu selections, including selecting
+ submenus and choosing a specific operation, or any subsequence of such a
+ sequence. The names of individual selections should be separated by
+ ``-->``.
+
+ For example, to mark the selection "Start > Programs", use this markup::
+
+ :menuselection:`Start --> Programs`
+
+ When including a selection that includes some trailing indicator, such as the
+ ellipsis some operating systems use to indicate that the command opens a
+ dialog, the indicator should be omitted from the selection name.
+
+.. describe:: mimetype
+
+ The name of a MIME type, or a component of a MIME type (the major or minor
+ portion, taken alone).
+
+.. describe:: newsgroup
+
+ The name of a Usenet newsgroup.
+
+.. describe:: option
+
+ A command-line option to an executable program. The leading hyphen(s) must
+ be included.
+
+.. describe:: program
+
+ The name of an executable program. This may differ from the file name for
+ the executable for some platforms. In particular, the ``.exe`` (or other)
+ extension should be omitted for Windows programs.
+
+.. describe:: regexp
+
+ A regular expression. Quotes should not be included.
+
+.. describe:: samp
+
+ A piece of literal text, such as code. Within the contents, you can use
+ curly braces to indicate a "variable" part, as in ``:file:``.
+
+ If you don't need the "variable part" indication, use the standard
+ ````code```` instead.
+
+.. describe:: var
+
+ A Python or C variable or parameter name.
+
+
+The following roles generate external links:
+
+.. describe:: pep
+
+ A reference to a Python Enhancement Proposal. This generates appropriate
+ index entries. The text "PEP *number*\ " is generated; in the HTML output,
+ this text is a hyperlink to an online copy of the specified PEP.
+
+.. describe:: rfc
+
+ A reference to an Internet Request for Comments. This generates appropriate
+ index entries. The text "RFC *number*\ " is generated; in the HTML output,
+ this text is a hyperlink to an online copy of the specified RFC.
+
+
+Note that there are no special roles for including hyperlinks as you can use
+the standard reST markup for that purpose.
+
+
+.. _doc-ref-role:
+
+Cross-linking markup
+--------------------
+
+To support cross-referencing to arbitrary sections in the documentation, the
+standard reST labels are "abused" a bit: Every label must precede a section
+title; and every label name must be unique throughout the entire documentation
+source.
+
+You can then reference to these sections using the ``:ref:`label-name``` role.
+
+Example::
+
+ .. _my-reference-label:
+
+ Section to cross-reference
+ --------------------------
+
+ This is the text of the section.
+
+ It refers to the section itself, see :ref:`my-reference-label`.
+
+The ``:ref:`` invocation is replaced with the section title.
+
+
+Paragraph-level markup
+----------------------
+
+These directives create short paragraphs and can be used inside information
+units as well as normal text:
+
+.. describe:: note
+
+ An especially important bit of information about an API that a user should be
+ aware of when using whatever bit of API the note pertains to. The content of
+ the directive should be written in complete sentences and include all
+ appropriate punctuation.
+
+ Example::
+
+ .. note::
+
+ This function is not suitable for sending spam e-mails.
+
+.. describe:: warning
+
+ An important bit of information about an API that a user should be very aware
+ of when using whatever bit of API the warning pertains to. The content of
+ the directive should be written in complete sentences and include all
+ appropriate punctuation. This differs from ``note`` in that it is recommended
+ over ``note`` for information regarding security.
+
+.. describe:: versionadded
+
+ This directive documents the version of Python which added the described
+ feature to the library or C API. When this applies to an entire module, it
+ should be placed at the top of the module section before any prose.
+
+ The first argument must be given and is the version in question; you can add
+ a second argument consisting of a *brief* explanation of the change.
+
+ Example::
+
+ .. versionadded:: 2.5
+ The `spam` parameter.
+
+ Note that there must be no blank line between the directive head and the
+ explanation; this is to make these blocks visually continuous in the markup.
+
+.. describe:: versionchanged
+
+ Similar to ``versionadded``, but describes when and what changed in the named
+ feature in some way (new parameters, changed side effects, etc.).
+
+--------------
+
+.. describe:: seealso
+
+ Many sections include a list of references to module documentation or
+ external documents. These lists are created using the ``seealso`` directive.
+
+ The ``seealso`` directive is typically placed in a section just before any
+ sub-sections. For the HTML output, it is shown boxed off from the main flow
+ of the text.
+
+ The content of the ``seealso`` directive should be a reST definition list.
+ Example::
+
+ .. seealso::
+
+ Module :mod:`zipfile`
+ Documentation of the :mod:`zipfile` standard module.
+
+ `GNU tar manual, Basic Tar Format <http://link>`_
+ Documentation for tar archive files, including GNU tar extensions.
+
+.. describe:: rubric
+
+ This directive creates a paragraph heading that is not used to create a
+ table of contents node. It is currently used for the "Footnotes" caption.
+
+.. describe:: centered
+
+ This directive creates a centered boldfaced paragraph. Use it as follows::
+
+ .. centered::
+
+ Paragraph contents.
+
+
+Table-of-contents markup
+------------------------
+
+Since reST does not have facilities to interconnect several documents, or split
+documents into multiple output files, Sphinx uses a custom directive to add
+relations between the single files the documentation is made of, as well as
+tables of contents. The ``toctree`` directive is the central element.
+
+.. describe:: toctree
+
+ This directive inserts a "TOC tree" at the current location, using the
+ individual TOCs (including "sub-TOC trees") of the files given in the
+ directive body. A numeric ``maxdepth`` option may be given to indicate the
+ depth of the tree; by default, all levels are included.
+
+ Consider this example (taken from the library reference index)::
+
+ .. toctree::
+ :maxdepth: 2
+
+ intro.rst
+ strings.rst
+ datatypes.rst
+ numeric.rst
+ (many more files listed here)
+
+ This accomplishes two things:
+
+ * Tables of contents from all those files are inserted, with a maximum depth
+ of two, that means one nested heading. ``toctree`` directives in those
+ files are also taken into account.
+ * Sphinx knows that the relative order of the files ``intro.rst``,
+ ``strings.rst`` and so forth, and it knows that they are children of the
+ shown file, the library index. From this information it generates "next
+ chapter", "previous chapter" and "parent chapter" links.
+
+ In the end, all files included in the build process must occur in one
+ ``toctree`` directive; Sphinx will emit a warning if it finds a file that is
+ not included, because that means that this file will not be reachable through
+ standard navigation.
+
+ The special file ``contents.rst`` at the root of the source directory is the
+ "root" of the TOC tree hierarchy; from it the "Contents" page is generated.
+
+
+Index-generating markup
+-----------------------
+
+Sphinx automatically creates index entries from all information units (like
+functions, classes or attributes) like discussed before.
+
+However, there is also an explicit directive available, to make the index more
+comprehensive and enable index entries in documents where information is not
+mainly contained in information units, such as the language reference.
+
+The directive is ``index`` and contains one or more index entries. Each entry
+consists of a type and a value, separated by a colon.
+
+For example::
+
+ .. index::
+ single: execution!context
+ module: __main__
+ module: sys
+ triple: module; search; path
+
+This directive contains five entries, which will be converted to entries in the
+generated index which link to the exact location of the index statement (or, in
+case of offline media, the corresponding page number).
+
+The possible entry types are:
+
+single
+ Creates a single index entry. Can be made a subentry by separating the
+ subentry text with a semicolon (this is also used below to describe what
+ entries are created).
+pair
+ ``pair: loop; statement`` is a shortcut that creates two index entries,
+ namely ``loop; statement`` and ``statement; loop``.
+triple
+ Likewise, ``triple: module; search; path`` is a shortcut that creates three
+ index entries, which are ``module; search path``, ``search; path, module`` and
+ ``path; module search``.
+module, keyword, operator, object, exception, statement, builtin
+ These all create two index entries. For example, ``module: hashlib`` creates
+ the entries ``module; hashlib`` and ``hashlib; module``.
+
+
+Grammar production displays
+---------------------------
+
+Special markup is available for displaying the productions of a formal grammar.
+The markup is simple and does not attempt to model all aspects of BNF (or any
+derived forms), but provides enough to allow context-free grammars to be
+displayed in a way that causes uses of a symbol to be rendered as hyperlinks to
+the definition of the symbol. There is this directive:
+
+.. describe:: productionlist
+
+ This directive is used to enclose a group of productions. Each production is
+ given on a single line and consists of a name, separated by a colon from the
+ following definition. If the definition spans multiple lines, each
+ continuation line must begin with a colon placed at the same column as in the
+ first line.
+
+ Blank lines are not allowed within ``productionlist`` directive arguments.
+
+ The definition can contain token names which are marked as interpreted text
+ (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references
+ to the productions of these tokens.
+
+ Note that no further reST parsing is done in the production, so that you
+ don't have to escape ``*`` or ``|`` characters.
+
+
+.. XXX describe optional first parameter
+
+The following is an example taken from the Python Reference Manual::
+
+ .. productionlist::
+ try_stmt: try1_stmt | try2_stmt
+ try1_stmt: "try" ":" `suite`
+ : ("except" [`expression` ["," `target`]] ":" `suite`)+
+ : ["else" ":" `suite`]
+ : ["finally" ":" `suite`]
+ try2_stmt: "try" ":" `suite`
+ : "finally" ":" `suite`
+
+
+Substitutions
+-------------
+
+The documentation system provides three substitutions that are defined by default.
+They are set in the build configuration file, see :ref:`doc-build-config`.
+
+.. describe:: |release|
+
+ Replaced by the Python release the documentation refers to. This is the full
+ version string including alpha/beta/release candidate tags, e.g. ``2.5.2b3``.
+
+.. describe:: |version|
+
+ Replaced by the Python version the documentation refers to. This consists
+ only of the major and minor version parts, e.g. ``2.5``, even for version
+ 2.5.1.
+
+.. describe:: |today|
+
+ Replaced by either today's date, or the date set in the build configuration
+ file. Normally has the format ``April 14, 2007``.
+
+
+.. rubric:: Footnotes
+
+.. [1] There is a standard ``.. include`` directive, but it raises errors if the
+ file is not found. This one only emits a warning.
--- /dev/null
+.. highlightlang:: rest
+
+reStructuredText Primer
+=======================
+
+This section is a brief introduction to reStructuredText (reST) concepts and
+syntax, intended to provide authors with enough information to author documents
+productively. Since reST was designed to be a simple, unobtrusive markup
+language, this will not take too long.
+
+.. seealso::
+
+ The authoritative `reStructuredText User
+ Documentation <http://docutils.sourceforge.net/rst.html>`_.
+
+
+Paragraphs
+----------
+
+The paragraph is the most basic block in a reST document. Paragraphs are simply
+chunks of text separated by one or more blank lines. As in Python, indentation
+is significant in reST, so all lines of the same paragraph must be left-aligned
+to the same level of indentation.
+
+
+Inline markup
+-------------
+
+The standard reST inline markup is quite simple: use
+
+* one asterisk: ``*text*`` for emphasis (italics),
+* two asterisks: ``**text**`` for strong emphasis (boldface), and
+* backquotes: ````text```` for code samples.
+
+If asterisks or backquotes appear in running text and could be confused with
+inline markup delimiters, they have to be escaped with a backslash.
+
+Be aware of some restrictions of this markup:
+
+* it may not be nested,
+* content may not start or end with whitespace: ``* text*`` is wrong,
+* it must be separated from surrounding text by non-word characters. Use a
+ backslash escaped space to work around that: ``thisis\ *one*\ word``.
+
+These restrictions may be lifted in future versions of the docutils.
+
+reST also allows for custom "interpreted text roles"', which signify that the
+enclosed text should be interpreted in a specific way. Sphinx uses this to
+provide semantic markup and cross-referencing of identifiers, as described in
+the appropriate section. The general syntax is ``:rolename:`content```.
+
+
+Lists and Quotes
+----------------
+
+List markup is natural: just place an asterisk at the start of a paragraph and
+indent properly. The same goes for numbered lists; they can also be
+autonumbered using a ``#`` sign::
+
+ * This is a bulleted list.
+ * It has two items, the second
+ item uses two lines.
+
+ 1. This is a numbered list.
+ 2. It has two items too.
+
+ #. This is a numbered list.
+ #. It has two items too.
+
+Note that Sphinx disables the use of enumerated lists introduced by alphabetic
+or roman numerals, such as ::
+
+ A. First item
+ B. Second item
+
+
+Nested lists are possible, but be aware that they must be separated from the
+parent list items by blank lines::
+
+ * this is
+ * a list
+
+ * with a nested list
+ * and some subitems
+
+ * and here the parent list continues
+
+Definition lists are created as follows::
+
+ term (up to a line of text)
+ Definition of the term, which must be indented
+
+ and can even consist of multiple paragraphs
+
+ next term
+ Description.
+
+
+Paragraphs are quoted by just indenting them more than the surrounding
+paragraphs.
+
+
+Source Code
+-----------
+
+Literal code blocks are introduced by ending a paragraph with the special marker
+``::``. The literal block must be indented, to be able to include blank lines::
+
+ This is a normal text paragraph. The next paragraph is a code sample::
+
+ It is not processed in any way, except
+ that the indentation is removed.
+
+ It can span multiple lines.
+
+ This is a normal text paragraph again.
+
+The handling of the ``::`` marker is smart:
+
+* If it occurs as a paragraph of its own, that paragraph is completely left
+ out of the document.
+* If it is preceded by whitespace, the marker is removed.
+* If it is preceded by non-whitespace, the marker is replaced by a single
+ colon.
+
+That way, the second sentence in the above example's first paragraph would be
+rendered as "The next paragraph is a code sample:".
+
+
+Hyperlinks
+----------
+
+External links
+^^^^^^^^^^^^^^
+
+Use ```Link text <http://target>`_`` for inline web links. If the link text
+should be the web address, you don't need special markup at all, the parser
+finds links and mail addresses in ordinary text.
+
+Internal links
+^^^^^^^^^^^^^^
+
+Internal linking is done via a special reST role, see the section on specific
+markup, :ref:`doc-ref-role`.
+
+
+Sections
+--------
+
+Section headers are created by underlining (and optionally overlining) the
+section title with a punctuation character, at least as long as the text::
+
+ =================
+ This is a heading
+ =================
+
+Normally, there are no heading levels assigned to certain characters as the
+structure is determined from the succession of headings. However, for the
+Python documentation, we use this convention:
+
+* ``#`` with overline, for parts
+* ``*`` with overline, for chapters
+* ``=``, for sections
+* ``-``, for subsections
+* ``^``, for subsubsections
+* ``"``, for paragraphs
+
+
+Explicit Markup
+---------------
+
+"Explicit markup" is used in reST for most constructs that need special
+handling, such as footnotes, specially-highlighted paragraphs, comments, and
+generic directives.
+
+An explicit markup block begins with a line starting with ``..`` followed by
+whitespace and is terminated by the next paragraph at the same level of
+indentation. (There needs to be a blank line between explicit markup and normal
+paragraphs. This may all sound a bit complicated, but it is intuitive enough
+when you write it.)
+
+
+Directives
+----------
+
+A directive is a generic block of explicit markup. Besides roles, it is one of
+the extension mechanisms of reST, and Sphinx makes heavy use of it.
+
+Basically, a directive consists of a name, arguments, options and content. (Keep
+this terminology in mind, it is used in the next chapter describing custom
+directives.) Looking at this example, ::
+
+ .. function:: foo(x)
+ foo(y, z)
+ :bar: no
+
+ Return a line of text input from the user.
+
+``function`` is the directive name. It is given two arguments here, the
+remainder of the first line and the second line, as well as one option ``bar``
+(as you can see, options are given in the lines immediately following the
+arguments and indicated by the colons).
+
+The directive content follows after a blank line and is indented relative to the
+directive start.
+
+
+Footnotes
+---------
+
+For footnotes, use ``[#]_`` to mark the footnote location, and add the footnote
+body at the bottom of the document after a "Footnotes" rubric heading, like so::
+
+ Lorem ipsum [#]_ dolor sit amet ... [#]_
+
+ .. rubric:: Footnotes
+
+ .. [#] Text of the first footnote.
+ .. [#] Text of the second footnote.
+
+You can also explicitly number the footnotes for better context.
+
+
+Comments
+--------
+
+Every explicit markup block which isn't a valid markup construct (like the
+footnotes above) is regarded as a comment.
+
+
+Source encoding
+---------------
+
+Since the easiest way to include special characters like em dashes or copyright
+signs in reST is to directly write them as Unicode characters, one has to
+specify an encoding:
+
+All Python documentation source files must be in UTF-8 encoding, and the HTML
+documents written from them will be in that encoding as well.
+
+
+Gotchas
+-------
+
+There are some problems one commonly runs into while authoring reST documents:
+
+* **Separation of inline markup:** As said above, inline markup spans must be
+ separated from the surrounding text by non-word characters, you have to use
+ an escaped space to get around that.
+
+.. XXX more?
--- /dev/null
+.. highlightlang:: rest
+
+The Sphinx build system
+=======================
+
+.. XXX: intro...
+
+.. _doc-build-config:
+
+The build configuration file
+----------------------------
+
+The documentation root, that is the ``Doc`` subdirectory of the source
+distribution, contains a file named ``conf.py``. This file is called the "build
+configuration file", and it contains several variables that are read and used
+during a build run.
+
+These variables are:
+
+version : string
+ A string that is used as a replacement for the ``|version|`` reST
+ substitution. It should be the Python version the documentation refers to.
+ This consists only of the major and minor version parts, e.g. ``2.5``, even
+ for version 2.5.1.
+
+release : string
+ A string that is used as a replacement for the ``|release|`` reST
+ substitution. It should be the full version string including
+ alpha/beta/release candidate tags, e.g. ``2.5.2b3``.
+
+Both ``release`` and ``version`` can be ``'auto'``, which means that they are
+determined at runtime from the ``Include/patchlevel.h`` file, if a complete
+Python source distribution can be found, or else from the interpreter running
+Sphinx.
+
+today_fmt : string
+ A ``strftime`` format that is used to format a replacement for the
+ ``|today|`` reST substitution.
+
+today : string
+ A string that can contain a date that should be written to the documentation
+ output literally. If this is nonzero, it is used instead of
+ ``strftime(today_fmt)``.
+
+unused_files : list of strings
+ A list of reST filenames that are to be disregarded during building. This
+ could be docs for temporarily disabled modules or documentation that's not
+ yet ready for public consumption.
+
+last_updated_format : string
+ If this is not an empty string, it will be given to ``time.strftime()`` and
+ written to each generated output file after "last updated on:".
+
+use_smartypants : bool
+ If true, use SmartyPants to convert quotes and dashes to the typographically
+ correct entities.
+
+add_function_parentheses : bool
+ If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and
+ ``:cfunc:`` cross-references.
\ No newline at end of file
--- /dev/null
+.. highlightlang:: rest
+
+Style Guide
+===========
+
+The Python documentation should follow the `Apple Publications Style Guide`_
+wherever possible. This particular style guide was selected mostly because it
+seems reasonable and is easy to get online.
+
+Topics which are not covered in the Apple's style guide will be discussed in
+this document.
+
+All reST files use an indentation of 3 spaces. The maximum line length is 80
+characters for normal text, but tables, deeply indented code samples and long
+links may extend beyond that.
+
+Make generous use of blank lines where applicable; they help grouping things
+together.
+
+A sentence-ending period may be followed by one or two spaces; while reST
+ignores the second space, it is customarily put in by some users, for example
+to aid Emacs' auto-fill mode.
+
+Footnotes are generally discouraged, though they may be used when they are the
+best way to present specific information. When a footnote reference is added at
+the end of the sentence, it should follow the sentence-ending punctuation. The
+reST markup should appear something like this::
+
+ This sentence has a footnote reference. [#]_ This is the next sentence.
+
+Footnotes should be gathered at the end of a file, or if the file is very long,
+at the end of a section. The docutils will automatically create backlinks to
+the footnote reference.
+
+Footnotes may appear in the middle of sentences where appropriate.
+
+Many special names are used in the Python documentation, including the names of
+operating systems, programming languages, standards bodies, and the like. Most
+of these entities are not assigned any special markup, but the preferred
+spellings are given here to aid authors in maintaining the consistency of
+presentation in the Python documentation.
+
+Other terms and words deserve special mention as well; these conventions should
+be used to ensure consistency throughout the documentation:
+
+CPU
+ For "central processing unit." Many style guides say this should be spelled
+ out on the first use (and if you must use it, do so!). For the Python
+ documentation, this abbreviation should be avoided since there's no
+ reasonable way to predict which occurrence will be the first seen by the
+ reader. It is better to use the word "processor" instead.
+
+POSIX
+ The name assigned to a particular group of standards. This is always
+ uppercase.
+
+Python
+ The name of our favorite programming language is always capitalized.
+
+Unicode
+ The name of a character set and matching encoding. This is always written
+ capitalized.
+
+Unix
+ The name of the operating system developed at AT&T Bell Labs in the early
+ 1970s.
+
+
+.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf
+
--- /dev/null
+.. highlightlang:: c
+
+
+.. _building:
+
+********************************************
+Building C and C++ Extensions with distutils
+********************************************
+
+.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
+
+
+Starting in Python 1.4, Python provides, on Unix, a special make file for
+building make files for building dynamically-linked extensions and custom
+interpreters. Starting with Python 2.0, this mechanism (known as related to
+Makefile.pre.in, and Setup files) is no longer supported. Building custom
+interpreters was rarely used, and extension modules can be built using
+distutils.
+
+Building an extension module using distutils requires that distutils is
+installed on the build machine, which is included in Python 2.x and available
+separately for Python 1.5. Since distutils also supports creation of binary
+packages, users don't necessarily need a compiler and distutils to install the
+extension.
+
+A distutils package contains a driver script, :file:`setup.py`. This is a plain
+Python file, which, in the most simple case, could look like this::
+
+ from distutils.core import setup, Extension
+
+ module1 = Extension('demo',
+ sources = ['demo.c'])
+
+ setup (name = 'PackageName',
+ version = '1.0',
+ description = 'This is a demo package',
+ ext_modules = [module1])
+
+
+With this :file:`setup.py`, and a file :file:`demo.c`, running ::
+
+ python setup.py build
+
+will compile :file:`demo.c`, and produce an extension module named ``demo`` in
+the :file:`build` directory. Depending on the system, the module file will end
+up in a subdirectory :file:`build/lib.system`, and may have a name like
+:file:`demo.so` or :file:`demo.pyd`.
+
+In the :file:`setup.py`, all execution is performed by calling the ``setup``
+function. This takes a variable number of keyword arguments, of which the
+example above uses only a subset. Specifically, the example specifies
+meta-information to build packages, and it specifies the contents of the
+package. Normally, a package will contain of addition modules, like Python
+source modules, documentation, subpackages, etc. Please refer to the distutils
+documentation in :ref:`distutils-index` to learn more about the features of
+distutils; this section explains building extension modules only.
+
+It is common to pre-compute arguments to :func:`setup`, to better structure the
+driver script. In the example above, the\ ``ext_modules`` argument to
+:func:`setup` is a list of extension modules, each of which is an instance of
+the :class:`Extension`. In the example, the instance defines an extension named
+``demo`` which is build by compiling a single source file, :file:`demo.c`.
+
+In many cases, building an extension is more complex, since additional
+preprocessor defines and libraries may be needed. This is demonstrated in the
+example below. ::
+
+ from distutils.core import setup, Extension
+
+ module1 = Extension('demo',
+ define_macros = [('MAJOR_VERSION', '1'),
+ ('MINOR_VERSION', '0')],
+ include_dirs = ['/usr/local/include'],
+ libraries = ['tcl83'],
+ library_dirs = ['/usr/local/lib'],
+ sources = ['demo.c'])
+
+ setup (name = 'PackageName',
+ version = '1.0',
+ description = 'This is a demo package',
+ author = 'Martin v. Loewis',
+ author_email = 'martin@v.loewis.de',
+ url = 'http://www.python.org/doc/current/ext/building.html',
+ long_description = '''
+ This is really just a demo package.
+ ''',
+ ext_modules = [module1])
+
+
+In this example, :func:`setup` is called with additional meta-information, which
+is recommended when distribution packages have to be built. For the extension
+itself, it specifies preprocessor defines, include directories, library
+directories, and libraries. Depending on the compiler, distutils passes this
+information in different ways to the compiler. For example, on Unix, this may
+result in the compilation commands ::
+
+ gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o
+
+ gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so
+
+These lines are for demonstration purposes only; distutils users should trust
+that distutils gets the invocations right.
+
+
+.. _distributing:
+
+Distributing your extension modules
+===================================
+
+When an extension has been successfully build, there are three ways to use it.
+
+End-users will typically want to install the module, they do so by running ::
+
+ python setup.py install
+
+Module maintainers should produce source packages; to do so, they run ::
+
+ python setup.py sdist
+
+In some cases, additional files need to be included in a source distribution;
+this is done through a :file:`MANIFEST.in` file; see the distutils documentation
+for details.
+
+If the source distribution has been build successfully, maintainers can also
+create binary distributions. Depending on the platform, one of the following
+commands can be used to do so. ::
+
+ python setup.py bdist_wininst
+ python setup.py bdist_rpm
+ python setup.py bdist_dumb
+
--- /dev/null
+.. highlightlang:: c
+
+
+.. _embedding:
+
+***************************************
+Embedding Python in Another Application
+***************************************
+
+The previous chapters discussed how to extend Python, that is, how to extend the
+functionality of Python by attaching a library of C functions to it. It is also
+possible to do it the other way around: enrich your C/C++ application by
+embedding Python in it. Embedding provides your application with the ability to
+implement some of the functionality of your application in Python rather than C
+or C++. This can be used for many purposes; one example would be to allow users
+to tailor the application to their needs by writing some scripts in Python. You
+can also use it yourself if some of the functionality can be written in Python
+more easily.
+
+Embedding Python is similar to extending it, but not quite. The difference is
+that when you extend Python, the main program of the application is still the
+Python interpreter, while if you embed Python, the main program may have nothing
+to do with Python --- instead, some parts of the application occasionally call
+the Python interpreter to run some Python code.
+
+So if you are embedding Python, you are providing your own main program. One of
+the things this main program has to do is initialize the Python interpreter. At
+the very least, you have to call the function :cfunc:`Py_Initialize` (on Mac OS,
+call :cfunc:`PyMac_Initialize` instead). There are optional calls to pass
+command line arguments to Python. Then later you can call the interpreter from
+any part of the application.
+
+There are several different ways to call the interpreter: you can pass a string
+containing Python statements to :cfunc:`PyRun_SimpleString`, or you can pass a
+stdio file pointer and a file name (for identification in error messages only)
+to :cfunc:`PyRun_SimpleFile`. You can also call the lower-level operations
+described in the previous chapters to construct and use Python objects.
+
+A simple demo of embedding Python can be found in the directory
+:file:`Demo/embed/` of the source distribution.
+
+
+.. seealso::
+
+ :ref:`c-api-index`
+ The details of Python's C interface are given in this manual. A great deal of
+ necessary information can be found here.
+
+
+.. _high-level-embedding:
+
+Very High Level Embedding
+=========================
+
+The simplest form of embedding Python is the use of the very high level
+interface. This interface is intended to execute a Python script without needing
+to interact with the application directly. This can for example be used to
+perform some operation on a file. ::
+
+ #include <Python.h>
+
+ int
+ main(int argc, char *argv[])
+ {
+ Py_Initialize();
+ PyRun_SimpleString("from time import time,ctime\n"
+ "print 'Today is',ctime(time())\n");
+ Py_Finalize();
+ return 0;
+ }
+
+The above code first initializes the Python interpreter with
+:cfunc:`Py_Initialize`, followed by the execution of a hard-coded Python script
+that print the date and time. Afterwards, the :cfunc:`Py_Finalize` call shuts
+the interpreter down, followed by the end of the program. In a real program,
+you may want to get the Python script from another source, perhaps a text-editor
+routine, a file, or a database. Getting the Python code from a file can better
+be done by using the :cfunc:`PyRun_SimpleFile` function, which saves you the
+trouble of allocating memory space and loading the file contents.
+
+
+.. _lower-level-embedding:
+
+Beyond Very High Level Embedding: An overview
+=============================================
+
+The high level interface gives you the ability to execute arbitrary pieces of
+Python code from your application, but exchanging data values is quite
+cumbersome to say the least. If you want that, you should use lower level calls.
+At the cost of having to write more C code, you can achieve almost anything.
+
+It should be noted that extending Python and embedding Python is quite the same
+activity, despite the different intent. Most topics discussed in the previous
+chapters are still valid. To show this, consider what the extension code from
+Python to C really does:
+
+#. Convert data values from Python to C,
+
+#. Perform a function call to a C routine using the converted values, and
+
+#. Convert the data values from the call from C to Python.
+
+When embedding Python, the interface code does:
+
+#. Convert data values from C to Python,
+
+#. Perform a function call to a Python interface routine using the converted
+ values, and
+
+#. Convert the data values from the call from Python to C.
+
+As you can see, the data conversion steps are simply swapped to accommodate the
+different direction of the cross-language transfer. The only difference is the
+routine that you call between both data conversions. When extending, you call a
+C routine, when embedding, you call a Python routine.
+
+This chapter will not discuss how to convert data from Python to C and vice
+versa. Also, proper use of references and dealing with errors is assumed to be
+understood. Since these aspects do not differ from extending the interpreter,
+you can refer to earlier chapters for the required information.
+
+
+.. _pure-embedding:
+
+Pure Embedding
+==============
+
+The first program aims to execute a function in a Python script. Like in the
+section about the very high level interface, the Python interpreter does not
+directly interact with the application (but that will change in the next
+section).
+
+The code to run a function defined in a Python script is:
+
+.. literalinclude:: ../includes/run-func.c
+
+
+This code loads a Python script using ``argv[1]``, and calls the function named
+in ``argv[2]``. Its integer arguments are the other values of the ``argv``
+array. If you compile and link this program (let's call the finished executable
+:program:`call`), and use it to execute a Python script, such as::
+
+ def multiply(a,b):
+ print "Will compute", a, "times", b
+ c = 0
+ for i in range(0, a):
+ c = c + b
+ return c
+
+then the result should be::
+
+ $ call multiply multiply 3 2
+ Will compute 3 times 2
+ Result of call: 6
+
+Although the program is quite large for its functionality, most of the code is
+for data conversion between Python and C, and for error reporting. The
+interesting part with respect to embedding Python starts with
+
+.. % $
+
+::
+
+ Py_Initialize();
+ pName = PyString_FromString(argv[1]);
+ /* Error checking of pName left out */
+ pModule = PyImport_Import(pName);
+
+After initializing the interpreter, the script is loaded using
+:cfunc:`PyImport_Import`. This routine needs a Python string as its argument,
+which is constructed using the :cfunc:`PyString_FromString` data conversion
+routine. ::
+
+ pFunc = PyObject_GetAttrString(pModule, argv[2]);
+ /* pFunc is a new reference */
+
+ if (pFunc && PyCallable_Check(pFunc)) {
+ ...
+ }
+ Py_XDECREF(pFunc);
+
+Once the script is loaded, the name we're looking for is retrieved using
+:cfunc:`PyObject_GetAttrString`. If the name exists, and the object returned is
+callable, you can safely assume that it is a function. The program then
+proceeds by constructing a tuple of arguments as normal. The call to the Python
+function is then made with::
+
+ pValue = PyObject_CallObject(pFunc, pArgs);
+
+Upon return of the function, ``pValue`` is either *NULL* or it contains a
+reference to the return value of the function. Be sure to release the reference
+after examining the value.
+
+
+.. _extending-with-embedding:
+
+Extending Embedded Python
+=========================
+
+Until now, the embedded Python interpreter had no access to functionality from
+the application itself. The Python API allows this by extending the embedded
+interpreter. That is, the embedded interpreter gets extended with routines
+provided by the application. While it sounds complex, it is not so bad. Simply
+forget for a while that the application starts the Python interpreter. Instead,
+consider the application to be a set of subroutines, and write some glue code
+that gives Python access to those routines, just like you would write a normal
+Python extension. For example::
+
+ static int numargs=0;
+
+ /* Return the number of arguments of the application command line */
+ static PyObject*
+ emb_numargs(PyObject *self, PyObject *args)
+ {
+ if(!PyArg_ParseTuple(args, ":numargs"))
+ return NULL;
+ return Py_BuildValue("i", numargs);
+ }
+
+ static PyMethodDef EmbMethods[] = {
+ {"numargs", emb_numargs, METH_VARARGS,
+ "Return the number of arguments received by the process."},
+ {NULL, NULL, 0, NULL}
+ };
+
+Insert the above code just above the :cfunc:`main` function. Also, insert the
+following two statements directly after :cfunc:`Py_Initialize`::
+
+ numargs = argc;
+ Py_InitModule("emb", EmbMethods);
+
+These two lines initialize the ``numargs`` variable, and make the
+:func:`emb.numargs` function accessible to the embedded Python interpreter.
+With these extensions, the Python script can do things like ::
+
+ import emb
+ print "Number of arguments", emb.numargs()
+
+In a real application, the methods will expose an API of the application to
+Python.
+
+.. % \section{For the future}
+.. %
+.. % You don't happen to have a nice library to get textual
+.. % equivalents of numeric values do you :-) ?
+.. % Callbacks here ? (I may be using information from that section
+.. % ?!)
+.. % threads
+.. % code examples do not really behave well if errors happen
+.. % (what to watch out for)
+
+
+.. _embeddingincplusplus:
+
+Embedding Python in C++
+=======================
+
+It is also possible to embed Python in a C++ program; precisely how this is done
+will depend on the details of the C++ system used; in general you will need to
+write the main program in C++, and use the C++ compiler to compile and link your
+program. There is no need to recompile Python itself using C++.
+
+
+.. _link-reqs:
+
+Linking Requirements
+====================
+
+While the :program:`configure` script shipped with the Python sources will
+correctly build Python to export the symbols needed by dynamically linked
+extensions, this is not automatically inherited by applications which embed the
+Python library statically, at least on Unix. This is an issue when the
+application is linked to the static runtime library (:file:`libpython.a`) and
+needs to load dynamic extensions (implemented as :file:`.so` files).
+
+The problem is that some entry points are defined by the Python runtime solely
+for extension modules to use. If the embedding application does not use any of
+these entry points, some linkers will not include those entries in the symbol
+table of the finished executable. Some additional options are needed to inform
+the linker not to remove these symbols.
+
+Determining the right options to use for any given platform can be quite
+difficult, but fortunately the Python configuration already has those values.
+To retrieve them from an installed Python interpreter, start an interactive
+interpreter and have a short session like this::
+
+ >>> import distutils.sysconfig
+ >>> distutils.sysconfig.get_config_var('LINKFORSHARED')
+ '-Xlinker -export-dynamic'
+
+.. index:: module: distutils.sysconfig
+
+The contents of the string presented will be the options that should be used.
+If the string is empty, there's no need to add any additional options. The
+:const:`LINKFORSHARED` definition corresponds to the variable of the same name
+in Python's top-level :file:`Makefile`.
+
--- /dev/null
+.. highlightlang:: c
+
+
+.. _extending-intro:
+
+******************************
+Extending Python with C or C++
+******************************
+
+It is quite easy to add new built-in modules to Python, if you know how to
+program in C. Such :dfn:`extension modules` can do two things that can't be
+done directly in Python: they can implement new built-in object types, and they
+can call C library functions and system calls.
+
+To support extensions, the Python API (Application Programmers Interface)
+defines a set of functions, macros and variables that provide access to most
+aspects of the Python run-time system. The Python API is incorporated in a C
+source file by including the header ``"Python.h"``.
+
+The compilation of an extension module depends on its intended use as well as on
+your system setup; details are given in later chapters.
+
+
+.. _extending-simpleexample:
+
+A Simple Example
+================
+
+Let's create an extension module called ``spam`` (the favorite food of Monty
+Python fans...) and let's say we want to create a Python interface to the C
+library function :cfunc:`system`. [#]_ This function takes a null-terminated
+character string as argument and returns an integer. We want this function to
+be callable from Python as follows::
+
+ >>> import spam
+ >>> status = spam.system("ls -l")
+
+Begin by creating a file :file:`spammodule.c`. (Historically, if a module is
+called ``spam``, the C file containing its implementation is called
+:file:`spammodule.c`; if the module name is very long, like ``spammify``, the
+module name can be just :file:`spammify.c`.)
+
+The first line of our file can be::
+
+ #include <Python.h>
+
+which pulls in the Python API (you can add a comment describing the purpose of
+the module and a copyright notice if you like).
+
+.. warning::
+
+ Since Python may define some pre-processor definitions which affect the standard
+ headers on some systems, you *must* include :file:`Python.h` before any standard
+ headers are included.
+
+All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` or
+``PY``, except those defined in standard header files. For convenience, and
+since they are used extensively by the Python interpreter, ``"Python.h"``
+includes a few standard header files: ``<stdio.h>``, ``<string.h>``,
+``<errno.h>``, and ``<stdlib.h>``. If the latter header file does not exist on
+your system, it declares the functions :cfunc:`malloc`, :cfunc:`free` and
+:cfunc:`realloc` directly.
+
+The next thing we add to our module file is the C function that will be called
+when the Python expression ``spam.system(string)`` is evaluated (we'll see
+shortly how it ends up being called)::
+
+ static PyObject *
+ spam_system(PyObject *self, PyObject *args)
+ {
+ const char *command;
+ int sts;
+
+ if (!PyArg_ParseTuple(args, "s", &command))
+ return NULL;
+ sts = system(command);
+ return Py_BuildValue("i", sts);
+ }
+
+There is a straightforward translation from the argument list in Python (for
+example, the single expression ``"ls -l"``) to the arguments passed to the C
+function. The C function always has two arguments, conventionally named *self*
+and *args*.
+
+The *self* argument is only used when the C function implements a built-in
+method, not a function. In the example, *self* will always be a *NULL* pointer,
+since we are defining a function, not a method. (This is done so that the
+interpreter doesn't have to understand two different types of C functions.)
+
+The *args* argument will be a pointer to a Python tuple object containing the
+arguments. Each item of the tuple corresponds to an argument in the call's
+argument list. The arguments are Python objects --- in order to do anything
+with them in our C function we have to convert them to C values. The function
+:cfunc:`PyArg_ParseTuple` in the Python API checks the argument types and
+converts them to C values. It uses a template string to determine the required
+types of the arguments as well as the types of the C variables into which to
+store the converted values. More about this later.
+
+:cfunc:`PyArg_ParseTuple` returns true (nonzero) if all arguments have the right
+type and its components have been stored in the variables whose addresses are
+passed. It returns false (zero) if an invalid argument list was passed. In the
+latter case it also raises an appropriate exception so the calling function can
+return *NULL* immediately (as we saw in the example).
+
+
+.. _extending-errors:
+
+Intermezzo: Errors and Exceptions
+=================================
+
+An important convention throughout the Python interpreter is the following: when
+a function fails, it should set an exception condition and return an error value
+(usually a *NULL* pointer). Exceptions are stored in a static global variable
+inside the interpreter; if this variable is *NULL* no exception has occurred. A
+second global variable stores the "associated value" of the exception (the
+second argument to :keyword:`raise`). A third variable contains the stack
+traceback in case the error originated in Python code. These three variables
+are the C equivalents of the Python variables ``sys.exc_type``,
+``sys.exc_value`` and ``sys.exc_traceback`` (see the section on module
+:mod:`sys` in the Python Library Reference). It is important to know about them
+to understand how errors are passed around.
+
+The Python API defines a number of functions to set various types of exceptions.
+
+The most common one is :cfunc:`PyErr_SetString`. Its arguments are an exception
+object and a C string. The exception object is usually a predefined object like
+:cdata:`PyExc_ZeroDivisionError`. The C string indicates the cause of the error
+and is converted to a Python string object and stored as the "associated value"
+of the exception.
+
+Another useful function is :cfunc:`PyErr_SetFromErrno`, which only takes an
+exception argument and constructs the associated value by inspection of the
+global variable :cdata:`errno`. The most general function is
+:cfunc:`PyErr_SetObject`, which takes two object arguments, the exception and
+its associated value. You don't need to :cfunc:`Py_INCREF` the objects passed
+to any of these functions.
+
+You can test non-destructively whether an exception has been set with
+:cfunc:`PyErr_Occurred`. This returns the current exception object, or *NULL*
+if no exception has occurred. You normally don't need to call
+:cfunc:`PyErr_Occurred` to see whether an error occurred in a function call,
+since you should be able to tell from the return value.
+
+When a function *f* that calls another function *g* detects that the latter
+fails, *f* should itself return an error value (usually *NULL* or ``-1``). It
+should *not* call one of the :cfunc:`PyErr_\*` functions --- one has already
+been called by *g*. *f*'s caller is then supposed to also return an error
+indication to *its* caller, again *without* calling :cfunc:`PyErr_\*`, and so on
+--- the most detailed cause of the error was already reported by the function
+that first detected it. Once the error reaches the Python interpreter's main
+loop, this aborts the currently executing Python code and tries to find an
+exception handler specified by the Python programmer.
+
+(There are situations where a module can actually give a more detailed error
+message by calling another :cfunc:`PyErr_\*` function, and in such cases it is
+fine to do so. As a general rule, however, this is not necessary, and can cause
+information about the cause of the error to be lost: most operations can fail
+for a variety of reasons.)
+
+To ignore an exception set by a function call that failed, the exception
+condition must be cleared explicitly by calling :cfunc:`PyErr_Clear`. The only
+time C code should call :cfunc:`PyErr_Clear` is if it doesn't want to pass the
+error on to the interpreter but wants to handle it completely by itself
+(possibly by trying something else, or pretending nothing went wrong).
+
+Every failing :cfunc:`malloc` call must be turned into an exception --- the
+direct caller of :cfunc:`malloc` (or :cfunc:`realloc`) must call
+:cfunc:`PyErr_NoMemory` and return a failure indicator itself. All the
+object-creating functions (for example, :cfunc:`PyInt_FromLong`) already do
+this, so this note is only relevant to those who call :cfunc:`malloc` directly.
+
+Also note that, with the important exception of :cfunc:`PyArg_ParseTuple` and
+friends, functions that return an integer status usually return a positive value
+or zero for success and ``-1`` for failure, like Unix system calls.
+
+Finally, be careful to clean up garbage (by making :cfunc:`Py_XDECREF` or
+:cfunc:`Py_DECREF` calls for objects you have already created) when you return
+an error indicator!
+
+The choice of which exception to raise is entirely yours. There are predeclared
+C objects corresponding to all built-in Python exceptions, such as
+:cdata:`PyExc_ZeroDivisionError`, which you can use directly. Of course, you
+should choose exceptions wisely --- don't use :cdata:`PyExc_TypeError` to mean
+that a file couldn't be opened (that should probably be :cdata:`PyExc_IOError`).
+If something's wrong with the argument list, the :cfunc:`PyArg_ParseTuple`
+function usually raises :cdata:`PyExc_TypeError`. If you have an argument whose
+value must be in a particular range or must satisfy other conditions,
+:cdata:`PyExc_ValueError` is appropriate.
+
+You can also define a new exception that is unique to your module. For this, you
+usually declare a static object variable at the beginning of your file::
+
+ static PyObject *SpamError;
+
+and initialize it in your module's initialization function (:cfunc:`initspam`)
+with an exception object (leaving out the error checking for now)::
+
+ PyMODINIT_FUNC
+ initspam(void)
+ {
+ PyObject *m;
+
+ m = Py_InitModule("spam", SpamMethods);
+ if (m == NULL)
+ return;
+
+ SpamError = PyErr_NewException("spam.error", NULL, NULL);
+ Py_INCREF(SpamError);
+ PyModule_AddObject(m, "error", SpamError);
+ }
+
+Note that the Python name for the exception object is :exc:`spam.error`. The
+:cfunc:`PyErr_NewException` function may create a class with the base class
+being :exc:`Exception` (unless another class is passed in instead of *NULL*),
+described in :ref:`bltin-exceptions`.
+
+Note also that the :cdata:`SpamError` variable retains a reference to the newly
+created exception class; this is intentional! Since the exception could be
+removed from the module by external code, an owned reference to the class is
+needed to ensure that it will not be discarded, causing :cdata:`SpamError` to
+become a dangling pointer. Should it become a dangling pointer, C code which
+raises the exception could cause a core dump or other unintended side effects.
+
+We discuss the use of PyMODINIT_FUNC as a function return type later in this
+sample.
+
+
+.. _backtoexample:
+
+Back to the Example
+===================
+
+Going back to our example function, you should now be able to understand this
+statement::
+
+ if (!PyArg_ParseTuple(args, "s", &command))
+ return NULL;
+
+It returns *NULL* (the error indicator for functions returning object pointers)
+if an error is detected in the argument list, relying on the exception set by
+:cfunc:`PyArg_ParseTuple`. Otherwise the string value of the argument has been
+copied to the local variable :cdata:`command`. This is a pointer assignment and
+you are not supposed to modify the string to which it points (so in Standard C,
+the variable :cdata:`command` should properly be declared as ``const char
+*command``).
+
+The next statement is a call to the Unix function :cfunc:`system`, passing it
+the string we just got from :cfunc:`PyArg_ParseTuple`::
+
+ sts = system(command);
+
+Our :func:`spam.system` function must return the value of :cdata:`sts` as a
+Python object. This is done using the function :cfunc:`Py_BuildValue`, which is
+something like the inverse of :cfunc:`PyArg_ParseTuple`: it takes a format
+string and an arbitrary number of C values, and returns a new Python object.
+More info on :cfunc:`Py_BuildValue` is given later. ::
+
+ return Py_BuildValue("i", sts);
+
+In this case, it will return an integer object. (Yes, even integers are objects
+on the heap in Python!)
+
+If you have a C function that returns no useful argument (a function returning
+:ctype:`void`), the corresponding Python function must return ``None``. You
+need this idiom to do so (which is implemented by the :cmacro:`Py_RETURN_NONE`
+macro)::
+
+ Py_INCREF(Py_None);
+ return Py_None;
+
+:cdata:`Py_None` is the C name for the special Python object ``None``. It is a
+genuine Python object rather than a *NULL* pointer, which means "error" in most
+contexts, as we have seen.
+
+
+.. _methodtable:
+
+The Module's Method Table and Initialization Function
+=====================================================
+
+I promised to show how :cfunc:`spam_system` is called from Python programs.
+First, we need to list its name and address in a "method table"::
+
+ static PyMethodDef SpamMethods[] = {
+ ...
+ {"system", spam_system, METH_VARARGS,
+ "Execute a shell command."},
+ ...
+ {NULL, NULL, 0, NULL} /* Sentinel */
+ };
+
+Note the third entry (``METH_VARARGS``). This is a flag telling the interpreter
+the calling convention to be used for the C function. It should normally always
+be ``METH_VARARGS`` or ``METH_VARARGS | METH_KEYWORDS``; a value of ``0`` means
+that an obsolete variant of :cfunc:`PyArg_ParseTuple` is used.
+
+When using only ``METH_VARARGS``, the function should expect the Python-level
+parameters to be passed in as a tuple acceptable for parsing via
+:cfunc:`PyArg_ParseTuple`; more information on this function is provided below.
+
+The :const:`METH_KEYWORDS` bit may be set in the third field if keyword
+arguments should be passed to the function. In this case, the C function should
+accept a third ``PyObject *`` parameter which will be a dictionary of keywords.
+Use :cfunc:`PyArg_ParseTupleAndKeywords` to parse the arguments to such a
+function.
+
+The method table must be passed to the interpreter in the module's
+initialization function. The initialization function must be named
+:cfunc:`initname`, where *name* is the name of the module, and should be the
+only non-\ :keyword:`static` item defined in the module file::
+
+ PyMODINIT_FUNC
+ initspam(void)
+ {
+ (void) Py_InitModule("spam", SpamMethods);
+ }
+
+Note that PyMODINIT_FUNC declares the function as ``void`` return type,
+declares any special linkage declarations required by the platform, and for C++
+declares the function as ``extern "C"``.
+
+When the Python program imports module :mod:`spam` for the first time,
+:cfunc:`initspam` is called. (See below for comments about embedding Python.)
+It calls :cfunc:`Py_InitModule`, which creates a "module object" (which is
+inserted in the dictionary ``sys.modules`` under the key ``"spam"``), and
+inserts built-in function objects into the newly created module based upon the
+table (an array of :ctype:`PyMethodDef` structures) that was passed as its
+second argument. :cfunc:`Py_InitModule` returns a pointer to the module object
+that it creates (which is unused here). It may abort with a fatal error for
+certain errors, or return *NULL* if the module could not be initialized
+satisfactorily.
+
+When embedding Python, the :cfunc:`initspam` function is not called
+automatically unless there's an entry in the :cdata:`_PyImport_Inittab` table.
+The easiest way to handle this is to statically initialize your
+statically-linked modules by directly calling :cfunc:`initspam` after the call
+to :cfunc:`Py_Initialize`::
+
+ int
+ main(int argc, char *argv[])
+ {
+ /* Pass argv[0] to the Python interpreter */
+ Py_SetProgramName(argv[0]);
+
+ /* Initialize the Python interpreter. Required. */
+ Py_Initialize();
+
+ /* Add a static module */
+ initspam();
+
+An example may be found in the file :file:`Demo/embed/demo.c` in the Python
+source distribution.
+
+.. note::
+
+ Removing entries from ``sys.modules`` or importing compiled modules into
+ multiple interpreters within a process (or following a :cfunc:`fork` without an
+ intervening :cfunc:`exec`) can create problems for some extension modules.
+ Extension module authors should exercise caution when initializing internal data
+ structures. Note also that the :func:`reload` function can be used with
+ extension modules, and will call the module initialization function
+ (:cfunc:`initspam` in the example), but will not load the module again if it was
+ loaded from a dynamically loadable object file (:file:`.so` on Unix,
+ :file:`.dll` on Windows).
+
+A more substantial example module is included in the Python source distribution
+as :file:`Modules/xxmodule.c`. This file may be used as a template or simply
+read as an example. The :program:`modulator.py` script included in the source
+distribution or Windows install provides a simple graphical user interface for
+declaring the functions and objects which a module should implement, and can
+generate a template which can be filled in. The script lives in the
+:file:`Tools/modulator/` directory; see the :file:`README` file there for more
+information.
+
+
+.. _compilation:
+
+Compilation and Linkage
+=======================
+
+There are two more things to do before you can use your new extension: compiling
+and linking it with the Python system. If you use dynamic loading, the details
+may depend on the style of dynamic loading your system uses; see the chapters
+about building extension modules (chapter :ref:`building`) and additional
+information that pertains only to building on Windows (chapter
+:ref:`building-on-windows`) for more information about this.
+
+If you can't use dynamic loading, or if you want to make your module a permanent
+part of the Python interpreter, you will have to change the configuration setup
+and rebuild the interpreter. Luckily, this is very simple on Unix: just place
+your file (:file:`spammodule.c` for example) in the :file:`Modules/` directory
+of an unpacked source distribution, add a line to the file
+:file:`Modules/Setup.local` describing your file::
+
+ spam spammodule.o
+
+and rebuild the interpreter by running :program:`make` in the toplevel
+directory. You can also run :program:`make` in the :file:`Modules/`
+subdirectory, but then you must first rebuild :file:`Makefile` there by running
+':program:`make` Makefile'. (This is necessary each time you change the
+:file:`Setup` file.)
+
+If your module requires additional libraries to link with, these can be listed
+on the line in the configuration file as well, for instance::
+
+ spam spammodule.o -lX11
+
+
+.. _callingpython:
+
+Calling Python Functions from C
+===============================
+
+So far we have concentrated on making C functions callable from Python. The
+reverse is also useful: calling Python functions from C. This is especially the
+case for libraries that support so-called "callback" functions. If a C
+interface makes use of callbacks, the equivalent Python often needs to provide a
+callback mechanism to the Python programmer; the implementation will require
+calling the Python callback functions from a C callback. Other uses are also
+imaginable.
+
+Fortunately, the Python interpreter is easily called recursively, and there is a
+standard interface to call a Python function. (I won't dwell on how to call the
+Python parser with a particular string as input --- if you're interested, have a
+look at the implementation of the :option:`-c` command line option in
+:file:`Python/pythonmain.c` from the Python source code.)
+
+Calling a Python function is easy. First, the Python program must somehow pass
+you the Python function object. You should provide a function (or some other
+interface) to do this. When this function is called, save a pointer to the
+Python function object (be careful to :cfunc:`Py_INCREF` it!) in a global
+variable --- or wherever you see fit. For example, the following function might
+be part of a module definition::
+
+ static PyObject *my_callback = NULL;
+
+ static PyObject *
+ my_set_callback(PyObject *dummy, PyObject *args)
+ {
+ PyObject *result = NULL;
+ PyObject *temp;
+
+ if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {
+ if (!PyCallable_Check(temp)) {
+ PyErr_SetString(PyExc_TypeError, "parameter must be callable");
+ return NULL;
+ }
+ Py_XINCREF(temp); /* Add a reference to new callback */
+ Py_XDECREF(my_callback); /* Dispose of previous callback */
+ my_callback = temp; /* Remember new callback */
+ /* Boilerplate to return "None" */
+ Py_INCREF(Py_None);
+ result = Py_None;
+ }
+ return result;
+ }
+
+This function must be registered with the interpreter using the
+:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`. The
+:cfunc:`PyArg_ParseTuple` function and its arguments are documented in section
+:ref:`parsetuple`.
+
+The macros :cfunc:`Py_XINCREF` and :cfunc:`Py_XDECREF` increment/decrement the
+reference count of an object and are safe in the presence of *NULL* pointers
+(but note that *temp* will not be *NULL* in this context). More info on them
+in section :ref:`refcounts`.
+
+.. index:: single: PyEval_CallObject()
+
+Later, when it is time to call the function, you call the C function
+:cfunc:`PyEval_CallObject`. This function has two arguments, both pointers to
+arbitrary Python objects: the Python function, and the argument list. The
+argument list must always be a tuple object, whose length is the number of
+arguments. To call the Python function with no arguments, pass an empty tuple;
+to call it with one argument, pass a singleton tuple. :cfunc:`Py_BuildValue`
+returns a tuple when its format string consists of zero or more format codes
+between parentheses. For example::
+
+ int arg;
+ PyObject *arglist;
+ PyObject *result;
+ ...
+ arg = 123;
+ ...
+ /* Time to call the callback */
+ arglist = Py_BuildValue("(i)", arg);
+ result = PyEval_CallObject(my_callback, arglist);
+ Py_DECREF(arglist);
+
+:cfunc:`PyEval_CallObject` returns a Python object pointer: this is the return
+value of the Python function. :cfunc:`PyEval_CallObject` is
+"reference-count-neutral" with respect to its arguments. In the example a new
+tuple was created to serve as the argument list, which is :cfunc:`Py_DECREF`\
+-ed immediately after the call.
+
+The return value of :cfunc:`PyEval_CallObject` is "new": either it is a brand
+new object, or it is an existing object whose reference count has been
+incremented. So, unless you want to save it in a global variable, you should
+somehow :cfunc:`Py_DECREF` the result, even (especially!) if you are not
+interested in its value.
+
+Before you do this, however, it is important to check that the return value
+isn't *NULL*. If it is, the Python function terminated by raising an exception.
+If the C code that called :cfunc:`PyEval_CallObject` is called from Python, it
+should now return an error indication to its Python caller, so the interpreter
+can print a stack trace, or the calling Python code can handle the exception.
+If this is not possible or desirable, the exception should be cleared by calling
+:cfunc:`PyErr_Clear`. For example::
+
+ if (result == NULL)
+ return NULL; /* Pass error back */
+ ...use result...
+ Py_DECREF(result);
+
+Depending on the desired interface to the Python callback function, you may also
+have to provide an argument list to :cfunc:`PyEval_CallObject`. In some cases
+the argument list is also provided by the Python program, through the same
+interface that specified the callback function. It can then be saved and used
+in the same manner as the function object. In other cases, you may have to
+construct a new tuple to pass as the argument list. The simplest way to do this
+is to call :cfunc:`Py_BuildValue`. For example, if you want to pass an integral
+event code, you might use the following code::
+
+ PyObject *arglist;
+ ...
+ arglist = Py_BuildValue("(l)", eventcode);
+ result = PyEval_CallObject(my_callback, arglist);
+ Py_DECREF(arglist);
+ if (result == NULL)
+ return NULL; /* Pass error back */
+ /* Here maybe use the result */
+ Py_DECREF(result);
+
+Note the placement of ``Py_DECREF(arglist)`` immediately after the call, before
+the error check! Also note that strictly spoken this code is not complete:
+:cfunc:`Py_BuildValue` may run out of memory, and this should be checked.
+
+
+.. _parsetuple:
+
+Extracting Parameters in Extension Functions
+============================================
+
+.. index:: single: PyArg_ParseTuple()
+
+The :cfunc:`PyArg_ParseTuple` function is declared as follows::
+
+ int PyArg_ParseTuple(PyObject *arg, char *format, ...);
+
+The *arg* argument must be a tuple object containing an argument list passed
+from Python to a C function. The *format* argument must be a format string,
+whose syntax is explained in :ref:`arg-parsing` in the Python/C API Reference
+Manual. The remaining arguments must be addresses of variables whose type is
+determined by the format string.
+
+Note that while :cfunc:`PyArg_ParseTuple` checks that the Python arguments have
+the required types, it cannot check the validity of the addresses of C variables
+passed to the call: if you make mistakes there, your code will probably crash or
+at least overwrite random bits in memory. So be careful!
+
+Note that any Python object references which are provided to the caller are
+*borrowed* references; do not decrement their reference count!
+
+Some example calls::
+
+ int ok;
+ int i, j;
+ long k, l;
+ const char *s;
+ int size;
+
+ ok = PyArg_ParseTuple(args, ""); /* No arguments */
+ /* Python call: f() */
+
+::
+
+ ok = PyArg_ParseTuple(args, "s", &s); /* A string */
+ /* Possible Python call: f('whoops!') */
+
+::
+
+ ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */
+ /* Possible Python call: f(1, 2, 'three') */
+
+::
+
+ ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
+ /* A pair of ints and a string, whose size is also returned */
+ /* Possible Python call: f((1, 2), 'three') */
+
+::
+
+ {
+ const char *file;
+ const char *mode = "r";
+ int bufsize = 0;
+ ok = PyArg_ParseTuple(args, "s|si", &file, &mode, &bufsize);
+ /* A string, and optionally another string and an integer */
+ /* Possible Python calls:
+ f('spam')
+ f('spam', 'w')
+ f('spam', 'wb', 100000) */
+ }
+
+::
+
+ {
+ int left, top, right, bottom, h, v;
+ ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
+ &left, &top, &right, &bottom, &h, &v);
+ /* A rectangle and a point */
+ /* Possible Python call:
+ f(((0, 0), (400, 300)), (10, 10)) */
+ }
+
+::
+
+ {
+ Py_complex c;
+ ok = PyArg_ParseTuple(args, "D:myfunction", &c);
+ /* a complex, also providing a function name for errors */
+ /* Possible Python call: myfunction(1+2j) */
+ }
+
+
+.. _parsetupleandkeywords:
+
+Keyword Parameters for Extension Functions
+==========================================
+
+.. index:: single: PyArg_ParseTupleAndKeywords()
+
+The :cfunc:`PyArg_ParseTupleAndKeywords` function is declared as follows::
+
+ int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
+ char *format, char *kwlist[], ...);
+
+The *arg* and *format* parameters are identical to those of the
+:cfunc:`PyArg_ParseTuple` function. The *kwdict* parameter is the dictionary of
+keywords received as the third parameter from the Python runtime. The *kwlist*
+parameter is a *NULL*-terminated list of strings which identify the parameters;
+the names are matched with the type information from *format* from left to
+right. On success, :cfunc:`PyArg_ParseTupleAndKeywords` returns true, otherwise
+it returns false and raises an appropriate exception.
+
+.. note::
+
+ Nested tuples cannot be parsed when using keyword arguments! Keyword parameters
+ passed in which are not present in the *kwlist* will cause :exc:`TypeError` to
+ be raised.
+
+.. index:: single: Philbrick, Geoff
+
+Here is an example module which uses keywords, based on an example by Geoff
+Philbrick (philbrick@hks.com):
+
+.. %
+
+::
+
+ #include "Python.h"
+
+ static PyObject *
+ keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
+ {
+ int voltage;
+ char *state = "a stiff";
+ char *action = "voom";
+ char *type = "Norwegian Blue";
+
+ static char *kwlist[] = {"voltage", "state", "action", "type", NULL};
+
+ if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist,
+ &voltage, &state, &action, &type))
+ return NULL;
+
+ printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
+ action, voltage);
+ printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);
+
+ Py_INCREF(Py_None);
+
+ return Py_None;
+ }
+
+ static PyMethodDef keywdarg_methods[] = {
+ /* The cast of the function is necessary since PyCFunction values
+ * only take two PyObject* parameters, and keywdarg_parrot() takes
+ * three.
+ */
+ {"parrot", (PyCFunction)keywdarg_parrot, METH_VARARGS | METH_KEYWORDS,
+ "Print a lovely skit to standard output."},
+ {NULL, NULL, 0, NULL} /* sentinel */
+ };
+
+::
+
+ void
+ initkeywdarg(void)
+ {
+ /* Create the module and add the functions */
+ Py_InitModule("keywdarg", keywdarg_methods);
+ }
+
+
+.. _buildvalue:
+
+Building Arbitrary Values
+=========================
+
+This function is the counterpart to :cfunc:`PyArg_ParseTuple`. It is declared
+as follows::
+
+ PyObject *Py_BuildValue(char *format, ...);
+
+It recognizes a set of format units similar to the ones recognized by
+:cfunc:`PyArg_ParseTuple`, but the arguments (which are input to the function,
+not output) must not be pointers, just values. It returns a new Python object,
+suitable for returning from a C function called from Python.
+
+One difference with :cfunc:`PyArg_ParseTuple`: while the latter requires its
+first argument to be a tuple (since Python argument lists are always represented
+as tuples internally), :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.
+
+Examples (to the left the call, to the right the resulting Python value)::
+
+ Py_BuildValue("") None
+ Py_BuildValue("i", 123) 123
+ Py_BuildValue("iii", 123, 456, 789) (123, 456, 789)
+ Py_BuildValue("s", "hello") 'hello'
+ Py_BuildValue("ss", "hello", "world") ('hello', 'world')
+ Py_BuildValue("s#", "hello", 4) 'hell'
+ Py_BuildValue("()") ()
+ Py_BuildValue("(i)", 123) (123,)
+ Py_BuildValue("(ii)", 123, 456) (123, 456)
+ Py_BuildValue("(i,i)", 123, 456) (123, 456)
+ Py_BuildValue("[i,i]", 123, 456) [123, 456]
+ Py_BuildValue("{s:i,s:i}",
+ "abc", 123, "def", 456) {'abc': 123, 'def': 456}
+ Py_BuildValue("((ii)(ii)) (ii)",
+ 1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6))
+
+
+.. _refcounts:
+
+Reference Counts
+================
+
+In languages like C or C++, the programmer is responsible for dynamic allocation
+and deallocation of memory on the heap. In C, this is done using the functions
+:cfunc:`malloc` and :cfunc:`free`. In C++, the operators :keyword:`new` and
+:keyword:`delete` are used with essentially the same meaning and we'll restrict
+the following discussion to the C case.
+
+Every block of memory allocated with :cfunc:`malloc` should eventually be
+returned to the pool of available memory by exactly one call to :cfunc:`free`.
+It is important to call :cfunc:`free` at the right time. If a block's address
+is forgotten but :cfunc:`free` is not called for it, the memory it occupies
+cannot be reused until the program terminates. This is called a :dfn:`memory
+leak`. On the other hand, if a program calls :cfunc:`free` for a block and then
+continues to use the block, it creates a conflict with re-use of the block
+through another :cfunc:`malloc` call. This is called :dfn:`using freed memory`.
+It has the same bad consequences as referencing uninitialized data --- core
+dumps, wrong results, mysterious crashes.
+
+Common causes of memory leaks are unusual paths through the code. For instance,
+a function may allocate a block of memory, do some calculation, and then free
+the block again. Now a change in the requirements for the function may add a
+test to the calculation that detects an error condition and can return
+prematurely from the function. It's easy to forget to free the allocated memory
+block when taking this premature exit, especially when it is added later to the
+code. Such leaks, once introduced, often go undetected for a long time: the
+error exit is taken only in a small fraction of all calls, and most modern
+machines have plenty of virtual memory, so the leak only becomes apparent in a
+long-running process that uses the leaking function frequently. Therefore, it's
+important to prevent leaks from happening by having a coding convention or
+strategy that minimizes this kind of errors.
+
+Since Python makes heavy use of :cfunc:`malloc` and :cfunc:`free`, it needs a
+strategy to avoid memory leaks as well as the use of freed memory. The chosen
+method is called :dfn:`reference counting`. The principle is simple: every
+object contains a counter, which is incremented when a reference to the object
+is stored somewhere, and which is decremented when a reference to it is deleted.
+When the counter reaches zero, the last reference to the object has been deleted
+and the object is freed.
+
+An alternative strategy is called :dfn:`automatic garbage collection`.
+(Sometimes, reference counting is also referred to as a garbage collection
+strategy, hence my use of "automatic" to distinguish the two.) The big
+advantage of automatic garbage collection is that the user doesn't need to call
+:cfunc:`free` explicitly. (Another claimed advantage is an improvement in speed
+or memory usage --- this is no hard fact however.) The disadvantage is that for
+C, there is no truly portable automatic garbage collector, while reference
+counting can be implemented portably (as long as the functions :cfunc:`malloc`
+and :cfunc:`free` are available --- which the C Standard guarantees). Maybe some
+day a sufficiently portable automatic garbage collector will be available for C.
+Until then, we'll have to live with reference counts.
+
+While Python uses the traditional reference counting implementation, it also
+offers a cycle detector that works to detect reference cycles. This allows
+applications to not worry about creating direct or indirect circular references;
+these are the weakness of garbage collection implemented using only reference
+counting. Reference cycles consist of objects which contain (possibly indirect)
+references to themselves, so that each object in the cycle has a reference count
+which is non-zero. Typical reference counting implementations are not able to
+reclaim the memory belonging to any objects in a reference cycle, or referenced
+from the objects in the cycle, even though there are no further references to
+the cycle itself.
+
+The cycle detector is able to detect garbage cycles and can reclaim them so long
+as there are no finalizers implemented in Python (:meth:`__del__` methods).
+When there are such finalizers, the detector exposes the cycles through the
+:mod:`gc` module (specifically, the
+``garbage`` variable in that module). The :mod:`gc` module also exposes a way
+to run the detector (the :func:`collect` function), as well as configuration
+interfaces and the ability to disable the detector at runtime. The cycle
+detector is considered an optional component; though it is included by default,
+it can be disabled at build time using the :option:`--without-cycle-gc` option
+to the :program:`configure` script on Unix platforms (including Mac OS X) or by
+removing the definition of ``WITH_CYCLE_GC`` in the :file:`pyconfig.h` header on
+other platforms. If the cycle detector is disabled in this way, the :mod:`gc`
+module will not be available.
+
+
+.. _refcountsinpython:
+
+Reference Counting in Python
+----------------------------
+
+There are two macros, ``Py_INCREF(x)`` and ``Py_DECREF(x)``, which handle the
+incrementing and decrementing of the reference count. :cfunc:`Py_DECREF` also
+frees the object when the count reaches zero. For flexibility, it doesn't call
+:cfunc:`free` directly --- rather, it makes a call through a function pointer in
+the object's :dfn:`type object`. For this purpose (and others), every object
+also contains a pointer to its type object.
+
+The big question now remains: when to use ``Py_INCREF(x)`` and ``Py_DECREF(x)``?
+Let's first introduce some terms. Nobody "owns" an object; however, you can
+:dfn:`own a reference` to an object. An object's reference count is now defined
+as the number of owned references to it. The owner of a reference is
+responsible for calling :cfunc:`Py_DECREF` when the reference is no longer
+needed. Ownership of a reference can be transferred. There are three ways to
+dispose of an owned reference: pass it on, store it, or call :cfunc:`Py_DECREF`.
+Forgetting to dispose of an owned reference creates a memory leak.
+
+It is also possible to :dfn:`borrow` [#]_ a reference to an object. The
+borrower of a reference should not call :cfunc:`Py_DECREF`. The borrower must
+not hold on to the object longer than the owner from which it was borrowed.
+Using a borrowed reference after the owner has disposed of it risks using freed
+memory and should be avoided completely. [#]_
+
+The advantage of borrowing over owning a reference is that you don't need to
+take care of disposing of the reference on all possible paths through the code
+--- in other words, with a borrowed reference you don't run the risk of leaking
+when a premature exit is taken. The disadvantage of borrowing over leaking is
+that there are some subtle situations where in seemingly correct code a borrowed
+reference can be used after the owner from which it was borrowed has in fact
+disposed of it.
+
+A borrowed reference can be changed into an owned reference by calling
+:cfunc:`Py_INCREF`. This does not affect the status of the owner from which the
+reference was borrowed --- it creates a new owned reference, and gives full
+owner responsibilities (the new owner must dispose of the reference properly, as
+well as the previous owner).
+
+
+.. _ownershiprules:
+
+Ownership Rules
+---------------
+
+Whenever an object reference is passed into or out of a function, it is part of
+the function's interface specification whether ownership is transferred with the
+reference or not.
+
+Most functions that return a reference to an object pass on ownership with the
+reference. In particular, all functions whose function it is to create a new
+object, such as :cfunc:`PyInt_FromLong` and :cfunc:`Py_BuildValue`, pass
+ownership to the receiver. Even if the object is not actually new, you still
+receive ownership of a new reference to that object. For instance,
+:cfunc:`PyInt_FromLong` maintains a cache of popular values and can return a
+reference to a cached item.
+
+Many functions that extract objects from other objects also transfer ownership
+with the reference, for instance :cfunc:`PyObject_GetAttrString`. The picture
+is less clear, here, however, since a few common routines are exceptions:
+:cfunc:`PyTuple_GetItem`, :cfunc:`PyList_GetItem`, :cfunc:`PyDict_GetItem`, and
+:cfunc:`PyDict_GetItemString` all return references that you borrow from the
+tuple, list or dictionary.
+
+The function :cfunc:`PyImport_AddModule` also returns a borrowed reference, even
+though it may actually create the object it returns: this is possible because an
+owned reference to the object is stored in ``sys.modules``.
+
+When you pass an object reference into another function, in general, the
+function borrows the reference from you --- if it needs to store it, it will use
+:cfunc:`Py_INCREF` to become an independent owner. There are exactly two
+important exceptions to this rule: :cfunc:`PyTuple_SetItem` and
+:cfunc:`PyList_SetItem`. These functions take over ownership of the item passed
+to them --- even if they fail! (Note that :cfunc:`PyDict_SetItem` and friends
+don't take over ownership --- they are "normal.")
+
+When a C function is called from Python, it borrows references to its arguments
+from the caller. The caller owns a reference to the object, so the borrowed
+reference's lifetime is guaranteed until the function returns. Only when such a
+borrowed reference must be stored or passed on, it must be turned into an owned
+reference by calling :cfunc:`Py_INCREF`.
+
+The object reference returned from a C function that is called from Python must
+be an owned reference --- ownership is transferred from the function to its
+caller.
+
+
+.. _thinice:
+
+Thin Ice
+--------
+
+There are a few situations where seemingly harmless use of a borrowed reference
+can lead to problems. These all have to do with implicit invocations of the
+interpreter, which can cause the owner of a reference to dispose of it.
+
+The first and most important case to know about is using :cfunc:`Py_DECREF` on
+an unrelated object while borrowing a reference to a list item. For instance::
+
+ void
+ bug(PyObject *list)
+ {
+ PyObject *item = PyList_GetItem(list, 0);
+
+ PyList_SetItem(list, 1, PyInt_FromLong(0L));
+ PyObject_Print(item, stdout, 0); /* BUG! */
+ }
+
+This function first borrows a reference to ``list[0]``, then replaces
+``list[1]`` with the value ``0``, and finally prints the borrowed reference.
+Looks harmless, right? But it's not!
+
+Let's follow the control flow into :cfunc:`PyList_SetItem`. The list owns
+references to all its items, so when item 1 is replaced, it has to dispose of
+the original item 1. Now let's suppose the original item 1 was an instance of a
+user-defined class, and let's further suppose that the class defined a
+:meth:`__del__` method. If this class instance has a reference count of 1,
+disposing of it will call its :meth:`__del__` method.
+
+Since it is written in Python, the :meth:`__del__` method can execute arbitrary
+Python code. Could it perhaps do something to invalidate the reference to
+``item`` in :cfunc:`bug`? You bet! Assuming that the list passed into
+:cfunc:`bug` is accessible to the :meth:`__del__` method, it could execute a
+statement to the effect of ``del list[0]``, and assuming this was the last
+reference to that object, it would free the memory associated with it, thereby
+invalidating ``item``.
+
+The solution, once you know the source of the problem, is easy: temporarily
+increment the reference count. The correct version of the function reads::
+
+ void
+ no_bug(PyObject *list)
+ {
+ PyObject *item = PyList_GetItem(list, 0);
+
+ Py_INCREF(item);
+ PyList_SetItem(list, 1, PyInt_FromLong(0L));
+ PyObject_Print(item, stdout, 0);
+ Py_DECREF(item);
+ }
+
+This is a true story. An older version of Python contained variants of this bug
+and someone spent a considerable amount of time in a C debugger to figure out
+why his :meth:`__del__` methods would fail...
+
+The second case of problems with a borrowed reference is a variant involving
+threads. Normally, multiple threads in the Python interpreter can't get in each
+other's way, because there is a global lock protecting Python's entire object
+space. However, it is possible to temporarily release this lock using the macro
+:cmacro:`Py_BEGIN_ALLOW_THREADS`, and to re-acquire it using
+:cmacro:`Py_END_ALLOW_THREADS`. This is common around blocking I/O calls, to
+let other threads use the processor while waiting for the I/O to complete.
+Obviously, the following function has the same problem as the previous one::
+
+ void
+ bug(PyObject *list)
+ {
+ PyObject *item = PyList_GetItem(list, 0);
+ Py_BEGIN_ALLOW_THREADS
+ ...some blocking I/O call...
+ Py_END_ALLOW_THREADS
+ PyObject_Print(item, stdout, 0); /* BUG! */
+ }
+
+
+.. _nullpointers:
+
+NULL Pointers
+-------------
+
+In general, functions that take object references as arguments do not expect you
+to pass them *NULL* pointers, and will dump core (or cause later core dumps) if
+you do so. Functions that return object references generally return *NULL* only
+to indicate that an exception occurred. The reason for not testing for *NULL*
+arguments is that functions often pass the objects they receive on to other
+function --- if each function were to test for *NULL*, there would be a lot of
+redundant tests and the code would run more slowly.
+
+It is better to test for *NULL* only at the "source:" when a pointer that may be
+*NULL* is received, for example, from :cfunc:`malloc` or from a function that
+may raise an exception.
+
+The macros :cfunc:`Py_INCREF` and :cfunc:`Py_DECREF` do not check for *NULL*
+pointers --- however, their variants :cfunc:`Py_XINCREF` and :cfunc:`Py_XDECREF`
+do.
+
+The macros for checking for a particular object type (``Pytype_Check()``) don't
+check for *NULL* pointers --- again, there is much code that calls several of
+these in a row to test an object against various different expected types, and
+this would generate redundant tests. There are no variants with *NULL*
+checking.
+
+The C function calling mechanism guarantees that the argument list passed to C
+functions (``args`` in the examples) is never *NULL* --- in fact it guarantees
+that it is always a tuple. [#]_
+
+It is a severe error to ever let a *NULL* pointer "escape" to the Python user.
+
+.. % Frank Stajano:
+.. % A pedagogically buggy example, along the lines of the previous listing,
+.. % would be helpful here -- showing in more concrete terms what sort of
+.. % actions could cause the problem. I can't very well imagine it from the
+.. % description.
+
+
+.. _cplusplus:
+
+Writing Extensions in C++
+=========================
+
+It is possible to write extension modules in C++. Some restrictions apply. If
+the main program (the Python interpreter) is compiled and linked by the C
+compiler, global or static objects with constructors cannot be used. This is
+not a problem if the main program is linked by the C++ compiler. Functions that
+will be called by the Python interpreter (in particular, module initialization
+functions) have to be declared using ``extern "C"``. It is unnecessary to
+enclose the Python header files in ``extern "C" {...}`` --- they use this form
+already if the symbol ``__cplusplus`` is defined (all recent C++ compilers
+define this symbol).
+
+
+.. _using-cobjects:
+
+Providing a C API for an Extension Module
+=========================================
+
+.. sectionauthor:: Konrad Hinsen <hinsen@cnrs-orleans.fr>
+
+
+Many extension modules just provide new functions and types to be used from
+Python, but sometimes the code in an extension module can be useful for other
+extension modules. For example, an extension module could implement a type
+"collection" which works like lists without order. Just like the standard Python
+list type has a C API which permits extension modules to create and manipulate
+lists, this new collection type should have a set of C functions for direct
+manipulation from other extension modules.
+
+At first sight this seems easy: just write the functions (without declaring them
+:keyword:`static`, of course), provide an appropriate header file, and document
+the C API. And in fact this would work if all extension modules were always
+linked statically with the Python interpreter. When modules are used as shared
+libraries, however, the symbols defined in one module may not be visible to
+another module. The details of visibility depend on the operating system; some
+systems use one global namespace for the Python interpreter and all extension
+modules (Windows, for example), whereas others require an explicit list of
+imported symbols at module link time (AIX is one example), or offer a choice of
+different strategies (most Unices). And even if symbols are globally visible,
+the module whose functions one wishes to call might not have been loaded yet!
+
+Portability therefore requires not to make any assumptions about symbol
+visibility. This means that all symbols in extension modules should be declared
+:keyword:`static`, except for the module's initialization function, in order to
+avoid name clashes with other extension modules (as discussed in section
+:ref:`methodtable`). And it means that symbols that *should* be accessible from
+other extension modules must be exported in a different way.
+
+Python provides a special mechanism to pass C-level information (pointers) from
+one extension module to another one: CObjects. A CObject is a Python data type
+which stores a pointer (:ctype:`void \*`). CObjects can only be created and
+accessed via their C API, but they can be passed around like any other Python
+object. In particular, they can be assigned to a name in an extension module's
+namespace. Other extension modules can then import this module, retrieve the
+value of this name, and then retrieve the pointer from the CObject.
+
+There are many ways in which CObjects can be used to export the C API of an
+extension module. Each name could get its own CObject, or all C API pointers
+could be stored in an array whose address is published in a CObject. And the
+various tasks of storing and retrieving the pointers can be distributed in
+different ways between the module providing the code and the client modules.
+
+The following example demonstrates an approach that puts most of the burden on
+the writer of the exporting module, which is appropriate for commonly used
+library modules. It stores all C API pointers (just one in the example!) in an
+array of :ctype:`void` pointers which becomes the value of a CObject. The header
+file corresponding to the module provides a macro that takes care of importing
+the module and retrieving its C API pointers; client modules only have to call
+this macro before accessing the C API.
+
+The exporting module is a modification of the :mod:`spam` module from section
+:ref:`extending-simpleexample`. The function :func:`spam.system` does not call
+the C library function :cfunc:`system` directly, but a function
+:cfunc:`PySpam_System`, which would of course do something more complicated in
+reality (such as adding "spam" to every command). This function
+:cfunc:`PySpam_System` is also exported to other extension modules.
+
+The function :cfunc:`PySpam_System` is a plain C function, declared
+:keyword:`static` like everything else::
+
+ static int
+ PySpam_System(const char *command)
+ {
+ return system(command);
+ }
+
+The function :cfunc:`spam_system` is modified in a trivial way::
+
+ static PyObject *
+ spam_system(PyObject *self, PyObject *args)
+ {
+ const char *command;
+ int sts;
+
+ if (!PyArg_ParseTuple(args, "s", &command))
+ return NULL;
+ sts = PySpam_System(command);
+ return Py_BuildValue("i", sts);
+ }
+
+In the beginning of the module, right after the line ::
+
+ #include "Python.h"
+
+two more lines must be added::
+
+ #define SPAM_MODULE
+ #include "spammodule.h"
+
+The ``#define`` is used to tell the header file that it is being included in the
+exporting module, not a client module. Finally, the module's initialization
+function must take care of initializing the C API pointer array::
+
+ PyMODINIT_FUNC
+ initspam(void)
+ {
+ PyObject *m;
+ static void *PySpam_API[PySpam_API_pointers];
+ PyObject *c_api_object;
+
+ m = Py_InitModule("spam", SpamMethods);
+ if (m == NULL)
+ return;
+
+ /* Initialize the C API pointer array */
+ PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;
+
+ /* Create a CObject containing the API pointer array's address */
+ c_api_object = PyCObject_FromVoidPtr((void *)PySpam_API, NULL);
+
+ if (c_api_object != NULL)
+ PyModule_AddObject(m, "_C_API", c_api_object);
+ }
+
+Note that ``PySpam_API`` is declared :keyword:`static`; otherwise the pointer
+array would disappear when :func:`initspam` terminates!
+
+The bulk of the work is in the header file :file:`spammodule.h`, which looks
+like this::
+
+ #ifndef Py_SPAMMODULE_H
+ #define Py_SPAMMODULE_H
+ #ifdef __cplusplus
+ extern "C" {
+ #endif
+
+ /* Header file for spammodule */
+
+ /* C API functions */
+ #define PySpam_System_NUM 0
+ #define PySpam_System_RETURN int
+ #define PySpam_System_PROTO (const char *command)
+
+ /* Total number of C API pointers */
+ #define PySpam_API_pointers 1
+
+
+ #ifdef SPAM_MODULE
+ /* This section is used when compiling spammodule.c */
+
+ static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;
+
+ #else
+ /* This section is used in modules that use spammodule's API */
+
+ static void **PySpam_API;
+
+ #define PySpam_System \
+ (*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])
+
+ /* Return -1 and set exception on error, 0 on success. */
+ static int
+ import_spam(void)
+ {
+ PyObject *module = PyImport_ImportModule("spam");
+
+ if (module != NULL) {
+ PyObject *c_api_object = PyObject_GetAttrString(module, "_C_API");
+ if (c_api_object == NULL)
+ return -1;
+ if (PyCObject_Check(c_api_object))
+ PySpam_API = (void **)PyCObject_AsVoidPtr(c_api_object);
+ Py_DECREF(c_api_object);
+ }
+ return 0;
+ }
+
+ #endif
+
+ #ifdef __cplusplus
+ }
+ #endif
+
+ #endif /* !defined(Py_SPAMMODULE_H) */
+
+All that a client module must do in order to have access to the function
+:cfunc:`PySpam_System` is to call the function (or rather macro)
+:cfunc:`import_spam` in its initialization function::
+
+ PyMODINIT_FUNC
+ initclient(void)
+ {
+ PyObject *m;
+
+ m = Py_InitModule("client", ClientMethods);
+ if (m == NULL)
+ return;
+ if (import_spam() < 0)
+ return;
+ /* additional initialization can happen here */
+ }
+
+The main disadvantage of this approach is that the file :file:`spammodule.h` is
+rather complicated. However, the basic structure is the same for each function
+that is exported, so it has to be learned only once.
+
+Finally it should be mentioned that CObjects offer additional functionality,
+which is especially useful for memory allocation and deallocation of the pointer
+stored in a CObject. The details are described in the Python/C API Reference
+Manual in the section :ref:`cobjects` and in the implementation of CObjects (files
+:file:`Include/cobject.h` and :file:`Objects/cobject.c` in the Python source
+code distribution).
+
+.. rubric:: Footnotes
+
+.. [#] An interface for this function already exists in the standard module :mod:`os`
+ --- it was chosen as a simple and straightforward example.
+
+.. [#] The metaphor of "borrowing" a reference is not completely correct: the owner
+ still has a copy of the reference.
+
+.. [#] Checking that the reference count is at least 1 **does not work** --- the
+ reference count itself could be in freed memory and may thus be reused for
+ another object!
+
+.. [#] These guarantees don't hold when you use the "old" style calling convention ---
+ this is still found in much existing code.
+
--- /dev/null
+.. _extending-index:
+
+##################################################
+ Extending and Embedding the Python Interpreter
+##################################################
+
+:Release: |version|
+:Date: |today|
+
+This document describes how to write modules in C or C++ to extend the Python
+interpreter with new modules. Those modules can define new functions but also
+new object types and their methods. The document also describes how to embed
+the Python interpreter in another application, for use as an extension language.
+Finally, it shows how to compile and link extension modules so that they can be
+loaded dynamically (at run time) into the interpreter, if the underlying
+operating system supports this feature.
+
+This document assumes basic knowledge about Python. For an informal
+introduction to the language, see :ref:`tutorial-index`. :ref:`reference-index`
+gives a more formal definition of the language. :ref:`library-index` documents
+the existing object types, functions and modules (both built-in and written in
+Python) that give the language its wide application range.
+
+For a detailed description of the whole Python/C API, see the separate
+:ref:`c-api-index`.
+
+.. toctree::
+ :maxdepth: 2
+
+ extending.rst
+ newtypes.rst
+ building.rst
+ windows.rst
+ embedding.rst
--- /dev/null
+.. highlightlang:: c
+
+
+.. _defining-new-types:
+
+******************
+Defining New Types
+******************
+
+.. sectionauthor:: Michael Hudson <mwh@python.net>
+.. sectionauthor:: Dave Kuhlman <dkuhlman@rexx.com>
+.. sectionauthor:: Jim Fulton <jim@zope.com>
+
+
+As mentioned in the last chapter, Python allows the writer of an extension
+module to define new types that can be manipulated from Python code, much like
+strings and lists in core Python.
+
+This is not hard; the code for all extension types follows a pattern, but there
+are some details that you need to understand before you can get started.
+
+.. note::
+
+ The way new types are defined changed dramatically (and for the better) in
+ Python 2.2. This document documents how to define new types for Python 2.2 and
+ later. If you need to support older versions of Python, you will need to refer
+ to `older versions of this documentation
+ <http://www.python.org/doc/versions/>`_.
+
+
+.. _dnt-basics:
+
+The Basics
+==========
+
+The Python runtime sees all Python objects as variables of type
+:ctype:`PyObject\*`. A :ctype:`PyObject` is not a very magnificent object - it
+just contains the refcount and a pointer to the object's "type object". This is
+where the action is; the type object determines which (C) functions get called
+when, for instance, an attribute gets looked up on an object or it is multiplied
+by another object. These C functions are called "type methods" to distinguish
+them from things like ``[].append`` (which we call "object methods").
+
+So, if you want to define a new object type, you need to create a new type
+object.
+
+This sort of thing can only be explained by example, so here's a minimal, but
+complete, module that defines a new type:
+
+.. literalinclude:: ../includes/noddy.c
+
+
+Now that's quite a bit to take in at once, but hopefully bits will seem familiar
+from the last chapter.
+
+The first bit that will be new is::
+
+ typedef struct {
+ PyObject_HEAD
+ } noddy_NoddyObject;
+
+This is what a Noddy object will contain---in this case, nothing more than every
+Python object contains, namely a refcount and a pointer to a type object. These
+are the fields the ``PyObject_HEAD`` macro brings in. The reason for the macro
+is to standardize the layout and to enable special debugging fields in debug
+builds. Note that there is no semicolon after the ``PyObject_HEAD`` macro; one
+is included in the macro definition. Be wary of adding one by accident; it's
+easy to do from habit, and your compiler might not complain, but someone else's
+probably will! (On Windows, MSVC is known to call this an error and refuse to
+compile the code.)
+
+For contrast, let's take a look at the corresponding definition for standard
+Python integers::
+
+ typedef struct {
+ PyObject_HEAD
+ long ob_ival;
+ } PyIntObject;
+
+Moving on, we come to the crunch --- the type object. ::
+
+ static PyTypeObject noddy_NoddyType = {
+ PyObject_HEAD_INIT(NULL)
+ 0, /*ob_size*/
+ "noddy.Noddy", /*tp_name*/
+ sizeof(noddy_NoddyObject), /*tp_basicsize*/
+ 0, /*tp_itemsize*/
+ 0, /*tp_dealloc*/
+ 0, /*tp_print*/
+ 0, /*tp_getattr*/
+ 0, /*tp_setattr*/
+ 0, /*tp_compare*/
+ 0, /*tp_repr*/
+ 0, /*tp_as_number*/
+ 0, /*tp_as_sequence*/
+ 0, /*tp_as_mapping*/
+ 0, /*tp_hash */
+ 0, /*tp_call*/
+ 0, /*tp_str*/
+ 0, /*tp_getattro*/
+ 0, /*tp_setattro*/
+ 0, /*tp_as_buffer*/
+ Py_TPFLAGS_DEFAULT, /*tp_flags*/
+ "Noddy objects", /* tp_doc */
+ };
+
+Now if you go and look up the definition of :ctype:`PyTypeObject` in
+:file:`object.h` you'll see that it has many more fields that the definition
+above. The remaining fields will be filled with zeros by the C compiler, and
+it's common practice to not specify them explicitly unless you need them.
+
+This is so important that we're going to pick the top of it apart still
+further::
+
+ PyObject_HEAD_INIT(NULL)
+
+This line is a bit of a wart; what we'd like to write is::
+
+ PyObject_HEAD_INIT(&PyType_Type)
+
+as the type of a type object is "type", but this isn't strictly conforming C and
+some compilers complain. Fortunately, this member will be filled in for us by
+:cfunc:`PyType_Ready`. ::
+
+ 0, /* ob_size */
+
+The :attr:`ob_size` field of the header is not used; its presence in the type
+structure is a historical artifact that is maintained for binary compatibility
+with extension modules compiled for older versions of Python. Always set this
+field to zero. ::
+
+ "noddy.Noddy", /* tp_name */
+
+The name of our type. This will appear in the default textual representation of
+our objects and in some error messages, for example::
+
+ >>> "" + noddy.new_noddy()
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ TypeError: cannot add type "noddy.Noddy" to string
+
+Note that the name is a dotted name that includes both the module name and the
+name of the type within the module. The module in this case is :mod:`noddy` and
+the type is :class:`Noddy`, so we set the type name to :class:`noddy.Noddy`. ::
+
+ sizeof(noddy_NoddyObject), /* tp_basicsize */
+
+This is so that Python knows how much memory to allocate when you call
+:cfunc:`PyObject_New`.
+
+.. note::
+
+ If you want your type to be subclassable from Python, and your type has the same
+ :attr:`tp_basicsize` as its base type, you may have problems with multiple
+ inheritance. A Python subclass of your type will have to list your type first
+ in its :attr:`__bases__`, or else it will not be able to call your type's
+ :meth:`__new__` method without getting an error. You can avoid this problem by
+ ensuring that your type has a larger value for :attr:`tp_basicsize` than its
+ base type does. Most of the time, this will be true anyway, because either your
+ base type will be :class:`object`, or else you will be adding data members to
+ your base type, and therefore increasing its size.
+
+::
+
+ 0, /* tp_itemsize */
+
+This has to do with variable length objects like lists and strings. Ignore this
+for now.
+
+Skipping a number of type methods that we don't provide, we set the class flags
+to :const:`Py_TPFLAGS_DEFAULT`. ::
+
+ Py_TPFLAGS_DEFAULT, /*tp_flags*/
+
+All types should include this constant in their flags. It enables all of the
+members defined by the current version of Python.
+
+We provide a doc string for the type in :attr:`tp_doc`. ::
+
+ "Noddy objects", /* tp_doc */
+
+Now we get into the type methods, the things that make your objects different
+from the others. We aren't going to implement any of these in this version of
+the module. We'll expand this example later to have more interesting behavior.
+
+For now, all we want to be able to do is to create new :class:`Noddy` objects.
+To enable object creation, we have to provide a :attr:`tp_new` implementation.
+In this case, we can just use the default implementation provided by the API
+function :cfunc:`PyType_GenericNew`. We'd like to just assign this to the
+:attr:`tp_new` slot, but we can't, for portability sake, On some platforms or
+compilers, we can't statically initialize a structure member with a function
+defined in another C module, so, instead, we'll assign the :attr:`tp_new` slot
+in the module initialization function just before calling
+:cfunc:`PyType_Ready`::
+
+ noddy_NoddyType.tp_new = PyType_GenericNew;
+ if (PyType_Ready(&noddy_NoddyType) < 0)
+ return;
+
+All the other type methods are *NULL*, so we'll go over them later --- that's
+for a later section!
+
+Everything else in the file should be familiar, except for some code in
+:cfunc:`initnoddy`::
+
+ if (PyType_Ready(&noddy_NoddyType) < 0)
+ return;
+
+This initializes the :class:`Noddy` type, filing in a number of members,
+including :attr:`ob_type` that we initially set to *NULL*. ::
+
+ PyModule_AddObject(m, "Noddy", (PyObject *)&noddy_NoddyType);
+
+This adds the type to the module dictionary. This allows us to create
+:class:`Noddy` instances by calling the :class:`Noddy` class::
+
+ >>> import noddy
+ >>> mynoddy = noddy.Noddy()
+
+That's it! All that remains is to build it; put the above code in a file called
+:file:`noddy.c` and ::
+
+ from distutils.core import setup, Extension
+ setup(name="noddy", version="1.0",
+ ext_modules=[Extension("noddy", ["noddy.c"])])
+
+in a file called :file:`setup.py`; then typing ::
+
+ $ python setup.py build
+
+at a shell should produce a file :file:`noddy.so` in a subdirectory; move to
+that directory and fire up Python --- you should be able to ``import noddy`` and
+play around with Noddy objects.
+
+.. % $ <-- bow to font-lock ;-(
+
+That wasn't so hard, was it?
+
+Of course, the current Noddy type is pretty uninteresting. It has no data and
+doesn't do anything. It can't even be subclassed.
+
+
+Adding data and methods to the Basic example
+--------------------------------------------
+
+Let's expend the basic example to add some data and methods. Let's also make
+the type usable as a base class. We'll create a new module, :mod:`noddy2` that
+adds these capabilities:
+
+.. literalinclude:: ../includes/noddy2.c
+
+
+This version of the module has a number of changes.
+
+We've added an extra include::
+
+ #include "structmember.h"
+
+This include provides declarations that we use to handle attributes, as
+described a bit later.
+
+The name of the :class:`Noddy` object structure has been shortened to
+:class:`Noddy`. The type object name has been shortened to :class:`NoddyType`.
+
+The :class:`Noddy` type now has three data attributes, *first*, *last*, and
+*number*. The *first* and *last* variables are Python strings containing first
+and last names. The *number* attribute is an integer.
+
+The object structure is updated accordingly::
+
+ typedef struct {
+ PyObject_HEAD
+ PyObject *first;
+ PyObject *last;
+ int number;
+ } Noddy;
+
+Because we now have data to manage, we have to be more careful about object
+allocation and deallocation. At a minimum, we need a deallocation method::
+
+ static void
+ Noddy_dealloc(Noddy* self)
+ {
+ Py_XDECREF(self->first);
+ Py_XDECREF(self->last);
+ self->ob_type->tp_free((PyObject*)self);
+ }
+
+which is assigned to the :attr:`tp_dealloc` member::
+
+ (destructor)Noddy_dealloc, /*tp_dealloc*/
+
+This method decrements the reference counts of the two Python attributes. We use
+:cfunc:`Py_XDECREF` here because the :attr:`first` and :attr:`last` members
+could be *NULL*. It then calls the :attr:`tp_free` member of the object's type
+to free the object's memory. Note that the object's type might not be
+:class:`NoddyType`, because the object may be an instance of a subclass.
+
+We want to make sure that the first and last names are initialized to empty
+strings, so we provide a new method::
+
+ static PyObject *
+ Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
+ {
+ Noddy *self;
+
+ self = (Noddy *)type->tp_alloc(type, 0);
+ if (self != NULL) {
+ self->first = PyString_FromString("");
+ if (self->first == NULL)
+ {
+ Py_DECREF(self);
+ return NULL;
+ }
+
+ self->last = PyString_FromString("");
+ if (self->last == NULL)
+ {
+ Py_DECREF(self);
+ return NULL;
+ }
+
+ self->number = 0;
+ }
+
+ return (PyObject *)self;
+ }
+
+and install it in the :attr:`tp_new` member::
+
+ Noddy_new, /* tp_new */
+
+The new member is responsible for creating (as opposed to initializing) objects
+of the type. It is exposed in Python as the :meth:`__new__` method. See the
+paper titled "Unifying types and classes in Python" for a detailed discussion of
+the :meth:`__new__` method. One reason to implement a new method is to assure
+the initial values of instance variables. In this case, we use the new method
+to make sure that the initial values of the members :attr:`first` and
+:attr:`last` are not *NULL*. If we didn't care whether the initial values were
+*NULL*, we could have used :cfunc:`PyType_GenericNew` as our new method, as we
+did before. :cfunc:`PyType_GenericNew` initializes all of the instance variable
+members to *NULL*.
+
+The new method is a static method that is passed the type being instantiated and
+any arguments passed when the type was called, and that returns the new object
+created. New methods always accept positional and keyword arguments, but they
+often ignore the arguments, leaving the argument handling to initializer
+methods. Note that if the type supports subclassing, the type passed may not be
+the type being defined. The new method calls the tp_alloc slot to allocate
+memory. We don't fill the :attr:`tp_alloc` slot ourselves. Rather
+:cfunc:`PyType_Ready` fills it for us by inheriting it from our base class,
+which is :class:`object` by default. Most types use the default allocation.
+
+.. note::
+
+ If you are creating a co-operative :attr:`tp_new` (one that calls a base type's
+ :attr:`tp_new` or :meth:`__new__`), you must *not* try to determine what method
+ to call using method resolution order at runtime. Always statically determine
+ what type you are going to call, and call its :attr:`tp_new` directly, or via
+ ``type->tp_base->tp_new``. If you do not do this, Python subclasses of your
+ type that also inherit from other Python-defined classes may not work correctly.
+ (Specifically, you may not be able to create instances of such subclasses
+ without getting a :exc:`TypeError`.)
+
+We provide an initialization function::
+
+ static int
+ Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
+ {
+ PyObject *first=NULL, *last=NULL, *tmp;
+
+ static char *kwlist[] = {"first", "last", "number", NULL};
+
+ if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
+ &first, &last,
+ &self->number))
+ return -1;
+
+ if (first) {
+ tmp = self->first;
+ Py_INCREF(first);
+ self->first = first;
+ Py_XDECREF(tmp);
+ }
+
+ if (last) {
+ tmp = self->last;
+ Py_INCREF(last);
+ self->last = last;
+ Py_XDECREF(tmp);
+ }
+
+ return 0;
+ }
+
+by filling the :attr:`tp_init` slot. ::
+
+ (initproc)Noddy_init, /* tp_init */
+
+The :attr:`tp_init` slot is exposed in Python as the :meth:`__init__` method. It
+is used to initialize an object after it's created. Unlike the new method, we
+can't guarantee that the initializer is called. The initializer isn't called
+when unpickling objects and it can be overridden. Our initializer accepts
+arguments to provide initial values for our instance. Initializers always accept
+positional and keyword arguments.
+
+Initializers can be called multiple times. Anyone can call the :meth:`__init__`
+method on our objects. For this reason, we have to be extra careful when
+assigning the new values. We might be tempted, for example to assign the
+:attr:`first` member like this::
+
+ if (first) {
+ Py_XDECREF(self->first);
+ Py_INCREF(first);
+ self->first = first;
+ }
+
+But this would be risky. Our type doesn't restrict the type of the
+:attr:`first` member, so it could be any kind of object. It could have a
+destructor that causes code to be executed that tries to access the
+:attr:`first` member. To be paranoid and protect ourselves against this
+possibility, we almost always reassign members before decrementing their
+reference counts. When don't we have to do this?
+
+* when we absolutely know that the reference count is greater than 1
+
+* when we know that deallocation of the object [#]_ will not cause any calls
+ back into our type's code
+
+* when decrementing a reference count in a :attr:`tp_dealloc` handler when
+ garbage-collections is not supported [#]_
+
+We want to want to expose our instance variables as attributes. There are a
+number of ways to do that. The simplest way is to define member definitions::
+
+ static PyMemberDef Noddy_members[] = {
+ {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
+ "first name"},
+ {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
+ "last name"},
+ {"number", T_INT, offsetof(Noddy, number), 0,
+ "noddy number"},
+ {NULL} /* Sentinel */
+ };
+
+and put the definitions in the :attr:`tp_members` slot::
+
+ Noddy_members, /* tp_members */
+
+Each member definition has a member name, type, offset, access flags and
+documentation string. See the "Generic Attribute Management" section below for
+details.
+
+A disadvantage of this approach is that it doesn't provide a way to restrict the
+types of objects that can be assigned to the Python attributes. We expect the
+first and last names to be strings, but any Python objects can be assigned.
+Further, the attributes can be deleted, setting the C pointers to *NULL*. Even
+though we can make sure the members are initialized to non-*NULL* values, the
+members can be set to *NULL* if the attributes are deleted.
+
+We define a single method, :meth:`name`, that outputs the objects name as the
+concatenation of the first and last names. ::
+
+ static PyObject *
+ Noddy_name(Noddy* self)
+ {
+ static PyObject *format = NULL;
+ PyObject *args, *result;
+
+ if (format == NULL) {
+ format = PyString_FromString("%s %s");
+ if (format == NULL)
+ return NULL;
+ }
+
+ if (self->first == NULL) {
+ PyErr_SetString(PyExc_AttributeError, "first");
+ return NULL;
+ }
+
+ if (self->last == NULL) {
+ PyErr_SetString(PyExc_AttributeError, "last");
+ return NULL;
+ }
+
+ args = Py_BuildValue("OO", self->first, self->last);
+ if (args == NULL)
+ return NULL;
+
+ result = PyString_Format(format, args);
+ Py_DECREF(args);
+
+ return result;
+ }
+
+The method is implemented as a C function that takes a :class:`Noddy` (or
+:class:`Noddy` subclass) instance as the first argument. Methods always take an
+instance as the first argument. Methods often take positional and keyword
+arguments as well, but in this cased we don't take any and don't need to accept
+a positional argument tuple or keyword argument dictionary. This method is
+equivalent to the Python method::
+
+ def name(self):
+ return "%s %s" % (self.first, self.last)
+
+Note that we have to check for the possibility that our :attr:`first` and
+:attr:`last` members are *NULL*. This is because they can be deleted, in which
+case they are set to *NULL*. It would be better to prevent deletion of these
+attributes and to restrict the attribute values to be strings. We'll see how to
+do that in the next section.
+
+Now that we've defined the method, we need to create an array of method
+definitions::
+
+ static PyMethodDef Noddy_methods[] = {
+ {"name", (PyCFunction)Noddy_name, METH_NOARGS,
+ "Return the name, combining the first and last name"
+ },
+ {NULL} /* Sentinel */
+ };
+
+and assign them to the :attr:`tp_methods` slot::
+
+ Noddy_methods, /* tp_methods */
+
+Note that we used the :const:`METH_NOARGS` flag to indicate that the method is
+passed no arguments.
+
+Finally, we'll make our type usable as a base class. We've written our methods
+carefully so far so that they don't make any assumptions about the type of the
+object being created or used, so all we need to do is to add the
+:const:`Py_TPFLAGS_BASETYPE` to our class flag definition::
+
+ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
+
+We rename :cfunc:`initnoddy` to :cfunc:`initnoddy2` and update the module name
+passed to :cfunc:`Py_InitModule3`.
+
+Finally, we update our :file:`setup.py` file to build the new module::
+
+ from distutils.core import setup, Extension
+ setup(name="noddy", version="1.0",
+ ext_modules=[
+ Extension("noddy", ["noddy.c"]),
+ Extension("noddy2", ["noddy2.c"]),
+ ])
+
+
+Providing finer control over data attributes
+--------------------------------------------
+
+In this section, we'll provide finer control over how the :attr:`first` and
+:attr:`last` attributes are set in the :class:`Noddy` example. In the previous
+version of our module, the instance variables :attr:`first` and :attr:`last`
+could be set to non-string values or even deleted. We want to make sure that
+these attributes always contain strings.
+
+.. literalinclude:: ../includes/noddy3.c
+
+
+To provide greater control, over the :attr:`first` and :attr:`last` attributes,
+we'll use custom getter and setter functions. Here are the functions for
+getting and setting the :attr:`first` attribute::
+
+ Noddy_getfirst(Noddy *self, void *closure)
+ {
+ Py_INCREF(self->first);
+ return self->first;
+ }
+
+ static int
+ Noddy_setfirst(Noddy *self, PyObject *value, void *closure)
+ {
+ if (value == NULL) {
+ PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
+ return -1;
+ }
+
+ if (! PyString_Check(value)) {
+ PyErr_SetString(PyExc_TypeError,
+ "The first attribute value must be a string");
+ return -1;
+ }
+
+ Py_DECREF(self->first);
+ Py_INCREF(value);
+ self->first = value;
+
+ return 0;
+ }
+
+The getter function is passed a :class:`Noddy` object and a "closure", which is
+void pointer. In this case, the closure is ignored. (The closure supports an
+advanced usage in which definition data is passed to the getter and setter. This
+could, for example, be used to allow a single set of getter and setter functions
+that decide the attribute to get or set based on data in the closure.)
+
+The setter function is passed the :class:`Noddy` object, the new value, and the
+closure. The new value may be *NULL*, in which case the attribute is being
+deleted. In our setter, we raise an error if the attribute is deleted or if the
+attribute value is not a string.
+
+We create an array of :ctype:`PyGetSetDef` structures::
+
+ static PyGetSetDef Noddy_getseters[] = {
+ {"first",
+ (getter)Noddy_getfirst, (setter)Noddy_setfirst,
+ "first name",
+ NULL},
+ {"last",
+ (getter)Noddy_getlast, (setter)Noddy_setlast,
+ "last name",
+ NULL},
+ {NULL} /* Sentinel */
+ };
+
+and register it in the :attr:`tp_getset` slot::
+
+ Noddy_getseters, /* tp_getset */
+
+to register out attribute getters and setters.
+
+The last item in a :ctype:`PyGetSetDef` structure is the closure mentioned
+above. In this case, we aren't using the closure, so we just pass *NULL*.
+
+We also remove the member definitions for these attributes::
+
+ static PyMemberDef Noddy_members[] = {
+ {"number", T_INT, offsetof(Noddy, number), 0,
+ "noddy number"},
+ {NULL} /* Sentinel */
+ };
+
+We also need to update the :attr:`tp_init` handler to only allow strings [#]_ to
+be passed::
+
+ static int
+ Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
+ {
+ PyObject *first=NULL, *last=NULL, *tmp;
+
+ static char *kwlist[] = {"first", "last", "number", NULL};
+
+ if (! PyArg_ParseTupleAndKeywords(args, kwds, "|SSi", kwlist,
+ &first, &last,
+ &self->number))
+ return -1;
+
+ if (first) {
+ tmp = self->first;
+ Py_INCREF(first);
+ self->first = first;
+ Py_DECREF(tmp);
+ }
+
+ if (last) {
+ tmp = self->last;
+ Py_INCREF(last);
+ self->last = last;
+ Py_DECREF(tmp);
+ }
+
+ return 0;
+ }
+
+With these changes, we can assure that the :attr:`first` and :attr:`last`
+members are never *NULL* so we can remove checks for *NULL* values in almost all
+cases. This means that most of the :cfunc:`Py_XDECREF` calls can be converted to
+:cfunc:`Py_DECREF` calls. The only place we can't change these calls is in the
+deallocator, where there is the possibility that the initialization of these
+members failed in the constructor.
+
+We also rename the module initialization function and module name in the
+initialization function, as we did before, and we add an extra definition to the
+:file:`setup.py` file.
+
+
+Supporting cyclic garbage collection
+------------------------------------
+
+Python has a cyclic-garbage collector that can identify unneeded objects even
+when their reference counts are not zero. This can happen when objects are
+involved in cycles. For example, consider::
+
+ >>> l = []
+ >>> l.append(l)
+ >>> del l
+
+In this example, we create a list that contains itself. When we delete it, it
+still has a reference from itself. Its reference count doesn't drop to zero.
+Fortunately, Python's cyclic-garbage collector will eventually figure out that
+the list is garbage and free it.
+
+In the second version of the :class:`Noddy` example, we allowed any kind of
+object to be stored in the :attr:`first` or :attr:`last` attributes. [#]_ This
+means that :class:`Noddy` objects can participate in cycles::
+
+ >>> import noddy2
+ >>> n = noddy2.Noddy()
+ >>> l = [n]
+ >>> n.first = l
+
+This is pretty silly, but it gives us an excuse to add support for the
+cyclic-garbage collector to the :class:`Noddy` example. To support cyclic
+garbage collection, types need to fill two slots and set a class flag that
+enables these slots:
+
+.. literalinclude:: ../includes/noddy4.c
+
+
+The traversal method provides access to subobjects that could participate in
+cycles::
+
+ static int
+ Noddy_traverse(Noddy *self, visitproc visit, void *arg)
+ {
+ int vret;
+
+ if (self->first) {
+ vret = visit(self->first, arg);
+ if (vret != 0)
+ return vret;
+ }
+ if (self->last) {
+ vret = visit(self->last, arg);
+ if (vret != 0)
+ return vret;
+ }
+
+ return 0;
+ }
+
+For each subobject that can participate in cycles, we need to call the
+:cfunc:`visit` function, which is passed to the traversal method. The
+:cfunc:`visit` function takes as arguments the subobject and the extra argument
+*arg* passed to the traversal method. It returns an integer value that must be
+returned if it is non-zero.
+
+Python 2.4 and higher provide a :cfunc:`Py_VISIT` macro that automates calling
+visit functions. With :cfunc:`Py_VISIT`, :cfunc:`Noddy_traverse` can be
+simplified::
+
+ static int
+ Noddy_traverse(Noddy *self, visitproc visit, void *arg)
+ {
+ Py_VISIT(self->first);
+ Py_VISIT(self->last);
+ return 0;
+ }
+
+.. note::
+
+ Note that the :attr:`tp_traverse` implementation must name its arguments exactly
+ *visit* and *arg* in order to use :cfunc:`Py_VISIT`. This is to encourage
+ uniformity across these boring implementations.
+
+We also need to provide a method for clearing any subobjects that can
+participate in cycles. We implement the method and reimplement the deallocator
+to use it::
+
+ static int
+ Noddy_clear(Noddy *self)
+ {
+ PyObject *tmp;
+
+ tmp = self->first;
+ self->first = NULL;
+ Py_XDECREF(tmp);
+
+ tmp = self->last;
+ self->last = NULL;
+ Py_XDECREF(tmp);
+
+ return 0;
+ }
+
+ static void
+ Noddy_dealloc(Noddy* self)
+ {
+ Noddy_clear(self);
+ self->ob_type->tp_free((PyObject*)self);
+ }
+
+Notice the use of a temporary variable in :cfunc:`Noddy_clear`. We use the
+temporary variable so that we can set each member to *NULL* before decrementing
+its reference count. We do this because, as was discussed earlier, if the
+reference count drops to zero, we might cause code to run that calls back into
+the object. In addition, because we now support garbage collection, we also
+have to worry about code being run that triggers garbage collection. If garbage
+collection is run, our :attr:`tp_traverse` handler could get called. We can't
+take a chance of having :cfunc:`Noddy_traverse` called when a member's reference
+count has dropped to zero and its value hasn't been set to *NULL*.
+
+Python 2.4 and higher provide a :cfunc:`Py_CLEAR` that automates the careful
+decrementing of reference counts. With :cfunc:`Py_CLEAR`, the
+:cfunc:`Noddy_clear` function can be simplified::
+
+ static int
+ Noddy_clear(Noddy *self)
+ {
+ Py_CLEAR(self->first);
+ Py_CLEAR(self->last);
+ return 0;
+ }
+
+Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags::
+
+ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /*tp_flags*/
+
+That's pretty much it. If we had written custom :attr:`tp_alloc` or
+:attr:`tp_free` slots, we'd need to modify them for cyclic-garbage collection.
+Most extensions will use the versions automatically provided.
+
+
+Subclassing other types
+-----------------------
+
+It is possible to create new extension types that are derived from existing
+types. It is easiest to inherit from the built in types, since an extension can
+easily use the :class:`PyTypeObject` it needs. It can be difficult to share
+these :class:`PyTypeObject` structures between extension modules.
+
+In this example we will create a :class:`Shoddy` type that inherits from the
+builtin :class:`list` type. The new type will be completely compatible with
+regular lists, but will have an additional :meth:`increment` method that
+increases an internal counter. ::
+
+ >>> import shoddy
+ >>> s = shoddy.Shoddy(range(3))
+ >>> s.extend(s)
+ >>> print len(s)
+ 6
+ >>> print s.increment()
+ 1
+ >>> print s.increment()
+ 2
+
+.. literalinclude:: ../includes/shoddy.c
+
+
+As you can see, the source code closely resembles the :class:`Noddy` examples in
+previous sections. We will break down the main differences between them. ::
+
+ typedef struct {
+ PyListObject list;
+ int state;
+ } Shoddy;
+
+The primary difference for derived type objects is that the base type's object
+structure must be the first value. The base type will already include the
+:cfunc:`PyObject_HEAD` at the beginning of its structure.
+
+When a Python object is a :class:`Shoddy` instance, its *PyObject\** pointer can
+be safely cast to both *PyListObject\** and *Shoddy\**. ::
+
+ static int
+ Shoddy_init(Shoddy *self, PyObject *args, PyObject *kwds)
+ {
+ if (PyList_Type.tp_init((PyObject *)self, args, kwds) < 0)
+ return -1;
+ self->state = 0;
+ return 0;
+ }
+
+In the :attr:`__init__` method for our type, we can see how to call through to
+the :attr:`__init__` method of the base type.
+
+This pattern is important when writing a type with custom :attr:`new` and
+:attr:`dealloc` methods. The :attr:`new` method should not actually create the
+memory for the object with :attr:`tp_alloc`, that will be handled by the base
+class when calling its :attr:`tp_new`.
+
+When filling out the :cfunc:`PyTypeObject` for the :class:`Shoddy` type, you see
+a slot for :cfunc:`tp_base`. Due to cross platform compiler issues, you can't
+fill that field directly with the :cfunc:`PyList_Type`; it can be done later in
+the module's :cfunc:`init` function. ::
+
+ PyMODINIT_FUNC
+ initshoddy(void)
+ {
+ PyObject *m;
+
+ ShoddyType.tp_base = &PyList_Type;
+ if (PyType_Ready(&ShoddyType) < 0)
+ return;
+
+ m = Py_InitModule3("shoddy", NULL, "Shoddy module");
+ if (m == NULL)
+ return;
+
+ Py_INCREF(&ShoddyType);
+ PyModule_AddObject(m, "Shoddy", (PyObject *) &ShoddyType);
+ }
+
+Before calling :cfunc:`PyType_Ready`, the type structure must have the
+:attr:`tp_base` slot filled in. When we are deriving a new type, it is not
+necessary to fill out the :attr:`tp_alloc` slot with :cfunc:`PyType_GenericNew`
+-- the allocate function from the base type will be inherited.
+
+After that, calling :cfunc:`PyType_Ready` and adding the type object to the
+module is the same as with the basic :class:`Noddy` examples.
+
+
+.. _dnt-type-methods:
+
+Type Methods
+============
+
+This section aims to give a quick fly-by on the various type methods you can
+implement and what they do.
+
+Here is the definition of :ctype:`PyTypeObject`, with some fields only used in
+debug builds omitted:
+
+.. literalinclude:: ../includes/typestruct.h
+
+
+Now that's a *lot* of methods. Don't worry too much though - if you have a type
+you want to define, the chances are very good that you will only implement a
+handful of these.
+
+As you probably expect by now, we're going to go over this and give more
+information about the various handlers. We won't go in the order they are
+defined in the structure, because there is a lot of historical baggage that
+impacts the ordering of the fields; be sure your type initialization keeps the
+fields in the right order! It's often easiest to find an example that includes
+all the fields you need (even if they're initialized to ``0``) and then change
+the values to suit your new type. ::
+
+ char *tp_name; /* For printing */
+
+The name of the type - as mentioned in the last section, this will appear in
+various places, almost entirely for diagnostic purposes. Try to choose something
+that will be helpful in such a situation! ::
+
+ int tp_basicsize, tp_itemsize; /* For allocation */
+
+These fields tell the runtime how much memory to allocate when new objects of
+this type are created. Python has some built-in support for variable length
+structures (think: strings, lists) which is where the :attr:`tp_itemsize` field
+comes in. This will be dealt with later. ::
+
+ char *tp_doc;
+
+Here you can put a string (or its address) that you want returned when the
+Python script references ``obj.__doc__`` to retrieve the doc string.
+
+Now we come to the basic type methods---the ones most extension types will
+implement.
+
+
+Finalization and De-allocation
+------------------------------
+
+.. index::
+ single: object; deallocation
+ single: deallocation, object
+ single: object; finalization
+ single: finalization, of objects
+
+::
+
+ destructor tp_dealloc;
+
+This function is called when the reference count of the instance of your type is
+reduced to zero and the Python interpreter wants to reclaim it. If your type
+has memory to free or other clean-up to perform, put it here. The object itself
+needs to be freed here as well. Here is an example of this function::
+
+ static void
+ newdatatype_dealloc(newdatatypeobject * obj)
+ {
+ free(obj->obj_UnderlyingDatatypePtr);
+ obj->ob_type->tp_free(obj);
+ }
+
+.. index::
+ single: PyErr_Fetch()
+ single: PyErr_Restore()
+
+One important requirement of the deallocator function is that it leaves any
+pending exceptions alone. This is important since deallocators are frequently
+called as the interpreter unwinds the Python stack; when the stack is unwound
+due to an exception (rather than normal returns), nothing is done to protect the
+deallocators from seeing that an exception has already been set. Any actions
+which a deallocator performs which may cause additional Python code to be
+executed may detect that an exception has been set. This can lead to misleading
+errors from the interpreter. The proper way to protect against this is to save
+a pending exception before performing the unsafe action, and restoring it when
+done. This can be done using the :cfunc:`PyErr_Fetch` and
+:cfunc:`PyErr_Restore` functions::
+
+ static void
+ my_dealloc(PyObject *obj)
+ {
+ MyObject *self = (MyObject *) obj;
+ PyObject *cbresult;
+
+ if (self->my_callback != NULL) {
+ PyObject *err_type, *err_value, *err_traceback;
+ int have_error = PyErr_Occurred() ? 1 : 0;
+
+ if (have_error)
+ PyErr_Fetch(&err_type, &err_value, &err_traceback);
+
+ cbresult = PyObject_CallObject(self->my_callback, NULL);
+ if (cbresult == NULL)
+ PyErr_WriteUnraisable(self->my_callback);
+ else
+ Py_DECREF(cbresult);
+
+ if (have_error)
+ PyErr_Restore(err_type, err_value, err_traceback);
+
+ Py_DECREF(self->my_callback);
+ }
+ obj->ob_type->tp_free((PyObject*)self);
+ }
+
+
+Object Presentation
+-------------------
+
+.. index::
+ builtin: repr
+ builtin: str
+
+In Python, there are three ways to generate a textual representation of an
+object: the :func:`repr` function (or equivalent back-tick syntax), the
+:func:`str` function, and the :keyword:`print` statement. For most objects, the
+:keyword:`print` statement is equivalent to the :func:`str` function, but it is
+possible to special-case printing to a :ctype:`FILE\*` if necessary; this should
+only be done if efficiency is identified as a problem and profiling suggests
+that creating a temporary string object to be written to a file is too
+expensive.
+
+These handlers are all optional, and most types at most need to implement the
+:attr:`tp_str` and :attr:`tp_repr` handlers. ::
+
+ reprfunc tp_repr;
+ reprfunc tp_str;
+ printfunc tp_print;
+
+The :attr:`tp_repr` handler should return a string object containing a
+representation of the instance for which it is called. Here is a simple
+example::
+
+ static PyObject *
+ newdatatype_repr(newdatatypeobject * obj)
+ {
+ return PyString_FromFormat("Repr-ified_newdatatype{{size:\%d}}",
+ obj->obj_UnderlyingDatatypePtr->size);
+ }
+
+If no :attr:`tp_repr` handler is specified, the interpreter will supply a
+representation that uses the type's :attr:`tp_name` and a uniquely-identifying
+value for the object.
+
+The :attr:`tp_str` handler is to :func:`str` what the :attr:`tp_repr` handler
+described above is to :func:`repr`; that is, it is called when Python code calls
+:func:`str` on an instance of your object. Its implementation is very similar
+to the :attr:`tp_repr` function, but the resulting string is intended for human
+consumption. If :attr:`tp_str` is not specified, the :attr:`tp_repr` handler is
+used instead.
+
+Here is a simple example::
+
+ static PyObject *
+ newdatatype_str(newdatatypeobject * obj)
+ {
+ return PyString_FromFormat("Stringified_newdatatype{{size:\%d}}",
+ obj->obj_UnderlyingDatatypePtr->size);
+ }
+
+The print function will be called whenever Python needs to "print" an instance
+of the type. For example, if 'node' is an instance of type TreeNode, then the
+print function is called when Python code calls::
+
+ print node
+
+There is a flags argument and one flag, :const:`Py_PRINT_RAW`, and it suggests
+that you print without string quotes and possibly without interpreting escape
+sequences.
+
+The print function receives a file object as an argument. You will likely want
+to write to that file object.
+
+Here is a sample print function::
+
+ static int
+ newdatatype_print(newdatatypeobject *obj, FILE *fp, int flags)
+ {
+ if (flags & Py_PRINT_RAW) {
+ fprintf(fp, "<{newdatatype object--size: %d}>",
+ obj->obj_UnderlyingDatatypePtr->size);
+ }
+ else {
+ fprintf(fp, "\"<{newdatatype object--size: %d}>\"",
+ obj->obj_UnderlyingDatatypePtr->size);
+ }
+ return 0;
+ }
+
+
+Attribute Management
+--------------------
+
+For every object which can support attributes, the corresponding type must
+provide the functions that control how the attributes are resolved. There needs
+to be a function which can retrieve attributes (if any are defined), and another
+to set attributes (if setting attributes is allowed). Removing an attribute is
+a special case, for which the new value passed to the handler is *NULL*.
+
+Python supports two pairs of attribute handlers; a type that supports attributes
+only needs to implement the functions for one pair. The difference is that one
+pair takes the name of the attribute as a :ctype:`char\*`, while the other
+accepts a :ctype:`PyObject\*`. Each type can use whichever pair makes more
+sense for the implementation's convenience. ::
+
+ getattrfunc tp_getattr; /* char * version */
+ setattrfunc tp_setattr;
+ /* ... */
+ getattrofunc tp_getattrofunc; /* PyObject * version */
+ setattrofunc tp_setattrofunc;
+
+If accessing attributes of an object is always a simple operation (this will be
+explained shortly), there are generic implementations which can be used to
+provide the :ctype:`PyObject\*` version of the attribute management functions.
+The actual need for type-specific attribute handlers almost completely
+disappeared starting with Python 2.2, though there are many examples which have
+not been updated to use some of the new generic mechanism that is available.
+
+
+Generic Attribute Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 2.2
+
+Most extension types only use *simple* attributes. So, what makes the
+attributes simple? There are only a couple of conditions that must be met:
+
+#. The name of the attributes must be known when :cfunc:`PyType_Ready` is
+ called.
+
+#. No special processing is needed to record that an attribute was looked up or
+ set, nor do actions need to be taken based on the value.
+
+Note that this list does not place any restrictions on the values of the
+attributes, when the values are computed, or how relevant data is stored.
+
+When :cfunc:`PyType_Ready` is called, it uses three tables referenced by the
+type object to create *descriptors* which are placed in the dictionary of the
+type object. Each descriptor controls access to one attribute of the instance
+object. Each of the tables is optional; if all three are *NULL*, instances of
+the type will only have attributes that are inherited from their base type, and
+should leave the :attr:`tp_getattro` and :attr:`tp_setattro` fields *NULL* as
+well, allowing the base type to handle attributes.
+
+The tables are declared as three fields of the type object::
+
+ struct PyMethodDef *tp_methods;
+ struct PyMemberDef *tp_members;
+ struct PyGetSetDef *tp_getset;
+
+If :attr:`tp_methods` is not *NULL*, it must refer to an array of
+:ctype:`PyMethodDef` structures. Each entry in the table is an instance of this
+structure::
+
+ typedef struct PyMethodDef {
+ char *ml_name; /* method name */
+ PyCFunction ml_meth; /* implementation function */
+ int ml_flags; /* flags */
+ char *ml_doc; /* docstring */
+ } PyMethodDef;
+
+One entry should be defined for each method provided by the type; no entries are
+needed for methods inherited from a base type. One additional entry is needed
+at the end; it is a sentinel that marks the end of the array. The
+:attr:`ml_name` field of the sentinel must be *NULL*.
+
+XXX Need to refer to some unified discussion of the structure fields, shared
+with the next section.
+
+The second table is used to define attributes which map directly to data stored
+in the instance. A variety of primitive C types are supported, and access may
+be read-only or read-write. The structures in the table are defined as::
+
+ typedef struct PyMemberDef {
+ char *name;
+ int type;
+ int offset;
+ int flags;
+ char *doc;
+ } PyMemberDef;
+
+For each entry in the table, a descriptor will be constructed and added to the
+type which will be able to extract a value from the instance structure. The
+:attr:`type` field should contain one of the type codes defined in the
+:file:`structmember.h` header; the value will be used to determine how to
+convert Python values to and from C values. The :attr:`flags` field is used to
+store flags which control how the attribute can be accessed.
+
+XXX Need to move some of this to a shared section!
+
+The following flag constants are defined in :file:`structmember.h`; they may be
+combined using bitwise-OR.
+
++---------------------------+----------------------------------------------+
+| Constant | Meaning |
++===========================+==============================================+
+| :const:`READONLY` | Never writable. |
++---------------------------+----------------------------------------------+
+| :const:`RO` | Shorthand for :const:`READONLY`. |
++---------------------------+----------------------------------------------+
+| :const:`READ_RESTRICTED` | Not readable in restricted mode. |
++---------------------------+----------------------------------------------+
+| :const:`WRITE_RESTRICTED` | Not writable in restricted mode. |
++---------------------------+----------------------------------------------+
+| :const:`RESTRICTED` | Not readable or writable in restricted mode. |
++---------------------------+----------------------------------------------+
+
+.. index::
+ single: READONLY
+ single: RO
+ single: READ_RESTRICTED
+ single: WRITE_RESTRICTED
+ single: RESTRICTED
+
+An interesting advantage of using the :attr:`tp_members` table to build
+descriptors that are used at runtime is that any attribute defined this way can
+have an associated doc string simply by providing the text in the table. An
+application can use the introspection API to retrieve the descriptor from the
+class object, and get the doc string using its :attr:`__doc__` attribute.
+
+As with the :attr:`tp_methods` table, a sentinel entry with a :attr:`name` value
+of *NULL* is required.
+
+.. % XXX Descriptors need to be explained in more detail somewhere, but
+.. % not here.
+.. %
+.. % Descriptor objects have two handler functions which correspond to
+.. % the \member{tp_getattro} and \member{tp_setattro} handlers. The
+.. % \method{__get__()} handler is a function which is passed the
+.. % descriptor, instance, and type objects, and returns the value of the
+.. % attribute, or it returns \NULL{} and sets an exception. The
+.. % \method{__set__()} handler is passed the descriptor, instance, type,
+.. % and new value;
+
+
+Type-specific Attribute Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For simplicity, only the :ctype:`char\*` version will be demonstrated here; the
+type of the name parameter is the only difference between the :ctype:`char\*`
+and :ctype:`PyObject\*` flavors of the interface. This example effectively does
+the same thing as the generic example above, but does not use the generic
+support added in Python 2.2. The value in showing this is two-fold: it
+demonstrates how basic attribute management can be done in a way that is
+portable to older versions of Python, and explains how the handler functions are
+called, so that if you do need to extend their functionality, you'll understand
+what needs to be done.
+
+The :attr:`tp_getattr` handler is called when the object requires an attribute
+look-up. It is called in the same situations where the :meth:`__getattr__`
+method of a class would be called.
+
+A likely way to handle this is (1) to implement a set of functions (such as
+:cfunc:`newdatatype_getSize` and :cfunc:`newdatatype_setSize` in the example
+below), (2) provide a method table listing these functions, and (3) provide a
+getattr function that returns the result of a lookup in that table. The method
+table uses the same structure as the :attr:`tp_methods` field of the type
+object.
+
+Here is an example::
+
+ static PyMethodDef newdatatype_methods[] = {
+ {"getSize", (PyCFunction)newdatatype_getSize, METH_VARARGS,
+ "Return the current size."},
+ {"setSize", (PyCFunction)newdatatype_setSize, METH_VARARGS,
+ "Set the size."},
+ {NULL, NULL, 0, NULL} /* sentinel */
+ };
+
+ static PyObject *
+ newdatatype_getattr(newdatatypeobject *obj, char *name)
+ {
+ return Py_FindMethod(newdatatype_methods, (PyObject *)obj, name);
+ }
+
+The :attr:`tp_setattr` handler is called when the :meth:`__setattr__` or
+:meth:`__delattr__` method of a class instance would be called. When an
+attribute should be deleted, the third parameter will be *NULL*. Here is an
+example that simply raises an exception; if this were really all you wanted, the
+:attr:`tp_setattr` handler should be set to *NULL*. ::
+
+ static int
+ newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
+ {
+ (void)PyErr_Format(PyExc_RuntimeError, "Read-only attribute: \%s", name);
+ return -1;
+ }
+
+
+Object Comparison
+-----------------
+
+::
+
+ cmpfunc tp_compare;
+
+The :attr:`tp_compare` handler is called when comparisons are needed and the
+object does not implement the specific rich comparison method which matches the
+requested comparison. (It is always used if defined and the
+:cfunc:`PyObject_Compare` or :cfunc:`PyObject_Cmp` functions are used, or if
+:func:`cmp` is used from Python.) It is analogous to the :meth:`__cmp__` method.
+This function should return ``-1`` if *obj1* is less than *obj2*, ``0`` if they
+are equal, and ``1`` if *obj1* is greater than *obj2*. (It was previously
+allowed to return arbitrary negative or positive integers for less than and
+greater than, respectively; as of Python 2.2, this is no longer allowed. In the
+future, other return values may be assigned a different meaning.)
+
+A :attr:`tp_compare` handler may raise an exception. In this case it should
+return a negative value. The caller has to test for the exception using
+:cfunc:`PyErr_Occurred`.
+
+Here is a sample implementation::
+
+ static int
+ newdatatype_compare(newdatatypeobject * obj1, newdatatypeobject * obj2)
+ {
+ long result;
+
+ if (obj1->obj_UnderlyingDatatypePtr->size <
+ obj2->obj_UnderlyingDatatypePtr->size) {
+ result = -1;
+ }
+ else if (obj1->obj_UnderlyingDatatypePtr->size >
+ obj2->obj_UnderlyingDatatypePtr->size) {
+ result = 1;
+ }
+ else {
+ result = 0;
+ }
+ return result;
+ }
+
+
+Abstract Protocol Support
+-------------------------
+
+Python supports a variety of *abstract* 'protocols;' the specific interfaces
+provided to use these interfaces are documented in :ref:`abstract`.
+
+
+A number of these abstract interfaces were defined early in the development of
+the Python implementation. In particular, the number, mapping, and sequence
+protocols have been part of Python since the beginning. Other protocols have
+been added over time. For protocols which depend on several handler routines
+from the type implementation, the older protocols have been defined as optional
+blocks of handlers referenced by the type object. For newer protocols there are
+additional slots in the main type object, with a flag bit being set to indicate
+that the slots are present and should be checked by the interpreter. (The flag
+bit does not indicate that the slot values are non-*NULL*. The flag may be set
+to indicate the presence of a slot, but a slot may still be unfilled.) ::
+
+ PyNumberMethods tp_as_number;
+ PySequenceMethods tp_as_sequence;
+ PyMappingMethods tp_as_mapping;
+
+If you wish your object to be able to act like a number, a sequence, or a
+mapping object, then you place the address of a structure that implements the C
+type :ctype:`PyNumberMethods`, :ctype:`PySequenceMethods`, or
+:ctype:`PyMappingMethods`, respectively. It is up to you to fill in this
+structure with appropriate values. You can find examples of the use of each of
+these in the :file:`Objects` directory of the Python source distribution. ::
+
+ hashfunc tp_hash;
+
+This function, if you choose to provide it, should return a hash number for an
+instance of your data type. Here is a moderately pointless example::
+
+ static long
+ newdatatype_hash(newdatatypeobject *obj)
+ {
+ long result;
+ result = obj->obj_UnderlyingDatatypePtr->size;
+ result = result * 3;
+ return result;
+ }
+
+::
+
+ ternaryfunc tp_call;
+
+This function is called when an instance of your data type is "called", for
+example, if ``obj1`` is an instance of your data type and the Python script
+contains ``obj1('hello')``, the :attr:`tp_call` handler is invoked.
+
+This function takes three arguments:
+
+#. *arg1* is the instance of the data type which is the subject of the call. If
+ the call is ``obj1('hello')``, then *arg1* is ``obj1``.
+
+#. *arg2* is a tuple containing the arguments to the call. You can use
+ :cfunc:`PyArg_ParseTuple` to extract the arguments.
+
+#. *arg3* is a dictionary of keyword arguments that were passed. If this is
+ non-*NULL* and you support keyword arguments, use
+ :cfunc:`PyArg_ParseTupleAndKeywords` to extract the arguments. If you do not
+ want to support keyword arguments and this is non-*NULL*, raise a
+ :exc:`TypeError` with a message saying that keyword arguments are not supported.
+
+Here is a desultory example of the implementation of the call function. ::
+
+ /* Implement the call function.
+ * obj1 is the instance receiving the call.
+ * obj2 is a tuple containing the arguments to the call, in this
+ * case 3 strings.
+ */
+ static PyObject *
+ newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *other)
+ {
+ PyObject *result;
+ char *arg1;
+ char *arg2;
+ char *arg3;
+
+ if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {
+ return NULL;
+ }
+ result = PyString_FromFormat(
+ "Returning -- value: [\%d] arg1: [\%s] arg2: [\%s] arg3: [\%s]\n",
+ obj->obj_UnderlyingDatatypePtr->size,
+ arg1, arg2, arg3);
+ printf("\%s", PyString_AS_STRING(result));
+ return result;
+ }
+
+XXX some fields need to be added here... ::
+
+ /* Added in release 2.2 */
+ /* Iterators */
+ getiterfunc tp_iter;
+ iternextfunc tp_iternext;
+
+These functions provide support for the iterator protocol. Any object which
+wishes to support iteration over its contents (which may be generated during
+iteration) must implement the ``tp_iter`` handler. Objects which are returned
+by a ``tp_iter`` handler must implement both the ``tp_iter`` and ``tp_iternext``
+handlers. Both handlers take exactly one parameter, the instance for which they
+are being called, and return a new reference. In the case of an error, they
+should set an exception and return *NULL*.
+
+For an object which represents an iterable collection, the ``tp_iter`` handler
+must return an iterator object. The iterator object is responsible for
+maintaining the state of the iteration. For collections which can support
+multiple iterators which do not interfere with each other (as lists and tuples
+do), a new iterator should be created and returned. Objects which can only be
+iterated over once (usually due to side effects of iteration) should implement
+this handler by returning a new reference to themselves, and should also
+implement the ``tp_iternext`` handler. File objects are an example of such an
+iterator.
+
+Iterator objects should implement both handlers. The ``tp_iter`` handler should
+return a new reference to the iterator (this is the same as the ``tp_iter``
+handler for objects which can only be iterated over destructively). The
+``tp_iternext`` handler should return a new reference to the next object in the
+iteration if there is one. If the iteration has reached the end, it may return
+*NULL* without setting an exception or it may set :exc:`StopIteration`; avoiding
+the exception can yield slightly better performance. If an actual error occurs,
+it should set an exception and return *NULL*.
+
+
+.. _weakref-support:
+
+Weak Reference Support
+----------------------
+
+One of the goals of Python's weak-reference implementation is to allow any type
+to participate in the weak reference mechanism without incurring the overhead on
+those objects which do not benefit by weak referencing (such as numbers).
+
+For an object to be weakly referencable, the extension must include a
+:ctype:`PyObject\*` field in the instance structure for the use of the weak
+reference mechanism; it must be initialized to *NULL* by the object's
+constructor. It must also set the :attr:`tp_weaklistoffset` field of the
+corresponding type object to the offset of the field. For example, the instance
+type is defined with the following structure::
+
+ typedef struct {
+ PyObject_HEAD
+ PyClassObject *in_class; /* The class object */
+ PyObject *in_dict; /* A dictionary */
+ PyObject *in_weakreflist; /* List of weak references */
+ } PyInstanceObject;
+
+The statically-declared type object for instances is defined this way::
+
+ PyTypeObject PyInstance_Type = {
+ PyObject_HEAD_INIT(&PyType_Type)
+ 0,
+ "module.instance",
+
+ /* Lots of stuff omitted for brevity... */
+
+ Py_TPFLAGS_DEFAULT, /* tp_flags */
+ 0, /* tp_doc */
+ 0, /* tp_traverse */
+ 0, /* tp_clear */
+ 0, /* tp_richcompare */
+ offsetof(PyInstanceObject, in_weakreflist), /* tp_weaklistoffset */
+ };
+
+The type constructor is responsible for initializing the weak reference list to
+*NULL*::
+
+ static PyObject *
+ instance_new() {
+ /* Other initialization stuff omitted for brevity */
+
+ self->in_weakreflist = NULL;
+
+ return (PyObject *) self;
+ }
+
+The only further addition is that the destructor needs to call the weak
+reference manager to clear any weak references. This should be done before any
+other parts of the destruction have occurred, but is only required if the weak
+reference list is non-*NULL*::
+
+ static void
+ instance_dealloc(PyInstanceObject *inst)
+ {
+ /* Allocate temporaries if needed, but do not begin
+ destruction just yet.
+ */
+
+ if (inst->in_weakreflist != NULL)
+ PyObject_ClearWeakRefs((PyObject *) inst);
+
+ /* Proceed with object destruction normally. */
+ }
+
+
+More Suggestions
+----------------
+
+Remember that you can omit most of these functions, in which case you provide
+``0`` as a value. There are type definitions for each of the functions you must
+provide. They are in :file:`object.h` in the Python include directory that
+comes with the source distribution of Python.
+
+In order to learn how to implement any specific method for your new data type,
+do the following: Download and unpack the Python source distribution. Go the
+:file:`Objects` directory, then search the C source files for ``tp_`` plus the
+function you want (for example, ``tp_print`` or ``tp_compare``). You will find
+examples of the function you want to implement.
+
+When you need to verify that an object is an instance of the type you are
+implementing, use the :cfunc:`PyObject_TypeCheck` function. A sample of its use
+might be something like the following::
+
+ if (! PyObject_TypeCheck(some_object, &MyType)) {
+ PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");
+ return NULL;
+ }
+
+.. rubric:: Footnotes
+
+.. [#] This is true when we know that the object is a basic type, like a string or a
+ float.
+
+.. [#] We relied on this in the :attr:`tp_dealloc` handler in this example, because our
+ type doesn't support garbage collection. Even if a type supports garbage
+ collection, there are calls that can be made to "untrack" the object from
+ garbage collection, however, these calls are advanced and not covered here.
+
+.. [#] We now know that the first and last members are strings, so perhaps we could be
+ less careful about decrementing their reference counts, however, we accept
+ instances of string subclasses. Even though deallocating normal strings won't
+ call back into our objects, we can't guarantee that deallocating an instance of
+ a string subclass won't. call back into out objects.
+
+.. [#] Even in the third version, we aren't guaranteed to avoid cycles. Instances of
+ string subclasses are allowed and string subclasses could allow cycles even if
+ normal strings don't.
+
--- /dev/null
+.. highlightlang:: c
+
+
+.. _building-on-windows:
+
+****************************************
+Building C and C++ Extensions on Windows
+****************************************
+
+.. %
+
+This chapter briefly explains how to create a Windows extension module for
+Python using Microsoft Visual C++, and follows with more detailed background
+information on how it works. The explanatory material is useful for both the
+Windows programmer learning to build Python extensions and the Unix programmer
+interested in producing software which can be successfully built on both Unix
+and Windows.
+
+Module authors are encouraged to use the distutils approach for building
+extension modules, instead of the one described in this section. You will still
+need the C compiler that was used to build Python; typically Microsoft Visual
+C++.
+
+.. note::
+
+ This chapter mentions a number of filenames that include an encoded Python
+ version number. These filenames are represented with the version number shown
+ as ``XY``; in practive, ``'X'`` will be the major version number and ``'Y'``
+ will be the minor version number of the Python release you're working with. For
+ example, if you are using Python 2.2.1, ``XY`` will actually be ``22``.
+
+
+.. _win-cookbook:
+
+A Cookbook Approach
+===================
+
+There are two approaches to building extension modules on Windows, just as there
+are on Unix: use the :mod:`distutils` package to control the build process, or
+do things manually. The distutils approach works well for most extensions;
+documentation on using :mod:`distutils` to build and package extension modules
+is available in :ref:`distutils-index`. This section describes the manual
+approach to building Python extensions written in C or C++.
+
+To build extensions using these instructions, you need to have a copy of the
+Python sources of the same version as your installed Python. You will need
+Microsoft Visual C++ "Developer Studio"; project files are supplied for VC++
+version 7.1, but you can use older versions of VC++. Notice that you should use
+the same version of VC++that was used to build Python itself. The example files
+described here are distributed with the Python sources in the
+:file:`PC\\example_nt\\` directory.
+
+#. **Copy the example files** --- The :file:`example_nt` directory is a
+ subdirectory of the :file:`PC` directory, in order to keep all the PC-specific
+ files under the same directory in the source distribution. However, the
+ :file:`example_nt` directory can't actually be used from this location. You
+ first need to copy or move it up one level, so that :file:`example_nt` is a
+ sibling of the :file:`PC` and :file:`Include` directories. Do all your work
+ from within this new location.
+
+#. **Open the project** --- From VC++, use the :menuselection:`File --> Open
+ Solution` dialog (not :menuselection:`File --> Open`!). Navigate to and select
+ the file :file:`example.sln`, in the *copy* of the :file:`example_nt` directory
+ you made above. Click Open.
+
+#. **Build the example DLL** --- In order to check that everything is set up
+ right, try building:
+
+#. Select a configuration. This step is optional. Choose
+ :menuselection:`Build --> Configuration Manager --> Active Solution Configuration`
+ and select either :guilabel:`Release` or :guilabel:`Debug`. If you skip this
+ step, VC++ will use the Debug configuration by default.
+
+#. Build the DLL. Choose :menuselection:`Build --> Build Solution`. This
+ creates all intermediate and result files in a subdirectory called either
+ :file:`Debug` or :file:`Release`, depending on which configuration you selected
+ in the preceding step.
+
+#. **Testing the debug-mode DLL** --- Once the Debug build has succeeded, bring
+ up a DOS box, and change to the :file:`example_nt\\Debug` directory. You should
+ now be able to repeat the following session (``C>`` is the DOS prompt, ``>>>``
+ is the Python prompt; note that build information and various debug output from
+ Python may not match this screen dump exactly)::
+
+ C>..\..\PCbuild\python_d
+ Adding parser accelerators ...
+ Done.
+ Python 2.2 (#28, Dec 19 2001, 23:26:37) [MSC 32 bit (Intel)] on win32
+ Type "copyright", "credits" or "license" for more information.
+ >>> import example
+ [4897 refs]
+ >>> example.foo()
+ Hello, world
+ [4903 refs]
+ >>>
+
+ Congratulations! You've successfully built your first Python extension module.
+
+#. **Creating your own project** --- Choose a name and create a directory for
+ it. Copy your C sources into it. Note that the module source file name does
+ not necessarily have to match the module name, but the name of the
+ initialization function should match the module name --- you can only import a
+ module :mod:`spam` if its initialization function is called :cfunc:`initspam`,
+ and it should call :cfunc:`Py_InitModule` with the string ``"spam"`` as its
+ first argument (use the minimal :file:`example.c` in this directory as a guide).
+ By convention, it lives in a file called :file:`spam.c` or :file:`spammodule.c`.
+ The output file should be called :file:`spam.dll` or :file:`spam.pyd` (the
+ latter is supported to avoid confusion with a system library :file:`spam.dll` to
+ which your module could be a Python interface) in Release mode, or
+ :file:`spam_d.dll` or :file:`spam_d.pyd` in Debug mode.
+
+ Now your options are:
+
+#. Copy :file:`example.sln` and :file:`example.vcproj`, rename them to
+ :file:`spam.\*`, and edit them by hand, or
+
+#. Create a brand new project; instructions are below.
+
+ In either case, copy :file:`example_nt\\example.def` to :file:`spam\\spam.def`,
+ and edit the new :file:`spam.def` so its second line contains the string
+ '``initspam``'. If you created a new project yourself, add the file
+ :file:`spam.def` to the project now. (This is an annoying little file with only
+ two lines. An alternative approach is to forget about the :file:`.def` file,
+ and add the option :option:`/export:initspam` somewhere to the Link settings, by
+ manually editing the setting in Project Properties dialog).
+
+#. **Creating a brand new project** --- Use the :menuselection:`File --> New
+ --> Project` dialog to create a new Project Workspace. Select :guilabel:`Visual
+ C++ Projects/Win32/ Win32 Project`, enter the name (``spam``), and make sure the
+ Location is set to parent of the :file:`spam` directory you have created (which
+ should be a direct subdirectory of the Python build tree, a sibling of
+ :file:`Include` and :file:`PC`). Select Win32 as the platform (in my version,
+ this is the only choice). Make sure the Create new workspace radio button is
+ selected. Click OK.
+
+ You should now create the file :file:`spam.def` as instructed in the previous
+ section. Add the source files to the project, using :menuselection:`Project -->
+ Add Existing Item`. Set the pattern to ``*.*`` and select both :file:`spam.c`
+ and :file:`spam.def` and click OK. (Inserting them one by one is fine too.)
+
+ Now open the :menuselection:`Project --> spam properties` dialog. You only need
+ to change a few settings. Make sure :guilabel:`All Configurations` is selected
+ from the :guilabel:`Settings for:` dropdown list. Select the C/C++ tab. Choose
+ the General category in the popup menu at the top. Type the following text in
+ the entry box labeled :guilabel:`Additional Include Directories`::
+
+ ..\Include,..\PC
+
+ Then, choose the General category in the Linker tab, and enter ::
+
+ ..\PCbuild
+
+ in the text box labelled :guilabel:`Additional library Directories`.
+
+ Now you need to add some mode-specific settings:
+
+ Select :guilabel:`Release` in the :guilabel:`Configuration` dropdown list.
+ Choose the :guilabel:`Link` tab, choose the :guilabel:`Input` category, and
+ append ``pythonXY.lib`` to the list in the :guilabel:`Additional Dependencies`
+ box.
+
+ Select :guilabel:`Debug` in the :guilabel:`Configuration` dropdown list, and
+ append ``pythonXY_d.lib`` to the list in the :guilabel:`Additional Dependencies`
+ box. Then click the C/C++ tab, select :guilabel:`Code Generation`, and select
+ :guilabel:`Multi-threaded Debug DLL` from the :guilabel:`Runtime library`
+ dropdown list.
+
+ Select :guilabel:`Release` again from the :guilabel:`Configuration` dropdown
+ list. Select :guilabel:`Multi-threaded DLL` from the :guilabel:`Runtime
+ library` dropdown list.
+
+If your module creates a new type, you may have trouble with this line::
+
+ PyObject_HEAD_INIT(&PyType_Type)
+
+Change it to::
+
+ PyObject_HEAD_INIT(NULL)
+
+and add the following to the module initialization function::
+
+ MyObject_Type.ob_type = &PyType_Type;
+
+Refer to section 3 of the `Python FAQ <http://www.python.org/doc/FAQ.html>`_ for
+details on why you must do this.
+
+
+.. _dynamic-linking:
+
+Differences Between Unix and Windows
+====================================
+
+.. sectionauthor:: Chris Phoenix <cphoenix@best.com>
+
+
+Unix and Windows use completely different paradigms for run-time loading of
+code. Before you try to build a module that can be dynamically loaded, be aware
+of how your system works.
+
+In Unix, a shared object (:file:`.so`) file contains code to be used by the
+program, and also the names of functions and data that it expects to find in the
+program. When the file is joined to the program, all references to those
+functions and data in the file's code are changed to point to the actual
+locations in the program where the functions and data are placed in memory.
+This is basically a link operation.
+
+In Windows, a dynamic-link library (:file:`.dll`) file has no dangling
+references. Instead, an access to functions or data goes through a lookup
+table. So the DLL code does not have to be fixed up at runtime to refer to the
+program's memory; instead, the code already uses the DLL's lookup table, and the
+lookup table is modified at runtime to point to the functions and data.
+
+In Unix, there is only one type of library file (:file:`.a`) which contains code
+from several object files (:file:`.o`). During the link step to create a shared
+object file (:file:`.so`), the linker may find that it doesn't know where an
+identifier is defined. The linker will look for it in the object files in the
+libraries; if it finds it, it will include all the code from that object file.
+
+In Windows, there are two types of library, a static library and an import
+library (both called :file:`.lib`). A static library is like a Unix :file:`.a`
+file; it contains code to be included as necessary. An import library is
+basically used only to reassure the linker that a certain identifier is legal,
+and will be present in the program when the DLL is loaded. So the linker uses
+the information from the import library to build the lookup table for using
+identifiers that are not included in the DLL. When an application or a DLL is
+linked, an import library may be generated, which will need to be used for all
+future DLLs that depend on the symbols in the application or DLL.
+
+Suppose you are building two dynamic-load modules, B and C, which should share
+another block of code A. On Unix, you would *not* pass :file:`A.a` to the
+linker for :file:`B.so` and :file:`C.so`; that would cause it to be included
+twice, so that B and C would each have their own copy. In Windows, building
+:file:`A.dll` will also build :file:`A.lib`. You *do* pass :file:`A.lib` to the
+linker for B and C. :file:`A.lib` does not contain code; it just contains
+information which will be used at runtime to access A's code.
+
+In Windows, using an import library is sort of like using ``import spam``; it
+gives you access to spam's names, but does not create a separate copy. On Unix,
+linking with a library is more like ``from spam import *``; it does create a
+separate copy.
+
+
+.. _win-dlls:
+
+Using DLLs in Practice
+======================
+
+.. sectionauthor:: Chris Phoenix <cphoenix@best.com>
+
+
+Windows Python is built in Microsoft Visual C++; using other compilers may or
+may not work (though Borland seems to). The rest of this section is MSVC++
+specific.
+
+When creating DLLs in Windows, you must pass :file:`pythonXY.lib` to the linker.
+To build two DLLs, spam and ni (which uses C functions found in spam), you could
+use these commands::
+
+ cl /LD /I/python/include spam.c ../libs/pythonXY.lib
+ cl /LD /I/python/include ni.c spam.lib ../libs/pythonXY.lib
+
+The first command created three files: :file:`spam.obj`, :file:`spam.dll` and
+:file:`spam.lib`. :file:`Spam.dll` does not contain any Python functions (such
+as :cfunc:`PyArg_ParseTuple`), but it does know how to find the Python code
+thanks to :file:`pythonXY.lib`.
+
+The second command created :file:`ni.dll` (and :file:`.obj` and :file:`.lib`),
+which knows how to find the necessary functions from spam, and also from the
+Python executable.
+
+Not every identifier is exported to the lookup table. If you want any other
+modules (including Python) to be able to see your identifiers, you have to say
+``_declspec(dllexport)``, as in ``void _declspec(dllexport) initspam(void)`` or
+``PyObject _declspec(dllexport) *NiGetSpamData(void)``.
+
+Developer Studio will throw in a lot of import libraries that you do not really
+need, adding about 100K to your executable. To get rid of them, use the Project
+Settings dialog, Link tab, to specify *ignore default libraries*. Add the
+correct :file:`msvcrtxx.lib` to the list of libraries.
+
--- /dev/null
+*************************
+ Python Advocacy HOWTO
+*************************
+
+:Author: A.M. Kuchling
+:Release: 0.03
+
+
+.. topic:: Abstract
+
+ It's usually difficult to get your management to accept open source software,
+ and Python is no exception to this rule. This document discusses reasons to use
+ Python, strategies for winning acceptance, facts and arguments you can use, and
+ cases where you *shouldn't* try to use Python.
+
+
+Reasons to Use Python
+=====================
+
+There are several reasons to incorporate a scripting language into your
+development process, and this section will discuss them, and why Python has some
+properties that make it a particularly good choice.
+
+
+Programmability
+---------------
+
+Programs are often organized in a modular fashion. Lower-level operations are
+grouped together, and called by higher-level functions, which may in turn be
+used as basic operations by still further upper levels.
+
+For example, the lowest level might define a very low-level set of functions for
+accessing a hash table. The next level might use hash tables to store the
+headers of a mail message, mapping a header name like ``Date`` to a value such
+as ``Tue, 13 May 1997 20:00:54 -0400``. A yet higher level may operate on
+message objects, without knowing or caring that message headers are stored in a
+hash table, and so forth.
+
+Often, the lowest levels do very simple things; they implement a data structure
+such as a binary tree or hash table, or they perform some simple computation,
+such as converting a date string to a number. The higher levels then contain
+logic connecting these primitive operations. Using the approach, the primitives
+can be seen as basic building blocks which are then glued together to produce
+the complete product.
+
+Why is this design approach relevant to Python? Because Python is well suited
+to functioning as such a glue language. A common approach is to write a Python
+module that implements the lower level operations; for the sake of speed, the
+implementation might be in C, Java, or even Fortran. Once the primitives are
+available to Python programs, the logic underlying higher level operations is
+written in the form of Python code. The high-level logic is then more
+understandable, and easier to modify.
+
+John Ousterhout wrote a paper that explains this idea at greater length,
+entitled "Scripting: Higher Level Programming for the 21st Century". I
+recommend that you read this paper; see the references for the URL. Ousterhout
+is the inventor of the Tcl language, and therefore argues that Tcl should be
+used for this purpose; he only briefly refers to other languages such as Python,
+Perl, and Lisp/Scheme, but in reality, Ousterhout's argument applies to
+scripting languages in general, since you could equally write extensions for any
+of the languages mentioned above.
+
+
+Prototyping
+-----------
+
+In *The Mythical Man-Month*, Fredrick Brooks suggests the following rule when
+planning software projects: "Plan to throw one away; you will anyway." Brooks
+is saying that the first attempt at a software design often turns out to be
+wrong; unless the problem is very simple or you're an extremely good designer,
+you'll find that new requirements and features become apparent once development
+has actually started. If these new requirements can't be cleanly incorporated
+into the program's structure, you're presented with two unpleasant choices:
+hammer the new features into the program somehow, or scrap everything and write
+a new version of the program, taking the new features into account from the
+beginning.
+
+Python provides you with a good environment for quickly developing an initial
+prototype. That lets you get the overall program structure and logic right, and
+you can fine-tune small details in the fast development cycle that Python
+provides. Once you're satisfied with the GUI interface or program output, you
+can translate the Python code into C++, Fortran, Java, or some other compiled
+language.
+
+Prototyping means you have to be careful not to use too many Python features
+that are hard to implement in your other language. Using ``eval()``, or regular
+expressions, or the :mod:`pickle` module, means that you're going to need C or
+Java libraries for formula evaluation, regular expressions, and serialization,
+for example. But it's not hard to avoid such tricky code, and in the end the
+translation usually isn't very difficult. The resulting code can be rapidly
+debugged, because any serious logical errors will have been removed from the
+prototype, leaving only more minor slip-ups in the translation to track down.
+
+This strategy builds on the earlier discussion of programmability. Using Python
+as glue to connect lower-level components has obvious relevance for constructing
+prototype systems. In this way Python can help you with development, even if
+end users never come in contact with Python code at all. If the performance of
+the Python version is adequate and corporate politics allow it, you may not need
+to do a translation into C or Java, but it can still be faster to develop a
+prototype and then translate it, instead of attempting to produce the final
+version immediately.
+
+One example of this development strategy is Microsoft Merchant Server. Version
+1.0 was written in pure Python, by a company that subsequently was purchased by
+Microsoft. Version 2.0 began to translate the code into C++, shipping with some
+C++code and some Python code. Version 3.0 didn't contain any Python at all; all
+the code had been translated into C++. Even though the product doesn't contain
+a Python interpreter, the Python language has still served a useful purpose by
+speeding up development.
+
+This is a very common use for Python. Past conference papers have also
+described this approach for developing high-level numerical algorithms; see
+David M. Beazley and Peter S. Lomdahl's paper "Feeding a Large-scale Physics
+Application to Python" in the references for a good example. If an algorithm's
+basic operations are things like "Take the inverse of this 4000x4000 matrix",
+and are implemented in some lower-level language, then Python has almost no
+additional performance cost; the extra time required for Python to evaluate an
+expression like ``m.invert()`` is dwarfed by the cost of the actual computation.
+It's particularly good for applications where seemingly endless tweaking is
+required to get things right. GUI interfaces and Web sites are prime examples.
+
+The Python code is also shorter and faster to write (once you're familiar with
+Python), so it's easier to throw it away if you decide your approach was wrong;
+if you'd spent two weeks working on it instead of just two hours, you might
+waste time trying to patch up what you've got out of a natural reluctance to
+admit that those two weeks were wasted. Truthfully, those two weeks haven't
+been wasted, since you've learnt something about the problem and the technology
+you're using to solve it, but it's human nature to view this as a failure of
+some sort.
+
+
+Simplicity and Ease of Understanding
+------------------------------------
+
+Python is definitely *not* a toy language that's only usable for small tasks.
+The language features are general and powerful enough to enable it to be used
+for many different purposes. It's useful at the small end, for 10- or 20-line
+scripts, but it also scales up to larger systems that contain thousands of lines
+of code.
+
+However, this expressiveness doesn't come at the cost of an obscure or tricky
+syntax. While Python has some dark corners that can lead to obscure code, there
+are relatively few such corners, and proper design can isolate their use to only
+a few classes or modules. It's certainly possible to write confusing code by
+using too many features with too little concern for clarity, but most Python
+code can look a lot like a slightly-formalized version of human-understandable
+pseudocode.
+
+In *The New Hacker's Dictionary*, Eric S. Raymond gives the following definition
+for "compact":
+
+.. epigraph::
+
+ Compact *adj.* Of a design, describes the valuable property that it can all be
+ apprehended at once in one's head. This generally means the thing created from
+ the design can be used with greater facility and fewer errors than an equivalent
+ tool that is not compact. Compactness does not imply triviality or lack of
+ power; for example, C is compact and FORTRAN is not, but C is more powerful than
+ FORTRAN. Designs become non-compact through accreting features and cruft that
+ don't merge cleanly into the overall design scheme (thus, some fans of Classic C
+ maintain that ANSI C is no longer compact).
+
+ (From http://www.catb.org/ esr/jargon/html/C/compact.html)
+
+In this sense of the word, Python is quite compact, because the language has
+just a few ideas, which are used in lots of places. Take namespaces, for
+example. Import a module with ``import math``, and you create a new namespace
+called ``math``. Classes are also namespaces that share many of the properties
+of modules, and have a few of their own; for example, you can create instances
+of a class. Instances? They're yet another namespace. Namespaces are currently
+implemented as Python dictionaries, so they have the same methods as the
+standard dictionary data type: .keys() returns all the keys, and so forth.
+
+This simplicity arises from Python's development history. The language syntax
+derives from different sources; ABC, a relatively obscure teaching language, is
+one primary influence, and Modula-3 is another. (For more information about ABC
+and Modula-3, consult their respective Web sites at http://www.cwi.nl/
+steven/abc/ and http://www.m3.org.) Other features have come from C, Icon,
+Algol-68, and even Perl. Python hasn't really innovated very much, but instead
+has tried to keep the language small and easy to learn, building on ideas that
+have been tried in other languages and found useful.
+
+Simplicity is a virtue that should not be underestimated. It lets you learn the
+language more quickly, and then rapidly write code, code that often works the
+first time you run it.
+
+
+Java Integration
+----------------
+
+If you're working with Java, Jython (http://www.jython.org/) is definitely worth
+your attention. Jython is a re-implementation of Python in Java that compiles
+Python code into Java bytecodes. The resulting environment has very tight,
+almost seamless, integration with Java. It's trivial to access Java classes
+from Python, and you can write Python classes that subclass Java classes.
+Jython can be used for prototyping Java applications in much the same way
+CPython is used, and it can also be used for test suites for Java code, or
+embedded in a Java application to add scripting capabilities.
+
+
+Arguments and Rebuttals
+=======================
+
+Let's say that you've decided upon Python as the best choice for your
+application. How can you convince your management, or your fellow developers,
+to use Python? This section lists some common arguments against using Python,
+and provides some possible rebuttals.
+
+**Python is freely available software that doesn't cost anything. How good can
+it be?**
+
+Very good, indeed. These days Linux and Apache, two other pieces of open source
+software, are becoming more respected as alternatives to commercial software,
+but Python hasn't had all the publicity.
+
+Python has been around for several years, with many users and developers.
+Accordingly, the interpreter has been used by many people, and has gotten most
+of the bugs shaken out of it. While bugs are still discovered at intervals,
+they're usually either quite obscure (they'd have to be, for no one to have run
+into them before) or they involve interfaces to external libraries. The
+internals of the language itself are quite stable.
+
+Having the source code should be viewed as making the software available for
+peer review; people can examine the code, suggest (and implement) improvements,
+and track down bugs. To find out more about the idea of open source code, along
+with arguments and case studies supporting it, go to http://www.opensource.org.
+
+**Who's going to support it?**
+
+Python has a sizable community of developers, and the number is still growing.
+The Internet community surrounding the language is an active one, and is worth
+being considered another one of Python's advantages. Most questions posted to
+the comp.lang.python newsgroup are quickly answered by someone.
+
+Should you need to dig into the source code, you'll find it's clear and
+well-organized, so it's not very difficult to write extensions and track down
+bugs yourself. If you'd prefer to pay for support, there are companies and
+individuals who offer commercial support for Python.
+
+**Who uses Python for serious work?**
+
+Lots of people; one interesting thing about Python is the surprising diversity
+of applications that it's been used for. People are using Python to:
+
+* Run Web sites
+
+* Write GUI interfaces
+
+* Control number-crunching code on supercomputers
+
+* Make a commercial application scriptable by embedding the Python interpreter
+ inside it
+
+* Process large XML data sets
+
+* Build test suites for C or Java code
+
+Whatever your application domain is, there's probably someone who's used Python
+for something similar. Yet, despite being useable for such high-end
+applications, Python's still simple enough to use for little jobs.
+
+See http://wiki.python.org/moin/OrganizationsUsingPython for a list of some of
+the organizations that use Python.
+
+**What are the restrictions on Python's use?**
+
+They're practically nonexistent. Consult the :file:`Misc/COPYRIGHT` file in the
+source distribution, or http://www.python.org/doc/Copyright.html for the full
+language, but it boils down to three conditions.
+
+* You have to leave the copyright notice on the software; if you don't include
+ the source code in a product, you have to put the copyright notice in the
+ supporting documentation.
+
+* Don't claim that the institutions that have developed Python endorse your
+ product in any way.
+
+* If something goes wrong, you can't sue for damages. Practically all software
+ licences contain this condition.
+
+Notice that you don't have to provide source code for anything that contains
+Python or is built with it. Also, the Python interpreter and accompanying
+documentation can be modified and redistributed in any way you like, and you
+don't have to pay anyone any licensing fees at all.
+
+**Why should we use an obscure language like Python instead of well-known
+language X?**
+
+I hope this HOWTO, and the documents listed in the final section, will help
+convince you that Python isn't obscure, and has a healthily growing user base.
+One word of advice: always present Python's positive advantages, instead of
+concentrating on language X's failings. People want to know why a solution is
+good, rather than why all the other solutions are bad. So instead of attacking
+a competing solution on various grounds, simply show how Python's virtues can
+help.
+
+
+Useful Resources
+================
+
+http://www.pythonology.com/success
+ The Python Success Stories are a collection of stories from successful users of
+ Python, with the emphasis on business and corporate users.
+
+.. % \term{\url{http://www.fsbassociates.com/books/pythonchpt1.htm}}
+.. % The first chapter of \emph{Internet Programming with Python} also
+.. % examines some of the reasons for using Python. The book is well worth
+.. % buying, but the publishers have made the first chapter available on
+.. % the Web.
+
+http://home.pacbell.net/ouster/scripting.html
+ John Ousterhout's white paper on scripting is a good argument for the utility of
+ scripting languages, though naturally enough, he emphasizes Tcl, the language he
+ developed. Most of the arguments would apply to any scripting language.
+
+http://www.python.org/workshops/1997-10/proceedings/beazley.html
+ The authors, David M. Beazley and Peter S. Lomdahl, describe their use of
+ Python at Los Alamos National Laboratory. It's another good example of how
+ Python can help get real work done. This quotation from the paper has been
+ echoed by many people:
+
+ .. epigraph::
+
+ Originally developed as a large monolithic application for massively parallel
+ processing systems, we have used Python to transform our application into a
+ flexible, highly modular, and extremely powerful system for performing
+ simulation, data analysis, and visualization. In addition, we describe how
+ Python has solved a number of important problems related to the development,
+ debugging, deployment, and maintenance of scientific software.
+
+http://pythonjournal.cognizor.com/pyj1/Everitt-Feit_interview98-V1.html
+ This interview with Andy Feit, discussing Infoseek's use of Python, can be used
+ to show that choosing Python didn't introduce any difficulties into a company's
+ development process, and provided some substantial benefits.
+
+.. % \term{\url{http://www.python.org/psa/Commercial.html}}
+.. % Robin Friedrich wrote this document on how to support Python's use in
+.. % commercial projects.
+
+http://www.python.org/workshops/1997-10/proceedings/stein.ps
+ For the 6th Python conference, Greg Stein presented a paper that traced Python's
+ adoption and usage at a startup called eShop, and later at Microsoft.
+
+http://www.opensource.org
+ Management may be doubtful of the reliability and usefulness of software that
+ wasn't written commercially. This site presents arguments that show how open
+ source software can have considerable advantages over closed-source software.
+
+http://sunsite.unc.edu/LDP/HOWTO/mini/Advocacy.html
+ The Linux Advocacy mini-HOWTO was the inspiration for this document, and is also
+ well worth reading for general suggestions on winning acceptance for a new
+ technology, such as Linux or Python. In general, you won't make much progress
+ by simply attacking existing systems and complaining about their inadequacies;
+ this often ends up looking like unfocused whining. It's much better to point
+ out some of the many areas where Python is an improvement over other systems.
+
--- /dev/null
+**********************************
+ Curses Programming with Python
+**********************************
+
+:Author: A.M. Kuchling, Eric S. Raymond
+:Release: 2.02
+
+
+.. topic:: Abstract
+
+ This document describes how to write text-mode programs with Python 2.x, using
+ the :mod:`curses` extension module to control the display.
+
+
+What is curses?
+===============
+
+The curses library supplies a terminal-independent screen-painting and
+keyboard-handling facility for text-based terminals; such terminals include
+VT100s, the Linux console, and the simulated terminal provided by X11 programs
+such as xterm and rxvt. Display terminals support various control codes to
+perform common operations such as moving the cursor, scrolling the screen, and
+erasing areas. Different terminals use widely differing codes, and often have
+their own minor quirks.
+
+In a world of X displays, one might ask "why bother"? It's true that
+character-cell display terminals are an obsolete technology, but there are
+niches in which being able to do fancy things with them are still valuable. One
+is on small-footprint or embedded Unixes that don't carry an X server. Another
+is for tools like OS installers and kernel configurators that may have to run
+before X is available.
+
+The curses library hides all the details of different terminals, and provides
+the programmer with an abstraction of a display, containing multiple
+non-overlapping windows. The contents of a window can be changed in various
+ways-- adding text, erasing it, changing its appearance--and the curses library
+will automagically figure out what control codes need to be sent to the terminal
+to produce the right output.
+
+The curses library was originally written for BSD Unix; the later System V
+versions of Unix from AT&T added many enhancements and new functions. BSD curses
+is no longer maintained, having been replaced by ncurses, which is an
+open-source implementation of the AT&T interface. If you're using an
+open-source Unix such as Linux or FreeBSD, your system almost certainly uses
+ncurses. Since most current commercial Unix versions are based on System V
+code, all the functions described here will probably be available. The older
+versions of curses carried by some proprietary Unixes may not support
+everything, though.
+
+No one has made a Windows port of the curses module. On a Windows platform, try
+the Console module written by Fredrik Lundh. The Console module provides
+cursor-addressable text output, plus full support for mouse and keyboard input,
+and is available from http://effbot.org/efflib/console.
+
+
+The Python curses module
+------------------------
+
+Thy Python module is a fairly simple wrapper over the C functions provided by
+curses; if you're already familiar with curses programming in C, it's really
+easy to transfer that knowledge to Python. The biggest difference is that the
+Python interface makes things simpler, by merging different C functions such as
+:func:`addstr`, :func:`mvaddstr`, :func:`mvwaddstr`, into a single
+:meth:`addstr` method. You'll see this covered in more detail later.
+
+This HOWTO is simply an introduction to writing text-mode programs with curses
+and Python. It doesn't attempt to be a complete guide to the curses API; for
+that, see the Python library guide's section on ncurses, and the C manual pages
+for ncurses. It will, however, give you the basic ideas.
+
+
+Starting and ending a curses application
+========================================
+
+Before doing anything, curses must be initialized. This is done by calling the
+:func:`initscr` function, which will determine the terminal type, send any
+required setup codes to the terminal, and create various internal data
+structures. If successful, :func:`initscr` returns a window object representing
+the entire screen; this is usually called ``stdscr``, after the name of the
+corresponding C variable. ::
+
+ import curses
+ stdscr = curses.initscr()
+
+Usually curses applications turn off automatic echoing of keys to the screen, in
+order to be able to read keys and only display them under certain circumstances.
+This requires calling the :func:`noecho` function. ::
+
+ curses.noecho()
+
+Applications will also commonly need to react to keys instantly, without
+requiring the Enter key to be pressed; this is called cbreak mode, as opposed to
+the usual buffered input mode. ::
+
+ curses.cbreak()
+
+Terminals usually return special keys, such as the cursor keys or navigation
+keys such as Page Up and Home, as a multibyte escape sequence. While you could
+write your application to expect such sequences and process them accordingly,
+curses can do it for you, returning a special value such as
+:const:`curses.KEY_LEFT`. To get curses to do the job, you'll have to enable
+keypad mode. ::
+
+ stdscr.keypad(1)
+
+Terminating a curses application is much easier than starting one. You'll need
+to call ::
+
+ curses.nocbreak(); stdscr.keypad(0); curses.echo()
+
+to reverse the curses-friendly terminal settings. Then call the :func:`endwin`
+function to restore the terminal to its original operating mode. ::
+
+ curses.endwin()
+
+A common problem when debugging a curses application is to get your terminal
+messed up when the application dies without restoring the terminal to its
+previous state. In Python this commonly happens when your code is buggy and
+raises an uncaught exception. Keys are no longer be echoed to the screen when
+you type them, for example, which makes using the shell difficult.
+
+In Python you can avoid these complications and make debugging much easier by
+importing the module :mod:`curses.wrapper`. It supplies a :func:`wrapper`
+function that takes a callable. It does the initializations described above,
+and also initializes colors if color support is present. It then runs your
+provided callable and finally deinitializes appropriately. The callable is
+called inside a try-catch clause which catches exceptions, performs curses
+deinitialization, and then passes the exception upwards. Thus, your terminal
+won't be left in a funny state on exception.
+
+
+Windows and Pads
+================
+
+Windows are the basic abstraction in curses. A window object represents a
+rectangular area of the screen, and supports various methods to display text,
+erase it, allow the user to input strings, and so forth.
+
+The ``stdscr`` object returned by the :func:`initscr` function is a window
+object that covers the entire screen. Many programs may need only this single
+window, but you might wish to divide the screen into smaller windows, in order
+to redraw or clear them separately. The :func:`newwin` function creates a new
+window of a given size, returning the new window object. ::
+
+ begin_x = 20 ; begin_y = 7
+ height = 5 ; width = 40
+ win = curses.newwin(height, width, begin_y, begin_x)
+
+A word about the coordinate system used in curses: coordinates are always passed
+in the order *y,x*, and the top-left corner of a window is coordinate (0,0).
+This breaks a common convention for handling coordinates, where the *x*
+coordinate usually comes first. This is an unfortunate difference from most
+other computer applications, but it's been part of curses since it was first
+written, and it's too late to change things now.
+
+When you call a method to display or erase text, the effect doesn't immediately
+show up on the display. This is because curses was originally written with slow
+300-baud terminal connections in mind; with these terminals, minimizing the time
+required to redraw the screen is very important. This lets curses accumulate
+changes to the screen, and display them in the most efficient manner. For
+example, if your program displays some characters in a window, and then clears
+the window, there's no need to send the original characters because they'd never
+be visible.
+
+Accordingly, curses requires that you explicitly tell it to redraw windows,
+using the :func:`refresh` method of window objects. In practice, this doesn't
+really complicate programming with curses much. Most programs go into a flurry
+of activity, and then pause waiting for a keypress or some other action on the
+part of the user. All you have to do is to be sure that the screen has been
+redrawn before pausing to wait for user input, by simply calling
+``stdscr.refresh()`` or the :func:`refresh` method of some other relevant
+window.
+
+A pad is a special case of a window; it can be larger than the actual display
+screen, and only a portion of it displayed at a time. Creating a pad simply
+requires the pad's height and width, while refreshing a pad requires giving the
+coordinates of the on-screen area where a subsection of the pad will be
+displayed. ::
+
+ pad = curses.newpad(100, 100)
+ # These loops fill the pad with letters; this is
+ # explained in the next section
+ for y in range(0, 100):
+ for x in range(0, 100):
+ try: pad.addch(y,x, ord('a') + (x*x+y*y) % 26 )
+ except curses.error: pass
+
+ # Displays a section of the pad in the middle of the screen
+ pad.refresh( 0,0, 5,5, 20,75)
+
+The :func:`refresh` call displays a section of the pad in the rectangle
+extending from coordinate (5,5) to coordinate (20,75) on the screen; the upper
+left corner of the displayed section is coordinate (0,0) on the pad. Beyond
+that difference, pads are exactly like ordinary windows and support the same
+methods.
+
+If you have multiple windows and pads on screen there is a more efficient way to
+go, which will prevent annoying screen flicker at refresh time. Use the
+:meth:`noutrefresh` method of each window to update the data structure
+representing the desired state of the screen; then change the physical screen to
+match the desired state in one go with the function :func:`doupdate`. The
+normal :meth:`refresh` method calls :func:`doupdate` as its last act.
+
+
+Displaying Text
+===============
+
+From a C programmer's point of view, curses may sometimes look like a twisty
+maze of functions, all subtly different. For example, :func:`addstr` displays a
+string at the current cursor location in the ``stdscr`` window, while
+:func:`mvaddstr` moves to a given y,x coordinate first before displaying the
+string. :func:`waddstr` is just like :func:`addstr`, but allows specifying a
+window to use, instead of using ``stdscr`` by default. :func:`mvwaddstr` follows
+similarly.
+
+Fortunately the Python interface hides all these details; ``stdscr`` is a window
+object like any other, and methods like :func:`addstr` accept multiple argument
+forms. Usually there are four different forms.
+
++---------------------------------+-----------------------------------------------+
+| Form | Description |
++=================================+===============================================+
+| *str* or *ch* | Display the string *str* or character *ch* at |
+| | the current position |
++---------------------------------+-----------------------------------------------+
+| *str* or *ch*, *attr* | Display the string *str* or character *ch*, |
+| | using attribute *attr* at the current |
+| | position |
++---------------------------------+-----------------------------------------------+
+| *y*, *x*, *str* or *ch* | Move to position *y,x* within the window, and |
+| | display *str* or *ch* |
++---------------------------------+-----------------------------------------------+
+| *y*, *x*, *str* or *ch*, *attr* | Move to position *y,x* within the window, and |
+| | display *str* or *ch*, using attribute *attr* |
++---------------------------------+-----------------------------------------------+
+
+Attributes allow displaying text in highlighted forms, such as in boldface,
+underline, reverse code, or in color. They'll be explained in more detail in
+the next subsection.
+
+The :func:`addstr` function takes a Python string as the value to be displayed,
+while the :func:`addch` functions take a character, which can be either a Python
+string of length 1 or an integer. If it's a string, you're limited to
+displaying characters between 0 and 255. SVr4 curses provides constants for
+extension characters; these constants are integers greater than 255. For
+example, :const:`ACS_PLMINUS` is a +/- symbol, and :const:`ACS_ULCORNER` is the
+upper left corner of a box (handy for drawing borders).
+
+Windows remember where the cursor was left after the last operation, so if you
+leave out the *y,x* coordinates, the string or character will be displayed
+wherever the last operation left off. You can also move the cursor with the
+``move(y,x)`` method. Because some terminals always display a flashing cursor,
+you may want to ensure that the cursor is positioned in some location where it
+won't be distracting; it can be confusing to have the cursor blinking at some
+apparently random location.
+
+If your application doesn't need a blinking cursor at all, you can call
+``curs_set(0)`` to make it invisible. Equivalently, and for compatibility with
+older curses versions, there's a ``leaveok(bool)`` function. When *bool* is
+true, the curses library will attempt to suppress the flashing cursor, and you
+won't need to worry about leaving it in odd locations.
+
+
+Attributes and Color
+--------------------
+
+Characters can be displayed in different ways. Status lines in a text-based
+application are commonly shown in reverse video; a text viewer may need to
+highlight certain words. curses supports this by allowing you to specify an
+attribute for each cell on the screen.
+
+An attribute is a integer, each bit representing a different attribute. You can
+try to display text with multiple attribute bits set, but curses doesn't
+guarantee that all the possible combinations are available, or that they're all
+visually distinct. That depends on the ability of the terminal being used, so
+it's safest to stick to the most commonly available attributes, listed here.
+
++----------------------+--------------------------------------+
+| Attribute | Description |
++======================+======================================+
+| :const:`A_BLINK` | Blinking text |
++----------------------+--------------------------------------+
+| :const:`A_BOLD` | Extra bright or bold text |
++----------------------+--------------------------------------+
+| :const:`A_DIM` | Half bright text |
++----------------------+--------------------------------------+
+| :const:`A_REVERSE` | Reverse-video text |
++----------------------+--------------------------------------+
+| :const:`A_STANDOUT` | The best highlighting mode available |
++----------------------+--------------------------------------+
+| :const:`A_UNDERLINE` | Underlined text |
++----------------------+--------------------------------------+
+
+So, to display a reverse-video status line on the top line of the screen, you
+could code::
+
+ stdscr.addstr(0, 0, "Current mode: Typing mode",
+ curses.A_REVERSE)
+ stdscr.refresh()
+
+The curses library also supports color on those terminals that provide it, The
+most common such terminal is probably the Linux console, followed by color
+xterms.
+
+To use color, you must call the :func:`start_color` function soon after calling
+:func:`initscr`, to initialize the default color set (the
+:func:`curses.wrapper.wrapper` function does this automatically). Once that's
+done, the :func:`has_colors` function returns TRUE if the terminal in use can
+actually display color. (Note: curses uses the American spelling 'color',
+instead of the Canadian/British spelling 'colour'. If you're used to the
+British spelling, you'll have to resign yourself to misspelling it for the sake
+of these functions.)
+
+The curses library maintains a finite number of color pairs, containing a
+foreground (or text) color and a background color. You can get the attribute
+value corresponding to a color pair with the :func:`color_pair` function; this
+can be bitwise-OR'ed with other attributes such as :const:`A_REVERSE`, but
+again, such combinations are not guaranteed to work on all terminals.
+
+An example, which displays a line of text using color pair 1::
+
+ stdscr.addstr( "Pretty text", curses.color_pair(1) )
+ stdscr.refresh()
+
+As I said before, a color pair consists of a foreground and background color.
+:func:`start_color` initializes 8 basic colors when it activates color mode.
+They are: 0:black, 1:red, 2:green, 3:yellow, 4:blue, 5:magenta, 6:cyan, and
+7:white. The curses module defines named constants for each of these colors:
+:const:`curses.COLOR_BLACK`, :const:`curses.COLOR_RED`, and so forth.
+
+The ``init_pair(n, f, b)`` function changes the definition of color pair *n*, to
+foreground color f and background color b. Color pair 0 is hard-wired to white
+on black, and cannot be changed.
+
+Let's put all this together. To change color 1 to red text on a white
+background, you would call::
+
+ curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE)
+
+When you change a color pair, any text already displayed using that color pair
+will change to the new colors. You can also display new text in this color
+with::
+
+ stdscr.addstr(0,0, "RED ALERT!", curses.color_pair(1) )
+
+Very fancy terminals can change the definitions of the actual colors to a given
+RGB value. This lets you change color 1, which is usually red, to purple or
+blue or any other color you like. Unfortunately, the Linux console doesn't
+support this, so I'm unable to try it out, and can't provide any examples. You
+can check if your terminal can do this by calling :func:`can_change_color`,
+which returns TRUE if the capability is there. If you're lucky enough to have
+such a talented terminal, consult your system's man pages for more information.
+
+
+User Input
+==========
+
+The curses library itself offers only very simple input mechanisms. Python's
+support adds a text-input widget that makes up some of the lack.
+
+The most common way to get input to a window is to use its :meth:`getch` method.
+:meth:`getch` pauses and waits for the user to hit a key, displaying it if
+:func:`echo` has been called earlier. You can optionally specify a coordinate
+to which the cursor should be moved before pausing.
+
+It's possible to change this behavior with the method :meth:`nodelay`. After
+``nodelay(1)``, :meth:`getch` for the window becomes non-blocking and returns
+``curses.ERR`` (a value of -1) when no input is ready. There's also a
+:func:`halfdelay` function, which can be used to (in effect) set a timer on each
+:meth:`getch`; if no input becomes available within the number of milliseconds
+specified as the argument to :func:`halfdelay`, curses raises an exception.
+
+The :meth:`getch` method returns an integer; if it's between 0 and 255, it
+represents the ASCII code of the key pressed. Values greater than 255 are
+special keys such as Page Up, Home, or the cursor keys. You can compare the
+value returned to constants such as :const:`curses.KEY_PPAGE`,
+:const:`curses.KEY_HOME`, or :const:`curses.KEY_LEFT`. Usually the main loop of
+your program will look something like this::
+
+ while 1:
+ c = stdscr.getch()
+ if c == ord('p'): PrintDocument()
+ elif c == ord('q'): break # Exit the while()
+ elif c == curses.KEY_HOME: x = y = 0
+
+The :mod:`curses.ascii` module supplies ASCII class membership functions that
+take either integer or 1-character-string arguments; these may be useful in
+writing more readable tests for your command interpreters. It also supplies
+conversion functions that take either integer or 1-character-string arguments
+and return the same type. For example, :func:`curses.ascii.ctrl` returns the
+control character corresponding to its argument.
+
+There's also a method to retrieve an entire string, :const:`getstr()`. It isn't
+used very often, because its functionality is quite limited; the only editing
+keys available are the backspace key and the Enter key, which terminates the
+string. It can optionally be limited to a fixed number of characters. ::
+
+ curses.echo() # Enable echoing of characters
+
+ # Get a 15-character string, with the cursor on the top line
+ s = stdscr.getstr(0,0, 15)
+
+The Python :mod:`curses.textpad` module supplies something better. With it, you
+can turn a window into a text box that supports an Emacs-like set of
+keybindings. Various methods of :class:`Textbox` class support editing with
+input validation and gathering the edit results either with or without trailing
+spaces. See the library documentation on :mod:`curses.textpad` for the
+details.
+
+
+For More Information
+====================
+
+This HOWTO didn't cover some advanced topics, such as screen-scraping or
+capturing mouse events from an xterm instance. But the Python library page for
+the curses modules is now pretty complete. You should browse it next.
+
+If you're in doubt about the detailed behavior of any of the ncurses entry
+points, consult the manual pages for your curses implementation, whether it's
+ncurses or a proprietary Unix vendor's. The manual pages will document any
+quirks, and provide complete lists of all the functions, attributes, and
+:const:`ACS_\*` characters available to you.
+
+Because the curses API is so large, some functions aren't supported in the
+Python interface, not because they're difficult to implement, but because no one
+has needed them yet. Feel free to add them and then submit a patch. Also, we
+don't yet have support for the menus or panels libraries associated with
+ncurses; feel free to add that.
+
+If you write an interesting little program, feel free to contribute it as
+another demo. We can always use more of them!
+
+The ncurses FAQ: http://dickey.his.com/ncurses/ncurses.faq.html
+
--- /dev/null
+************************************
+ Idioms and Anti-Idioms in Python
+************************************
+
+:Author: Moshe Zadka
+
+This document is placed in the public doman.
+
+
+.. topic:: Abstract
+
+ This document can be considered a companion to the tutorial. It shows how to use
+ Python, and even more importantly, how *not* to use Python.
+
+
+Language Constructs You Should Not Use
+======================================
+
+While Python has relatively few gotchas compared to other languages, it still
+has some constructs which are only useful in corner cases, or are plain
+dangerous.
+
+
+from module import \*
+---------------------
+
+
+Inside Function Definitions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``from module import *`` is *invalid* inside function definitions. While many
+versions of Python do not check for the invalidity, it does not make it more
+valid, no more then having a smart lawyer makes a man innocent. Do not use it
+like that ever. Even in versions where it was accepted, it made the function
+execution slower, because the compiler could not be certain which names are
+local and which are global. In Python 2.1 this construct causes warnings, and
+sometimes even errors.
+
+
+At Module Level
+^^^^^^^^^^^^^^^
+
+While it is valid to use ``from module import *`` at module level it is usually
+a bad idea. For one, this loses an important property Python otherwise has ---
+you can know where each toplevel name is defined by a simple "search" function
+in your favourite editor. You also open yourself to trouble in the future, if
+some module grows additional functions or classes.
+
+One of the most awful question asked on the newsgroup is why this code::
+
+ f = open("www")
+ f.read()
+
+does not work. Of course, it works just fine (assuming you have a file called
+"www".) But it does not work if somewhere in the module, the statement ``from os
+import *`` is present. The :mod:`os` module has a function called :func:`open`
+which returns an integer. While it is very useful, shadowing builtins is one of
+its least useful properties.
+
+Remember, you can never know for sure what names a module exports, so either
+take what you need --- ``from module import name1, name2``, or keep them in the
+module and access on a per-need basis --- ``import module;print module.name``.
+
+
+When It Is Just Fine
+^^^^^^^^^^^^^^^^^^^^
+
+There are situations in which ``from module import *`` is just fine:
+
+* The interactive prompt. For example, ``from math import *`` makes Python an
+ amazing scientific calculator.
+
+* When extending a module in C with a module in Python.
+
+* When the module advertises itself as ``from import *`` safe.
+
+
+Unadorned :keyword:`exec`, :func:`execfile` and friends
+-------------------------------------------------------
+
+The word "unadorned" refers to the use without an explicit dictionary, in which
+case those constructs evaluate code in the *current* environment. This is
+dangerous for the same reasons ``from import *`` is dangerous --- it might step
+over variables you are counting on and mess up things for the rest of your code.
+Simply do not do that.
+
+Bad examples::
+
+ >>> for name in sys.argv[1:]:
+ >>> exec "%s=1" % name
+ >>> def func(s, **kw):
+ >>> for var, val in kw.items():
+ >>> exec "s.%s=val" % var # invalid!
+ >>> execfile("handler.py")
+ >>> handle()
+
+Good examples::
+
+ >>> d = {}
+ >>> for name in sys.argv[1:]:
+ >>> d[name] = 1
+ >>> def func(s, **kw):
+ >>> for var, val in kw.items():
+ >>> setattr(s, var, val)
+ >>> d={}
+ >>> execfile("handle.py", d, d)
+ >>> handle = d['handle']
+ >>> handle()
+
+
+from module import name1, name2
+-------------------------------
+
+This is a "don't" which is much weaker then the previous "don't"s but is still
+something you should not do if you don't have good reasons to do that. The
+reason it is usually bad idea is because you suddenly have an object which lives
+in two seperate namespaces. When the binding in one namespace changes, the
+binding in the other will not, so there will be a discrepancy between them. This
+happens when, for example, one module is reloaded, or changes the definition of
+a function at runtime.
+
+Bad example::
+
+ # foo.py
+ a = 1
+
+ # bar.py
+ from foo import a
+ if something():
+ a = 2 # danger: foo.a != a
+
+Good example::
+
+ # foo.py
+ a = 1
+
+ # bar.py
+ import foo
+ if something():
+ foo.a = 2
+
+
+except:
+-------
+
+Python has the ``except:`` clause, which catches all exceptions. Since *every*
+error in Python raises an exception, this makes many programming errors look
+like runtime problems, and hinders the debugging process.
+
+The following code shows a great example::
+
+ try:
+ foo = opne("file") # misspelled "open"
+ except:
+ sys.exit("could not open file!")
+
+The second line triggers a :exc:`NameError` which is caught by the except
+clause. The program will exit, and you will have no idea that this has nothing
+to do with the readability of ``"file"``.
+
+The example above is better written ::
+
+ try:
+ foo = opne("file") # will be changed to "open" as soon as we run it
+ except IOError:
+ sys.exit("could not open file")
+
+There are some situations in which the ``except:`` clause is useful: for
+example, in a framework when running callbacks, it is good not to let any
+callback disturb the framework.
+
+
+Exceptions
+==========
+
+Exceptions are a useful feature of Python. You should learn to raise them
+whenever something unexpected occurs, and catch them only where you can do
+something about them.
+
+The following is a very popular anti-idiom ::
+
+ def get_status(file):
+ if not os.path.exists(file):
+ print "file not found"
+ sys.exit(1)
+ return open(file).readline()
+
+Consider the case the file gets deleted between the time the call to
+:func:`os.path.exists` is made and the time :func:`open` is called. That means
+the last line will throw an :exc:`IOError`. The same would happen if *file*
+exists but has no read permission. Since testing this on a normal machine on
+existing and non-existing files make it seem bugless, that means in testing the
+results will seem fine, and the code will get shipped. Then an unhandled
+:exc:`IOError` escapes to the user, who has to watch the ugly traceback.
+
+Here is a better way to do it. ::
+
+ def get_status(file):
+ try:
+ return open(file).readline()
+ except (IOError, OSError):
+ print "file not found"
+ sys.exit(1)
+
+In this version, \*either\* the file gets opened and the line is read (so it
+works even on flaky NFS or SMB connections), or the message is printed and the
+application aborted.
+
+Still, :func:`get_status` makes too many assumptions --- that it will only be
+used in a short running script, and not, say, in a long running server. Sure,
+the caller could do something like ::
+
+ try:
+ status = get_status(log)
+ except SystemExit:
+ status = None
+
+So, try to make as few ``except`` clauses in your code --- those will usually be
+a catch-all in the :func:`main`, or inside calls which should always succeed.
+
+So, the best version is probably ::
+
+ def get_status(file):
+ return open(file).readline()
+
+The caller can deal with the exception if it wants (for example, if it tries
+several files in a loop), or just let the exception filter upwards to *its*
+caller.
+
+The last version is not very good either --- due to implementation details, the
+file would not be closed when an exception is raised until the handler finishes,
+and perhaps not at all in non-C implementations (e.g., Jython). ::
+
+ def get_status(file):
+ fp = open(file)
+ try:
+ return fp.readline()
+ finally:
+ fp.close()
+
+
+Using the Batteries
+===================
+
+Every so often, people seem to be writing stuff in the Python library again,
+usually poorly. While the occasional module has a poor interface, it is usually
+much better to use the rich standard library and data types that come with
+Python then inventing your own.
+
+A useful module very few people know about is :mod:`os.path`. It always has the
+correct path arithmetic for your operating system, and will usually be much
+better then whatever you come up with yourself.
+
+Compare::
+
+ # ugh!
+ return dir+"/"+file
+ # better
+ return os.path.join(dir, file)
+
+More useful functions in :mod:`os.path`: :func:`basename`, :func:`dirname` and
+:func:`splitext`.
+
+There are also many useful builtin functions people seem not to be aware of for
+some reason: :func:`min` and :func:`max` can find the minimum/maximum of any
+sequence with comparable semantics, for example, yet many people write their own
+:func:`max`/:func:`min`. Another highly useful function is :func:`reduce`. A
+classical use of :func:`reduce` is something like ::
+
+ import sys, operator
+ nums = map(float, sys.argv[1:])
+ print reduce(operator.add, nums)/len(nums)
+
+This cute little script prints the average of all numbers given on the command
+line. The :func:`reduce` adds up all the numbers, and the rest is just some
+pre- and postprocessing.
+
+On the same note, note that :func:`float`, :func:`int` and :func:`long` all
+accept arguments of type string, and so are suited to parsing --- assuming you
+are ready to deal with the :exc:`ValueError` they raise.
+
+
+Using Backslash to Continue Statements
+======================================
+
+Since Python treats a newline as a statement terminator, and since statements
+are often more then is comfortable to put in one line, many people do::
+
+ if foo.bar()['first'][0] == baz.quux(1, 2)[5:9] and \
+ calculate_number(10, 20) != forbulate(500, 360):
+ pass
+
+You should realize that this is dangerous: a stray space after the ``XXX`` would
+make this line wrong, and stray spaces are notoriously hard to see in editors.
+In this case, at least it would be a syntax error, but if the code was::
+
+ value = foo.bar()['first'][0]*baz.quux(1, 2)[5:9] \
+ + calculate_number(10, 20)*forbulate(500, 360)
+
+then it would just be subtly wrong.
+
+It is usually much better to use the implicit continuation inside parenthesis:
+
+This version is bulletproof::
+
+ value = (foo.bar()['first'][0]*baz.quux(1, 2)[5:9]
+ + calculate_number(10, 20)*forbulate(500, 360))
+
--- /dev/null
+********************************
+ Functional Programming HOWTO
+********************************
+
+:Author: \A. M. Kuchling
+:Release: 0.30
+
+(This is a first draft. Please send comments/error reports/suggestions to
+amk@amk.ca. This URL is probably not going to be the final location of the
+document, so be careful about linking to it -- you may want to add a
+disclaimer.)
+
+In this document, we'll take a tour of Python's features suitable for
+implementing programs in a functional style. After an introduction to the
+concepts of functional programming, we'll look at language features such as
+iterators and generators and relevant library modules such as :mod:`itertools`
+and :mod:`functools`.
+
+
+Introduction
+============
+
+This section explains the basic concept of functional programming; if you're
+just interested in learning about Python language features, skip to the next
+section.
+
+Programming languages support decomposing problems in several different ways:
+
+* Most programming languages are **procedural**: programs are lists of
+ instructions that tell the computer what to do with the program's input. C,
+ Pascal, and even Unix shells are procedural languages.
+
+* In **declarative** languages, you write a specification that describes the
+ problem to be solved, and the language implementation figures out how to
+ perform the computation efficiently. SQL is the declarative language you're
+ most likely to be familiar with; a SQL query describes the data set you want
+ to retrieve, and the SQL engine decides whether to scan tables or use indexes,
+ which subclauses should be performed first, etc.
+
+* **Object-oriented** programs manipulate collections of objects. Objects have
+ internal state and support methods that query or modify this internal state in
+ some way. Smalltalk and Java are object-oriented languages. C++ and Python
+ are languages that support object-oriented programming, but don't force the
+ use of object-oriented features.
+
+* **Functional** programming decomposes a problem into a set of functions.
+ Ideally, functions only take inputs and produce outputs, and don't have any
+ internal state that affects the output produced for a given input. Well-known
+ functional languages include the ML family (Standard ML, OCaml, and other
+ variants) and Haskell.
+
+The designers of some computer languages have chosen one approach to programming
+that's emphasized. This often makes it difficult to write programs that use a
+different approach. Other languages are multi-paradigm languages that support
+several different approaches. Lisp, C++, and Python are multi-paradigm; you can
+write programs or libraries that are largely procedural, object-oriented, or
+functional in all of these languages. In a large program, different sections
+might be written using different approaches; the GUI might be object-oriented
+while the processing logic is procedural or functional, for example.
+
+In a functional program, input flows through a set of functions. Each function
+operates on its input and produces some output. Functional style frowns upon
+functions with side effects that modify internal state or make other changes
+that aren't visible in the function's return value. Functions that have no side
+effects at all are called **purely functional**. Avoiding side effects means
+not using data structures that get updated as a program runs; every function's
+output must only depend on its input.
+
+Some languages are very strict about purity and don't even have assignment
+statements such as ``a=3`` or ``c = a + b``, but it's difficult to avoid all
+side effects. Printing to the screen or writing to a disk file are side
+effects, for example. For example, in Python a ``print`` statement or a
+``time.sleep(1)`` both return no useful value; they're only called for their
+side effects of sending some text to the screen or pausing execution for a
+second.
+
+Python programs written in functional style usually won't go to the extreme of
+avoiding all I/O or all assignments; instead, they'll provide a
+functional-appearing interface but will use non-functional features internally.
+For example, the implementation of a function will still use assignments to
+local variables, but won't modify global variables or have other side effects.
+
+Functional programming can be considered the opposite of object-oriented
+programming. Objects are little capsules containing some internal state along
+with a collection of method calls that let you modify this state, and programs
+consist of making the right set of state changes. Functional programming wants
+to avoid state changes as much as possible and works with data flowing between
+functions. In Python you might combine the two approaches by writing functions
+that take and return instances representing objects in your application (e-mail
+messages, transactions, etc.).
+
+Functional design may seem like an odd constraint to work under. Why should you
+avoid objects and side effects? There are theoretical and practical advantages
+to the functional style:
+
+* Formal provability.
+* Modularity.
+* Composability.
+* Ease of debugging and testing.
+
+Formal provability
+------------------
+
+A theoretical benefit is that it's easier to construct a mathematical proof that
+a functional program is correct.
+
+For a long time researchers have been interested in finding ways to
+mathematically prove programs correct. This is different from testing a program
+on numerous inputs and concluding that its output is usually correct, or reading
+a program's source code and concluding that the code looks right; the goal is
+instead a rigorous proof that a program produces the right result for all
+possible inputs.
+
+The technique used to prove programs correct is to write down **invariants**,
+properties of the input data and of the program's variables that are always
+true. For each line of code, you then show that if invariants X and Y are true
+**before** the line is executed, the slightly different invariants X' and Y' are
+true **after** the line is executed. This continues until you reach the end of
+the program, at which point the invariants should match the desired conditions
+on the program's output.
+
+Functional programming's avoidance of assignments arose because assignments are
+difficult to handle with this technique; assignments can break invariants that
+were true before the assignment without producing any new invariants that can be
+propagated onward.
+
+Unfortunately, proving programs correct is largely impractical and not relevant
+to Python software. Even trivial programs require proofs that are several pages
+long; the proof of correctness for a moderately complicated program would be
+enormous, and few or none of the programs you use daily (the Python interpreter,
+your XML parser, your web browser) could be proven correct. Even if you wrote
+down or generated a proof, there would then be the question of verifying the
+proof; maybe there's an error in it, and you wrongly believe you've proved the
+program correct.
+
+Modularity
+----------
+
+A more practical benefit of functional programming is that it forces you to
+break apart your problem into small pieces. Programs are more modular as a
+result. It's easier to specify and write a small function that does one thing
+than a large function that performs a complicated transformation. Small
+functions are also easier to read and to check for errors.
+
+
+Ease of debugging and testing
+-----------------------------
+
+Testing and debugging a functional-style program is easier.
+
+Debugging is simplified because functions are generally small and clearly
+specified. When a program doesn't work, each function is an interface point
+where you can check that the data are correct. You can look at the intermediate
+inputs and outputs to quickly isolate the function that's responsible for a bug.
+
+Testing is easier because each function is a potential subject for a unit test.
+Functions don't depend on system state that needs to be replicated before
+running a test; instead you only have to synthesize the right input and then
+check that the output matches expectations.
+
+
+
+Composability
+-------------
+
+As you work on a functional-style program, you'll write a number of functions
+with varying inputs and outputs. Some of these functions will be unavoidably
+specialized to a particular application, but others will be useful in a wide
+variety of programs. For example, a function that takes a directory path and
+returns all the XML files in the directory, or a function that takes a filename
+and returns its contents, can be applied to many different situations.
+
+Over time you'll form a personal library of utilities. Often you'll assemble
+new programs by arranging existing functions in a new configuration and writing
+a few functions specialized for the current task.
+
+
+
+Iterators
+=========
+
+I'll start by looking at a Python language feature that's an important
+foundation for writing functional-style programs: iterators.
+
+An iterator is an object representing a stream of data; this object returns the
+data one element at a time. A Python iterator must support a method called
+``next()`` that takes no arguments and always returns the next element of the
+stream. If there are no more elements in the stream, ``next()`` must raise the
+``StopIteration`` exception. Iterators don't have to be finite, though; it's
+perfectly reasonable to write an iterator that produces an infinite stream of
+data.
+
+The built-in :func:`iter` function takes an arbitrary object and tries to return
+an iterator that will return the object's contents or elements, raising
+:exc:`TypeError` if the object doesn't support iteration. Several of Python's
+built-in data types support iteration, the most common being lists and
+dictionaries. An object is called an **iterable** object if you can get an
+iterator for it.
+
+You can experiment with the iteration interface manually::
+
+ >>> L = [1,2,3]
+ >>> it = iter(L)
+ >>> print it
+ <iterator object at 0x8116870>
+ >>> it.next()
+ 1
+ >>> it.next()
+ 2
+ >>> it.next()
+ 3
+ >>> it.next()
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ StopIteration
+ >>>
+
+Python expects iterable objects in several different contexts, the most
+important being the ``for`` statement. In the statement ``for X in Y``, Y must
+be an iterator or some object for which ``iter()`` can create an iterator.
+These two statements are equivalent::
+
+ for i in iter(obj):
+ print i
+
+ for i in obj:
+ print i
+
+Iterators can be materialized as lists or tuples by using the :func:`list` or
+:func:`tuple` constructor functions::
+
+ >>> L = [1,2,3]
+ >>> iterator = iter(L)
+ >>> t = tuple(iterator)
+ >>> t
+ (1, 2, 3)
+
+Sequence unpacking also supports iterators: if you know an iterator will return
+N elements, you can unpack them into an N-tuple::
+
+ >>> L = [1,2,3]
+ >>> iterator = iter(L)
+ >>> a,b,c = iterator
+ >>> a,b,c
+ (1, 2, 3)
+
+Built-in functions such as :func:`max` and :func:`min` can take a single
+iterator argument and will return the largest or smallest element. The ``"in"``
+and ``"not in"`` operators also support iterators: ``X in iterator`` is true if
+X is found in the stream returned by the iterator. You'll run into obvious
+problems if the iterator is infinite; ``max()``, ``min()``, and ``"not in"``
+will never return, and if the element X never appears in the stream, the
+``"in"`` operator won't return either.
+
+Note that you can only go forward in an iterator; there's no way to get the
+previous element, reset the iterator, or make a copy of it. Iterator objects
+can optionally provide these additional capabilities, but the iterator protocol
+only specifies the ``next()`` method. Functions may therefore consume all of
+the iterator's output, and if you need to do something different with the same
+stream, you'll have to create a new iterator.
+
+
+
+Data Types That Support Iterators
+---------------------------------
+
+We've already seen how lists and tuples support iterators. In fact, any Python
+sequence type, such as strings, will automatically support creation of an
+iterator.
+
+Calling :func:`iter` on a dictionary returns an iterator that will loop over the
+dictionary's keys::
+
+ >>> m = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6,
+ ... 'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12}
+ >>> for key in m:
+ ... print key, m[key]
+ Mar 3
+ Feb 2
+ Aug 8
+ Sep 9
+ May 5
+ Jun 6
+ Jul 7
+ Jan 1
+ Apr 4
+ Nov 11
+ Dec 12
+ Oct 10
+
+Note that the order is essentially random, because it's based on the hash
+ordering of the objects in the dictionary.
+
+Applying ``iter()`` to a dictionary always loops over the keys, but dictionaries
+have methods that return other iterators. If you want to iterate over keys,
+values, or key/value pairs, you can explicitly call the ``iterkeys()``,
+``itervalues()``, or ``iteritems()`` methods to get an appropriate iterator.
+
+The :func:`dict` constructor can accept an iterator that returns a finite stream
+of ``(key, value)`` tuples::
+
+ >>> L = [('Italy', 'Rome'), ('France', 'Paris'), ('US', 'Washington DC')]
+ >>> dict(iter(L))
+ {'Italy': 'Rome', 'US': 'Washington DC', 'France': 'Paris'}
+
+Files also support iteration by calling the ``readline()`` method until there
+are no more lines in the file. This means you can read each line of a file like
+this::
+
+ for line in file:
+ # do something for each line
+ ...
+
+Sets can take their contents from an iterable and let you iterate over the set's
+elements::
+
+ S = set((2, 3, 5, 7, 11, 13))
+ for i in S:
+ print i
+
+
+
+Generator expressions and list comprehensions
+=============================================
+
+Two common operations on an iterator's output are 1) performing some operation
+for every element, 2) selecting a subset of elements that meet some condition.
+For example, given a list of strings, you might want to strip off trailing
+whitespace from each line or extract all the strings containing a given
+substring.
+
+List comprehensions and generator expressions (short form: "listcomps" and
+"genexps") are a concise notation for such operations, borrowed from the
+functional programming language Haskell (http://www.haskell.org). You can strip
+all the whitespace from a stream of strings with the following code::
+
+ line_list = [' line 1\n', 'line 2 \n', ...]
+
+ # Generator expression -- returns iterator
+ stripped_iter = (line.strip() for line in line_list)
+
+ # List comprehension -- returns list
+ stripped_list = [line.strip() for line in line_list]
+
+You can select only certain elements by adding an ``"if"`` condition::
+
+ stripped_list = [line.strip() for line in line_list
+ if line != ""]
+
+With a list comprehension, you get back a Python list; ``stripped_list`` is a
+list containing the resulting lines, not an iterator. Generator expressions
+return an iterator that computes the values as necessary, not needing to
+materialize all the values at once. This means that list comprehensions aren't
+useful if you're working with iterators that return an infinite stream or a very
+large amount of data. Generator expressions are preferable in these situations.
+
+Generator expressions are surrounded by parentheses ("()") and list
+comprehensions are surrounded by square brackets ("[]"). Generator expressions
+have the form::
+
+ ( expression for expr in sequence1
+ if condition1
+ for expr2 in sequence2
+ if condition2
+ for expr3 in sequence3 ...
+ if condition3
+ for exprN in sequenceN
+ if conditionN )
+
+Again, for a list comprehension only the outside brackets are different (square
+brackets instead of parentheses).
+
+The elements of the generated output will be the successive values of
+``expression``. The ``if`` clauses are all optional; if present, ``expression``
+is only evaluated and added to the result when ``condition`` is true.
+
+Generator expressions always have to be written inside parentheses, but the
+parentheses signalling a function call also count. If you want to create an
+iterator that will be immediately passed to a function you can write::
+
+ obj_total = sum(obj.count for obj in list_all_objects())
+
+The ``for...in`` clauses contain the sequences to be iterated over. The
+sequences do not have to be the same length, because they are iterated over from
+left to right, **not** in parallel. For each element in ``sequence1``,
+``sequence2`` is looped over from the beginning. ``sequence3`` is then looped
+over for each resulting pair of elements from ``sequence1`` and ``sequence2``.
+
+To put it another way, a list comprehension or generator expression is
+equivalent to the following Python code::
+
+ for expr1 in sequence1:
+ if not (condition1):
+ continue # Skip this element
+ for expr2 in sequence2:
+ if not (condition2):
+ continue # Skip this element
+ ...
+ for exprN in sequenceN:
+ if not (conditionN):
+ continue # Skip this element
+
+ # Output the value of
+ # the expression.
+
+This means that when there are multiple ``for...in`` clauses but no ``if``
+clauses, the length of the resulting output will be equal to the product of the
+lengths of all the sequences. If you have two lists of length 3, the output
+list is 9 elements long::
+
+ seq1 = 'abc'
+ seq2 = (1,2,3)
+ >>> [ (x,y) for x in seq1 for y in seq2]
+ [('a', 1), ('a', 2), ('a', 3),
+ ('b', 1), ('b', 2), ('b', 3),
+ ('c', 1), ('c', 2), ('c', 3)]
+
+To avoid introducing an ambiguity into Python's grammar, if ``expression`` is
+creating a tuple, it must be surrounded with parentheses. The first list
+comprehension below is a syntax error, while the second one is correct::
+
+ # Syntax error
+ [ x,y for x in seq1 for y in seq2]
+ # Correct
+ [ (x,y) for x in seq1 for y in seq2]
+
+
+Generators
+==========
+
+Generators are a special class of functions that simplify the task of writing
+iterators. Regular functions compute a value and return it, but generators
+return an iterator that returns a stream of values.
+
+You're doubtless familiar with how regular function calls work in Python or C.
+When you call a function, it gets a private namespace where its local variables
+are created. When the function reaches a ``return`` statement, the local
+variables are destroyed and the value is returned to the caller. A later call
+to the same function creates a new private namespace and a fresh set of local
+variables. But, what if the local variables weren't thrown away on exiting a
+function? What if you could later resume the function where it left off? This
+is what generators provide; they can be thought of as resumable functions.
+
+Here's the simplest example of a generator function::
+
+ def generate_ints(N):
+ for i in range(N):
+ yield i
+
+Any function containing a ``yield`` keyword is a generator function; this is
+detected by Python's bytecode compiler which compiles the function specially as
+a result.
+
+When you call a generator function, it doesn't return a single value; instead it
+returns a generator object that supports the iterator protocol. On executing
+the ``yield`` expression, the generator outputs the value of ``i``, similar to a
+``return`` statement. The big difference between ``yield`` and a ``return``
+statement is that on reaching a ``yield`` the generator's state of execution is
+suspended and local variables are preserved. On the next call to the
+generator's ``.next()`` method, the function will resume executing.
+
+Here's a sample usage of the ``generate_ints()`` generator::
+
+ >>> gen = generate_ints(3)
+ >>> gen
+ <generator object at 0x8117f90>
+ >>> gen.next()
+ 0
+ >>> gen.next()
+ 1
+ >>> gen.next()
+ 2
+ >>> gen.next()
+ Traceback (most recent call last):
+ File "stdin", line 1, in ?
+ File "stdin", line 2, in generate_ints
+ StopIteration
+
+You could equally write ``for i in generate_ints(5)``, or ``a,b,c =
+generate_ints(3)``.
+
+Inside a generator function, the ``return`` statement can only be used without a
+value, and signals the end of the procession of values; after executing a
+``return`` the generator cannot return any further values. ``return`` with a
+value, such as ``return 5``, is a syntax error inside a generator function. The
+end of the generator's results can also be indicated by raising
+``StopIteration`` manually, or by just letting the flow of execution fall off
+the bottom of the function.
+
+You could achieve the effect of generators manually by writing your own class
+and storing all the local variables of the generator as instance variables. For
+example, returning a list of integers could be done by setting ``self.count`` to
+0, and having the ``next()`` method increment ``self.count`` and return it.
+However, for a moderately complicated generator, writing a corresponding class
+can be much messier.
+
+The test suite included with Python's library, ``test_generators.py``, contains
+a number of more interesting examples. Here's one generator that implements an
+in-order traversal of a tree using generators recursively.
+
+::
+
+ # A recursive generator that generates Tree leaves in in-order.
+ def inorder(t):
+ if t:
+ for x in inorder(t.left):
+ yield x
+
+ yield t.label
+
+ for x in inorder(t.right):
+ yield x
+
+Two other examples in ``test_generators.py`` produce solutions for the N-Queens
+problem (placing N queens on an NxN chess board so that no queen threatens
+another) and the Knight's Tour (finding a route that takes a knight to every
+square of an NxN chessboard without visiting any square twice).
+
+
+
+Passing values into a generator
+-------------------------------
+
+In Python 2.4 and earlier, generators only produced output. Once a generator's
+code was invoked to create an iterator, there was no way to pass any new
+information into the function when its execution is resumed. You could hack
+together this ability by making the generator look at a global variable or by
+passing in some mutable object that callers then modify, but these approaches
+are messy.
+
+In Python 2.5 there's a simple way to pass values into a generator.
+:keyword:`yield` became an expression, returning a value that can be assigned to
+a variable or otherwise operated on::
+
+ val = (yield i)
+
+I recommend that you **always** put parentheses around a ``yield`` expression
+when you're doing something with the returned value, as in the above example.
+The parentheses aren't always necessary, but it's easier to always add them
+instead of having to remember when they're needed.
+
+(PEP 342 explains the exact rules, which are that a ``yield``-expression must
+always be parenthesized except when it occurs at the top-level expression on the
+right-hand side of an assignment. This means you can write ``val = yield i``
+but have to use parentheses when there's an operation, as in ``val = (yield i)
++ 12``.)
+
+Values are sent into a generator by calling its ``send(value)`` method. This
+method resumes the generator's code and the ``yield`` expression returns the
+specified value. If the regular ``next()`` method is called, the ``yield``
+returns ``None``.
+
+Here's a simple counter that increments by 1 and allows changing the value of
+the internal counter.
+
+::
+
+ def counter (maximum):
+ i = 0
+ while i < maximum:
+ val = (yield i)
+ # If value provided, change counter
+ if val is not None:
+ i = val
+ else:
+ i += 1
+
+And here's an example of changing the counter:
+
+ >>> it = counter(10)
+ >>> print it.next()
+ 0
+ >>> print it.next()
+ 1
+ >>> print it.send(8)
+ 8
+ >>> print it.next()
+ 9
+ >>> print it.next()
+ Traceback (most recent call last):
+ File ``t.py'', line 15, in ?
+ print it.next()
+ StopIteration
+
+Because ``yield`` will often be returning ``None``, you should always check for
+this case. Don't just use its value in expressions unless you're sure that the
+``send()`` method will be the only method used resume your generator function.
+
+In addition to ``send()``, there are two other new methods on generators:
+
+* ``throw(type, value=None, traceback=None)`` is used to raise an exception
+ inside the generator; the exception is raised by the ``yield`` expression
+ where the generator's execution is paused.
+
+* ``close()`` raises a :exc:`GeneratorExit` exception inside the generator to
+ terminate the iteration. On receiving this exception, the generator's code
+ must either raise :exc:`GeneratorExit` or :exc:`StopIteration`; catching the
+ exception and doing anything else is illegal and will trigger a
+ :exc:`RuntimeError`. ``close()`` will also be called by Python's garbage
+ collector when the generator is garbage-collected.
+
+ If you need to run cleanup code when a :exc:`GeneratorExit` occurs, I suggest
+ using a ``try: ... finally:`` suite instead of catching :exc:`GeneratorExit`.
+
+The cumulative effect of these changes is to turn generators from one-way
+producers of information into both producers and consumers.
+
+Generators also become **coroutines**, a more generalized form of subroutines.
+Subroutines are entered at one point and exited at another point (the top of the
+function, and a ``return`` statement), but coroutines can be entered, exited,
+and resumed at many different points (the ``yield`` statements).
+
+
+Built-in functions
+==================
+
+Let's look in more detail at built-in functions often used with iterators.
+
+Two Python's built-in functions, :func:`map` and :func:`filter`, are somewhat
+obsolete; they duplicate the features of list comprehensions but return actual
+lists instead of iterators.
+
+``map(f, iterA, iterB, ...)`` returns a list containing ``f(iterA[0], iterB[0]),
+f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ...``.
+
+::
+
+ def upper(s):
+ return s.upper()
+ map(upper, ['sentence', 'fragment']) =>
+ ['SENTENCE', 'FRAGMENT']
+
+ [upper(s) for s in ['sentence', 'fragment']] =>
+ ['SENTENCE', 'FRAGMENT']
+
+As shown above, you can achieve the same effect with a list comprehension. The
+:func:`itertools.imap` function does the same thing but can handle infinite
+iterators; it'll be discussed later, in the section on the :mod:`itertools` module.
+
+``filter(predicate, iter)`` returns a list that contains all the sequence
+elements that meet a certain condition, and is similarly duplicated by list
+comprehensions. A **predicate** is a function that returns the truth value of
+some condition; for use with :func:`filter`, the predicate must take a single
+value.
+
+::
+
+ def is_even(x):
+ return (x % 2) == 0
+
+ filter(is_even, range(10)) =>
+ [0, 2, 4, 6, 8]
+
+This can also be written as a list comprehension::
+
+ >>> [x for x in range(10) if is_even(x)]
+ [0, 2, 4, 6, 8]
+
+:func:`filter` also has a counterpart in the :mod:`itertools` module,
+:func:`itertools.ifilter`, that returns an iterator and can therefore handle
+infinite sequences just as :func:`itertools.imap` can.
+
+``reduce(func, iter, [initial_value])`` doesn't have a counterpart in the
+:mod:`itertools` module because it cumulatively performs an operation on all the
+iterable's elements and therefore can't be applied to infinite iterables.
+``func`` must be a function that takes two elements and returns a single value.
+:func:`reduce` takes the first two elements A and B returned by the iterator and
+calculates ``func(A, B)``. It then requests the third element, C, calculates
+``func(func(A, B), C)``, combines this result with the fourth element returned,
+and continues until the iterable is exhausted. If the iterable returns no
+values at all, a :exc:`TypeError` exception is raised. If the initial value is
+supplied, it's used as a starting point and ``func(initial_value, A)`` is the
+first calculation.
+
+::
+
+ import operator
+ reduce(operator.concat, ['A', 'BB', 'C']) =>
+ 'ABBC'
+ reduce(operator.concat, []) =>
+ TypeError: reduce() of empty sequence with no initial value
+ reduce(operator.mul, [1,2,3], 1) =>
+ 6
+ reduce(operator.mul, [], 1) =>
+ 1
+
+If you use :func:`operator.add` with :func:`reduce`, you'll add up all the
+elements of the iterable. This case is so common that there's a special
+built-in called :func:`sum` to compute it::
+
+ reduce(operator.add, [1,2,3,4], 0) =>
+ 10
+ sum([1,2,3,4]) =>
+ 10
+ sum([]) =>
+ 0
+
+For many uses of :func:`reduce`, though, it can be clearer to just write the
+obvious :keyword:`for` loop::
+
+ # Instead of:
+ product = reduce(operator.mul, [1,2,3], 1)
+
+ # You can write:
+ product = 1
+ for i in [1,2,3]:
+ product *= i
+
+
+``enumerate(iter)`` counts off the elements in the iterable, returning 2-tuples
+containing the count and each element.
+
+::
+
+ enumerate(['subject', 'verb', 'object']) =>
+ (0, 'subject'), (1, 'verb'), (2, 'object')
+
+:func:`enumerate` is often used when looping through a list and recording the
+indexes at which certain conditions are met::
+
+ f = open('data.txt', 'r')
+ for i, line in enumerate(f):
+ if line.strip() == '':
+ print 'Blank line at line #%i' % i
+
+``sorted(iterable, [cmp=None], [key=None], [reverse=False)`` collects all the
+elements of the iterable into a list, sorts the list, and returns the sorted
+result. The ``cmp``, ``key``, and ``reverse`` arguments are passed through to
+the constructed list's ``.sort()`` method.
+
+::
+
+ import random
+ # Generate 8 random numbers between [0, 10000)
+ rand_list = random.sample(range(10000), 8)
+ rand_list =>
+ [769, 7953, 9828, 6431, 8442, 9878, 6213, 2207]
+ sorted(rand_list) =>
+ [769, 2207, 6213, 6431, 7953, 8442, 9828, 9878]
+ sorted(rand_list, reverse=True) =>
+ [9878, 9828, 8442, 7953, 6431, 6213, 2207, 769]
+
+(For a more detailed discussion of sorting, see the Sorting mini-HOWTO in the
+Python wiki at http://wiki.python.org/moin/HowTo/Sorting.)
+
+The ``any(iter)`` and ``all(iter)`` built-ins look at the truth values of an
+iterable's contents. :func:`any` returns True if any element in the iterable is
+a true value, and :func:`all` returns True if all of the elements are true
+values::
+
+ any([0,1,0]) =>
+ True
+ any([0,0,0]) =>
+ False
+ any([1,1,1]) =>
+ True
+ all([0,1,0]) =>
+ False
+ all([0,0,0]) =>
+ False
+ all([1,1,1]) =>
+ True
+
+
+Small functions and the lambda expression
+=========================================
+
+When writing functional-style programs, you'll often need little functions that
+act as predicates or that combine elements in some way.
+
+If there's a Python built-in or a module function that's suitable, you don't
+need to define a new function at all::
+
+ stripped_lines = [line.strip() for line in lines]
+ existing_files = filter(os.path.exists, file_list)
+
+If the function you need doesn't exist, you need to write it. One way to write
+small functions is to use the ``lambda`` statement. ``lambda`` takes a number
+of parameters and an expression combining these parameters, and creates a small
+function that returns the value of the expression::
+
+ lowercase = lambda x: x.lower()
+
+ print_assign = lambda name, value: name + '=' + str(value)
+
+ adder = lambda x, y: x+y
+
+An alternative is to just use the ``def`` statement and define a function in the
+usual way::
+
+ def lowercase(x):
+ return x.lower()
+
+ def print_assign(name, value):
+ return name + '=' + str(value)
+
+ def adder(x,y):
+ return x + y
+
+Which alternative is preferable? That's a style question; my usual course is to
+avoid using ``lambda``.
+
+One reason for my preference is that ``lambda`` is quite limited in the
+functions it can define. The result has to be computable as a single
+expression, which means you can't have multiway ``if... elif... else``
+comparisons or ``try... except`` statements. If you try to do too much in a
+``lambda`` statement, you'll end up with an overly complicated expression that's
+hard to read. Quick, what's the following code doing?
+
+::
+
+ total = reduce(lambda a, b: (0, a[1] + b[1]), items)[1]
+
+You can figure it out, but it takes time to disentangle the expression to figure
+out what's going on. Using a short nested ``def`` statements makes things a
+little bit better::
+
+ def combine (a, b):
+ return 0, a[1] + b[1]
+
+ total = reduce(combine, items)[1]
+
+But it would be best of all if I had simply used a ``for`` loop::
+
+ total = 0
+ for a, b in items:
+ total += b
+
+Or the :func:`sum` built-in and a generator expression::
+
+ total = sum(b for a,b in items)
+
+Many uses of :func:`reduce` are clearer when written as ``for`` loops.
+
+Fredrik Lundh once suggested the following set of rules for refactoring uses of
+``lambda``:
+
+1) Write a lambda function.
+2) Write a comment explaining what the heck that lambda does.
+3) Study the comment for a while, and think of a name that captures the essence
+ of the comment.
+4) Convert the lambda to a def statement, using that name.
+5) Remove the comment.
+
+I really like these rules, but you're free to disagree that this lambda-free
+style is better.
+
+
+The itertools module
+====================
+
+The :mod:`itertools` module contains a number of commonly-used iterators as well
+as functions for combining several iterators. This section will introduce the
+module's contents by showing small examples.
+
+The module's functions fall into a few broad classes:
+
+* Functions that create a new iterator based on an existing iterator.
+* Functions for treating an iterator's elements as function arguments.
+* Functions for selecting portions of an iterator's output.
+* A function for grouping an iterator's output.
+
+Creating new iterators
+----------------------
+
+``itertools.count(n)`` returns an infinite stream of integers, increasing by 1
+each time. You can optionally supply the starting number, which defaults to 0::
+
+ itertools.count() =>
+ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...
+ itertools.count(10) =>
+ 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...
+
+``itertools.cycle(iter)`` saves a copy of the contents of a provided iterable
+and returns a new iterator that returns its elements from first to last. The
+new iterator will repeat these elements infinitely.
+
+::
+
+ itertools.cycle([1,2,3,4,5]) =>
+ 1, 2, 3, 4, 5, 1, 2, 3, 4, 5, ...
+
+``itertools.repeat(elem, [n])`` returns the provided element ``n`` times, or
+returns the element endlessly if ``n`` is not provided.
+
+::
+
+ itertools.repeat('abc') =>
+ abc, abc, abc, abc, abc, abc, abc, abc, abc, abc, ...
+ itertools.repeat('abc', 5) =>
+ abc, abc, abc, abc, abc
+
+``itertools.chain(iterA, iterB, ...)`` takes an arbitrary number of iterables as
+input, and returns all the elements of the first iterator, then all the elements
+of the second, and so on, until all of the iterables have been exhausted.
+
+::
+
+ itertools.chain(['a', 'b', 'c'], (1, 2, 3)) =>
+ a, b, c, 1, 2, 3
+
+``itertools.izip(iterA, iterB, ...)`` takes one element from each iterable and
+returns them in a tuple::
+
+ itertools.izip(['a', 'b', 'c'], (1, 2, 3)) =>
+ ('a', 1), ('b', 2), ('c', 3)
+
+It's similiar to the built-in :func:`zip` function, but doesn't construct an
+in-memory list and exhaust all the input iterators before returning; instead
+tuples are constructed and returned only if they're requested. (The technical
+term for this behaviour is `lazy evaluation
+<http://en.wikipedia.org/wiki/Lazy_evaluation>`__.)
+
+This iterator is intended to be used with iterables that are all of the same
+length. If the iterables are of different lengths, the resulting stream will be
+the same length as the shortest iterable.
+
+::
+
+ itertools.izip(['a', 'b'], (1, 2, 3)) =>
+ ('a', 1), ('b', 2)
+
+You should avoid doing this, though, because an element may be taken from the
+longer iterators and discarded. This means you can't go on to use the iterators
+further because you risk skipping a discarded element.
+
+``itertools.islice(iter, [start], stop, [step])`` returns a stream that's a
+slice of the iterator. With a single ``stop`` argument, it will return the
+first ``stop`` elements. If you supply a starting index, you'll get
+``stop-start`` elements, and if you supply a value for ``step``, elements will
+be skipped accordingly. Unlike Python's string and list slicing, you can't use
+negative values for ``start``, ``stop``, or ``step``.
+
+::
+
+ itertools.islice(range(10), 8) =>
+ 0, 1, 2, 3, 4, 5, 6, 7
+ itertools.islice(range(10), 2, 8) =>
+ 2, 3, 4, 5, 6, 7
+ itertools.islice(range(10), 2, 8, 2) =>
+ 2, 4, 6
+
+``itertools.tee(iter, [n])`` replicates an iterator; it returns ``n``
+independent iterators that will all return the contents of the source iterator.
+If you don't supply a value for ``n``, the default is 2. Replicating iterators
+requires saving some of the contents of the source iterator, so this can consume
+significant memory if the iterator is large and one of the new iterators is
+consumed more than the others.
+
+::
+
+ itertools.tee( itertools.count() ) =>
+ iterA, iterB
+
+ where iterA ->
+ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...
+
+ and iterB ->
+ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...
+
+
+Calling functions on elements
+-----------------------------
+
+Two functions are used for calling other functions on the contents of an
+iterable.
+
+``itertools.imap(f, iterA, iterB, ...)`` returns a stream containing
+``f(iterA[0], iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ...``::
+
+ itertools.imap(operator.add, [5, 6, 5], [1, 2, 3]) =>
+ 6, 8, 8
+
+The ``operator`` module contains a set of functions corresponding to Python's
+operators. Some examples are ``operator.add(a, b)`` (adds two values),
+``operator.ne(a, b)`` (same as ``a!=b``), and ``operator.attrgetter('id')``
+(returns a callable that fetches the ``"id"`` attribute).
+
+``itertools.starmap(func, iter)`` assumes that the iterable will return a stream
+of tuples, and calls ``f()`` using these tuples as the arguments::
+
+ itertools.starmap(os.path.join,
+ [('/usr', 'bin', 'java'), ('/bin', 'python'),
+ ('/usr', 'bin', 'perl'),('/usr', 'bin', 'ruby')])
+ =>
+ /usr/bin/java, /bin/python, /usr/bin/perl, /usr/bin/ruby
+
+
+Selecting elements
+------------------
+
+Another group of functions chooses a subset of an iterator's elements based on a
+predicate.
+
+``itertools.ifilter(predicate, iter)`` returns all the elements for which the
+predicate returns true::
+
+ def is_even(x):
+ return (x % 2) == 0
+
+ itertools.ifilter(is_even, itertools.count()) =>
+ 0, 2, 4, 6, 8, 10, 12, 14, ...
+
+``itertools.ifilterfalse(predicate, iter)`` is the opposite, returning all
+elements for which the predicate returns false::
+
+ itertools.ifilterfalse(is_even, itertools.count()) =>
+ 1, 3, 5, 7, 9, 11, 13, 15, ...
+
+``itertools.takewhile(predicate, iter)`` returns elements for as long as the
+predicate returns true. Once the predicate returns false, the iterator will
+signal the end of its results.
+
+::
+
+ def less_than_10(x):
+ return (x < 10)
+
+ itertools.takewhile(less_than_10, itertools.count()) =>
+ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
+
+ itertools.takewhile(is_even, itertools.count()) =>
+ 0
+
+``itertools.dropwhile(predicate, iter)`` discards elements while the predicate
+returns true, and then returns the rest of the iterable's results.
+
+::
+
+ itertools.dropwhile(less_than_10, itertools.count()) =>
+ 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...
+
+ itertools.dropwhile(is_even, itertools.count()) =>
+ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ...
+
+
+Grouping elements
+-----------------
+
+The last function I'll discuss, ``itertools.groupby(iter, key_func=None)``, is
+the most complicated. ``key_func(elem)`` is a function that can compute a key
+value for each element returned by the iterable. If you don't supply a key
+function, the key is simply each element itself.
+
+``groupby()`` collects all the consecutive elements from the underlying iterable
+that have the same key value, and returns a stream of 2-tuples containing a key
+value and an iterator for the elements with that key.
+
+::
+
+ city_list = [('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL'),
+ ('Anchorage', 'AK'), ('Nome', 'AK'),
+ ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ'),
+ ...
+ ]
+
+ def get_state ((city, state)):
+ return state
+
+ itertools.groupby(city_list, get_state) =>
+ ('AL', iterator-1),
+ ('AK', iterator-2),
+ ('AZ', iterator-3), ...
+
+ where
+ iterator-1 =>
+ ('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL')
+ iterator-2 =>
+ ('Anchorage', 'AK'), ('Nome', 'AK')
+ iterator-3 =>
+ ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ')
+
+``groupby()`` assumes that the underlying iterable's contents will already be
+sorted based on the key. Note that the returned iterators also use the
+underlying iterable, so you have to consume the results of iterator-1 before
+requesting iterator-2 and its corresponding key.
+
+
+The functools module
+====================
+
+The :mod:`functools` module in Python 2.5 contains some higher-order functions.
+A **higher-order function** takes one or more functions as input and returns a
+new function. The most useful tool in this module is the
+:func:`functools.partial` function.
+
+For programs written in a functional style, you'll sometimes want to construct
+variants of existing functions that have some of the parameters filled in.
+Consider a Python function ``f(a, b, c)``; you may wish to create a new function
+``g(b, c)`` that's equivalent to ``f(1, b, c)``; you're filling in a value for
+one of ``f()``'s parameters. This is called "partial function application".
+
+The constructor for ``partial`` takes the arguments ``(function, arg1, arg2,
+... kwarg1=value1, kwarg2=value2)``. The resulting object is callable, so you
+can just call it to invoke ``function`` with the filled-in arguments.
+
+Here's a small but realistic example::
+
+ import functools
+
+ def log (message, subsystem):
+ "Write the contents of 'message' to the specified subsystem."
+ print '%s: %s' % (subsystem, message)
+ ...
+
+ server_log = functools.partial(log, subsystem='server')
+ server_log('Unable to open socket')
+
+
+The operator module
+-------------------
+
+The :mod:`operator` module was mentioned earlier. It contains a set of
+functions corresponding to Python's operators. These functions are often useful
+in functional-style code because they save you from writing trivial functions
+that perform a single operation.
+
+Some of the functions in this module are:
+
+* Math operations: ``add()``, ``sub()``, ``mul()``, ``div()``, ``floordiv()``,
+ ``abs()``, ...
+* Logical operations: ``not_()``, ``truth()``.
+* Bitwise operations: ``and_()``, ``or_()``, ``invert()``.
+* Comparisons: ``eq()``, ``ne()``, ``lt()``, ``le()``, ``gt()``, and ``ge()``.
+* Object identity: ``is_()``, ``is_not()``.
+
+Consult the operator module's documentation for a complete list.
+
+
+
+The functional module
+---------------------
+
+Collin Winter's `functional module <http://oakwinter.com/code/functional/>`__
+provides a number of more advanced tools for functional programming. It also
+reimplements several Python built-ins, trying to make them more intuitive to
+those used to functional programming in other languages.
+
+This section contains an introduction to some of the most important functions in
+``functional``; full documentation can be found at `the project's website
+<http://oakwinter.com/code/functional/documentation/>`__.
+
+``compose(outer, inner, unpack=False)``
+
+The ``compose()`` function implements function composition. In other words, it
+returns a wrapper around the ``outer`` and ``inner`` callables, such that the
+return value from ``inner`` is fed directly to ``outer``. That is,
+
+::
+
+ >>> def add(a, b):
+ ... return a + b
+ ...
+ >>> def double(a):
+ ... return 2 * a
+ ...
+ >>> compose(double, add)(5, 6)
+ 22
+
+is equivalent to
+
+::
+
+ >>> double(add(5, 6))
+ 22
+
+The ``unpack`` keyword is provided to work around the fact that Python functions
+are not always `fully curried <http://en.wikipedia.org/wiki/Currying>`__. By
+default, it is expected that the ``inner`` function will return a single object
+and that the ``outer`` function will take a single argument. Setting the
+``unpack`` argument causes ``compose`` to expect a tuple from ``inner`` which
+will be expanded before being passed to ``outer``. Put simply,
+
+::
+
+ compose(f, g)(5, 6)
+
+is equivalent to::
+
+ f(g(5, 6))
+
+while
+
+::
+
+ compose(f, g, unpack=True)(5, 6)
+
+is equivalent to::
+
+ f(*g(5, 6))
+
+Even though ``compose()`` only accepts two functions, it's trivial to build up a
+version that will compose any number of functions. We'll use ``reduce()``,
+``compose()`` and ``partial()`` (the last of which is provided by both
+``functional`` and ``functools``).
+
+::
+
+ from functional import compose, partial
+
+ multi_compose = partial(reduce, compose)
+
+
+We can also use ``map()``, ``compose()`` and ``partial()`` to craft a version of
+``"".join(...)`` that converts its arguments to string::
+
+ from functional import compose, partial
+
+ join = compose("".join, partial(map, str))
+
+
+``flip(func)``
+
+``flip()`` wraps the callable in ``func`` and causes it to receive its
+non-keyword arguments in reverse order.
+
+::
+
+ >>> def triple(a, b, c):
+ ... return (a, b, c)
+ ...
+ >>> triple(5, 6, 7)
+ (5, 6, 7)
+ >>>
+ >>> flipped_triple = flip(triple)
+ >>> flipped_triple(5, 6, 7)
+ (7, 6, 5)
+
+``foldl(func, start, iterable)``
+
+``foldl()`` takes a binary function, a starting value (usually some kind of
+'zero'), and an iterable. The function is applied to the starting value and the
+first element of the list, then the result of that and the second element of the
+list, then the result of that and the third element of the list, and so on.
+
+This means that a call such as::
+
+ foldl(f, 0, [1, 2, 3])
+
+is equivalent to::
+
+ f(f(f(0, 1), 2), 3)
+
+
+``foldl()`` is roughly equivalent to the following recursive function::
+
+ def foldl(func, start, seq):
+ if len(seq) == 0:
+ return start
+
+ return foldl(func, func(start, seq[0]), seq[1:])
+
+Speaking of equivalence, the above ``foldl`` call can be expressed in terms of
+the built-in ``reduce`` like so::
+
+ reduce(f, [1, 2, 3], 0)
+
+
+We can use ``foldl()``, ``operator.concat()`` and ``partial()`` to write a
+cleaner, more aesthetically-pleasing version of Python's ``"".join(...)``
+idiom::
+
+ from functional import foldl, partial
+ from operator import concat
+
+ join = partial(foldl, concat, "")
+
+
+Revision History and Acknowledgements
+=====================================
+
+The author would like to thank the following people for offering suggestions,
+corrections and assistance with various drafts of this article: Ian Bicking,
+Nick Coghlan, Nick Efford, Raymond Hettinger, Jim Jewett, Mike Krell, Leandro
+Lameiro, Jussi Salmela, Collin Winter, Blake Winton.
+
+Version 0.1: posted June 30 2006.
+
+Version 0.11: posted July 1 2006. Typo fixes.
+
+Version 0.2: posted July 10 2006. Merged genexp and listcomp sections into one.
+Typo fixes.
+
+Version 0.21: Added more references suggested on the tutor mailing list.
+
+Version 0.30: Adds a section on the ``functional`` module written by Collin
+Winter; adds short section on the operator module; a few other edits.
+
+
+References
+==========
+
+General
+-------
+
+**Structure and Interpretation of Computer Programs**, by Harold Abelson and
+Gerald Jay Sussman with Julie Sussman. Full text at
+http://mitpress.mit.edu/sicp/. In this classic textbook of computer science,
+chapters 2 and 3 discuss the use of sequences and streams to organize the data
+flow inside a program. The book uses Scheme for its examples, but many of the
+design approaches described in these chapters are applicable to functional-style
+Python code.
+
+http://www.defmacro.org/ramblings/fp.html: A general introduction to functional
+programming that uses Java examples and has a lengthy historical introduction.
+
+http://en.wikipedia.org/wiki/Functional_programming: General Wikipedia entry
+describing functional programming.
+
+http://en.wikipedia.org/wiki/Coroutine: Entry for coroutines.
+
+http://en.wikipedia.org/wiki/Currying: Entry for the concept of currying.
+
+Python-specific
+---------------
+
+http://gnosis.cx/TPiP/: The first chapter of David Mertz's book
+:title-reference:`Text Processing in Python` discusses functional programming
+for text processing, in the section titled "Utilizing Higher-Order Functions in
+Text Processing".
+
+Mertz also wrote a 3-part series of articles on functional programming
+for IBM's DeveloperWorks site; see
+`part 1 <http://www-128.ibm.com/developerworks/library/l-prog.html>`__,
+`part 2 <http://www-128.ibm.com/developerworks/library/l-prog2.html>`__, and
+`part 3 <http://www-128.ibm.com/developerworks/linux/library/l-prog3.html>`__,
+
+
+Python documentation
+--------------------
+
+Documentation for the :mod:`itertools` module.
+
+Documentation for the :mod:`operator` module.
+
+:pep:`289`: "Generator Expressions"
+
+:pep:`342`: "Coroutines via Enhanced Generators" describes the new generator
+features in Python 2.5.
+
+.. comment
+
+ Topics to place
+ -----------------------------
+
+ XXX os.walk()
+
+ XXX Need a large example.
+
+ But will an example add much? I'll post a first draft and see
+ what the comments say.
+
+.. comment
+
+ Original outline:
+ Introduction
+ Idea of FP
+ Programs built out of functions
+ Functions are strictly input-output, no internal state
+ Opposed to OO programming, where objects have state
+
+ Why FP?
+ Formal provability
+ Assignment is difficult to reason about
+ Not very relevant to Python
+ Modularity
+ Small functions that do one thing
+ Debuggability:
+ Easy to test due to lack of state
+ Easy to verify output from intermediate steps
+ Composability
+ You assemble a toolbox of functions that can be mixed
+
+ Tackling a problem
+ Need a significant example
+
+ Iterators
+ Generators
+ The itertools module
+ List comprehensions
+ Small functions and the lambda statement
+ Built-in functions
+ map
+ filter
+ reduce
+
+.. comment
+
+ Handy little function for printing part of an iterator -- used
+ while writing this document.
+
+ import itertools
+ def print_iter(it):
+ slice = itertools.islice(it, 10)
+ for elem in slice[:-1]:
+ sys.stdout.write(str(elem))
+ sys.stdout.write(', ')
+ print elem[-1]
+
+
--- /dev/null
+***************
+ Python HOWTOs
+***************
+
+Python HOWTOs are documents that cover a single, specific topic,
+and attempt to cover it fairly completely. Modelled on the Linux
+Documentation Project's HOWTO collection, this collection is an
+effort to foster documentation that's more detailed than the
+Python Library Reference.
+
+Currently, the HOWTOs are:
+
+.. toctree::
+ :maxdepth: 1
+
+ advocacy.rst
+ pythonmac.rst
+ curses.rst
+ doanddont.rst
+ functional.rst
+ regex.rst
+ sockets.rst
+ unicode.rst
+ urllib2.rst
+
--- /dev/null
+
+.. _using-on-mac:
+
+***************************
+Using Python on a Macintosh
+***************************
+
+:Author: Bob Savage <bobsavage@mac.com>
+
+
+Python on a Macintosh running Mac OS X is in principle very similar to Python on
+any other Unix platform, but there are a number of additional features such as
+the IDE and the Package Manager that are worth pointing out.
+
+The Mac-specific modules are documented in :ref:`mac-specific-services`.
+
+Python on Mac OS 9 or earlier can be quite different from Python on Unix or
+Windows, but is beyond the scope of this manual, as that platform is no longer
+supported, starting with Python 2.4. See http://www.cwi.nl/~jack/macpython for
+installers for the latest 2.3 release for Mac OS 9 and related documentation.
+
+
+.. _getting-osx:
+
+Getting and Installing MacPython
+================================
+
+Mac OS X 10.4 comes with Python 2.3 pre-installed by Apple. However, you are
+encouraged to install the most recent version of Python from the Python website
+(http://www.python.org). A "universal binary" build of Python 2.5, which runs
+natively on the Mac's new Intel and legacy PPC CPU's, is available there.
+
+What you get after installing is a number of things:
+
+* A :file:`MacPython 2.5` folder in your :file:`Applications` folder. In here
+ you find IDLE, the development environment that is a standard part of official
+ Python distributions; PythonLauncher, which handles double-clicking Python
+ scripts from the Finder; and the "Build Applet" tool, which allows you to
+ package Python scripts as standalone applications on your system.
+
+* A framework :file:`/Library/Frameworks/Python.framework`, which includes the
+ Python executable and libraries. The installer adds this location to your shell
+ path. To uninstall MacPython, you can simply remove these three things. A
+ symlink to the Python executable is placed in /usr/local/bin/.
+
+The Apple-provided build of Python is installed in
+:file:`/System/Library/Frameworks/Python.framework` and :file:`/usr/bin/python`,
+respectively. You should never modify or delete these, as they are
+Apple-controlled and are used by Apple- or third-party software.
+
+IDLE includes a help menu that allows you to access Python documentation. If you
+are completely new to Python you should start reading the tutorial introduction
+in that document.
+
+If you are familiar with Python on other Unix platforms you should read the
+section on running Python scripts from the Unix shell.
+
+
+How to run a Python script
+--------------------------
+
+Your best way to get started with Python on Mac OS X is through the IDLE
+integrated development environment, see section :ref:`ide` and use the Help menu
+when the IDE is running.
+
+If you want to run Python scripts from the Terminal window command line or from
+the Finder you first need an editor to create your script. Mac OS X comes with a
+number of standard Unix command line editors, :program:`vim` and
+:program:`emacs` among them. If you want a more Mac-like editor,
+:program:`BBEdit` or :program:`TextWrangler` from Bare Bones Software (see
+http://www.barebones.com/products/bbedit/index.shtml) are good choices, as is
+:program:`TextMate` (see http://macromates.com/). Other editors include
+:program:`Gvim` (http://macvim.org) and :program:`Aquamacs`
+(http://aquamacs.org).
+
+To run your script from the Terminal window you must make sure that
+:file:`/usr/local/bin` is in your shell search path.
+
+To run your script from the Finder you have two options:
+
+* Drag it to :program:`PythonLauncher`
+
+* Select :program:`PythonLauncher` as the default application to open your
+ script (or any .py script) through the finder Info window and double-click it.
+ :program:`PythonLauncher` has various preferences to control how your script is
+ launched. Option-dragging allows you to change these for one invocation, or use
+ its Preferences menu to change things globally.
+
+
+.. _osx-gui-scripts:
+
+Running scripts with a GUI
+--------------------------
+
+With older versions of Python, there is one Mac OS X quirk that you need to be
+aware of: programs that talk to the Aqua window manager (in other words,
+anything that has a GUI) need to be run in a special way. Use :program:`pythonw`
+instead of :program:`python` to start such scripts.
+
+With Python 2.5, you can use either :program:`python` or :program:`pythonw`.
+
+
+Configuration
+-------------
+
+Python on OS X honors all standard Unix environment variables such as
+:envvar:`PYTHONPATH`, but setting these variables for programs started from the
+Finder is non-standard as the Finder does not read your :file:`.profile` or
+:file:`.cshrc` at startup. You need to create a file :file:`~
+/.MacOSX/environment.plist`. See Apple's Technical Document QA1067 for details.
+
+For more information on installation Python packages in MacPython, see section
+:ref:`mac-package-manager`.
+
+
+.. _ide:
+
+The IDE
+=======
+
+MacPython ships with the standard IDLE development environment. A good
+introduction to using IDLE can be found at http://hkn.eecs.berkeley.edu/
+dyoo/python/idle_intro/index.html.
+
+
+.. _mac-package-manager:
+
+Installing Additional Python Packages
+=====================================
+
+There are several methods to install additional Python packages:
+
+* http://pythonmac.org/packages/ contains selected compiled packages for Python
+ 2.5, 2.4, and 2.3.
+
+* Packages can be installed via the standard Python distutils mode (``python
+ setup.py install``).
+
+* Many packages can also be installed via the :program:`setuptools` extension.
+
+
+GUI Programming on the Mac
+==========================
+
+There are several options for building GUI applications on the Mac with Python.
+
+*PyObjC* is a Python binding to Apple's Objective-C/Cocoa framework, which is
+the foundation of most modern Mac development. Information on PyObjC is
+available from http://pyobjc.sourceforge.net.
+
+The standard Python GUI toolkit is :mod:`Tkinter`, based on the cross-platform
+Tk toolkit (http://www.tcl.tk). An Aqua-native version of Tk is bundled with OS
+X by Apple, and the latest version can be downloaded and installed from
+http://www.activestate.com; it can also be built from source.
+
+*wxPython* is another popular cross-platform GUI toolkit that runs natively on
+Mac OS X. Packages and documentation are available from http://www.wxpython.org.
+
+*PyQt* is another popular cross-platform GUI toolkit that runs natively on Mac
+OS X. More information can be found at
+http://www.riverbankcomputing.co.uk/pyqt/.
+
+
+Distributing Python Applications on the Mac
+===========================================
+
+The "Build Applet" tool that is placed in the MacPython 2.5 folder is fine for
+packaging small Python scripts on your own machine to run as a standard Mac
+application. This tool, however, is not robust enough to distribute Python
+applications to other users.
+
+The standard tool for deploying standalone Python applications on the Mac is
+:program:`py2app`. More information on installing and using py2app can be found
+at http://undefined.org/python/#py2app.
+
+
+Application Scripting
+=====================
+
+Python can also be used to script other Mac applications via Apple's Open
+Scripting Architecture (OSA); see http://appscript.sourceforge.net. Appscript is
+a high-level, user-friendly Apple event bridge that allows you to control
+scriptable Mac OS X applications using ordinary Python scripts. Appscript makes
+Python a serious alternative to Apple's own *AppleScript* language for
+automating your Mac. A related package, *PyOSA*, is an OSA language component
+for the Python scripting language, allowing Python code to be executed by any
+OSA-enabled application (Script Editor, Mail, iTunes, etc.). PyOSA makes Python
+a full peer to AppleScript.
+
+
+Other Resources
+===============
+
+The MacPython mailing list is an excellent support resource for Python users and
+developers on the Mac:
+
+http://www.python.org/community/sigs/current/pythonmac-sig/
+
+Another useful resource is the MacPython wiki:
+
+http://wiki.python.org/moin/MacPython
+
--- /dev/null
+****************************
+ Regular Expression HOWTO
+****************************
+
+:Author: A.M. Kuchling
+:Release: 0.05
+
+.. % TODO:
+.. % Document lookbehind assertions
+.. % Better way of displaying a RE, a string, and what it matches
+.. % Mention optional argument to match.groups()
+.. % Unicode (at least a reference)
+
+
+.. topic:: Abstract
+
+ This document is an introductory tutorial to using regular expressions in Python
+ with the :mod:`re` module. It provides a gentler introduction than the
+ corresponding section in the Library Reference.
+
+
+Introduction
+============
+
+The :mod:`re` module was added in Python 1.5, and provides Perl-style regular
+expression patterns. Earlier versions of Python came with the :mod:`regex`
+module, which provided Emacs-style patterns. The :mod:`regex` module was
+removed completely in Python 2.5.
+
+Regular expressions (called REs, or regexes, or regex patterns) are essentially
+a tiny, highly specialized programming language embedded inside Python and made
+available through the :mod:`re` module. Using this little language, you specify
+the rules for the set of possible strings that you want to match; this set might
+contain English sentences, or e-mail addresses, or TeX commands, or anything you
+like. You can then ask questions such as "Does this string match the pattern?",
+or "Is there a match for the pattern anywhere in this string?". You can also
+use REs to modify a string or to split it apart in various ways.
+
+Regular expression patterns are compiled into a series of bytecodes which are
+then executed by a matching engine written in C. For advanced use, it may be
+necessary to pay careful attention to how the engine will execute a given RE,
+and write the RE in a certain way in order to produce bytecode that runs faster.
+Optimization isn't covered in this document, because it requires that you have a
+good understanding of the matching engine's internals.
+
+The regular expression language is relatively small and restricted, so not all
+possible string processing tasks can be done using regular expressions. There
+are also tasks that *can* be done with regular expressions, but the expressions
+turn out to be very complicated. In these cases, you may be better off writing
+Python code to do the processing; while Python code will be slower than an
+elaborate regular expression, it will also probably be more understandable.
+
+
+Simple Patterns
+===============
+
+We'll start by learning about the simplest possible regular expressions. Since
+regular expressions are used to operate on strings, we'll begin with the most
+common task: matching characters.
+
+For a detailed explanation of the computer science underlying regular
+expressions (deterministic and non-deterministic finite automata), you can refer
+to almost any textbook on writing compilers.
+
+
+Matching Characters
+-------------------
+
+Most letters and characters will simply match themselves. For example, the
+regular expression ``test`` will match the string ``test`` exactly. (You can
+enable a case-insensitive mode that would let this RE match ``Test`` or ``TEST``
+as well; more about this later.)
+
+There are exceptions to this rule; some characters are special
+:dfn:`metacharacters`, and don't match themselves. Instead, they signal that
+some out-of-the-ordinary thing should be matched, or they affect other portions
+of the RE by repeating them or changing their meaning. Much of this document is
+devoted to discussing various metacharacters and what they do.
+
+Here's a complete list of the metacharacters; their meanings will be discussed
+in the rest of this HOWTO. ::
+
+ . ^ $ * + ? { [ ] \ | ( )
+
+The first metacharacters we'll look at are ``[`` and ``]``. They're used for
+specifying a character class, which is a set of characters that you wish to
+match. Characters can be listed individually, or a range of characters can be
+indicated by giving two characters and separating them by a ``'-'``. For
+example, ``[abc]`` will match any of the characters ``a``, ``b``, or ``c``; this
+is the same as ``[a-c]``, which uses a range to express the same set of
+characters. If you wanted to match only lowercase letters, your RE would be
+``[a-z]``.
+
+.. % $
+
+Metacharacters are not active inside classes. For example, ``[akm$]`` will
+match any of the characters ``'a'``, ``'k'``, ``'m'``, or ``'$'``; ``'$'`` is
+usually a metacharacter, but inside a character class it's stripped of its
+special nature.
+
+You can match the characters not listed within the class by :dfn:`complementing`
+the set. This is indicated by including a ``'^'`` as the first character of the
+class; ``'^'`` outside a character class will simply match the ``'^'``
+character. For example, ``[^5]`` will match any character except ``'5'``.
+
+Perhaps the most important metacharacter is the backslash, ``\``. As in Python
+string literals, the backslash can be followed by various characters to signal
+various special sequences. It's also used to escape all the metacharacters so
+you can still match them in patterns; for example, if you need to match a ``[``
+or ``\``, you can precede them with a backslash to remove their special
+meaning: ``\[`` or ``\\``.
+
+Some of the special sequences beginning with ``'\'`` represent predefined sets
+of characters that are often useful, such as the set of digits, the set of
+letters, or the set of anything that isn't whitespace. The following predefined
+special sequences are available:
+
+``\d``
+ Matches any decimal digit; this is equivalent to the class ``[0-9]``.
+
+``\D``
+ Matches any non-digit character; this is equivalent to the class ``[^0-9]``.
+
+``\s``
+ Matches any whitespace character; this is equivalent to the class ``[
+ \t\n\r\f\v]``.
+
+``\S``
+ Matches any non-whitespace character; this is equivalent to the class ``[^
+ \t\n\r\f\v]``.
+
+``\w``
+ Matches any alphanumeric character; this is equivalent to the class
+ ``[a-zA-Z0-9_]``.
+
+``\W``
+ Matches any non-alphanumeric character; this is equivalent to the class
+ ``[^a-zA-Z0-9_]``.
+
+These sequences can be included inside a character class. For example,
+``[\s,.]`` is a character class that will match any whitespace character, or
+``','`` or ``'.'``.
+
+The final metacharacter in this section is ``.``. It matches anything except a
+newline character, and there's an alternate mode (``re.DOTALL``) where it will
+match even a newline. ``'.'`` is often used where you want to match "any
+character".
+
+
+Repeating Things
+----------------
+
+Being able to match varying sets of characters is the first thing regular
+expressions can do that isn't already possible with the methods available on
+strings. However, if that was the only additional capability of regexes, they
+wouldn't be much of an advance. Another capability is that you can specify that
+portions of the RE must be repeated a certain number of times.
+
+The first metacharacter for repeating things that we'll look at is ``*``. ``*``
+doesn't match the literal character ``*``; instead, it specifies that the
+previous character can be matched zero or more times, instead of exactly once.
+
+For example, ``ca*t`` will match ``ct`` (0 ``a`` characters), ``cat`` (1 ``a``),
+``caaat`` (3 ``a`` characters), and so forth. The RE engine has various
+internal limitations stemming from the size of C's ``int`` type that will
+prevent it from matching over 2 billion ``a`` characters; you probably don't
+have enough memory to construct a string that large, so you shouldn't run into
+that limit.
+
+Repetitions such as ``*`` are :dfn:`greedy`; when repeating a RE, the matching
+engine will try to repeat it as many times as possible. If later portions of the
+pattern don't match, the matching engine will then back up and try again with
+few repetitions.
+
+A step-by-step example will make this more obvious. Let's consider the
+expression ``a[bcd]*b``. This matches the letter ``'a'``, zero or more letters
+from the class ``[bcd]``, and finally ends with a ``'b'``. Now imagine matching
+this RE against the string ``abcbd``.
+
++------+-----------+---------------------------------+
+| Step | Matched | Explanation |
++======+===========+=================================+
+| 1 | ``a`` | The ``a`` in the RE matches. |
++------+-----------+---------------------------------+
+| 2 | ``abcbd`` | The engine matches ``[bcd]*``, |
+| | | going as far as it can, which |
+| | | is to the end of the string. |
++------+-----------+---------------------------------+
+| 3 | *Failure* | The engine tries to match |
+| | | ``b``, but the current position |
+| | | is at the end of the string, so |
+| | | it fails. |
++------+-----------+---------------------------------+
+| 4 | ``abcb`` | Back up, so that ``[bcd]*`` |
+| | | matches one less character. |
++------+-----------+---------------------------------+
+| 5 | *Failure* | Try ``b`` again, but the |
+| | | current position is at the last |
+| | | character, which is a ``'d'``. |
++------+-----------+---------------------------------+
+| 6 | ``abc`` | Back up again, so that |
+| | | ``[bcd]*`` is only matching |
+| | | ``bc``. |
++------+-----------+---------------------------------+
+| 6 | ``abcb`` | Try ``b`` again. This time |
+| | | but the character at the |
+| | | current position is ``'b'``, so |
+| | | it succeeds. |
++------+-----------+---------------------------------+
+
+The end of the RE has now been reached, and it has matched ``abcb``. This
+demonstrates how the matching engine goes as far as it can at first, and if no
+match is found it will then progressively back up and retry the rest of the RE
+again and again. It will back up until it has tried zero matches for
+``[bcd]*``, and if that subsequently fails, the engine will conclude that the
+string doesn't match the RE at all.
+
+Another repeating metacharacter is ``+``, which matches one or more times. Pay
+careful attention to the difference between ``*`` and ``+``; ``*`` matches
+*zero* or more times, so whatever's being repeated may not be present at all,
+while ``+`` requires at least *one* occurrence. To use a similar example,
+``ca+t`` will match ``cat`` (1 ``a``), ``caaat`` (3 ``a``'s), but won't match
+``ct``.
+
+There are two more repeating qualifiers. The question mark character, ``?``,
+matches either once or zero times; you can think of it as marking something as
+being optional. For example, ``home-?brew`` matches either ``homebrew`` or
+``home-brew``.
+
+The most complicated repeated qualifier is ``{m,n}``, where *m* and *n* are
+decimal integers. This qualifier means there must be at least *m* repetitions,
+and at most *n*. For example, ``a/{1,3}b`` will match ``a/b``, ``a//b``, and
+``a///b``. It won't match ``ab``, which has no slashes, or ``a////b``, which
+has four.
+
+You can omit either *m* or *n*; in that case, a reasonable value is assumed for
+the missing value. Omitting *m* is interpreted as a lower limit of 0, while
+omitting *n* results in an upper bound of infinity --- actually, the upper bound
+is the 2-billion limit mentioned earlier, but that might as well be infinity.
+
+Readers of a reductionist bent may notice that the three other qualifiers can
+all be expressed using this notation. ``{0,}`` is the same as ``*``, ``{1,}``
+is equivalent to ``+``, and ``{0,1}`` is the same as ``?``. It's better to use
+``*``, ``+``, or ``?`` when you can, simply because they're shorter and easier
+to read.
+
+
+Using Regular Expressions
+=========================
+
+Now that we've looked at some simple regular expressions, how do we actually use
+them in Python? The :mod:`re` module provides an interface to the regular
+expression engine, allowing you to compile REs into objects and then perform
+matches with them.
+
+
+Compiling Regular Expressions
+-----------------------------
+
+Regular expressions are compiled into :class:`RegexObject` instances, which have
+methods for various operations such as searching for pattern matches or
+performing string substitutions. ::
+
+ >>> import re
+ >>> p = re.compile('ab*')
+ >>> print p
+ <re.RegexObject instance at 80b4150>
+
+:func:`re.compile` also accepts an optional *flags* argument, used to enable
+various special features and syntax variations. We'll go over the available
+settings later, but for now a single example will do::
+
+ >>> p = re.compile('ab*', re.IGNORECASE)
+
+The RE is passed to :func:`re.compile` as a string. REs are handled as strings
+because regular expressions aren't part of the core Python language, and no
+special syntax was created for expressing them. (There are applications that
+don't need REs at all, so there's no need to bloat the language specification by
+including them.) Instead, the :mod:`re` module is simply a C extension module
+included with Python, just like the :mod:`socket` or :mod:`zlib` modules.
+
+Putting REs in strings keeps the Python language simpler, but has one
+disadvantage which is the topic of the next section.
+
+
+The Backslash Plague
+--------------------
+
+As stated earlier, regular expressions use the backslash character (``'\'``) to
+indicate special forms or to allow special characters to be used without
+invoking their special meaning. This conflicts with Python's usage of the same
+character for the same purpose in string literals.
+
+Let's say you want to write a RE that matches the string ``\section``, which
+might be found in a LaTeX file. To figure out what to write in the program
+code, start with the desired string to be matched. Next, you must escape any
+backslashes and other metacharacters by preceding them with a backslash,
+resulting in the string ``\\section``. The resulting string that must be passed
+to :func:`re.compile` must be ``\\section``. However, to express this as a
+Python string literal, both backslashes must be escaped *again*.
+
++-------------------+------------------------------------------+
+| Characters | Stage |
++===================+==========================================+
+| ``\section`` | Text string to be matched |
++-------------------+------------------------------------------+
+| ``\\section`` | Escaped backslash for :func:`re.compile` |
++-------------------+------------------------------------------+
+| ``"\\\\section"`` | Escaped backslashes for a string literal |
++-------------------+------------------------------------------+
+
+In short, to match a literal backslash, one has to write ``'\\\\'`` as the RE
+string, because the regular expression must be ``\\``, and each backslash must
+be expressed as ``\\`` inside a regular Python string literal. In REs that
+feature backslashes repeatedly, this leads to lots of repeated backslashes and
+makes the resulting strings difficult to understand.
+
+The solution is to use Python's raw string notation for regular expressions;
+backslashes are not handled in any special way in a string literal prefixed with
+``'r'``, so ``r"\n"`` is a two-character string containing ``'\'`` and ``'n'``,
+while ``"\n"`` is a one-character string containing a newline. Regular
+expressions will often be written in Python code using this raw string notation.
+
++-------------------+------------------+
+| Regular String | Raw string |
++===================+==================+
+| ``"ab*"`` | ``r"ab*"`` |
++-------------------+------------------+
+| ``"\\\\section"`` | ``r"\\section"`` |
++-------------------+------------------+
+| ``"\\w+\\s+\\1"`` | ``r"\w+\s+\1"`` |
++-------------------+------------------+
+
+
+Performing Matches
+------------------
+
+Once you have an object representing a compiled regular expression, what do you
+do with it? :class:`RegexObject` instances have several methods and attributes.
+Only the most significant ones will be covered here; consult `the Library
+Reference <http://www.python.org/doc/lib/module-re.html>`_ for a complete
+listing.
+
++------------------+-----------------------------------------------+
+| Method/Attribute | Purpose |
++==================+===============================================+
+| ``match()`` | Determine if the RE matches at the beginning |
+| | of the string. |
++------------------+-----------------------------------------------+
+| ``search()`` | Scan through a string, looking for any |
+| | location where this RE matches. |
++------------------+-----------------------------------------------+
+| ``findall()`` | Find all substrings where the RE matches, and |
+| | returns them as a list. |
++------------------+-----------------------------------------------+
+| ``finditer()`` | Find all substrings where the RE matches, and |
+| | returns them as an iterator. |
++------------------+-----------------------------------------------+
+
+:meth:`match` and :meth:`search` return ``None`` if no match can be found. If
+they're successful, a ``MatchObject`` instance is returned, containing
+information about the match: where it starts and ends, the substring it matched,
+and more.
+
+You can learn about this by interactively experimenting with the :mod:`re`
+module. If you have Tkinter available, you may also want to look at
+:file:`Tools/scripts/redemo.py`, a demonstration program included with the
+Python distribution. It allows you to enter REs and strings, and displays
+whether the RE matches or fails. :file:`redemo.py` can be quite useful when
+trying to debug a complicated RE. Phil Schwartz's `Kodos
+<http://www.phil-schwartz.com/kodos.spy>`_ is also an interactive tool for
+developing and testing RE patterns.
+
+This HOWTO uses the standard Python interpreter for its examples. First, run the
+Python interpreter, import the :mod:`re` module, and compile a RE::
+
+ Python 2.2.2 (#1, Feb 10 2003, 12:57:01)
+ >>> import re
+ >>> p = re.compile('[a-z]+')
+ >>> p
+ <_sre.SRE_Pattern object at 80c3c28>
+
+Now, you can try matching various strings against the RE ``[a-z]+``. An empty
+string shouldn't match at all, since ``+`` means 'one or more repetitions'.
+:meth:`match` should return ``None`` in this case, which will cause the
+interpreter to print no output. You can explicitly print the result of
+:meth:`match` to make this clear. ::
+
+ >>> p.match("")
+ >>> print p.match("")
+ None
+
+Now, let's try it on a string that it should match, such as ``tempo``. In this
+case, :meth:`match` will return a :class:`MatchObject`, so you should store the
+result in a variable for later use. ::
+
+ >>> m = p.match('tempo')
+ >>> print m
+ <_sre.SRE_Match object at 80c4f68>
+
+Now you can query the :class:`MatchObject` for information about the matching
+string. :class:`MatchObject` instances also have several methods and
+attributes; the most important ones are:
+
++------------------+--------------------------------------------+
+| Method/Attribute | Purpose |
++==================+============================================+
+| ``group()`` | Return the string matched by the RE |
++------------------+--------------------------------------------+
+| ``start()`` | Return the starting position of the match |
++------------------+--------------------------------------------+
+| ``end()`` | Return the ending position of the match |
++------------------+--------------------------------------------+
+| ``span()`` | Return a tuple containing the (start, end) |
+| | positions of the match |
++------------------+--------------------------------------------+
+
+Trying these methods will soon clarify their meaning::
+
+ >>> m.group()
+ 'tempo'
+ >>> m.start(), m.end()
+ (0, 5)
+ >>> m.span()
+ (0, 5)
+
+:meth:`group` returns the substring that was matched by the RE. :meth:`start`
+and :meth:`end` return the starting and ending index of the match. :meth:`span`
+returns both start and end indexes in a single tuple. Since the :meth:`match`
+method only checks if the RE matches at the start of a string, :meth:`start`
+will always be zero. However, the :meth:`search` method of :class:`RegexObject`
+instances scans through the string, so the match may not start at zero in that
+case. ::
+
+ >>> print p.match('::: message')
+ None
+ >>> m = p.search('::: message') ; print m
+ <re.MatchObject instance at 80c9650>
+ >>> m.group()
+ 'message'
+ >>> m.span()
+ (4, 11)
+
+In actual programs, the most common style is to store the :class:`MatchObject`
+in a variable, and then check if it was ``None``. This usually looks like::
+
+ p = re.compile( ... )
+ m = p.match( 'string goes here' )
+ if m:
+ print 'Match found: ', m.group()
+ else:
+ print 'No match'
+
+Two :class:`RegexObject` methods return all of the matches for a pattern.
+:meth:`findall` returns a list of matching strings::
+
+ >>> p = re.compile('\d+')
+ >>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping')
+ ['12', '11', '10']
+
+:meth:`findall` has to create the entire list before it can be returned as the
+result. The :meth:`finditer` method returns a sequence of :class:`MatchObject`
+instances as an iterator. [#]_ ::
+
+ >>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...')
+ >>> iterator
+ <callable-iterator object at 0x401833ac>
+ >>> for match in iterator:
+ ... print match.span()
+ ...
+ (0, 2)
+ (22, 24)
+ (29, 31)
+
+
+Module-Level Functions
+----------------------
+
+You don't have to create a :class:`RegexObject` and call its methods; the
+:mod:`re` module also provides top-level functions called :func:`match`,
+:func:`search`, :func:`findall`, :func:`sub`, and so forth. These functions
+take the same arguments as the corresponding :class:`RegexObject` method, with
+the RE string added as the first argument, and still return either ``None`` or a
+:class:`MatchObject` instance. ::
+
+ >>> print re.match(r'From\s+', 'Fromage amk')
+ None
+ >>> re.match(r'From\s+', 'From amk Thu May 14 19:12:10 1998')
+ <re.MatchObject instance at 80c5978>
+
+Under the hood, these functions simply produce a :class:`RegexObject` for you
+and call the appropriate method on it. They also store the compiled object in a
+cache, so future calls using the same RE are faster.
+
+Should you use these module-level functions, or should you get the
+:class:`RegexObject` and call its methods yourself? That choice depends on how
+frequently the RE will be used, and on your personal coding style. If the RE is
+being used at only one point in the code, then the module functions are probably
+more convenient. If a program contains a lot of regular expressions, or re-uses
+the same ones in several locations, then it might be worthwhile to collect all
+the definitions in one place, in a section of code that compiles all the REs
+ahead of time. To take an example from the standard library, here's an extract
+from :file:`xmllib.py`::
+
+ ref = re.compile( ... )
+ entityref = re.compile( ... )
+ charref = re.compile( ... )
+ starttagopen = re.compile( ... )
+
+I generally prefer to work with the compiled object, even for one-time uses, but
+few people will be as much of a purist about this as I am.
+
+
+Compilation Flags
+-----------------
+
+Compilation flags let you modify some aspects of how regular expressions work.
+Flags are available in the :mod:`re` module under two names, a long name such as
+:const:`IGNORECASE` and a short, one-letter form such as :const:`I`. (If you're
+familiar with Perl's pattern modifiers, the one-letter forms use the same
+letters; the short form of :const:`re.VERBOSE` is :const:`re.X`, for example.)
+Multiple flags can be specified by bitwise OR-ing them; ``re.I | re.M`` sets
+both the :const:`I` and :const:`M` flags, for example.
+
+Here's a table of the available flags, followed by a more detailed explanation
+of each one.
+
++---------------------------------+--------------------------------------------+
+| Flag | Meaning |
++=================================+============================================+
+| :const:`DOTALL`, :const:`S` | Make ``.`` match any character, including |
+| | newlines |
++---------------------------------+--------------------------------------------+
+| :const:`IGNORECASE`, :const:`I` | Do case-insensitive matches |
++---------------------------------+--------------------------------------------+
+| :const:`LOCALE`, :const:`L` | Do a locale-aware match |
++---------------------------------+--------------------------------------------+
+| :const:`MULTILINE`, :const:`M` | Multi-line matching, affecting ``^`` and |
+| | ``$`` |
++---------------------------------+--------------------------------------------+
+| :const:`VERBOSE`, :const:`X` | Enable verbose REs, which can be organized |
+| | more cleanly and understandably. |
++---------------------------------+--------------------------------------------+
+
+
+.. data:: I
+ IGNORECASE
+ :noindex:
+
+ Perform case-insensitive matching; character class and literal strings will
+ match letters by ignoring case. For example, ``[A-Z]`` will match lowercase
+ letters, too, and ``Spam`` will match ``Spam``, ``spam``, or ``spAM``. This
+ lowercasing doesn't take the current locale into account; it will if you also
+ set the :const:`LOCALE` flag.
+
+
+.. data:: L
+ LOCALE
+ :noindex:
+
+ Make ``\w``, ``\W``, ``\b``, and ``\B``, dependent on the current locale.
+
+ Locales are a feature of the C library intended to help in writing programs that
+ take account of language differences. For example, if you're processing French
+ text, you'd want to be able to write ``\w+`` to match words, but ``\w`` only
+ matches the character class ``[A-Za-z]``; it won't match ``'é'`` or ``'ç'``. If
+ your system is configured properly and a French locale is selected, certain C
+ functions will tell the program that ``'é'`` should also be considered a letter.
+ Setting the :const:`LOCALE` flag when compiling a regular expression will cause
+ the resulting compiled object to use these C functions for ``\w``; this is
+ slower, but also enables ``\w+`` to match French words as you'd expect.
+
+
+.. data:: M
+ MULTILINE
+ :noindex:
+
+ (``^`` and ``$`` haven't been explained yet; they'll be introduced in section
+ :ref:`more-metacharacters`.)
+
+ Usually ``^`` matches only at the beginning of the string, and ``$`` matches
+ only at the end of the string and immediately before the newline (if any) at the
+ end of the string. When this flag is specified, ``^`` matches at the beginning
+ of the string and at the beginning of each line within the string, immediately
+ following each newline. Similarly, the ``$`` metacharacter matches either at
+ the end of the string and at the end of each line (immediately preceding each
+ newline).
+
+
+.. data:: S
+ DOTALL
+ :noindex:
+
+ Makes the ``'.'`` special character match any character at all, including a
+ newline; without this flag, ``'.'`` will match anything *except* a newline.
+
+
+.. data:: X
+ VERBOSE
+ :noindex:
+
+ This flag allows you to write regular expressions that are more readable by
+ granting you more flexibility in how you can format them. When this flag has
+ been specified, whitespace within the RE string is ignored, except when the
+ whitespace is in a character class or preceded by an unescaped backslash; this
+ lets you organize and indent the RE more clearly. This flag also lets you put
+ comments within a RE that will be ignored by the engine; comments are marked by
+ a ``'#'`` that's neither in a character class or preceded by an unescaped
+ backslash.
+
+ For example, here's a RE that uses :const:`re.VERBOSE`; see how much easier it
+ is to read? ::
+
+ charref = re.compile(r"""
+ &[#] # Start of a numeric entity reference
+ (
+ 0[0-7]+ # Octal form
+ | [0-9]+ # Decimal form
+ | x[0-9a-fA-F]+ # Hexadecimal form
+ )
+ ; # Trailing semicolon
+ """, re.VERBOSE)
+
+ Without the verbose setting, the RE would look like this::
+
+ charref = re.compile("&#(0[0-7]+"
+ "|[0-9]+"
+ "|x[0-9a-fA-F]+);")
+
+ In the above example, Python's automatic concatenation of string literals has
+ been used to break up the RE into smaller pieces, but it's still more difficult
+ to understand than the version using :const:`re.VERBOSE`.
+
+
+More Pattern Power
+==================
+
+So far we've only covered a part of the features of regular expressions. In
+this section, we'll cover some new metacharacters, and how to use groups to
+retrieve portions of the text that was matched.
+
+
+.. _more-metacharacters:
+
+More Metacharacters
+-------------------
+
+There are some metacharacters that we haven't covered yet. Most of them will be
+covered in this section.
+
+Some of the remaining metacharacters to be discussed are :dfn:`zero-width
+assertions`. They don't cause the engine to advance through the string;
+instead, they consume no characters at all, and simply succeed or fail. For
+example, ``\b`` is an assertion that the current position is located at a word
+boundary; the position isn't changed by the ``\b`` at all. This means that
+zero-width assertions should never be repeated, because if they match once at a
+given location, they can obviously be matched an infinite number of times.
+
+``|``
+ Alternation, or the "or" operator. If A and B are regular expressions,
+ ``A|B`` will match any string that matches either ``A`` or ``B``. ``|`` has very
+ low precedence in order to make it work reasonably when you're alternating
+ multi-character strings. ``Crow|Servo`` will match either ``Crow`` or ``Servo``,
+ not ``Cro``, a ``'w'`` or an ``'S'``, and ``ervo``.
+
+ To match a literal ``'|'``, use ``\|``, or enclose it inside a character class,
+ as in ``[|]``.
+
+``^``
+ Matches at the beginning of lines. Unless the :const:`MULTILINE` flag has been
+ set, this will only match at the beginning of the string. In :const:`MULTILINE`
+ mode, this also matches immediately after each newline within the string.
+
+ For example, if you wish to match the word ``From`` only at the beginning of a
+ line, the RE to use is ``^From``. ::
+
+ >>> print re.search('^From', 'From Here to Eternity')
+ <re.MatchObject instance at 80c1520>
+ >>> print re.search('^From', 'Reciting From Memory')
+ None
+
+ .. % To match a literal \character{\^}, use \regexp{\e\^} or enclose it
+ .. % inside a character class, as in \regexp{[{\e}\^]}.
+
+``$``
+ Matches at the end of a line, which is defined as either the end of the string,
+ or any location followed by a newline character. ::
+
+ >>> print re.search('}$', '{block}')
+ <re.MatchObject instance at 80adfa8>
+ >>> print re.search('}$', '{block} ')
+ None
+ >>> print re.search('}$', '{block}\n')
+ <re.MatchObject instance at 80adfa8>
+
+ To match a literal ``'$'``, use ``\$`` or enclose it inside a character class,
+ as in ``[$]``.
+
+ .. % $
+
+``\A``
+ Matches only at the start of the string. When not in :const:`MULTILINE` mode,
+ ``\A`` and ``^`` are effectively the same. In :const:`MULTILINE` mode, they're
+ different: ``\A`` still matches only at the beginning of the string, but ``^``
+ may match at any location inside the string that follows a newline character.
+
+``\Z``
+ Matches only at the end of the string.
+
+``\b``
+ Word boundary. This is a zero-width assertion that matches only at the
+ beginning or end of a word. A word is defined as a sequence of alphanumeric
+ characters, so the end of a word is indicated by whitespace or a
+ non-alphanumeric character.
+
+ The following example matches ``class`` only when it's a complete word; it won't
+ match when it's contained inside another word. ::
+
+ >>> p = re.compile(r'\bclass\b')
+ >>> print p.search('no class at all')
+ <re.MatchObject instance at 80c8f28>
+ >>> print p.search('the declassified algorithm')
+ None
+ >>> print p.search('one subclass is')
+ None
+
+ There are two subtleties you should remember when using this special sequence.
+ First, this is the worst collision between Python's string literals and regular
+ expression sequences. In Python's string literals, ``\b`` is the backspace
+ character, ASCII value 8. If you're not using raw strings, then Python will
+ convert the ``\b`` to a backspace, and your RE won't match as you expect it to.
+ The following example looks the same as our previous RE, but omits the ``'r'``
+ in front of the RE string. ::
+
+ >>> p = re.compile('\bclass\b')
+ >>> print p.search('no class at all')
+ None
+ >>> print p.search('\b' + 'class' + '\b')
+ <re.MatchObject instance at 80c3ee0>
+
+ Second, inside a character class, where there's no use for this assertion,
+ ``\b`` represents the backspace character, for compatibility with Python's
+ string literals.
+
+``\B``
+ Another zero-width assertion, this is the opposite of ``\b``, only matching when
+ the current position is not at a word boundary.
+
+
+Grouping
+--------
+
+Frequently you need to obtain more information than just whether the RE matched
+or not. Regular expressions are often used to dissect strings by writing a RE
+divided into several subgroups which match different components of interest.
+For example, an RFC-822 header line is divided into a header name and a value,
+separated by a ``':'``, like this::
+
+ From: author@example.com
+ User-Agent: Thunderbird 1.5.0.9 (X11/20061227)
+ MIME-Version: 1.0
+ To: editor@example.com
+
+This can be handled by writing a regular expression which matches an entire
+header line, and has one group which matches the header name, and another group
+which matches the header's value.
+
+Groups are marked by the ``'('``, ``')'`` metacharacters. ``'('`` and ``')'``
+have much the same meaning as they do in mathematical expressions; they group
+together the expressions contained inside them, and you can repeat the contents
+of a group with a repeating qualifier, such as ``*``, ``+``, ``?``, or
+``{m,n}``. For example, ``(ab)*`` will match zero or more repetitions of
+``ab``. ::
+
+ >>> p = re.compile('(ab)*')
+ >>> print p.match('ababababab').span()
+ (0, 10)
+
+Groups indicated with ``'('``, ``')'`` also capture the starting and ending
+index of the text that they match; this can be retrieved by passing an argument
+to :meth:`group`, :meth:`start`, :meth:`end`, and :meth:`span`. Groups are
+numbered starting with 0. Group 0 is always present; it's the whole RE, so
+:class:`MatchObject` methods all have group 0 as their default argument. Later
+we'll see how to express groups that don't capture the span of text that they
+match. ::
+
+ >>> p = re.compile('(a)b')
+ >>> m = p.match('ab')
+ >>> m.group()
+ 'ab'
+ >>> m.group(0)
+ 'ab'
+
+Subgroups are numbered from left to right, from 1 upward. Groups can be nested;
+to determine the number, just count the opening parenthesis characters, going
+from left to right. ::
+
+ >>> p = re.compile('(a(b)c)d')
+ >>> m = p.match('abcd')
+ >>> m.group(0)
+ 'abcd'
+ >>> m.group(1)
+ 'abc'
+ >>> m.group(2)
+ 'b'
+
+:meth:`group` can be passed multiple group numbers at a time, in which case it
+will return a tuple containing the corresponding values for those groups. ::
+
+ >>> m.group(2,1,2)
+ ('b', 'abc', 'b')
+
+The :meth:`groups` method returns a tuple containing the strings for all the
+subgroups, from 1 up to however many there are. ::
+
+ >>> m.groups()
+ ('abc', 'b')
+
+Backreferences in a pattern allow you to specify that the contents of an earlier
+capturing group must also be found at the current location in the string. For
+example, ``\1`` will succeed if the exact contents of group 1 can be found at
+the current position, and fails otherwise. Remember that Python's string
+literals also use a backslash followed by numbers to allow including arbitrary
+characters in a string, so be sure to use a raw string when incorporating
+backreferences in a RE.
+
+For example, the following RE detects doubled words in a string. ::
+
+ >>> p = re.compile(r'(\b\w+)\s+\1')
+ >>> p.search('Paris in the the spring').group()
+ 'the the'
+
+Backreferences like this aren't often useful for just searching through a string
+--- there are few text formats which repeat data in this way --- but you'll soon
+find out that they're *very* useful when performing string substitutions.
+
+
+Non-capturing and Named Groups
+------------------------------
+
+Elaborate REs may use many groups, both to capture substrings of interest, and
+to group and structure the RE itself. In complex REs, it becomes difficult to
+keep track of the group numbers. There are two features which help with this
+problem. Both of them use a common syntax for regular expression extensions, so
+we'll look at that first.
+
+Perl 5 added several additional features to standard regular expressions, and
+the Python :mod:`re` module supports most of them. It would have been
+difficult to choose new single-keystroke metacharacters or new special sequences
+beginning with ``\`` to represent the new features without making Perl's regular
+expressions confusingly different from standard REs. If you chose ``&`` as a
+new metacharacter, for example, old expressions would be assuming that ``&`` was
+a regular character and wouldn't have escaped it by writing ``\&`` or ``[&]``.
+
+The solution chosen by the Perl developers was to use ``(?...)`` as the
+extension syntax. ``?`` immediately after a parenthesis was a syntax error
+because the ``?`` would have nothing to repeat, so this didn't introduce any
+compatibility problems. The characters immediately after the ``?`` indicate
+what extension is being used, so ``(?=foo)`` is one thing (a positive lookahead
+assertion) and ``(?:foo)`` is something else (a non-capturing group containing
+the subexpression ``foo``).
+
+Python adds an extension syntax to Perl's extension syntax. If the first
+character after the question mark is a ``P``, you know that it's an extension
+that's specific to Python. Currently there are two such extensions:
+``(?P<name>...)`` defines a named group, and ``(?P=name)`` is a backreference to
+a named group. If future versions of Perl 5 add similar features using a
+different syntax, the :mod:`re` module will be changed to support the new
+syntax, while preserving the Python-specific syntax for compatibility's sake.
+
+Now that we've looked at the general extension syntax, we can return to the
+features that simplify working with groups in complex REs. Since groups are
+numbered from left to right and a complex expression may use many groups, it can
+become difficult to keep track of the correct numbering. Modifying such a
+complex RE is annoying, too: insert a new group near the beginning and you
+change the numbers of everything that follows it.
+
+Sometimes you'll want to use a group to collect a part of a regular expression,
+but aren't interested in retrieving the group's contents. You can make this fact
+explicit by using a non-capturing group: ``(?:...)``, where you can replace the
+``...`` with any other regular expression. ::
+
+ >>> m = re.match("([abc])+", "abc")
+ >>> m.groups()
+ ('c',)
+ >>> m = re.match("(?:[abc])+", "abc")
+ >>> m.groups()
+ ()
+
+Except for the fact that you can't retrieve the contents of what the group
+matched, a non-capturing group behaves exactly the same as a capturing group;
+you can put anything inside it, repeat it with a repetition metacharacter such
+as ``*``, and nest it within other groups (capturing or non-capturing).
+``(?:...)`` is particularly useful when modifying an existing pattern, since you
+can add new groups without changing how all the other groups are numbered. It
+should be mentioned that there's no performance difference in searching between
+capturing and non-capturing groups; neither form is any faster than the other.
+
+A more significant feature is named groups: instead of referring to them by
+numbers, groups can be referenced by a name.
+
+The syntax for a named group is one of the Python-specific extensions:
+``(?P<name>...)``. *name* is, obviously, the name of the group. Named groups
+also behave exactly like capturing groups, and additionally associate a name
+with a group. The :class:`MatchObject` methods that deal with capturing groups
+all accept either integers that refer to the group by number or strings that
+contain the desired group's name. Named groups are still given numbers, so you
+can retrieve information about a group in two ways::
+
+ >>> p = re.compile(r'(?P<word>\b\w+\b)')
+ >>> m = p.search( '(((( Lots of punctuation )))' )
+ >>> m.group('word')
+ 'Lots'
+ >>> m.group(1)
+ 'Lots'
+
+Named groups are handy because they let you use easily-remembered names, instead
+of having to remember numbers. Here's an example RE from the :mod:`imaplib`
+module::
+
+ InternalDate = re.compile(r'INTERNALDATE "'
+ r'(?P<day>[ 123][0-9])-(?P<mon>[A-Z][a-z][a-z])-'
+ r'(?P<year>[0-9][0-9][0-9][0-9])'
+ r' (?P<hour>[0-9][0-9]):(?P<min>[0-9][0-9]):(?P<sec>[0-9][0-9])'
+ r' (?P<zonen>[-+])(?P<zoneh>[0-9][0-9])(?P<zonem>[0-9][0-9])'
+ r'"')
+
+It's obviously much easier to retrieve ``m.group('zonem')``, instead of having
+to remember to retrieve group 9.
+
+The syntax for backreferences in an expression such as ``(...)\1`` refers to the
+number of the group. There's naturally a variant that uses the group name
+instead of the number. This is another Python extension: ``(?P=name)`` indicates
+that the contents of the group called *name* should again be matched at the
+current point. The regular expression for finding doubled words,
+``(\b\w+)\s+\1`` can also be written as ``(?P<word>\b\w+)\s+(?P=word)``::
+
+ >>> p = re.compile(r'(?P<word>\b\w+)\s+(?P=word)')
+ >>> p.search('Paris in the the spring').group()
+ 'the the'
+
+
+Lookahead Assertions
+--------------------
+
+Another zero-width assertion is the lookahead assertion. Lookahead assertions
+are available in both positive and negative form, and look like this:
+
+``(?=...)``
+ Positive lookahead assertion. This succeeds if the contained regular
+ expression, represented here by ``...``, successfully matches at the current
+ location, and fails otherwise. But, once the contained expression has been
+ tried, the matching engine doesn't advance at all; the rest of the pattern is
+ tried right where the assertion started.
+
+``(?!...)``
+ Negative lookahead assertion. This is the opposite of the positive assertion;
+ it succeeds if the contained expression *doesn't* match at the current position
+ in the string.
+
+To make this concrete, let's look at a case where a lookahead is useful.
+Consider a simple pattern to match a filename and split it apart into a base
+name and an extension, separated by a ``.``. For example, in ``news.rc``,
+``news`` is the base name, and ``rc`` is the filename's extension.
+
+The pattern to match this is quite simple:
+
+``.*[.].*$``
+
+Notice that the ``.`` needs to be treated specially because it's a
+metacharacter; I've put it inside a character class. Also notice the trailing
+``$``; this is added to ensure that all the rest of the string must be included
+in the extension. This regular expression matches ``foo.bar`` and
+``autoexec.bat`` and ``sendmail.cf`` and ``printers.conf``.
+
+Now, consider complicating the problem a bit; what if you want to match
+filenames where the extension is not ``bat``? Some incorrect attempts:
+
+``.*[.][^b].*$`` The first attempt above tries to exclude ``bat`` by requiring
+that the first character of the extension is not a ``b``. This is wrong,
+because the pattern also doesn't match ``foo.bar``.
+
+.. % $
+
+``.*[.]([^b]..|.[^a].|..[^t])$``
+
+.. % Messes up the HTML without the curly braces around \^
+
+The expression gets messier when you try to patch up the first solution by
+requiring one of the following cases to match: the first character of the
+extension isn't ``b``; the second character isn't ``a``; or the third character
+isn't ``t``. This accepts ``foo.bar`` and rejects ``autoexec.bat``, but it
+requires a three-letter extension and won't accept a filename with a two-letter
+extension such as ``sendmail.cf``. We'll complicate the pattern again in an
+effort to fix it.
+
+``.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$``
+
+In the third attempt, the second and third letters are all made optional in
+order to allow matching extensions shorter than three characters, such as
+``sendmail.cf``.
+
+The pattern's getting really complicated now, which makes it hard to read and
+understand. Worse, if the problem changes and you want to exclude both ``bat``
+and ``exe`` as extensions, the pattern would get even more complicated and
+confusing.
+
+A negative lookahead cuts through all this confusion:
+
+``.*[.](?!bat$).*$`` The negative lookahead means: if the expression ``bat``
+doesn't match at this point, try the rest of the pattern; if ``bat$`` does
+match, the whole pattern will fail. The trailing ``$`` is required to ensure
+that something like ``sample.batch``, where the extension only starts with
+``bat``, will be allowed.
+
+.. % $
+
+Excluding another filename extension is now easy; simply add it as an
+alternative inside the assertion. The following pattern excludes filenames that
+end in either ``bat`` or ``exe``:
+
+``.*[.](?!bat$|exe$).*$``
+
+.. % $
+
+
+Modifying Strings
+=================
+
+Up to this point, we've simply performed searches against a static string.
+Regular expressions are also commonly used to modify strings in various ways,
+using the following :class:`RegexObject` methods:
+
++------------------+-----------------------------------------------+
+| Method/Attribute | Purpose |
++==================+===============================================+
+| ``split()`` | Split the string into a list, splitting it |
+| | wherever the RE matches |
++------------------+-----------------------------------------------+
+| ``sub()`` | Find all substrings where the RE matches, and |
+| | replace them with a different string |
++------------------+-----------------------------------------------+
+| ``subn()`` | Does the same thing as :meth:`sub`, but |
+| | returns the new string and the number of |
+| | replacements |
++------------------+-----------------------------------------------+
+
+
+Splitting Strings
+-----------------
+
+The :meth:`split` method of a :class:`RegexObject` splits a string apart
+wherever the RE matches, returning a list of the pieces. It's similar to the
+:meth:`split` method of strings but provides much more generality in the
+delimiters that you can split by; :meth:`split` only supports splitting by
+whitespace or by a fixed string. As you'd expect, there's a module-level
+:func:`re.split` function, too.
+
+
+.. method:: .split(string [, maxsplit=0])
+ :noindex:
+
+ Split *string* by the matches of the regular expression. If capturing
+ parentheses are used in the RE, then their contents will also be returned as
+ part of the resulting list. If *maxsplit* is nonzero, at most *maxsplit* splits
+ are performed.
+
+You can limit the number of splits made, by passing a value for *maxsplit*.
+When *maxsplit* is nonzero, at most *maxsplit* splits will be made, and the
+remainder of the string is returned as the final element of the list. In the
+following example, the delimiter is any sequence of non-alphanumeric characters.
+::
+
+ >>> p = re.compile(r'\W+')
+ >>> p.split('This is a test, short and sweet, of split().')
+ ['This', 'is', 'a', 'test', 'short', 'and', 'sweet', 'of', 'split', '']
+ >>> p.split('This is a test, short and sweet, of split().', 3)
+ ['This', 'is', 'a', 'test, short and sweet, of split().']
+
+Sometimes you're not only interested in what the text between delimiters is, but
+also need to know what the delimiter was. If capturing parentheses are used in
+the RE, then their values are also returned as part of the list. Compare the
+following calls::
+
+ >>> p = re.compile(r'\W+')
+ >>> p2 = re.compile(r'(\W+)')
+ >>> p.split('This... is a test.')
+ ['This', 'is', 'a', 'test', '']
+ >>> p2.split('This... is a test.')
+ ['This', '... ', 'is', ' ', 'a', ' ', 'test', '.', '']
+
+The module-level function :func:`re.split` adds the RE to be used as the first
+argument, but is otherwise the same. ::
+
+ >>> re.split('[\W]+', 'Words, words, words.')
+ ['Words', 'words', 'words', '']
+ >>> re.split('([\W]+)', 'Words, words, words.')
+ ['Words', ', ', 'words', ', ', 'words', '.', '']
+ >>> re.split('[\W]+', 'Words, words, words.', 1)
+ ['Words', 'words, words.']
+
+
+Search and Replace
+------------------
+
+Another common task is to find all the matches for a pattern, and replace them
+with a different string. The :meth:`sub` method takes a replacement value,
+which can be either a string or a function, and the string to be processed.
+
+
+.. method:: .sub(replacement, string[, count=0])
+ :noindex:
+
+ Returns the string obtained by replacing the leftmost non-overlapping
+ occurrences of the RE in *string* by the replacement *replacement*. If the
+ pattern isn't found, *string* is returned unchanged.
+
+ The optional argument *count* is the maximum number of pattern occurrences to be
+ replaced; *count* must be a non-negative integer. The default value of 0 means
+ to replace all occurrences.
+
+Here's a simple example of using the :meth:`sub` method. It replaces colour
+names with the word ``colour``::
+
+ >>> p = re.compile( '(blue|white|red)')
+ >>> p.sub( 'colour', 'blue socks and red shoes')
+ 'colour socks and colour shoes'
+ >>> p.sub( 'colour', 'blue socks and red shoes', count=1)
+ 'colour socks and red shoes'
+
+The :meth:`subn` method does the same work, but returns a 2-tuple containing the
+new string value and the number of replacements that were performed::
+
+ >>> p = re.compile( '(blue|white|red)')
+ >>> p.subn( 'colour', 'blue socks and red shoes')
+ ('colour socks and colour shoes', 2)
+ >>> p.subn( 'colour', 'no colours at all')
+ ('no colours at all', 0)
+
+Empty matches are replaced only when they're not adjacent to a previous match.
+::
+
+ >>> p = re.compile('x*')
+ >>> p.sub('-', 'abxd')
+ '-a-b-d-'
+
+If *replacement* is a string, any backslash escapes in it are processed. That
+is, ``\n`` is converted to a single newline character, ``\r`` is converted to a
+carriage return, and so forth. Unknown escapes such as ``\j`` are left alone.
+Backreferences, such as ``\6``, are replaced with the substring matched by the
+corresponding group in the RE. This lets you incorporate portions of the
+original text in the resulting replacement string.
+
+This example matches the word ``section`` followed by a string enclosed in
+``{``, ``}``, and changes ``section`` to ``subsection``::
+
+ >>> p = re.compile('section{ ( [^}]* ) }', re.VERBOSE)
+ >>> p.sub(r'subsection{\1}','section{First} section{second}')
+ 'subsection{First} subsection{second}'
+
+There's also a syntax for referring to named groups as defined by the
+``(?P<name>...)`` syntax. ``\g<name>`` will use the substring matched by the
+group named ``name``, and ``\g<number>`` uses the corresponding group number.
+``\g<2>`` is therefore equivalent to ``\2``, but isn't ambiguous in a
+replacement string such as ``\g<2>0``. (``\20`` would be interpreted as a
+reference to group 20, not a reference to group 2 followed by the literal
+character ``'0'``.) The following substitutions are all equivalent, but use all
+three variations of the replacement string. ::
+
+ >>> p = re.compile('section{ (?P<name> [^}]* ) }', re.VERBOSE)
+ >>> p.sub(r'subsection{\1}','section{First}')
+ 'subsection{First}'
+ >>> p.sub(r'subsection{\g<1>}','section{First}')
+ 'subsection{First}'
+ >>> p.sub(r'subsection{\g<name>}','section{First}')
+ 'subsection{First}'
+
+*replacement* can also be a function, which gives you even more control. If
+*replacement* is a function, the function is called for every non-overlapping
+occurrence of *pattern*. On each call, the function is passed a
+:class:`MatchObject` argument for the match and can use this information to
+compute the desired replacement string and return it.
+
+In the following example, the replacement function translates decimals into
+hexadecimal::
+
+ >>> def hexrepl( match ):
+ ... "Return the hex string for a decimal number"
+ ... value = int( match.group() )
+ ... return hex(value)
+ ...
+ >>> p = re.compile(r'\d+')
+ >>> p.sub(hexrepl, 'Call 65490 for printing, 49152 for user code.')
+ 'Call 0xffd2 for printing, 0xc000 for user code.'
+
+When using the module-level :func:`re.sub` function, the pattern is passed as
+the first argument. The pattern may be a string or a :class:`RegexObject`; if
+you need to specify regular expression flags, you must either use a
+:class:`RegexObject` as the first parameter, or use embedded modifiers in the
+pattern, e.g. ``sub("(?i)b+", "x", "bbbb BBBB")`` returns ``'x x'``.
+
+
+Common Problems
+===============
+
+Regular expressions are a powerful tool for some applications, but in some ways
+their behaviour isn't intuitive and at times they don't behave the way you may
+expect them to. This section will point out some of the most common pitfalls.
+
+
+Use String Methods
+------------------
+
+Sometimes using the :mod:`re` module is a mistake. If you're matching a fixed
+string, or a single character class, and you're not using any :mod:`re` features
+such as the :const:`IGNORECASE` flag, then the full power of regular expressions
+may not be required. Strings have several methods for performing operations with
+fixed strings and they're usually much faster, because the implementation is a
+single small C loop that's been optimized for the purpose, instead of the large,
+more generalized regular expression engine.
+
+One example might be replacing a single fixed string with another one; for
+example, you might replace ``word`` with ``deed``. ``re.sub()`` seems like the
+function to use for this, but consider the :meth:`replace` method. Note that
+:func:`replace` will also replace ``word`` inside words, turning ``swordfish``
+into ``sdeedfish``, but the naive RE ``word`` would have done that, too. (To
+avoid performing the substitution on parts of words, the pattern would have to
+be ``\bword\b``, in order to require that ``word`` have a word boundary on
+either side. This takes the job beyond :meth:`replace`'s abilities.)
+
+Another common task is deleting every occurrence of a single character from a
+string or replacing it with another single character. You might do this with
+something like ``re.sub('\n', ' ', S)``, but :meth:`translate` is capable of
+doing both tasks and will be faster than any regular expression operation can
+be.
+
+In short, before turning to the :mod:`re` module, consider whether your problem
+can be solved with a faster and simpler string method.
+
+
+match() versus search()
+-----------------------
+
+The :func:`match` function only checks if the RE matches at the beginning of the
+string while :func:`search` will scan forward through the string for a match.
+It's important to keep this distinction in mind. Remember, :func:`match` will
+only report a successful match which will start at 0; if the match wouldn't
+start at zero, :func:`match` will *not* report it. ::
+
+ >>> print re.match('super', 'superstition').span()
+ (0, 5)
+ >>> print re.match('super', 'insuperable')
+ None
+
+On the other hand, :func:`search` will scan forward through the string,
+reporting the first match it finds. ::
+
+ >>> print re.search('super', 'superstition').span()
+ (0, 5)
+ >>> print re.search('super', 'insuperable').span()
+ (2, 7)
+
+Sometimes you'll be tempted to keep using :func:`re.match`, and just add ``.*``
+to the front of your RE. Resist this temptation and use :func:`re.search`
+instead. The regular expression compiler does some analysis of REs in order to
+speed up the process of looking for a match. One such analysis figures out what
+the first character of a match must be; for example, a pattern starting with
+``Crow`` must match starting with a ``'C'``. The analysis lets the engine
+quickly scan through the string looking for the starting character, only trying
+the full match if a ``'C'`` is found.
+
+Adding ``.*`` defeats this optimization, requiring scanning to the end of the
+string and then backtracking to find a match for the rest of the RE. Use
+:func:`re.search` instead.
+
+
+Greedy versus Non-Greedy
+------------------------
+
+When repeating a regular expression, as in ``a*``, the resulting action is to
+consume as much of the pattern as possible. This fact often bites you when
+you're trying to match a pair of balanced delimiters, such as the angle brackets
+surrounding an HTML tag. The naive pattern for matching a single HTML tag
+doesn't work because of the greedy nature of ``.*``. ::
+
+ >>> s = '<html><head><title>Title</title>'
+ >>> len(s)
+ 32
+ >>> print re.match('<.*>', s).span()
+ (0, 32)
+ >>> print re.match('<.*>', s).group()
+ <html><head><title>Title</title>
+
+The RE matches the ``'<'`` in ``<html>``, and the ``.*`` consumes the rest of
+the string. There's still more left in the RE, though, and the ``>`` can't
+match at the end of the string, so the regular expression engine has to
+backtrack character by character until it finds a match for the ``>``. The
+final match extends from the ``'<'`` in ``<html>`` to the ``'>'`` in
+``</title>``, which isn't what you want.
+
+In this case, the solution is to use the non-greedy qualifiers ``*?``, ``+?``,
+``??``, or ``{m,n}?``, which match as *little* text as possible. In the above
+example, the ``'>'`` is tried immediately after the first ``'<'`` matches, and
+when it fails, the engine advances a character at a time, retrying the ``'>'``
+at every step. This produces just the right result::
+
+ >>> print re.match('<.*?>', s).group()
+ <html>
+
+(Note that parsing HTML or XML with regular expressions is painful.
+Quick-and-dirty patterns will handle common cases, but HTML and XML have special
+cases that will break the obvious regular expression; by the time you've written
+a regular expression that handles all of the possible cases, the patterns will
+be *very* complicated. Use an HTML or XML parser module for such tasks.)
+
+
+Not Using re.VERBOSE
+--------------------
+
+By now you've probably noticed that regular expressions are a very compact
+notation, but they're not terribly readable. REs of moderate complexity can
+become lengthy collections of backslashes, parentheses, and metacharacters,
+making them difficult to read and understand.
+
+For such REs, specifying the ``re.VERBOSE`` flag when compiling the regular
+expression can be helpful, because it allows you to format the regular
+expression more clearly.
+
+The ``re.VERBOSE`` flag has several effects. Whitespace in the regular
+expression that *isn't* inside a character class is ignored. This means that an
+expression such as ``dog | cat`` is equivalent to the less readable ``dog|cat``,
+but ``[a b]`` will still match the characters ``'a'``, ``'b'``, or a space. In
+addition, you can also put comments inside a RE; comments extend from a ``#``
+character to the next newline. When used with triple-quoted strings, this
+enables REs to be formatted more neatly::
+
+ pat = re.compile(r"""
+ \s* # Skip leading whitespace
+ (?P<header>[^:]+) # Header name
+ \s* : # Whitespace, and a colon
+ (?P<value>.*?) # The header's value -- *? used to
+ # lose the following trailing whitespace
+ \s*$ # Trailing whitespace to end-of-line
+ """, re.VERBOSE)
+
+This is far more readable than:
+
+.. % $
+
+::
+
+ pat = re.compile(r"\s*(?P<header>[^:]+)\s*:(?P<value>.*?)\s*$")
+
+.. % $
+
+
+Feedback
+========
+
+Regular expressions are a complicated topic. Did this document help you
+understand them? Were there parts that were unclear, or Problems you
+encountered that weren't covered here? If so, please send suggestions for
+improvements to the author.
+
+The most complete book on regular expressions is almost certainly Jeffrey
+Friedl's Mastering Regular Expressions, published by O'Reilly. Unfortunately,
+it exclusively concentrates on Perl and Java's flavours of regular expressions,
+and doesn't contain any Python material at all, so it won't be useful as a
+reference for programming in Python. (The first edition covered Python's
+now-removed :mod:`regex` module, which won't help you much.) Consider checking
+it out from your library.
+
+
+.. rubric:: Footnotes
+
+.. [#] Introduced in Python 2.2.2.
+
--- /dev/null
+****************************
+ Socket Programming HOWTO
+****************************
+
+:Author: Gordon McMillan
+
+
+.. topic:: Abstract
+
+ Sockets are used nearly everywhere, but are one of the most severely
+ misunderstood technologies around. This is a 10,000 foot overview of sockets.
+ It's not really a tutorial - you'll still have work to do in getting things
+ operational. It doesn't cover the fine points (and there are a lot of them), but
+ I hope it will give you enough background to begin using them decently.
+
+
+Sockets
+=======
+
+Sockets are used nearly everywhere, but are one of the most severely
+misunderstood technologies around. This is a 10,000 foot overview of sockets.
+It's not really a tutorial - you'll still have work to do in getting things
+working. It doesn't cover the fine points (and there are a lot of them), but I
+hope it will give you enough background to begin using them decently.
+
+I'm only going to talk about INET sockets, but they account for at least 99% of
+the sockets in use. And I'll only talk about STREAM sockets - unless you really
+know what you're doing (in which case this HOWTO isn't for you!), you'll get
+better behavior and performance from a STREAM socket than anything else. I will
+try to clear up the mystery of what a socket is, as well as some hints on how to
+work with blocking and non-blocking sockets. But I'll start by talking about
+blocking sockets. You'll need to know how they work before dealing with
+non-blocking sockets.
+
+Part of the trouble with understanding these things is that "socket" can mean a
+number of subtly different things, depending on context. So first, let's make a
+distinction between a "client" socket - an endpoint of a conversation, and a
+"server" socket, which is more like a switchboard operator. The client
+application (your browser, for example) uses "client" sockets exclusively; the
+web server it's talking to uses both "server" sockets and "client" sockets.
+
+
+History
+-------
+
+Of the various forms of IPC (*Inter Process Communication*), sockets are by far
+the most popular. On any given platform, there are likely to be other forms of
+IPC that are faster, but for cross-platform communication, sockets are about the
+only game in town.
+
+They were invented in Berkeley as part of the BSD flavor of Unix. They spread
+like wildfire with the Internet. With good reason --- the combination of sockets
+with INET makes talking to arbitrary machines around the world unbelievably easy
+(at least compared to other schemes).
+
+
+Creating a Socket
+=================
+
+Roughly speaking, when you clicked on the link that brought you to this page,
+your browser did something like the following::
+
+ #create an INET, STREAMing socket
+ s = socket.socket(
+ socket.AF_INET, socket.SOCK_STREAM)
+ #now connect to the web server on port 80
+ # - the normal http port
+ s.connect(("www.mcmillan-inc.com", 80))
+
+When the ``connect`` completes, the socket ``s`` can now be used to send in a
+request for the text of this page. The same socket will read the reply, and then
+be destroyed. That's right - destroyed. Client sockets are normally only used
+for one exchange (or a small set of sequential exchanges).
+
+What happens in the web server is a bit more complex. First, the web server
+creates a "server socket". ::
+
+ #create an INET, STREAMing socket
+ serversocket = socket.socket(
+ socket.AF_INET, socket.SOCK_STREAM)
+ #bind the socket to a public host,
+ # and a well-known port
+ serversocket.bind((socket.gethostname(), 80))
+ #become a server socket
+ serversocket.listen(5)
+
+A couple things to notice: we used ``socket.gethostname()`` so that the socket
+would be visible to the outside world. If we had used ``s.bind(('', 80))`` or
+``s.bind(('localhost', 80))`` or ``s.bind(('127.0.0.1', 80))`` we would still
+have a "server" socket, but one that was only visible within the same machine.
+
+A second thing to note: low number ports are usually reserved for "well known"
+services (HTTP, SNMP etc). If you're playing around, use a nice high number (4
+digits).
+
+Finally, the argument to ``listen`` tells the socket library that we want it to
+queue up as many as 5 connect requests (the normal max) before refusing outside
+connections. If the rest of the code is written properly, that should be plenty.
+
+OK, now we have a "server" socket, listening on port 80. Now we enter the
+mainloop of the web server::
+
+ while 1:
+ #accept connections from outside
+ (clientsocket, address) = serversocket.accept()
+ #now do something with the clientsocket
+ #in this case, we'll pretend this is a threaded server
+ ct = client_thread(clientsocket)
+ ct.run()
+
+There's actually 3 general ways in which this loop could work - dispatching a
+thread to handle ``clientsocket``, create a new process to handle
+``clientsocket``, or restructure this app to use non-blocking sockets, and
+mulitplex between our "server" socket and any active ``clientsocket``\ s using
+``select``. More about that later. The important thing to understand now is
+this: this is *all* a "server" socket does. It doesn't send any data. It doesn't
+receive any data. It just produces "client" sockets. Each ``clientsocket`` is
+created in response to some *other* "client" socket doing a ``connect()`` to the
+host and port we're bound to. As soon as we've created that ``clientsocket``, we
+go back to listening for more connections. The two "clients" are free to chat it
+up - they are using some dynamically allocated port which will be recycled when
+the conversation ends.
+
+
+IPC
+---
+
+If you need fast IPC between two processes on one machine, you should look into
+whatever form of shared memory the platform offers. A simple protocol based
+around shared memory and locks or semaphores is by far the fastest technique.
+
+If you do decide to use sockets, bind the "server" socket to ``'localhost'``. On
+most platforms, this will take a shortcut around a couple of layers of network
+code and be quite a bit faster.
+
+
+Using a Socket
+==============
+
+The first thing to note, is that the web browser's "client" socket and the web
+server's "client" socket are identical beasts. That is, this is a "peer to peer"
+conversation. Or to put it another way, *as the designer, you will have to
+decide what the rules of etiquette are for a conversation*. Normally, the
+``connect``\ ing socket starts the conversation, by sending in a request, or
+perhaps a signon. But that's a design decision - it's not a rule of sockets.
+
+Now there are two sets of verbs to use for communication. You can use ``send``
+and ``recv``, or you can transform your client socket into a file-like beast and
+use ``read`` and ``write``. The latter is the way Java presents their sockets.
+I'm not going to talk about it here, except to warn you that you need to use
+``flush`` on sockets. These are buffered "files", and a common mistake is to
+``write`` something, and then ``read`` for a reply. Without a ``flush`` in
+there, you may wait forever for the reply, because the request may still be in
+your output buffer.
+
+Now we come the major stumbling block of sockets - ``send`` and ``recv`` operate
+on the network buffers. They do not necessarily handle all the bytes you hand
+them (or expect from them), because their major focus is handling the network
+buffers. In general, they return when the associated network buffers have been
+filled (``send``) or emptied (``recv``). They then tell you how many bytes they
+handled. It is *your* responsibility to call them again until your message has
+been completely dealt with.
+
+When a ``recv`` returns 0 bytes, it means the other side has closed (or is in
+the process of closing) the connection. You will not receive any more data on
+this connection. Ever. You may be able to send data successfully; I'll talk
+about that some on the next page.
+
+A protocol like HTTP uses a socket for only one transfer. The client sends a
+request, the reads a reply. That's it. The socket is discarded. This means that
+a client can detect the end of the reply by receiving 0 bytes.
+
+But if you plan to reuse your socket for further transfers, you need to realize
+that *there is no "EOT" (End of Transfer) on a socket.* I repeat: if a socket
+``send`` or ``recv`` returns after handling 0 bytes, the connection has been
+broken. If the connection has *not* been broken, you may wait on a ``recv``
+forever, because the socket will *not* tell you that there's nothing more to
+read (for now). Now if you think about that a bit, you'll come to realize a
+fundamental truth of sockets: *messages must either be fixed length* (yuck), *or
+be delimited* (shrug), *or indicate how long they are* (much better), *or end by
+shutting down the connection*. The choice is entirely yours, (but some ways are
+righter than others).
+
+Assuming you don't want to end the connection, the simplest solution is a fixed
+length message::
+
+ class mysocket:
+ '''demonstration class only
+ - coded for clarity, not efficiency
+ '''
+
+ def __init__(self, sock=None):
+ if sock is None:
+ self.sock = socket.socket(
+ socket.AF_INET, socket.SOCK_STREAM)
+ else:
+ self.sock = sock
+
+ def connect(self, host, port):
+ self.sock.connect((host, port))
+
+ def mysend(self, msg):
+ totalsent = 0
+ while totalsent < MSGLEN:
+ sent = self.sock.send(msg[totalsent:])
+ if sent == 0:
+ raise RuntimeError, \
+ "socket connection broken"
+ totalsent = totalsent + sent
+
+ def myreceive(self):
+ msg = ''
+ while len(msg) < MSGLEN:
+ chunk = self.sock.recv(MSGLEN-len(msg))
+ if chunk == '':
+ raise RuntimeError, \
+ "socket connection broken"
+ msg = msg + chunk
+ return msg
+
+The sending code here is usable for almost any messaging scheme - in Python you
+send strings, and you can use ``len()`` to determine its length (even if it has
+embedded ``\0`` characters). It's mostly the receiving code that gets more
+complex. (And in C, it's not much worse, except you can't use ``strlen`` if the
+message has embedded ``\0``\ s.)
+
+The easiest enhancement is to make the first character of the message an
+indicator of message type, and have the type determine the length. Now you have
+two ``recv``\ s - the first to get (at least) that first character so you can
+look up the length, and the second in a loop to get the rest. If you decide to
+go the delimited route, you'll be receiving in some arbitrary chunk size, (4096
+or 8192 is frequently a good match for network buffer sizes), and scanning what
+you've received for a delimiter.
+
+One complication to be aware of: if your conversational protocol allows multiple
+messages to be sent back to back (without some kind of reply), and you pass
+``recv`` an arbitrary chunk size, you may end up reading the start of a
+following message. You'll need to put that aside and hold onto it, until it's
+needed.
+
+Prefixing the message with it's length (say, as 5 numeric characters) gets more
+complex, because (believe it or not), you may not get all 5 characters in one
+``recv``. In playing around, you'll get away with it; but in high network loads,
+your code will very quickly break unless you use two ``recv`` loops - the first
+to determine the length, the second to get the data part of the message. Nasty.
+This is also when you'll discover that ``send`` does not always manage to get
+rid of everything in one pass. And despite having read this, you will eventually
+get bit by it!
+
+In the interests of space, building your character, (and preserving my
+competitive position), these enhancements are left as an exercise for the
+reader. Lets move on to cleaning up.
+
+
+Binary Data
+-----------
+
+It is perfectly possible to send binary data over a socket. The major problem is
+that not all machines use the same formats for binary data. For example, a
+Motorola chip will represent a 16 bit integer with the value 1 as the two hex
+bytes 00 01. Intel and DEC, however, are byte-reversed - that same 1 is 01 00.
+Socket libraries have calls for converting 16 and 32 bit integers - ``ntohl,
+htonl, ntohs, htons`` where "n" means *network* and "h" means *host*, "s" means
+*short* and "l" means *long*. Where network order is host order, these do
+nothing, but where the machine is byte-reversed, these swap the bytes around
+appropriately.
+
+In these days of 32 bit machines, the ascii representation of binary data is
+frequently smaller than the binary representation. That's because a surprising
+amount of the time, all those longs have the value 0, or maybe 1. The string "0"
+would be two bytes, while binary is four. Of course, this doesn't fit well with
+fixed-length messages. Decisions, decisions.
+
+
+Disconnecting
+=============
+
+Strictly speaking, you're supposed to use ``shutdown`` on a socket before you
+``close`` it. The ``shutdown`` is an advisory to the socket at the other end.
+Depending on the argument you pass it, it can mean "I'm not going to send
+anymore, but I'll still listen", or "I'm not listening, good riddance!". Most
+socket libraries, however, are so used to programmers neglecting to use this
+piece of etiquette that normally a ``close`` is the same as ``shutdown();
+close()``. So in most situations, an explicit ``shutdown`` is not needed.
+
+One way to use ``shutdown`` effectively is in an HTTP-like exchange. The client
+sends a request and then does a ``shutdown(1)``. This tells the server "This
+client is done sending, but can still receive." The server can detect "EOF" by
+a receive of 0 bytes. It can assume it has the complete request. The server
+sends a reply. If the ``send`` completes successfully then, indeed, the client
+was still receiving.
+
+Python takes the automatic shutdown a step further, and says that when a socket
+is garbage collected, it will automatically do a ``close`` if it's needed. But
+relying on this is a very bad habit. If your socket just disappears without
+doing a ``close``, the socket at the other end may hang indefinitely, thinking
+you're just being slow. *Please* ``close`` your sockets when you're done.
+
+
+When Sockets Die
+----------------
+
+Probably the worst thing about using blocking sockets is what happens when the
+other side comes down hard (without doing a ``close``). Your socket is likely to
+hang. SOCKSTREAM is a reliable protocol, and it will wait a long, long time
+before giving up on a connection. If you're using threads, the entire thread is
+essentially dead. There's not much you can do about it. As long as you aren't
+doing something dumb, like holding a lock while doing a blocking read, the
+thread isn't really consuming much in the way of resources. Do *not* try to kill
+the thread - part of the reason that threads are more efficient than processes
+is that they avoid the overhead associated with the automatic recycling of
+resources. In other words, if you do manage to kill the thread, your whole
+process is likely to be screwed up.
+
+
+Non-blocking Sockets
+====================
+
+If you've understood the preceeding, you already know most of what you need to
+know about the mechanics of using sockets. You'll still use the same calls, in
+much the same ways. It's just that, if you do it right, your app will be almost
+inside-out.
+
+In Python, you use ``socket.setblocking(0)`` to make it non-blocking. In C, it's
+more complex, (for one thing, you'll need to choose between the BSD flavor
+``O_NONBLOCK`` and the almost indistinguishable Posix flavor ``O_NDELAY``, which
+is completely different from ``TCP_NODELAY``), but it's the exact same idea. You
+do this after creating the socket, but before using it. (Actually, if you're
+nuts, you can switch back and forth.)
+
+The major mechanical difference is that ``send``, ``recv``, ``connect`` and
+``accept`` can return without having done anything. You have (of course) a
+number of choices. You can check return code and error codes and generally drive
+yourself crazy. If you don't believe me, try it sometime. Your app will grow
+large, buggy and suck CPU. So let's skip the brain-dead solutions and do it
+right.
+
+Use ``select``.
+
+In C, coding ``select`` is fairly complex. In Python, it's a piece of cake, but
+it's close enough to the C version that if you understand ``select`` in Python,
+you'll have little trouble with it in C. ::
+
+ ready_to_read, ready_to_write, in_error = \
+ select.select(
+ potential_readers,
+ potential_writers,
+ potential_errs,
+ timeout)
+
+You pass ``select`` three lists: the first contains all sockets that you might
+want to try reading; the second all the sockets you might want to try writing
+to, and the last (normally left empty) those that you want to check for errors.
+You should note that a socket can go into more than one list. The ``select``
+call is blocking, but you can give it a timeout. This is generally a sensible
+thing to do - give it a nice long timeout (say a minute) unless you have good
+reason to do otherwise.
+
+In return, you will get three lists. They have the sockets that are actually
+readable, writable and in error. Each of these lists is a subset (possbily
+empty) of the corresponding list you passed in. And if you put a socket in more
+than one input list, it will only be (at most) in one output list.
+
+If a socket is in the output readable list, you can be
+as-close-to-certain-as-we-ever-get-in-this-business that a ``recv`` on that
+socket will return *something*. Same idea for the writable list. You'll be able
+to send *something*. Maybe not all you want to, but *something* is better than
+nothing. (Actually, any reasonably healthy socket will return as writable - it
+just means outbound network buffer space is available.)
+
+If you have a "server" socket, put it in the potential_readers list. If it comes
+out in the readable list, your ``accept`` will (almost certainly) work. If you
+have created a new socket to ``connect`` to someone else, put it in the
+ptoential_writers list. If it shows up in the writable list, you have a decent
+chance that it has connected.
+
+One very nasty problem with ``select``: if somewhere in those input lists of
+sockets is one which has died a nasty death, the ``select`` will fail. You then
+need to loop through every single damn socket in all those lists and do a
+``select([sock],[],[],0)`` until you find the bad one. That timeout of 0 means
+it won't take long, but it's ugly.
+
+Actually, ``select`` can be handy even with blocking sockets. It's one way of
+determining whether you will block - the socket returns as readable when there's
+something in the buffers. However, this still doesn't help with the problem of
+determining whether the other end is done, or just busy with something else.
+
+**Portability alert**: On Unix, ``select`` works both with the sockets and
+files. Don't try this on Windows. On Windows, ``select`` works with sockets
+only. Also note that in C, many of the more advanced socket options are done
+differently on Windows. In fact, on Windows I usually use threads (which work
+very, very well) with my sockets. Face it, if you want any kind of performance,
+your code will look very different on Windows than on Unix. (I haven't the
+foggiest how you do this stuff on a Mac.)
+
+
+Performance
+-----------
+
+There's no question that the fastest sockets code uses non-blocking sockets and
+select to multiplex them. You can put together something that will saturate a
+LAN connection without putting any strain on the CPU. The trouble is that an app
+written this way can't do much of anything else - it needs to be ready to
+shuffle bytes around at all times.
+
+Assuming that your app is actually supposed to do something more than that,
+threading is the optimal solution, (and using non-blocking sockets will be
+faster than using blocking sockets). Unfortunately, threading support in Unixes
+varies both in API and quality. So the normal Unix solution is to fork a
+subprocess to deal with each connection. The overhead for this is significant
+(and don't do this on Windows - the overhead of process creation is enormous
+there). It also means that unless each subprocess is completely independent,
+you'll need to use another form of IPC, say a pipe, or shared memory and
+semaphores, to communicate between the parent and child processes.
+
+Finally, remember that even though blocking sockets are somewhat slower than
+non-blocking, in many cases they are the "right" solution. After all, if your
+app is driven by the data it receives over a socket, there's not much sense in
+complicating the logic just so your app can wait on ``select`` instead of
+``recv``.
+
--- /dev/null
+*****************
+ Unicode HOWTO
+*****************
+
+:Release: 1.02
+
+This HOWTO discusses Python's support for Unicode, and explains various problems
+that people commonly encounter when trying to work with Unicode.
+
+Introduction to Unicode
+=======================
+
+History of Character Codes
+--------------------------
+
+In 1968, the American Standard Code for Information Interchange, better known by
+its acronym ASCII, was standardized. ASCII defined numeric codes for various
+characters, with the numeric values running from 0 to
+127. For example, the lowercase letter 'a' is assigned 97 as its code
+value.
+
+ASCII was an American-developed standard, so it only defined unaccented
+characters. There was an 'e', but no 'é' or 'Í'. This meant that languages
+which required accented characters couldn't be faithfully represented in ASCII.
+(Actually the missing accents matter for English, too, which contains words such
+as 'naïve' and 'café', and some publications have house styles which require
+spellings such as 'coöperate'.)
+
+For a while people just wrote programs that didn't display accents. I remember
+looking at Apple ][ BASIC programs, published in French-language publications in
+the mid-1980s, that had lines like these::
+
+ PRINT "FICHER EST COMPLETE."
+ PRINT "CARACTERE NON ACCEPTE."
+
+Those messages should contain accents, and they just look wrong to someone who
+can read French.
+
+In the 1980s, almost all personal computers were 8-bit, meaning that bytes could
+hold values ranging from 0 to 255. ASCII codes only went up to 127, so some
+machines assigned values between 128 and 255 to accented characters. Different
+machines had different codes, however, which led to problems exchanging files.
+Eventually various commonly used sets of values for the 128-255 range emerged.
+Some were true standards, defined by the International Standards Organization,
+and some were **de facto** conventions that were invented by one company or
+another and managed to catch on.
+
+255 characters aren't very many. For example, you can't fit both the accented
+characters used in Western Europe and the Cyrillic alphabet used for Russian
+into the 128-255 range because there are more than 127 such characters.
+
+You could write files using different codes (all your Russian files in a coding
+system called KOI8, all your French files in a different coding system called
+Latin1), but what if you wanted to write a French document that quotes some
+Russian text? In the 1980s people began to want to solve this problem, and the
+Unicode standardization effort began.
+
+Unicode started out using 16-bit characters instead of 8-bit characters. 16
+bits means you have 2^16 = 65,536 distinct values available, making it possible
+to represent many different characters from many different alphabets; an initial
+goal was to have Unicode contain the alphabets for every single human language.
+It turns out that even 16 bits isn't enough to meet that goal, and the modern
+Unicode specification uses a wider range of codes, 0-1,114,111 (0x10ffff in
+base-16).
+
+There's a related ISO standard, ISO 10646. Unicode and ISO 10646 were
+originally separate efforts, but the specifications were merged with the 1.1
+revision of Unicode.
+
+(This discussion of Unicode's history is highly simplified. I don't think the
+average Python programmer needs to worry about the historical details; consult
+the Unicode consortium site listed in the References for more information.)
+
+
+Definitions
+-----------
+
+A **character** is the smallest possible component of a text. 'A', 'B', 'C',
+etc., are all different characters. So are 'È' and 'Í'. Characters are
+abstractions, and vary depending on the language or context you're talking
+about. For example, the symbol for ohms (Ω) is usually drawn much like the
+capital letter omega (Ω) in the Greek alphabet (they may even be the same in
+some fonts), but these are two different characters that have different
+meanings.
+
+The Unicode standard describes how characters are represented by **code
+points**. A code point is an integer value, usually denoted in base 16. In the
+standard, a code point is written using the notation U+12ca to mean the
+character with value 0x12ca (4810 decimal). The Unicode standard contains a lot
+of tables listing characters and their corresponding code points::
+
+ 0061 'a'; LATIN SMALL LETTER A
+ 0062 'b'; LATIN SMALL LETTER B
+ 0063 'c'; LATIN SMALL LETTER C
+ ...
+ 007B '{'; LEFT CURLY BRACKET
+
+Strictly, these definitions imply that it's meaningless to say 'this is
+character U+12ca'. U+12ca is a code point, which represents some particular
+character; in this case, it represents the character 'ETHIOPIC SYLLABLE WI'. In
+informal contexts, this distinction between code points and characters will
+sometimes be forgotten.
+
+A character is represented on a screen or on paper by a set of graphical
+elements that's called a **glyph**. The glyph for an uppercase A, for example,
+is two diagonal strokes and a horizontal stroke, though the exact details will
+depend on the font being used. Most Python code doesn't need to worry about
+glyphs; figuring out the correct glyph to display is generally the job of a GUI
+toolkit or a terminal's font renderer.
+
+
+Encodings
+---------
+
+To summarize the previous section: a Unicode string is a sequence of code
+points, which are numbers from 0 to 0x10ffff. This sequence needs to be
+represented as a set of bytes (meaning, values from 0-255) in memory. The rules
+for translating a Unicode string into a sequence of bytes are called an
+**encoding**.
+
+The first encoding you might think of is an array of 32-bit integers. In this
+representation, the string "Python" would look like this::
+
+ P y t h o n
+ 0x50 00 00 00 79 00 00 00 74 00 00 00 68 00 00 00 6f 00 00 00 6e 00 00 00
+ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
+
+This representation is straightforward but using it presents a number of
+problems.
+
+1. It's not portable; different processors order the bytes differently.
+
+2. It's very wasteful of space. In most texts, the majority of the code points
+ are less than 127, or less than 255, so a lot of space is occupied by zero
+ bytes. The above string takes 24 bytes compared to the 6 bytes needed for an
+ ASCII representation. Increased RAM usage doesn't matter too much (desktop
+ computers have megabytes of RAM, and strings aren't usually that large), but
+ expanding our usage of disk and network bandwidth by a factor of 4 is
+ intolerable.
+
+3. It's not compatible with existing C functions such as ``strlen()``, so a new
+ family of wide string functions would need to be used.
+
+4. Many Internet standards are defined in terms of textual data, and can't
+ handle content with embedded zero bytes.
+
+Generally people don't use this encoding, instead choosing other encodings that
+are more efficient and convenient.
+
+Encodings don't have to handle every possible Unicode character, and most
+encodings don't. For example, Python's default encoding is the 'ascii'
+encoding. The rules for converting a Unicode string into the ASCII encoding are
+simple; for each code point:
+
+1. If the code point is < 128, each byte is the same as the value of the code
+ point.
+
+2. If the code point is 128 or greater, the Unicode string can't be represented
+ in this encoding. (Python raises a :exc:`UnicodeEncodeError` exception in this
+ case.)
+
+Latin-1, also known as ISO-8859-1, is a similar encoding. Unicode code points
+0-255 are identical to the Latin-1 values, so converting to this encoding simply
+requires converting code points to byte values; if a code point larger than 255
+is encountered, the string can't be encoded into Latin-1.
+
+Encodings don't have to be simple one-to-one mappings like Latin-1. Consider
+IBM's EBCDIC, which was used on IBM mainframes. Letter values weren't in one
+block: 'a' through 'i' had values from 129 to 137, but 'j' through 'r' were 145
+through 153. If you wanted to use EBCDIC as an encoding, you'd probably use
+some sort of lookup table to perform the conversion, but this is largely an
+internal detail.
+
+UTF-8 is one of the most commonly used encodings. UTF stands for "Unicode
+Transformation Format", and the '8' means that 8-bit numbers are used in the
+encoding. (There's also a UTF-16 encoding, but it's less frequently used than
+UTF-8.) UTF-8 uses the following rules:
+
+1. If the code point is <128, it's represented by the corresponding byte value.
+2. If the code point is between 128 and 0x7ff, it's turned into two byte values
+ between 128 and 255.
+3. Code points >0x7ff are turned into three- or four-byte sequences, where each
+ byte of the sequence is between 128 and 255.
+
+UTF-8 has several convenient properties:
+
+1. It can handle any Unicode code point.
+2. A Unicode string is turned into a string of bytes containing no embedded zero
+ bytes. This avoids byte-ordering issues, and means UTF-8 strings can be
+ processed by C functions such as ``strcpy()`` and sent through protocols that
+ can't handle zero bytes.
+3. A string of ASCII text is also valid UTF-8 text.
+4. UTF-8 is fairly compact; the majority of code points are turned into two
+ bytes, and values less than 128 occupy only a single byte.
+5. If bytes are corrupted or lost, it's possible to determine the start of the
+ next UTF-8-encoded code point and resynchronize. It's also unlikely that
+ random 8-bit data will look like valid UTF-8.
+
+
+
+References
+----------
+
+The Unicode Consortium site at <http://www.unicode.org> has character charts, a
+glossary, and PDF versions of the Unicode specification. Be prepared for some
+difficult reading. <http://www.unicode.org/history/> is a chronology of the
+origin and development of Unicode.
+
+To help understand the standard, Jukka Korpela has written an introductory guide
+to reading the Unicode character tables, available at
+<http://www.cs.tut.fi/~jkorpela/unicode/guide.html>.
+
+Roman Czyborra wrote another explanation of Unicode's basic principles; it's at
+<http://czyborra.com/unicode/characters.html>. Czyborra has written a number of
+other Unicode-related documentation, available from <http://www.cyzborra.com>.
+
+Two other good introductory articles were written by Joel Spolsky
+<http://www.joelonsoftware.com/articles/Unicode.html> and Jason Orendorff
+<http://www.jorendorff.com/articles/unicode/>. If this introduction didn't make
+things clear to you, you should try reading one of these alternate articles
+before continuing.
+
+Wikipedia entries are often helpful; see the entries for "character encoding"
+<http://en.wikipedia.org/wiki/Character_encoding> and UTF-8
+<http://en.wikipedia.org/wiki/UTF-8>, for example.
+
+
+Python's Unicode Support
+========================
+
+Now that you've learned the rudiments of Unicode, we can look at Python's
+Unicode features.
+
+
+The Unicode Type
+----------------
+
+Unicode strings are expressed as instances of the :class:`unicode` type, one of
+Python's repertoire of built-in types. It derives from an abstract type called
+:class:`basestring`, which is also an ancestor of the :class:`str` type; you can
+therefore check if a value is a string type with ``isinstance(value,
+basestring)``. Under the hood, Python represents Unicode strings as either 16-
+or 32-bit integers, depending on how the Python interpreter was compiled.
+
+The :func:`unicode` constructor has the signature ``unicode(string[, encoding,
+errors])``. All of its arguments should be 8-bit strings. The first argument
+is converted to Unicode using the specified encoding; if you leave off the
+``encoding`` argument, the ASCII encoding is used for the conversion, so
+characters greater than 127 will be treated as errors::
+
+ >>> unicode('abcdef')
+ u'abcdef'
+ >>> s = unicode('abcdef')
+ >>> type(s)
+ <type 'unicode'>
+ >>> unicode('abcdef' + chr(255))
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ UnicodeDecodeError: 'ascii' codec can't decode byte 0xff in position 6:
+ ordinal not in range(128)
+
+The ``errors`` argument specifies the response when the input string can't be
+converted according to the encoding's rules. Legal values for this argument are
+'strict' (raise a ``UnicodeDecodeError`` exception), 'replace' (add U+FFFD,
+'REPLACEMENT CHARACTER'), or 'ignore' (just leave the character out of the
+Unicode result). The following examples show the differences::
+
+ >>> unicode('\x80abc', errors='strict')
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ UnicodeDecodeError: 'ascii' codec can't decode byte 0x80 in position 0:
+ ordinal not in range(128)
+ >>> unicode('\x80abc', errors='replace')
+ u'\ufffdabc'
+ >>> unicode('\x80abc', errors='ignore')
+ u'abc'
+
+Encodings are specified as strings containing the encoding's name. Python 2.4
+comes with roughly 100 different encodings; see the Python Library Reference at
+<http://docs.python.org/lib/standard-encodings.html> for a list. Some encodings
+have multiple names; for example, 'latin-1', 'iso_8859_1' and '8859' are all
+synonyms for the same encoding.
+
+One-character Unicode strings can also be created with the :func:`unichr`
+built-in function, which takes integers and returns a Unicode string of length 1
+that contains the corresponding code point. The reverse operation is the
+built-in :func:`ord` function that takes a one-character Unicode string and
+returns the code point value::
+
+ >>> unichr(40960)
+ u'\ua000'
+ >>> ord(u'\ua000')
+ 40960
+
+Instances of the :class:`unicode` type have many of the same methods as the
+8-bit string type for operations such as searching and formatting::
+
+ >>> s = u'Was ever feather so lightly blown to and fro as this multitude?'
+ >>> s.count('e')
+ 5
+ >>> s.find('feather')
+ 9
+ >>> s.find('bird')
+ -1
+ >>> s.replace('feather', 'sand')
+ u'Was ever sand so lightly blown to and fro as this multitude?'
+ >>> s.upper()
+ u'WAS EVER FEATHER SO LIGHTLY BLOWN TO AND FRO AS THIS MULTITUDE?'
+
+Note that the arguments to these methods can be Unicode strings or 8-bit
+strings. 8-bit strings will be converted to Unicode before carrying out the
+operation; Python's default ASCII encoding will be used, so characters greater
+than 127 will cause an exception::
+
+ >>> s.find('Was\x9f')
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ UnicodeDecodeError: 'ascii' codec can't decode byte 0x9f in position 3: ordinal not in range(128)
+ >>> s.find(u'Was\x9f')
+ -1
+
+Much Python code that operates on strings will therefore work with Unicode
+strings without requiring any changes to the code. (Input and output code needs
+more updating for Unicode; more on this later.)
+
+Another important method is ``.encode([encoding], [errors='strict'])``, which
+returns an 8-bit string version of the Unicode string, encoded in the requested
+encoding. The ``errors`` parameter is the same as the parameter of the
+``unicode()`` constructor, with one additional possibility; as well as 'strict',
+'ignore', and 'replace', you can also pass 'xmlcharrefreplace' which uses XML's
+character references. The following example shows the different results::
+
+ >>> u = unichr(40960) + u'abcd' + unichr(1972)
+ >>> u.encode('utf-8')
+ '\xea\x80\x80abcd\xde\xb4'
+ >>> u.encode('ascii')
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ UnicodeEncodeError: 'ascii' codec can't encode character '\ua000' in position 0: ordinal not in range(128)
+ >>> u.encode('ascii', 'ignore')
+ 'abcd'
+ >>> u.encode('ascii', 'replace')
+ '?abcd?'
+ >>> u.encode('ascii', 'xmlcharrefreplace')
+ 'ꀀabcd޴'
+
+Python's 8-bit strings have a ``.decode([encoding], [errors])`` method that
+interprets the string using the given encoding::
+
+ >>> u = unichr(40960) + u'abcd' + unichr(1972) # Assemble a string
+ >>> utf8_version = u.encode('utf-8') # Encode as UTF-8
+ >>> type(utf8_version), utf8_version
+ (<type 'str'>, '\xea\x80\x80abcd\xde\xb4')
+ >>> u2 = utf8_version.decode('utf-8') # Decode using UTF-8
+ >>> u == u2 # The two strings match
+ True
+
+The low-level routines for registering and accessing the available encodings are
+found in the :mod:`codecs` module. However, the encoding and decoding functions
+returned by this module are usually more low-level than is comfortable, so I'm
+not going to describe the :mod:`codecs` module here. If you need to implement a
+completely new encoding, you'll need to learn about the :mod:`codecs` module
+interfaces, but implementing encodings is a specialized task that also won't be
+covered here. Consult the Python documentation to learn more about this module.
+
+The most commonly used part of the :mod:`codecs` module is the
+:func:`codecs.open` function which will be discussed in the section on input and
+output.
+
+
+Unicode Literals in Python Source Code
+--------------------------------------
+
+In Python source code, Unicode literals are written as strings prefixed with the
+'u' or 'U' character: ``u'abcdefghijk'``. Specific code points can be written
+using the ``\u`` escape sequence, which is followed by four hex digits giving
+the code point. The ``\U`` escape sequence is similar, but expects 8 hex
+digits, not 4.
+
+Unicode literals can also use the same escape sequences as 8-bit strings,
+including ``\x``, but ``\x`` only takes two hex digits so it can't express an
+arbitrary code point. Octal escapes can go up to U+01ff, which is octal 777.
+
+::
+
+ >>> s = u"a\xac\u1234\u20ac\U00008000"
+ ^^^^ two-digit hex escape
+ ^^^^^^ four-digit Unicode escape
+ ^^^^^^^^^^ eight-digit Unicode escape
+ >>> for c in s: print ord(c),
+ ...
+ 97 172 4660 8364 32768
+
+Using escape sequences for code points greater than 127 is fine in small doses,
+but becomes an annoyance if you're using many accented characters, as you would
+in a program with messages in French or some other accent-using language. You
+can also assemble strings using the :func:`unichr` built-in function, but this is
+even more tedious.
+
+Ideally, you'd want to be able to write literals in your language's natural
+encoding. You could then edit Python source code with your favorite editor
+which would display the accented characters naturally, and have the right
+characters used at runtime.
+
+Python supports writing Unicode literals in any encoding, but you have to
+declare the encoding being used. This is done by including a special comment as
+either the first or second line of the source file::
+
+ #!/usr/bin/env python
+ # -*- coding: latin-1 -*-
+
+ u = u'abcdé'
+ print ord(u[-1])
+
+The syntax is inspired by Emacs's notation for specifying variables local to a
+file. Emacs supports many different variables, but Python only supports
+'coding'. The ``-*-`` symbols indicate that the comment is special; within
+them, you must supply the name ``coding`` and the name of your chosen encoding,
+separated by ``':'``.
+
+If you don't include such a comment, the default encoding used will be ASCII.
+Versions of Python before 2.4 were Euro-centric and assumed Latin-1 as a default
+encoding for string literals; in Python 2.4, characters greater than 127 still
+work but result in a warning. For example, the following program has no
+encoding declaration::
+
+ #!/usr/bin/env python
+ u = u'abcdé'
+ print ord(u[-1])
+
+When you run it with Python 2.4, it will output the following warning::
+
+ amk:~$ python p263.py
+ sys:1: DeprecationWarning: Non-ASCII character '\xe9'
+ in file p263.py on line 2, but no encoding declared;
+ see http://www.python.org/peps/pep-0263.html for details
+
+
+Unicode Properties
+------------------
+
+The Unicode specification includes a database of information about code points.
+For each code point that's defined, the information includes the character's
+name, its category, the numeric value if applicable (Unicode has characters
+representing the Roman numerals and fractions such as one-third and
+four-fifths). There are also properties related to the code point's use in
+bidirectional text and other display-related properties.
+
+The following program displays some information about several characters, and
+prints the numeric value of one particular character::
+
+ import unicodedata
+
+ u = unichr(233) + unichr(0x0bf2) + unichr(3972) + unichr(6000) + unichr(13231)
+
+ for i, c in enumerate(u):
+ print i, '%04x' % ord(c), unicodedata.category(c),
+ print unicodedata.name(c)
+
+ # Get numeric value of second character
+ print unicodedata.numeric(u[1])
+
+When run, this prints::
+
+ 0 00e9 Ll LATIN SMALL LETTER E WITH ACUTE
+ 1 0bf2 No TAMIL NUMBER ONE THOUSAND
+ 2 0f84 Mn TIBETAN MARK HALANTA
+ 3 1770 Lo TAGBANWA LETTER SA
+ 4 33af So SQUARE RAD OVER S SQUARED
+ 1000.0
+
+The category codes are abbreviations describing the nature of the character.
+These are grouped into categories such as "Letter", "Number", "Punctuation", or
+"Symbol", which in turn are broken up into subcategories. To take the codes
+from the above output, ``'Ll'`` means 'Letter, lowercase', ``'No'`` means
+"Number, other", ``'Mn'`` is "Mark, nonspacing", and ``'So'`` is "Symbol,
+other". See
+<http://www.unicode.org/Public/UNIDATA/UCD.html#General_Category_Values> for a
+list of category codes.
+
+References
+----------
+
+The Unicode and 8-bit string types are described in the Python library reference
+at :ref:`typesseq`.
+
+The documentation for the :mod:`unicodedata` module.
+
+The documentation for the :mod:`codecs` module.
+
+Marc-André Lemburg gave a presentation at EuroPython 2002 titled "Python and
+Unicode". A PDF version of his slides is available at
+<http://www.egenix.com/files/python/Unicode-EPC2002-Talk.pdf>, and is an
+excellent overview of the design of Python's Unicode features.
+
+
+Reading and Writing Unicode Data
+================================
+
+Once you've written some code that works with Unicode data, the next problem is
+input/output. How do you get Unicode strings into your program, and how do you
+convert Unicode into a form suitable for storage or transmission?
+
+It's possible that you may not need to do anything depending on your input
+sources and output destinations; you should check whether the libraries used in
+your application support Unicode natively. XML parsers often return Unicode
+data, for example. Many relational databases also support Unicode-valued
+columns and can return Unicode values from an SQL query.
+
+Unicode data is usually converted to a particular encoding before it gets
+written to disk or sent over a socket. It's possible to do all the work
+yourself: open a file, read an 8-bit string from it, and convert the string with
+``unicode(str, encoding)``. However, the manual approach is not recommended.
+
+One problem is the multi-byte nature of encodings; one Unicode character can be
+represented by several bytes. If you want to read the file in arbitrary-sized
+chunks (say, 1K or 4K), you need to write error-handling code to catch the case
+where only part of the bytes encoding a single Unicode character are read at the
+end of a chunk. One solution would be to read the entire file into memory and
+then perform the decoding, but that prevents you from working with files that
+are extremely large; if you need to read a 2Gb file, you need 2Gb of RAM.
+(More, really, since for at least a moment you'd need to have both the encoded
+string and its Unicode version in memory.)
+
+The solution would be to use the low-level decoding interface to catch the case
+of partial coding sequences. The work of implementing this has already been
+done for you: the :mod:`codecs` module includes a version of the :func:`open`
+function that returns a file-like object that assumes the file's contents are in
+a specified encoding and accepts Unicode parameters for methods such as
+``.read()`` and ``.write()``.
+
+The function's parameters are ``open(filename, mode='rb', encoding=None,
+errors='strict', buffering=1)``. ``mode`` can be ``'r'``, ``'w'``, or ``'a'``,
+just like the corresponding parameter to the regular built-in ``open()``
+function; add a ``'+'`` to update the file. ``buffering`` is similarly parallel
+to the standard function's parameter. ``encoding`` is a string giving the
+encoding to use; if it's left as ``None``, a regular Python file object that
+accepts 8-bit strings is returned. Otherwise, a wrapper object is returned, and
+data written to or read from the wrapper object will be converted as needed.
+``errors`` specifies the action for encoding errors and can be one of the usual
+values of 'strict', 'ignore', and 'replace'.
+
+Reading Unicode from a file is therefore simple::
+
+ import codecs
+ f = codecs.open('unicode.rst', encoding='utf-8')
+ for line in f:
+ print repr(line)
+
+It's also possible to open files in update mode, allowing both reading and
+writing::
+
+ f = codecs.open('test', encoding='utf-8', mode='w+')
+ f.write(u'\u4500 blah blah blah\n')
+ f.seek(0)
+ print repr(f.readline()[:1])
+ f.close()
+
+Unicode character U+FEFF is used as a byte-order mark (BOM), and is often
+written as the first character of a file in order to assist with autodetection
+of the file's byte ordering. Some encodings, such as UTF-16, expect a BOM to be
+present at the start of a file; when such an encoding is used, the BOM will be
+automatically written as the first character and will be silently dropped when
+the file is read. There are variants of these encodings, such as 'utf-16-le'
+and 'utf-16-be' for little-endian and big-endian encodings, that specify one
+particular byte ordering and don't skip the BOM.
+
+
+Unicode filenames
+-----------------
+
+Most of the operating systems in common use today support filenames that contain
+arbitrary Unicode characters. Usually this is implemented by converting the
+Unicode string into some encoding that varies depending on the system. For
+example, MacOS X uses UTF-8 while Windows uses a configurable encoding; on
+Windows, Python uses the name "mbcs" to refer to whatever the currently
+configured encoding is. On Unix systems, there will only be a filesystem
+encoding if you've set the ``LANG`` or ``LC_CTYPE`` environment variables; if
+you haven't, the default encoding is ASCII.
+
+The :func:`sys.getfilesystemencoding` function returns the encoding to use on
+your current system, in case you want to do the encoding manually, but there's
+not much reason to bother. When opening a file for reading or writing, you can
+usually just provide the Unicode string as the filename, and it will be
+automatically converted to the right encoding for you::
+
+ filename = u'filename\u4500abc'
+ f = open(filename, 'w')
+ f.write('blah\n')
+ f.close()
+
+Functions in the :mod:`os` module such as :func:`os.stat` will also accept Unicode
+filenames.
+
+:func:`os.listdir`, which returns filenames, raises an issue: should it return
+the Unicode version of filenames, or should it return 8-bit strings containing
+the encoded versions? :func:`os.listdir` will do both, depending on whether you
+provided the directory path as an 8-bit string or a Unicode string. If you pass
+a Unicode string as the path, filenames will be decoded using the filesystem's
+encoding and a list of Unicode strings will be returned, while passing an 8-bit
+path will return the 8-bit versions of the filenames. For example, assuming the
+default filesystem encoding is UTF-8, running the following program::
+
+ fn = u'filename\u4500abc'
+ f = open(fn, 'w')
+ f.close()
+
+ import os
+ print os.listdir('.')
+ print os.listdir(u'.')
+
+will produce the following output::
+
+ amk:~$ python t.py
+ ['.svn', 'filename\xe4\x94\x80abc', ...]
+ [u'.svn', u'filename\u4500abc', ...]
+
+The first list contains UTF-8-encoded filenames, and the second list contains
+the Unicode versions.
+
+
+
+Tips for Writing Unicode-aware Programs
+---------------------------------------
+
+This section provides some suggestions on writing software that deals with
+Unicode.
+
+The most important tip is:
+
+ Software should only work with Unicode strings internally, converting to a
+ particular encoding on output.
+
+If you attempt to write processing functions that accept both Unicode and 8-bit
+strings, you will find your program vulnerable to bugs wherever you combine the
+two different kinds of strings. Python's default encoding is ASCII, so whenever
+a character with an ASCII value > 127 is in the input data, you'll get a
+:exc:`UnicodeDecodeError` because that character can't be handled by the ASCII
+encoding.
+
+It's easy to miss such problems if you only test your software with data that
+doesn't contain any accents; everything will seem to work, but there's actually
+a bug in your program waiting for the first user who attempts to use characters
+> 127. A second tip, therefore, is:
+
+ Include characters > 127 and, even better, characters > 255 in your test
+ data.
+
+When using data coming from a web browser or some other untrusted source, a
+common technique is to check for illegal characters in a string before using the
+string in a generated command line or storing it in a database. If you're doing
+this, be careful to check the string once it's in the form that will be used or
+stored; it's possible for encodings to be used to disguise characters. This is
+especially true if the input data also specifies the encoding; many encodings
+leave the commonly checked-for characters alone, but Python includes some
+encodings such as ``'base64'`` that modify every single character.
+
+For example, let's say you have a content management system that takes a Unicode
+filename, and you want to disallow paths with a '/' character. You might write
+this code::
+
+ def read_file (filename, encoding):
+ if '/' in filename:
+ raise ValueError("'/' not allowed in filenames")
+ unicode_name = filename.decode(encoding)
+ f = open(unicode_name, 'r')
+ # ... return contents of file ...
+
+However, if an attacker could specify the ``'base64'`` encoding, they could pass
+``'L2V0Yy9wYXNzd2Q='``, which is the base-64 encoded form of the string
+``'/etc/passwd'``, to read a system file. The above code looks for ``'/'``
+characters in the encoded form and misses the dangerous character in the
+resulting decoded form.
+
+References
+----------
+
+The PDF slides for Marc-André Lemburg's presentation "Writing Unicode-aware
+Applications in Python" are available at
+<http://www.egenix.com/files/python/LSM2005-Developing-Unicode-aware-applications-in-Python.pdf>
+and discuss questions of character encodings as well as how to internationalize
+and localize an application.
+
+
+Revision History and Acknowledgements
+=====================================
+
+Thanks to the following people who have noted errors or offered suggestions on
+this article: Nicholas Bastin, Marius Gedminas, Kent Johnson, Ken Krugler,
+Marc-André Lemburg, Martin von Löwis, Chad Whitacre.
+
+Version 1.0: posted August 5 2005.
+
+Version 1.01: posted August 7 2005. Corrects factual and markup errors; adds
+several links.
+
+Version 1.02: posted August 16 2005. Corrects factual errors.
+
+
+.. comment Additional topic: building Python w/ UCS2 or UCS4 support
+.. comment Describe obscure -U switch somewhere?
+.. comment Describe use of codecs.StreamRecoder and StreamReaderWriter
+
+.. comment
+ Original outline:
+
+ - [ ] Unicode introduction
+ - [ ] ASCII
+ - [ ] Terms
+ - [ ] Character
+ - [ ] Code point
+ - [ ] Encodings
+ - [ ] Common encodings: ASCII, Latin-1, UTF-8
+ - [ ] Unicode Python type
+ - [ ] Writing unicode literals
+ - [ ] Obscurity: -U switch
+ - [ ] Built-ins
+ - [ ] unichr()
+ - [ ] ord()
+ - [ ] unicode() constructor
+ - [ ] Unicode type
+ - [ ] encode(), decode() methods
+ - [ ] Unicodedata module for character properties
+ - [ ] I/O
+ - [ ] Reading/writing Unicode data into files
+ - [ ] Byte-order marks
+ - [ ] Unicode filenames
+ - [ ] Writing Unicode programs
+ - [ ] Do everything in Unicode
+ - [ ] Declaring source code encodings (PEP 263)
+ - [ ] Other issues
+ - [ ] Building Python (UCS2, UCS4)
--- /dev/null
+************************************************
+ HOWTO Fetch Internet Resources Using urllib2
+************************************************
+
+:Author: `Michael Foord <http://www.voidspace.org.uk/python/index.shtml>`_
+
+.. note::
+
+ There is an French translation of an earlier revision of this
+ HOWTO, available at `urllib2 - Le Manuel manquant
+ <http://www.voidspace/python/articles/urllib2_francais.shtml>`_.
+
+
+
+Introduction
+============
+
+.. sidebar:: Related Articles
+
+ You may also find useful the following article on fetching web resources
+ with Python :
+
+ * `Basic Authentication <http://www.voidspace.org.uk/python/articles/authentication.shtml>`_
+
+ A tutorial on *Basic Authentication*, with examples in Python.
+
+**urllib2** is a `Python <http://www.python.org>`_ module for fetching URLs
+(Uniform Resource Locators). It offers a very simple interface, in the form of
+the *urlopen* function. This is capable of fetching URLs using a variety of
+different protocols. It also offers a slightly more complex interface for
+handling common situations - like basic authentication, cookies, proxies and so
+on. These are provided by objects called handlers and openers.
+
+urllib2 supports fetching URLs for many "URL schemes" (identified by the string
+before the ":" in URL - for example "ftp" is the URL scheme of
+"ftp://python.org/") using their associated network protocols (e.g. FTP, HTTP).
+This tutorial focuses on the most common case, HTTP.
+
+For straightforward situations *urlopen* is very easy to use. But as soon as you
+encounter errors or non-trivial cases when opening HTTP URLs, you will need some
+understanding of the HyperText Transfer Protocol. The most comprehensive and
+authoritative reference to HTTP is :rfc:`2616`. This is a technical document and
+not intended to be easy to read. This HOWTO aims to illustrate using *urllib2*,
+with enough detail about HTTP to help you through. It is not intended to replace
+the :mod:`urllib2` docs, but is supplementary to them.
+
+
+Fetching URLs
+=============
+
+The simplest way to use urllib2 is as follows::
+
+ import urllib2
+ response = urllib2.urlopen('http://python.org/')
+ html = response.read()
+
+Many uses of urllib2 will be that simple (note that instead of an 'http:' URL we
+could have used an URL starting with 'ftp:', 'file:', etc.). However, it's the
+purpose of this tutorial to explain the more complicated cases, concentrating on
+HTTP.
+
+HTTP is based on requests and responses - the client makes requests and servers
+send responses. urllib2 mirrors this with a ``Request`` object which represents
+the HTTP request you are making. In its simplest form you create a Request
+object that specifies the URL you want to fetch. Calling ``urlopen`` with this
+Request object returns a response object for the URL requested. This response is
+a file-like object, which means you can for example call ``.read()`` on the
+response::
+
+ import urllib2
+
+ req = urllib2.Request('http://www.voidspace.org.uk')
+ response = urllib2.urlopen(req)
+ the_page = response.read()
+
+Note that urllib2 makes use of the same Request interface to handle all URL
+schemes. For example, you can make an FTP request like so::
+
+ req = urllib2.Request('ftp://example.com/')
+
+In the case of HTTP, there are two extra things that Request objects allow you
+to do: First, you can pass data to be sent to the server. Second, you can pass
+extra information ("metadata") *about* the data or the about request itself, to
+the server - this information is sent as HTTP "headers". Let's look at each of
+these in turn.
+
+Data
+----
+
+Sometimes you want to send data to a URL (often the URL will refer to a CGI
+(Common Gateway Interface) script [#]_ or other web application). With HTTP,
+this is often done using what's known as a **POST** request. This is often what
+your browser does when you submit a HTML form that you filled in on the web. Not
+all POSTs have to come from forms: you can use a POST to transmit arbitrary data
+to your own application. In the common case of HTML forms, the data needs to be
+encoded in a standard way, and then passed to the Request object as the ``data``
+argument. The encoding is done using a function from the ``urllib`` library
+*not* from ``urllib2``. ::
+
+ import urllib
+ import urllib2
+
+ url = 'http://www.someserver.com/cgi-bin/register.cgi'
+ values = {'name' : 'Michael Foord',
+ 'location' : 'Northampton',
+ 'language' : 'Python' }
+
+ data = urllib.urlencode(values)
+ req = urllib2.Request(url, data)
+ response = urllib2.urlopen(req)
+ the_page = response.read()
+
+Note that other encodings are sometimes required (e.g. for file upload from HTML
+forms - see `HTML Specification, Form Submission
+<http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13>`_ for more
+details).
+
+If you do not pass the ``data`` argument, urllib2 uses a **GET** request. One
+way in which GET and POST requests differ is that POST requests often have
+"side-effects": they change the state of the system in some way (for example by
+placing an order with the website for a hundredweight of tinned spam to be
+delivered to your door). Though the HTTP standard makes it clear that POSTs are
+intended to *always* cause side-effects, and GET requests *never* to cause
+side-effects, nothing prevents a GET request from having side-effects, nor a
+POST requests from having no side-effects. Data can also be passed in an HTTP
+GET request by encoding it in the URL itself.
+
+This is done as follows::
+
+ >>> import urllib2
+ >>> import urllib
+ >>> data = {}
+ >>> data['name'] = 'Somebody Here'
+ >>> data['location'] = 'Northampton'
+ >>> data['language'] = 'Python'
+ >>> url_values = urllib.urlencode(data)
+ >>> print url_values
+ name=Somebody+Here&language=Python&location=Northampton
+ >>> url = 'http://www.example.com/example.cgi'
+ >>> full_url = url + '?' + url_values
+ >>> data = urllib2.open(full_url)
+
+Notice that the full URL is created by adding a ``?`` to the URL, followed by
+the encoded values.
+
+Headers
+-------
+
+We'll discuss here one particular HTTP header, to illustrate how to add headers
+to your HTTP request.
+
+Some websites [#]_ dislike being browsed by programs, or send different versions
+to different browsers [#]_ . By default urllib2 identifies itself as
+``Python-urllib/x.y`` (where ``x`` and ``y`` are the major and minor version
+numbers of the Python release,
+e.g. ``Python-urllib/2.5``), which may confuse the site, or just plain
+not work. The way a browser identifies itself is through the
+``User-Agent`` header [#]_. When you create a Request object you can
+pass a dictionary of headers in. The following example makes the same
+request as above, but identifies itself as a version of Internet
+Explorer [#]_. ::
+
+ import urllib
+ import urllib2
+
+ url = 'http://www.someserver.com/cgi-bin/register.cgi'
+ user_agent = 'Mozilla/4.0 (compatible; MSIE 5.5; Windows NT)'
+ values = {'name' : 'Michael Foord',
+ 'location' : 'Northampton',
+ 'language' : 'Python' }
+ headers = { 'User-Agent' : user_agent }
+
+ data = urllib.urlencode(values)
+ req = urllib2.Request(url, data, headers)
+ response = urllib2.urlopen(req)
+ the_page = response.read()
+
+The response also has two useful methods. See the section on `info and geturl`_
+which comes after we have a look at what happens when things go wrong.
+
+
+Handling Exceptions
+===================
+
+*urlopen* raises ``URLError`` when it cannot handle a response (though as usual
+with Python APIs, builtin exceptions such as ValueError, TypeError etc. may also
+be raised).
+
+``HTTPError`` is the subclass of ``URLError`` raised in the specific case of
+HTTP URLs.
+
+URLError
+--------
+
+Often, URLError is raised because there is no network connection (no route to
+the specified server), or the specified server doesn't exist. In this case, the
+exception raised will have a 'reason' attribute, which is a tuple containing an
+error code and a text error message.
+
+e.g. ::
+
+ >>> req = urllib2.Request('http://www.pretend_server.org')
+ >>> try: urllib2.urlopen(req)
+ >>> except URLError, e:
+ >>> print e.reason
+ >>>
+ (4, 'getaddrinfo failed')
+
+
+HTTPError
+---------
+
+Every HTTP response from the server contains a numeric "status code". Sometimes
+the status code indicates that the server is unable to fulfil the request. The
+default handlers will handle some of these responses for you (for example, if
+the response is a "redirection" that requests the client fetch the document from
+a different URL, urllib2 will handle that for you). For those it can't handle,
+urlopen will raise an ``HTTPError``. Typical errors include '404' (page not
+found), '403' (request forbidden), and '401' (authentication required).
+
+See section 10 of RFC 2616 for a reference on all the HTTP error codes.
+
+The ``HTTPError`` instance raised will have an integer 'code' attribute, which
+corresponds to the error sent by the server.
+
+Error Codes
+~~~~~~~~~~~
+
+Because the default handlers handle redirects (codes in the 300 range), and
+codes in the 100-299 range indicate success, you will usually only see error
+codes in the 400-599 range.
+
+``BaseHTTPServer.BaseHTTPRequestHandler.responses`` is a useful dictionary of
+response codes in that shows all the response codes used by RFC 2616. The
+dictionary is reproduced here for convenience ::
+
+ # Table mapping response codes to messages; entries have the
+ # form {code: (shortmessage, longmessage)}.
+ responses = {
+ 100: ('Continue', 'Request received, please continue'),
+ 101: ('Switching Protocols',
+ 'Switching to new protocol; obey Upgrade header'),
+
+ 200: ('OK', 'Request fulfilled, document follows'),
+ 201: ('Created', 'Document created, URL follows'),
+ 202: ('Accepted',
+ 'Request accepted, processing continues off-line'),
+ 203: ('Non-Authoritative Information', 'Request fulfilled from cache'),
+ 204: ('No Content', 'Request fulfilled, nothing follows'),
+ 205: ('Reset Content', 'Clear input form for further input.'),
+ 206: ('Partial Content', 'Partial content follows.'),
+
+ 300: ('Multiple Choices',
+ 'Object has several resources -- see URI list'),
+ 301: ('Moved Permanently', 'Object moved permanently -- see URI list'),
+ 302: ('Found', 'Object moved temporarily -- see URI list'),
+ 303: ('See Other', 'Object moved -- see Method and URL list'),
+ 304: ('Not Modified',
+ 'Document has not changed since given time'),
+ 305: ('Use Proxy',
+ 'You must use proxy specified in Location to access this '
+ 'resource.'),
+ 307: ('Temporary Redirect',
+ 'Object moved temporarily -- see URI list'),
+
+ 400: ('Bad Request',
+ 'Bad request syntax or unsupported method'),
+ 401: ('Unauthorized',
+ 'No permission -- see authorization schemes'),
+ 402: ('Payment Required',
+ 'No payment -- see charging schemes'),
+ 403: ('Forbidden',
+ 'Request forbidden -- authorization will not help'),
+ 404: ('Not Found', 'Nothing matches the given URI'),
+ 405: ('Method Not Allowed',
+ 'Specified method is invalid for this server.'),
+ 406: ('Not Acceptable', 'URI not available in preferred format.'),
+ 407: ('Proxy Authentication Required', 'You must authenticate with '
+ 'this proxy before proceeding.'),
+ 408: ('Request Timeout', 'Request timed out; try again later.'),
+ 409: ('Conflict', 'Request conflict.'),
+ 410: ('Gone',
+ 'URI no longer exists and has been permanently removed.'),
+ 411: ('Length Required', 'Client must specify Content-Length.'),
+ 412: ('Precondition Failed', 'Precondition in headers is false.'),
+ 413: ('Request Entity Too Large', 'Entity is too large.'),
+ 414: ('Request-URI Too Long', 'URI is too long.'),
+ 415: ('Unsupported Media Type', 'Entity body in unsupported format.'),
+ 416: ('Requested Range Not Satisfiable',
+ 'Cannot satisfy request range.'),
+ 417: ('Expectation Failed',
+ 'Expect condition could not be satisfied.'),
+
+ 500: ('Internal Server Error', 'Server got itself in trouble'),
+ 501: ('Not Implemented',
+ 'Server does not support this operation'),
+ 502: ('Bad Gateway', 'Invalid responses from another server/proxy.'),
+ 503: ('Service Unavailable',
+ 'The server cannot process the request due to a high load'),
+ 504: ('Gateway Timeout',
+ 'The gateway server did not receive a timely response'),
+ 505: ('HTTP Version Not Supported', 'Cannot fulfill request.'),
+ }
+
+When an error is raised the server responds by returning an HTTP error code
+*and* an error page. You can use the ``HTTPError`` instance as a response on the
+page returned. This means that as well as the code attribute, it also has read,
+geturl, and info, methods. ::
+
+ >>> req = urllib2.Request('http://www.python.org/fish.html')
+ >>> try:
+ >>> urllib2.urlopen(req)
+ >>> except URLError, e:
+ >>> print e.code
+ >>> print e.read()
+ >>>
+ 404
+ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+ <?xml-stylesheet href="./css/ht2html.css"
+ type="text/css"?>
+ <html><head><title>Error 404: File Not Found</title>
+ ...... etc...
+
+Wrapping it Up
+--------------
+
+So if you want to be prepared for ``HTTPError`` *or* ``URLError`` there are two
+basic approaches. I prefer the second approach.
+
+Number 1
+~~~~~~~~
+
+::
+
+
+ from urllib2 import Request, urlopen, URLError, HTTPError
+ req = Request(someurl)
+ try:
+ response = urlopen(req)
+ except HTTPError, e:
+ print 'The server couldn\'t fulfill the request.'
+ print 'Error code: ', e.code
+ except URLError, e:
+ print 'We failed to reach a server.'
+ print 'Reason: ', e.reason
+ else:
+ # everything is fine
+
+
+.. note::
+
+ The ``except HTTPError`` *must* come first, otherwise ``except URLError``
+ will *also* catch an ``HTTPError``.
+
+Number 2
+~~~~~~~~
+
+::
+
+ from urllib2 import Request, urlopen, URLError
+ req = Request(someurl)
+ try:
+ response = urlopen(req)
+ except URLError, e:
+ if hasattr(e, 'reason'):
+ print 'We failed to reach a server.'
+ print 'Reason: ', e.reason
+ elif hasattr(e, 'code'):
+ print 'The server couldn\'t fulfill the request.'
+ print 'Error code: ', e.code
+ else:
+ # everything is fine
+
+
+info and geturl
+===============
+
+The response returned by urlopen (or the ``HTTPError`` instance) has two useful
+methods ``info`` and ``geturl``.
+
+**geturl** - this returns the real URL of the page fetched. This is useful
+because ``urlopen`` (or the opener object used) may have followed a
+redirect. The URL of the page fetched may not be the same as the URL requested.
+
+**info** - this returns a dictionary-like object that describes the page
+fetched, particularly the headers sent by the server. It is currently an
+``httplib.HTTPMessage`` instance.
+
+Typical headers include 'Content-length', 'Content-type', and so on. See the
+`Quick Reference to HTTP Headers <http://www.cs.tut.fi/~jkorpela/http.html>`_
+for a useful listing of HTTP headers with brief explanations of their meaning
+and use.
+
+
+Openers and Handlers
+====================
+
+When you fetch a URL you use an opener (an instance of the perhaps
+confusingly-named :class:`urllib2.OpenerDirector`). Normally we have been using
+the default opener - via ``urlopen`` - but you can create custom
+openers. Openers use handlers. All the "heavy lifting" is done by the
+handlers. Each handler knows how to open URLs for a particular URL scheme (http,
+ftp, etc.), or how to handle an aspect of URL opening, for example HTTP
+redirections or HTTP cookies.
+
+You will want to create openers if you want to fetch URLs with specific handlers
+installed, for example to get an opener that handles cookies, or to get an
+opener that does not handle redirections.
+
+To create an opener, instantiate an ``OpenerDirector``, and then call
+``.add_handler(some_handler_instance)`` repeatedly.
+
+Alternatively, you can use ``build_opener``, which is a convenience function for
+creating opener objects with a single function call. ``build_opener`` adds
+several handlers by default, but provides a quick way to add more and/or
+override the default handlers.
+
+Other sorts of handlers you might want to can handle proxies, authentication,
+and other common but slightly specialised situations.
+
+``install_opener`` can be used to make an ``opener`` object the (global) default
+opener. This means that calls to ``urlopen`` will use the opener you have
+installed.
+
+Opener objects have an ``open`` method, which can be called directly to fetch
+urls in the same way as the ``urlopen`` function: there's no need to call
+``install_opener``, except as a convenience.
+
+
+Basic Authentication
+====================
+
+To illustrate creating and installing a handler we will use the
+``HTTPBasicAuthHandler``. For a more detailed discussion of this subject --
+including an explanation of how Basic Authentication works - see the `Basic
+Authentication Tutorial
+<http://www.voidspace.org.uk/python/articles/authentication.shtml>`_.
+
+When authentication is required, the server sends a header (as well as the 401
+error code) requesting authentication. This specifies the authentication scheme
+and a 'realm'. The header looks like : ``Www-authenticate: SCHEME
+realm="REALM"``.
+
+e.g. ::
+
+ Www-authenticate: Basic realm="cPanel Users"
+
+
+The client should then retry the request with the appropriate name and password
+for the realm included as a header in the request. This is 'basic
+authentication'. In order to simplify this process we can create an instance of
+``HTTPBasicAuthHandler`` and an opener to use this handler.
+
+The ``HTTPBasicAuthHandler`` uses an object called a password manager to handle
+the mapping of URLs and realms to passwords and usernames. If you know what the
+realm is (from the authentication header sent by the server), then you can use a
+``HTTPPasswordMgr``. Frequently one doesn't care what the realm is. In that
+case, it is convenient to use ``HTTPPasswordMgrWithDefaultRealm``. This allows
+you to specify a default username and password for a URL. This will be supplied
+in the absence of you providing an alternative combination for a specific
+realm. We indicate this by providing ``None`` as the realm argument to the
+``add_password`` method.
+
+The top-level URL is the first URL that requires authentication. URLs "deeper"
+than the URL you pass to .add_password() will also match. ::
+
+ # create a password manager
+ password_mgr = urllib2.HTTPPasswordMgrWithDefaultRealm()
+
+ # Add the username and password.
+ # If we knew the realm, we could use it instead of ``None``.
+ top_level_url = "http://example.com/foo/"
+ password_mgr.add_password(None, top_level_url, username, password)
+
+ handler = urllib2.HTTPBasicAuthHandler(password_mgr)
+
+ # create "opener" (OpenerDirector instance)
+ opener = urllib2.build_opener(handler)
+
+ # use the opener to fetch a URL
+ opener.open(a_url)
+
+ # Install the opener.
+ # Now all calls to urllib2.urlopen use our opener.
+ urllib2.install_opener(opener)
+
+.. note::
+
+ In the above example we only supplied our ``HHTPBasicAuthHandler`` to
+ ``build_opener``. By default openers have the handlers for normal situations
+ -- ``ProxyHandler``, ``UnknownHandler``, ``HTTPHandler``,
+ ``HTTPDefaultErrorHandler``, ``HTTPRedirectHandler``, ``FTPHandler``,
+ ``FileHandler``, ``HTTPErrorProcessor``.
+
+``top_level_url`` is in fact *either* a full URL (including the 'http:' scheme
+component and the hostname and optionally the port number)
+e.g. "http://example.com/" *or* an "authority" (i.e. the hostname,
+optionally including the port number) e.g. "example.com" or "example.com:8080"
+(the latter example includes a port number). The authority, if present, must
+NOT contain the "userinfo" component - for example "joe@password:example.com" is
+not correct.
+
+
+Proxies
+=======
+
+**urllib2** will auto-detect your proxy settings and use those. This is through
+the ``ProxyHandler`` which is part of the normal handler chain. Normally that's
+a good thing, but there are occasions when it may not be helpful [#]_. One way
+to do this is to setup our own ``ProxyHandler``, with no proxies defined. This
+is done using similar steps to setting up a `Basic Authentication`_ handler : ::
+
+ >>> proxy_support = urllib2.ProxyHandler({})
+ >>> opener = urllib2.build_opener(proxy_support)
+ >>> urllib2.install_opener(opener)
+
+.. note::
+
+ Currently ``urllib2`` *does not* support fetching of ``https`` locations
+ through a proxy. However, this can be enabled by extending urllib2 as
+ shown in the recipe [#]_.
+
+
+Sockets and Layers
+==================
+
+The Python support for fetching resources from the web is layered. urllib2 uses
+the httplib library, which in turn uses the socket library.
+
+As of Python 2.3 you can specify how long a socket should wait for a response
+before timing out. This can be useful in applications which have to fetch web
+pages. By default the socket module has *no timeout* and can hang. Currently,
+the socket timeout is not exposed at the httplib or urllib2 levels. However,
+you can set the default timeout globally for all sockets using ::
+
+ import socket
+ import urllib2
+
+ # timeout in seconds
+ timeout = 10
+ socket.setdefaulttimeout(timeout)
+
+ # this call to urllib2.urlopen now uses the default timeout
+ # we have set in the socket module
+ req = urllib2.Request('http://www.voidspace.org.uk')
+ response = urllib2.urlopen(req)
+
+
+-------
+
+
+Footnotes
+=========
+
+This document was reviewed and revised by John Lee.
+
+.. [#] For an introduction to the CGI protocol see
+ `Writing Web Applications in Python <http://www.pyzine.com/Issue008/Section_Articles/article_CGIOne.html>`_.
+.. [#] Like Google for example. The *proper* way to use google from a program
+ is to use `PyGoogle <http://pygoogle.sourceforge.net>`_ of course. See
+ `Voidspace Google <http://www.voidspace.org.uk/python/recipebook.shtml#google>`_
+ for some examples of using the Google API.
+.. [#] Browser sniffing is a very bad practise for website design - building
+ sites using web standards is much more sensible. Unfortunately a lot of
+ sites still send different versions to different browsers.
+.. [#] The user agent for MSIE 6 is
+ *'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)'*
+.. [#] For details of more HTTP request headers, see
+ `Quick Reference to HTTP Headers`_.
+.. [#] In my case I have to use a proxy to access the internet at work. If you
+ attempt to fetch *localhost* URLs through this proxy it blocks them. IE
+ is set to use the proxy, which urllib2 picks up on. In order to test
+ scripts with a localhost server, I have to prevent urllib2 from using
+ the proxy.
+.. [#] urllib2 opener for SSL proxy (CONNECT method): `ASPN Cookbook Recipe
+ <http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/456195>`_.
+
--- /dev/null
+#!/usr/bin/env python
+
+"""Send the contents of a directory as a MIME message."""
+
+import os
+import sys
+import smtplib
+# For guessing MIME type based on file name extension
+import mimetypes
+
+from optparse import OptionParser
+
+from email import encoders
+from email.message import Message
+from email.mime.audio import MIMEAudio
+from email.mime.base import MIMEBase
+from email.mime.image import MIMEImage
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+
+COMMASPACE = ', '
+
+
+def main():
+ parser = OptionParser(usage="""\
+Send the contents of a directory as a MIME message.
+
+Usage: %prog [options]
+
+Unless the -o option is given, the email is sent by forwarding to your local
+SMTP server, which then does the normal delivery process. Your local machine
+must be running an SMTP server.
+""")
+ parser.add_option('-d', '--directory',
+ type='string', action='store',
+ help="""Mail the contents of the specified directory,
+ otherwise use the current directory. Only the regular
+ files in the directory are sent, and we don't recurse to
+ subdirectories.""")
+ parser.add_option('-o', '--output',
+ type='string', action='store', metavar='FILE',
+ help="""Print the composed message to FILE instead of
+ sending the message to the SMTP server.""")
+ parser.add_option('-s', '--sender',
+ type='string', action='store', metavar='SENDER',
+ help='The value of the From: header (required)')
+ parser.add_option('-r', '--recipient',
+ type='string', action='append', metavar='RECIPIENT',
+ default=[], dest='recipients',
+ help='A To: header value (at least one required)')
+ opts, args = parser.parse_args()
+ if not opts.sender or not opts.recipients:
+ parser.print_help()
+ sys.exit(1)
+ directory = opts.directory
+ if not directory:
+ directory = '.'
+ # Create the enclosing (outer) message
+ outer = MIMEMultipart()
+ outer['Subject'] = 'Contents of directory %s' % os.path.abspath(directory)
+ outer['To'] = COMMASPACE.join(opts.recipients)
+ outer['From'] = opts.sender
+ outer.preamble = 'You will not see this in a MIME-aware mail reader.\n'
+
+ for filename in os.listdir(directory):
+ path = os.path.join(directory, filename)
+ if not os.path.isfile(path):
+ continue
+ # Guess the content type based on the file's extension. Encoding
+ # will be ignored, although we should check for simple things like
+ # gzip'd or compressed files.
+ ctype, encoding = mimetypes.guess_type(path)
+ if ctype is None or encoding is not None:
+ # No guess could be made, or the file is encoded (compressed), so
+ # use a generic bag-of-bits type.
+ ctype = 'application/octet-stream'
+ maintype, subtype = ctype.split('/', 1)
+ if maintype == 'text':
+ fp = open(path)
+ # Note: we should handle calculating the charset
+ msg = MIMEText(fp.read(), _subtype=subtype)
+ fp.close()
+ elif maintype == 'image':
+ fp = open(path, 'rb')
+ msg = MIMEImage(fp.read(), _subtype=subtype)
+ fp.close()
+ elif maintype == 'audio':
+ fp = open(path, 'rb')
+ msg = MIMEAudio(fp.read(), _subtype=subtype)
+ fp.close()
+ else:
+ fp = open(path, 'rb')
+ msg = MIMEBase(maintype, subtype)
+ msg.set_payload(fp.read())
+ fp.close()
+ # Encode the payload using Base64
+ encoders.encode_base64(msg)
+ # Set the filename parameter
+ msg.add_header('Content-Disposition', 'attachment', filename=filename)
+ outer.attach(msg)
+ # Now send or store the message
+ composed = outer.as_string()
+ if opts.output:
+ fp = open(opts.output, 'w')
+ fp.write(composed)
+ fp.close()
+ else:
+ s = smtplib.SMTP()
+ s.connect()
+ s.sendmail(opts.sender, opts.recipients, composed)
+ s.close()
+
+
+if __name__ == '__main__':
+ main()
--- /dev/null
+# Import smtplib for the actual sending function
+import smtplib
+
+# Here are the email package modules we'll need
+from email.mime.image import MIMEImage
+from email.mime.multipart import MIMEMultipart
+
+COMMASPACE = ', '
+
+# Create the container (outer) email message.
+msg = MIMEMultipart()
+msg['Subject'] = 'Our family reunion'
+# me == the sender's email address
+# family = the list of all recipients' email addresses
+msg['From'] = me
+msg['To'] = COMMASPACE.join(family)
+msg.preamble = 'Our family reunion'
+
+# Assume we know that the image files are all in PNG format
+for file in pngfiles:
+ # Open the files in binary mode. Let the MIMEImage class automatically
+ # guess the specific image type.
+ fp = open(file, 'rb')
+ img = MIMEImage(fp.read())
+ fp.close()
+ msg.attach(img)
+
+# Send the email via our own SMTP server.
+s = smtplib.SMTP()
+s.connect()
+s.sendmail(me, family, msg.as_string())
+s.close()
--- /dev/null
+# Import smtplib for the actual sending function
+import smtplib
+
+# Import the email modules we'll need
+from email.mime.text import MIMEText
+
+# Open a plain text file for reading. For this example, assume that
+# the text file contains only ASCII characters.
+fp = open(textfile, 'rb')
+# Create a text/plain message
+msg = MIMEText(fp.read())
+fp.close()
+
+# me == the sender's email address
+# you == the recipient's email address
+msg['Subject'] = 'The contents of %s' % textfile
+msg['From'] = me
+msg['To'] = you
+
+# Send the message via our own SMTP server, but don't include the
+# envelope header.
+s = smtplib.SMTP()
+s.connect()
+s.sendmail(me, [you], msg.as_string())
+s.close()
--- /dev/null
+#!/usr/bin/env python
+
+"""Unpack a MIME message into a directory of files."""
+
+import os
+import sys
+import email
+import errno
+import mimetypes
+
+from optparse import OptionParser
+
+
+def main():
+ parser = OptionParser(usage="""\
+Unpack a MIME message into a directory of files.
+
+Usage: %prog [options] msgfile
+""")
+ parser.add_option('-d', '--directory',
+ type='string', action='store',
+ help="""Unpack the MIME message into the named
+ directory, which will be created if it doesn't already
+ exist.""")
+ opts, args = parser.parse_args()
+ if not opts.directory:
+ parser.print_help()
+ sys.exit(1)
+
+ try:
+ msgfile = args[0]
+ except IndexError:
+ parser.print_help()
+ sys.exit(1)
+
+ try:
+ os.mkdir(opts.directory)
+ except OSError, e:
+ # Ignore directory exists error
+ if e.errno <> errno.EEXIST:
+ raise
+
+ fp = open(msgfile)
+ msg = email.message_from_file(fp)
+ fp.close()
+
+ counter = 1
+ for part in msg.walk():
+ # multipart/* are just containers
+ if part.get_content_maintype() == 'multipart':
+ continue
+ # Applications should really sanitize the given filename so that an
+ # email message can't be used to overwrite important files
+ filename = part.get_filename()
+ if not filename:
+ ext = mimetypes.guess_extension(part.get_type())
+ if not ext:
+ # Use a generic bag-of-bits extension
+ ext = '.bin'
+ filename = 'part-%03d%s' % (counter, ext)
+ counter += 1
+ fp = open(os.path.join(opts.directory, filename), 'wb')
+ fp.write(part.get_payload(decode=True))
+ fp.close()
+
+
+if __name__ == '__main__':
+ main()
--- /dev/null
+import xml.dom.minidom
+
+document = """\
+<slideshow>
+<title>Demo slideshow</title>
+<slide><title>Slide title</title>
+<point>This is a demo</point>
+<point>Of a program for processing slides</point>
+</slide>
+
+<slide><title>Another demo slide</title>
+<point>It is important</point>
+<point>To have more than</point>
+<point>one slide</point>
+</slide>
+</slideshow>
+"""
+
+dom = xml.dom.minidom.parseString(document)
+
+def getText(nodelist):
+ rc = ""
+ for node in nodelist:
+ if node.nodeType == node.TEXT_NODE:
+ rc = rc + node.data
+ return rc
+
+def handleSlideshow(slideshow):
+ print "<html>"
+ handleSlideshowTitle(slideshow.getElementsByTagName("title")[0])
+ slides = slideshow.getElementsByTagName("slide")
+ handleToc(slides)
+ handleSlides(slides)
+ print "</html>"
+
+def handleSlides(slides):
+ for slide in slides:
+ handleSlide(slide)
+
+def handleSlide(slide):
+ handleSlideTitle(slide.getElementsByTagName("title")[0])
+ handlePoints(slide.getElementsByTagName("point"))
+
+def handleSlideshowTitle(title):
+ print "<title>%s</title>" % getText(title.childNodes)
+
+def handleSlideTitle(title):
+ print "<h2>%s</h2>" % getText(title.childNodes)
+
+def handlePoints(points):
+ print "<ul>"
+ for point in points:
+ handlePoint(point)
+ print "</ul>"
+
+def handlePoint(point):
+ print "<li>%s</li>" % getText(point.childNodes)
+
+def handleToc(slides):
+ for slide in slides:
+ title = slide.getElementsByTagName("title")[0]
+ print "<p>%s</p>" % getText(title.childNodes)
+
+handleSlideshow(dom)
--- /dev/null
+#include <Python.h>
+
+typedef struct {
+ PyObject_HEAD
+ /* Type-specific fields go here. */
+} noddy_NoddyObject;
+
+static PyTypeObject noddy_NoddyType = {
+ PyObject_HEAD_INIT(NULL)
+ 0, /*ob_size*/
+ "noddy.Noddy", /*tp_name*/
+ sizeof(noddy_NoddyObject), /*tp_basicsize*/
+ 0, /*tp_itemsize*/
+ 0, /*tp_dealloc*/
+ 0, /*tp_print*/
+ 0, /*tp_getattr*/
+ 0, /*tp_setattr*/
+ 0, /*tp_compare*/
+ 0, /*tp_repr*/
+ 0, /*tp_as_number*/
+ 0, /*tp_as_sequence*/
+ 0, /*tp_as_mapping*/
+ 0, /*tp_hash */
+ 0, /*tp_call*/
+ 0, /*tp_str*/
+ 0, /*tp_getattro*/
+ 0, /*tp_setattro*/
+ 0, /*tp_as_buffer*/
+ Py_TPFLAGS_DEFAULT, /*tp_flags*/
+ "Noddy objects", /* tp_doc */
+};
+
+static PyMethodDef noddy_methods[] = {
+ {NULL} /* Sentinel */
+};
+
+#ifndef PyMODINIT_FUNC /* declarations for DLL import/export */
+#define PyMODINIT_FUNC void
+#endif
+PyMODINIT_FUNC
+initnoddy(void)
+{
+ PyObject* m;
+
+ noddy_NoddyType.tp_new = PyType_GenericNew;
+ if (PyType_Ready(&noddy_NoddyType) < 0)
+ return;
+
+ m = Py_InitModule3("noddy", noddy_methods,
+ "Example module that creates an extension type.");
+
+ Py_INCREF(&noddy_NoddyType);
+ PyModule_AddObject(m, "Noddy", (PyObject *)&noddy_NoddyType);
+}
--- /dev/null
+#include <Python.h>
+#include "structmember.h"
+
+typedef struct {
+ PyObject_HEAD
+ PyObject *first; /* first name */
+ PyObject *last; /* last name */
+ int number;
+} Noddy;
+
+static void
+Noddy_dealloc(Noddy* self)
+{
+ Py_XDECREF(self->first);
+ Py_XDECREF(self->last);
+ self->ob_type->tp_free((PyObject*)self);
+}
+
+static PyObject *
+Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
+{
+ Noddy *self;
+
+ self = (Noddy *)type->tp_alloc(type, 0);
+ if (self != NULL) {
+ self->first = PyString_FromString("");
+ if (self->first == NULL)
+ {
+ Py_DECREF(self);
+ return NULL;
+ }
+
+ self->last = PyString_FromString("");
+ if (self->last == NULL)
+ {
+ Py_DECREF(self);
+ return NULL;
+ }
+
+ self->number = 0;
+ }
+
+ return (PyObject *)self;
+}
+
+static int
+Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
+{
+ PyObject *first=NULL, *last=NULL, *tmp;
+
+ static char *kwlist[] = {"first", "last", "number", NULL};
+
+ if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
+ &first, &last,
+ &self->number))
+ return -1;
+
+ if (first) {
+ tmp = self->first;
+ Py_INCREF(first);
+ self->first = first;
+ Py_XDECREF(tmp);
+ }
+
+ if (last) {
+ tmp = self->last;
+ Py_INCREF(last);
+ self->last = last;
+ Py_XDECREF(tmp);
+ }
+
+ return 0;
+}
+
+
+static PyMemberDef Noddy_members[] = {
+ {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
+ "first name"},
+ {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
+ "last name"},
+ {"number", T_INT, offsetof(Noddy, number), 0,
+ "noddy number"},
+ {NULL} /* Sentinel */
+};
+
+static PyObject *
+Noddy_name(Noddy* self)
+{
+ static PyObject *format = NULL;
+ PyObject *args, *result;
+
+ if (format == NULL) {
+ format = PyString_FromString("%s %s");
+ if (format == NULL)
+ return NULL;
+ }
+
+ if (self->first == NULL) {
+ PyErr_SetString(PyExc_AttributeError, "first");
+ return NULL;
+ }
+
+ if (self->last == NULL) {
+ PyErr_SetString(PyExc_AttributeError, "last");
+ return NULL;
+ }
+
+ args = Py_BuildValue("OO", self->first, self->last);
+ if (args == NULL)
+ return NULL;
+
+ result = PyString_Format(format, args);
+ Py_DECREF(args);
+
+ return result;
+}
+
+static PyMethodDef Noddy_methods[] = {
+ {"name", (PyCFunction)Noddy_name, METH_NOARGS,
+ "Return the name, combining the first and last name"
+ },
+ {NULL} /* Sentinel */
+};
+
+static PyTypeObject NoddyType = {
+ PyObject_HEAD_INIT(NULL)
+ 0, /*ob_size*/
+ "noddy.Noddy", /*tp_name*/
+ sizeof(Noddy), /*tp_basicsize*/
+ 0, /*tp_itemsize*/
+ (destructor)Noddy_dealloc, /*tp_dealloc*/
+ 0, /*tp_print*/
+ 0, /*tp_getattr*/
+ 0, /*tp_setattr*/
+ 0, /*tp_compare*/
+ 0, /*tp_repr*/
+ 0, /*tp_as_number*/
+ 0, /*tp_as_sequence*/
+ 0, /*tp_as_mapping*/
+ 0, /*tp_hash */
+ 0, /*tp_call*/
+ 0, /*tp_str*/
+ 0, /*tp_getattro*/
+ 0, /*tp_setattro*/
+ 0, /*tp_as_buffer*/
+ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
+ "Noddy objects", /* tp_doc */
+ 0, /* tp_traverse */
+ 0, /* tp_clear */
+ 0, /* tp_richcompare */
+ 0, /* tp_weaklistoffset */
+ 0, /* tp_iter */
+ 0, /* tp_iternext */
+ Noddy_methods, /* tp_methods */
+ Noddy_members, /* tp_members */
+ 0, /* tp_getset */
+ 0, /* tp_base */
+ 0, /* tp_dict */
+ 0, /* tp_descr_get */
+ 0, /* tp_descr_set */
+ 0, /* tp_dictoffset */
+ (initproc)Noddy_init, /* tp_init */
+ 0, /* tp_alloc */
+ Noddy_new, /* tp_new */
+};
+
+static PyMethodDef module_methods[] = {
+ {NULL} /* Sentinel */
+};
+
+#ifndef PyMODINIT_FUNC /* declarations for DLL import/export */
+#define PyMODINIT_FUNC void
+#endif
+PyMODINIT_FUNC
+initnoddy2(void)
+{
+ PyObject* m;
+
+ if (PyType_Ready(&NoddyType) < 0)
+ return;
+
+ m = Py_InitModule3("noddy2", module_methods,
+ "Example module that creates an extension type.");
+
+ if (m == NULL)
+ return;
+
+ Py_INCREF(&NoddyType);
+ PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
+}
--- /dev/null
+#include <Python.h>
+#include "structmember.h"
+
+typedef struct {
+ PyObject_HEAD
+ PyObject *first;
+ PyObject *last;
+ int number;
+} Noddy;
+
+static void
+Noddy_dealloc(Noddy* self)
+{
+ Py_XDECREF(self->first);
+ Py_XDECREF(self->last);
+ self->ob_type->tp_free((PyObject*)self);
+}
+
+static PyObject *
+Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
+{
+ Noddy *self;
+
+ self = (Noddy *)type->tp_alloc(type, 0);
+ if (self != NULL) {
+ self->first = PyString_FromString("");
+ if (self->first == NULL)
+ {
+ Py_DECREF(self);
+ return NULL;
+ }
+
+ self->last = PyString_FromString("");
+ if (self->last == NULL)
+ {
+ Py_DECREF(self);
+ return NULL;
+ }
+
+ self->number = 0;
+ }
+
+ return (PyObject *)self;
+}
+
+static int
+Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
+{
+ PyObject *first=NULL, *last=NULL, *tmp;
+
+ static char *kwlist[] = {"first", "last", "number", NULL};
+
+ if (! PyArg_ParseTupleAndKeywords(args, kwds, "|SSi", kwlist,
+ &first, &last,
+ &self->number))
+ return -1;
+
+ if (first) {
+ tmp = self->first;
+ Py_INCREF(first);
+ self->first = first;
+ Py_DECREF(tmp);
+ }
+
+ if (last) {
+ tmp = self->last;
+ Py_INCREF(last);
+ self->last = last;
+ Py_DECREF(tmp);
+ }
+
+ return 0;
+}
+
+static PyMemberDef Noddy_members[] = {
+ {"number", T_INT, offsetof(Noddy, number), 0,
+ "noddy number"},
+ {NULL} /* Sentinel */
+};
+
+static PyObject *
+Noddy_getfirst(Noddy *self, void *closure)
+{
+ Py_INCREF(self->first);
+ return self->first;
+}
+
+static int
+Noddy_setfirst(Noddy *self, PyObject *value, void *closure)
+{
+ if (value == NULL) {
+ PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
+ return -1;
+ }
+
+ if (! PyString_Check(value)) {
+ PyErr_SetString(PyExc_TypeError,
+ "The first attribute value must be a string");
+ return -1;
+ }
+
+ Py_DECREF(self->first);
+ Py_INCREF(value);
+ self->first = value;
+
+ return 0;
+}
+
+static PyObject *
+Noddy_getlast(Noddy *self, void *closure)
+{
+ Py_INCREF(self->last);
+ return self->last;
+}
+
+static int
+Noddy_setlast(Noddy *self, PyObject *value, void *closure)
+{
+ if (value == NULL) {
+ PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
+ return -1;
+ }
+
+ if (! PyString_Check(value)) {
+ PyErr_SetString(PyExc_TypeError,
+ "The last attribute value must be a string");
+ return -1;
+ }
+
+ Py_DECREF(self->last);
+ Py_INCREF(value);
+ self->last = value;
+
+ return 0;
+}
+
+static PyGetSetDef Noddy_getseters[] = {
+ {"first",
+ (getter)Noddy_getfirst, (setter)Noddy_setfirst,
+ "first name",
+ NULL},
+ {"last",
+ (getter)Noddy_getlast, (setter)Noddy_setlast,
+ "last name",
+ NULL},
+ {NULL} /* Sentinel */
+};
+
+static PyObject *
+Noddy_name(Noddy* self)
+{
+ static PyObject *format = NULL;
+ PyObject *args, *result;
+
+ if (format == NULL) {
+ format = PyString_FromString("%s %s");
+ if (format == NULL)
+ return NULL;
+ }
+
+ args = Py_BuildValue("OO", self->first, self->last);
+ if (args == NULL)
+ return NULL;
+
+ result = PyString_Format(format, args);
+ Py_DECREF(args);
+
+ return result;
+}
+
+static PyMethodDef Noddy_methods[] = {
+ {"name", (PyCFunction)Noddy_name, METH_NOARGS,
+ "Return the name, combining the first and last name"
+ },
+ {NULL} /* Sentinel */
+};
+
+static PyTypeObject NoddyType = {
+ PyObject_HEAD_INIT(NULL)
+ 0, /*ob_size*/
+ "noddy.Noddy", /*tp_name*/
+ sizeof(Noddy), /*tp_basicsize*/
+ 0, /*tp_itemsize*/
+ (destructor)Noddy_dealloc, /*tp_dealloc*/
+ 0, /*tp_print*/
+ 0, /*tp_getattr*/
+ 0, /*tp_setattr*/
+ 0, /*tp_compare*/
+ 0, /*tp_repr*/
+ 0, /*tp_as_number*/
+ 0, /*tp_as_sequence*/
+ 0, /*tp_as_mapping*/
+ 0, /*tp_hash */
+ 0, /*tp_call*/
+ 0, /*tp_str*/
+ 0, /*tp_getattro*/
+ 0, /*tp_setattro*/
+ 0, /*tp_as_buffer*/
+ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
+ "Noddy objects", /* tp_doc */
+ 0, /* tp_traverse */
+ 0, /* tp_clear */
+ 0, /* tp_richcompare */
+ 0, /* tp_weaklistoffset */
+ 0, /* tp_iter */
+ 0, /* tp_iternext */
+ Noddy_methods, /* tp_methods */
+ Noddy_members, /* tp_members */
+ Noddy_getseters, /* tp_getset */
+ 0, /* tp_base */
+ 0, /* tp_dict */
+ 0, /* tp_descr_get */
+ 0, /* tp_descr_set */
+ 0, /* tp_dictoffset */
+ (initproc)Noddy_init, /* tp_init */
+ 0, /* tp_alloc */
+ Noddy_new, /* tp_new */
+};
+
+static PyMethodDef module_methods[] = {
+ {NULL} /* Sentinel */
+};
+
+#ifndef PyMODINIT_FUNC /* declarations for DLL import/export */
+#define PyMODINIT_FUNC void
+#endif
+PyMODINIT_FUNC
+initnoddy3(void)
+{
+ PyObject* m;
+
+ if (PyType_Ready(&NoddyType) < 0)
+ return;
+
+ m = Py_InitModule3("noddy3", module_methods,
+ "Example module that creates an extension type.");
+
+ if (m == NULL)
+ return;
+
+ Py_INCREF(&NoddyType);
+ PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
+}
--- /dev/null
+#include <Python.h>
+#include "structmember.h"
+
+typedef struct {
+ PyObject_HEAD
+ PyObject *first;
+ PyObject *last;
+ int number;
+} Noddy;
+
+static int
+Noddy_traverse(Noddy *self, visitproc visit, void *arg)
+{
+ int vret;
+
+ if (self->first) {
+ vret = visit(self->first, arg);
+ if (vret != 0)
+ return vret;
+ }
+ if (self->last) {
+ vret = visit(self->last, arg);
+ if (vret != 0)
+ return vret;
+ }
+
+ return 0;
+}
+
+static int
+Noddy_clear(Noddy *self)
+{
+ PyObject *tmp;
+
+ tmp = self->first;
+ self->first = NULL;
+ Py_XDECREF(tmp);
+
+ tmp = self->last;
+ self->last = NULL;
+ Py_XDECREF(tmp);
+
+ return 0;
+}
+
+static void
+Noddy_dealloc(Noddy* self)
+{
+ Noddy_clear(self);
+ self->ob_type->tp_free((PyObject*)self);
+}
+
+static PyObject *
+Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
+{
+ Noddy *self;
+
+ self = (Noddy *)type->tp_alloc(type, 0);
+ if (self != NULL) {
+ self->first = PyString_FromString("");
+ if (self->first == NULL)
+ {
+ Py_DECREF(self);
+ return NULL;
+ }
+
+ self->last = PyString_FromString("");
+ if (self->last == NULL)
+ {
+ Py_DECREF(self);
+ return NULL;
+ }
+
+ self->number = 0;
+ }
+
+ return (PyObject *)self;
+}
+
+static int
+Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
+{
+ PyObject *first=NULL, *last=NULL, *tmp;
+
+ static char *kwlist[] = {"first", "last", "number", NULL};
+
+ if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
+ &first, &last,
+ &self->number))
+ return -1;
+
+ if (first) {
+ tmp = self->first;
+ Py_INCREF(first);
+ self->first = first;
+ Py_XDECREF(tmp);
+ }
+
+ if (last) {
+ tmp = self->last;
+ Py_INCREF(last);
+ self->last = last;
+ Py_XDECREF(tmp);
+ }
+
+ return 0;
+}
+
+
+static PyMemberDef Noddy_members[] = {
+ {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
+ "first name"},
+ {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
+ "last name"},
+ {"number", T_INT, offsetof(Noddy, number), 0,
+ "noddy number"},
+ {NULL} /* Sentinel */
+};
+
+static PyObject *
+Noddy_name(Noddy* self)
+{
+ static PyObject *format = NULL;
+ PyObject *args, *result;
+
+ if (format == NULL) {
+ format = PyString_FromString("%s %s");
+ if (format == NULL)
+ return NULL;
+ }
+
+ if (self->first == NULL) {
+ PyErr_SetString(PyExc_AttributeError, "first");
+ return NULL;
+ }
+
+ if (self->last == NULL) {
+ PyErr_SetString(PyExc_AttributeError, "last");
+ return NULL;
+ }
+
+ args = Py_BuildValue("OO", self->first, self->last);
+ if (args == NULL)
+ return NULL;
+
+ result = PyString_Format(format, args);
+ Py_DECREF(args);
+
+ return result;
+}
+
+static PyMethodDef Noddy_methods[] = {
+ {"name", (PyCFunction)Noddy_name, METH_NOARGS,
+ "Return the name, combining the first and last name"
+ },
+ {NULL} /* Sentinel */
+};
+
+static PyTypeObject NoddyType = {
+ PyObject_HEAD_INIT(NULL)
+ 0, /*ob_size*/
+ "noddy.Noddy", /*tp_name*/
+ sizeof(Noddy), /*tp_basicsize*/
+ 0, /*tp_itemsize*/
+ (destructor)Noddy_dealloc, /*tp_dealloc*/
+ 0, /*tp_print*/
+ 0, /*tp_getattr*/
+ 0, /*tp_setattr*/
+ 0, /*tp_compare*/
+ 0, /*tp_repr*/
+ 0, /*tp_as_number*/
+ 0, /*tp_as_sequence*/
+ 0, /*tp_as_mapping*/
+ 0, /*tp_hash */
+ 0, /*tp_call*/
+ 0, /*tp_str*/
+ 0, /*tp_getattro*/
+ 0, /*tp_setattro*/
+ 0, /*tp_as_buffer*/
+ Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /*tp_flags*/
+ "Noddy objects", /* tp_doc */
+ (traverseproc)Noddy_traverse, /* tp_traverse */
+ (inquiry)Noddy_clear, /* tp_clear */
+ 0, /* tp_richcompare */
+ 0, /* tp_weaklistoffset */
+ 0, /* tp_iter */
+ 0, /* tp_iternext */
+ Noddy_methods, /* tp_methods */
+ Noddy_members, /* tp_members */
+ 0, /* tp_getset */
+ 0, /* tp_base */
+ 0, /* tp_dict */
+ 0, /* tp_descr_get */
+ 0, /* tp_descr_set */
+ 0, /* tp_dictoffset */
+ (initproc)Noddy_init, /* tp_init */
+ 0, /* tp_alloc */
+ Noddy_new, /* tp_new */
+};
+
+static PyMethodDef module_methods[] = {
+ {NULL} /* Sentinel */
+};
+
+#ifndef PyMODINIT_FUNC /* declarations for DLL import/export */
+#define PyMODINIT_FUNC void
+#endif
+PyMODINIT_FUNC
+initnoddy4(void)
+{
+ PyObject* m;
+
+ if (PyType_Ready(&NoddyType) < 0)
+ return;
+
+ m = Py_InitModule3("noddy4", module_methods,
+ "Example module that creates an extension type.");
+
+ if (m == NULL)
+ return;
+
+ Py_INCREF(&NoddyType);
+ PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
+}
--- /dev/null
+#include <Python.h>
+
+int
+main(int argc, char *argv[])
+{
+ PyObject *pName, *pModule, *pDict, *pFunc;
+ PyObject *pArgs, *pValue;
+ int i;
+
+ if (argc < 3) {
+ fprintf(stderr,"Usage: call pythonfile funcname [args]\n");
+ return 1;
+ }
+
+ Py_Initialize();
+ pName = PyString_FromString(argv[1]);
+ /* Error checking of pName left out */
+
+ pModule = PyImport_Import(pName);
+ Py_DECREF(pName);
+
+ if (pModule != NULL) {
+ pFunc = PyObject_GetAttrString(pModule, argv[2]);
+ /* pFunc is a new reference */
+
+ if (pFunc && PyCallable_Check(pFunc)) {
+ pArgs = PyTuple_New(argc - 3);
+ for (i = 0; i < argc - 3; ++i) {
+ pValue = PyInt_FromLong(atoi(argv[i + 3]));
+ if (!pValue) {
+ Py_DECREF(pArgs);
+ Py_DECREF(pModule);
+ fprintf(stderr, "Cannot convert argument\n");
+ return 1;
+ }
+ /* pValue reference stolen here: */
+ PyTuple_SetItem(pArgs, i, pValue);
+ }
+ pValue = PyObject_CallObject(pFunc, pArgs);
+ Py_DECREF(pArgs);
+ if (pValue != NULL) {
+ printf("Result of call: %ld\n", PyInt_AsLong(pValue));
+ Py_DECREF(pValue);
+ }
+ else {
+ Py_DECREF(pFunc);
+ Py_DECREF(pModule);
+ PyErr_Print();
+ fprintf(stderr,"Call failed\n");
+ return 1;
+ }
+ }
+ else {
+ if (PyErr_Occurred())
+ PyErr_Print();
+ fprintf(stderr, "Cannot find function \"%s\"\n", argv[2]);
+ }
+ Py_XDECREF(pFunc);
+ Py_DECREF(pModule);
+ }
+ else {
+ PyErr_Print();
+ fprintf(stderr, "Failed to load \"%s\"\n", argv[1]);
+ return 1;
+ }
+ Py_Finalize();
+ return 0;
+}
--- /dev/null
+from distutils.core import setup, Extension
+setup(name="noddy", version="1.0",
+ ext_modules=[
+ Extension("noddy", ["noddy.c"]),
+ Extension("noddy2", ["noddy2.c"]),
+ Extension("noddy3", ["noddy3.c"]),
+ Extension("noddy4", ["noddy4.c"]),
+ ])
--- /dev/null
+#include <Python.h>
+
+typedef struct {
+ PyListObject list;
+ int state;
+} Shoddy;
+
+
+static PyObject *
+Shoddy_increment(Shoddy *self, PyObject *unused)
+{
+ self->state++;
+ return PyInt_FromLong(self->state);
+}
+
+
+static PyMethodDef Shoddy_methods[] = {
+ {"increment", (PyCFunction)Shoddy_increment, METH_NOARGS,
+ PyDoc_STR("increment state counter")},
+ {NULL, NULL},
+};
+
+static int
+Shoddy_init(Shoddy *self, PyObject *args, PyObject *kwds)
+{
+ if (PyList_Type.tp_init((PyObject *)self, args, kwds) < 0)
+ return -1;
+ self->state = 0;
+ return 0;
+}
+
+
+static PyTypeObject ShoddyType = {
+ PyObject_HEAD_INIT(NULL)
+ 0, /* ob_size */
+ "shoddy.Shoddy", /* tp_name */
+ sizeof(Shoddy), /* tp_basicsize */
+ 0, /* tp_itemsize */
+ 0, /* tp_dealloc */
+ 0, /* tp_print */
+ 0, /* tp_getattr */
+ 0, /* tp_setattr */
+ 0, /* tp_compare */
+ 0, /* tp_repr */
+ 0, /* tp_as_number */
+ 0, /* tp_as_sequence */
+ 0, /* tp_as_mapping */
+ 0, /* tp_hash */
+ 0, /* tp_call */
+ 0, /* tp_str */
+ 0, /* tp_getattro */
+ 0, /* tp_setattro */
+ 0, /* tp_as_buffer */
+ Py_TPFLAGS_DEFAULT |
+ Py_TPFLAGS_BASETYPE, /* tp_flags */
+ 0, /* tp_doc */
+ 0, /* tp_traverse */
+ 0, /* tp_clear */
+ 0, /* tp_richcompare */
+ 0, /* tp_weaklistoffset */
+ 0, /* tp_iter */
+ 0, /* tp_iternext */
+ Shoddy_methods, /* tp_methods */
+ 0, /* tp_members */
+ 0, /* tp_getset */
+ 0, /* tp_base */
+ 0, /* tp_dict */
+ 0, /* tp_descr_get */
+ 0, /* tp_descr_set */
+ 0, /* tp_dictoffset */
+ (initproc)Shoddy_init, /* tp_init */
+ 0, /* tp_alloc */
+ 0, /* tp_new */
+};
+
+PyMODINIT_FUNC
+initshoddy(void)
+{
+ PyObject *m;
+
+ ShoddyType.tp_base = &PyList_Type;
+ if (PyType_Ready(&ShoddyType) < 0)
+ return;
+
+ m = Py_InitModule3("shoddy", NULL, "Shoddy module");
+ if (m == NULL)
+ return;
+
+ Py_INCREF(&ShoddyType);
+ PyModule_AddObject(m, "Shoddy", (PyObject *) &ShoddyType);
+}
--- /dev/null
+import sqlite3
+import datetime, time
+
+def adapt_datetime(ts):
+ return time.mktime(ts.timetuple())
+
+sqlite3.register_adapter(datetime.datetime, adapt_datetime)
+
+con = sqlite3.connect(":memory:")
+cur = con.cursor()
+
+now = datetime.datetime.now()
+cur.execute("select ?", (now,))
+print cur.fetchone()[0]
--- /dev/null
+import sqlite3
+
+class Point(object):
+ def __init__(self, x, y):
+ self.x, self.y = x, y
+
+ def __conform__(self, protocol):
+ if protocol is sqlite3.PrepareProtocol:
+ return "%f;%f" % (self.x, self.y)
+
+con = sqlite3.connect(":memory:")
+cur = con.cursor()
+
+p = Point(4.0, -3.2)
+cur.execute("select ?", (p,))
+print cur.fetchone()[0]
--- /dev/null
+import sqlite3
+
+class Point(object):
+ def __init__(self, x, y):
+ self.x, self.y = x, y
+
+def adapt_point(point):
+ return "%f;%f" % (point.x, point.y)
+
+sqlite3.register_adapter(Point, adapt_point)
+
+con = sqlite3.connect(":memory:")
+cur = con.cursor()
+
+p = Point(4.0, -3.2)
+cur.execute("select ?", (p,))
+print cur.fetchone()[0]
--- /dev/null
+import sqlite3
+
+def collate_reverse(string1, string2):
+ return -cmp(string1, string2)
+
+con = sqlite3.connect(":memory:")
+con.create_collation("reverse", collate_reverse)
+
+cur = con.cursor()
+cur.execute("create table test(x)")
+cur.executemany("insert into test(x) values (?)", [("a",), ("b",)])
+cur.execute("select x from test order by x collate reverse")
+for row in cur:
+ print row
+con.close()
--- /dev/null
+# A minimal SQLite shell for experiments
+
+import sqlite3
+
+con = sqlite3.connect(":memory:")
+con.isolation_level = None
+cur = con.cursor()
+
+buffer = ""
+
+print "Enter your SQL commands to execute in sqlite3."
+print "Enter a blank line to exit."
+
+while True:
+ line = raw_input()
+ if line == "":
+ break
+ buffer += line
+ if sqlite3.complete_statement(buffer):
+ try:
+ buffer = buffer.strip()
+ cur.execute(buffer)
+
+ if buffer.lstrip().upper().startswith("SELECT"):
+ print cur.fetchall()
+ except sqlite3.Error, e:
+ print "An error occurred:", e.args[0]
+ buffer = ""
+
+con.close()
--- /dev/null
+import sqlite3
+
+con = sqlite3.connect("mydb")
--- /dev/null
+import sqlite3
+
+con = sqlite3.connect(":memory:")
--- /dev/null
+import sqlite3
+
+class Point(object):
+ def __init__(self, x, y):
+ self.x, self.y = x, y
+
+ def __repr__(self):
+ return "(%f;%f)" % (self.x, self.y)
+
+def adapt_point(point):
+ return "%f;%f" % (point.x, point.y)
+
+def convert_point(s):
+ x, y = map(float, s.split(";"))
+ return Point(x, y)
+
+# Register the adapter
+sqlite3.register_adapter(Point, adapt_point)
+
+# Register the converter
+sqlite3.register_converter("point", convert_point)
+
+p = Point(4.0, -3.2)
+
+#########################
+# 1) Using declared types
+con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
+cur = con.cursor()
+cur.execute("create table test(p point)")
+
+cur.execute("insert into test(p) values (?)", (p,))
+cur.execute("select p from test")
+print "with declared types:", cur.fetchone()[0]
+cur.close()
+con.close()
+
+#######################
+# 1) Using column names
+con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
+cur = con.cursor()
+cur.execute("create table test(p)")
+
+cur.execute("insert into test(p) values (?)", (p,))
+cur.execute('select p as "p [point]" from test')
+print "with column names:", cur.fetchone()[0]
+cur.close()
+con.close()
--- /dev/null
+import sqlite3
+
+class CountCursorsConnection(sqlite3.Connection):
+ def __init__(self, *args, **kwargs):
+ sqlite3.Connection.__init__(self, *args, **kwargs)
+ self.numcursors = 0
+
+ def cursor(self, *args, **kwargs):
+ self.numcursors += 1
+ return sqlite3.Connection.cursor(self, *args, **kwargs)
+
+con = sqlite3.connect(":memory:", factory=CountCursorsConnection)
+cur1 = con.cursor()
+cur2 = con.cursor()
+print con.numcursors
--- /dev/null
+# Not referenced from the documentation, but builds the database file the other
+# code snippets expect.
+
+import sqlite3
+import os
+
+DB_FILE = "mydb"
+
+if os.path.exists(DB_FILE):
+ os.remove(DB_FILE)
+
+con = sqlite3.connect(DB_FILE)
+cur = con.cursor()
+cur.execute("""
+ create table people
+ (
+ name_last varchar(20),
+ age integer
+ )
+ """)
+
+cur.execute("insert into people (name_last, age) values ('Yeltsin', 72)")
+cur.execute("insert into people (name_last, age) values ('Putin', 51)")
+
+con.commit()
+
+cur.close()
+con.close()
--- /dev/null
+import sqlite3
+
+con = sqlite3.connect("mydb")
+
+cur = con.cursor()
+SELECT = "select name_last, age from people order by age, name_last"
+
+# 1. Iterate over the rows available from the cursor, unpacking the
+# resulting sequences to yield their elements (name_last, age):
+cur.execute(SELECT)
+for (name_last, age) in cur:
+ print '%s is %d years old.' % (name_last, age)
+
+# 2. Equivalently:
+cur.execute(SELECT)
+for row in cur:
+ print '%s is %d years old.' % (row[0], row[1])
--- /dev/null
+import sqlite3
+
+# Create a connection to the database file "mydb":
+con = sqlite3.connect("mydb")
+
+# Get a Cursor object that operates in the context of Connection con:
+cur = con.cursor()
+
+# Execute the SELECT statement:
+cur.execute("select * from people order by age")
+
+# Retrieve all rows as a sequence and print that sequence:
+print cur.fetchall()
--- /dev/null
+import sqlite3
+
+con = sqlite3.connect("mydb")
+
+cur = con.cursor()
+
+who = "Yeltsin"
+age = 72
+
+cur.execute("select name_last, age from people where name_last=? and age=?", (who, age))
+print cur.fetchone()
--- /dev/null
+import sqlite3
+
+con = sqlite3.connect("mydb")
+
+cur = con.cursor()
+
+who = "Yeltsin"
+age = 72
+
+cur.execute("select name_last, age from people where name_last=:who and age=:age",
+ {"who": who, "age": age})
+print cur.fetchone()
--- /dev/null
+import sqlite3
+
+con = sqlite3.connect("mydb")
+
+cur = con.cursor()
+
+who = "Yeltsin"
+age = 72
+
+cur.execute("select name_last, age from people where name_last=:who and age=:age",
+ locals())
+print cur.fetchone()
--- /dev/null
+import sqlite3
+
+class IterChars:
+ def __init__(self):
+ self.count = ord('a')
+
+ def __iter__(self):
+ return self
+
+ def next(self):
+ if self.count > ord('z'):
+ raise StopIteration
+ self.count += 1
+ return (chr(self.count - 1),) # this is a 1-tuple
+
+con = sqlite3.connect(":memory:")
+cur = con.cursor()
+cur.execute("create table characters(c)")
+
+theIter = IterChars()
+cur.executemany("insert into characters(c) values (?)", theIter)
+
+cur.execute("select c from characters")
+print cur.fetchall()
--- /dev/null
+import sqlite3
+
+def char_generator():
+ import string
+ for c in string.letters[:26]:
+ yield (c,)
+
+con = sqlite3.connect(":memory:")
+cur = con.cursor()
+cur.execute("create table characters(c)")
+
+cur.executemany("insert into characters(c) values (?)", char_generator())
+
+cur.execute("select c from characters")
+print cur.fetchall()
--- /dev/null
+import sqlite3
+
+con = sqlite3.connect(":memory:")
+cur = con.cursor()
+cur.executescript("""
+ create table person(
+ firstname,
+ lastname,
+ age
+ );
+
+ create table book(
+ title,
+ author,
+ published
+ );
+
+ insert into book(title, author, published)
+ values (
+ 'Dirk Gently''s Holistic Detective Agency',
+ 'Douglas Adams',
+ 1987
+ );
+ """)
--- /dev/null
+import sqlite3
+
+con = sqlite3.connect("mydb")
+
+cur = con.cursor()
+
+newPeople = (
+ ('Lebed' , 53),
+ ('Zhirinovsky' , 57),
+ )
+
+for person in newPeople:
+ cur.execute("insert into people (name_last, age) values (?, ?)", person)
+
+# The changes will not be saved unless the transaction is committed explicitly:
+con.commit()
--- /dev/null
+import sqlite3
+import md5
+
+def md5sum(t):
+ return md5.md5(t).hexdigest()
+
+con = sqlite3.connect(":memory:")
+con.create_function("md5", 1, md5sum)
+cur = con.cursor()
+cur.execute("select md5(?)", ("foo",))
+print cur.fetchone()[0]
--- /dev/null
+import sqlite3
+
+class MySum:
+ def __init__(self):
+ self.count = 0
+
+ def step(self, value):
+ self.count += value
+
+ def finalize(self):
+ return self.count
+
+con = sqlite3.connect(":memory:")
+con.create_aggregate("mysum", 1, MySum)
+cur = con.cursor()
+cur.execute("create table test(i)")
+cur.execute("insert into test(i) values (1)")
+cur.execute("insert into test(i) values (2)")
+cur.execute("select mysum(i) from test")
+print cur.fetchone()[0]
--- /dev/null
+import sqlite3
+import datetime
+
+con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
+cur = con.cursor()
+cur.execute('select ? as "x [timestamp]"', (datetime.datetime.now(),))
+dt = cur.fetchone()[0]
+print dt, type(dt)
--- /dev/null
+import sqlite3
+import datetime
+
+con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
+cur = con.cursor()
+cur.execute("create table test(d date, ts timestamp)")
+
+today = datetime.date.today()
+now = datetime.datetime.now()
+
+cur.execute("insert into test(d, ts) values (?, ?)", (today, now))
+cur.execute("select d, ts from test")
+row = cur.fetchone()
+print today, "=>", row[0], type(row[0])
+print now, "=>", row[1], type(row[1])
+
+cur.execute('select current_date as "d [date]", current_timestamp as "ts [timestamp]"')
+row = cur.fetchone()
+print "current_date", row[0], type(row[0])
+print "current_timestamp", row[1], type(row[1])
--- /dev/null
+import sqlite3
+
+def dict_factory(cursor, row):
+ d = {}
+ for idx, col in enumerate(cursor.description):
+ d[col[0]] = row[idx]
+ return d
+
+con = sqlite3.connect(":memory:")
+con.row_factory = dict_factory
+cur = con.cursor()
+cur.execute("select 1 as a")
+print cur.fetchone()["a"]
--- /dev/null
+import sqlite3
+
+con = sqlite3.connect("mydb")
+con.row_factory = sqlite3.Row
+
+cur = con.cursor()
+cur.execute("select name_last, age from people")
+for row in cur:
+ assert row[0] == row["name_last"]
+ assert row["name_last"] == row["nAmE_lAsT"]
+ assert row[1] == row["age"]
+ assert row[1] == row["AgE"]
--- /dev/null
+import sqlite3
+
+# The shared cache is only available in SQLite versions 3.3.3 or later
+# See the SQLite documentaton for details.
+
+sqlite3.enable_shared_cache(True)
--- /dev/null
+import sqlite3
+
+persons = [
+ ("Hugo", "Boss"),
+ ("Calvin", "Klein")
+ ]
+
+con = sqlite3.connect(":memory:")
+
+# Create the table
+con.execute("create table person(firstname, lastname)")
+
+# Fill the table
+con.executemany("insert into person(firstname, lastname) values (?, ?)", persons)
+
+# Print the table contents
+for row in con.execute("select firstname, lastname from person"):
+ print row
+
+# Using a dummy WHERE clause to not let SQLite take the shortcut table deletes.
+print "I just deleted", con.execute("delete from person where 1=1").rowcount, "rows"
--- /dev/null
+import sqlite3
+
+FIELD_MAX_WIDTH = 20
+TABLE_NAME = 'people'
+SELECT = 'select * from %s order by age, name_last' % TABLE_NAME
+
+con = sqlite3.connect("mydb")
+
+cur = con.cursor()
+cur.execute(SELECT)
+
+# Print a header.
+for fieldDesc in cur.description:
+ print fieldDesc[0].ljust(FIELD_MAX_WIDTH) ,
+print # Finish the header with a newline.
+print '-' * 78
+
+# For each row, print the value of each field left-justified within
+# the maximum possible width of that field.
+fieldIndices = range(len(cur.description))
+for row in cur:
+ for fieldIndex in fieldIndices:
+ fieldValue = str(row[fieldIndex])
+ print fieldValue.ljust(FIELD_MAX_WIDTH) ,
+
+ print # Finish the row with a newline.
--- /dev/null
+import sqlite3
+
+con = sqlite3.connect(":memory:")
+cur = con.cursor()
+
+# Create the table
+con.execute("create table person(lastname, firstname)")
+
+AUSTRIA = u"\xd6sterreich"
+
+# by default, rows are returned as Unicode
+cur.execute("select ?", (AUSTRIA,))
+row = cur.fetchone()
+assert row[0] == AUSTRIA
+
+# but we can make pysqlite always return bytestrings ...
+con.text_factory = str
+cur.execute("select ?", (AUSTRIA,))
+row = cur.fetchone()
+assert type(row[0]) == str
+# the bytestrings will be encoded in UTF-8, unless you stored garbage in the
+# database ...
+assert row[0] == AUSTRIA.encode("utf-8")
+
+# we can also implement a custom text_factory ...
+# here we implement one that will ignore Unicode characters that cannot be
+# decoded from UTF-8
+con.text_factory = lambda x: unicode(x, "utf-8", "ignore")
+cur.execute("select ?", ("this is latin1 and would normally create errors" + u"\xe4\xf6\xfc".encode("latin1"),))
+row = cur.fetchone()
+assert type(row[0]) == unicode
+
+# pysqlite offers a builtin optimized text_factory that will return bytestring
+# objects, if the data is in ASCII only, and otherwise return unicode objects
+con.text_factory = sqlite3.OptimizedUnicode
+cur.execute("select ?", (AUSTRIA,))
+row = cur.fetchone()
+assert type(row[0]) == unicode
+
+cur.execute("select ?", ("Germany",))
+row = cur.fetchone()
+assert type(row[0]) == str
--- /dev/null
+"""Test module for the noddy examples
+
+Noddy 1:
+
+>>> import noddy
+>>> n1 = noddy.Noddy()
+>>> n2 = noddy.Noddy()
+>>> del n1
+>>> del n2
+
+
+Noddy 2
+
+>>> import noddy2
+>>> n1 = noddy2.Noddy('jim', 'fulton', 42)
+>>> n1.first
+'jim'
+>>> n1.last
+'fulton'
+>>> n1.number
+42
+>>> n1.name()
+'jim fulton'
+>>> n1.first = 'will'
+>>> n1.name()
+'will fulton'
+>>> n1.last = 'tell'
+>>> n1.name()
+'will tell'
+>>> del n1.first
+>>> n1.name()
+Traceback (most recent call last):
+...
+AttributeError: first
+>>> n1.first
+Traceback (most recent call last):
+...
+AttributeError: first
+>>> n1.first = 'drew'
+>>> n1.first
+'drew'
+>>> del n1.number
+Traceback (most recent call last):
+...
+TypeError: can't delete numeric/char attribute
+>>> n1.number=2
+>>> n1.number
+2
+>>> n1.first = 42
+>>> n1.name()
+'42 tell'
+>>> n2 = noddy2.Noddy()
+>>> n2.name()
+' '
+>>> n2.first
+''
+>>> n2.last
+''
+>>> del n2.first
+>>> n2.first
+Traceback (most recent call last):
+...
+AttributeError: first
+>>> n2.first
+Traceback (most recent call last):
+...
+AttributeError: first
+>>> n2.name()
+Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+AttributeError: first
+>>> n2.number
+0
+>>> n3 = noddy2.Noddy('jim', 'fulton', 'waaa')
+Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+TypeError: an integer is required
+>>> del n1
+>>> del n2
+
+
+Noddy 3
+
+>>> import noddy3
+>>> n1 = noddy3.Noddy('jim', 'fulton', 42)
+>>> n1 = noddy3.Noddy('jim', 'fulton', 42)
+>>> n1.name()
+'jim fulton'
+>>> del n1.first
+Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+TypeError: Cannot delete the first attribute
+>>> n1.first = 42
+Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+TypeError: The first attribute value must be a string
+>>> n1.first = 'will'
+>>> n1.name()
+'will fulton'
+>>> n2 = noddy3.Noddy()
+>>> n2 = noddy3.Noddy()
+>>> n2 = noddy3.Noddy()
+>>> n3 = noddy3.Noddy('jim', 'fulton', 'waaa')
+Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+TypeError: an integer is required
+>>> del n1
+>>> del n2
+
+Noddy 4
+
+>>> import noddy4
+>>> n1 = noddy4.Noddy('jim', 'fulton', 42)
+>>> n1.first
+'jim'
+>>> n1.last
+'fulton'
+>>> n1.number
+42
+>>> n1.name()
+'jim fulton'
+>>> n1.first = 'will'
+>>> n1.name()
+'will fulton'
+>>> n1.last = 'tell'
+>>> n1.name()
+'will tell'
+>>> del n1.first
+>>> n1.name()
+Traceback (most recent call last):
+...
+AttributeError: first
+>>> n1.first
+Traceback (most recent call last):
+...
+AttributeError: first
+>>> n1.first = 'drew'
+>>> n1.first
+'drew'
+>>> del n1.number
+Traceback (most recent call last):
+...
+TypeError: can't delete numeric/char attribute
+>>> n1.number=2
+>>> n1.number
+2
+>>> n1.first = 42
+>>> n1.name()
+'42 tell'
+>>> n2 = noddy4.Noddy()
+>>> n2 = noddy4.Noddy()
+>>> n2 = noddy4.Noddy()
+>>> n2 = noddy4.Noddy()
+>>> n2.name()
+' '
+>>> n2.first
+''
+>>> n2.last
+''
+>>> del n2.first
+>>> n2.first
+Traceback (most recent call last):
+...
+AttributeError: first
+>>> n2.first
+Traceback (most recent call last):
+...
+AttributeError: first
+>>> n2.name()
+Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+AttributeError: first
+>>> n2.number
+0
+>>> n3 = noddy4.Noddy('jim', 'fulton', 'waaa')
+Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+TypeError: an integer is required
+
+
+Test cyclic gc(?)
+
+>>> import gc
+>>> gc.disable()
+
+>>> x = []
+>>> l = [x]
+>>> n2.first = l
+>>> n2.first
+[[]]
+>>> l.append(n2)
+>>> del l
+>>> del n1
+>>> del n2
+>>> sys.getrefcount(x)
+3
+>>> ignore = gc.collect()
+>>> sys.getrefcount(x)
+2
+
+>>> gc.enable()
+"""
+
+import os
+import sys
+from distutils.util import get_platform
+PLAT_SPEC = "%s-%s" % (get_platform(), sys.version[0:3])
+src = os.path.join("build", "lib.%s" % PLAT_SPEC)
+sys.path.append(src)
+
+if __name__ == "__main__":
+ import doctest, __main__
+ doctest.testmod(__main__)
--- /dev/null
+typedef struct _typeobject {
+ PyObject_VAR_HEAD
+ char *tp_name; /* For printing, in format "<module>.<name>" */
+ int tp_basicsize, tp_itemsize; /* For allocation */
+
+ /* Methods to implement standard operations */
+
+ destructor tp_dealloc;
+ printfunc tp_print;
+ getattrfunc tp_getattr;
+ setattrfunc tp_setattr;
+ cmpfunc tp_compare;
+ reprfunc tp_repr;
+
+ /* Method suites for standard classes */
+
+ PyNumberMethods *tp_as_number;
+ PySequenceMethods *tp_as_sequence;
+ PyMappingMethods *tp_as_mapping;
+
+ /* More standard operations (here for binary compatibility) */
+
+ hashfunc tp_hash;
+ ternaryfunc tp_call;
+ reprfunc tp_str;
+ getattrofunc tp_getattro;
+ setattrofunc tp_setattro;
+
+ /* Functions to access object as input/output buffer */
+ PyBufferProcs *tp_as_buffer;
+
+ /* Flags to define presence of optional/expanded features */
+ long tp_flags;
+
+ char *tp_doc; /* Documentation string */
+
+ /* Assigned meaning in release 2.0 */
+ /* call function for all accessible objects */
+ traverseproc tp_traverse;
+
+ /* delete references to contained objects */
+ inquiry tp_clear;
+
+ /* Assigned meaning in release 2.1 */
+ /* rich comparisons */
+ richcmpfunc tp_richcompare;
+
+ /* weak reference enabler */
+ long tp_weaklistoffset;
+
+ /* Added in release 2.2 */
+ /* Iterators */
+ getiterfunc tp_iter;
+ iternextfunc tp_iternext;
+
+ /* Attribute descriptor and subclassing stuff */
+ struct PyMethodDef *tp_methods;
+ struct PyMemberDef *tp_members;
+ struct PyGetSetDef *tp_getset;
+ struct _typeobject *tp_base;
+ PyObject *tp_dict;
+ descrgetfunc tp_descr_get;
+ descrsetfunc tp_descr_set;
+ long tp_dictoffset;
+ initproc tp_init;
+ allocfunc tp_alloc;
+ newfunc tp_new;
+ freefunc tp_free; /* Low-level free-memory routine */
+ inquiry tp_is_gc; /* For PyObject_IS_GC */
+ PyObject *tp_bases;
+ PyObject *tp_mro; /* method resolution order */
+ PyObject *tp_cache;
+ PyObject *tp_subclasses;
+ PyObject *tp_weaklist;
+
+} PyTypeObject;
--- /dev/null
+from datetime import tzinfo, timedelta, datetime
+
+ZERO = timedelta(0)
+HOUR = timedelta(hours=1)
+
+# A UTC class.
+
+class UTC(tzinfo):
+ """UTC"""
+
+ def utcoffset(self, dt):
+ return ZERO
+
+ def tzname(self, dt):
+ return "UTC"
+
+ def dst(self, dt):
+ return ZERO
+
+utc = UTC()
+
+# A class building tzinfo objects for fixed-offset time zones.
+# Note that FixedOffset(0, "UTC") is a different way to build a
+# UTC tzinfo object.
+
+class FixedOffset(tzinfo):
+ """Fixed offset in minutes east from UTC."""
+
+ def __init__(self, offset, name):
+ self.__offset = timedelta(minutes = offset)
+ self.__name = name
+
+ def utcoffset(self, dt):
+ return self.__offset
+
+ def tzname(self, dt):
+ return self.__name
+
+ def dst(self, dt):
+ return ZERO
+
+# A class capturing the platform's idea of local time.
+
+import time as _time
+
+STDOFFSET = timedelta(seconds = -_time.timezone)
+if _time.daylight:
+ DSTOFFSET = timedelta(seconds = -_time.altzone)
+else:
+ DSTOFFSET = STDOFFSET
+
+DSTDIFF = DSTOFFSET - STDOFFSET
+
+class LocalTimezone(tzinfo):
+
+ def utcoffset(self, dt):
+ if self._isdst(dt):
+ return DSTOFFSET
+ else:
+ return STDOFFSET
+
+ def dst(self, dt):
+ if self._isdst(dt):
+ return DSTDIFF
+ else:
+ return ZERO
+
+ def tzname(self, dt):
+ return _time.tzname[self._isdst(dt)]
+
+ def _isdst(self, dt):
+ tt = (dt.year, dt.month, dt.day,
+ dt.hour, dt.minute, dt.second,
+ dt.weekday(), 0, -1)
+ stamp = _time.mktime(tt)
+ tt = _time.localtime(stamp)
+ return tt.tm_isdst > 0
+
+Local = LocalTimezone()
+
+
+# A complete implementation of current DST rules for major US time zones.
+
+def first_sunday_on_or_after(dt):
+ days_to_go = 6 - dt.weekday()
+ if days_to_go:
+ dt += timedelta(days_to_go)
+ return dt
+
+# In the US, DST starts at 2am (standard time) on the first Sunday in April.
+DSTSTART = datetime(1, 4, 1, 2)
+# and ends at 2am (DST time; 1am standard time) on the last Sunday of Oct.
+# which is the first Sunday on or after Oct 25.
+DSTEND = datetime(1, 10, 25, 1)
+
+class USTimeZone(tzinfo):
+
+ def __init__(self, hours, reprname, stdname, dstname):
+ self.stdoffset = timedelta(hours=hours)
+ self.reprname = reprname
+ self.stdname = stdname
+ self.dstname = dstname
+
+ def __repr__(self):
+ return self.reprname
+
+ def tzname(self, dt):
+ if self.dst(dt):
+ return self.dstname
+ else:
+ return self.stdname
+
+ def utcoffset(self, dt):
+ return self.stdoffset + self.dst(dt)
+
+ def dst(self, dt):
+ if dt is None or dt.tzinfo is None:
+ # An exception may be sensible here, in one or both cases.
+ # It depends on how you want to treat them. The default
+ # fromutc() implementation (called by the default astimezone()
+ # implementation) passes a datetime with dt.tzinfo is self.
+ return ZERO
+ assert dt.tzinfo is self
+
+ # Find first Sunday in April & the last in October.
+ start = first_sunday_on_or_after(DSTSTART.replace(year=dt.year))
+ end = first_sunday_on_or_after(DSTEND.replace(year=dt.year))
+
+ # Can't compare naive to aware objects, so strip the timezone from
+ # dt first.
+ if start <= dt.replace(tzinfo=None) < end:
+ return HOUR
+ else:
+ return ZERO
+
+Eastern = USTimeZone(-5, "Eastern", "EST", "EDT")
+Central = USTimeZone(-6, "Central", "CST", "CDT")
+Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
+Pacific = USTimeZone(-8, "Pacific", "PST", "PDT")
--- /dev/null
+.. highlightlang:: none
+
+.. _install-index:
+
+*****************************
+ Installing Python Modules
+*****************************
+
+:Author: Greg Ward
+:Release: |version|
+:Date: |today|
+
+.. % TODO:
+.. % Fill in XXX comments
+
+.. % The audience for this document includes people who don't know anything
+.. % about Python and aren't about to learn the language just in order to
+.. % install and maintain it for their users, i.e. system administrators.
+.. % Thus, I have to be sure to explain the basics at some point:
+.. % sys.path and PYTHONPATH at least. Should probably give pointers to
+.. % other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc.
+.. %
+.. % Finally, it might be useful to include all the material from my "Care
+.. % and Feeding of a Python Installation" talk in here somewhere. Yow!
+
+.. topic:: Abstract
+
+ This document describes the Python Distribution Utilities ("Distutils") from the
+ end-user's point-of-view, describing how to extend the capabilities of a
+ standard Python installation by building and installing third-party Python
+ modules and extensions.
+
+
+.. _inst-intro:
+
+Introduction
+============
+
+Although Python's extensive standard library covers many programming needs,
+there often comes a time when you need to add some new functionality to your
+Python installation in the form of third-party modules. This might be necessary
+to support your own programming, or to support an application that you want to
+use and that happens to be written in Python.
+
+In the past, there has been little support for adding third-party modules to an
+existing Python installation. With the introduction of the Python Distribution
+Utilities (Distutils for short) in Python 2.0, this changed.
+
+This document is aimed primarily at the people who need to install third-party
+Python modules: end-users and system administrators who just need to get some
+Python application running, and existing Python programmers who want to add some
+new goodies to their toolbox. You don't need to know Python to read this
+document; there will be some brief forays into using Python's interactive mode
+to explore your installation, but that's it. If you're looking for information
+on how to distribute your own Python modules so that others may use them, see
+the :ref:`distutils-index` manual.
+
+
+.. _inst-trivial-install:
+
+Best case: trivial installation
+-------------------------------
+
+In the best case, someone will have prepared a special version of the module
+distribution you want to install that is targeted specifically at your platform
+and is installed just like any other software on your platform. For example,
+the module developer might make an executable installer available for Windows
+users, an RPM package for users of RPM-based Linux systems (Red Hat, SuSE,
+Mandrake, and many others), a Debian package for users of Debian-based Linux
+systems, and so forth.
+
+In that case, you would download the installer appropriate to your platform and
+do the obvious thing with it: run it if it's an executable installer, ``rpm
+--install`` it if it's an RPM, etc. You don't need to run Python or a setup
+script, you don't need to compile anything---you might not even need to read any
+instructions (although it's always a good idea to do so anyways).
+
+Of course, things will not always be that easy. You might be interested in a
+module distribution that doesn't have an easy-to-use installer for your
+platform. In that case, you'll have to start with the source distribution
+released by the module's author/maintainer. Installing from a source
+distribution is not too hard, as long as the modules are packaged in the
+standard way. The bulk of this document is about building and installing
+modules from standard source distributions.
+
+
+.. _inst-new-standard:
+
+The new standard: Distutils
+---------------------------
+
+If you download a module source distribution, you can tell pretty quickly if it
+was packaged and distributed in the standard way, i.e. using the Distutils.
+First, the distribution's name and version number will be featured prominently
+in the name of the downloaded archive, e.g. :file:`foo-1.0.tar.gz` or
+:file:`widget-0.9.7.zip`. Next, the archive will unpack into a similarly-named
+directory: :file:`foo-1.0` or :file:`widget-0.9.7`. Additionally, the
+distribution will contain a setup script :file:`setup.py`, and a file named
+:file:`README.txt` or possibly just :file:`README`, which should explain that
+building and installing the module distribution is a simple matter of running ::
+
+ python setup.py install
+
+If all these things are true, then you already know how to build and install the
+modules you've just downloaded: Run the command above. Unless you need to
+install things in a non-standard way or customize the build process, you don't
+really need this manual. Or rather, the above command is everything you need to
+get out of this manual.
+
+
+.. _inst-standard-install:
+
+Standard Build and Install
+==========================
+
+As described in section :ref:`inst-new-standard`, building and installing a module
+distribution using the Distutils is usually one simple command::
+
+ python setup.py install
+
+On Unix, you'd run this command from a shell prompt; on Windows, you have to
+open a command prompt window ("DOS box") and do it there; on Mac OS X, you open
+a :command:`Terminal` window to get a shell prompt.
+
+
+.. _inst-platform-variations:
+
+Platform variations
+-------------------
+
+You should always run the setup command from the distribution root directory,
+i.e. the top-level subdirectory that the module source distribution unpacks
+into. For example, if you've just downloaded a module source distribution
+:file:`foo-1.0.tar.gz` onto a Unix system, the normal thing to do is::
+
+ gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0
+ cd foo-1.0
+ python setup.py install
+
+On Windows, you'd probably download :file:`foo-1.0.zip`. If you downloaded the
+archive file to :file:`C:\\Temp`, then it would unpack into
+:file:`C:\\Temp\\foo-1.0`; you can use either a archive manipulator with a
+graphical user interface (such as WinZip) or a command-line tool (such as
+:program:`unzip` or :program:`pkunzip`) to unpack the archive. Then, open a
+command prompt window ("DOS box"), and run::
+
+ cd c:\Temp\foo-1.0
+ python setup.py install
+
+
+.. _inst-splitting-up:
+
+Splitting the job up
+--------------------
+
+Running ``setup.py install`` builds and installs all modules in one run. If you
+prefer to work incrementally---especially useful if you want to customize the
+build process, or if things are going wrong---you can use the setup script to do
+one thing at a time. This is particularly helpful when the build and install
+will be done by different users---for example, you might want to build a module
+distribution and hand it off to a system administrator for installation (or do
+it yourself, with super-user privileges).
+
+For example, you can build everything in one step, and then install everything
+in a second step, by invoking the setup script twice::
+
+ python setup.py build
+ python setup.py install
+
+If you do this, you will notice that running the :command:`install` command
+first runs the :command:`build` command, which---in this case---quickly notices
+that it has nothing to do, since everything in the :file:`build` directory is
+up-to-date.
+
+You may not need this ability to break things down often if all you do is
+install modules downloaded off the 'net, but it's very handy for more advanced
+tasks. If you get into distributing your own Python modules and extensions,
+you'll run lots of individual Distutils commands on their own.
+
+
+.. _inst-how-build-works:
+
+How building works
+------------------
+
+As implied above, the :command:`build` command is responsible for putting the
+files to install into a *build directory*. By default, this is :file:`build`
+under the distribution root; if you're excessively concerned with speed, or want
+to keep the source tree pristine, you can change the build directory with the
+:option:`--build-base` option. For example::
+
+ python setup.py build --build-base=/tmp/pybuild/foo-1.0
+
+(Or you could do this permanently with a directive in your system or personal
+Distutils configuration file; see section :ref:`inst-config-files`.) Normally, this
+isn't necessary.
+
+The default layout for the build tree is as follows::
+
+ --- build/ --- lib/
+ or
+ --- build/ --- lib.<plat>/
+ temp.<plat>/
+
+where ``<plat>`` expands to a brief description of the current OS/hardware
+platform and Python version. The first form, with just a :file:`lib` directory,
+is used for "pure module distributions"---that is, module distributions that
+include only pure Python modules. If a module distribution contains any
+extensions (modules written in C/C++), then the second form, with two ``<plat>``
+directories, is used. In that case, the :file:`temp.{plat}` directory holds
+temporary files generated by the compile/link process that don't actually get
+installed. In either case, the :file:`lib` (or :file:`lib.{plat}`) directory
+contains all Python modules (pure Python and extensions) that will be installed.
+
+In the future, more directories will be added to handle Python scripts,
+documentation, binary executables, and whatever else is needed to handle the job
+of installing Python modules and applications.
+
+
+.. _inst-how-install-works:
+
+How installation works
+----------------------
+
+After the :command:`build` command runs (whether you run it explicitly, or the
+:command:`install` command does it for you), the work of the :command:`install`
+command is relatively simple: all it has to do is copy everything under
+:file:`build/lib` (or :file:`build/lib.{plat}`) to your chosen installation
+directory.
+
+If you don't choose an installation directory---i.e., if you just run ``setup.py
+install``\ ---then the :command:`install` command installs to the standard
+location for third-party Python modules. This location varies by platform and
+by how you built/installed Python itself. On Unix (and Mac OS X, which is also
+Unix-based), it also depends on whether the module distribution being installed
+is pure Python or contains extensions ("non-pure"):
+
++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
+| Platform | Standard installation location | Default value | Notes |
++=================+=====================================================+==================================================+=======+
+| Unix (pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) |
++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
+| Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) |
++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
+| Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) |
++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
+
+Notes:
+
+(1)
+ Most Linux distributions include Python as a standard part of the system, so
+ :file:`{prefix}` and :file:`{exec-prefix}` are usually both :file:`/usr` on
+ Linux. If you build Python yourself on Linux (or any Unix-like system), the
+ default :file:`{prefix}` and :file:`{exec-prefix}` are :file:`/usr/local`.
+
+(2)
+ The default installation directory on Windows was :file:`C:\\Program
+ Files\\Python` under Python 1.6a1, 1.5.2, and earlier.
+
+:file:`{prefix}` and :file:`{exec-prefix}` stand for the directories that Python
+is installed to, and where it finds its libraries at run-time. They are always
+the same under Windows, and very often the same under Unix and Mac OS X. You
+can find out what your Python installation uses for :file:`{prefix}` and
+:file:`{exec-prefix}` by running Python in interactive mode and typing a few
+simple commands. Under Unix, just type ``python`` at the shell prompt. Under
+Windows, choose :menuselection:`Start --> Programs --> Python X.Y -->
+Python (command line)`. Once the interpreter is started, you type Python code
+at the prompt. For example, on my Linux system, I type the three Python
+statements shown below, and get the output as shown, to find out my
+:file:`{prefix}` and :file:`{exec-prefix}`::
+
+ Python 2.4 (#26, Aug 7 2004, 17:19:02)
+ Type "help", "copyright", "credits" or "license" for more information.
+ >>> import sys
+ >>> sys.prefix
+ '/usr'
+ >>> sys.exec_prefix
+ '/usr'
+
+If you don't want to install modules to the standard location, or if you don't
+have permission to write there, then you need to read about alternate
+installations in section :ref:`inst-alt-install`. If you want to customize your
+installation directories more heavily, see section :ref:`inst-custom-install` on
+custom installations.
+
+
+.. _inst-alt-install:
+
+Alternate Installation
+======================
+
+Often, it is necessary or desirable to install modules to a location other than
+the standard location for third-party Python modules. For example, on a Unix
+system you might not have permission to write to the standard third-party module
+directory. Or you might wish to try out a module before making it a standard
+part of your local Python installation. This is especially true when upgrading
+a distribution already present: you want to make sure your existing base of
+scripts still works with the new version before actually upgrading.
+
+The Distutils :command:`install` command is designed to make installing module
+distributions to an alternate location simple and painless. The basic idea is
+that you supply a base directory for the installation, and the
+:command:`install` command picks a set of directories (called an *installation
+scheme*) under this base directory in which to install files. The details
+differ across platforms, so read whichever of the following sections applies to
+you.
+
+
+.. _inst-alt-install-prefix:
+
+Alternate installation: the home scheme
+---------------------------------------
+
+The idea behind the "home scheme" is that you build and maintain a personal
+stash of Python modules. This scheme's name is derived from the idea of a
+"home" directory on Unix, since it's not unusual for a Unix user to make their
+home directory have a layout similar to :file:`/usr/` or :file:`/usr/local/`.
+This scheme can be used by anyone, regardless of the operating system their
+installing for.
+
+Installing a new module distribution is as simple as ::
+
+ python setup.py install --home=<dir>
+
+where you can supply any directory you like for the :option:`--home` option. On
+Unix, lazy typists can just type a tilde (``~``); the :command:`install` command
+will expand this to your home directory::
+
+ python setup.py install --home=~
+
+The :option:`--home` option defines the installation base directory. Files are
+installed to the following directories under the installation base as follows:
+
++------------------------------+---------------------------+-----------------------------+
+| Type of file | Installation Directory | Override option |
++==============================+===========================+=============================+
+| pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` |
++------------------------------+---------------------------+-----------------------------+
+| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` |
++------------------------------+---------------------------+-----------------------------+
+| scripts | :file:`{home}/bin` | :option:`--install-scripts` |
++------------------------------+---------------------------+-----------------------------+
+| data | :file:`{home}/share` | :option:`--install-data` |
++------------------------------+---------------------------+-----------------------------+
+
+.. versionchanged:: 2.4
+ The :option:`--home` option used to be supported only on Unix.
+
+
+.. _inst-alt-install-home:
+
+Alternate installation: Unix (the prefix scheme)
+------------------------------------------------
+
+The "prefix scheme" is useful when you wish to use one Python installation to
+perform the build/install (i.e., to run the setup script), but install modules
+into the third-party module directory of a different Python installation (or
+something that looks like a different Python installation). If this sounds a
+trifle unusual, it is---that's why the "home scheme" comes first. However,
+there are at least two known cases where the prefix scheme will be useful.
+
+First, consider that many Linux distributions put Python in :file:`/usr`, rather
+than the more traditional :file:`/usr/local`. This is entirely appropriate,
+since in those cases Python is part of "the system" rather than a local add-on.
+However, if you are installing Python modules from source, you probably want
+them to go in :file:`/usr/local/lib/python2.{X}` rather than
+:file:`/usr/lib/python2.{X}`. This can be done with ::
+
+ /usr/bin/python setup.py install --prefix=/usr/local
+
+Another possibility is a network filesystem where the name used to write to a
+remote directory is different from the name used to read it: for example, the
+Python interpreter accessed as :file:`/usr/local/bin/python` might search for
+modules in :file:`/usr/local/lib/python2.{X}`, but those modules would have to
+be installed to, say, :file:`/mnt/{@server}/export/lib/python2.{X}`. This could
+be done with ::
+
+ /usr/local/bin/python setup.py install --prefix=/mnt/@server/export
+
+In either case, the :option:`--prefix` option defines the installation base, and
+the :option:`--exec-prefix` option defines the platform-specific installation
+base, which is used for platform-specific files. (Currently, this just means
+non-pure module distributions, but could be expanded to C libraries, binary
+executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to
+:option:`--prefix`. Files are installed as follows:
+
++------------------------------+-----------------------------------------------------+-----------------------------+
+| Type of file | Installation Directory | Override option |
++==============================+=====================================================+=============================+
+| pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` |
++------------------------------+-----------------------------------------------------+-----------------------------+
+| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` |
++------------------------------+-----------------------------------------------------+-----------------------------+
+| scripts | :file:`{prefix}/bin` | :option:`--install-scripts` |
++------------------------------+-----------------------------------------------------+-----------------------------+
+| data | :file:`{prefix}/share` | :option:`--install-data` |
++------------------------------+-----------------------------------------------------+-----------------------------+
+
+There is no requirement that :option:`--prefix` or :option:`--exec-prefix`
+actually point to an alternate Python installation; if the directories listed
+above do not already exist, they are created at installation time.
+
+Incidentally, the real reason the prefix scheme is important is simply that a
+standard Unix installation uses the prefix scheme, but with :option:`--prefix`
+and :option:`--exec-prefix` supplied by Python itself as ``sys.prefix`` and
+``sys.exec_prefix``. Thus, you might think you'll never use the prefix scheme,
+but every time you run ``python setup.py install`` without any other options,
+you're using it.
+
+Note that installing extensions to an alternate Python installation has no
+effect on how those extensions are built: in particular, the Python header files
+(:file:`Python.h` and friends) installed with the Python interpreter used to run
+the setup script will be used in compiling extensions. It is your
+responsibility to ensure that the interpreter used to run extensions installed
+in this way is compatible with the interpreter used to build them. The best way
+to do this is to ensure that the two interpreters are the same version of Python
+(possibly different builds, or possibly copies of the same build). (Of course,
+if your :option:`--prefix` and :option:`--exec-prefix` don't even point to an
+alternate Python installation, this is immaterial.)
+
+
+.. _inst-alt-install-windows:
+
+Alternate installation: Windows (the prefix scheme)
+---------------------------------------------------
+
+Windows has no concept of a user's home directory, and since the standard Python
+installation under Windows is simpler than under Unix, the :option:`--prefix`
+option has traditionally been used to install additional packages in separate
+locations on Windows. ::
+
+ python setup.py install --prefix="\Temp\Python"
+
+to install modules to the :file:`\\Temp\\Python` directory on the current drive.
+
+The installation base is defined by the :option:`--prefix` option; the
+:option:`--exec-prefix` option is not supported under Windows. Files are
+installed as follows:
+
++------------------------------+---------------------------+-----------------------------+
+| Type of file | Installation Directory | Override option |
++==============================+===========================+=============================+
+| pure module distribution | :file:`{prefix}` | :option:`--install-purelib` |
++------------------------------+---------------------------+-----------------------------+
+| non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` |
++------------------------------+---------------------------+-----------------------------+
+| scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` |
++------------------------------+---------------------------+-----------------------------+
+| data | :file:`{prefix}\\Data` | :option:`--install-data` |
++------------------------------+---------------------------+-----------------------------+
+
+
+.. _inst-custom-install:
+
+Custom Installation
+===================
+
+Sometimes, the alternate installation schemes described in section
+:ref:`inst-alt-install` just don't do what you want. You might want to tweak just
+one or two directories while keeping everything under the same base directory,
+or you might want to completely redefine the installation scheme. In either
+case, you're creating a *custom installation scheme*.
+
+You probably noticed the column of "override options" in the tables describing
+the alternate installation schemes above. Those options are how you define a
+custom installation scheme. These override options can be relative, absolute,
+or explicitly defined in terms of one of the installation base directories.
+(There are two installation base directories, and they are normally the same---
+they only differ when you use the Unix "prefix scheme" and supply different
+:option:`--prefix` and :option:`--exec-prefix` options.)
+
+For example, say you're installing a module distribution to your home directory
+under Unix---but you want scripts to go in :file:`~/scripts` rather than
+:file:`~/bin`. As you might expect, you can override this directory with the
+:option:`--install-scripts` option; in this case, it makes most sense to supply
+a relative path, which will be interpreted relative to the installation base
+directory (your home directory, in this case)::
+
+ python setup.py install --home=~ --install-scripts=scripts
+
+Another Unix example: suppose your Python installation was built and installed
+with a prefix of :file:`/usr/local/python`, so under a standard installation
+scripts will wind up in :file:`/usr/local/python/bin`. If you want them in
+:file:`/usr/local/bin` instead, you would supply this absolute directory for the
+:option:`--install-scripts` option::
+
+ python setup.py install --install-scripts=/usr/local/bin
+
+(This performs an installation using the "prefix scheme," where the prefix is
+whatever your Python interpreter was installed with--- :file:`/usr/local/python`
+in this case.)
+
+If you maintain Python on Windows, you might want third-party modules to live in
+a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}`
+itself. This is almost as easy as customizing the script installation directory
+---you just have to remember that there are two types of modules to worry about,
+pure modules and non-pure modules (i.e., modules from a non-pure distribution).
+For example::
+
+ python setup.py install --install-purelib=Site --install-platlib=Site
+
+The specified installation directories are relative to :file:`{prefix}`. Of
+course, you also have to ensure that these directories are in Python's module
+search path, such as by putting a :file:`.pth` file in :file:`{prefix}`. See
+section :ref:`inst-search-path` to find out how to modify Python's search path.
+
+If you want to define an entire installation scheme, you just have to supply all
+of the installation directory options. The recommended way to do this is to
+supply relative paths; for example, if you want to maintain all Python
+module-related files under :file:`python` in your home directory, and you want a
+separate directory for each platform that you use your home directory from, you
+might define the following installation scheme::
+
+ python setup.py install --home=~ \
+ --install-purelib=python/lib \
+ --install-platlib=python/lib.$PLAT \
+ --install-scripts=python/scripts
+ --install-data=python/data
+
+or, equivalently,
+
+.. % $ % -- bow to font-lock
+
+::
+
+ python setup.py install --home=~/python \
+ --install-purelib=lib \
+ --install-platlib='lib.$PLAT' \
+ --install-scripts=scripts
+ --install-data=data
+
+``$PLAT`` is not (necessarily) an environment variable---it will be expanded by
+the Distutils as it parses your command line options, just as it does when
+parsing your configuration file(s).
+
+.. % $ % -- bow to font-lock
+
+Obviously, specifying the entire installation scheme every time you install a
+new module distribution would be very tedious. Thus, you can put these options
+into your Distutils config file (see section :ref:`inst-config-files`)::
+
+ [install]
+ install-base=$HOME
+ install-purelib=python/lib
+ install-platlib=python/lib.$PLAT
+ install-scripts=python/scripts
+ install-data=python/data
+
+or, equivalently, ::
+
+ [install]
+ install-base=$HOME/python
+ install-purelib=lib
+ install-platlib=lib.$PLAT
+ install-scripts=scripts
+ install-data=data
+
+Note that these two are *not* equivalent if you supply a different installation
+base directory when you run the setup script. For example, ::
+
+ python setup.py install --install-base=/tmp
+
+would install pure modules to :file:`{/tmp/python/lib}` in the first case, and
+to :file:`{/tmp/lib}` in the second case. (For the second case, you probably
+want to supply an installation base of :file:`/tmp/python`.)
+
+You probably noticed the use of ``$HOME`` and ``$PLAT`` in the sample
+configuration file input. These are Distutils configuration variables, which
+bear a strong resemblance to environment variables. In fact, you can use
+environment variables in config files on platforms that have such a notion but
+the Distutils additionally define a few extra variables that may not be in your
+environment, such as ``$PLAT``. (And of course, on systems that don't have
+environment variables, such as Mac OS 9, the configuration variables supplied by
+the Distutils are the only ones you can use.) See section :ref:`inst-config-files`
+for details.
+
+.. % XXX need some Windows examples---when would custom
+.. % installation schemes be needed on those platforms?
+
+.. % XXX I'm not sure where this section should go.
+
+
+.. _inst-search-path:
+
+Modifying Python's Search Path
+------------------------------
+
+When the Python interpreter executes an :keyword:`import` statement, it searches
+for both Python code and extension modules along a search path. A default value
+for the path is configured into the Python binary when the interpreter is built.
+You can determine the path by importing the :mod:`sys` module and printing the
+value of ``sys.path``. ::
+
+ $ python
+ Python 2.2 (#11, Oct 3 2002, 13:31:27)
+ [GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
+ Type ``help'', ``copyright'', ``credits'' or ``license'' for more information.
+ >>> import sys
+ >>> sys.path
+ ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
+ '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
+ '/usr/local/lib/python2.3/site-packages']
+ >>>
+
+The null string in ``sys.path`` represents the current working directory.
+
+.. % $ <-- bow to font-lock
+
+The expected convention for locally installed packages is to put them in the
+:file:`{...}/site-packages/` directory, but you may want to install Python
+modules into some arbitrary directory. For example, your site may have a
+convention of keeping all software related to the web server under :file:`/www`.
+Add-on Python modules might then belong in :file:`/www/python`, and in order to
+import them, this directory must be added to ``sys.path``. There are several
+different ways to add the directory.
+
+The most convenient way is to add a path configuration file to a directory
+that's already on Python's path, usually to the :file:`.../site-packages/`
+directory. Path configuration files have an extension of :file:`.pth`, and each
+line must contain a single path that will be appended to ``sys.path``. (Because
+the new paths are appended to ``sys.path``, modules in the added directories
+will not override standard modules. This means you can't use this mechanism for
+installing fixed versions of standard modules.)
+
+Paths can be absolute or relative, in which case they're relative to the
+directory containing the :file:`.pth` file. Any directories added to the search
+path will be scanned in turn for :file:`.pth` files. See `site module
+documentation <http://www.python.org/dev/doc/devel/lib/module-site.html>`_ for
+more information.
+
+A slightly less convenient way is to edit the :file:`site.py` file in Python's
+standard library, and modify ``sys.path``. :file:`site.py` is automatically
+imported when the Python interpreter is executed, unless the :option:`-S` switch
+is supplied to suppress this behaviour. So you could simply edit
+:file:`site.py` and add two lines to it::
+
+ import sys
+ sys.path.append('/www/python/')
+
+However, if you reinstall the same major version of Python (perhaps when
+upgrading from 2.2 to 2.2.2, for example) :file:`site.py` will be overwritten by
+the stock version. You'd have to remember that it was modified and save a copy
+before doing the installation.
+
+There are two environment variables that can modify ``sys.path``.
+:envvar:`PYTHONHOME` sets an alternate value for the prefix of the Python
+installation. For example, if :envvar:`PYTHONHOME` is set to ``/www/python``,
+the search path will be set to ``['', '/www/python/lib/pythonX.Y/',
+'/www/python/lib/pythonX.Y/plat-linux2', ...]``.
+
+The :envvar:`PYTHONPATH` variable can be set to a list of paths that will be
+added to the beginning of ``sys.path``. For example, if :envvar:`PYTHONPATH` is
+set to ``/www/python:/opt/py``, the search path will begin with
+``['/www/python', '/opt/py']``. (Note that directories must exist in order to
+be added to ``sys.path``; the :mod:`site` module removes paths that don't
+exist.)
+
+Finally, ``sys.path`` is just a regular Python list, so any Python application
+can modify it by adding or removing entries.
+
+
+.. _inst-config-files:
+
+Distutils Configuration Files
+=============================
+
+As mentioned above, you can use Distutils configuration files to record personal
+or site preferences for any Distutils options. That is, any option to any
+command can be stored in one of two or three (depending on your platform)
+configuration files, which will be consulted before the command-line is parsed.
+This means that configuration files will override default values, and the
+command-line will in turn override configuration files. Furthermore, if
+multiple configuration files apply, values from "earlier" files are overridden
+by "later" files.
+
+
+.. _inst-config-filenames:
+
+Location and names of config files
+----------------------------------
+
+The names and locations of the configuration files vary slightly across
+platforms. On Unix and Mac OS X, the three configuration files (in the order
+they are processed) are:
+
++--------------+----------------------------------------------------------+-------+
+| Type of file | Location and filename | Notes |
++==============+==========================================================+=======+
+| system | :file:`{prefix}/lib/python{ver}/distutils/distutils.cfg` | \(1) |
++--------------+----------------------------------------------------------+-------+
+| personal | :file:`$HOME/.pydistutils.cfg` | \(2) |
++--------------+----------------------------------------------------------+-------+
+| local | :file:`setup.cfg` | \(3) |
++--------------+----------------------------------------------------------+-------+
+
+And on Windows, the configuration files are:
+
++--------------+-------------------------------------------------+-------+
+| Type of file | Location and filename | Notes |
++==============+=================================================+=======+
+| system | :file:`{prefix}\\Lib\\distutils\\distutils.cfg` | \(4) |
++--------------+-------------------------------------------------+-------+
+| personal | :file:`%HOME%\\pydistutils.cfg` | \(5) |
++--------------+-------------------------------------------------+-------+
+| local | :file:`setup.cfg` | \(3) |
++--------------+-------------------------------------------------+-------+
+
+Notes:
+
+(1)
+ Strictly speaking, the system-wide configuration file lives in the directory
+ where the Distutils are installed; under Python 1.6 and later on Unix, this is
+ as shown. For Python 1.5.2, the Distutils will normally be installed to
+ :file:`{prefix}/lib/python1.5/site-packages/distutils`, so the system
+ configuration file should be put there under Python 1.5.2.
+
+(2)
+ On Unix, if the :envvar:`HOME` environment variable is not defined, the user's
+ home directory will be determined with the :func:`getpwuid` function from the
+ standard :mod:`pwd` module.
+
+(3)
+ I.e., in the current directory (usually the location of the setup script).
+
+(4)
+ (See also note (1).) Under Python 1.6 and later, Python's default "installation
+ prefix" is :file:`C:\\Python`, so the system configuration file is normally
+ :file:`C:\\Python\\Lib\\distutils\\distutils.cfg`. Under Python 1.5.2, the
+ default prefix was :file:`C:\\Program Files\\Python`, and the Distutils were not
+ part of the standard library---so the system configuration file would be
+ :file:`C:\\Program Files\\Python\\distutils\\distutils.cfg` in a standard Python
+ 1.5.2 installation under Windows.
+
+(5)
+ On Windows, if the :envvar:`HOME` environment variable is not defined, no
+ personal configuration file will be found or used. (In other words, the
+ Distutils make no attempt to guess your home directory on Windows.)
+
+
+.. _inst-config-syntax:
+
+Syntax of config files
+----------------------
+
+The Distutils configuration files all have the same syntax. The config files
+are grouped into sections. There is one section for each Distutils command,
+plus a ``global`` section for global options that affect every command. Each
+section consists of one option per line, specified as ``option=value``.
+
+For example, the following is a complete config file that just forces all
+commands to run quietly by default::
+
+ [global]
+ verbose=0
+
+If this is installed as the system config file, it will affect all processing of
+any Python module distribution by any user on the current system. If it is
+installed as your personal config file (on systems that support them), it will
+affect only module distributions processed by you. And if it is used as the
+:file:`setup.cfg` for a particular module distribution, it affects only that
+distribution.
+
+You could override the default "build base" directory and make the
+:command:`build\*` commands always forcibly rebuild all files with the
+following::
+
+ [build]
+ build-base=blib
+ force=1
+
+which corresponds to the command-line arguments ::
+
+ python setup.py build --build-base=blib --force
+
+except that including the :command:`build` command on the command-line means
+that command will be run. Including a particular command in config files has no
+such implication; it only means that if the command is run, the options in the
+config file will apply. (Or if other commands that derive values from it are
+run, they will use the values in the config file.)
+
+You can find out the complete list of options for any command using the
+:option:`--help` option, e.g.::
+
+ python setup.py build --help
+
+and you can find out the complete list of global options by using
+:option:`--help` without a command::
+
+ python setup.py --help
+
+See also the "Reference" section of the "Distributing Python Modules" manual.
+
+
+.. _inst-building-ext:
+
+Building Extensions: Tips and Tricks
+====================================
+
+Whenever possible, the Distutils try to use the configuration information made
+available by the Python interpreter used to run the :file:`setup.py` script.
+For example, the same compiler and linker flags used to compile Python will also
+be used for compiling extensions. Usually this will work well, but in
+complicated situations this might be inappropriate. This section discusses how
+to override the usual Distutils behaviour.
+
+
+.. _inst-tweak-flags:
+
+Tweaking compiler/linker flags
+------------------------------
+
+Compiling a Python extension written in C or C++ will sometimes require
+specifying custom flags for the compiler and linker in order to use a particular
+library or produce a special kind of object code. This is especially true if the
+extension hasn't been tested on your platform, or if you're trying to
+cross-compile Python.
+
+In the most general case, the extension author might have foreseen that
+compiling the extensions would be complicated, and provided a :file:`Setup` file
+for you to edit. This will likely only be done if the module distribution
+contains many separate extension modules, or if they often require elaborate
+sets of compiler flags in order to work.
+
+A :file:`Setup` file, if present, is parsed in order to get a list of extensions
+to build. Each line in a :file:`Setup` describes a single module. Lines have
+the following structure::
+
+ module ... [sourcefile ...] [cpparg ...] [library ...]
+
+
+Let's examine each of the fields in turn.
+
+* *module* is the name of the extension module to be built, and should be a
+ valid Python identifier. You can't just change this in order to rename a module
+ (edits to the source code would also be needed), so this should be left alone.
+
+* *sourcefile* is anything that's likely to be a source code file, at least
+ judging by the filename. Filenames ending in :file:`.c` are assumed to be
+ written in C, filenames ending in :file:`.C`, :file:`.cc`, and :file:`.c++` are
+ assumed to be C++, and filenames ending in :file:`.m` or :file:`.mm` are assumed
+ to be in Objective C.
+
+* *cpparg* is an argument for the C preprocessor, and is anything starting with
+ :option:`-I`, :option:`-D`, :option:`-U` or :option:`-C`.
+
+* *library* is anything ending in :file:`.a` or beginning with :option:`-l` or
+ :option:`-L`.
+
+If a particular platform requires a special library on your platform, you can
+add it by editing the :file:`Setup` file and running ``python setup.py build``.
+For example, if the module defined by the line ::
+
+ foo foomodule.c
+
+must be linked with the math library :file:`libm.a` on your platform, simply add
+:option:`-lm` to the line::
+
+ foo foomodule.c -lm
+
+Arbitrary switches intended for the compiler or the linker can be supplied with
+the :option:`-Xcompiler` *arg* and :option:`-Xlinker` *arg* options::
+
+ foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
+
+The next option after :option:`-Xcompiler` and :option:`-Xlinker` will be
+appended to the proper command line, so in the above example the compiler will
+be passed the :option:`-o32` option, and the linker will be passed
+:option:`-shared`. If a compiler option requires an argument, you'll have to
+supply multiple :option:`-Xcompiler` options; for example, to pass ``-x c++``
+the :file:`Setup` file would have to contain ``-Xcompiler -x -Xcompiler c++``.
+
+Compiler flags can also be supplied through setting the :envvar:`CFLAGS`
+environment variable. If set, the contents of :envvar:`CFLAGS` will be added to
+the compiler flags specified in the :file:`Setup` file.
+
+
+.. _inst-non-ms-compilers:
+
+Using non-Microsoft compilers on Windows
+----------------------------------------
+
+.. sectionauthor:: Rene Liebscher <R.Liebscher@gmx.de>
+
+
+
+Borland C++
+^^^^^^^^^^^
+
+This subsection describes the necessary steps to use Distutils with the Borland
+C++ compiler version 5.5. First you have to know that Borland's object file
+format (OMF) is different from the format used by the Python version you can
+download from the Python or ActiveState Web site. (Python is built with
+Microsoft Visual C++, which uses COFF as the object file format.) For this
+reason you have to convert Python's library :file:`python25.lib` into the
+Borland format. You can do this as follows:
+
+.. % Should we mention that users have to create cfg-files for the compiler?
+.. % see also http://community.borland.com/article/0,1410,21205,00.html
+
+::
+
+ coff2omf python25.lib python25_bcpp.lib
+
+The :file:`coff2omf` program comes with the Borland compiler. The file
+:file:`python25.lib` is in the :file:`Libs` directory of your Python
+installation. If your extension uses other libraries (zlib, ...) you have to
+convert them too.
+
+The converted files have to reside in the same directories as the normal
+libraries.
+
+How does Distutils manage to use these libraries with their changed names? If
+the extension needs a library (eg. :file:`foo`) Distutils checks first if it
+finds a library with suffix :file:`_bcpp` (eg. :file:`foo_bcpp.lib`) and then
+uses this library. In the case it doesn't find such a special library it uses
+the default name (:file:`foo.lib`.) [#]_
+
+To let Distutils compile your extension with Borland C++ you now have to type::
+
+ python setup.py build --compiler=bcpp
+
+If you want to use the Borland C++ compiler as the default, you could specify
+this in your personal or system-wide configuration file for Distutils (see
+section :ref:`inst-config-files`.)
+
+
+.. seealso::
+
+ `C++Builder Compiler <http://www.borland.com/bcppbuilder/freecompiler/>`_
+ Information about the free C++ compiler from Borland, including links to the
+ download pages.
+
+ `Creating Python Extensions Using Borland's Free Compiler <http://www.cyberus.ca/~g_will/pyExtenDL.shtml>`_
+ Document describing how to use Borland's free command-line C++ compiler to build
+ Python.
+
+
+GNU C / Cygwin / MinGW
+^^^^^^^^^^^^^^^^^^^^^^
+
+These instructions only apply if you're using a version of Python prior to
+2.4.1 with a MinGW prior to 3.0.0 (with binutils-2.13.90-20030111-1).
+
+This section describes the necessary steps to use Distutils with the GNU C/C++
+compilers in their Cygwin and MinGW distributions. [#]_ For a Python interpreter
+that was built with Cygwin, everything should work without any of these
+following steps.
+
+These compilers require some special libraries. This task is more complex than
+for Borland's C++, because there is no program to convert the library. First
+you have to create a list of symbols which the Python DLL exports. (You can find
+a good program for this task at
+http://starship.python.net/crew/kernr/mingw32/Notes.html, see at PExports 0.42h
+there.)
+
+.. % I don't understand what the next line means. --amk
+.. % (inclusive the references on data structures.)
+
+::
+
+ pexports python25.dll >python25.def
+
+The location of an installed :file:`python25.dll` will depend on the
+installation options and the version and language of Windows. In a "just for
+me" installation, it will appear in the root of the installation directory. In
+a shared installation, it will be located in the system directory.
+
+Then you can create from these information an import library for gcc. ::
+
+ /cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a
+
+The resulting library has to be placed in the same directory as
+:file:`python25.lib`. (Should be the :file:`libs` directory under your Python
+installation directory.)
+
+If your extension uses other libraries (zlib,...) you might have to convert
+them too. The converted files have to reside in the same directories as the
+normal libraries do.
+
+To let Distutils compile your extension with Cygwin you now have to type ::
+
+ python setup.py build --compiler=cygwin
+
+and for Cygwin in no-cygwin mode [#]_ or for MinGW type::
+
+ python setup.py build --compiler=mingw32
+
+If you want to use any of these options/compilers as default, you should
+consider to write it in your personal or system-wide configuration file for
+Distutils (see section :ref:`inst-config-files`.)
+
+
+.. seealso::
+
+ `Building Python modules on MS Windows platform with MinGW <http://www.zope.org/Members/als/tips/win32_mingw_modules>`_
+ Information about building the required libraries for the MinGW environment.
+
+ http://pyopengl.sourceforge.net/ftp/win32-stuff/
+ Converted import libraries in Cygwin/MinGW and Borland format, and a script to
+ create the registry entries needed for Distutils to locate the built Python.
+
+.. rubric:: Footnotes
+
+.. [#] This also means you could replace all existing COFF-libraries with OMF-libraries
+ of the same name.
+
+.. [#] Check http://sources.redhat.com/cygwin/ and http://www.mingw.org/ for more
+ information
+
+.. [#] Then you have no POSIX emulation available, but you also don't need
+ :file:`cygwin1.dll`.
--- /dev/null
+
+:mod:`__builtin__` --- Built-in objects
+=======================================
+
+.. module:: __builtin__
+ :synopsis: The module that provides the built-in namespace.
+
+
+This module provides direct access to all 'built-in' identifiers of Python; for
+example, ``__builtin__.open`` is the full name for the built-in function
+:func:`open`. See chapter :ref:`builtin`.
+
+This module is not normally accessed explicitly by most applications, but can be
+useful in modules that provide objects with the same name as a built-in value,
+but in which the built-in of that name is also needed. For example, in a module
+that wants to implement an :func:`open` function that wraps the built-in
+:func:`open`, this module can be used directly::
+
+ import __builtin__
+
+ def open(path):
+ f = __builtin__.open(path, 'r')
+ return UpperCaser(f)
+
+ class UpperCaser:
+ '''Wrapper around a file that converts output to upper-case.'''
+
+ def __init__(self, f):
+ self._f = f
+
+ def read(self, count=-1):
+ return self._f.read(count).upper()
+
+ # ...
+
+As an implementation detail, most modules have the name ``__builtins__`` (note
+the ``'s'``) made available as part of their globals. The value of
+``__builtins__`` is normally either this module or the value of this modules's
+:attr:`__dict__` attribute. Since this is an implementation detail, it may not
+be used by alternate implementations of Python.
+
--- /dev/null
+
+:mod:`__future__` --- Future statement definitions
+==================================================
+
+.. module:: __future__
+ :synopsis: Future statement definitions
+
+
+:mod:`__future__` is a real module, and serves three purposes:
+
+* To avoid confusing existing tools that analyze import statements and expect to
+ find the modules they're importing.
+
+* To ensure that future_statements run under releases prior to 2.1 at least
+ yield runtime exceptions (the import of :mod:`__future__` will fail, because
+ there was no module of that name prior to 2.1).
+
+* To document when incompatible changes were introduced, and when they will be
+ --- or were --- made mandatory. This is a form of executable documentation, and
+ can be inspected programatically via importing :mod:`__future__` and examining
+ its contents.
+
+Each statement in :file:`__future__.py` is of the form::
+
+ FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ","
+ CompilerFlag ")"
+
+
+where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are
+5-tuples of the same form as ``sys.version_info``::
+
+ (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
+ PY_MINOR_VERSION, # the 1; an int
+ PY_MICRO_VERSION, # the 0; an int
+ PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
+ PY_RELEASE_SERIAL # the 3; an int
+ )
+
+*OptionalRelease* records the first release in which the feature was accepted.
+
+In the case of a *MandatoryRelease* that has not yet occurred,
+*MandatoryRelease* predicts the release in which the feature will become part of
+the language.
+
+Else *MandatoryRelease* records when the feature became part of the language; in
+releases at or after that, modules no longer need a future statement to use the
+feature in question, but may continue to use such imports.
+
+*MandatoryRelease* may also be ``None``, meaning that a planned feature got
+dropped.
+
+Instances of class :class:`_Feature` have two corresponding methods,
+:meth:`getOptionalRelease` and :meth:`getMandatoryRelease`.
+
+*CompilerFlag* is the (bitfield) flag that should be passed in the fourth
+argument to the builtin function :func:`compile` to enable the feature in
+dynamically compiled code. This flag is stored in the :attr:`compiler_flag`
+attribute on :class:`_Feature` instances.
+
+No feature description will ever be deleted from :mod:`__future__`.
+
--- /dev/null
+
+:mod:`__main__` --- Top-level script environment
+================================================
+
+.. module:: __main__
+ :synopsis: The environment where the top-level script is run.
+
+
+This module represents the (otherwise anonymous) scope in which the
+interpreter's main program executes --- commands read either from standard
+input, from a script file, or from an interactive prompt. It is this
+environment in which the idiomatic "conditional script" stanza causes a script
+to run::
+
+ if __name__ == "__main__":
+ main()
+
--- /dev/null
+.. _ast:
+
+Abstract Syntax Trees
+=====================
+
+.. module:: _ast
+ :synopsis: Abstract Syntax Tree classes.
+
+.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
+
+
+.. versionadded:: 2.5
+
+The ``_ast`` module helps Python applications to process trees of the Python
+abstract syntax grammar. The Python compiler currently provides read-only access
+to such trees, meaning that applications can only create a tree for a given
+piece of Python source code; generating byte code from a (potentially modified)
+tree is not supported. The abstract syntax itself might change with each Python
+release; this module helps to find out programmatically what the current grammar
+looks like.
+
+An abstract syntax tree can be generated by passing ``_ast.PyCF_ONLY_AST`` as a
+flag to the :func:`compile` builtin function. The result will be a tree of
+objects whose classes all inherit from ``_ast.AST``.
+
+The actual classes are derived from the ``Parser/Python.asdl`` file, which is
+reproduced below. There is one class defined for each left-hand side symbol in
+the abstract grammar (for example, ``_ast.stmt`` or ``_ast.expr``). In addition,
+there is one class defined for each constructor on the right-hand side; these
+classes inherit from the classes for the left-hand side trees. For example,
+``_ast.BinOp`` inherits from ``_ast.expr``. For production rules with
+alternatives (aka "sums"), the left-hand side class is abstract: only instances
+of specific constructor nodes are ever created.
+
+Each concrete class has an attribute ``_fields`` which gives the names of all
+child nodes.
+
+Each instance of a concrete class has one attribute for each child node, of the
+type as defined in the grammar. For example, ``_ast.BinOp`` instances have an
+attribute ``left`` of type ``_ast.expr``. Instances of ``_ast.expr`` and
+``_ast.stmt`` subclasses also have lineno and col_offset attributes. The lineno
+is the line number of source text (1 indexed so the first line is line 1) and
+the col_offset is the utf8 byte offset of the first token that generated the
+node. The utf8 offset is recorded because the parser uses utf8 internally.
+
+If these attributes are marked as optional in the grammar (using a question
+mark), the value might be ``None``. If the attributes can have zero-or-more
+values (marked with an asterisk), the values are represented as Python lists.
+
+
+Abstract Grammar
+----------------
+
+The module defines a string constant ``__version__`` which is the decimal
+subversion revision number of the file shown below.
+
+The abstract grammar is currently defined as follows:
+
+.. literalinclude:: ../../Parser/Python.asdl
--- /dev/null
+
+:mod:`_winreg` -- Windows registry access
+=========================================
+
+.. module:: _winreg
+ :platform: Windows
+ :synopsis: Routines and objects for manipulating the Windows registry.
+.. sectionauthor:: Mark Hammond <MarkH@ActiveState.com>
+
+
+.. versionadded:: 2.0
+
+These functions expose the Windows registry API to Python. Instead of using an
+integer as the registry handle, a handle object is used to ensure that the
+handles are closed correctly, even if the programmer neglects to explicitly
+close them.
+
+This module exposes a very low-level interface to the Windows registry; it is
+expected that in the future a new ``winreg`` module will be created offering a
+higher-level interface to the registry API.
+
+This module offers the following functions:
+
+
+.. function:: CloseKey(hkey)
+
+ Closes a previously opened registry key. The hkey argument specifies a
+ previously opened key.
+
+ Note that if *hkey* is not closed using this method (or via
+ :meth:`handle.Close`), it is closed when the *hkey* object is destroyed by
+ Python.
+
+
+.. function:: ConnectRegistry(computer_name, key)
+
+ Establishes a connection to a predefined registry handle on another computer,
+ and returns a :dfn:`handle object`
+
+ *computer_name* is the name of the remote computer, of the form
+ ``r"\\computername"``. If ``None``, the local computer is used.
+
+ *key* is the predefined handle to connect to.
+
+ The return value is the handle of the opened key. If the function fails, an
+ :exc:`EnvironmentError` exception is raised.
+
+
+.. function:: CreateKey(key, sub_key)
+
+ Creates or opens the specified key, returning a :dfn:`handle object`
+
+ *key* is an already open key, or one of the predefined :const:`HKEY_\*`
+ constants.
+
+ *sub_key* is a string that names the key this method opens or creates.
+
+ If *key* is one of the predefined keys, *sub_key* may be ``None``. In that
+ case, the handle returned is the same key handle passed in to the function.
+
+ If the key already exists, this function opens the existing key.
+
+ The return value is the handle of the opened key. If the function fails, an
+ :exc:`EnvironmentError` exception is raised.
+
+
+.. function:: DeleteKey(key, sub_key)
+
+ Deletes the specified key.
+
+ *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
+ constants.
+
+ *sub_key* is a string that must be a subkey of the key identified by the *key*
+ parameter. This value must not be ``None``, and the key may not have subkeys.
+
+ *This method can not delete keys with subkeys.*
+
+ If the method succeeds, the entire key, including all of its values, is removed.
+ If the method fails, an :exc:`EnvironmentError` exception is raised.
+
+
+.. function:: DeleteValue(key, value)
+
+ Removes a named value from a registry key.
+
+ *key* is an already open key, or one of the predefined :const:`HKEY_\*`
+ constants.
+
+ *value* is a string that identifies the value to remove.
+
+
+.. function:: EnumKey(key, index)
+
+ Enumerates subkeys of an open registry key, returning a string.
+
+ *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
+ constants.
+
+ *index* is an integer that identifies the index of the key to retrieve.
+
+ The function retrieves the name of one subkey each time it is called. It is
+ typically called repeatedly until an :exc:`EnvironmentError` exception is
+ raised, indicating, no more values are available.
+
+
+.. function:: EnumValue(key, index)
+
+ Enumerates values of an open registry key, returning a tuple.
+
+ *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
+ constants.
+
+ *index* is an integer that identifies the index of the value to retrieve.
+
+ The function retrieves the name of one subkey each time it is called. It is
+ typically called repeatedly, until an :exc:`EnvironmentError` exception is
+ raised, indicating no more values.
+
+ The result is a tuple of 3 items:
+
+ +-------+--------------------------------------------+
+ | Index | Meaning |
+ +=======+============================================+
+ | ``0`` | A string that identifies the value name |
+ +-------+--------------------------------------------+
+ | ``1`` | An object that holds the value data, and |
+ | | whose type depends on the underlying |
+ | | registry type |
+ +-------+--------------------------------------------+
+ | ``2`` | An integer that identifies the type of the |
+ | | value data |
+ +-------+--------------------------------------------+
+
+
+.. function:: FlushKey(key)
+
+ Writes all the attributes of a key to the registry.
+
+ *key* is an already open key, or one of the predefined :const:`HKEY_\*`
+ constants.
+
+ It is not necessary to call RegFlushKey to change a key. Registry changes are
+ flushed to disk by the registry using its lazy flusher. Registry changes are
+ also flushed to disk at system shutdown. Unlike :func:`CloseKey`, the
+ :func:`FlushKey` method returns only when all the data has been written to the
+ registry. An application should only call :func:`FlushKey` if it requires
+ absolute certainty that registry changes are on disk.
+
+ .. note::
+
+ If you don't know whether a :func:`FlushKey` call is required, it probably
+ isn't.
+
+
+.. function:: RegLoadKey(key, sub_key, file_name)
+
+ Creates a subkey under the specified key and stores registration information
+ from a specified file into that subkey.
+
+ *key* is an already open key, or any of the predefined :const:`HKEY_\*`
+ constants.
+
+ *sub_key* is a string that identifies the sub_key to load.
+
+ *file_name* is the name of the file to load registry data from. This file must
+ have been created with the :func:`SaveKey` function. Under the file allocation
+ table (FAT) file system, the filename may not have an extension.
+
+ A call to LoadKey() fails if the calling process does not have the
+ :const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different than
+ permissions - see the Win32 documentation for more details.
+
+ If *key* is a handle returned by :func:`ConnectRegistry`, then the path
+ specified in *fileName* is relative to the remote computer.
+
+ The Win32 documentation implies *key* must be in the :const:`HKEY_USER` or
+ :const:`HKEY_LOCAL_MACHINE` tree. This may or may not be true.
+
+
+.. function:: OpenKey(key, sub_key[, res=0][, sam=KEY_READ])
+
+ Opens the specified key, returning a :dfn:`handle object`
+
+ *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
+ constants.
+
+ *sub_key* is a string that identifies the sub_key to open.
+
+ *res* is a reserved integer, and must be zero. The default is zero.
+
+ *sam* is an integer that specifies an access mask that describes the desired
+ security access for the key. Default is :const:`KEY_READ`
+
+ The result is a new handle to the specified key.
+
+ If the function fails, :exc:`EnvironmentError` is raised.
+
+
+.. function:: OpenKeyEx()
+
+ The functionality of :func:`OpenKeyEx` is provided via :func:`OpenKey`, by the
+ use of default arguments.
+
+
+.. function:: QueryInfoKey(key)
+
+ Returns information about a key, as a tuple.
+
+ *key* is an already open key, or one of the predefined :const:`HKEY_\*`
+ constants.
+
+ The result is a tuple of 3 items:
+
+ +-------+---------------------------------------------+
+ | Index | Meaning |
+ +=======+=============================================+
+ | ``0`` | An integer giving the number of sub keys |
+ | | this key has. |
+ +-------+---------------------------------------------+
+ | ``1`` | An integer giving the number of values this |
+ | | key has. |
+ +-------+---------------------------------------------+
+ | ``2`` | A long integer giving when the key was last |
+ | | modified (if available) as 100's of |
+ | | nanoseconds since Jan 1, 1600. |
+ +-------+---------------------------------------------+
+
+
+.. function:: QueryValue(key, sub_key)
+
+ Retrieves the unnamed value for a key, as a string
+
+ *key* is an already open key, or one of the predefined :const:`HKEY_\*`
+ constants.
+
+ *sub_key* is a string that holds the name of the subkey with which the value is
+ associated. If this parameter is ``None`` or empty, the function retrieves the
+ value set by the :func:`SetValue` method for the key identified by *key*.
+
+ Values in the registry have name, type, and data components. This method
+ retrieves the data for a key's first value that has a NULL name. But the
+ underlying API call doesn't return the type, Lame Lame Lame, DO NOT USE THIS!!!
+
+
+.. function:: QueryValueEx(key, value_name)
+
+ Retrieves the type and data for a specified value name associated with an open
+ registry key.
+
+ *key* is an already open key, or one of the predefined :const:`HKEY_\*`
+ constants.
+
+ *value_name* is a string indicating the value to query.
+
+ The result is a tuple of 2 items:
+
+ +-------+-----------------------------------------+
+ | Index | Meaning |
+ +=======+=========================================+
+ | ``0`` | The value of the registry item. |
+ +-------+-----------------------------------------+
+ | ``1`` | An integer giving the registry type for |
+ | | this value. |
+ +-------+-----------------------------------------+
+
+
+.. function:: SaveKey(key, file_name)
+
+ Saves the specified key, and all its subkeys to the specified file.
+
+ *key* is an already open key, or one of the predefined :const:`HKEY_\*`
+ constants.
+
+ *file_name* is the name of the file to save registry data to. This file cannot
+ already exist. If this filename includes an extension, it cannot be used on file
+ allocation table (FAT) file systems by the :meth:`LoadKey`, :meth:`ReplaceKey`
+ or :meth:`RestoreKey` methods.
+
+ If *key* represents a key on a remote computer, the path described by
+ *file_name* is relative to the remote computer. The caller of this method must
+ possess the :const:`SeBackupPrivilege` security privilege. Note that
+ privileges are different than permissions - see the Win32 documentation for
+ more details.
+
+ This function passes NULL for *security_attributes* to the API.
+
+
+.. function:: SetValue(key, sub_key, type, value)
+
+ Associates a value with a specified key.
+
+ *key* is an already open key, or one of the predefined :const:`HKEY_\*`
+ constants.
+
+ *sub_key* is a string that names the subkey with which the value is associated.
+
+ *type* is an integer that specifies the type of the data. Currently this must be
+ :const:`REG_SZ`, meaning only strings are supported. Use the :func:`SetValueEx`
+ function for support for other data types.
+
+ *value* is a string that specifies the new value.
+
+ If the key specified by the *sub_key* parameter does not exist, the SetValue
+ function creates it.
+
+ Value lengths are limited by available memory. Long values (more than 2048
+ bytes) should be stored as files with the filenames stored in the configuration
+ registry. This helps the registry perform efficiently.
+
+ The key identified by the *key* parameter must have been opened with
+ :const:`KEY_SET_VALUE` access.
+
+
+.. function:: SetValueEx(key, value_name, reserved, type, value)
+
+ Stores data in the value field of an open registry key.
+
+ *key* is an already open key, or one of the predefined :const:`HKEY_\*`
+ constants.
+
+ *value_name* is a string that names the subkey with which the value is
+ associated.
+
+ *type* is an integer that specifies the type of the data. This should be one
+ of the following constants defined in this module:
+
+ +----------------------------------+---------------------------------------------+
+ | Constant | Meaning |
+ +==================================+=============================================+
+ | :const:`REG_BINARY` | Binary data in any form. |
+ +----------------------------------+---------------------------------------------+
+ | :const:`REG_DWORD` | A 32-bit number. |
+ +----------------------------------+---------------------------------------------+
+ | :const:`REG_DWORD_LITTLE_ENDIAN` | A 32-bit number in little-endian format. |
+ +----------------------------------+---------------------------------------------+
+ | :const:`REG_DWORD_BIG_ENDIAN` | A 32-bit number in big-endian format. |
+ +----------------------------------+---------------------------------------------+
+ | :const:`REG_EXPAND_SZ` | Null-terminated string containing |
+ | | references to environment variables |
+ | | (``%PATH%``). |
+ +----------------------------------+---------------------------------------------+
+ | :const:`REG_LINK` | A Unicode symbolic link. |
+ +----------------------------------+---------------------------------------------+
+ | :const:`REG_MULTI_SZ` | A sequence of null-terminated strings, |
+ | | terminated by two null characters. (Python |
+ | | handles this termination automatically.) |
+ +----------------------------------+---------------------------------------------+
+ | :const:`REG_NONE` | No defined value type. |
+ +----------------------------------+---------------------------------------------+
+ | :const:`REG_RESOURCE_LIST` | A device-driver resource list. |
+ +----------------------------------+---------------------------------------------+
+ | :const:`REG_SZ` | A null-terminated string. |
+ +----------------------------------+---------------------------------------------+
+
+ *reserved* can be anything - zero is always passed to the API.
+
+ *value* is a string that specifies the new value.
+
+ This method can also set additional value and type information for the specified
+ key. The key identified by the key parameter must have been opened with
+ :const:`KEY_SET_VALUE` access.
+
+ To open the key, use the :func:`CreateKeyEx` or :func:`OpenKey` methods.
+
+ Value lengths are limited by available memory. Long values (more than 2048
+ bytes) should be stored as files with the filenames stored in the configuration
+ registry. This helps the registry perform efficiently.
+
+
+.. _handle-object:
+
+Registry Handle Objects
+-----------------------
+
+This object wraps a Windows HKEY object, automatically closing it when the
+object is destroyed. To guarantee cleanup, you can call either the
+:meth:`Close` method on the object, or the :func:`CloseKey` function.
+
+All registry functions in this module return one of these objects.
+
+All registry functions in this module which accept a handle object also accept
+an integer, however, use of the handle object is encouraged.
+
+Handle objects provide semantics for :meth:`__nonzero__` - thus ::
+
+ if handle:
+ print "Yes"
+
+will print ``Yes`` if the handle is currently valid (has not been closed or
+detached).
+
+The object also support comparison semantics, so handle objects will compare
+true if they both reference the same underlying Windows handle value.
+
+Handle objects can be converted to an integer (e.g., using the builtin
+:func:`int` function), in which case the underlying Windows handle value is
+returned. You can also use the :meth:`Detach` method to return the integer
+handle, and also disconnect the Windows handle from the handle object.
+
+
+.. method:: PyHKEY.Close()
+
+ Closes the underlying Windows handle.
+
+ If the handle is already closed, no error is raised.
+
+
+.. method:: PyHKEY.Detach()
+
+ Detaches the Windows handle from the handle object.
+
+ The result is an integer (or long on 64 bit Windows) that holds the value of the
+ handle before it is detached. If the handle is already detached or closed, this
+ will return zero.
+
+ After calling this function, the handle is effectively invalidated, but the
+ handle is not closed. You would call this function when you need the
+ underlying Win32 handle to exist beyond the lifetime of the handle object.
+
--- /dev/null
+
+:mod:`aepack` --- Conversion between Python variables and AppleEvent data containers
+====================================================================================
+
+.. module:: aepack
+ :platform: Mac
+ :synopsis: Conversion between Python variables and AppleEvent data containers.
+.. sectionauthor:: Vincent Marchetti <vincem@en.com>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aepack` module defines functions for converting (packing) Python
+variables to AppleEvent descriptors and back (unpacking). Within Python the
+AppleEvent descriptor is handled by Python objects of built-in type
+:class:`AEDesc`, defined in module :mod:`Carbon.AE`.
+
+The :mod:`aepack` module defines the following functions:
+
+
+.. function:: pack(x[, forcetype])
+
+ Returns an :class:`AEDesc` object containing a conversion of Python value x. If
+ *forcetype* is provided it specifies the descriptor type of the result.
+ Otherwise, a default mapping of Python types to Apple Event descriptor types is
+ used, as follows:
+
+ +-----------------+-----------------------------------+
+ | Python type | descriptor type |
+ +=================+===================================+
+ | :class:`FSSpec` | typeFSS |
+ +-----------------+-----------------------------------+
+ | :class:`FSRef` | typeFSRef |
+ +-----------------+-----------------------------------+
+ | :class:`Alias` | typeAlias |
+ +-----------------+-----------------------------------+
+ | integer | typeLong (32 bit integer) |
+ +-----------------+-----------------------------------+
+ | float | typeFloat (64 bit floating point) |
+ +-----------------+-----------------------------------+
+ | string | typeText |
+ +-----------------+-----------------------------------+
+ | unicode | typeUnicodeText |
+ +-----------------+-----------------------------------+
+ | list | typeAEList |
+ +-----------------+-----------------------------------+
+ | dictionary | typeAERecord |
+ +-----------------+-----------------------------------+
+ | instance | *see below* |
+ +-----------------+-----------------------------------+
+
+ If *x* is a Python instance then this function attempts to call an
+ :meth:`__aepack__` method. This method should return an :class:`AEDesc` object.
+
+ If the conversion *x* is not defined above, this function returns the Python
+ string representation of a value (the repr() function) encoded as a text
+ descriptor.
+
+
+.. function:: unpack(x[, formodulename])
+
+ *x* must be an object of type :class:`AEDesc`. This function returns a Python
+ object representation of the data in the Apple Event descriptor *x*. Simple
+ AppleEvent data types (integer, text, float) are returned as their obvious
+ Python counterparts. Apple Event lists are returned as Python lists, and the
+ list elements are recursively unpacked. Object references (ex. ``line 3 of
+ document 1``) are returned as instances of :class:`aetypes.ObjectSpecifier`,
+ unless ``formodulename`` is specified. AppleEvent descriptors with descriptor
+ type typeFSS are returned as :class:`FSSpec` objects. AppleEvent record
+ descriptors are returned as Python dictionaries, with 4-character string keys
+ and elements recursively unpacked.
+
+ The optional ``formodulename`` argument is used by the stub packages generated
+ by :mod:`gensuitemodule`, and ensures that the OSA classes for object specifiers
+ are looked up in the correct module. This ensures that if, say, the Finder
+ returns an object specifier for a window you get an instance of
+ ``Finder.Window`` and not a generic ``aetypes.Window``. The former knows about
+ all the properties and elements a window has in the Finder, while the latter
+ knows no such things.
+
+
+.. seealso::
+
+ Module :mod:`Carbon.AE`
+ Built-in access to Apple Event Manager routines.
+
+ Module :mod:`aetypes`
+ Python definitions of codes for Apple Event descriptor types.
+
+ ` Inside Macintosh: Interapplication Communication <http://developer.apple.com/techpubs/mac/IAC/IAC-2.html>`_
+ Information about inter-process communications on the Macintosh.
+
--- /dev/null
+
+:mod:`aetools` --- OSA client support
+=====================================
+
+.. module:: aetools
+ :platform: Mac
+ :synopsis: Basic support for sending Apple Events
+.. sectionauthor:: Jack Jansen <Jack.Jansen@cwi.nl>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aetools` module contains the basic functionality on which Python
+AppleScript client support is built. It also imports and re-exports the core
+functionality of the :mod:`aetypes` and :mod:`aepack` modules. The stub packages
+generated by :mod:`gensuitemodule` import the relevant portions of
+:mod:`aetools`, so usually you do not need to import it yourself. The exception
+to this is when you cannot use a generated suite package and need lower-level
+access to scripting.
+
+The :mod:`aetools` module itself uses the AppleEvent support provided by the
+:mod:`Carbon.AE` module. This has one drawback: you need access to the window
+manager, see section :ref:`osx-gui-scripts` for details. This restriction may be
+lifted in future releases.
+
+The :mod:`aetools` module defines the following functions:
+
+
+.. function:: packevent(ae, parameters, attributes)
+
+ Stores parameters and attributes in a pre-created ``Carbon.AE.AEDesc`` object.
+ ``parameters`` and ``attributes`` are dictionaries mapping 4-character OSA
+ parameter keys to Python objects. The objects are packed using
+ ``aepack.pack()``.
+
+
+.. function:: unpackevent(ae[, formodulename])
+
+ Recursively unpacks a ``Carbon.AE.AEDesc`` event to Python objects. The function
+ returns the parameter dictionary and the attribute dictionary. The
+ ``formodulename`` argument is used by generated stub packages to control where
+ AppleScript classes are looked up.
+
+
+.. function:: keysubst(arguments, keydict)
+
+ Converts a Python keyword argument dictionary ``arguments`` to the format
+ required by ``packevent`` by replacing the keys, which are Python identifiers,
+ by the four-character OSA keys according to the mapping specified in
+ ``keydict``. Used by the generated suite packages.
+
+
+.. function:: enumsubst(arguments, key, edict)
+
+ If the ``arguments`` dictionary contains an entry for ``key`` convert the value
+ for that entry according to dictionary ``edict``. This converts human-readable
+ Python enumeration names to the OSA 4-character codes. Used by the generated
+ suite packages.
+
+The :mod:`aetools` module defines the following class:
+
+
+.. class:: TalkTo([signature=None, start=0, timeout=0])
+
+ Base class for the proxy used to talk to an application. ``signature`` overrides
+ the class attribute ``_signature`` (which is usually set by subclasses) and is
+ the 4-char creator code defining the application to talk to. ``start`` can be
+ set to true to enable running the application on class instantiation.
+ ``timeout`` can be specified to change the default timeout used while waiting
+ for an AppleEvent reply.
+
+
+.. method:: TalkTo._start()
+
+ Test whether the application is running, and attempt to start it if not.
+
+
+.. method:: TalkTo.send(code, subcode[, parameters, attributes])
+
+ Create the AppleEvent ``Carbon.AE.AEDesc`` for the verb with the OSA designation
+ ``code, subcode`` (which are the usual 4-character strings), pack the
+ ``parameters`` and ``attributes`` into it, send it to the target application,
+ wait for the reply, unpack the reply with ``unpackevent`` and return the reply
+ appleevent, the unpacked return values as a dictionary and the return
+ attributes.
+
--- /dev/null
+
+:mod:`aetypes` --- AppleEvent objects
+=====================================
+
+.. module:: aetypes
+ :platform: Mac
+ :synopsis: Python representation of the Apple Event Object Model.
+.. sectionauthor:: Vincent Marchetti <vincem@en.com>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`aetypes` defines classes used to represent Apple Event data
+descriptors and Apple Event object specifiers.
+
+Apple Event data is contained in descriptors, and these descriptors are typed.
+For many descriptors the Python representation is simply the corresponding
+Python type: ``typeText`` in OSA is a Python string, ``typeFloat`` is a float,
+etc. For OSA types that have no direct Python counterpart this module declares
+classes. Packing and unpacking instances of these classes is handled
+automatically by :mod:`aepack`.
+
+An object specifier is essentially an address of an object implemented in a
+Apple Event server. An Apple Event specifier is used as the direct object for an
+Apple Event or as the argument of an optional parameter. The :mod:`aetypes`
+module contains the base classes for OSA classes and properties, which are used
+by the packages generated by :mod:`gensuitemodule` to populate the classes and
+properties in a given suite.
+
+For reasons of backward compatibility, and for cases where you need to script an
+application for which you have not generated the stub package this module also
+contains object specifiers for a number of common OSA classes such as
+``Document``, ``Window``, ``Character``, etc.
+
+The :mod:`AEObjects` module defines the following classes to represent Apple
+Event descriptor data:
+
+
+.. class:: Unknown(type, data)
+
+ The representation of OSA descriptor data for which the :mod:`aepack` and
+ :mod:`aetypes` modules have no support, i.e. anything that is not represented by
+ the other classes here and that is not equivalent to a simple Python value.
+
+
+.. class:: Enum(enum)
+
+ An enumeration value with the given 4-character string value.
+
+
+.. class:: InsertionLoc(of, pos)
+
+ Position ``pos`` in object ``of``.
+
+
+.. class:: Boolean(bool)
+
+ A boolean.
+
+
+.. class:: StyledText(style, text)
+
+ Text with style information (font, face, etc) included.
+
+
+.. class:: AEText(script, style, text)
+
+ Text with script system and style information included.
+
+
+.. class:: IntlText(script, language, text)
+
+ Text with script system and language information included.
+
+
+.. class:: IntlWritingCode(script, language)
+
+ Script system and language information.
+
+
+.. class:: QDPoint(v, h)
+
+ A quickdraw point.
+
+
+.. class:: QDRectangle(v0, h0, v1, h1)
+
+ A quickdraw rectangle.
+
+
+.. class:: RGBColor(r, g, b)
+
+ A color.
+
+
+.. class:: Type(type)
+
+ An OSA type value with the given 4-character name.
+
+
+.. class:: Keyword(name)
+
+ An OSA keyword with the given 4-character name.
+
+
+.. class:: Range(start, stop)
+
+ A range.
+
+
+.. class:: Ordinal(abso)
+
+ Non-numeric absolute positions, such as ``"firs"``, first, or ``"midd"``,
+ middle.
+
+
+.. class:: Logical(logc, term)
+
+ The logical expression of applying operator ``logc`` to ``term``.
+
+
+.. class:: Comparison(obj1, relo, obj2)
+
+ The comparison ``relo`` of ``obj1`` to ``obj2``.
+
+The following classes are used as base classes by the generated stub packages to
+represent AppleScript classes and properties in Python:
+
+
+.. class:: ComponentItem(which[, fr])
+
+ Abstract baseclass for an OSA class. The subclass should set the class attribute
+ ``want`` to the 4-character OSA class code. Instances of subclasses of this
+ class are equivalent to AppleScript Object Specifiers. Upon instantiation you
+ should pass a selector in ``which``, and optionally a parent object in ``fr``.
+
+
+.. class:: NProperty(fr)
+
+ Abstract baseclass for an OSA property. The subclass should set the class
+ attributes ``want`` and ``which`` to designate which property we are talking
+ about. Instances of subclasses of this class are Object Specifiers.
+
+
+.. class:: ObjectSpecifier(want, form, seld[, fr])
+
+ Base class of ``ComponentItem`` and ``NProperty``, a general OSA Object
+ Specifier. See the Apple Open Scripting Architecture documentation for the
+ parameters. Note that this class is not abstract.
+
--- /dev/null
+
+:mod:`aifc` --- Read and write AIFF and AIFC files
+==================================================
+
+.. module:: aifc
+ :synopsis: Read and write audio files in AIFF or AIFC format.
+
+
+.. index::
+ single: Audio Interchange File Format
+ single: AIFF
+ single: AIFF-C
+
+This module provides support for reading and writing AIFF and AIFF-C files.
+AIFF is Audio Interchange File Format, a format for storing digital audio
+samples in a file. AIFF-C is a newer version of the format that includes the
+ability to compress the audio data.
+
+**Caveat:** Some operations may only work under IRIX; these will raise
+:exc:`ImportError` when attempting to import the :mod:`cl` module, which is only
+available on IRIX.
+
+Audio files have a number of parameters that describe the audio data. The
+sampling rate or frame rate is the number of times per second the sound is
+sampled. The number of channels indicate if the audio is mono, stereo, or
+quadro. Each frame consists of one sample per channel. The sample size is the
+size in bytes of each sample. Thus a frame consists of
+*nchannels*\**samplesize* bytes, and a second's worth of audio consists of
+*nchannels*\**samplesize*\**framerate* bytes.
+
+For example, CD quality audio has a sample size of two bytes (16 bits), uses two
+channels (stereo) and has a frame rate of 44,100 frames/second. This gives a
+frame size of 4 bytes (2\*2), and a second's worth occupies 2\*2\*44100 bytes
+(176,400 bytes).
+
+Module :mod:`aifc` defines the following function:
+
+
+.. function:: open(file[, mode])
+
+ Open an AIFF or AIFF-C file and return an object instance with methods that are
+ described below. The argument *file* is either a string naming a file or a file
+ object. *mode* must be ``'r'`` or ``'rb'`` when the file must be opened for
+ reading, or ``'w'`` or ``'wb'`` when the file must be opened for writing. If
+ omitted, ``file.mode`` is used if it exists, otherwise ``'rb'`` is used. When
+ used for writing, the file object should be seekable, unless you know ahead of
+ time how many samples you are going to write in total and use
+ :meth:`writeframesraw` and :meth:`setnframes`.
+
+Objects returned by :func:`open` when a file is opened for reading have the
+following methods:
+
+
+.. method:: aifc.getnchannels()
+
+ Return the number of audio channels (1 for mono, 2 for stereo).
+
+
+.. method:: aifc.getsampwidth()
+
+ Return the size in bytes of individual samples.
+
+
+.. method:: aifc.getframerate()
+
+ Return the sampling rate (number of audio frames per second).
+
+
+.. method:: aifc.getnframes()
+
+ Return the number of audio frames in the file.
+
+
+.. method:: aifc.getcomptype()
+
+ Return a four-character string describing the type of compression used in the
+ audio file. For AIFF files, the returned value is ``'NONE'``.
+
+
+.. method:: aifc.getcompname()
+
+ Return a human-readable description of the type of compression used in the audio
+ file. For AIFF files, the returned value is ``'not compressed'``.
+
+
+.. method:: aifc.getparams()
+
+ Return a tuple consisting of all of the above values in the above order.
+
+
+.. method:: aifc.getmarkers()
+
+ Return a list of markers in the audio file. A marker consists of a tuple of
+ three elements. The first is the mark ID (an integer), the second is the mark
+ position in frames from the beginning of the data (an integer), the third is the
+ name of the mark (a string).
+
+
+.. method:: aifc.getmark(id)
+
+ Return the tuple as described in :meth:`getmarkers` for the mark with the given
+ *id*.
+
+
+.. method:: aifc.readframes(nframes)
+
+ Read and return the next *nframes* frames from the audio file. The returned
+ data is a string containing for each frame the uncompressed samples of all
+ channels.
+
+
+.. method:: aifc.rewind()
+
+ Rewind the read pointer. The next :meth:`readframes` will start from the
+ beginning.
+
+
+.. method:: aifc.setpos(pos)
+
+ Seek to the specified frame number.
+
+
+.. method:: aifc.tell()
+
+ Return the current frame number.
+
+
+.. method:: aifc.close()
+
+ Close the AIFF file. After calling this method, the object can no longer be
+ used.
+
+Objects returned by :func:`open` when a file is opened for writing have all the
+above methods, except for :meth:`readframes` and :meth:`setpos`. In addition
+the following methods exist. The :meth:`get\*` methods can only be called after
+the corresponding :meth:`set\*` methods have been called. Before the first
+:meth:`writeframes` or :meth:`writeframesraw`, all parameters except for the
+number of frames must be filled in.
+
+
+.. method:: aifc.aiff()
+
+ Create an AIFF file. The default is that an AIFF-C file is created, unless the
+ name of the file ends in ``'.aiff'`` in which case the default is an AIFF file.
+
+
+.. method:: aifc.aifc()
+
+ Create an AIFF-C file. The default is that an AIFF-C file is created, unless
+ the name of the file ends in ``'.aiff'`` in which case the default is an AIFF
+ file.
+
+
+.. method:: aifc.setnchannels(nchannels)
+
+ Specify the number of channels in the audio file.
+
+
+.. method:: aifc.setsampwidth(width)
+
+ Specify the size in bytes of audio samples.
+
+
+.. method:: aifc.setframerate(rate)
+
+ Specify the sampling frequency in frames per second.
+
+
+.. method:: aifc.setnframes(nframes)
+
+ Specify the number of frames that are to be written to the audio file. If this
+ parameter is not set, or not set correctly, the file needs to support seeking.
+
+
+.. method:: aifc.setcomptype(type, name)
+
+ .. index::
+ single: u-LAW
+ single: A-LAW
+ single: G.722
+
+ Specify the compression type. If not specified, the audio data will not be
+ compressed. In AIFF files, compression is not possible. The name parameter
+ should be a human-readable description of the compression type, the type
+ parameter should be a four-character string. Currently the following
+ compression types are supported: NONE, ULAW, ALAW, G722.
+
+
+.. method:: aifc.setparams(nchannels, sampwidth, framerate, comptype, compname)
+
+ Set all the above parameters at once. The argument is a tuple consisting of the
+ various parameters. This means that it is possible to use the result of a
+ :meth:`getparams` call as argument to :meth:`setparams`.
+
+
+.. method:: aifc.setmark(id, pos, name)
+
+ Add a mark with the given id (larger than 0), and the given name at the given
+ position. This method can be called at any time before :meth:`close`.
+
+
+.. method:: aifc.tell()
+
+ Return the current write position in the output file. Useful in combination
+ with :meth:`setmark`.
+
+
+.. method:: aifc.writeframes(data)
+
+ Write data to the output file. This method can only be called after the audio
+ file parameters have been set.
+
+
+.. method:: aifc.writeframesraw(data)
+
+ Like :meth:`writeframes`, except that the header of the audio file is not
+ updated.
+
+
+.. method:: aifc.close()
+
+ Close the AIFF file. The header of the file is updated to reflect the actual
+ size of the audio data. After calling this method, the object can no longer be
+ used.
+
--- /dev/null
+
+:mod:`al` --- Audio functions on the SGI
+========================================
+
+.. module:: al
+ :platform: IRIX
+ :synopsis: Audio functions on the SGI.
+
+
+This module provides access to the audio facilities of the SGI Indy and Indigo
+workstations. See section 3A of the IRIX man pages for details. You'll need to
+read those man pages to understand what these functions do! Some of the
+functions are not available in IRIX releases before 4.0.5. Again, see the
+manual to check whether a specific function is available on your platform.
+
+All functions and methods defined in this module are equivalent to the C
+functions with ``AL`` prefixed to their name.
+
+.. index:: module: AL
+
+Symbolic constants from the C header file ``<audio.h>`` are defined in the
+standard module :mod:`AL`, see below.
+
+.. warning::
+
+ The current version of the audio library may dump core when bad argument values
+ are passed rather than returning an error status. Unfortunately, since the
+ precise circumstances under which this may happen are undocumented and hard to
+ check, the Python interface can provide no protection against this kind of
+ problems. (One example is specifying an excessive queue size --- there is no
+ documented upper limit.)
+
+The module defines the following functions:
+
+
+.. function:: openport(name, direction[, config])
+
+ The name and direction arguments are strings. The optional *config* argument is
+ a configuration object as returned by :func:`newconfig`. The return value is an
+ :dfn:`audio port object`; methods of audio port objects are described below.
+
+
+.. function:: newconfig()
+
+ The return value is a new :dfn:`audio configuration object`; methods of audio
+ configuration objects are described below.
+
+
+.. function:: queryparams(device)
+
+ The device argument is an integer. The return value is a list of integers
+ containing the data returned by :cfunc:`ALqueryparams`.
+
+
+.. function:: getparams(device, list)
+
+ The *device* argument is an integer. The list argument is a list such as
+ returned by :func:`queryparams`; it is modified in place (!).
+
+
+.. function:: setparams(device, list)
+
+ The *device* argument is an integer. The *list* argument is a list such as
+ returned by :func:`queryparams`.
+
+
+.. _al-config-objects:
+
+Configuration Objects
+---------------------
+
+Configuration objects returned by :func:`newconfig` have the following methods:
+
+
+.. method:: audio configuration.getqueuesize()
+
+ Return the queue size.
+
+
+.. method:: audio configuration.setqueuesize(size)
+
+ Set the queue size.
+
+
+.. method:: audio configuration.getwidth()
+
+ Get the sample width.
+
+
+.. method:: audio configuration.setwidth(width)
+
+ Set the sample width.
+
+
+.. method:: audio configuration.getchannels()
+
+ Get the channel count.
+
+
+.. method:: audio configuration.setchannels(nchannels)
+
+ Set the channel count.
+
+
+.. method:: audio configuration.getsampfmt()
+
+ Get the sample format.
+
+
+.. method:: audio configuration.setsampfmt(sampfmt)
+
+ Set the sample format.
+
+
+.. method:: audio configuration.getfloatmax()
+
+ Get the maximum value for floating sample formats.
+
+
+.. method:: audio configuration.setfloatmax(floatmax)
+
+ Set the maximum value for floating sample formats.
+
+
+.. _al-port-objects:
+
+Port Objects
+------------
+
+Port objects, as returned by :func:`openport`, have the following methods:
+
+
+.. method:: audio port.closeport()
+
+ Close the port.
+
+
+.. method:: audio port.getfd()
+
+ Return the file descriptor as an int.
+
+
+.. method:: audio port.getfilled()
+
+ Return the number of filled samples.
+
+
+.. method:: audio port.getfillable()
+
+ Return the number of fillable samples.
+
+
+.. method:: audio port.readsamps(nsamples)
+
+ Read a number of samples from the queue, blocking if necessary. Return the data
+ as a string containing the raw data, (e.g., 2 bytes per sample in big-endian
+ byte order (high byte, low byte) if you have set the sample width to 2 bytes).
+
+
+.. method:: audio port.writesamps(samples)
+
+ Write samples into the queue, blocking if necessary. The samples are encoded as
+ described for the :meth:`readsamps` return value.
+
+
+.. method:: audio port.getfillpoint()
+
+ Return the 'fill point'.
+
+
+.. method:: audio port.setfillpoint(fillpoint)
+
+ Set the 'fill point'.
+
+
+.. method:: audio port.getconfig()
+
+ Return a configuration object containing the current configuration of the port.
+
+
+.. method:: audio port.setconfig(config)
+
+ Set the configuration from the argument, a configuration object.
+
+
+.. method:: audio port.getstatus(list)
+
+ Get status information on last error.
+
+
+:mod:`AL` --- Constants used with the :mod:`al` module
+======================================================
+
+.. module:: AL
+ :platform: IRIX
+ :synopsis: Constants used with the al module.
+
+
+This module defines symbolic constants needed to use the built-in module
+:mod:`al` (see above); they are equivalent to those defined in the C header file
+``<audio.h>`` except that the name prefix ``AL_`` is omitted. Read the module
+source for a complete list of the defined names. Suggested use::
+
+ import al
+ from AL import *
+
--- /dev/null
+
+.. _allos:
+
+*********************************
+Generic Operating System Services
+*********************************
+
+The modules described in this chapter provide interfaces to operating system
+features that are available on (almost) all operating systems, such as files and
+a clock. The interfaces are generally modeled after the Unix or C interfaces,
+but they are available on most other systems as well. Here's an overview:
+
+
+.. toctree::
+
+ os.rst
+ time.rst
+ optparse.rst
+ getopt.rst
+ logging.rst
+ getpass.rst
+ curses.rst
+ curses.ascii.rst
+ curses.panel.rst
+ platform.rst
+ errno.rst
+ ctypes.rst
--- /dev/null
+
+:mod:`anydbm` --- Generic access to DBM-style databases
+=======================================================
+
+.. module:: anydbm
+ :synopsis: Generic interface to DBM-style database modules.
+
+
+.. index::
+ module: dbhash
+ module: bsddb
+ module: gdbm
+ module: dbm
+ module: dumbdbm
+
+:mod:`anydbm` is a generic interface to variants of the DBM database ---
+:mod:`dbhash` (requires :mod:`bsddb`), :mod:`gdbm`, or :mod:`dbm`. If none of
+these modules is installed, the slow-but-simple implementation in module
+:mod:`dumbdbm` will be used.
+
+
+.. function:: open(filename[, flag[, mode]])
+
+ Open the database file *filename* and return a corresponding object.
+
+ If the database file already exists, the :mod:`whichdb` module is used to
+ determine its type and the appropriate module is used; if it does not exist, the
+ first module listed above that can be imported is used.
+
+ The optional *flag* argument can be ``'r'`` to open an existing database for
+ reading only, ``'w'`` to open an existing database for reading and writing,
+ ``'c'`` to create the database if it doesn't exist, or ``'n'``, which will
+ always create a new empty database. If not specified, the default value is
+ ``'r'``.
+
+ The optional *mode* argument is the Unix mode of the file, used only when the
+ database has to be created. It defaults to octal ``0666`` (and will be modified
+ by the prevailing umask).
+
+
+.. exception:: error
+
+ A tuple containing the exceptions that can be raised by each of the supported
+ modules, with a unique exception also named :exc:`anydbm.error` as the first
+ item --- the latter is used when :exc:`anydbm.error` is raised.
+
+The object returned by :func:`open` supports most of the same functionality as
+dictionaries; keys and their corresponding values can be stored, retrieved, and
+deleted, and the :meth:`has_key` and :meth:`keys` methods are available. Keys
+and values must always be strings.
+
+The following example records some hostnames and a corresponding title, and
+then prints out the contents of the database::
+
+ import anydbm
+
+ # Open database, creating it if necessary.
+ db = anydbm.open('cache', 'c')
+
+ # Record some values
+ db['www.python.org'] = 'Python Website'
+ db['www.cnn.com'] = 'Cable News Network'
+
+ # Loop through contents. Other dictionary methods
+ # such as .keys(), .values() also work.
+ for k, v in db.iteritems():
+ print k, '\t', v
+
+ # Storing a non-string key or value will raise an exception (most
+ # likely a TypeError).
+ db['www.yahoo.com'] = 4
+
+ # Close when done.
+ db.close()
+
+
+.. seealso::
+
+ Module :mod:`dbhash`
+ BSD ``db`` database interface.
+
+ Module :mod:`dbm`
+ Standard Unix database interface.
+
+ Module :mod:`dumbdbm`
+ Portable implementation of the ``dbm`` interface.
+
+ Module :mod:`gdbm`
+ GNU database interface, based on the ``dbm`` interface.
+
+ Module :mod:`shelve`
+ General object persistence built on top of the Python ``dbm`` interface.
+
+ Module :mod:`whichdb`
+ Utility module used to determine the type of an existing database.
+
--- /dev/null
+
+.. _archiving:
+
+******************************
+Data Compression and Archiving
+******************************
+
+The modules described in this chapter support data compression with the zlib,
+gzip, and bzip2 algorithms, and the creation of ZIP- and tar-format archives.
+
+
+.. toctree::
+
+ zlib.rst
+ gzip.rst
+ bz2.rst
+ zipfile.rst
+ tarfile.rst
--- /dev/null
+
+:mod:`array` --- Efficient arrays of numeric values
+===================================================
+
+.. module:: array
+ :synopsis: Efficient arrays of uniformly typed numeric values.
+
+
+.. index:: single: arrays
+
+This module defines an object type which can efficiently represent an array of
+basic values: characters, integers, floating point numbers. Arrays are sequence
+types and behave very much like lists, except that the type of objects stored in
+them is constrained. The type is specified at object creation time by using a
+:dfn:`type code`, which is a single character. The following type codes are
+defined:
+
++-----------+----------------+-------------------+-----------------------+
+| Type code | C Type | Python Type | Minimum size in bytes |
++===========+================+===================+=======================+
+| ``'c'`` | char | character | 1 |
++-----------+----------------+-------------------+-----------------------+
+| ``'b'`` | signed char | int | 1 |
++-----------+----------------+-------------------+-----------------------+
+| ``'B'`` | unsigned char | int | 1 |
++-----------+----------------+-------------------+-----------------------+
+| ``'u'`` | Py_UNICODE | Unicode character | 2 |
++-----------+----------------+-------------------+-----------------------+
+| ``'h'`` | signed short | int | 2 |
++-----------+----------------+-------------------+-----------------------+
+| ``'H'`` | unsigned short | int | 2 |
++-----------+----------------+-------------------+-----------------------+
+| ``'i'`` | signed int | int | 2 |
++-----------+----------------+-------------------+-----------------------+
+| ``'I'`` | unsigned int | long | 2 |
++-----------+----------------+-------------------+-----------------------+
+| ``'l'`` | signed long | int | 4 |
++-----------+----------------+-------------------+-----------------------+
+| ``'L'`` | unsigned long | long | 4 |
++-----------+----------------+-------------------+-----------------------+
+| ``'f'`` | float | float | 4 |
++-----------+----------------+-------------------+-----------------------+
+| ``'d'`` | double | float | 8 |
++-----------+----------------+-------------------+-----------------------+
+
+The actual representation of values is determined by the machine architecture
+(strictly speaking, by the C implementation). The actual size can be accessed
+through the :attr:`itemsize` attribute. The values stored for ``'L'`` and
+``'I'`` items will be represented as Python long integers when retrieved,
+because Python's plain integer type cannot represent the full range of C's
+unsigned (long) integers.
+
+The module defines the following type:
+
+
+.. function:: array(typecode[, initializer])
+
+ Return a new array whose items are restricted by *typecode*, and initialized
+ from the optional *initializer* value, which must be a list, string, or iterable
+ over elements of the appropriate type.
+
+ .. versionchanged:: 2.4
+ Formerly, only lists or strings were accepted.
+
+ If given a list or string, the initializer is passed to the new array's
+ :meth:`fromlist`, :meth:`fromstring`, or :meth:`fromunicode` method (see below)
+ to add initial items to the array. Otherwise, the iterable initializer is
+ passed to the :meth:`extend` method.
+
+
+.. data:: ArrayType
+
+ Obsolete alias for :func:`array`.
+
+Array objects support the ordinary sequence operations of indexing, slicing,
+concatenation, and multiplication. When using slice assignment, the assigned
+value must be an array object with the same type code; in all other cases,
+:exc:`TypeError` is raised. Array objects also implement the buffer interface,
+and may be used wherever buffer objects are supported.
+
+The following data items and methods are also supported:
+
+
+.. attribute:: array.typecode
+
+ The typecode character used to create the array.
+
+
+.. attribute:: array.itemsize
+
+ The length in bytes of one array item in the internal representation.
+
+
+.. method:: array.append(x)
+
+ Append a new item with value *x* to the end of the array.
+
+
+.. method:: array.buffer_info()
+
+ Return a tuple ``(address, length)`` giving the current memory address and the
+ length in elements of the buffer used to hold array's contents. The size of the
+ memory buffer in bytes can be computed as ``array.buffer_info()[1] *
+ array.itemsize``. This is occasionally useful when working with low-level (and
+ inherently unsafe) I/O interfaces that require memory addresses, such as certain
+ :cfunc:`ioctl` operations. The returned numbers are valid as long as the array
+ exists and no length-changing operations are applied to it.
+
+ .. note::
+
+ When using array objects from code written in C or C++ (the only way to
+ effectively make use of this information), it makes more sense to use the buffer
+ interface supported by array objects. This method is maintained for backward
+ compatibility and should be avoided in new code. The buffer interface is
+ documented in :ref:`bufferobjects`.
+
+
+.. method:: array.byteswap()
+
+ "Byteswap" all items of the array. This is only supported for values which are
+ 1, 2, 4, or 8 bytes in size; for other types of values, :exc:`RuntimeError` is
+ raised. It is useful when reading data from a file written on a machine with a
+ different byte order.
+
+
+.. method:: array.count(x)
+
+ Return the number of occurrences of *x* in the array.
+
+
+.. method:: array.extend(iterable)
+
+ Append items from *iterable* to the end of the array. If *iterable* is another
+ array, it must have *exactly* the same type code; if not, :exc:`TypeError` will
+ be raised. If *iterable* is not an array, it must be iterable and its elements
+ must be the right type to be appended to the array.
+
+ .. versionchanged:: 2.4
+ Formerly, the argument could only be another array.
+
+
+.. method:: array.fromfile(f, n)
+
+ Read *n* items (as machine values) from the file object *f* and append them to
+ the end of the array. If less than *n* items are available, :exc:`EOFError` is
+ raised, but the items that were available are still inserted into the array.
+ *f* must be a real built-in file object; something else with a :meth:`read`
+ method won't do.
+
+
+.. method:: array.fromlist(list)
+
+ Append items from the list. This is equivalent to ``for x in list:
+ a.append(x)`` except that if there is a type error, the array is unchanged.
+
+
+.. method:: array.fromstring(s)
+
+ Appends items from the string, interpreting the string as an array of machine
+ values (as if it had been read from a file using the :meth:`fromfile` method).
+
+
+.. method:: array.fromunicode(s)
+
+ Extends this array with data from the given unicode string. The array must
+ be a type ``'u'`` array; otherwise a :exc:`ValueError` is raised. Use
+ ``array.fromstring(unicodestring.encode(enc))`` to append Unicode data to an
+ array of some other type.
+
+
+.. method:: array.index(x)
+
+ Return the smallest *i* such that *i* is the index of the first occurrence of
+ *x* in the array.
+
+
+.. method:: array.insert(i, x)
+
+ Insert a new item with value *x* in the array before position *i*. Negative
+ values are treated as being relative to the end of the array.
+
+
+.. method:: array.pop([i])
+
+ Removes the item with the index *i* from the array and returns it. The optional
+ argument defaults to ``-1``, so that by default the last item is removed and
+ returned.
+
+
+.. method:: array.read(f, n)
+
+ .. deprecated:: 1.5.1
+ Use the :meth:`fromfile` method.
+
+ Read *n* items (as machine values) from the file object *f* and append them to
+ the end of the array. If less than *n* items are available, :exc:`EOFError` is
+ raised, but the items that were available are still inserted into the array.
+ *f* must be a real built-in file object; something else with a :meth:`read`
+ method won't do.
+
+
+.. method:: array.remove(x)
+
+ Remove the first occurrence of *x* from the array.
+
+
+.. method:: array.reverse()
+
+ Reverse the order of the items in the array.
+
+
+.. method:: array.tofile(f)
+
+ Write all items (as machine values) to the file object *f*.
+
+
+.. method:: array.tolist()
+
+ Convert the array to an ordinary list with the same items.
+
+
+.. method:: array.tostring()
+
+ Convert the array to an array of machine values and return the string
+ representation (the same sequence of bytes that would be written to a file by
+ the :meth:`tofile` method.)
+
+
+.. method:: array.tounicode()
+
+ Convert the array to a unicode string. The array must be a type ``'u'`` array;
+ otherwise a :exc:`ValueError` is raised. Use ``array.tostring().decode(enc)`` to
+ obtain a unicode string from an array of some other type.
+
+
+.. method:: array.write(f)
+
+ .. deprecated:: 1.5.1
+ Use the :meth:`tofile` method.
+
+ Write all items (as machine values) to the file object *f*.
+
+When an array object is printed or converted to a string, it is represented as
+``array(typecode, initializer)``. The *initializer* is omitted if the array is
+empty, otherwise it is a string if the *typecode* is ``'c'``, otherwise it is a
+list of numbers. The string is guaranteed to be able to be converted back to an
+array with the same type and value using :func:`eval`, so long as the
+:func:`array` function has been imported using ``from array import array``.
+Examples::
+
+ array('l')
+ array('c', 'hello world')
+ array('u', u'hello \u2641')
+ array('l', [1, 2, 3, 4, 5])
+ array('d', [1.0, 2.0, 3.14])
+
+
+.. seealso::
+
+ Module :mod:`struct`
+ Packing and unpacking of heterogeneous binary data.
+
+ Module :mod:`xdrlib`
+ Packing and unpacking of External Data Representation (XDR) data as used in some
+ remote procedure call systems.
+
+ `The Numerical Python Manual <http://numpy.sourceforge.net/numdoc/HTML/numdoc.htm>`_
+ The Numeric Python extension (NumPy) defines another array type; see
+ http://numpy.sourceforge.net/ for further information about Numerical Python.
+ (A PDF version of the NumPy manual is available at
+ http://numpy.sourceforge.net/numdoc/numdoc.pdf).
+
--- /dev/null
+
+:mod:`asynchat` --- Asynchronous socket command/response handler
+================================================================
+
+.. module:: asynchat
+ :synopsis: Support for asynchronous command/response protocols.
+.. moduleauthor:: Sam Rushing <rushing@nightmare.com>
+.. sectionauthor:: Steve Holden <sholden@holdenweb.com>
+
+
+This module builds on the :mod:`asyncore` infrastructure, simplifying
+asynchronous clients and servers and making it easier to handle protocols whose
+elements are terminated by arbitrary strings, or are of variable length.
+:mod:`asynchat` defines the abstract class :class:`async_chat` that you
+subclass, providing implementations of the :meth:`collect_incoming_data` and
+:meth:`found_terminator` methods. It uses the same asynchronous loop as
+:mod:`asyncore`, and the two types of channel, :class:`asyncore.dispatcher` and
+:class:`asynchat.async_chat`, can freely be mixed in the channel map. Typically
+an :class:`asyncore.dispatcher` server channel generates new
+:class:`asynchat.async_chat` channel objects as it receives incoming connection
+requests.
+
+
+.. class:: async_chat()
+
+ This class is an abstract subclass of :class:`asyncore.dispatcher`. To make
+ practical use of the code you must subclass :class:`async_chat`, providing
+ meaningful :meth:`collect_incoming_data` and :meth:`found_terminator` methods.
+ The :class:`asyncore.dispatcher` methods can be used, although not all make
+ sense in a message/response context.
+
+ Like :class:`asyncore.dispatcher`, :class:`async_chat` defines a set of events
+ that are generated by an analysis of socket conditions after a :cfunc:`select`
+ call. Once the polling loop has been started the :class:`async_chat` object's
+ methods are called by the event-processing framework with no action on the part
+ of the programmer.
+
+ Unlike :class:`asyncore.dispatcher`, :class:`async_chat` allows you to define a
+ first-in-first-out queue (fifo) of *producers*. A producer need have only one
+ method, :meth:`more`, which should return data to be transmitted on the channel.
+ The producer indicates exhaustion (*i.e.* that it contains no more data) by
+ having its :meth:`more` method return the empty string. At this point the
+ :class:`async_chat` object removes the producer from the fifo and starts using
+ the next producer, if any. When the producer fifo is empty the
+ :meth:`handle_write` method does nothing. You use the channel object's
+ :meth:`set_terminator` method to describe how to recognize the end of, or an
+ important breakpoint in, an incoming transmission from the remote endpoint.
+
+ To build a functioning :class:`async_chat` subclass your input methods
+ :meth:`collect_incoming_data` and :meth:`found_terminator` must handle the data
+ that the channel receives asynchronously. The methods are described below.
+
+
+.. method:: async_chat.close_when_done()
+
+ Pushes a ``None`` on to the producer fifo. When this producer is popped off the
+ fifo it causes the channel to be closed.
+
+
+.. method:: async_chat.collect_incoming_data(data)
+
+ Called with *data* holding an arbitrary amount of received data. The default
+ method, which must be overridden, raises a :exc:`NotImplementedError` exception.
+
+
+.. method:: async_chat.discard_buffers()
+
+ In emergencies this method will discard any data held in the input and/or output
+ buffers and the producer fifo.
+
+
+.. method:: async_chat.found_terminator()
+
+ Called when the incoming data stream matches the termination condition set by
+ :meth:`set_terminator`. The default method, which must be overridden, raises a
+ :exc:`NotImplementedError` exception. The buffered input data should be
+ available via an instance attribute.
+
+
+.. method:: async_chat.get_terminator()
+
+ Returns the current terminator for the channel.
+
+
+.. method:: async_chat.handle_close()
+
+ Called when the channel is closed. The default method silently closes the
+ channel's socket.
+
+
+.. method:: async_chat.handle_read()
+
+ Called when a read event fires on the channel's socket in the asynchronous loop.
+ The default method checks for the termination condition established by
+ :meth:`set_terminator`, which can be either the appearance of a particular
+ string in the input stream or the receipt of a particular number of characters.
+ When the terminator is found, :meth:`handle_read` calls the
+ :meth:`found_terminator` method after calling :meth:`collect_incoming_data` with
+ any data preceding the terminating condition.
+
+
+.. method:: async_chat.handle_write()
+
+ Called when the application may write data to the channel. The default method
+ calls the :meth:`initiate_send` method, which in turn will call
+ :meth:`refill_buffer` to collect data from the producer fifo associated with the
+ channel.
+
+
+.. method:: async_chat.push(data)
+
+ Creates a :class:`simple_producer` object (*see below*) containing the data and
+ pushes it on to the channel's ``producer_fifo`` to ensure its transmission. This
+ is all you need to do to have the channel write the data out to the network,
+ although it is possible to use your own producers in more complex schemes to
+ implement encryption and chunking, for example.
+
+
+.. method:: async_chat.push_with_producer(producer)
+
+ Takes a producer object and adds it to the producer fifo associated with the
+ channel. When all currently-pushed producers have been exhausted the channel
+ will consume this producer's data by calling its :meth:`more` method and send
+ the data to the remote endpoint.
+
+
+.. method:: async_chat.readable()
+
+ Should return ``True`` for the channel to be included in the set of channels
+ tested by the :cfunc:`select` loop for readability.
+
+
+.. method:: async_chat.refill_buffer()
+
+ Refills the output buffer by calling the :meth:`more` method of the producer at
+ the head of the fifo. If it is exhausted then the producer is popped off the
+ fifo and the next producer is activated. If the current producer is, or becomes,
+ ``None`` then the channel is closed.
+
+
+.. method:: async_chat.set_terminator(term)
+
+ Sets the terminating condition to be recognised on the channel. ``term`` may be
+ any of three types of value, corresponding to three different ways to handle
+ incoming protocol data.
+
+ +-----------+---------------------------------------------+
+ | term | Description |
+ +===========+=============================================+
+ | *string* | Will call :meth:`found_terminator` when the |
+ | | string is found in the input stream |
+ +-----------+---------------------------------------------+
+ | *integer* | Will call :meth:`found_terminator` when the |
+ | | indicated number of characters have been |
+ | | received |
+ +-----------+---------------------------------------------+
+ | ``None`` | The channel continues to collect data |
+ | | forever |
+ +-----------+---------------------------------------------+
+
+ Note that any data following the terminator will be available for reading by the
+ channel after :meth:`found_terminator` is called.
+
+
+.. method:: async_chat.writable()
+
+ Should return ``True`` as long as items remain on the producer fifo, or the
+ channel is connected and the channel's output buffer is non-empty.
+
+
+asynchat - Auxiliary Classes and Functions
+------------------------------------------
+
+
+.. class:: simple_producer(data[, buffer_size=512])
+
+ A :class:`simple_producer` takes a chunk of data and an optional buffer size.
+ Repeated calls to its :meth:`more` method yield successive chunks of the data no
+ larger than *buffer_size*.
+
+
+.. method:: simple_producer.more()
+
+ Produces the next chunk of information from the producer, or returns the empty
+ string.
+
+
+.. class:: fifo([list=None])
+
+ Each channel maintains a :class:`fifo` holding data which has been pushed by the
+ application but not yet popped for writing to the channel. A :class:`fifo` is a
+ list used to hold data and/or producers until they are required. If the *list*
+ argument is provided then it should contain producers or data items to be
+ written to the channel.
+
+
+.. method:: fifo.is_empty()
+
+ Returns ``True`` iff the fifo is empty.
+
+
+.. method:: fifo.first()
+
+ Returns the least-recently :meth:`push`\ ed item from the fifo.
+
+
+.. method:: fifo.push(data)
+
+ Adds the given data (which may be a string or a producer object) to the producer
+ fifo.
+
+
+.. method:: fifo.pop()
+
+ If the fifo is not empty, returns ``True, first()``, deleting the popped item.
+ Returns ``False, None`` for an empty fifo.
+
+The :mod:`asynchat` module also defines one utility function, which may be of
+use in network and textual analysis operations.
+
+
+.. function:: find_prefix_at_end(haystack, needle)
+
+ Returns ``True`` if string *haystack* ends with any non-empty prefix of string
+ *needle*.
+
+
+.. _asynchat-example:
+
+asynchat Example
+----------------
+
+The following partial example shows how HTTP requests can be read with
+:class:`async_chat`. A web server might create an :class:`http_request_handler`
+object for each incoming client connection. Notice that initially the channel
+terminator is set to match the blank line at the end of the HTTP headers, and a
+flag indicates that the headers are being read.
+
+Once the headers have been read, if the request is of type POST (indicating that
+further data are present in the input stream) then the ``Content-Length:``
+header is used to set a numeric terminator to read the right amount of data from
+the channel.
+
+The :meth:`handle_request` method is called once all relevant input has been
+marshalled, after setting the channel terminator to ``None`` to ensure that any
+extraneous data sent by the web client are ignored. ::
+
+ class http_request_handler(asynchat.async_chat):
+
+ def __init__(self, conn, addr, sessions, log):
+ asynchat.async_chat.__init__(self, conn=conn)
+ self.addr = addr
+ self.sessions = sessions
+ self.ibuffer = []
+ self.obuffer = ""
+ self.set_terminator("\r\n\r\n")
+ self.reading_headers = True
+ self.handling = False
+ self.cgi_data = None
+ self.log = log
+
+ def collect_incoming_data(self, data):
+ """Buffer the data"""
+ self.ibuffer.append(data)
+
+ def found_terminator(self):
+ if self.reading_headers:
+ self.reading_headers = False
+ self.parse_headers("".join(self.ibuffer))
+ self.ibuffer = []
+ if self.op.upper() == "POST":
+ clen = self.headers.getheader("content-length")
+ self.set_terminator(int(clen))
+ else:
+ self.handling = True
+ self.set_terminator(None)
+ self.handle_request()
+ elif not self.handling:
+ self.set_terminator(None) # browsers sometimes over-send
+ self.cgi_data = parse(self.headers, "".join(self.ibuffer))
+ self.handling = True
+ self.ibuffer = []
+ self.handle_request()
+
--- /dev/null
+
+:mod:`asyncore` --- Asynchronous socket handler
+===============================================
+
+.. module:: asyncore
+ :synopsis: A base class for developing asynchronous socket handling services.
+.. moduleauthor:: Sam Rushing <rushing@nightmare.com>
+.. sectionauthor:: Christopher Petrilli <petrilli@amber.org>
+.. sectionauthor:: Steve Holden <sholden@holdenweb.com>
+
+
+This module provides the basic infrastructure for writing asynchronous socket
+service clients and servers.
+
+.. % Heavily adapted from original documentation by Sam Rushing.
+
+There are only two ways to have a program on a single processor do "more than
+one thing at a time." Multi-threaded programming is the simplest and most
+popular way to do it, but there is another very different technique, that lets
+you have nearly all the advantages of multi-threading, without actually using
+multiple threads. It's really only practical if your program is largely I/O
+bound. If your program is processor bound, then pre-emptive scheduled threads
+are probably what you really need. Network servers are rarely processor bound,
+however.
+
+If your operating system supports the :cfunc:`select` system call in its I/O
+library (and nearly all do), then you can use it to juggle multiple
+communication channels at once; doing other work while your I/O is taking place
+in the "background." Although this strategy can seem strange and complex,
+especially at first, it is in many ways easier to understand and control than
+multi-threaded programming. The :mod:`asyncore` module solves many of the
+difficult problems for you, making the task of building sophisticated
+high-performance network servers and clients a snap. For "conversational"
+applications and protocols the companion :mod:`asynchat` module is invaluable.
+
+The basic idea behind both modules is to create one or more network *channels*,
+instances of class :class:`asyncore.dispatcher` and
+:class:`asynchat.async_chat`. Creating the channels adds them to a global map,
+used by the :func:`loop` function if you do not provide it with your own *map*.
+
+Once the initial channel(s) is(are) created, calling the :func:`loop` function
+activates channel service, which continues until the last channel (including any
+that have been added to the map during asynchronous service) is closed.
+
+
+.. function:: loop([timeout[, use_poll[, map[,count]]]])
+
+ Enter a polling loop that terminates after count passes or all open channels
+ have been closed. All arguments are optional. The *count* parameter defaults
+ to None, resulting in the loop terminating only when all channels have been
+ closed. The *timeout* argument sets the timeout parameter for the appropriate
+ :func:`select` or :func:`poll` call, measured in seconds; the default is 30
+ seconds. The *use_poll* parameter, if true, indicates that :func:`poll` should
+ be used in preference to :func:`select` (the default is ``False``).
+
+ The *map* parameter is a dictionary whose items are the channels to watch. As
+ channels are closed they are deleted from their map. If *map* is omitted, a
+ global map is used. Channels (instances of :class:`asyncore.dispatcher`,
+ :class:`asynchat.async_chat` and subclasses thereof) can freely be mixed in the
+ map.
+
+
+.. class:: dispatcher()
+
+ The :class:`dispatcher` class is a thin wrapper around a low-level socket
+ object. To make it more useful, it has a few methods for event-handling which
+ are called from the asynchronous loop. Otherwise, it can be treated as a
+ normal non-blocking socket object.
+
+ Two class attributes can be modified, to improve performance, or possibly even
+ to conserve memory.
+
+
+ .. data:: ac_in_buffer_size
+
+ The asynchronous input buffer size (default ``4096``).
+
+
+ .. data:: ac_out_buffer_size
+
+ The asynchronous output buffer size (default ``4096``).
+
+ The firing of low-level events at certain times or in certain connection states
+ tells the asynchronous loop that certain higher-level events have taken place.
+ For example, if we have asked for a socket to connect to another host, we know
+ that the connection has been made when the socket becomes writable for the first
+ time (at this point you know that you may write to it with the expectation of
+ success). The implied higher-level events are:
+
+ +----------------------+----------------------------------------+
+ | Event | Description |
+ +======================+========================================+
+ | ``handle_connect()`` | Implied by the first write event |
+ +----------------------+----------------------------------------+
+ | ``handle_close()`` | Implied by a read event with no data |
+ | | available |
+ +----------------------+----------------------------------------+
+ | ``handle_accept()`` | Implied by a read event on a listening |
+ | | socket |
+ +----------------------+----------------------------------------+
+
+ During asynchronous processing, each mapped channel's :meth:`readable` and
+ :meth:`writable` methods are used to determine whether the channel's socket
+ should be added to the list of channels :cfunc:`select`\ ed or :cfunc:`poll`\ ed
+ for read and write events.
+
+Thus, the set of channel events is larger than the basic socket events. The full
+set of methods that can be overridden in your subclass follows:
+
+
+.. method:: dispatcher.handle_read()
+
+ Called when the asynchronous loop detects that a :meth:`read` call on the
+ channel's socket will succeed.
+
+
+.. method:: dispatcher.handle_write()
+
+ Called when the asynchronous loop detects that a writable socket can be written.
+ Often this method will implement the necessary buffering for performance. For
+ example::
+
+ def handle_write(self):
+ sent = self.send(self.buffer)
+ self.buffer = self.buffer[sent:]
+
+
+.. method:: dispatcher.handle_expt()
+
+ Called when there is out of band (OOB) data for a socket connection. This will
+ almost never happen, as OOB is tenuously supported and rarely used.
+
+
+.. method:: dispatcher.handle_connect()
+
+ Called when the active opener's socket actually makes a connection. Might send a
+ "welcome" banner, or initiate a protocol negotiation with the remote endpoint,
+ for example.
+
+
+.. method:: dispatcher.handle_close()
+
+ Called when the socket is closed.
+
+
+.. method:: dispatcher.handle_error()
+
+ Called when an exception is raised and not otherwise handled. The default
+ version prints a condensed traceback.
+
+
+.. method:: dispatcher.handle_accept()
+
+ Called on listening channels (passive openers) when a connection can be
+ established with a new remote endpoint that has issued a :meth:`connect` call
+ for the local endpoint.
+
+
+.. method:: dispatcher.readable()
+
+ Called each time around the asynchronous loop to determine whether a channel's
+ socket should be added to the list on which read events can occur. The default
+ method simply returns ``True``, indicating that by default, all channels will
+ be interested in read events.
+
+
+.. method:: dispatcher.writable()
+
+ Called each time around the asynchronous loop to determine whether a channel's
+ socket should be added to the list on which write events can occur. The default
+ method simply returns ``True``, indicating that by default, all channels will
+ be interested in write events.
+
+In addition, each channel delegates or extends many of the socket methods. Most
+of these are nearly identical to their socket partners.
+
+
+.. method:: dispatcher.create_socket(family, type)
+
+ This is identical to the creation of a normal socket, and will use the same
+ options for creation. Refer to the :mod:`socket` documentation for information
+ on creating sockets.
+
+
+.. method:: dispatcher.connect(address)
+
+ As with the normal socket object, *address* is a tuple with the first element
+ the host to connect to, and the second the port number.
+
+
+.. method:: dispatcher.send(data)
+
+ Send *data* to the remote end-point of the socket.
+
+
+.. method:: dispatcher.recv(buffer_size)
+
+ Read at most *buffer_size* bytes from the socket's remote end-point. An empty
+ string implies that the channel has been closed from the other end.
+
+
+.. method:: dispatcher.listen(backlog)
+
+ Listen for connections made to the socket. The *backlog* argument specifies the
+ maximum number of queued connections and should be at least 1; the maximum value
+ is system-dependent (usually 5).
+
+
+.. method:: dispatcher.bind(address)
+
+ Bind the socket to *address*. The socket must not already be bound. (The
+ format of *address* depends on the address family --- see above.) To mark the
+ socket as re-usable (setting the :const:`SO_REUSEADDR` option), call the
+ :class:`dispatcher` object's :meth:`set_reuse_addr` method.
+
+
+.. method:: dispatcher.accept()
+
+ Accept a connection. The socket must be bound to an address and listening for
+ connections. The return value is a pair ``(conn, address)`` where *conn* is a
+ *new* socket object usable to send and receive data on the connection, and
+ *address* is the address bound to the socket on the other end of the connection.
+
+
+.. method:: dispatcher.close()
+
+ Close the socket. All future operations on the socket object will fail. The
+ remote end-point will receive no more data (after queued data is flushed).
+ Sockets are automatically closed when they are garbage-collected.
+
+
+.. _asyncore-example:
+
+asyncore Example basic HTTP client
+----------------------------------
+
+Here is a very basic HTTP client that uses the :class:`dispatcher` class to
+implement its socket handling::
+
+ import asyncore, socket
+
+ class http_client(asyncore.dispatcher):
+
+ def __init__(self, host, path):
+ asyncore.dispatcher.__init__(self)
+ self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
+ self.connect( (host, 80) )
+ self.buffer = 'GET %s HTTP/1.0\r\n\r\n' % path
+
+ def handle_connect(self):
+ pass
+
+ def handle_close(self):
+ self.close()
+
+ def handle_read(self):
+ print self.recv(8192)
+
+ def writable(self):
+ return (len(self.buffer) > 0)
+
+ def handle_write(self):
+ sent = self.send(self.buffer)
+ self.buffer = self.buffer[sent:]
+
+ c = http_client('www.python.org', '/')
+
+ asyncore.loop()
+
--- /dev/null
+
+:mod:`atexit` --- Exit handlers
+===============================
+
+.. module:: atexit
+ :synopsis: Register and execute cleanup functions.
+.. moduleauthor:: Skip Montanaro <skip@mojam.com>
+.. sectionauthor:: Skip Montanaro <skip@mojam.com>
+
+
+.. versionadded:: 2.0
+
+The :mod:`atexit` module defines a single function to register cleanup
+functions. Functions thus registered are automatically executed upon normal
+interpreter termination.
+
+Note: the functions registered via this module are not called when the program
+is killed by a signal, when a Python fatal internal error is detected, or when
+:func:`os._exit` is called.
+
+.. index:: single: exitfunc (in sys)
+
+This is an alternate interface to the functionality provided by the
+``sys.exitfunc`` variable.
+
+Note: This module is unlikely to work correctly when used with other code that
+sets ``sys.exitfunc``. In particular, other core Python modules are free to use
+:mod:`atexit` without the programmer's knowledge. Authors who use
+``sys.exitfunc`` should convert their code to use :mod:`atexit` instead. The
+simplest way to convert code that sets ``sys.exitfunc`` is to import
+:mod:`atexit` and register the function that had been bound to ``sys.exitfunc``.
+
+
+.. function:: register(func[, *args[, **kargs]])
+
+ Register *func* as a function to be executed at termination. Any optional
+ arguments that are to be passed to *func* must be passed as arguments to
+ :func:`register`.
+
+ At normal program termination (for instance, if :func:`sys.exit` is called or
+ the main module's execution completes), all functions registered are called in
+ last in, first out order. The assumption is that lower level modules will
+ normally be imported before higher level modules and thus must be cleaned up
+ later.
+
+ If an exception is raised during execution of the exit handlers, a traceback is
+ printed (unless :exc:`SystemExit` is raised) and the exception information is
+ saved. After all exit handlers have had a chance to run the last exception to
+ be raised is re-raised.
+
+ .. versionchanged:: 2.6
+ This function now returns *func* which makes it possible to use it as a
+ decorator without binding the original name to ``None``.
+
+
+.. seealso::
+
+ Module :mod:`readline`
+ Useful example of :mod:`atexit` to read and write :mod:`readline` history files.
+
+
+.. _atexit-example:
+
+:mod:`atexit` Example
+---------------------
+
+The following simple example demonstrates how a module can initialize a counter
+from a file when it is imported and save the counter's updated value
+automatically when the program terminates without relying on the application
+making an explicit call into this module at termination. ::
+
+ try:
+ _count = int(open("/tmp/counter").read())
+ except IOError:
+ _count = 0
+
+ def incrcounter(n):
+ global _count
+ _count = _count + n
+
+ def savecounter():
+ open("/tmp/counter", "w").write("%d" % _count)
+
+ import atexit
+ atexit.register(savecounter)
+
+Positional and keyword arguments may also be passed to :func:`register` to be
+passed along to the registered function when it is called::
+
+ def goodbye(name, adjective):
+ print 'Goodbye, %s, it was %s to meet you.' % (name, adjective)
+
+ import atexit
+ atexit.register(goodbye, 'Donny', 'nice')
+
+ # or:
+ atexit.register(goodbye, adjective='nice', name='Donny')
+
+Usage as a decorator::
+
+ import atexit
+
+ @atexit.register
+ def goodbye():
+ print "You are now leaving the Python sector."
+
+This obviously only works with functions that don't take arguments.
+
--- /dev/null
+
+:mod:`audioop` --- Manipulate raw audio data
+============================================
+
+.. module:: audioop
+ :synopsis: Manipulate raw audio data.
+
+
+The :mod:`audioop` module contains some useful operations on sound fragments.
+It operates on sound fragments consisting of signed integer samples 8, 16 or 32
+bits wide, stored in Python strings. This is the same format as used by the
+:mod:`al` and :mod:`sunaudiodev` modules. All scalar items are integers, unless
+specified otherwise.
+
+.. index::
+ single: Intel/DVI ADPCM
+ single: ADPCM, Intel/DVI
+ single: a-LAW
+ single: u-LAW
+
+This module provides support for a-LAW, u-LAW and Intel/DVI ADPCM encodings.
+
+.. % This para is mostly here to provide an excuse for the index entries...
+
+A few of the more complicated operations only take 16-bit samples, otherwise the
+sample size (in bytes) is always a parameter of the operation.
+
+The module defines the following variables and functions:
+
+
+.. exception:: error
+
+ This exception is raised on all errors, such as unknown number of bytes per
+ sample, etc.
+
+
+.. function:: add(fragment1, fragment2, width)
+
+ Return a fragment which is the addition of the two samples passed as parameters.
+ *width* is the sample width in bytes, either ``1``, ``2`` or ``4``. Both
+ fragments should have the same length.
+
+
+.. function:: adpcm2lin(adpcmfragment, width, state)
+
+ Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See the
+ description of :func:`lin2adpcm` for details on ADPCM coding. Return a tuple
+ ``(sample, newstate)`` where the sample has the width specified in *width*.
+
+
+.. function:: alaw2lin(fragment, width)
+
+ Convert sound fragments in a-LAW encoding to linearly encoded sound fragments.
+ a-LAW encoding always uses 8 bits samples, so *width* refers only to the sample
+ width of the output fragment here.
+
+ .. versionadded:: 2.5
+
+
+.. function:: avg(fragment, width)
+
+ Return the average over all samples in the fragment.
+
+
+.. function:: avgpp(fragment, width)
+
+ Return the average peak-peak value over all samples in the fragment. No
+ filtering is done, so the usefulness of this routine is questionable.
+
+
+.. function:: bias(fragment, width, bias)
+
+ Return a fragment that is the original fragment with a bias added to each
+ sample.
+
+
+.. function:: cross(fragment, width)
+
+ Return the number of zero crossings in the fragment passed as an argument.
+
+
+.. function:: findfactor(fragment, reference)
+
+ Return a factor *F* such that ``rms(add(fragment, mul(reference, -F)))`` is
+ minimal, i.e., return the factor with which you should multiply *reference* to
+ make it match as well as possible to *fragment*. The fragments should both
+ contain 2-byte samples.
+
+ The time taken by this routine is proportional to ``len(fragment)``.
+
+
+.. function:: findfit(fragment, reference)
+
+ Try to match *reference* as well as possible to a portion of *fragment* (which
+ should be the longer fragment). This is (conceptually) done by taking slices
+ out of *fragment*, using :func:`findfactor` to compute the best match, and
+ minimizing the result. The fragments should both contain 2-byte samples.
+ Return a tuple ``(offset, factor)`` where *offset* is the (integer) offset into
+ *fragment* where the optimal match started and *factor* is the (floating-point)
+ factor as per :func:`findfactor`.
+
+
+.. function:: findmax(fragment, length)
+
+ Search *fragment* for a slice of length *length* samples (not bytes!) with
+ maximum energy, i.e., return *i* for which ``rms(fragment[i*2:(i+length)*2])``
+ is maximal. The fragments should both contain 2-byte samples.
+
+ The routine takes time proportional to ``len(fragment)``.
+
+
+.. function:: getsample(fragment, width, index)
+
+ Return the value of sample *index* from the fragment.
+
+
+.. function:: lin2adpcm(fragment, width, state)
+
+ Convert samples to 4 bit Intel/DVI ADPCM encoding. ADPCM coding is an adaptive
+ coding scheme, whereby each 4 bit number is the difference between one sample
+ and the next, divided by a (varying) step. The Intel/DVI ADPCM algorithm has
+ been selected for use by the IMA, so it may well become a standard.
+
+ *state* is a tuple containing the state of the coder. The coder returns a tuple
+ ``(adpcmfrag, newstate)``, and the *newstate* should be passed to the next call
+ of :func:`lin2adpcm`. In the initial call, ``None`` can be passed as the state.
+ *adpcmfrag* is the ADPCM coded fragment packed 2 4-bit values per byte.
+
+
+.. function:: lin2alaw(fragment, width)
+
+ Convert samples in the audio fragment to a-LAW encoding and return this as a
+ Python string. a-LAW is an audio encoding format whereby you get a dynamic
+ range of about 13 bits using only 8 bit samples. It is used by the Sun audio
+ hardware, among others.
+
+ .. versionadded:: 2.5
+
+
+.. function:: lin2lin(fragment, width, newwidth)
+
+ Convert samples between 1-, 2- and 4-byte formats.
+
+
+.. function:: lin2ulaw(fragment, width)
+
+ Convert samples in the audio fragment to u-LAW encoding and return this as a
+ Python string. u-LAW is an audio encoding format whereby you get a dynamic
+ range of about 14 bits using only 8 bit samples. It is used by the Sun audio
+ hardware, among others.
+
+
+.. function:: minmax(fragment, width)
+
+ Return a tuple consisting of the minimum and maximum values of all samples in
+ the sound fragment.
+
+
+.. function:: max(fragment, width)
+
+ Return the maximum of the *absolute value* of all samples in a fragment.
+
+
+.. function:: maxpp(fragment, width)
+
+ Return the maximum peak-peak value in the sound fragment.
+
+
+.. function:: mul(fragment, width, factor)
+
+ Return a fragment that has all samples in the original fragment multiplied by
+ the floating-point value *factor*. Overflow is silently ignored.
+
+
+.. function:: ratecv(fragment, width, nchannels, inrate, outrate, state[, weightA[, weightB]])
+
+ Convert the frame rate of the input fragment.
+
+ *state* is a tuple containing the state of the converter. The converter returns
+ a tuple ``(newfragment, newstate)``, and *newstate* should be passed to the next
+ call of :func:`ratecv`. The initial call should pass ``None`` as the state.
+
+ The *weightA* and *weightB* arguments are parameters for a simple digital filter
+ and default to ``1`` and ``0`` respectively.
+
+
+.. function:: reverse(fragment, width)
+
+ Reverse the samples in a fragment and returns the modified fragment.
+
+
+.. function:: rms(fragment, width)
+
+ Return the root-mean-square of the fragment, i.e. ``sqrt(sum(S_i^2)/n)``.
+
+ This is a measure of the power in an audio signal.
+
+
+.. function:: tomono(fragment, width, lfactor, rfactor)
+
+ Convert a stereo fragment to a mono fragment. The left channel is multiplied by
+ *lfactor* and the right channel by *rfactor* before adding the two channels to
+ give a mono signal.
+
+
+.. function:: tostereo(fragment, width, lfactor, rfactor)
+
+ Generate a stereo fragment from a mono fragment. Each pair of samples in the
+ stereo fragment are computed from the mono sample, whereby left channel samples
+ are multiplied by *lfactor* and right channel samples by *rfactor*.
+
+
+.. function:: ulaw2lin(fragment, width)
+
+ Convert sound fragments in u-LAW encoding to linearly encoded sound fragments.
+ u-LAW encoding always uses 8 bits samples, so *width* refers only to the sample
+ width of the output fragment here.
+
+Note that operations such as :func:`mul` or :func:`max` make no distinction
+between mono and stereo fragments, i.e. all samples are treated equal. If this
+is a problem the stereo fragment should be split into two mono fragments first
+and recombined later. Here is an example of how to do that::
+
+ def mul_stereo(sample, width, lfactor, rfactor):
+ lsample = audioop.tomono(sample, width, 1, 0)
+ rsample = audioop.tomono(sample, width, 0, 1)
+ lsample = audioop.mul(sample, width, lfactor)
+ rsample = audioop.mul(sample, width, rfactor)
+ lsample = audioop.tostereo(lsample, width, 1, 0)
+ rsample = audioop.tostereo(rsample, width, 0, 1)
+ return audioop.add(lsample, rsample, width)
+
+If you use the ADPCM coder to build network packets and you want your protocol
+to be stateless (i.e. to be able to tolerate packet loss) you should not only
+transmit the data but also the state. Note that you should send the *initial*
+state (the one you passed to :func:`lin2adpcm`) along to the decoder, not the
+final state (as returned by the coder). If you want to use
+:func:`struct.struct` to store the state in binary you can code the first
+element (the predicted value) in 16 bits and the second (the delta index) in 8.
+
+The ADPCM coders have never been tried against other ADPCM coders, only against
+themselves. It could well be that I misinterpreted the standards in which case
+they will not be interoperable with the respective standards.
+
+The :func:`find\*` routines might look a bit funny at first sight. They are
+primarily meant to do echo cancellation. A reasonably fast way to do this is to
+pick the most energetic piece of the output sample, locate that in the input
+sample and subtract the whole output sample from the input sample::
+
+ def echocancel(outputdata, inputdata):
+ pos = audioop.findmax(outputdata, 800) # one tenth second
+ out_test = outputdata[pos*2:]
+ in_test = inputdata[pos*2:]
+ ipos, factor = audioop.findfit(in_test, out_test)
+ # Optional (for better cancellation):
+ # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
+ # out_test)
+ prefill = '\0'*(pos+ipos)*2
+ postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
+ outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill
+ return audioop.add(inputdata, outputdata, 2)
+
--- /dev/null
+
+:mod:`autoGIL` --- Global Interpreter Lock handling in event loops
+==================================================================
+
+.. module:: autoGIL
+ :platform: Mac
+ :synopsis: Global Interpreter Lock handling in event loops.
+.. moduleauthor:: Just van Rossum <just@letterror.com>
+
+
+The :mod:`autoGIL` module provides a function :func:`installAutoGIL` that
+automatically locks and unlocks Python's Global Interpreter Lock when running an
+event loop.
+
+
+.. exception:: AutoGILError
+
+ Raised if the observer callback cannot be installed, for example because the
+ current thread does not have a run loop.
+
+
+.. function:: installAutoGIL()
+
+ Install an observer callback in the event loop (CFRunLoop) for the current
+ thread, that will lock and unlock the Global Interpreter Lock (GIL) at
+ appropriate times, allowing other Python threads to run while the event loop is
+ idle.
+
+ Availability: OSX 10.1 or later.
+
--- /dev/null
+
+:mod:`base64` --- RFC 3548: Base16, Base32, Base64 Data Encodings
+=================================================================
+
+.. module:: base64
+ :synopsis: RFC 3548: Base16, Base32, Base64 Data Encodings
+
+
+.. index::
+ pair: base64; encoding
+ single: MIME; base64 encoding
+
+This module provides data encoding and decoding as specified in :rfc:`3548`.
+This standard defines the Base16, Base32, and Base64 algorithms for encoding and
+decoding arbitrary binary strings into text strings that can be safely sent by
+email, used as parts of URLs, or included as part of an HTTP POST request. The
+encoding algorithm is not the same as the :program:`uuencode` program.
+
+There are two interfaces provided by this module. The modern interface supports
+encoding and decoding string objects using all three alphabets. The legacy
+interface provides for encoding and decoding to and from file-like objects as
+well as strings, but only using the Base64 standard alphabet.
+
+The modern interface, which was introduced in Python 2.4, provides:
+
+
+.. function:: b64encode(s[, altchars])
+
+ Encode a string use Base64.
+
+ *s* is the string to encode. Optional *altchars* must be a string of at least
+ length 2 (additional characters are ignored) which specifies an alternative
+ alphabet for the ``+`` and ``/`` characters. This allows an application to e.g.
+ generate URL or filesystem safe Base64 strings. The default is ``None``, for
+ which the standard Base64 alphabet is used.
+
+ The encoded string is returned.
+
+
+.. function:: b64decode(s[, altchars])
+
+ Decode a Base64 encoded string.
+
+ *s* is the string to decode. Optional *altchars* must be a string of at least
+ length 2 (additional characters are ignored) which specifies the alternative
+ alphabet used instead of the ``+`` and ``/`` characters.
+
+ The decoded string is returned. A :exc:`TypeError` is raised if *s* were
+ incorrectly padded or if there are non-alphabet characters present in the
+ string.
+
+
+.. function:: standard_b64encode(s)
+
+ Encode string *s* using the standard Base64 alphabet.
+
+
+.. function:: standard_b64decode(s)
+
+ Decode string *s* using the standard Base64 alphabet.
+
+
+.. function:: urlsafe_b64encode(s)
+
+ Encode string *s* using a URL-safe alphabet, which substitutes ``-`` instead of
+ ``+`` and ``_`` instead of ``/`` in the standard Base64 alphabet.
+
+
+.. function:: urlsafe_b64decode(s)
+
+ Decode string *s* using a URL-safe alphabet, which substitutes ``-`` instead of
+ ``+`` and ``_`` instead of ``/`` in the standard Base64 alphabet.
+
+
+.. function:: b32encode(s)
+
+ Encode a string using Base32. *s* is the string to encode. The encoded string
+ is returned.
+
+
+.. function:: b32decode(s[, casefold[, map01]])
+
+ Decode a Base32 encoded string.
+
+ *s* is the string to decode. Optional *casefold* is a flag specifying whether a
+ lowercase alphabet is acceptable as input. For security purposes, the default
+ is ``False``.
+
+ :rfc:`3548` allows for optional mapping of the digit 0 (zero) to the letter O
+ (oh), and for optional mapping of the digit 1 (one) to either the letter I (eye)
+ or letter L (el). The optional argument *map01* when not ``None``, specifies
+ which letter the digit 1 should be mapped to (when *map01* is not ``None``, the
+ digit 0 is always mapped to the letter O). For security purposes the default is
+ ``None``, so that 0 and 1 are not allowed in the input.
+
+ The decoded string is returned. A :exc:`TypeError` is raised if *s* were
+ incorrectly padded or if there are non-alphabet characters present in the
+ string.
+
+
+.. function:: b16encode(s)
+
+ Encode a string using Base16.
+
+ *s* is the string to encode. The encoded string is returned.
+
+
+.. function:: b16decode(s[, casefold])
+
+ Decode a Base16 encoded string.
+
+ *s* is the string to decode. Optional *casefold* is a flag specifying whether a
+ lowercase alphabet is acceptable as input. For security purposes, the default
+ is ``False``.
+
+ The decoded string is returned. A :exc:`TypeError` is raised if *s* were
+ incorrectly padded or if there are non-alphabet characters present in the
+ string.
+
+The legacy interface:
+
+
+.. function:: decode(input, output)
+
+ Decode the contents of the *input* file and write the resulting binary data to
+ the *output* file. *input* and *output* must either be file objects or objects
+ that mimic the file object interface. *input* will be read until
+ ``input.read()`` returns an empty string.
+
+
+.. function:: decodestring(s)
+
+ Decode the string *s*, which must contain one or more lines of base64 encoded
+ data, and return a string containing the resulting binary data.
+
+
+.. function:: encode(input, output)
+
+ Encode the contents of the *input* file and write the resulting base64 encoded
+ data to the *output* file. *input* and *output* must either be file objects or
+ objects that mimic the file object interface. *input* will be read until
+ ``input.read()`` returns an empty string. :func:`encode` returns the encoded
+ data plus a trailing newline character (``'\n'``).
+
+
+.. function:: encodestring(s)
+
+ Encode the string *s*, which can contain arbitrary binary data, and return a
+ string containing one or more lines of base64-encoded data.
+ :func:`encodestring` returns a string containing one or more lines of
+ base64-encoded data always including an extra trailing newline (``'\n'``).
+
+An example usage of the module::
+
+ >>> import base64
+ >>> encoded = base64.b64encode('data to be encoded')
+ >>> encoded
+ 'ZGF0YSB0byBiZSBlbmNvZGVk'
+ >>> data = base64.b64decode(encoded)
+ >>> data
+ 'data to be encoded'
+
+
+.. seealso::
+
+ Module :mod:`binascii`
+ Support module containing ASCII-to-binary and binary-to-ASCII conversions.
+
+ :rfc:`1521` - MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies
+ Section 5.2, "Base64 Content-Transfer-Encoding," provides the definition of the
+ base64 encoding.
+
--- /dev/null
+
+:mod:`BaseHTTPServer` --- Basic HTTP server
+===========================================
+
+.. module:: BaseHTTPServer
+ :synopsis: Basic HTTP server (base class for SimpleHTTPServer and CGIHTTPServer).
+
+
+.. index::
+ pair: WWW; server
+ pair: HTTP; protocol
+ single: URL
+ single: httpd
+
+.. index::
+ module: SimpleHTTPServer
+ module: CGIHTTPServer
+
+This module defines two classes for implementing HTTP servers (Web servers).
+Usually, this module isn't used directly, but is used as a basis for building
+functioning Web servers. See the :mod:`SimpleHTTPServer` and
+:mod:`CGIHTTPServer` modules.
+
+The first class, :class:`HTTPServer`, is a :class:`SocketServer.TCPServer`
+subclass. It creates and listens at the HTTP socket, dispatching the requests
+to a handler. Code to create and run the server looks like this::
+
+ def run(server_class=BaseHTTPServer.HTTPServer,
+ handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
+ server_address = ('', 8000)
+ httpd = server_class(server_address, handler_class)
+ httpd.serve_forever()
+
+
+.. class:: HTTPServer(server_address, RequestHandlerClass)
+
+ This class builds on the :class:`TCPServer` class by storing the server address
+ as instance variables named :attr:`server_name` and :attr:`server_port`. The
+ server is accessible by the handler, typically through the handler's
+ :attr:`server` instance variable.
+
+
+.. class:: BaseHTTPRequestHandler(request, client_address, server)
+
+ This class is used to handle the HTTP requests that arrive at the server. By
+ itself, it cannot respond to any actual HTTP requests; it must be subclassed to
+ handle each request method (e.g. GET or POST). :class:`BaseHTTPRequestHandler`
+ provides a number of class and instance variables, and methods for use by
+ subclasses.
+
+ The handler will parse the request and the headers, then call a method specific
+ to the request type. The method name is constructed from the request. For
+ example, for the request method ``SPAM``, the :meth:`do_SPAM` method will be
+ called with no arguments. All of the relevant information is stored in instance
+ variables of the handler. Subclasses should not need to override or extend the
+ :meth:`__init__` method.
+
+:class:`BaseHTTPRequestHandler` has the following instance variables:
+
+
+.. attribute:: BaseHTTPRequestHandler.client_address
+
+ Contains a tuple of the form ``(host, port)`` referring to the client's address.
+
+
+.. attribute:: BaseHTTPRequestHandler.command
+
+ Contains the command (request type). For example, ``'GET'``.
+
+
+.. attribute:: BaseHTTPRequestHandler.path
+
+ Contains the request path.
+
+
+.. attribute:: BaseHTTPRequestHandler.request_version
+
+ Contains the version string from the request. For example, ``'HTTP/1.0'``.
+
+
+.. attribute:: BaseHTTPRequestHandler.headers
+
+ Holds an instance of the class specified by the :attr:`MessageClass` class
+ variable. This instance parses and manages the headers in the HTTP request.
+
+
+.. attribute:: BaseHTTPRequestHandler.rfile
+
+ Contains an input stream, positioned at the start of the optional input data.
+
+
+.. attribute:: BaseHTTPRequestHandler.wfile
+
+ Contains the output stream for writing a response back to the client. Proper
+ adherence to the HTTP protocol must be used when writing to this stream.
+
+:class:`BaseHTTPRequestHandler` has the following class variables:
+
+
+.. attribute:: BaseHTTPRequestHandler.server_version
+
+ Specifies the server software version. You may want to override this. The
+ format is multiple whitespace-separated strings, where each string is of the
+ form name[/version]. For example, ``'BaseHTTP/0.2'``.
+
+
+.. attribute:: BaseHTTPRequestHandler.sys_version
+
+ Contains the Python system version, in a form usable by the
+ :attr:`version_string` method and the :attr:`server_version` class variable. For
+ example, ``'Python/1.4'``.
+
+
+.. attribute:: BaseHTTPRequestHandler.error_message_format
+
+ Specifies a format string for building an error response to the client. It uses
+ parenthesized, keyed format specifiers, so the format operand must be a
+ dictionary. The *code* key should be an integer, specifying the numeric HTTP
+ error code value. *message* should be a string containing a (detailed) error
+ message of what occurred, and *explain* should be an explanation of the error
+ code number. Default *message* and *explain* values can found in the *responses*
+ class variable.
+
+
+.. attribute:: BaseHTTPRequestHandler.protocol_version
+
+ This specifies the HTTP protocol version used in responses. If set to
+ ``'HTTP/1.1'``, the server will permit HTTP persistent connections; however,
+ your server *must* then include an accurate ``Content-Length`` header (using
+ :meth:`send_header`) in all of its responses to clients. For backwards
+ compatibility, the setting defaults to ``'HTTP/1.0'``.
+
+
+.. attribute:: BaseHTTPRequestHandler.MessageClass
+
+ .. index:: single: Message (in module mimetools)
+
+ Specifies a :class:`rfc822.Message`\ -like class to parse HTTP headers.
+ Typically, this is not overridden, and it defaults to
+ :class:`mimetools.Message`.
+
+
+.. attribute:: BaseHTTPRequestHandler.responses
+
+ This variable contains a mapping of error code integers to two-element tuples
+ containing a short and long message. For example, ``{code: (shortmessage,
+ longmessage)}``. The *shortmessage* is usually used as the *message* key in an
+ error response, and *longmessage* as the *explain* key (see the
+ :attr:`error_message_format` class variable).
+
+A :class:`BaseHTTPRequestHandler` instance has the following methods:
+
+
+.. method:: BaseHTTPRequestHandler.handle()
+
+ Calls :meth:`handle_one_request` once (or, if persistent connections are
+ enabled, multiple times) to handle incoming HTTP requests. You should never need
+ to override it; instead, implement appropriate :meth:`do_\*` methods.
+
+
+.. method:: BaseHTTPRequestHandler.handle_one_request()
+
+ This method will parse and dispatch the request to the appropriate :meth:`do_\*`
+ method. You should never need to override it.
+
+
+.. method:: BaseHTTPRequestHandler.send_error(code[, message])
+
+ Sends and logs a complete error reply to the client. The numeric *code*
+ specifies the HTTP error code, with *message* as optional, more specific text. A
+ complete set of headers is sent, followed by text composed using the
+ :attr:`error_message_format` class variable.
+
+
+.. method:: BaseHTTPRequestHandler.send_response(code[, message])
+
+ Sends a response header and logs the accepted request. The HTTP response line is
+ sent, followed by *Server* and *Date* headers. The values for these two headers
+ are picked up from the :meth:`version_string` and :meth:`date_time_string`
+ methods, respectively.
+
+
+.. method:: BaseHTTPRequestHandler.send_header(keyword, value)
+
+ Writes a specific HTTP header to the output stream. *keyword* should specify the
+ header keyword, with *value* specifying its value.
+
+
+.. method:: BaseHTTPRequestHandler.end_headers()
+
+ Sends a blank line, indicating the end of the HTTP headers in the response.
+
+
+.. method:: BaseHTTPRequestHandler.log_request([code[, size]])
+
+ Logs an accepted (successful) request. *code* should specify the numeric HTTP
+ code associated with the response. If a size of the response is available, then
+ it should be passed as the *size* parameter.
+
+
+.. method:: BaseHTTPRequestHandler.log_error(...)
+
+ Logs an error when a request cannot be fulfilled. By default, it passes the
+ message to :meth:`log_message`, so it takes the same arguments (*format* and
+ additional values).
+
+
+.. method:: BaseHTTPRequestHandler.log_message(format, ...)
+
+ Logs an arbitrary message to ``sys.stderr``. This is typically overridden to
+ create custom error logging mechanisms. The *format* argument is a standard
+ printf-style format string, where the additional arguments to
+ :meth:`log_message` are applied as inputs to the formatting. The client address
+ and current date and time are prefixed to every message logged.
+
+
+.. method:: BaseHTTPRequestHandler.version_string()
+
+ Returns the server software's version string. This is a combination of the
+ :attr:`server_version` and :attr:`sys_version` class variables.
+
+
+.. method:: BaseHTTPRequestHandler.date_time_string([timestamp])
+
+ Returns the date and time given by *timestamp* (which must be in the format
+ returned by :func:`time.time`), formatted for a message header. If *timestamp*
+ is omitted, it uses the current date and time.
+
+ The result looks like ``'Sun, 06 Nov 1994 08:49:37 GMT'``.
+
+ .. versionadded:: 2.5
+ The *timestamp* parameter.
+
+
+.. method:: BaseHTTPRequestHandler.log_date_time_string()
+
+ Returns the current date and time, formatted for logging.
+
+
+.. method:: BaseHTTPRequestHandler.address_string()
+
+ Returns the client address, formatted for logging. A name lookup is performed on
+ the client's IP address.
+
+
+.. seealso::
+
+ Module :mod:`CGIHTTPServer`
+ Extended request handler that supports CGI scripts.
+
+ Module :mod:`SimpleHTTPServer`
+ Basic request handler that limits response to files actually under the document
+ root.
+
--- /dev/null
+
+:mod:`Bastion` --- Restricting access to objects
+================================================
+
+.. module:: Bastion
+ :synopsis: Providing restricted access to objects.
+.. moduleauthor:: Barry Warsaw <bwarsaw@python.org>
+
+
+.. versionchanged:: 2.3
+ Disabled module.
+
+.. warning::
+
+ The documentation has been left in place to help in reading old code that uses
+ the module.
+
+According to the dictionary, a bastion is "a fortified area or position", or
+"something that is considered a stronghold." It's a suitable name for this
+module, which provides a way to forbid access to certain attributes of an
+object. It must always be used with the :mod:`rexec` module, in order to allow
+restricted-mode programs access to certain safe attributes of an object, while
+denying access to other, unsafe attributes.
+
+.. % I'm concerned that the word 'bastion' won't be understood by people
+.. % for whom English is a second language, making the module name
+.. % somewhat mysterious. Thus, the brief definition... --amk
+
+.. % I've punted on the issue of documenting keyword arguments for now.
+
+
+.. function:: Bastion(object[, filter[, name[, class]]])
+
+ Protect the object *object*, returning a bastion for the object. Any attempt to
+ access one of the object's attributes will have to be approved by the *filter*
+ function; if the access is denied an :exc:`AttributeError` exception will be
+ raised.
+
+ If present, *filter* must be a function that accepts a string containing an
+ attribute name, and returns true if access to that attribute will be permitted;
+ if *filter* returns false, the access is denied. The default filter denies
+ access to any function beginning with an underscore (``'_'``). The bastion's
+ string representation will be ``<Bastion for name>`` if a value for *name* is
+ provided; otherwise, ``repr(object)`` will be used.
+
+ *class*, if present, should be a subclass of :class:`BastionClass`; see the
+ code in :file:`bastion.py` for the details. Overriding the default
+ :class:`BastionClass` will rarely be required.
+
+
+.. class:: BastionClass(getfunc, name)
+
+ Class which actually implements bastion objects. This is the default class used
+ by :func:`Bastion`. The *getfunc* parameter is a function which returns the
+ value of an attribute which should be exposed to the restricted execution
+ environment when called with the name of the attribute as the only parameter.
+ *name* is used to construct the :func:`repr` of the :class:`BastionClass`
+ instance.
+
--- /dev/null
+
+:mod:`binascii` --- Convert between binary and ASCII
+====================================================
+
+.. module:: binascii
+ :synopsis: Tools for converting between binary and various ASCII-encoded binary
+ representations.
+
+
+.. index::
+ module: uu
+ module: base64
+ module: binhex
+
+The :mod:`binascii` module contains a number of methods to convert between
+binary and various ASCII-encoded binary representations. Normally, you will not
+use these functions directly but use wrapper modules like :mod:`uu`,
+:mod:`base64`, or :mod:`binhex` instead. The :mod:`binascii` module contains
+low-level functions written in C for greater speed that are used by the
+higher-level modules.
+
+The :mod:`binascii` module defines the following functions:
+
+
+.. function:: a2b_uu(string)
+
+ Convert a single line of uuencoded data back to binary and return the binary
+ data. Lines normally contain 45 (binary) bytes, except for the last line. Line
+ data may be followed by whitespace.
+
+
+.. function:: b2a_uu(data)
+
+ Convert binary data to a line of ASCII characters, the return value is the
+ converted line, including a newline char. The length of *data* should be at most
+ 45.
+
+
+.. function:: a2b_base64(string)
+
+ Convert a block of base64 data back to binary and return the binary data. More
+ than one line may be passed at a time.
+
+
+.. function:: b2a_base64(data)
+
+ Convert binary data to a line of ASCII characters in base64 coding. The return
+ value is the converted line, including a newline char. The length of *data*
+ should be at most 57 to adhere to the base64 standard.
+
+
+.. function:: a2b_qp(string[, header])
+
+ Convert a block of quoted-printable data back to binary and return the binary
+ data. More than one line may be passed at a time. If the optional argument
+ *header* is present and true, underscores will be decoded as spaces.
+
+
+.. function:: b2a_qp(data[, quotetabs, istext, header])
+
+ Convert binary data to a line(s) of ASCII characters in quoted-printable
+ encoding. The return value is the converted line(s). If the optional argument
+ *quotetabs* is present and true, all tabs and spaces will be encoded. If the
+ optional argument *istext* is present and true, newlines are not encoded but
+ trailing whitespace will be encoded. If the optional argument *header* is
+ present and true, spaces will be encoded as underscores per RFC1522. If the
+ optional argument *header* is present and false, newline characters will be
+ encoded as well; otherwise linefeed conversion might corrupt the binary data
+ stream.
+
+
+.. function:: a2b_hqx(string)
+
+ Convert binhex4 formatted ASCII data to binary, without doing RLE-decompression.
+ The string should contain a complete number of binary bytes, or (in case of the
+ last portion of the binhex4 data) have the remaining bits zero.
+
+
+.. function:: rledecode_hqx(data)
+
+ Perform RLE-decompression on the data, as per the binhex4 standard. The
+ algorithm uses ``0x90`` after a byte as a repeat indicator, followed by a count.
+ A count of ``0`` specifies a byte value of ``0x90``. The routine returns the
+ decompressed data, unless data input data ends in an orphaned repeat indicator,
+ in which case the :exc:`Incomplete` exception is raised.
+
+
+.. function:: rlecode_hqx(data)
+
+ Perform binhex4 style RLE-compression on *data* and return the result.
+
+
+.. function:: b2a_hqx(data)
+
+ Perform hexbin4 binary-to-ASCII translation and return the resulting string. The
+ argument should already be RLE-coded, and have a length divisible by 3 (except
+ possibly the last fragment).
+
+
+.. function:: crc_hqx(data, crc)
+
+ Compute the binhex4 crc value of *data*, starting with an initial *crc* and
+ returning the result.
+
+
+.. function:: crc32(data[, crc])
+
+ Compute CRC-32, the 32-bit checksum of data, starting with an initial crc. This
+ is consistent with the ZIP file checksum. Since the algorithm is designed for
+ use as a checksum algorithm, it is not suitable for use as a general hash
+ algorithm. Use as follows::
+
+ print binascii.crc32("hello world")
+ # Or, in two pieces:
+ crc = binascii.crc32("hello")
+ crc = binascii.crc32(" world", crc)
+ print crc
+
+
+.. function:: b2a_hex(data)
+ hexlify(data)
+
+ Return the hexadecimal representation of the binary *data*. Every byte of
+ *data* is converted into the corresponding 2-digit hex representation. The
+ resulting string is therefore twice as long as the length of *data*.
+
+
+.. function:: a2b_hex(hexstr)
+ unhexlify(hexstr)
+
+ Return the binary data represented by the hexadecimal string *hexstr*. This
+ function is the inverse of :func:`b2a_hex`. *hexstr* must contain an even number
+ of hexadecimal digits (which can be upper or lower case), otherwise a
+ :exc:`TypeError` is raised.
+
+
+.. exception:: Error
+
+ Exception raised on errors. These are usually programming errors.
+
+
+.. exception:: Incomplete
+
+ Exception raised on incomplete data. These are usually not programming errors,
+ but may be handled by reading a little more data and trying again.
+
+
+.. seealso::
+
+ Module :mod:`base64`
+ Support for base64 encoding used in MIME email messages.
+
+ Module :mod:`binhex`
+ Support for the binhex format used on the Macintosh.
+
+ Module :mod:`uu`
+ Support for UU encoding used on Unix.
+
+ Module :mod:`quopri`
+ Support for quoted-printable encoding used in MIME email messages.
+
--- /dev/null
+
+:mod:`binhex` --- Encode and decode binhex4 files
+=================================================
+
+.. module:: binhex
+ :synopsis: Encode and decode files in binhex4 format.
+
+
+This module encodes and decodes files in binhex4 format, a format allowing
+representation of Macintosh files in ASCII. On the Macintosh, both forks of a
+file and the finder information are encoded (or decoded), on other platforms
+only the data fork is handled.
+
+The :mod:`binhex` module defines the following functions:
+
+
+.. function:: binhex(input, output)
+
+ Convert a binary file with filename *input* to binhex file *output*. The
+ *output* parameter can either be a filename or a file-like object (any object
+ supporting a :meth:`write` and :meth:`close` method).
+
+
+.. function:: hexbin(input[, output])
+
+ Decode a binhex file *input*. *input* may be a filename or a file-like object
+ supporting :meth:`read` and :meth:`close` methods. The resulting file is written
+ to a file named *output*, unless the argument is omitted in which case the
+ output filename is read from the binhex file.
+
+The following exception is also defined:
+
+
+.. exception:: Error
+
+ Exception raised when something can't be encoded using the binhex format (for
+ example, a filename is too long to fit in the filename field), or when input is
+ not properly encoded binhex data.
+
+
+.. seealso::
+
+ Module :mod:`binascii`
+ Support module containing ASCII-to-binary and binary-to-ASCII conversions.
+
+
+.. _binhex-notes:
+
+Notes
+-----
+
+There is an alternative, more powerful interface to the coder and decoder, see
+the source for details.
+
+If you code or decode textfiles on non-Macintosh platforms they will still use
+the Macintosh newline convention (carriage-return as end of line).
+
+As of this writing, :func:`hexbin` appears to not work in all cases.
+
--- /dev/null
+
+:mod:`bisect` --- Array bisection algorithm
+===========================================
+
+.. module:: bisect
+ :synopsis: Array bisection algorithms for binary searching.
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+.. % LaTeX produced by Fred L. Drake, Jr. <fdrake@acm.org>, with an
+.. % example based on the PyModules FAQ entry by Aaron Watters
+.. % <arw@pythonpros.com>.
+
+This module provides support for maintaining a list in sorted order without
+having to sort the list after each insertion. For long lists of items with
+expensive comparison operations, this can be an improvement over the more common
+approach. The module is called :mod:`bisect` because it uses a basic bisection
+algorithm to do its work. The source code may be most useful as a working
+example of the algorithm (the boundary conditions are already right!).
+
+The following functions are provided:
+
+
+.. function:: bisect_left(list, item[, lo[, hi]])
+
+ Locate the proper insertion point for *item* in *list* to maintain sorted order.
+ The parameters *lo* and *hi* may be used to specify a subset of the list which
+ should be considered; by default the entire list is used. If *item* is already
+ present in *list*, the insertion point will be before (to the left of) any
+ existing entries. The return value is suitable for use as the first parameter
+ to ``list.insert()``. This assumes that *list* is already sorted.
+
+ .. versionadded:: 2.1
+
+
+.. function:: bisect_right(list, item[, lo[, hi]])
+
+ Similar to :func:`bisect_left`, but returns an insertion point which comes after
+ (to the right of) any existing entries of *item* in *list*.
+
+ .. versionadded:: 2.1
+
+
+.. function:: bisect(...)
+
+ Alias for :func:`bisect_right`.
+
+
+.. function:: insort_left(list, item[, lo[, hi]])
+
+ Insert *item* in *list* in sorted order. This is equivalent to
+ ``list.insert(bisect.bisect_left(list, item, lo, hi), item)``. This assumes
+ that *list* is already sorted.
+
+ .. versionadded:: 2.1
+
+
+.. function:: insort_right(list, item[, lo[, hi]])
+
+ Similar to :func:`insort_left`, but inserting *item* in *list* after any
+ existing entries of *item*.
+
+ .. versionadded:: 2.1
+
+
+.. function:: insort(...)
+
+ Alias for :func:`insort_right`.
+
+
+Examples
+--------
+
+.. _bisect-example:
+
+The :func:`bisect` function is generally useful for categorizing numeric data.
+This example uses :func:`bisect` to look up a letter grade for an exam total
+(say) based on a set of ordered numeric breakpoints: 85 and up is an 'A', 75..84
+is a 'B', etc. ::
+
+ >>> grades = "FEDCBA"
+ >>> breakpoints = [30, 44, 66, 75, 85]
+ >>> from bisect import bisect
+ >>> def grade(total):
+ ... return grades[bisect(breakpoints, total)]
+ ...
+ >>> grade(66)
+ 'C'
+ >>> map(grade, [33, 99, 77, 44, 12, 88])
+ ['E', 'A', 'B', 'D', 'F', 'A']
+
+
--- /dev/null
+
+:mod:`bsddb` --- Interface to Berkeley DB library
+=================================================
+
+.. module:: bsddb
+ :synopsis: Interface to Berkeley DB database library
+.. sectionauthor:: Skip Montanaro <skip@mojam.com>
+
+
+The :mod:`bsddb` module provides an interface to the Berkeley DB library. Users
+can create hash, btree or record based library files using the appropriate open
+call. Bsddb objects behave generally like dictionaries. Keys and values must be
+strings, however, so to use other objects as keys or to store other kinds of
+objects the user must serialize them somehow, typically using
+:func:`marshal.dumps` or :func:`pickle.dumps`.
+
+The :mod:`bsddb` module requires a Berkeley DB library version from 3.3 thru
+4.5.
+
+
+.. seealso::
+
+ http://pybsddb.sourceforge.net/
+ The website with documentation for the :mod:`bsddb.db` Python Berkeley DB
+ interface that closely mirrors the object oriented interface provided in
+ Berkeley DB 3 and 4.
+
+ http://www.oracle.com/database/berkeley-db/
+ The Berkeley DB library.
+
+A more modern DB, DBEnv and DBSequence object interface is available in the
+:mod:`bsddb.db` module which closely matches the Berkeley DB C API documented at
+the above URLs. Additional features provided by the :mod:`bsddb.db` API include
+fine tuning, transactions, logging, and multiprocess concurrent database access.
+
+The following is a description of the legacy :mod:`bsddb` interface compatible
+with the old Python bsddb module. Starting in Python 2.5 this interface should
+be safe for multithreaded access. The :mod:`bsddb.db` API is recommended for
+threading users as it provides better control.
+
+The :mod:`bsddb` module defines the following functions that create objects that
+access the appropriate type of Berkeley DB file. The first two arguments of
+each function are the same. For ease of portability, only the first two
+arguments should be used in most instances.
+
+
+.. function:: hashopen(filename[, flag[, mode[, pgsize[, ffactor[, nelem[, cachesize[, lorder[, hflags]]]]]]]])
+
+ Open the hash format file named *filename*. Files never intended to be
+ preserved on disk may be created by passing ``None`` as the *filename*. The
+ optional *flag* identifies the mode used to open the file. It may be ``'r'``
+ (read only), ``'w'`` (read-write) , ``'c'`` (read-write - create if necessary;
+ the default) or ``'n'`` (read-write - truncate to zero length). The other
+ arguments are rarely used and are just passed to the low-level :cfunc:`dbopen`
+ function. Consult the Berkeley DB documentation for their use and
+ interpretation.
+
+
+.. function:: btopen(filename[, flag[, mode[, btflags[, cachesize[, maxkeypage[, minkeypage[, pgsize[, lorder]]]]]]]])
+
+ Open the btree format file named *filename*. Files never intended to be
+ preserved on disk may be created by passing ``None`` as the *filename*. The
+ optional *flag* identifies the mode used to open the file. It may be ``'r'``
+ (read only), ``'w'`` (read-write), ``'c'`` (read-write - create if necessary;
+ the default) or ``'n'`` (read-write - truncate to zero length). The other
+ arguments are rarely used and are just passed to the low-level dbopen function.
+ Consult the Berkeley DB documentation for their use and interpretation.
+
+
+.. function:: rnopen(filename[, flag[, mode[, rnflags[, cachesize[, pgsize[, lorder[, rlen[, delim[, source[, pad]]]]]]]]]])
+
+ Open a DB record format file named *filename*. Files never intended to be
+ preserved on disk may be created by passing ``None`` as the *filename*. The
+ optional *flag* identifies the mode used to open the file. It may be ``'r'``
+ (read only), ``'w'`` (read-write), ``'c'`` (read-write - create if necessary;
+ the default) or ``'n'`` (read-write - truncate to zero length). The other
+ arguments are rarely used and are just passed to the low-level dbopen function.
+ Consult the Berkeley DB documentation for their use and interpretation.
+
+.. note::
+
+ Beginning in 2.3 some Unix versions of Python may have a :mod:`bsddb185` module.
+ This is present *only* to allow backwards compatibility with systems which ship
+ with the old Berkeley DB 1.85 database library. The :mod:`bsddb185` module
+ should never be used directly in new code.
+
+
+.. seealso::
+
+ Module :mod:`dbhash`
+ DBM-style interface to the :mod:`bsddb`
+
+
+.. _bsddb-objects:
+
+Hash, BTree and Record Objects
+------------------------------
+
+Once instantiated, hash, btree and record objects support the same methods as
+dictionaries. In addition, they support the methods listed below.
+
+.. versionchanged:: 2.3.1
+ Added dictionary methods.
+
+
+.. method:: bsddbobject.close()
+
+ Close the underlying file. The object can no longer be accessed. Since there
+ is no open :meth:`open` method for these objects, to open the file again a new
+ :mod:`bsddb` module open function must be called.
+
+
+.. method:: bsddbobject.keys()
+
+ Return the list of keys contained in the DB file. The order of the list is
+ unspecified and should not be relied on. In particular, the order of the list
+ returned is different for different file formats.
+
+
+.. method:: bsddbobject.has_key(key)
+
+ Return ``1`` if the DB file contains the argument as a key.
+
+
+.. method:: bsddbobject.set_location(key)
+
+ Set the cursor to the item indicated by *key* and return a tuple containing the
+ key and its value. For binary tree databases (opened using :func:`btopen`), if
+ *key* does not actually exist in the database, the cursor will point to the next
+ item in sorted order and return that key and value. For other databases,
+ :exc:`KeyError` will be raised if *key* is not found in the database.
+
+
+.. method:: bsddbobject.first()
+
+ Set the cursor to the first item in the DB file and return it. The order of
+ keys in the file is unspecified, except in the case of B-Tree databases. This
+ method raises :exc:`bsddb.error` if the database is empty.
+
+
+.. method:: bsddbobject.next()
+
+ Set the cursor to the next item in the DB file and return it. The order of
+ keys in the file is unspecified, except in the case of B-Tree databases.
+
+
+.. method:: bsddbobject.previous()
+
+ Set the cursor to the previous item in the DB file and return it. The order of
+ keys in the file is unspecified, except in the case of B-Tree databases. This
+ is not supported on hashtable databases (those opened with :func:`hashopen`).
+
+
+.. method:: bsddbobject.last()
+
+ Set the cursor to the last item in the DB file and return it. The order of keys
+ in the file is unspecified. This is not supported on hashtable databases (those
+ opened with :func:`hashopen`). This method raises :exc:`bsddb.error` if the
+ database is empty.
+
+
+.. method:: bsddbobject.sync()
+
+ Synchronize the database on disk.
+
+Example::
+
+ >>> import bsddb
+ >>> db = bsddb.btopen('/tmp/spam.db', 'c')
+ >>> for i in range(10): db['%d'%i] = '%d'% (i*i)
+ ...
+ >>> db['3']
+ '9'
+ >>> db.keys()
+ ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
+ >>> db.first()
+ ('0', '0')
+ >>> db.next()
+ ('1', '1')
+ >>> db.last()
+ ('9', '81')
+ >>> db.set_location('2')
+ ('2', '4')
+ >>> db.previous()
+ ('1', '1')
+ >>> for k, v in db.iteritems():
+ ... print k, v
+ 0 0
+ 1 1
+ 2 4
+ 3 9
+ 4 16
+ 5 25
+ 6 36
+ 7 49
+ 8 64
+ 9 81
+ >>> '8' in db
+ True
+ >>> db.sync()
+ 0
+
--- /dev/null
+
+:mod:`bz2` --- Compression compatible with :program:`bzip2`
+===========================================================
+
+.. module:: bz2
+ :synopsis: Interface to compression and decompression routines compatible with bzip2.
+.. moduleauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
+.. sectionauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
+
+
+.. versionadded:: 2.3
+
+This module provides a comprehensive interface for the bz2 compression library.
+It implements a complete file interface, one-shot (de)compression functions, and
+types for sequential (de)compression.
+
+Here is a resume of the features offered by the bz2 module:
+
+* :class:`BZ2File` class implements a complete file interface, including
+ :meth:`readline`, :meth:`readlines`, :meth:`writelines`, :meth:`seek`, etc;
+
+* :class:`BZ2File` class implements emulated :meth:`seek` support;
+
+* :class:`BZ2File` class implements universal newline support;
+
+* :class:`BZ2File` class offers an optimized line iteration using the readahead
+ algorithm borrowed from file objects;
+
+* Sequential (de)compression supported by :class:`BZ2Compressor` and
+ :class:`BZ2Decompressor` classes;
+
+* One-shot (de)compression supported by :func:`compress` and :func:`decompress`
+ functions;
+
+* Thread safety uses individual locking mechanism;
+
+* Complete inline documentation;
+
+
+(De)compression of files
+------------------------
+
+Handling of compressed files is offered by the :class:`BZ2File` class.
+
+
+.. class:: BZ2File(filename[, mode[, buffering[, compresslevel]]])
+
+ Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)
+ or writing. When opened for writing, the file will be created if it doesn't
+ exist, and truncated otherwise. If *buffering* is given, ``0`` means unbuffered,
+ and larger numbers specify the buffer size; the default is ``0``. If
+ *compresslevel* is given, it must be a number between ``1`` and ``9``; the
+ default is ``9``. Add a ``'U'`` to mode to open the file for input with
+ universal newline support. Any line ending in the input file will be seen as a
+ ``'\n'`` in Python. Also, a file so opened gains the attribute
+ :attr:`newlines`; the value for this attribute is one of ``None`` (no newline
+ read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the newline
+ types seen. Universal newlines are available only when reading. Instances
+ support iteration in the same way as normal :class:`file` instances.
+
+
+.. method:: BZ2File.close()
+
+ Close the file. Sets data attribute :attr:`closed` to true. A closed file cannot
+ be used for further I/O operations. :meth:`close` may be called more than once
+ without error.
+
+
+.. method:: BZ2File.read([size])
+
+ Read at most *size* uncompressed bytes, returned as a string. If the *size*
+ argument is negative or omitted, read until EOF is reached.
+
+
+.. method:: BZ2File.readline([size])
+
+ Return the next line from the file, as a string, retaining newline. A
+ non-negative *size* argument limits the maximum number of bytes to return (an
+ incomplete line may be returned then). Return an empty string at EOF.
+
+
+.. method:: BZ2File.readlines([size])
+
+ Return a list of lines read. The optional *size* argument, if given, is an
+ approximate bound on the total number of bytes in the lines returned.
+
+
+.. method:: BZ2File.xreadlines()
+
+ For backward compatibility. :class:`BZ2File` objects now include the performance
+ optimizations previously implemented in the :mod:`xreadlines` module.
+
+ .. deprecated:: 2.3
+ This exists only for compatibility with the method by this name on :class:`file`
+ objects, which is deprecated. Use ``for line in file`` instead.
+
+
+.. method:: BZ2File.seek(offset[, whence])
+
+ Move to new file position. Argument *offset* is a byte count. Optional argument
+ *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start of file; offset
+ should be ``>= 0``); other values are ``os.SEEK_CUR`` or ``1`` (move relative to
+ current position; offset can be positive or negative), and ``os.SEEK_END`` or
+ ``2`` (move relative to end of file; offset is usually negative, although many
+ platforms allow seeking beyond the end of a file).
+
+ Note that seeking of bz2 files is emulated, and depending on the parameters the
+ operation may be extremely slow.
+
+
+.. method:: BZ2File.tell()
+
+ Return the current file position, an integer (may be a long integer).
+
+
+.. method:: BZ2File.write(data)
+
+ Write string *data* to file. Note that due to buffering, :meth:`close` may be
+ needed before the file on disk reflects the data written.
+
+
+.. method:: BZ2File.writelines(sequence_of_strings)
+
+ Write the sequence of strings to the file. Note that newlines are not added. The
+ sequence can be any iterable object producing strings. This is equivalent to
+ calling write() for each string.
+
+
+Sequential (de)compression
+--------------------------
+
+Sequential compression and decompression is done using the classes
+:class:`BZ2Compressor` and :class:`BZ2Decompressor`.
+
+
+.. class:: BZ2Compressor([compresslevel])
+
+ Create a new compressor object. This object may be used to compress data
+ sequentially. If you want to compress data in one shot, use the :func:`compress`
+ function instead. The *compresslevel* parameter, if given, must be a number
+ between ``1`` and ``9``; the default is ``9``.
+
+
+.. method:: BZ2Compressor.compress(data)
+
+ Provide more data to the compressor object. It will return chunks of compressed
+ data whenever possible. When you've finished providing data to compress, call
+ the :meth:`flush` method to finish the compression process, and return what is
+ left in internal buffers.
+
+
+.. method:: BZ2Compressor.flush()
+
+ Finish the compression process and return what is left in internal buffers. You
+ must not use the compressor object after calling this method.
+
+
+.. class:: BZ2Decompressor()
+
+ Create a new decompressor object. This object may be used to decompress data
+ sequentially. If you want to decompress data in one shot, use the
+ :func:`decompress` function instead.
+
+
+.. method:: BZ2Decompressor.decompress(data)
+
+ Provide more data to the decompressor object. It will return chunks of
+ decompressed data whenever possible. If you try to decompress data after the end
+ of stream is found, :exc:`EOFError` will be raised. If any data was found after
+ the end of stream, it'll be ignored and saved in :attr:`unused_data` attribute.
+
+
+One-shot (de)compression
+------------------------
+
+One-shot compression and decompression is provided through the :func:`compress`
+and :func:`decompress` functions.
+
+
+.. function:: compress(data[, compresslevel])
+
+ Compress *data* in one shot. If you want to compress data sequentially, use an
+ instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter, if
+ given, must be a number between ``1`` and ``9``; the default is ``9``.
+
+
+.. function:: decompress(data)
+
+ Decompress *data* in one shot. If you want to decompress data sequentially, use
+ an instance of :class:`BZ2Decompressor` instead.
+
--- /dev/null
+
+:mod:`calendar` --- General calendar-related functions
+======================================================
+
+.. module:: calendar
+ :synopsis: Functions for working with calendars, including some emulation of the Unix cal
+ program.
+.. sectionauthor:: Drew Csillag <drew_csillag@geocities.com>
+
+
+This module allows you to output calendars like the Unix :program:`cal` program,
+and provides additional useful functions related to the calendar. By default,
+these calendars have Monday as the first day of the week, and Sunday as the last
+(the European convention). Use :func:`setfirstweekday` to set the first day of
+the week to Sunday (6) or to any other weekday. Parameters that specify dates
+are given as integers. For related
+functionality, see also the :mod:`datetime` and :mod:`time` modules.
+
+Most of these functions and classses rely on the :mod:`datetime` module which
+uses an idealized calendar, the current Gregorian calendar indefinitely extended
+in both directions. This matches the definition of the "proleptic Gregorian"
+calendar in Dershowitz and Reingold's book "Calendrical Calculations", where
+it's the base calendar for all computations.
+
+
+.. class:: Calendar([firstweekday])
+
+ Creates a :class:`Calendar` object. *firstweekday* is an integer specifying the
+ first day of the week. ``0`` is Monday (the default), ``6`` is Sunday.
+
+ A :class:`Calendar` object provides several methods that can be used for
+ preparing the calendar data for formatting. This class doesn't do any formatting
+ itself. This is the job of subclasses.
+
+ .. versionadded:: 2.5
+
+:class:`Calendar` instances have the following methods:
+
+
+.. method:: Calendar.iterweekdays(weekday)
+
+ Return an iterator for the week day numbers that will be used for one week. The
+ first number from the iterator will be the same as the number returned by
+ :meth:`firstweekday`.
+
+
+.. method:: Calendar.itermonthdates(year, month)
+
+ Return an iterator for the month *month* (1-12) in the year *year*. This
+ iterator will return all days (as :class:`datetime.date` objects) for the month
+ and all days before the start of the month or after the end of the month that
+ are required to get a complete week.
+
+
+.. method:: Calendar.itermonthdays2(year, month)
+
+ Return an iterator for the month *month* in the year *year* similar to
+ :meth:`itermonthdates`. Days returned will be tuples consisting of a day number
+ and a week day number.
+
+
+.. method:: Calendar.itermonthdays(year, month)
+
+ Return an iterator for the month *month* in the year *year* similar to
+ :meth:`itermonthdates`. Days returned will simply be day numbers.
+
+
+.. method:: Calendar.monthdatescalendar(year, month)
+
+ Return a list of the weeks in the month *month* of the *year* as full weeks.
+ Weeks are lists of seven :class:`datetime.date` objects.
+
+
+.. method:: Calendar.monthdays2calendar(year, month)
+
+ Return a list of the weeks in the month *month* of the *year* as full weeks.
+ Weeks are lists of seven tuples of day numbers and weekday numbers.
+
+
+.. method:: Calendar.monthdayscalendar(year, month)
+
+ Return a list of the weeks in the month *month* of the *year* as full weeks.
+ Weeks are lists of seven day numbers.
+
+
+.. method:: Calendar.yeardatescalendar(year, month[, width])
+
+ Return the data for the specified year ready for formatting. The return value is
+ a list of month rows. Each month row contains up to *width* months (defaulting
+ to 3). Each month contains between 4 and 6 weeks and each week contains 1--7
+ days. Days are :class:`datetime.date` objects.
+
+
+.. method:: Calendar.yeardays2calendar(year, month[, width])
+
+ Return the data for the specified year ready for formatting (similar to
+ :meth:`yeardatescalendar`). Entries in the week lists are tuples of day numbers
+ and weekday numbers. Day numbers outside this month are zero.
+
+
+.. method:: Calendar.yeardayscalendar(year, month[, width])
+
+ Return the data for the specified year ready for formatting (similar to
+ :meth:`yeardatescalendar`). Entries in the week lists are day numbers. Day
+ numbers outside this month are zero.
+
+
+.. class:: TextCalendar([firstweekday])
+
+ This class can be used to generate plain text calendars.
+
+ .. versionadded:: 2.5
+
+:class:`TextCalendar` instances have the following methods:
+
+
+.. method:: TextCalendar.formatmonth(theyear, themonth[, w[, l]])
+
+ Return a month's calendar in a multi-line string. If *w* is provided, it
+ specifies the width of the date columns, which are centered. If *l* is given, it
+ specifies the number of lines that each week will use. Depends on the first
+ weekday as set by :func:`setfirstweekday`.
+
+
+.. method:: TextCalendar.prmonth(theyear, themonth[, w[, l]])
+
+ Print a month's calendar as returned by :meth:`formatmonth`.
+
+
+.. method:: TextCalendar.formatyear(theyear, themonth[, w[, l[, c[, m]]]])
+
+ Return a *m*-column calendar for an entire year as a multi-line string. Optional
+ parameters *w*, *l*, and *c* are for date column width, lines per week, and
+ number of spaces between month columns, respectively. Depends on the first
+ weekday as set by :meth:`setfirstweekday`. The earliest year for which a
+ calendar can be generated is platform-dependent.
+
+
+.. method:: TextCalendar.pryear(theyear[, w[, l[, c[, m]]]])
+
+ Print the calendar for an entire year as returned by :meth:`formatyear`.
+
+
+.. class:: HTMLCalendar([firstweekday])
+
+ This class can be used to generate HTML calendars.
+
+ .. versionadded:: 2.5
+
+:class:`HTMLCalendar` instances have the following methods:
+
+
+.. method:: HTMLCalendar.formatmonth(theyear, themonth[, withyear])
+
+ Return a month's calendar as an HTML table. If *withyear* is true the year will
+ be included in the header, otherwise just the month name will be used.
+
+
+.. method:: HTMLCalendar.formatyear(theyear, themonth[, width])
+
+ Return a year's calendar as an HTML table. *width* (defaulting to 3) specifies
+ the number of months per row.
+
+
+.. method:: HTMLCalendar.formatyearpage(theyear, themonth[, width[, css[, encoding]]])
+
+ Return a year's calendar as a complete HTML page. *width* (defaulting to 3)
+ specifies the number of months per row. *css* is the name for the cascading
+ style sheet to be used. :const:`None` can be passed if no style sheet should be
+ used. *encoding* specifies the encoding to be used for the output (defaulting to
+ the system default encoding).
+
+
+.. class:: LocaleTextCalendar([firstweekday[, locale]])
+
+ This subclass of :class:`TextCalendar` can be passed a locale name in the
+ constructor and will return month and weekday names in the specified locale. If
+ this locale includes an encoding all strings containing month and weekday names
+ will be returned as unicode.
+
+ .. versionadded:: 2.5
+
+
+.. class:: LocaleHTMLCalendar([firstweekday[, locale]])
+
+ This subclass of :class:`HTMLCalendar` can be passed a locale name in the
+ constructor and will return month and weekday names in the specified locale. If
+ this locale includes an encoding all strings containing month and weekday names
+ will be returned as unicode.
+
+ .. versionadded:: 2.5
+
+For simple text calendars this module provides the following functions.
+
+
+.. function:: setfirstweekday(weekday)
+
+ Sets the weekday (``0`` is Monday, ``6`` is Sunday) to start each week. The
+ values :const:`MONDAY`, :const:`TUESDAY`, :const:`WEDNESDAY`, :const:`THURSDAY`,
+ :const:`FRIDAY`, :const:`SATURDAY`, and :const:`SUNDAY` are provided for
+ convenience. For example, to set the first weekday to Sunday::
+
+ import calendar
+ calendar.setfirstweekday(calendar.SUNDAY)
+
+ .. versionadded:: 2.0
+
+
+.. function:: firstweekday()
+
+ Returns the current setting for the weekday to start each week.
+
+ .. versionadded:: 2.0
+
+
+.. function:: isleap(year)
+
+ Returns :const:`True` if *year* is a leap year, otherwise :const:`False`.
+
+
+.. function:: leapdays(y1, y2)
+
+ Returns the number of leap years in the range from *y1* to *y2* (exclusive),
+ where *y1* and *y2* are years.
+
+ .. versionchanged:: 2.0
+ This function didn't work for ranges spanning a century change in Python
+ 1.5.2.
+
+
+.. function:: weekday(year, month, day)
+
+ Returns the day of the week (``0`` is Monday) for *year* (``1970``--...),
+ *month* (``1``--``12``), *day* (``1``--``31``).
+
+
+.. function:: weekheader(n)
+
+ Return a header containing abbreviated weekday names. *n* specifies the width in
+ characters for one weekday.
+
+
+.. function:: monthrange(year, month)
+
+ Returns weekday of first day of the month and number of days in month, for the
+ specified *year* and *month*.
+
+
+.. function:: monthcalendar(year, month)
+
+ Returns a matrix representing a month's calendar. Each row represents a week;
+ days outside of the month a represented by zeros. Each week begins with Monday
+ unless set by :func:`setfirstweekday`.
+
+
+.. function:: prmonth(theyear, themonth[, w[, l]])
+
+ Prints a month's calendar as returned by :func:`month`.
+
+
+.. function:: month(theyear, themonth[, w[, l]])
+
+ Returns a month's calendar in a multi-line string using the :meth:`formatmonth`
+ of the :class:`TextCalendar` class.
+
+ .. versionadded:: 2.0
+
+
+.. function:: prcal(year[, w[, l[c]]])
+
+ Prints the calendar for an entire year as returned by :func:`calendar`.
+
+
+.. function:: calendar(year[, w[, l[c]]])
+
+ Returns a 3-column calendar for an entire year as a multi-line string using the
+ :meth:`formatyear` of the :class:`TextCalendar` class.
+
+ .. versionadded:: 2.0
+
+
+.. function:: timegm(tuple)
+
+ An unrelated but handy function that takes a time tuple such as returned by the
+ :func:`gmtime` function in the :mod:`time` module, and returns the corresponding
+ Unix timestamp value, assuming an epoch of 1970, and the POSIX encoding. In
+ fact, :func:`time.gmtime` and :func:`timegm` are each others' inverse.
+
+ .. versionadded:: 2.0
+
+The :mod:`calendar` module exports the following data attributes:
+
+
+.. data:: day_name
+
+ An array that represents the days of the week in the current locale.
+
+
+.. data:: day_abbr
+
+ An array that represents the abbreviated days of the week in the current locale.
+
+
+.. data:: month_name
+
+ An array that represents the months of the year in the current locale. This
+ follows normal convention of January being month number 1, so it has a length of
+ 13 and ``month_name[0]`` is the empty string.
+
+
+.. data:: month_abbr
+
+ An array that represents the abbreviated months of the year in the current
+ locale. This follows normal convention of January being month number 1, so it
+ has a length of 13 and ``month_abbr[0]`` is the empty string.
+
+
+.. seealso::
+
+ Module :mod:`datetime`
+ Object-oriented interface to dates and times with similar functionality to the
+ :mod:`time` module.
+
+ Module :mod:`time`
+ Low-level time related functions.
+
--- /dev/null
+
+.. _toolbox:
+
+*********************
+MacOS Toolbox Modules
+*********************
+
+There are a set of modules that provide interfaces to various MacOS toolboxes.
+If applicable the module will define a number of Python objects for the various
+structures declared by the toolbox, and operations will be implemented as
+methods of the object. Other operations will be implemented as functions in the
+module. Not all operations possible in C will also be possible in Python
+(callbacks are often a problem), and parameters will occasionally be different
+in Python (input and output buffers, especially). All methods and functions
+have a :attr:`__doc__` string describing their arguments and return values, and
+for additional description you are referred to `Inside Macintosh
+<http://developer.apple.com/documentation/macos8/mac8.html>`_ or similar works.
+
+These modules all live in a package called :mod:`Carbon`. Despite that name they
+are not all part of the Carbon framework: CF is really in the CoreFoundation
+framework and Qt is in the QuickTime framework. The normal use pattern is ::
+
+ from Carbon import AE
+
+**Warning!** These modules are not yet documented. If you wish to contribute
+documentation of any of these modules, please get in touch with docs@python.org.
+
+
+:mod:`Carbon.AE` --- Apple Events
+=================================
+
+.. module:: Carbon.AE
+ :platform: Mac
+ :synopsis: Interface to the Apple Events toolbox.
+
+
+
+:mod:`Carbon.AH` --- Apple Help
+===============================
+
+.. module:: Carbon.AH
+ :platform: Mac
+ :synopsis: Interface to the Apple Help manager.
+
+
+
+:mod:`Carbon.App` --- Appearance Manager
+========================================
+
+.. module:: Carbon.App
+ :platform: Mac
+ :synopsis: Interface to the Appearance Manager.
+
+
+
+:mod:`Carbon.CF` --- Core Foundation
+====================================
+
+.. module:: Carbon.CF
+ :platform: Mac
+ :synopsis: Interface to the Core Foundation.
+
+
+The ``CFBase``, ``CFArray``, ``CFData``, ``CFDictionary``, ``CFString`` and
+``CFURL`` objects are supported, some only partially.
+
+
+:mod:`Carbon.CG` --- Core Graphics
+==================================
+
+.. module:: Carbon.CG
+ :platform: Mac
+ :synopsis: Interface to the Component Manager.
+
+
+
+:mod:`Carbon.CarbonEvt` --- Carbon Event Manager
+================================================
+
+.. module:: Carbon.CarbonEvt
+ :platform: Mac
+ :synopsis: Interface to the Carbon Event Manager.
+
+
+
+:mod:`Carbon.Cm` --- Component Manager
+======================================
+
+.. module:: Carbon.Cm
+ :platform: Mac
+ :synopsis: Interface to the Component Manager.
+
+
+
+:mod:`Carbon.Ctl` --- Control Manager
+=====================================
+
+.. module:: Carbon.Ctl
+ :platform: Mac
+ :synopsis: Interface to the Control Manager.
+
+
+
+:mod:`Carbon.Dlg` --- Dialog Manager
+====================================
+
+.. module:: Carbon.Dlg
+ :platform: Mac
+ :synopsis: Interface to the Dialog Manager.
+
+
+
+:mod:`Carbon.Evt` --- Event Manager
+===================================
+
+.. module:: Carbon.Evt
+ :platform: Mac
+ :synopsis: Interface to the classic Event Manager.
+
+
+
+:mod:`Carbon.Fm` --- Font Manager
+=================================
+
+.. module:: Carbon.Fm
+ :platform: Mac
+ :synopsis: Interface to the Font Manager.
+
+
+
+:mod:`Carbon.Folder` --- Folder Manager
+=======================================
+
+.. module:: Carbon.Folder
+ :platform: Mac
+ :synopsis: Interface to the Folder Manager.
+
+
+
+:mod:`Carbon.Help` --- Help Manager
+===================================
+
+.. module:: Carbon.Help
+ :platform: Mac
+ :synopsis: Interface to the Carbon Help Manager.
+
+
+
+:mod:`Carbon.List` --- List Manager
+===================================
+
+.. module:: Carbon.List
+ :platform: Mac
+ :synopsis: Interface to the List Manager.
+
+
+
+:mod:`Carbon.Menu` --- Menu Manager
+===================================
+
+.. module:: Carbon.Menu
+ :platform: Mac
+ :synopsis: Interface to the Menu Manager.
+
+
+
+:mod:`Carbon.Mlte` --- MultiLingual Text Editor
+===============================================
+
+.. module:: Carbon.Mlte
+ :platform: Mac
+ :synopsis: Interface to the MultiLingual Text Editor.
+
+
+
+:mod:`Carbon.Qd` --- QuickDraw
+==============================
+
+.. module:: Carbon.Qd
+ :platform: Mac
+ :synopsis: Interface to the QuickDraw toolbox.
+
+
+
+:mod:`Carbon.Qdoffs` --- QuickDraw Offscreen
+============================================
+
+.. module:: Carbon.Qdoffs
+ :platform: Mac
+ :synopsis: Interface to the QuickDraw Offscreen APIs.
+
+
+
+:mod:`Carbon.Qt` --- QuickTime
+==============================
+
+.. module:: Carbon.Qt
+ :platform: Mac
+ :synopsis: Interface to the QuickTime toolbox.
+
+
+
+:mod:`Carbon.Res` --- Resource Manager and Handles
+==================================================
+
+.. module:: Carbon.Res
+ :platform: Mac
+ :synopsis: Interface to the Resource Manager and Handles.
+
+
+
+:mod:`Carbon.Scrap` --- Scrap Manager
+=====================================
+
+.. module:: Carbon.Scrap
+ :platform: Mac
+ :synopsis: The Scrap Manager provides basic services for implementing cut & paste and
+ clipboard operations.
+
+
+This module is only fully available on MacOS9 and earlier under classic PPC
+MacPython. Very limited functionality is available under Carbon MacPython.
+
+.. index:: single: Scrap Manager
+
+The Scrap Manager supports the simplest form of cut & paste operations on the
+Macintosh. It can be use for both inter- and intra-application clipboard
+operations.
+
+The :mod:`Scrap` module provides low-level access to the functions of the Scrap
+Manager. It contains the following functions:
+
+
+.. function:: InfoScrap()
+
+ Return current information about the scrap. The information is encoded as a
+ tuple containing the fields ``(size, handle, count, state, path)``.
+
+ +----------+---------------------------------------------+
+ | Field | Meaning |
+ +==========+=============================================+
+ | *size* | Size of the scrap in bytes. |
+ +----------+---------------------------------------------+
+ | *handle* | Resource object representing the scrap. |
+ +----------+---------------------------------------------+
+ | *count* | Serial number of the scrap contents. |
+ +----------+---------------------------------------------+
+ | *state* | Integer; positive if in memory, ``0`` if on |
+ | | disk, negative if uninitialized. |
+ +----------+---------------------------------------------+
+ | *path* | Filename of the scrap when stored on disk. |
+ +----------+---------------------------------------------+
+
+
+.. seealso::
+
+ `Scrap Manager <http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-109.html>`_
+ Apple's documentation for the Scrap Manager gives a lot of useful information
+ about using the Scrap Manager in applications.
+
+
+
+:mod:`Carbon.Snd` --- Sound Manager
+===================================
+
+.. module:: Carbon.Snd
+ :platform: Mac
+ :synopsis: Interface to the Sound Manager.
+
+
+
+:mod:`Carbon.TE` --- TextEdit
+=============================
+
+.. module:: Carbon.TE
+ :platform: Mac
+ :synopsis: Interface to TextEdit.
+
+
+
+:mod:`Carbon.Win` --- Window Manager
+====================================
+
+.. module:: Carbon.Win
+ :platform: Mac
+ :synopsis: Interface to the Window Manager.
+
+
--- /dev/null
+
+:mod:`cd` --- CD-ROM access on SGI systems
+==========================================
+
+.. module:: cd
+ :platform: IRIX
+ :synopsis: Interface to the CD-ROM on Silicon Graphics systems.
+
+
+This module provides an interface to the Silicon Graphics CD library. It is
+available only on Silicon Graphics systems.
+
+The way the library works is as follows. A program opens the CD-ROM device with
+:func:`open` and creates a parser to parse the data from the CD with
+:func:`createparser`. The object returned by :func:`open` can be used to read
+data from the CD, but also to get status information for the CD-ROM device, and
+to get information about the CD, such as the table of contents. Data from the
+CD is passed to the parser, which parses the frames, and calls any callback
+functions that have previously been added.
+
+An audio CD is divided into :dfn:`tracks` or :dfn:`programs` (the terms are used
+interchangeably). Tracks can be subdivided into :dfn:`indices`. An audio CD
+contains a :dfn:`table of contents` which gives the starts of the tracks on the
+CD. Index 0 is usually the pause before the start of a track. The start of the
+track as given by the table of contents is normally the start of index 1.
+
+Positions on a CD can be represented in two ways. Either a frame number or a
+tuple of three values, minutes, seconds and frames. Most functions use the
+latter representation. Positions can be both relative to the beginning of the
+CD, and to the beginning of the track.
+
+Module :mod:`cd` defines the following functions and constants:
+
+
+.. function:: createparser()
+
+ Create and return an opaque parser object. The methods of the parser object are
+ described below.
+
+
+.. function:: msftoframe(minutes, seconds, frames)
+
+ Converts a ``(minutes, seconds, frames)`` triple representing time in absolute
+ time code into the corresponding CD frame number.
+
+
+.. function:: open([device[, mode]])
+
+ Open the CD-ROM device. The return value is an opaque player object; methods of
+ the player object are described below. The device is the name of the SCSI
+ device file, e.g. ``'/dev/scsi/sc0d4l0'``, or ``None``. If omitted or ``None``,
+ the hardware inventory is consulted to locate a CD-ROM drive. The *mode*, if
+ not omitted, should be the string ``'r'``.
+
+The module defines the following variables:
+
+
+.. exception:: error
+
+ Exception raised on various errors.
+
+
+.. data:: DATASIZE
+
+ The size of one frame's worth of audio data. This is the size of the audio data
+ as passed to the callback of type ``audio``.
+
+
+.. data:: BLOCKSIZE
+
+ The size of one uninterpreted frame of audio data.
+
+The following variables are states as returned by :func:`getstatus`:
+
+
+.. data:: READY
+
+ The drive is ready for operation loaded with an audio CD.
+
+
+.. data:: NODISC
+
+ The drive does not have a CD loaded.
+
+
+.. data:: CDROM
+
+ The drive is loaded with a CD-ROM. Subsequent play or read operations will
+ return I/O errors.
+
+
+.. data:: ERROR
+
+ An error occurred while trying to read the disc or its table of contents.
+
+
+.. data:: PLAYING
+
+ The drive is in CD player mode playing an audio CD through its audio jacks.
+
+
+.. data:: PAUSED
+
+ The drive is in CD layer mode with play paused.
+
+
+.. data:: STILL
+
+ The equivalent of :const:`PAUSED` on older (non 3301) model Toshiba CD-ROM
+ drives. Such drives have never been shipped by SGI.
+
+
+.. data:: audio
+ pnum
+ index
+ ptime
+ atime
+ catalog
+ ident
+ control
+
+ Integer constants describing the various types of parser callbacks that can be
+ set by the :meth:`addcallback` method of CD parser objects (see below).
+
+
+.. _player-objects:
+
+Player Objects
+--------------
+
+Player objects (returned by :func:`open`) have the following methods:
+
+
+.. method:: CD player.allowremoval()
+
+ Unlocks the eject button on the CD-ROM drive permitting the user to eject the
+ caddy if desired.
+
+
+.. method:: CD player.bestreadsize()
+
+ Returns the best value to use for the *num_frames* parameter of the
+ :meth:`readda` method. Best is defined as the value that permits a continuous
+ flow of data from the CD-ROM drive.
+
+
+.. method:: CD player.close()
+
+ Frees the resources associated with the player object. After calling
+ :meth:`close`, the methods of the object should no longer be used.
+
+
+.. method:: CD player.eject()
+
+ Ejects the caddy from the CD-ROM drive.
+
+
+.. method:: CD player.getstatus()
+
+ Returns information pertaining to the current state of the CD-ROM drive. The
+ returned information is a tuple with the following values: *state*, *track*,
+ *rtime*, *atime*, *ttime*, *first*, *last*, *scsi_audio*, *cur_block*. *rtime*
+ is the time relative to the start of the current track; *atime* is the time
+ relative to the beginning of the disc; *ttime* is the total time on the disc.
+ For more information on the meaning of the values, see the man page
+ :manpage:`CDgetstatus(3dm)`. The value of *state* is one of the following:
+ :const:`ERROR`, :const:`NODISC`, :const:`READY`, :const:`PLAYING`,
+ :const:`PAUSED`, :const:`STILL`, or :const:`CDROM`.
+
+
+.. method:: CD player.gettrackinfo(track)
+
+ Returns information about the specified track. The returned information is a
+ tuple consisting of two elements, the start time of the track and the duration
+ of the track.
+
+
+.. method:: CD player.msftoblock(min, sec, frame)
+
+ Converts a minutes, seconds, frames triple representing a time in absolute time
+ code into the corresponding logical block number for the given CD-ROM drive.
+ You should use :func:`msftoframe` rather than :meth:`msftoblock` for comparing
+ times. The logical block number differs from the frame number by an offset
+ required by certain CD-ROM drives.
+
+
+.. method:: CD player.play(start, play)
+
+ Starts playback of an audio CD in the CD-ROM drive at the specified track. The
+ audio output appears on the CD-ROM drive's headphone and audio jacks (if
+ fitted). Play stops at the end of the disc. *start* is the number of the track
+ at which to start playing the CD; if *play* is 0, the CD will be set to an
+ initial paused state. The method :meth:`togglepause` can then be used to
+ commence play.
+
+
+.. method:: CD player.playabs(minutes, seconds, frames, play)
+
+ Like :meth:`play`, except that the start is given in minutes, seconds, and
+ frames instead of a track number.
+
+
+.. method:: CD player.playtrack(start, play)
+
+ Like :meth:`play`, except that playing stops at the end of the track.
+
+
+.. method:: CD player.playtrackabs(track, minutes, seconds, frames, play)
+
+ Like :meth:`play`, except that playing begins at the specified absolute time and
+ ends at the end of the specified track.
+
+
+.. method:: CD player.preventremoval()
+
+ Locks the eject button on the CD-ROM drive thus preventing the user from
+ arbitrarily ejecting the caddy.
+
+
+.. method:: CD player.readda(num_frames)
+
+ Reads the specified number of frames from an audio CD mounted in the CD-ROM
+ drive. The return value is a string representing the audio frames. This string
+ can be passed unaltered to the :meth:`parseframe` method of the parser object.
+
+
+.. method:: CD player.seek(minutes, seconds, frames)
+
+ Sets the pointer that indicates the starting point of the next read of digital
+ audio data from a CD-ROM. The pointer is set to an absolute time code location
+ specified in *minutes*, *seconds*, and *frames*. The return value is the
+ logical block number to which the pointer has been set.
+
+
+.. method:: CD player.seekblock(block)
+
+ Sets the pointer that indicates the starting point of the next read of digital
+ audio data from a CD-ROM. The pointer is set to the specified logical block
+ number. The return value is the logical block number to which the pointer has
+ been set.
+
+
+.. method:: CD player.seektrack(track)
+
+ Sets the pointer that indicates the starting point of the next read of digital
+ audio data from a CD-ROM. The pointer is set to the specified track. The
+ return value is the logical block number to which the pointer has been set.
+
+
+.. method:: CD player.stop()
+
+ Stops the current playing operation.
+
+
+.. method:: CD player.togglepause()
+
+ Pauses the CD if it is playing, and makes it play if it is paused.
+
+
+.. _cd-parser-objects:
+
+Parser Objects
+--------------
+
+Parser objects (returned by :func:`createparser`) have the following methods:
+
+
+.. method:: CD parser.addcallback(type, func, arg)
+
+ Adds a callback for the parser. The parser has callbacks for eight different
+ types of data in the digital audio data stream. Constants for these types are
+ defined at the :mod:`cd` module level (see above). The callback is called as
+ follows: ``func(arg, type, data)``, where *arg* is the user supplied argument,
+ *type* is the particular type of callback, and *data* is the data returned for
+ this *type* of callback. The type of the data depends on the *type* of callback
+ as follows:
+
+ +-------------+---------------------------------------------+
+ | Type | Value |
+ +=============+=============================================+
+ | ``audio`` | String which can be passed unmodified to |
+ | | :func:`al.writesamps`. |
+ +-------------+---------------------------------------------+
+ | ``pnum`` | Integer giving the program (track) number. |
+ +-------------+---------------------------------------------+
+ | ``index`` | Integer giving the index number. |
+ +-------------+---------------------------------------------+
+ | ``ptime`` | Tuple consisting of the program time in |
+ | | minutes, seconds, and frames. |
+ +-------------+---------------------------------------------+
+ | ``atime`` | Tuple consisting of the absolute time in |
+ | | minutes, seconds, and frames. |
+ +-------------+---------------------------------------------+
+ | ``catalog`` | String of 13 characters, giving the catalog |
+ | | number of the CD. |
+ +-------------+---------------------------------------------+
+ | ``ident`` | String of 12 characters, giving the ISRC |
+ | | identification number of the recording. |
+ | | The string consists of two characters |
+ | | country code, three characters owner code, |
+ | | two characters giving the year, and five |
+ | | characters giving a serial number. |
+ +-------------+---------------------------------------------+
+ | ``control`` | Integer giving the control bits from the CD |
+ | | subcode data |
+ +-------------+---------------------------------------------+
+
+
+.. method:: CD parser.deleteparser()
+
+ Deletes the parser and frees the memory it was using. The object should not be
+ used after this call. This call is done automatically when the last reference
+ to the object is removed.
+
+
+.. method:: CD parser.parseframe(frame)
+
+ Parses one or more frames of digital audio data from a CD such as returned by
+ :meth:`readda`. It determines which subcodes are present in the data. If these
+ subcodes have changed since the last frame, then :meth:`parseframe` executes a
+ callback of the appropriate type passing to it the subcode data found in the
+ frame. Unlike the C function, more than one frame of digital audio data can be
+ passed to this method.
+
+
+.. method:: CD parser.removecallback(type)
+
+ Removes the callback for the given *type*.
+
+
+.. method:: CD parser.resetparser()
+
+ Resets the fields of the parser used for tracking subcodes to an initial state.
+ :meth:`resetparser` should be called after the disc has been changed.
+
--- /dev/null
+
+:mod:`cgi` --- Common Gateway Interface support.
+================================================
+
+.. module:: cgi
+ :synopsis: Helpers for running Python scripts via the Common Gateway Interface.
+
+
+.. index::
+ pair: WWW; server
+ pair: CGI; protocol
+ pair: HTTP; protocol
+ pair: MIME; headers
+ single: URL
+ single: Common Gateway Interface
+
+Support module for Common Gateway Interface (CGI) scripts.
+
+This module defines a number of utilities for use by CGI scripts written in
+Python.
+
+
+Introduction
+------------
+
+.. _cgi-intro:
+
+A CGI script is invoked by an HTTP server, usually to process user input
+submitted through an HTML ``<FORM>`` or ``<ISINDEX>`` element.
+
+Most often, CGI scripts live in the server's special :file:`cgi-bin` directory.
+The HTTP server places all sorts of information about the request (such as the
+client's hostname, the requested URL, the query string, and lots of other
+goodies) in the script's shell environment, executes the script, and sends the
+script's output back to the client.
+
+The script's input is connected to the client too, and sometimes the form data
+is read this way; at other times the form data is passed via the "query string"
+part of the URL. This module is intended to take care of the different cases
+and provide a simpler interface to the Python script. It also provides a number
+of utilities that help in debugging scripts, and the latest addition is support
+for file uploads from a form (if your browser supports it).
+
+The output of a CGI script should consist of two sections, separated by a blank
+line. The first section contains a number of headers, telling the client what
+kind of data is following. Python code to generate a minimal header section
+looks like this::
+
+ print "Content-Type: text/html" # HTML is following
+ print # blank line, end of headers
+
+The second section is usually HTML, which allows the client software to display
+nicely formatted text with header, in-line images, etc. Here's Python code that
+prints a simple piece of HTML::
+
+ print "<TITLE>CGI script output</TITLE>"
+ print "<H1>This is my first CGI script</H1>"
+ print "Hello, world!"
+
+
+.. _using-the-cgi-module:
+
+Using the cgi module
+--------------------
+
+Begin by writing ``import cgi``. Do not use ``from cgi import *`` --- the
+module defines all sorts of names for its own use or for backward compatibility
+that you don't want in your namespace.
+
+When you write a new script, consider adding the line::
+
+ import cgitb; cgitb.enable()
+
+This activates a special exception handler that will display detailed reports in
+the Web browser if any errors occur. If you'd rather not show the guts of your
+program to users of your script, you can have the reports saved to files
+instead, with a line like this::
+
+ import cgitb; cgitb.enable(display=0, logdir="/tmp")
+
+It's very helpful to use this feature during script development. The reports
+produced by :mod:`cgitb` provide information that can save you a lot of time in
+tracking down bugs. You can always remove the ``cgitb`` line later when you
+have tested your script and are confident that it works correctly.
+
+To get at submitted form data, it's best to use the :class:`FieldStorage` class.
+The other classes defined in this module are provided mostly for backward
+compatibility. Instantiate it exactly once, without arguments. This reads the
+form contents from standard input or the environment (depending on the value of
+various environment variables set according to the CGI standard). Since it may
+consume standard input, it should be instantiated only once.
+
+The :class:`FieldStorage` instance can be indexed like a Python dictionary, and
+also supports the standard dictionary methods :meth:`has_key` and :meth:`keys`.
+The built-in :func:`len` is also supported. Form fields containing empty
+strings are ignored and do not appear in the dictionary; to keep such values,
+provide a true value for the optional *keep_blank_values* keyword parameter when
+creating the :class:`FieldStorage` instance.
+
+For instance, the following code (which assumes that the
+:mailheader:`Content-Type` header and blank line have already been printed)
+checks that the fields ``name`` and ``addr`` are both set to a non-empty
+string::
+
+ form = cgi.FieldStorage()
+ if not (form.has_key("name") and form.has_key("addr")):
+ print "<H1>Error</H1>"
+ print "Please fill in the name and addr fields."
+ return
+ print "<p>name:", form["name"].value
+ print "<p>addr:", form["addr"].value
+ ...further form processing here...
+
+Here the fields, accessed through ``form[key]``, are themselves instances of
+:class:`FieldStorage` (or :class:`MiniFieldStorage`, depending on the form
+encoding). The :attr:`value` attribute of the instance yields the string value
+of the field. The :meth:`getvalue` method returns this string value directly;
+it also accepts an optional second argument as a default to return if the
+requested key is not present.
+
+If the submitted form data contains more than one field with the same name, the
+object retrieved by ``form[key]`` is not a :class:`FieldStorage` or
+:class:`MiniFieldStorage` instance but a list of such instances. Similarly, in
+this situation, ``form.getvalue(key)`` would return a list of strings. If you
+expect this possibility (when your HTML form contains multiple fields with the
+same name), use the :func:`getlist` function, which always returns a list of
+values (so that you do not need to special-case the single item case). For
+example, this code concatenates any number of username fields, separated by
+commas::
+
+ value = form.getlist("username")
+ usernames = ",".join(value)
+
+If a field represents an uploaded file, accessing the value via the
+:attr:`value` attribute or the :func:`getvalue` method reads the entire file in
+memory as a string. This may not be what you want. You can test for an uploaded
+file by testing either the :attr:`filename` attribute or the :attr:`file`
+attribute. You can then read the data at leisure from the :attr:`file`
+attribute::
+
+ fileitem = form["userfile"]
+ if fileitem.file:
+ # It's an uploaded file; count lines
+ linecount = 0
+ while 1:
+ line = fileitem.file.readline()
+ if not line: break
+ linecount = linecount + 1
+
+The file upload draft standard entertains the possibility of uploading multiple
+files from one field (using a recursive :mimetype:`multipart/\*` encoding).
+When this occurs, the item will be a dictionary-like :class:`FieldStorage` item.
+This can be determined by testing its :attr:`type` attribute, which should be
+:mimetype:`multipart/form-data` (or perhaps another MIME type matching
+:mimetype:`multipart/\*`). In this case, it can be iterated over recursively
+just like the top-level form object.
+
+When a form is submitted in the "old" format (as the query string or as a single
+data part of type :mimetype:`application/x-www-form-urlencoded`), the items will
+actually be instances of the class :class:`MiniFieldStorage`. In this case, the
+:attr:`list`, :attr:`file`, and :attr:`filename` attributes are always ``None``.
+
+
+Higher Level Interface
+----------------------
+
+.. versionadded:: 2.2
+
+The previous section explains how to read CGI form data using the
+:class:`FieldStorage` class. This section describes a higher level interface
+which was added to this class to allow one to do it in a more readable and
+intuitive way. The interface doesn't make the techniques described in previous
+sections obsolete --- they are still useful to process file uploads efficiently,
+for example.
+
+.. % XXX: Is this true ?
+
+The interface consists of two simple methods. Using the methods you can process
+form data in a generic way, without the need to worry whether only one or more
+values were posted under one name.
+
+In the previous section, you learned to write following code anytime you
+expected a user to post more than one value under one name::
+
+ item = form.getvalue("item")
+ if isinstance(item, list):
+ # The user is requesting more than one item.
+ else:
+ # The user is requesting only one item.
+
+This situation is common for example when a form contains a group of multiple
+checkboxes with the same name::
+
+ <input type="checkbox" name="item" value="1" />
+ <input type="checkbox" name="item" value="2" />
+
+In most situations, however, there's only one form control with a particular
+name in a form and then you expect and need only one value associated with this
+name. So you write a script containing for example this code::
+
+ user = form.getvalue("user").upper()
+
+The problem with the code is that you should never expect that a client will
+provide valid input to your scripts. For example, if a curious user appends
+another ``user=foo`` pair to the query string, then the script would crash,
+because in this situation the ``getvalue("user")`` method call returns a list
+instead of a string. Calling the :meth:`toupper` method on a list is not valid
+(since lists do not have a method of this name) and results in an
+:exc:`AttributeError` exception.
+
+Therefore, the appropriate way to read form data values was to always use the
+code which checks whether the obtained value is a single value or a list of
+values. That's annoying and leads to less readable scripts.
+
+A more convenient approach is to use the methods :meth:`getfirst` and
+:meth:`getlist` provided by this higher level interface.
+
+
+.. method:: FieldStorage.getfirst(name[, default])
+
+ This method always returns only one value associated with form field *name*.
+ The method returns only the first value in case that more values were posted
+ under such name. Please note that the order in which the values are received
+ may vary from browser to browser and should not be counted on. [#]_ If no such
+ form field or value exists then the method returns the value specified by the
+ optional parameter *default*. This parameter defaults to ``None`` if not
+ specified.
+
+
+.. method:: FieldStorage.getlist(name)
+
+ This method always returns a list of values associated with form field *name*.
+ The method returns an empty list if no such form field or value exists for
+ *name*. It returns a list consisting of one item if only one such value exists.
+
+Using these methods you can write nice compact code::
+
+ import cgi
+ form = cgi.FieldStorage()
+ user = form.getfirst("user", "").upper() # This way it's safe.
+ for item in form.getlist("item"):
+ do_something(item)
+
+
+Old classes
+-----------
+
+These classes, present in earlier versions of the :mod:`cgi` module, are still
+supported for backward compatibility. New applications should use the
+:class:`FieldStorage` class.
+
+:class:`SvFormContentDict` stores single value form content as dictionary; it
+assumes each field name occurs in the form only once.
+
+:class:`FormContentDict` stores multiple value form content as a dictionary (the
+form items are lists of values). Useful if your form contains multiple fields
+with the same name.
+
+Other classes (:class:`FormContent`, :class:`InterpFormContentDict`) are present
+for backwards compatibility with really old applications only. If you still use
+these and would be inconvenienced when they disappeared from a next version of
+this module, drop me a note.
+
+
+.. _functions-in-cgi-module:
+
+Functions
+---------
+
+These are useful if you want more control, or if you want to employ some of the
+algorithms implemented in this module in other circumstances.
+
+
+.. function:: parse(fp[, keep_blank_values[, strict_parsing]])
+
+ Parse a query in the environment or from a file (the file defaults to
+ ``sys.stdin``). The *keep_blank_values* and *strict_parsing* parameters are
+ passed to :func:`parse_qs` unchanged.
+
+
+.. function:: parse_qs(qs[, keep_blank_values[, strict_parsing]])
+
+ Parse a query string given as a string argument (data of type
+ :mimetype:`application/x-www-form-urlencoded`). Data are returned as a
+ dictionary. The dictionary keys are the unique query variable names and the
+ values are lists of values for each name.
+
+ The optional argument *keep_blank_values* is a flag indicating whether blank
+ values in URL encoded queries should be treated as blank strings. A true value
+ indicates that blanks should be retained as blank strings. The default false
+ value indicates that blank values are to be ignored and treated as if they were
+ not included.
+
+ The optional argument *strict_parsing* is a flag indicating what to do with
+ parsing errors. If false (the default), errors are silently ignored. If true,
+ errors raise a :exc:`ValueError` exception.
+
+ Use the :func:`urllib.urlencode` function to convert such dictionaries into
+ query strings.
+
+
+.. function:: parse_qsl(qs[, keep_blank_values[, strict_parsing]])
+
+ Parse a query string given as a string argument (data of type
+ :mimetype:`application/x-www-form-urlencoded`). Data are returned as a list of
+ name, value pairs.
+
+ The optional argument *keep_blank_values* is a flag indicating whether blank
+ values in URL encoded queries should be treated as blank strings. A true value
+ indicates that blanks should be retained as blank strings. The default false
+ value indicates that blank values are to be ignored and treated as if they were
+ not included.
+
+ The optional argument *strict_parsing* is a flag indicating what to do with
+ parsing errors. If false (the default), errors are silently ignored. If true,
+ errors raise a :exc:`ValueError` exception.
+
+ Use the :func:`urllib.urlencode` function to convert such lists of pairs into
+ query strings.
+
+
+.. function:: parse_multipart(fp, pdict)
+
+ Parse input of type :mimetype:`multipart/form-data` (for file uploads).
+ Arguments are *fp* for the input file and *pdict* for a dictionary containing
+ other parameters in the :mailheader:`Content-Type` header.
+
+ Returns a dictionary just like :func:`parse_qs` keys are the field names, each
+ value is a list of values for that field. This is easy to use but not much good
+ if you are expecting megabytes to be uploaded --- in that case, use the
+ :class:`FieldStorage` class instead which is much more flexible.
+
+ Note that this does not parse nested multipart parts --- use
+ :class:`FieldStorage` for that.
+
+
+.. function:: parse_header(string)
+
+ Parse a MIME header (such as :mailheader:`Content-Type`) into a main value and a
+ dictionary of parameters.
+
+
+.. function:: test()
+
+ Robust test CGI script, usable as main program. Writes minimal HTTP headers and
+ formats all information provided to the script in HTML form.
+
+
+.. function:: print_environ()
+
+ Format the shell environment in HTML.
+
+
+.. function:: print_form(form)
+
+ Format a form in HTML.
+
+
+.. function:: print_directory()
+
+ Format the current directory in HTML.
+
+
+.. function:: print_environ_usage()
+
+ Print a list of useful (used by CGI) environment variables in HTML.
+
+
+.. function:: escape(s[, quote])
+
+ Convert the characters ``'&'``, ``'<'`` and ``'>'`` in string *s* to HTML-safe
+ sequences. Use this if you need to display text that might contain such
+ characters in HTML. If the optional flag *quote* is true, the quotation mark
+ character (``'"'``) is also translated; this helps for inclusion in an HTML
+ attribute value, as in ``<A HREF="...">``. If the value to be quoted might
+ include single- or double-quote characters, or both, consider using the
+ :func:`quoteattr` function in the :mod:`xml.sax.saxutils` module instead.
+
+
+.. _cgi-security:
+
+Caring about security
+---------------------
+
+.. index:: pair: CGI; security
+
+There's one important rule: if you invoke an external program (via the
+:func:`os.system` or :func:`os.popen` functions. or others with similar
+functionality), make very sure you don't pass arbitrary strings received from
+the client to the shell. This is a well-known security hole whereby clever
+hackers anywhere on the Web can exploit a gullible CGI script to invoke
+arbitrary shell commands. Even parts of the URL or field names cannot be
+trusted, since the request doesn't have to come from your form!
+
+To be on the safe side, if you must pass a string gotten from a form to a shell
+command, you should make sure the string contains only alphanumeric characters,
+dashes, underscores, and periods.
+
+
+Installing your CGI script on a Unix system
+-------------------------------------------
+
+Read the documentation for your HTTP server and check with your local system
+administrator to find the directory where CGI scripts should be installed;
+usually this is in a directory :file:`cgi-bin` in the server tree.
+
+Make sure that your script is readable and executable by "others"; the Unix file
+mode should be ``0755`` octal (use ``chmod 0755 filename``). Make sure that the
+first line of the script contains ``#!`` starting in column 1 followed by the
+pathname of the Python interpreter, for instance::
+
+ #!/usr/local/bin/python
+
+Make sure the Python interpreter exists and is executable by "others".
+
+Make sure that any files your script needs to read or write are readable or
+writable, respectively, by "others" --- their mode should be ``0644`` for
+readable and ``0666`` for writable. This is because, for security reasons, the
+HTTP server executes your script as user "nobody", without any special
+privileges. It can only read (write, execute) files that everybody can read
+(write, execute). The current directory at execution time is also different (it
+is usually the server's cgi-bin directory) and the set of environment variables
+is also different from what you get when you log in. In particular, don't count
+on the shell's search path for executables (:envvar:`PATH`) or the Python module
+search path (:envvar:`PYTHONPATH`) to be set to anything interesting.
+
+If you need to load modules from a directory which is not on Python's default
+module search path, you can change the path in your script, before importing
+other modules. For example::
+
+ import sys
+ sys.path.insert(0, "/usr/home/joe/lib/python")
+ sys.path.insert(0, "/usr/local/lib/python")
+
+(This way, the directory inserted last will be searched first!)
+
+Instructions for non-Unix systems will vary; check your HTTP server's
+documentation (it will usually have a section on CGI scripts).
+
+
+Testing your CGI script
+-----------------------
+
+Unfortunately, a CGI script will generally not run when you try it from the
+command line, and a script that works perfectly from the command line may fail
+mysteriously when run from the server. There's one reason why you should still
+test your script from the command line: if it contains a syntax error, the
+Python interpreter won't execute it at all, and the HTTP server will most likely
+send a cryptic error to the client.
+
+Assuming your script has no syntax errors, yet it does not work, you have no
+choice but to read the next section.
+
+
+Debugging CGI scripts
+---------------------
+
+.. index:: pair: CGI; debugging
+
+First of all, check for trivial installation errors --- reading the section
+above on installing your CGI script carefully can save you a lot of time. If
+you wonder whether you have understood the installation procedure correctly, try
+installing a copy of this module file (:file:`cgi.py`) as a CGI script. When
+invoked as a script, the file will dump its environment and the contents of the
+form in HTML form. Give it the right mode etc, and send it a request. If it's
+installed in the standard :file:`cgi-bin` directory, it should be possible to
+send it a request by entering a URL into your browser of the form::
+
+ http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
+
+If this gives an error of type 404, the server cannot find the script -- perhaps
+you need to install it in a different directory. If it gives another error,
+there's an installation problem that you should fix before trying to go any
+further. If you get a nicely formatted listing of the environment and form
+content (in this example, the fields should be listed as "addr" with value "At
+Home" and "name" with value "Joe Blow"), the :file:`cgi.py` script has been
+installed correctly. If you follow the same procedure for your own script, you
+should now be able to debug it.
+
+The next step could be to call the :mod:`cgi` module's :func:`test` function
+from your script: replace its main code with the single statement ::
+
+ cgi.test()
+
+This should produce the same results as those gotten from installing the
+:file:`cgi.py` file itself.
+
+When an ordinary Python script raises an unhandled exception (for whatever
+reason: of a typo in a module name, a file that can't be opened, etc.), the
+Python interpreter prints a nice traceback and exits. While the Python
+interpreter will still do this when your CGI script raises an exception, most
+likely the traceback will end up in one of the HTTP server's log files, or be
+discarded altogether.
+
+Fortunately, once you have managed to get your script to execute *some* code,
+you can easily send tracebacks to the Web browser using the :mod:`cgitb` module.
+If you haven't done so already, just add the line::
+
+ import cgitb; cgitb.enable()
+
+to the top of your script. Then try running it again; when a problem occurs,
+you should see a detailed report that will likely make apparent the cause of the
+crash.
+
+If you suspect that there may be a problem in importing the :mod:`cgitb` module,
+you can use an even more robust approach (which only uses built-in modules)::
+
+ import sys
+ sys.stderr = sys.stdout
+ print "Content-Type: text/plain"
+ print
+ ...your code here...
+
+This relies on the Python interpreter to print the traceback. The content type
+of the output is set to plain text, which disables all HTML processing. If your
+script works, the raw HTML will be displayed by your client. If it raises an
+exception, most likely after the first two lines have been printed, a traceback
+will be displayed. Because no HTML interpretation is going on, the traceback
+will be readable.
+
+
+Common problems and solutions
+-----------------------------
+
+* Most HTTP servers buffer the output from CGI scripts until the script is
+ completed. This means that it is not possible to display a progress report on
+ the client's display while the script is running.
+
+* Check the installation instructions above.
+
+* Check the HTTP server's log files. (``tail -f logfile`` in a separate window
+ may be useful!)
+
+* Always check a script for syntax errors first, by doing something like
+ ``python script.py``.
+
+* If your script does not have any syntax errors, try adding ``import cgitb;
+ cgitb.enable()`` to the top of the script.
+
+* When invoking external programs, make sure they can be found. Usually, this
+ means using absolute path names --- :envvar:`PATH` is usually not set to a very
+ useful value in a CGI script.
+
+* When reading or writing external files, make sure they can be read or written
+ by the userid under which your CGI script will be running: this is typically the
+ userid under which the web server is running, or some explicitly specified
+ userid for a web server's ``suexec`` feature.
+
+* Don't try to give a CGI script a set-uid mode. This doesn't work on most
+ systems, and is a security liability as well.
+
+.. rubric:: Footnotes
+
+.. [#] Note that some recent versions of the HTML specification do state what order the
+ field values should be supplied in, but knowing whether a request was
+ received from a conforming browser, or even from a browser at all, is tedious
+ and error-prone.
+
--- /dev/null
+
+:mod:`CGIHTTPServer` --- CGI-capable HTTP request handler
+=========================================================
+
+.. module:: CGIHTTPServer
+ :synopsis: This module provides a request handler for HTTP servers which can run CGI
+ scripts.
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+
+
+The :mod:`CGIHTTPServer` module defines a request-handler class, interface
+compatible with :class:`BaseHTTPServer.BaseHTTPRequestHandler` and inherits
+behavior from :class:`SimpleHTTPServer.SimpleHTTPRequestHandler` but can also
+run CGI scripts.
+
+.. note::
+
+ This module can run CGI scripts on Unix and Windows systems; on Mac OS it will
+ only be able to run Python scripts within the same process as itself.
+
+.. note::
+
+ CGI scripts run by the :class:`CGIHTTPRequestHandler` class cannot execute
+ redirects (HTTP code 302), because code 200 (script output follows) is sent
+ prior to execution of the CGI script. This pre-empts the status code.
+
+The :mod:`CGIHTTPServer` module defines the following class:
+
+
+.. class:: CGIHTTPRequestHandler(request, client_address, server)
+
+ This class is used to serve either files or output of CGI scripts from the
+ current directory and below. Note that mapping HTTP hierarchic structure to
+ local directory structure is exactly as in
+ :class:`SimpleHTTPServer.SimpleHTTPRequestHandler`.
+
+ The class will however, run the CGI script, instead of serving it as a file, if
+ it guesses it to be a CGI script. Only directory-based CGI are used --- the
+ other common server configuration is to treat special extensions as denoting CGI
+ scripts.
+
+ The :func:`do_GET` and :func:`do_HEAD` functions are modified to run CGI scripts
+ and serve the output, instead of serving files, if the request leads to
+ somewhere below the ``cgi_directories`` path.
+
+The :class:`CGIHTTPRequestHandler` defines the following data member:
+
+
+.. attribute:: CGIHTTPRequestHandler.cgi_directories
+
+ This defaults to ``['/cgi-bin', '/htbin']`` and describes directories to treat
+ as containing CGI scripts.
+
+The :class:`CGIHTTPRequestHandler` defines the following methods:
+
+
+.. method:: CGIHTTPRequestHandler.do_POST()
+
+ This method serves the ``'POST'`` request type, only allowed for CGI scripts.
+ Error 501, "Can only POST to CGI scripts", is output when trying to POST to a
+ non-CGI url.
+
+Note that CGI scripts will be run with UID of user nobody, for security reasons.
+Problems with the CGI script will be translated to error 403.
+
+For example usage, see the implementation of the :func:`test` function.
+
+
+.. seealso::
+
+ Module :mod:`BaseHTTPServer`
+ Base class implementation for Web server and request handler.
+
--- /dev/null
+
+:mod:`cgitb` --- Traceback manager for CGI scripts
+==================================================
+
+.. module:: cgitb
+ :synopsis: Configurable traceback handler for CGI scripts.
+.. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+.. versionadded:: 2.2
+
+.. index::
+ single: CGI; exceptions
+ single: CGI; tracebacks
+ single: exceptions; in CGI scripts
+ single: tracebacks; in CGI scripts
+
+The :mod:`cgitb` module provides a special exception handler for Python scripts.
+(Its name is a bit misleading. It was originally designed to display extensive
+traceback information in HTML for CGI scripts. It was later generalized to also
+display this information in plain text.) After this module is activated, if an
+uncaught exception occurs, a detailed, formatted report will be displayed. The
+report includes a traceback showing excerpts of the source code for each level,
+as well as the values of the arguments and local variables to currently running
+functions, to help you debug the problem. Optionally, you can save this
+information to a file instead of sending it to the browser.
+
+To enable this feature, simply add one line to the top of your CGI script::
+
+ import cgitb; cgitb.enable()
+
+The options to the :func:`enable` function control whether the report is
+displayed in the browser and whether the report is logged to a file for later
+analysis.
+
+
+.. function:: enable([display[, logdir[, context[, format]]]])
+
+ .. index:: single: excepthook() (in module sys)
+
+ This function causes the :mod:`cgitb` module to take over the interpreter's
+ default handling for exceptions by setting the value of :attr:`sys.excepthook`.
+
+ The optional argument *display* defaults to ``1`` and can be set to ``0`` to
+ suppress sending the traceback to the browser. If the argument *logdir* is
+ present, the traceback reports are written to files. The value of *logdir*
+ should be a directory where these files will be placed. The optional argument
+ *context* is the number of lines of context to display around the current line
+ of source code in the traceback; this defaults to ``5``. If the optional
+ argument *format* is ``"html"``, the output is formatted as HTML. Any other
+ value forces plain text output. The default value is ``"html"``.
+
+
+.. function:: handler([info])
+
+ This function handles an exception using the default settings (that is, show a
+ report in the browser, but don't log to a file). This can be used when you've
+ caught an exception and want to report it using :mod:`cgitb`. The optional
+ *info* argument should be a 3-tuple containing an exception type, exception
+ value, and traceback object, exactly like the tuple returned by
+ :func:`sys.exc_info`. If the *info* argument is not supplied, the current
+ exception is obtained from :func:`sys.exc_info`.
+
--- /dev/null
+
+:mod:`chunk` --- Read IFF chunked data
+======================================
+
+.. module:: chunk
+ :synopsis: Module to read IFF chunks.
+.. moduleauthor:: Sjoerd Mullender <sjoerd@acm.org>
+.. sectionauthor:: Sjoerd Mullender <sjoerd@acm.org>
+
+
+.. index::
+ single: Audio Interchange File Format
+ single: AIFF
+ single: AIFF-C
+ single: Real Media File Format
+ single: RMFF
+
+This module provides an interface for reading files that use EA IFF 85 chunks.
+[#]_ This format is used in at least the Audio Interchange File Format
+(AIFF/AIFF-C) and the Real Media File Format (RMFF). The WAVE audio file format
+is closely related and can also be read using this module.
+
+A chunk has the following structure:
+
++---------+--------+-------------------------------+
+| Offset | Length | Contents |
++=========+========+===============================+
+| 0 | 4 | Chunk ID |
++---------+--------+-------------------------------+
+| 4 | 4 | Size of chunk in big-endian |
+| | | byte order, not including the |
+| | | header |
++---------+--------+-------------------------------+
+| 8 | *n* | Data bytes, where *n* is the |
+| | | size given in the preceding |
+| | | field |
++---------+--------+-------------------------------+
+| 8 + *n* | 0 or 1 | Pad byte needed if *n* is odd |
+| | | and chunk alignment is used |
++---------+--------+-------------------------------+
+
+The ID is a 4-byte string which identifies the type of chunk.
+
+The size field (a 32-bit value, encoded using big-endian byte order) gives the
+size of the chunk data, not including the 8-byte header.
+
+Usually an IFF-type file consists of one or more chunks. The proposed usage of
+the :class:`Chunk` class defined here is to instantiate an instance at the start
+of each chunk and read from the instance until it reaches the end, after which a
+new instance can be instantiated. At the end of the file, creating a new
+instance will fail with a :exc:`EOFError` exception.
+
+
+.. class:: Chunk(file[, align, bigendian, inclheader])
+
+ Class which represents a chunk. The *file* argument is expected to be a
+ file-like object. An instance of this class is specifically allowed. The
+ only method that is needed is :meth:`read`. If the methods :meth:`seek` and
+ :meth:`tell` are present and don't raise an exception, they are also used.
+ If these methods are present and raise an exception, they are expected to not
+ have altered the object. If the optional argument *align* is true, chunks
+ are assumed to be aligned on 2-byte boundaries. If *align* is false, no
+ alignment is assumed. The default value is true. If the optional argument
+ *bigendian* is false, the chunk size is assumed to be in little-endian order.
+ This is needed for WAVE audio files. The default value is true. If the
+ optional argument *inclheader* is true, the size given in the chunk header
+ includes the size of the header. The default value is false.
+
+A :class:`Chunk` object supports the following methods:
+
+
+.. method:: Chunk.getname()
+
+ Returns the name (ID) of the chunk. This is the first 4 bytes of the chunk.
+
+
+.. method:: Chunk.getsize()
+
+ Returns the size of the chunk.
+
+
+.. method:: Chunk.close()
+
+ Close and skip to the end of the chunk. This does not close the underlying
+ file.
+
+The remaining methods will raise :exc:`IOError` if called after the
+:meth:`close` method has been called.
+
+
+.. method:: Chunk.isatty()
+
+ Returns ``False``.
+
+
+.. method:: Chunk.seek(pos[, whence])
+
+ Set the chunk's current position. The *whence* argument is optional and
+ defaults to ``0`` (absolute file positioning); other values are ``1`` (seek
+ relative to the current position) and ``2`` (seek relative to the file's end).
+ There is no return value. If the underlying file does not allow seek, only
+ forward seeks are allowed.
+
+
+.. method:: Chunk.tell()
+
+ Return the current position into the chunk.
+
+
+.. method:: Chunk.read([size])
+
+ Read at most *size* bytes from the chunk (less if the read hits the end of the
+ chunk before obtaining *size* bytes). If the *size* argument is negative or
+ omitted, read all data until the end of the chunk. The bytes are returned as a
+ string object. An empty string is returned when the end of the chunk is
+ encountered immediately.
+
+
+.. method:: Chunk.skip()
+
+ Skip to the end of the chunk. All further calls to :meth:`read` for the chunk
+ will return ``''``. If you are not interested in the contents of the chunk,
+ this method should be called so that the file points to the start of the next
+ chunk.
+
+.. rubric:: Footnotes
+
+.. [#] "EA IFF 85" Standard for Interchange Format Files, Jerry Morrison, Electronic
+ Arts, January 1985.
+
--- /dev/null
+
+:mod:`cmath` --- Mathematical functions for complex numbers
+===========================================================
+
+.. module:: cmath
+ :synopsis: Mathematical functions for complex numbers.
+
+
+This module is always available. It provides access to mathematical functions
+for complex numbers. The functions in this module accept integers,
+floating-point numbers or complex numbers as arguments. They will also accept
+any Python object that has either a :meth:`__complex__` or a :meth:`__float__`
+method: these methods are used to convert the object to a complex or
+floating-point number, respectively, and the function is then applied to the
+result of the conversion.
+
+The functions are:
+
+
+.. function:: acos(x)
+
+ Return the arc cosine of *x*. There are two branch cuts: One extends right from
+ 1 along the real axis to ∞, continuous from below. The other extends left from
+ -1 along the real axis to -∞, continuous from above.
+
+
+.. function:: acosh(x)
+
+ Return the hyperbolic arc cosine of *x*. There is one branch cut, extending left
+ from 1 along the real axis to -∞, continuous from above.
+
+
+.. function:: asin(x)
+
+ Return the arc sine of *x*. This has the same branch cuts as :func:`acos`.
+
+
+.. function:: asinh(x)
+
+ Return the hyperbolic arc sine of *x*. There are two branch cuts, extending
+ left from ``±1j`` to ``±∞j``, both continuous from above. These branch cuts
+ should be considered a bug to be corrected in a future release. The correct
+ branch cuts should extend along the imaginary axis, one from ``1j`` up to
+ ``∞j`` and continuous from the right, and one from ``-1j`` down to ``-∞j``
+ and continuous from the left.
+
+
+.. function:: atan(x)
+
+ Return the arc tangent of *x*. There are two branch cuts: One extends from
+ ``1j`` along the imaginary axis to ``∞j``, continuous from the left. The
+ other extends from ``-1j`` along the imaginary axis to ``-∞j``, continuous
+ from the left. (This should probably be changed so the upper cut becomes
+ continuous from the other side.)
+
+
+.. function:: atanh(x)
+
+ Return the hyperbolic arc tangent of *x*. There are two branch cuts: One
+ extends from ``1`` along the real axis to ``∞``, continuous from above. The
+ other extends from ``-1`` along the real axis to ``-∞``, continuous from
+ above. (This should probably be changed so the right cut becomes continuous
+ from the other side.)
+
+
+.. function:: cos(x)
+
+ Return the cosine of *x*.
+
+
+.. function:: cosh(x)
+
+ Return the hyperbolic cosine of *x*.
+
+
+.. function:: exp(x)
+
+ Return the exponential value ``e**x``.
+
+
+.. function:: log(x[, base])
+
+ Returns the logarithm of *x* to the given *base*. If the *base* is not
+ specified, returns the natural logarithm of *x*. There is one branch cut, from 0
+ along the negative real axis to -∞, continuous from above.
+
+ .. versionchanged:: 2.4
+ *base* argument added.
+
+
+.. function:: log10(x)
+
+ Return the base-10 logarithm of *x*. This has the same branch cut as
+ :func:`log`.
+
+
+.. function:: sin(x)
+
+ Return the sine of *x*.
+
+
+.. function:: sinh(x)
+
+ Return the hyperbolic sine of *x*.
+
+
+.. function:: sqrt(x)
+
+ Return the square root of *x*. This has the same branch cut as :func:`log`.
+
+
+.. function:: tan(x)
+
+ Return the tangent of *x*.
+
+
+.. function:: tanh(x)
+
+ Return the hyperbolic tangent of *x*.
+
+The module also defines two mathematical constants:
+
+
+.. data:: pi
+
+ The mathematical constant *pi*, as a float.
+
+
+.. data:: e
+
+ The mathematical constant *e*, as a float.
+
+.. index:: module: math
+
+Note that the selection of functions is similar, but not identical, to that in
+module :mod:`math`. The reason for having two modules is that some users aren't
+interested in complex numbers, and perhaps don't even know what they are. They
+would rather have ``math.sqrt(-1)`` raise an exception than return a complex
+number. Also note that the functions defined in :mod:`cmath` always return a
+complex number, even if the answer can be expressed as a real number (in which
+case the complex number has an imaginary part of zero).
+
+A note on branch cuts: They are curves along which the given function fails to
+be continuous. They are a necessary feature of many complex functions. It is
+assumed that if you need to compute with complex functions, you will understand
+about branch cuts. Consult almost any (not too elementary) book on complex
+variables for enlightenment. For information of the proper choice of branch
+cuts for numerical purposes, a good reference should be the following:
+
+
+.. seealso::
+
+ Kahan, W: Branch cuts for complex elementary functions; or, Much ado about
+ nothing's sign bit. In Iserles, A., and Powell, M. (eds.), The state of the art
+ in numerical analysis. Clarendon Press (1987) pp165-211.
+
--- /dev/null
+
+:mod:`cmd` --- Support for line-oriented command interpreters
+=============================================================
+
+.. module:: cmd
+ :synopsis: Build line-oriented command interpreters.
+.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
+
+
+The :class:`Cmd` class provides a simple framework for writing line-oriented
+command interpreters. These are often useful for test harnesses, administrative
+tools, and prototypes that will later be wrapped in a more sophisticated
+interface.
+
+
+.. class:: Cmd([completekey[, stdin[, stdout]]])
+
+ A :class:`Cmd` instance or subclass instance is a line-oriented interpreter
+ framework. There is no good reason to instantiate :class:`Cmd` itself; rather,
+ it's useful as a superclass of an interpreter class you define yourself in order
+ to inherit :class:`Cmd`'s methods and encapsulate action methods.
+
+ The optional argument *completekey* is the :mod:`readline` name of a completion
+ key; it defaults to :kbd:`Tab`. If *completekey* is not :const:`None` and
+ :mod:`readline` is available, command completion is done automatically.
+
+ The optional arguments *stdin* and *stdout* specify the input and output file
+ objects that the Cmd instance or subclass instance will use for input and
+ output. If not specified, they will default to *sys.stdin* and *sys.stdout*.
+
+ .. versionchanged:: 2.3
+ The *stdin* and *stdout* parameters were added.
+
+
+.. _cmd-objects:
+
+Cmd Objects
+-----------
+
+A :class:`Cmd` instance has the following methods:
+
+
+.. method:: Cmd.cmdloop([intro])
+
+ Repeatedly issue a prompt, accept input, parse an initial prefix off the
+ received input, and dispatch to action methods, passing them the remainder of
+ the line as argument.
+
+ The optional argument is a banner or intro string to be issued before the first
+ prompt (this overrides the :attr:`intro` class member).
+
+ If the :mod:`readline` module is loaded, input will automatically inherit
+ :program:`bash`\ -like history-list editing (e.g. :kbd:`Control-P` scrolls back
+ to the last command, :kbd:`Control-N` forward to the next one, :kbd:`Control-F`
+ moves the cursor to the right non-destructively, :kbd:`Control-B` moves the
+ cursor to the left non-destructively, etc.).
+
+ An end-of-file on input is passed back as the string ``'EOF'``.
+
+ An interpreter instance will recognize a command name ``foo`` if and only if it
+ has a method :meth:`do_foo`. As a special case, a line beginning with the
+ character ``'?'`` is dispatched to the method :meth:`do_help`. As another
+ special case, a line beginning with the character ``'!'`` is dispatched to the
+ method :meth:`do_shell` (if such a method is defined).
+
+ This method will return when the :meth:`postcmd` method returns a true value.
+ The *stop* argument to :meth:`postcmd` is the return value from the command's
+ corresponding :meth:`do_\*` method.
+
+ If completion is enabled, completing commands will be done automatically, and
+ completing of commands args is done by calling :meth:`complete_foo` with
+ arguments *text*, *line*, *begidx*, and *endidx*. *text* is the string prefix
+ we are attempting to match: all returned matches must begin with it. *line* is
+ the current input line with leading whitespace removed, *begidx* and *endidx*
+ are the beginning and ending indexes of the prefix text, which could be used to
+ provide different completion depending upon which position the argument is in.
+
+ All subclasses of :class:`Cmd` inherit a predefined :meth:`do_help`. This
+ method, called with an argument ``'bar'``, invokes the corresponding method
+ :meth:`help_bar`. With no argument, :meth:`do_help` lists all available help
+ topics (that is, all commands with corresponding :meth:`help_\*` methods), and
+ also lists any undocumented commands.
+
+
+.. method:: Cmd.onecmd(str)
+
+ Interpret the argument as though it had been typed in response to the prompt.
+ This may be overridden, but should not normally need to be; see the
+ :meth:`precmd` and :meth:`postcmd` methods for useful execution hooks. The
+ return value is a flag indicating whether interpretation of commands by the
+ interpreter should stop. If there is a :meth:`do_\*` method for the command
+ *str*, the return value of that method is returned, otherwise the return value
+ from the :meth:`default` method is returned.
+
+
+.. method:: Cmd.emptyline()
+
+ Method called when an empty line is entered in response to the prompt. If this
+ method is not overridden, it repeats the last nonempty command entered.
+
+
+.. method:: Cmd.default(line)
+
+ Method called on an input line when the command prefix is not recognized. If
+ this method is not overridden, it prints an error message and returns.
+
+
+.. method:: Cmd.completedefault(text, line, begidx, endidx)
+
+ Method called to complete an input line when no command-specific
+ :meth:`complete_\*` method is available. By default, it returns an empty list.
+
+
+.. method:: Cmd.precmd(line)
+
+ Hook method executed just before the command line *line* is interpreted, but
+ after the input prompt is generated and issued. This method is a stub in
+ :class:`Cmd`; it exists to be overridden by subclasses. The return value is
+ used as the command which will be executed by the :meth:`onecmd` method; the
+ :meth:`precmd` implementation may re-write the command or simply return *line*
+ unchanged.
+
+
+.. method:: Cmd.postcmd(stop, line)
+
+ Hook method executed just after a command dispatch is finished. This method is
+ a stub in :class:`Cmd`; it exists to be overridden by subclasses. *line* is the
+ command line which was executed, and *stop* is a flag which indicates whether
+ execution will be terminated after the call to :meth:`postcmd`; this will be the
+ return value of the :meth:`onecmd` method. The return value of this method will
+ be used as the new value for the internal flag which corresponds to *stop*;
+ returning false will cause interpretation to continue.
+
+
+.. method:: Cmd.preloop()
+
+ Hook method executed once when :meth:`cmdloop` is called. This method is a stub
+ in :class:`Cmd`; it exists to be overridden by subclasses.
+
+
+.. method:: Cmd.postloop()
+
+ Hook method executed once when :meth:`cmdloop` is about to return. This method
+ is a stub in :class:`Cmd`; it exists to be overridden by subclasses.
+
+Instances of :class:`Cmd` subclasses have some public instance variables:
+
+
+.. attribute:: Cmd.prompt
+
+ The prompt issued to solicit input.
+
+
+.. attribute:: Cmd.identchars
+
+ The string of characters accepted for the command prefix.
+
+
+.. attribute:: Cmd.lastcmd
+
+ The last nonempty command prefix seen.
+
+
+.. attribute:: Cmd.intro
+
+ A string to issue as an intro or banner. May be overridden by giving the
+ :meth:`cmdloop` method an argument.
+
+
+.. attribute:: Cmd.doc_header
+
+ The header to issue if the help output has a section for documented commands.
+
+
+.. attribute:: Cmd.misc_header
+
+ The header to issue if the help output has a section for miscellaneous help
+ topics (that is, there are :meth:`help_\*` methods without corresponding
+ :meth:`do_\*` methods).
+
+
+.. attribute:: Cmd.undoc_header
+
+ The header to issue if the help output has a section for undocumented commands
+ (that is, there are :meth:`do_\*` methods without corresponding :meth:`help_\*`
+ methods).
+
+
+.. attribute:: Cmd.ruler
+
+ The character used to draw separator lines under the help-message headers. If
+ empty, no ruler line is drawn. It defaults to ``'='``.
+
+
+.. attribute:: Cmd.use_rawinput
+
+ A flag, defaulting to true. If true, :meth:`cmdloop` uses :func:`raw_input` to
+ display a prompt and read the next command; if false, :meth:`sys.stdout.write`
+ and :meth:`sys.stdin.readline` are used. (This means that by importing
+ :mod:`readline`, on systems that support it, the interpreter will automatically
+ support :program:`Emacs`\ -like line editing and command-history keystrokes.)
+
--- /dev/null
+
+:mod:`code` --- Interpreter base classes
+========================================
+
+.. module:: code
+ :synopsis: Facilities to implement read-eval-print loops.
+
+
+
+The ``code`` module provides facilities to implement read-eval-print loops in
+Python. Two classes and convenience functions are included which can be used to
+build applications which provide an interactive interpreter prompt.
+
+
+.. class:: InteractiveInterpreter([locals])
+
+ This class deals with parsing and interpreter state (the user's namespace); it
+ does not deal with input buffering or prompting or input file naming (the
+ filename is always passed in explicitly). The optional *locals* argument
+ specifies the dictionary in which code will be executed; it defaults to a newly
+ created dictionary with key ``'__name__'`` set to ``'__console__'`` and key
+ ``'__doc__'`` set to ``None``.
+
+
+.. class:: InteractiveConsole([locals[, filename]])
+
+ Closely emulate the behavior of the interactive Python interpreter. This class
+ builds on :class:`InteractiveInterpreter` and adds prompting using the familiar
+ ``sys.ps1`` and ``sys.ps2``, and input buffering.
+
+
+.. function:: interact([banner[, readfunc[, local]]])
+
+ Convenience function to run a read-eval-print loop. This creates a new instance
+ of :class:`InteractiveConsole` and sets *readfunc* to be used as the
+ :meth:`raw_input` method, if provided. If *local* is provided, it is passed to
+ the :class:`InteractiveConsole` constructor for use as the default namespace for
+ the interpreter loop. The :meth:`interact` method of the instance is then run
+ with *banner* passed as the banner to use, if provided. The console object is
+ discarded after use.
+
+
+.. function:: compile_command(source[, filename[, symbol]])
+
+ This function is useful for programs that want to emulate Python's interpreter
+ main loop (a.k.a. the read-eval-print loop). The tricky part is to determine
+ when the user has entered an incomplete command that can be completed by
+ entering more text (as opposed to a complete command or a syntax error). This
+ function *almost* always makes the same decision as the real interpreter main
+ loop.
+
+ *source* is the source string; *filename* is the optional filename from which
+ source was read, defaulting to ``'<input>'``; and *symbol* is the optional
+ grammar start symbol, which should be either ``'single'`` (the default) or
+ ``'eval'``.
+
+ Returns a code object (the same as ``compile(source, filename, symbol)``) if the
+ command is complete and valid; ``None`` if the command is incomplete; raises
+ :exc:`SyntaxError` if the command is complete and contains a syntax error, or
+ raises :exc:`OverflowError` or :exc:`ValueError` if the command contains an
+ invalid literal.
+
+
+.. _interpreter-objects:
+
+Interactive Interpreter Objects
+-------------------------------
+
+
+.. method:: InteractiveInterpreter.runsource(source[, filename[, symbol]])
+
+ Compile and run some source in the interpreter. Arguments are the same as for
+ :func:`compile_command`; the default for *filename* is ``'<input>'``, and for
+ *symbol* is ``'single'``. One several things can happen:
+
+ * The input is incorrect; :func:`compile_command` raised an exception
+ (:exc:`SyntaxError` or :exc:`OverflowError`). A syntax traceback will be
+ printed by calling the :meth:`showsyntaxerror` method. :meth:`runsource`
+ returns ``False``.
+
+ * The input is incomplete, and more input is required; :func:`compile_command`
+ returned ``None``. :meth:`runsource` returns ``True``.
+
+ * The input is complete; :func:`compile_command` returned a code object. The
+ code is executed by calling the :meth:`runcode` (which also handles run-time
+ exceptions, except for :exc:`SystemExit`). :meth:`runsource` returns ``False``.
+
+ The return value can be used to decide whether to use ``sys.ps1`` or ``sys.ps2``
+ to prompt the next line.
+
+
+.. method:: InteractiveInterpreter.runcode(code)
+
+ Execute a code object. When an exception occurs, :meth:`showtraceback` is called
+ to display a traceback. All exceptions are caught except :exc:`SystemExit`,
+ which is allowed to propagate.
+
+ A note about :exc:`KeyboardInterrupt`: this exception may occur elsewhere in
+ this code, and may not always be caught. The caller should be prepared to deal
+ with it.
+
+
+.. method:: InteractiveInterpreter.showsyntaxerror([filename])
+
+ Display the syntax error that just occurred. This does not display a stack
+ trace because there isn't one for syntax errors. If *filename* is given, it is
+ stuffed into the exception instead of the default filename provided by Python's
+ parser, because it always uses ``'<string>'`` when reading from a string. The
+ output is written by the :meth:`write` method.
+
+
+.. method:: InteractiveInterpreter.showtraceback()
+
+ Display the exception that just occurred. We remove the first stack item
+ because it is within the interpreter object implementation. The output is
+ written by the :meth:`write` method.
+
+
+.. method:: InteractiveInterpreter.write(data)
+
+ Write a string to the standard error stream (``sys.stderr``). Derived classes
+ should override this to provide the appropriate output handling as needed.
+
+
+.. _console-objects:
+
+Interactive Console Objects
+---------------------------
+
+The :class:`InteractiveConsole` class is a subclass of
+:class:`InteractiveInterpreter`, and so offers all the methods of the
+interpreter objects as well as the following additions.
+
+
+.. method:: InteractiveConsole.interact([banner])
+
+ Closely emulate the interactive Python console. The optional banner argument
+ specify the banner to print before the first interaction; by default it prints a
+ banner similar to the one printed by the standard Python interpreter, followed
+ by the class name of the console object in parentheses (so as not to confuse
+ this with the real interpreter -- since it's so close!).
+
+
+.. method:: InteractiveConsole.push(line)
+
+ Push a line of source text to the interpreter. The line should not have a
+ trailing newline; it may have internal newlines. The line is appended to a
+ buffer and the interpreter's :meth:`runsource` method is called with the
+ concatenated contents of the buffer as source. If this indicates that the
+ command was executed or invalid, the buffer is reset; otherwise, the command is
+ incomplete, and the buffer is left as it was after the line was appended. The
+ return value is ``True`` if more input is required, ``False`` if the line was
+ dealt with in some way (this is the same as :meth:`runsource`).
+
+
+.. method:: InteractiveConsole.resetbuffer()
+
+ Remove any unhandled source text from the input buffer.
+
+
+.. method:: InteractiveConsole.raw_input([prompt])
+
+ Write a prompt and read a line. The returned line does not include the trailing
+ newline. When the user enters the EOF key sequence, :exc:`EOFError` is raised.
+ The base implementation uses the built-in function :func:`raw_input`; a subclass
+ may replace this with a different implementation.
+
--- /dev/null
+
+:mod:`codecs` --- Codec registry and base classes
+=================================================
+
+.. module:: codecs
+ :synopsis: Encode and decode data and streams.
+.. moduleauthor:: Marc-Andre Lemburg <mal@lemburg.com>
+.. sectionauthor:: Marc-Andre Lemburg <mal@lemburg.com>
+.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
+
+
+.. index::
+ single: Unicode
+ single: Codecs
+ pair: Codecs; encode
+ pair: Codecs; decode
+ single: streams
+ pair: stackable; streams
+
+This module defines base classes for standard Python codecs (encoders and
+decoders) and provides access to the internal Python codec registry which
+manages the codec and error handling lookup process.
+
+It defines the following functions:
+
+
+.. function:: register(search_function)
+
+ Register a codec search function. Search functions are expected to take one
+ argument, the encoding name in all lower case letters, and return a
+ :class:`CodecInfo` object having the following attributes:
+
+ * ``name`` The name of the encoding;
+
+ * ``encoder`` The stateless encoding function;
+
+ * ``decoder`` The stateless decoding function;
+
+ * ``incrementalencoder`` An incremental encoder class or factory function;
+
+ * ``incrementaldecoder`` An incremental decoder class or factory function;
+
+ * ``streamwriter`` A stream writer class or factory function;
+
+ * ``streamreader`` A stream reader class or factory function.
+
+ The various functions or classes take the following arguments:
+
+ *encoder* and *decoder*: These must be functions or methods which have the same
+ interface as the :meth:`encode`/:meth:`decode` methods of Codec instances (see
+ Codec Interface). The functions/methods are expected to work in a stateless
+ mode.
+
+ *incrementalencoder* and *incrementalencoder*: These have to be factory
+ functions providing the following interface:
+
+ ``factory(errors='strict')``
+
+ The factory functions must return objects providing the interfaces defined by
+ the base classes :class:`IncrementalEncoder` and :class:`IncrementalEncoder`,
+ respectively. Incremental codecs can maintain state.
+
+ *streamreader* and *streamwriter*: These have to be factory functions providing
+ the following interface:
+
+ ``factory(stream, errors='strict')``
+
+ The factory functions must return objects providing the interfaces defined by
+ the base classes :class:`StreamWriter` and :class:`StreamReader`, respectively.
+ Stream codecs can maintain state.
+
+ Possible values for errors are ``'strict'`` (raise an exception in case of an
+ encoding error), ``'replace'`` (replace malformed data with a suitable
+ replacement marker, such as ``'?'``), ``'ignore'`` (ignore malformed data and
+ continue without further notice), ``'xmlcharrefreplace'`` (replace with the
+ appropriate XML character reference (for encoding only)) and
+ ``'backslashreplace'`` (replace with backslashed escape sequences (for encoding
+ only)) as well as any other error handling name defined via
+ :func:`register_error`.
+
+ In case a search function cannot find a given encoding, it should return
+ ``None``.
+
+
+.. function:: lookup(encoding)
+
+ Looks up the codec info in the Python codec registry and returns a
+ :class:`CodecInfo` object as defined above.
+
+ Encodings are first looked up in the registry's cache. If not found, the list of
+ registered search functions is scanned. If no :class:`CodecInfo` object is
+ found, a :exc:`LookupError` is raised. Otherwise, the :class:`CodecInfo` object
+ is stored in the cache and returned to the caller.
+
+To simplify access to the various codecs, the module provides these additional
+functions which use :func:`lookup` for the codec lookup:
+
+
+.. function:: getencoder(encoding)
+
+ Look up the codec for the given encoding and return its encoder function.
+
+ Raises a :exc:`LookupError` in case the encoding cannot be found.
+
+
+.. function:: getdecoder(encoding)
+
+ Look up the codec for the given encoding and return its decoder function.
+
+ Raises a :exc:`LookupError` in case the encoding cannot be found.
+
+
+.. function:: getincrementalencoder(encoding)
+
+ Look up the codec for the given encoding and return its incremental encoder
+ class or factory function.
+
+ Raises a :exc:`LookupError` in case the encoding cannot be found or the codec
+ doesn't support an incremental encoder.
+
+ .. versionadded:: 2.5
+
+
+.. function:: getincrementaldecoder(encoding)
+
+ Look up the codec for the given encoding and return its incremental decoder
+ class or factory function.
+
+ Raises a :exc:`LookupError` in case the encoding cannot be found or the codec
+ doesn't support an incremental decoder.
+
+ .. versionadded:: 2.5
+
+
+.. function:: getreader(encoding)
+
+ Look up the codec for the given encoding and return its StreamReader class or
+ factory function.
+
+ Raises a :exc:`LookupError` in case the encoding cannot be found.
+
+
+.. function:: getwriter(encoding)
+
+ Look up the codec for the given encoding and return its StreamWriter class or
+ factory function.
+
+ Raises a :exc:`LookupError` in case the encoding cannot be found.
+
+
+.. function:: register_error(name, error_handler)
+
+ Register the error handling function *error_handler* under the name *name*.
+ *error_handler* will be called during encoding and decoding in case of an error,
+ when *name* is specified as the errors parameter.
+
+ For encoding *error_handler* will be called with a :exc:`UnicodeEncodeError`
+ instance, which contains information about the location of the error. The error
+ handler must either raise this or a different exception or return a tuple with a
+ replacement for the unencodable part of the input and a position where encoding
+ should continue. The encoder will encode the replacement and continue encoding
+ the original input at the specified position. Negative position values will be
+ treated as being relative to the end of the input string. If the resulting
+ position is out of bound an :exc:`IndexError` will be raised.
+
+ Decoding and translating works similar, except :exc:`UnicodeDecodeError` or
+ :exc:`UnicodeTranslateError` will be passed to the handler and that the
+ replacement from the error handler will be put into the output directly.
+
+
+.. function:: lookup_error(name)
+
+ Return the error handler previously registered under the name *name*.
+
+ Raises a :exc:`LookupError` in case the handler cannot be found.
+
+
+.. function:: strict_errors(exception)
+
+ Implements the ``strict`` error handling.
+
+
+.. function:: replace_errors(exception)
+
+ Implements the ``replace`` error handling.
+
+
+.. function:: ignore_errors(exception)
+
+ Implements the ``ignore`` error handling.
+
+
+.. function:: xmlcharrefreplace_errors_errors(exception)
+
+ Implements the ``xmlcharrefreplace`` error handling.
+
+
+.. function:: backslashreplace_errors_errors(exception)
+
+ Implements the ``backslashreplace`` error handling.
+
+To simplify working with encoded files or stream, the module also defines these
+utility functions:
+
+
+.. function:: open(filename, mode[, encoding[, errors[, buffering]]])
+
+ Open an encoded file using the given *mode* and return a wrapped version
+ providing transparent encoding/decoding.
+
+ .. note::
+
+ The wrapped version will only accept the object format defined by the codecs,
+ i.e. Unicode objects for most built-in codecs. Output is also codec-dependent
+ and will usually be Unicode as well.
+
+ *encoding* specifies the encoding which is to be used for the file.
+
+ *errors* may be given to define the error handling. It defaults to ``'strict'``
+ which causes a :exc:`ValueError` to be raised in case an encoding error occurs.
+
+ *buffering* has the same meaning as for the built-in :func:`open` function. It
+ defaults to line buffered.
+
+
+.. function:: EncodedFile(file, input[, output[, errors]])
+
+ Return a wrapped version of file which provides transparent encoding
+ translation.
+
+ Strings written to the wrapped file are interpreted according to the given
+ *input* encoding and then written to the original file as strings using the
+ *output* encoding. The intermediate encoding will usually be Unicode but depends
+ on the specified codecs.
+
+ If *output* is not given, it defaults to *input*.
+
+ *errors* may be given to define the error handling. It defaults to ``'strict'``,
+ which causes :exc:`ValueError` to be raised in case an encoding error occurs.
+
+
+.. function:: iterencode(iterable, encoding[, errors])
+
+ Uses an incremental encoder to iteratively encode the input provided by
+ *iterable*. This function is a generator. *errors* (as well as any other keyword
+ argument) is passed through to the incremental encoder.
+
+ .. versionadded:: 2.5
+
+
+.. function:: iterdecode(iterable, encoding[, errors])
+
+ Uses an incremental decoder to iteratively decode the input provided by
+ *iterable*. This function is a generator. *errors* (as well as any other keyword
+ argument) is passed through to the incremental decoder.
+
+ .. versionadded:: 2.5
+
+The module also provides the following constants which are useful for reading
+and writing to platform dependent files:
+
+
+.. data:: BOM
+ BOM_BE
+ BOM_LE
+ BOM_UTF8
+ BOM_UTF16
+ BOM_UTF16_BE
+ BOM_UTF16_LE
+ BOM_UTF32
+ BOM_UTF32_BE
+ BOM_UTF32_LE
+
+ These constants define various encodings of the Unicode byte order mark (BOM)
+ used in UTF-16 and UTF-32 data streams to indicate the byte order used in the
+ stream or file and in UTF-8 as a Unicode signature. :const:`BOM_UTF16` is either
+ :const:`BOM_UTF16_BE` or :const:`BOM_UTF16_LE` depending on the platform's
+ native byte order, :const:`BOM` is an alias for :const:`BOM_UTF16`,
+ :const:`BOM_LE` for :const:`BOM_UTF16_LE` and :const:`BOM_BE` for
+ :const:`BOM_UTF16_BE`. The others represent the BOM in UTF-8 and UTF-32
+ encodings.
+
+
+.. _codec-base-classes:
+
+Codec Base Classes
+------------------
+
+The :mod:`codecs` module defines a set of base classes which define the
+interface and can also be used to easily write you own codecs for use in Python.
+
+Each codec has to define four interfaces to make it usable as codec in Python:
+stateless encoder, stateless decoder, stream reader and stream writer. The
+stream reader and writers typically reuse the stateless encoder/decoder to
+implement the file protocols.
+
+The :class:`Codec` class defines the interface for stateless encoders/decoders.
+
+To simplify and standardize error handling, the :meth:`encode` and
+:meth:`decode` methods may implement different error handling schemes by
+providing the *errors* string argument. The following string values are defined
+and implemented by all standard Python codecs:
+
++-------------------------+-----------------------------------------------+
+| Value | Meaning |
++=========================+===============================================+
+| ``'strict'`` | Raise :exc:`UnicodeError` (or a subclass); |
+| | this is the default. |
++-------------------------+-----------------------------------------------+
+| ``'ignore'`` | Ignore the character and continue with the |
+| | next. |
++-------------------------+-----------------------------------------------+
+| ``'replace'`` | Replace with a suitable replacement |
+| | character; Python will use the official |
+| | U+FFFD REPLACEMENT CHARACTER for the built-in |
+| | Unicode codecs on decoding and '?' on |
+| | encoding. |
++-------------------------+-----------------------------------------------+
+| ``'xmlcharrefreplace'`` | Replace with the appropriate XML character |
+| | reference (only for encoding). |
++-------------------------+-----------------------------------------------+
+| ``'backslashreplace'`` | Replace with backslashed escape sequences |
+| | (only for encoding). |
++-------------------------+-----------------------------------------------+
+
+The set of allowed values can be extended via :meth:`register_error`.
+
+
+.. _codec-objects:
+
+Codec Objects
+^^^^^^^^^^^^^
+
+The :class:`Codec` class defines these methods which also define the function
+interfaces of the stateless encoder and decoder:
+
+
+.. method:: Codec.encode(input[, errors])
+
+ Encodes the object *input* and returns a tuple (output object, length consumed).
+ While codecs are not restricted to use with Unicode, in a Unicode context,
+ encoding converts a Unicode object to a plain string using a particular
+ character set encoding (e.g., ``cp1252`` or ``iso-8859-1``).
+
+ *errors* defines the error handling to apply. It defaults to ``'strict'``
+ handling.
+
+ The method may not store state in the :class:`Codec` instance. Use
+ :class:`StreamCodec` for codecs which have to keep state in order to make
+ encoding/decoding efficient.
+
+ The encoder must be able to handle zero length input and return an empty object
+ of the output object type in this situation.
+
+
+.. method:: Codec.decode(input[, errors])
+
+ Decodes the object *input* and returns a tuple (output object, length consumed).
+ In a Unicode context, decoding converts a plain string encoded using a
+ particular character set encoding to a Unicode object.
+
+ *input* must be an object which provides the ``bf_getreadbuf`` buffer slot.
+ Python strings, buffer objects and memory mapped files are examples of objects
+ providing this slot.
+
+ *errors* defines the error handling to apply. It defaults to ``'strict'``
+ handling.
+
+ The method may not store state in the :class:`Codec` instance. Use
+ :class:`StreamCodec` for codecs which have to keep state in order to make
+ encoding/decoding efficient.
+
+ The decoder must be able to handle zero length input and return an empty object
+ of the output object type in this situation.
+
+The :class:`IncrementalEncoder` and :class:`IncrementalDecoder` classes provide
+the basic interface for incremental encoding and decoding. Encoding/decoding the
+input isn't done with one call to the stateless encoder/decoder function, but
+with multiple calls to the :meth:`encode`/:meth:`decode` method of the
+incremental encoder/decoder. The incremental encoder/decoder keeps track of the
+encoding/decoding process during method calls.
+
+The joined output of calls to the :meth:`encode`/:meth:`decode` method is the
+same as if all the single inputs were joined into one, and this input was
+encoded/decoded with the stateless encoder/decoder.
+
+
+.. _incremental-encoder-objects:
+
+IncrementalEncoder Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 2.5
+
+The :class:`IncrementalEncoder` class is used for encoding an input in multiple
+steps. It defines the following methods which every incremental encoder must
+define in order to be compatible with the Python codec registry.
+
+
+.. class:: IncrementalEncoder([errors])
+
+ Constructor for an :class:`IncrementalEncoder` instance.
+
+ All incremental encoders must provide this constructor interface. They are free
+ to add additional keyword arguments, but only the ones defined here are used by
+ the Python codec registry.
+
+ The :class:`IncrementalEncoder` may implement different error handling schemes
+ by providing the *errors* keyword argument. These parameters are predefined:
+
+ * ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default.
+
+ * ``'ignore'`` Ignore the character and continue with the next.
+
+ * ``'replace'`` Replace with a suitable replacement character
+
+ * ``'xmlcharrefreplace'`` Replace with the appropriate XML character reference
+
+ * ``'backslashreplace'`` Replace with backslashed escape sequences.
+
+ The *errors* argument will be assigned to an attribute of the same name.
+ Assigning to this attribute makes it possible to switch between different error
+ handling strategies during the lifetime of the :class:`IncrementalEncoder`
+ object.
+
+ The set of allowed values for the *errors* argument can be extended with
+ :func:`register_error`.
+
+
+.. method:: IncrementalEncoder.encode(object[, final])
+
+ Encodes *object* (taking the current state of the encoder into account) and
+ returns the resulting encoded object. If this is the last call to :meth:`encode`
+ *final* must be true (the default is false).
+
+
+.. method:: IncrementalEncoder.reset()
+
+ Reset the encoder to the initial state.
+
+
+.. _incremental-decoder-objects:
+
+IncrementalDecoder Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :class:`IncrementalDecoder` class is used for decoding an input in multiple
+steps. It defines the following methods which every incremental decoder must
+define in order to be compatible with the Python codec registry.
+
+
+.. class:: IncrementalDecoder([errors])
+
+ Constructor for an :class:`IncrementalDecoder` instance.
+
+ All incremental decoders must provide this constructor interface. They are free
+ to add additional keyword arguments, but only the ones defined here are used by
+ the Python codec registry.
+
+ The :class:`IncrementalDecoder` may implement different error handling schemes
+ by providing the *errors* keyword argument. These parameters are predefined:
+
+ * ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default.
+
+ * ``'ignore'`` Ignore the character and continue with the next.
+
+ * ``'replace'`` Replace with a suitable replacement character.
+
+ The *errors* argument will be assigned to an attribute of the same name.
+ Assigning to this attribute makes it possible to switch between different error
+ handling strategies during the lifetime of the :class:`IncrementalEncoder`
+ object.
+
+ The set of allowed values for the *errors* argument can be extended with
+ :func:`register_error`.
+
+
+.. method:: IncrementalDecoder.decode(object[, final])
+
+ Decodes *object* (taking the current state of the decoder into account) and
+ returns the resulting decoded object. If this is the last call to :meth:`decode`
+ *final* must be true (the default is false). If *final* is true the decoder must
+ decode the input completely and must flush all buffers. If this isn't possible
+ (e.g. because of incomplete byte sequences at the end of the input) it must
+ initiate error handling just like in the stateless case (which might raise an
+ exception).
+
+
+.. method:: IncrementalDecoder.reset()
+
+ Reset the decoder to the initial state.
+
+The :class:`StreamWriter` and :class:`StreamReader` classes provide generic
+working interfaces which can be used to implement new encoding submodules very
+easily. See :mod:`encodings.utf_8` for an example of how this is done.
+
+
+.. _stream-writer-objects:
+
+StreamWriter Objects
+^^^^^^^^^^^^^^^^^^^^
+
+The :class:`StreamWriter` class is a subclass of :class:`Codec` and defines the
+following methods which every stream writer must define in order to be
+compatible with the Python codec registry.
+
+
+.. class:: StreamWriter(stream[, errors])
+
+ Constructor for a :class:`StreamWriter` instance.
+
+ All stream writers must provide this constructor interface. They are free to add
+ additional keyword arguments, but only the ones defined here are used by the
+ Python codec registry.
+
+ *stream* must be a file-like object open for writing binary data.
+
+ The :class:`StreamWriter` may implement different error handling schemes by
+ providing the *errors* keyword argument. These parameters are predefined:
+
+ * ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default.
+
+ * ``'ignore'`` Ignore the character and continue with the next.
+
+ * ``'replace'`` Replace with a suitable replacement character
+
+ * ``'xmlcharrefreplace'`` Replace with the appropriate XML character reference
+
+ * ``'backslashreplace'`` Replace with backslashed escape sequences.
+
+ The *errors* argument will be assigned to an attribute of the same name.
+ Assigning to this attribute makes it possible to switch between different error
+ handling strategies during the lifetime of the :class:`StreamWriter` object.
+
+ The set of allowed values for the *errors* argument can be extended with
+ :func:`register_error`.
+
+
+.. method:: StreamWriter.write(object)
+
+ Writes the object's contents encoded to the stream.
+
+
+.. method:: StreamWriter.writelines(list)
+
+ Writes the concatenated list of strings to the stream (possibly by reusing the
+ :meth:`write` method).
+
+
+.. method:: StreamWriter.reset()
+
+ Flushes and resets the codec buffers used for keeping state.
+
+ Calling this method should ensure that the data on the output is put into a
+ clean state that allows appending of new fresh data without having to rescan the
+ whole stream to recover state.
+
+In addition to the above methods, the :class:`StreamWriter` must also inherit
+all other methods and attributes from the underlying stream.
+
+
+.. _stream-reader-objects:
+
+StreamReader Objects
+^^^^^^^^^^^^^^^^^^^^
+
+The :class:`StreamReader` class is a subclass of :class:`Codec` and defines the
+following methods which every stream reader must define in order to be
+compatible with the Python codec registry.
+
+
+.. class:: StreamReader(stream[, errors])
+
+ Constructor for a :class:`StreamReader` instance.
+
+ All stream readers must provide this constructor interface. They are free to add
+ additional keyword arguments, but only the ones defined here are used by the
+ Python codec registry.
+
+ *stream* must be a file-like object open for reading (binary) data.
+
+ The :class:`StreamReader` may implement different error handling schemes by
+ providing the *errors* keyword argument. These parameters are defined:
+
+ * ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default.
+
+ * ``'ignore'`` Ignore the character and continue with the next.
+
+ * ``'replace'`` Replace with a suitable replacement character.
+
+ The *errors* argument will be assigned to an attribute of the same name.
+ Assigning to this attribute makes it possible to switch between different error
+ handling strategies during the lifetime of the :class:`StreamReader` object.
+
+ The set of allowed values for the *errors* argument can be extended with
+ :func:`register_error`.
+
+
+.. method:: StreamReader.read([size[, chars, [firstline]]])
+
+ Decodes data from the stream and returns the resulting object.
+
+ *chars* indicates the number of characters to read from the stream. :func:`read`
+ will never return more than *chars* characters, but it might return less, if
+ there are not enough characters available.
+
+ *size* indicates the approximate maximum number of bytes to read from the stream
+ for decoding purposes. The decoder can modify this setting as appropriate. The
+ default value -1 indicates to read and decode as much as possible. *size* is
+ intended to prevent having to decode huge files in one step.
+
+ *firstline* indicates that it would be sufficient to only return the first line,
+ if there are decoding errors on later lines.
+
+ The method should use a greedy read strategy meaning that it should read as much
+ data as is allowed within the definition of the encoding and the given size,
+ e.g. if optional encoding endings or state markers are available on the stream,
+ these should be read too.
+
+ .. versionchanged:: 2.4
+ *chars* argument added.
+
+ .. versionchanged:: 2.4.2
+ *firstline* argument added.
+
+
+.. method:: StreamReader.readline([size[, keepends]])
+
+ Read one line from the input stream and return the decoded data.
+
+ *size*, if given, is passed as size argument to the stream's :meth:`readline`
+ method.
+
+ If *keepends* is false line-endings will be stripped from the lines returned.
+
+ .. versionchanged:: 2.4
+ *keepends* argument added.
+
+
+.. method:: StreamReader.readlines([sizehint[, keepends]])
+
+ Read all lines available on the input stream and return them as a list of lines.
+
+ Line-endings are implemented using the codec's decoder method and are included
+ in the list entries if *keepends* is true.
+
+ *sizehint*, if given, is passed as the *size* argument to the stream's
+ :meth:`read` method.
+
+
+.. method:: StreamReader.reset()
+
+ Resets the codec buffers used for keeping state.
+
+ Note that no stream repositioning should take place. This method is primarily
+ intended to be able to recover from decoding errors.
+
+In addition to the above methods, the :class:`StreamReader` must also inherit
+all other methods and attributes from the underlying stream.
+
+The next two base classes are included for convenience. They are not needed by
+the codec registry, but may provide useful in practice.
+
+
+.. _stream-reader-writer:
+
+StreamReaderWriter Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :class:`StreamReaderWriter` allows wrapping streams which work in both read
+and write modes.
+
+The design is such that one can use the factory functions returned by the
+:func:`lookup` function to construct the instance.
+
+
+.. class:: StreamReaderWriter(stream, Reader, Writer, errors)
+
+ Creates a :class:`StreamReaderWriter` instance. *stream* must be a file-like
+ object. *Reader* and *Writer* must be factory functions or classes providing the
+ :class:`StreamReader` and :class:`StreamWriter` interface resp. Error handling
+ is done in the same way as defined for the stream readers and writers.
+
+:class:`StreamReaderWriter` instances define the combined interfaces of
+:class:`StreamReader` and :class:`StreamWriter` classes. They inherit all other
+methods and attributes from the underlying stream.
+
+
+.. _stream-recoder-objects:
+
+StreamRecoder Objects
+^^^^^^^^^^^^^^^^^^^^^
+
+The :class:`StreamRecoder` provide a frontend - backend view of encoding data
+which is sometimes useful when dealing with different encoding environments.
+
+The design is such that one can use the factory functions returned by the
+:func:`lookup` function to construct the instance.
+
+
+.. class:: StreamRecoder(stream, encode, decode, Reader, Writer, errors)
+
+ Creates a :class:`StreamRecoder` instance which implements a two-way conversion:
+ *encode* and *decode* work on the frontend (the input to :meth:`read` and output
+ of :meth:`write`) while *Reader* and *Writer* work on the backend (reading and
+ writing to the stream).
+
+ You can use these objects to do transparent direct recodings from e.g. Latin-1
+ to UTF-8 and back.
+
+ *stream* must be a file-like object.
+
+ *encode*, *decode* must adhere to the :class:`Codec` interface. *Reader*,
+ *Writer* must be factory functions or classes providing objects of the
+ :class:`StreamReader` and :class:`StreamWriter` interface respectively.
+
+ *encode* and *decode* are needed for the frontend translation, *Reader* and
+ *Writer* for the backend translation. The intermediate format used is
+ determined by the two sets of codecs, e.g. the Unicode codecs will use Unicode
+ as the intermediate encoding.
+
+ Error handling is done in the same way as defined for the stream readers and
+ writers.
+
+:class:`StreamRecoder` instances define the combined interfaces of
+:class:`StreamReader` and :class:`StreamWriter` classes. They inherit all other
+methods and attributes from the underlying stream.
+
+
+.. _encodings-overview:
+
+Encodings and Unicode
+---------------------
+
+Unicode strings are stored internally as sequences of codepoints (to be precise
+as :ctype:`Py_UNICODE` arrays). Depending on the way Python is compiled (either
+via :option:`--enable-unicode=ucs2` or :option:`--enable-unicode=ucs4`, with the
+former being the default) :ctype:`Py_UNICODE` is either a 16-bit or 32-bit data
+type. Once a Unicode object is used outside of CPU and memory, CPU endianness
+and how these arrays are stored as bytes become an issue. Transforming a
+unicode object into a sequence of bytes is called encoding and recreating the
+unicode object from the sequence of bytes is known as decoding. There are many
+different methods for how this transformation can be done (these methods are
+also called encodings). The simplest method is to map the codepoints 0-255 to
+the bytes ``0x0``-``0xff``. This means that a unicode object that contains
+codepoints above ``U+00FF`` can't be encoded with this method (which is called
+``'latin-1'`` or ``'iso-8859-1'``). :func:`unicode.encode` will raise a
+:exc:`UnicodeEncodeError` that looks like this: ``UnicodeEncodeError: 'latin-1'
+codec can't encode character u'\u1234' in position 3: ordinal not in
+range(256)``.
+
+There's another group of encodings (the so called charmap encodings) that choose
+a different subset of all unicode code points and how these codepoints are
+mapped to the bytes ``0x0``-``0xff``. To see how this is done simply open
+e.g. :file:`encodings/cp1252.py` (which is an encoding that is used primarily on
+Windows). There's a string constant with 256 characters that shows you which
+character is mapped to which byte value.
+
+All of these encodings can only encode 256 of the 65536 (or 1114111) codepoints
+defined in unicode. A simple and straightforward way that can store each Unicode
+code point, is to store each codepoint as two consecutive bytes. There are two
+possibilities: Store the bytes in big endian or in little endian order. These
+two encodings are called UTF-16-BE and UTF-16-LE respectively. Their
+disadvantage is that if e.g. you use UTF-16-BE on a little endian machine you
+will always have to swap bytes on encoding and decoding. UTF-16 avoids this
+problem: Bytes will always be in natural endianness. When these bytes are read
+by a CPU with a different endianness, then bytes have to be swapped though. To
+be able to detect the endianness of a UTF-16 byte sequence, there's the so
+called BOM (the "Byte Order Mark"). This is the Unicode character ``U+FEFF``.
+This character will be prepended to every UTF-16 byte sequence. The byte swapped
+version of this character (``0xFFFE``) is an illegal character that may not
+appear in a Unicode text. So when the first character in an UTF-16 byte sequence
+appears to be a ``U+FFFE`` the bytes have to be swapped on decoding.
+Unfortunately upto Unicode 4.0 the character ``U+FEFF`` had a second purpose as
+a ``ZERO WIDTH NO-BREAK SPACE``: A character that has no width and doesn't allow
+a word to be split. It can e.g. be used to give hints to a ligature algorithm.
+With Unicode 4.0 using ``U+FEFF`` as a ``ZERO WIDTH NO-BREAK SPACE`` has been
+deprecated (with ``U+2060`` (``WORD JOINER``) assuming this role). Nevertheless
+Unicode software still must be able to handle ``U+FEFF`` in both roles: As a BOM
+it's a device to determine the storage layout of the encoded bytes, and vanishes
+once the byte sequence has been decoded into a Unicode string; as a ``ZERO WIDTH
+NO-BREAK SPACE`` it's a normal character that will be decoded like any other.
+
+There's another encoding that is able to encoding the full range of Unicode
+characters: UTF-8. UTF-8 is an 8-bit encoding, which means there are no issues
+with byte order in UTF-8. Each byte in a UTF-8 byte sequence consists of two
+parts: Marker bits (the most significant bits) and payload bits. The marker bits
+are a sequence of zero to six 1 bits followed by a 0 bit. Unicode characters are
+encoded like this (with x being payload bits, which when concatenated give the
+Unicode character):
+
++-----------------------------------+----------------------------------------------+
+| Range | Encoding |
++===================================+==============================================+
+| ``U-00000000`` ... ``U-0000007F`` | 0xxxxxxx |
++-----------------------------------+----------------------------------------------+
+| ``U-00000080`` ... ``U-000007FF`` | 110xxxxx 10xxxxxx |
++-----------------------------------+----------------------------------------------+
+| ``U-00000800`` ... ``U-0000FFFF`` | 1110xxxx 10xxxxxx 10xxxxxx |
++-----------------------------------+----------------------------------------------+
+| ``U-00010000`` ... ``U-001FFFFF`` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |
++-----------------------------------+----------------------------------------------+
+| ``U-00200000`` ... ``U-03FFFFFF`` | 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx |
++-----------------------------------+----------------------------------------------+
+| ``U-04000000`` ... ``U-7FFFFFFF`` | 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx |
+| | 10xxxxxx |
++-----------------------------------+----------------------------------------------+
+
+The least significant bit of the Unicode character is the rightmost x bit.
+
+As UTF-8 is an 8-bit encoding no BOM is required and any ``U+FEFF`` character in
+the decoded Unicode string (even if it's the first character) is treated as a
+``ZERO WIDTH NO-BREAK SPACE``.
+
+Without external information it's impossible to reliably determine which
+encoding was used for encoding a Unicode string. Each charmap encoding can
+decode any random byte sequence. However that's not possible with UTF-8, as
+UTF-8 byte sequences have a structure that doesn't allow arbitrary byte
+sequence. To increase the reliability with which a UTF-8 encoding can be
+detected, Microsoft invented a variant of UTF-8 (that Python 2.5 calls
+``"utf-8-sig"``) for its Notepad program: Before any of the Unicode characters
+is written to the file, a UTF-8 encoded BOM (which looks like this as a byte
+sequence: ``0xef``, ``0xbb``, ``0xbf``) is written. As it's rather improbable
+that any charmap encoded file starts with these byte values (which would e.g.
+map to
+
+ | LATIN SMALL LETTER I WITH DIAERESIS
+ | RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
+ | INVERTED QUESTION MARK
+
+in iso-8859-1), this increases the probability that a utf-8-sig encoding can be
+correctly guessed from the byte sequence. So here the BOM is not used to be able
+to determine the byte order used for generating the byte sequence, but as a
+signature that helps in guessing the encoding. On encoding the utf-8-sig codec
+will write ``0xef``, ``0xbb``, ``0xbf`` as the first three bytes to the file. On
+decoding utf-8-sig will skip those three bytes if they appear as the first three
+bytes in the file.
+
+
+.. _standard-encodings:
+
+Standard Encodings
+------------------
+
+Python comes with a number of codecs built-in, either implemented as C functions
+or with dictionaries as mapping tables. The following table lists the codecs by
+name, together with a few common aliases, and the languages for which the
+encoding is likely used. Neither the list of aliases nor the list of languages
+is meant to be exhaustive. Notice that spelling alternatives that only differ in
+case or use a hyphen instead of an underscore are also valid aliases.
+
+Many of the character sets support the same languages. They vary in individual
+characters (e.g. whether the EURO SIGN is supported or not), and in the
+assignment of characters to code positions. For the European languages in
+particular, the following variants typically exist:
+
+* an ISO 8859 codeset
+
+* a Microsoft Windows code page, which is typically derived from a 8859 codeset,
+ but replaces control characters with additional graphic characters
+
+* an IBM EBCDIC code page
+
+* an IBM PC code page, which is ASCII compatible
+
++-----------------+--------------------------------+--------------------------------+
+| Codec | Aliases | Languages |
++=================+================================+================================+
+| ascii | 646, us-ascii | English |
++-----------------+--------------------------------+--------------------------------+
+| big5 | big5-tw, csbig5 | Traditional Chinese |
++-----------------+--------------------------------+--------------------------------+
+| big5hkscs | big5-hkscs, hkscs | Traditional Chinese |
++-----------------+--------------------------------+--------------------------------+
+| cp037 | IBM037, IBM039 | English |
++-----------------+--------------------------------+--------------------------------+
+| cp424 | EBCDIC-CP-HE, IBM424 | Hebrew |
++-----------------+--------------------------------+--------------------------------+
+| cp437 | 437, IBM437 | English |
++-----------------+--------------------------------+--------------------------------+
+| cp500 | EBCDIC-CP-BE, EBCDIC-CP-CH, | Western Europe |
+| | IBM500 | |
++-----------------+--------------------------------+--------------------------------+
+| cp737 | | Greek |
++-----------------+--------------------------------+--------------------------------+
+| cp775 | IBM775 | Baltic languages |
++-----------------+--------------------------------+--------------------------------+
+| cp850 | 850, IBM850 | Western Europe |
++-----------------+--------------------------------+--------------------------------+
+| cp852 | 852, IBM852 | Central and Eastern Europe |
++-----------------+--------------------------------+--------------------------------+
+| cp855 | 855, IBM855 | Bulgarian, Byelorussian, |
+| | | Macedonian, Russian, Serbian |
++-----------------+--------------------------------+--------------------------------+
+| cp856 | | Hebrew |
++-----------------+--------------------------------+--------------------------------+
+| cp857 | 857, IBM857 | Turkish |
++-----------------+--------------------------------+--------------------------------+
+| cp860 | 860, IBM860 | Portuguese |
++-----------------+--------------------------------+--------------------------------+
+| cp861 | 861, CP-IS, IBM861 | Icelandic |
++-----------------+--------------------------------+--------------------------------+
+| cp862 | 862, IBM862 | Hebrew |
++-----------------+--------------------------------+--------------------------------+
+| cp863 | 863, IBM863 | Canadian |
++-----------------+--------------------------------+--------------------------------+
+| cp864 | IBM864 | Arabic |
++-----------------+--------------------------------+--------------------------------+
+| cp865 | 865, IBM865 | Danish, Norwegian |
++-----------------+--------------------------------+--------------------------------+
+| cp866 | 866, IBM866 | Russian |
++-----------------+--------------------------------+--------------------------------+
+| cp869 | 869, CP-GR, IBM869 | Greek |
++-----------------+--------------------------------+--------------------------------+
+| cp874 | | Thai |
++-----------------+--------------------------------+--------------------------------+
+| cp875 | | Greek |
++-----------------+--------------------------------+--------------------------------+
+| cp932 | 932, ms932, mskanji, ms-kanji | Japanese |
++-----------------+--------------------------------+--------------------------------+
+| cp949 | 949, ms949, uhc | Korean |
++-----------------+--------------------------------+--------------------------------+
+| cp950 | 950, ms950 | Traditional Chinese |
++-----------------+--------------------------------+--------------------------------+
+| cp1006 | | Urdu |
++-----------------+--------------------------------+--------------------------------+
+| cp1026 | ibm1026 | Turkish |
++-----------------+--------------------------------+--------------------------------+
+| cp1140 | ibm1140 | Western Europe |
++-----------------+--------------------------------+--------------------------------+
+| cp1250 | windows-1250 | Central and Eastern Europe |
++-----------------+--------------------------------+--------------------------------+
+| cp1251 | windows-1251 | Bulgarian, Byelorussian, |
+| | | Macedonian, Russian, Serbian |
++-----------------+--------------------------------+--------------------------------+
+| cp1252 | windows-1252 | Western Europe |
++-----------------+--------------------------------+--------------------------------+
+| cp1253 | windows-1253 | Greek |
++-----------------+--------------------------------+--------------------------------+
+| cp1254 | windows-1254 | Turkish |
++-----------------+--------------------------------+--------------------------------+
+| cp1255 | windows-1255 | Hebrew |
++-----------------+--------------------------------+--------------------------------+
+| cp1256 | windows1256 | Arabic |
++-----------------+--------------------------------+--------------------------------+
+| cp1257 | windows-1257 | Baltic languages |
++-----------------+--------------------------------+--------------------------------+
+| cp1258 | windows-1258 | Vietnamese |
++-----------------+--------------------------------+--------------------------------+
+| euc_jp | eucjp, ujis, u-jis | Japanese |
++-----------------+--------------------------------+--------------------------------+
+| euc_jis_2004 | jisx0213, eucjis2004 | Japanese |
++-----------------+--------------------------------+--------------------------------+
+| euc_jisx0213 | eucjisx0213 | Japanese |
++-----------------+--------------------------------+--------------------------------+
+| euc_kr | euckr, korean, ksc5601, | Korean |
+| | ks_c-5601, ks_c-5601-1987, | |
+| | ksx1001, ks_x-1001 | |
++-----------------+--------------------------------+--------------------------------+
+| gb2312 | chinese, csiso58gb231280, euc- | Simplified Chinese |
+| | cn, euccn, eucgb2312-cn, | |
+| | gb2312-1980, gb2312-80, iso- | |
+| | ir-58 | |
++-----------------+--------------------------------+--------------------------------+
+| gbk | 936, cp936, ms936 | Unified Chinese |
++-----------------+--------------------------------+--------------------------------+
+| gb18030 | gb18030-2000 | Unified Chinese |
++-----------------+--------------------------------+--------------------------------+
+| hz | hzgb, hz-gb, hz-gb-2312 | Simplified Chinese |
++-----------------+--------------------------------+--------------------------------+
+| iso2022_jp | csiso2022jp, iso2022jp, | Japanese |
+| | iso-2022-jp | |
++-----------------+--------------------------------+--------------------------------+
+| iso2022_jp_1 | iso2022jp-1, iso-2022-jp-1 | Japanese |
++-----------------+--------------------------------+--------------------------------+
+| iso2022_jp_2 | iso2022jp-2, iso-2022-jp-2 | Japanese, Korean, Simplified |
+| | | Chinese, Western Europe, Greek |
++-----------------+--------------------------------+--------------------------------+
+| iso2022_jp_2004 | iso2022jp-2004, | Japanese |
+| | iso-2022-jp-2004 | |
++-----------------+--------------------------------+--------------------------------+
+| iso2022_jp_3 | iso2022jp-3, iso-2022-jp-3 | Japanese |
++-----------------+--------------------------------+--------------------------------+
+| iso2022_jp_ext | iso2022jp-ext, iso-2022-jp-ext | Japanese |
++-----------------+--------------------------------+--------------------------------+
+| iso2022_kr | csiso2022kr, iso2022kr, | Korean |
+| | iso-2022-kr | |
++-----------------+--------------------------------+--------------------------------+
+| latin_1 | iso-8859-1, iso8859-1, 8859, | West Europe |
+| | cp819, latin, latin1, L1 | |
++-----------------+--------------------------------+--------------------------------+
+| iso8859_2 | iso-8859-2, latin2, L2 | Central and Eastern Europe |
++-----------------+--------------------------------+--------------------------------+
+| iso8859_3 | iso-8859-3, latin3, L3 | Esperanto, Maltese |
++-----------------+--------------------------------+--------------------------------+
+| iso8859_4 | iso-8859-4, latin4, L4 | Baltic languagues |
++-----------------+--------------------------------+--------------------------------+
+| iso8859_5 | iso-8859-5, cyrillic | Bulgarian, Byelorussian, |
+| | | Macedonian, Russian, Serbian |
++-----------------+--------------------------------+--------------------------------+
+| iso8859_6 | iso-8859-6, arabic | Arabic |
++-----------------+--------------------------------+--------------------------------+
+| iso8859_7 | iso-8859-7, greek, greek8 | Greek |
++-----------------+--------------------------------+--------------------------------+
+| iso8859_8 | iso-8859-8, hebrew | Hebrew |
++-----------------+--------------------------------+--------------------------------+
+| iso8859_9 | iso-8859-9, latin5, L5 | Turkish |
++-----------------+--------------------------------+--------------------------------+
+| iso8859_10 | iso-8859-10, latin6, L6 | Nordic languages |
++-----------------+--------------------------------+--------------------------------+
+| iso8859_13 | iso-8859-13 | Baltic languages |
++-----------------+--------------------------------+--------------------------------+
+| iso8859_14 | iso-8859-14, latin8, L8 | Celtic languages |
++-----------------+--------------------------------+--------------------------------+
+| iso8859_15 | iso-8859-15 | Western Europe |
++-----------------+--------------------------------+--------------------------------+
+| johab | cp1361, ms1361 | Korean |
++-----------------+--------------------------------+--------------------------------+
+| koi8_r | | Russian |
++-----------------+--------------------------------+--------------------------------+
+| koi8_u | | Ukrainian |
++-----------------+--------------------------------+--------------------------------+
+| mac_cyrillic | maccyrillic | Bulgarian, Byelorussian, |
+| | | Macedonian, Russian, Serbian |
++-----------------+--------------------------------+--------------------------------+
+| mac_greek | macgreek | Greek |
++-----------------+--------------------------------+--------------------------------+
+| mac_iceland | maciceland | Icelandic |
++-----------------+--------------------------------+--------------------------------+
+| mac_latin2 | maclatin2, maccentraleurope | Central and Eastern Europe |
++-----------------+--------------------------------+--------------------------------+
+| mac_roman | macroman | Western Europe |
++-----------------+--------------------------------+--------------------------------+
+| mac_turkish | macturkish | Turkish |
++-----------------+--------------------------------+--------------------------------+
+| ptcp154 | csptcp154, pt154, cp154, | Kazakh |
+| | cyrillic-asian | |
++-----------------+--------------------------------+--------------------------------+
+| shift_jis | csshiftjis, shiftjis, sjis, | Japanese |
+| | s_jis | |
++-----------------+--------------------------------+--------------------------------+
+| shift_jis_2004 | shiftjis2004, sjis_2004, | Japanese |
+| | sjis2004 | |
++-----------------+--------------------------------+--------------------------------+
+| shift_jisx0213 | shiftjisx0213, sjisx0213, | Japanese |
+| | s_jisx0213 | |
++-----------------+--------------------------------+--------------------------------+
+| utf_16 | U16, utf16 | all languages |
++-----------------+--------------------------------+--------------------------------+
+| utf_16_be | UTF-16BE | all languages (BMP only) |
++-----------------+--------------------------------+--------------------------------+
+| utf_16_le | UTF-16LE | all languages (BMP only) |
++-----------------+--------------------------------+--------------------------------+
+| utf_7 | U7, unicode-1-1-utf-7 | all languages |
++-----------------+--------------------------------+--------------------------------+
+| utf_8 | U8, UTF, utf8 | all languages |
++-----------------+--------------------------------+--------------------------------+
+| utf_8_sig | | all languages |
++-----------------+--------------------------------+--------------------------------+
+
+A number of codecs are specific to Python, so their codec names have no meaning
+outside Python. Some of them don't convert from Unicode strings to byte strings,
+but instead use the property of the Python codecs machinery that any bijective
+function with one argument can be considered as an encoding.
+
+For the codecs listed below, the result in the "encoding" direction is always a
+byte string. The result of the "decoding" direction is listed as operand type in
+the table.
+
++--------------------+---------------------------+----------------+---------------------------+
+| Codec | Aliases | Operand type | Purpose |
++====================+===========================+================+===========================+
+| base64_codec | base64, base-64 | byte string | Convert operand to MIME |
+| | | | base64 |
++--------------------+---------------------------+----------------+---------------------------+
+| bz2_codec | bz2 | byte string | Compress the operand |
+| | | | using bz2 |
++--------------------+---------------------------+----------------+---------------------------+
+| hex_codec | hex | byte string | Convert operand to |
+| | | | hexadecimal |
+| | | | representation, with two |
+| | | | digits per byte |
++--------------------+---------------------------+----------------+---------------------------+
+| idna | | Unicode string | Implements :rfc:`3490`, |
+| | | | see also |
+| | | | :mod:`encodings.idna` |
++--------------------+---------------------------+----------------+---------------------------+
+| mbcs | dbcs | Unicode string | Windows only: Encode |
+| | | | operand according to the |
+| | | | ANSI codepage (CP_ACP) |
++--------------------+---------------------------+----------------+---------------------------+
+| palmos | | Unicode string | Encoding of PalmOS 3.5 |
++--------------------+---------------------------+----------------+---------------------------+
+| punycode | | Unicode string | Implements :rfc:`3492` |
++--------------------+---------------------------+----------------+---------------------------+
+| quopri_codec | quopri, quoted-printable, | byte string | Convert operand to MIME |
+| | quotedprintable | | quoted printable |
++--------------------+---------------------------+----------------+---------------------------+
+| raw_unicode_escape | | Unicode string | Produce a string that is |
+| | | | suitable as raw Unicode |
+| | | | literal in Python source |
+| | | | code |
++--------------------+---------------------------+----------------+---------------------------+
+| rot_13 | rot13 | Unicode string | Returns the Caesar-cypher |
+| | | | encryption of the operand |
++--------------------+---------------------------+----------------+---------------------------+
+| string_escape | | byte string | Produce a string that is |
+| | | | suitable as string |
+| | | | literal in Python source |
+| | | | code |
++--------------------+---------------------------+----------------+---------------------------+
+| undefined | | any | Raise an exception for |
+| | | | all conversions. Can be |
+| | | | used as the system |
+| | | | encoding if no automatic |
+| | | | coercion between byte and |
+| | | | Unicode strings is |
+| | | | desired. |
++--------------------+---------------------------+----------------+---------------------------+
+| unicode_escape | | Unicode string | Produce a string that is |
+| | | | suitable as Unicode |
+| | | | literal in Python source |
+| | | | code |
++--------------------+---------------------------+----------------+---------------------------+
+| unicode_internal | | Unicode string | Return the internal |
+| | | | representation of the |
+| | | | operand |
++--------------------+---------------------------+----------------+---------------------------+
+| uu_codec | uu | byte string | Convert the operand using |
+| | | | uuencode |
++--------------------+---------------------------+----------------+---------------------------+
+| zlib_codec | zip, zlib | byte string | Compress the operand |
+| | | | using gzip |
++--------------------+---------------------------+----------------+---------------------------+
+
+.. versionadded:: 2.3
+ The ``idna`` and ``punycode`` encodings.
+
+
+:mod:`encodings.idna` --- Internationalized Domain Names in Applications
+------------------------------------------------------------------------
+
+.. module:: encodings.idna
+ :synopsis: Internationalized Domain Names implementation
+.. moduleauthor:: Martin v. Löwis
+
+.. versionadded:: 2.3
+
+This module implements :rfc:`3490` (Internationalized Domain Names in
+Applications) and :rfc:`3492` (Nameprep: A Stringprep Profile for
+Internationalized Domain Names (IDN)). It builds upon the ``punycode`` encoding
+and :mod:`stringprep`.
+
+These RFCs together define a protocol to support non-ASCII characters in domain
+names. A domain name containing non-ASCII characters (such as
+``www.Alliancefrançaise.nu``) is converted into an ASCII-compatible encoding
+(ACE, such as ``www.xn--alliancefranaise-npb.nu``). The ACE form of the domain
+name is then used in all places where arbitrary characters are not allowed by
+the protocol, such as DNS queries, HTTP :mailheader:`Host` fields, and so
+on. This conversion is carried out in the application; if possible invisible to
+the user: The application should transparently convert Unicode domain labels to
+IDNA on the wire, and convert back ACE labels to Unicode before presenting them
+to the user.
+
+Python supports this conversion in several ways: The ``idna`` codec allows to
+convert between Unicode and the ACE. Furthermore, the :mod:`socket` module
+transparently converts Unicode host names to ACE, so that applications need not
+be concerned about converting host names themselves when they pass them to the
+socket module. On top of that, modules that have host names as function
+parameters, such as :mod:`httplib` and :mod:`ftplib`, accept Unicode host names
+(:mod:`httplib` then also transparently sends an IDNA hostname in the
+:mailheader:`Host` field if it sends that field at all).
+
+When receiving host names from the wire (such as in reverse name lookup), no
+automatic conversion to Unicode is performed: Applications wishing to present
+such host names to the user should decode them to Unicode.
+
+The module :mod:`encodings.idna` also implements the nameprep procedure, which
+performs certain normalizations on host names, to achieve case-insensitivity of
+international domain names, and to unify similar characters. The nameprep
+functions can be used directly if desired.
+
+
+.. function:: nameprep(label)
+
+ Return the nameprepped version of *label*. The implementation currently assumes
+ query strings, so ``AllowUnassigned`` is true.
+
+
+.. function:: ToASCII(label)
+
+ Convert a label to ASCII, as specified in :rfc:`3490`. ``UseSTD3ASCIIRules`` is
+ assumed to be false.
+
+
+.. function:: ToUnicode(label)
+
+ Convert a label to Unicode, as specified in :rfc:`3490`.
+
+
+:mod:`encodings.utf_8_sig` --- UTF-8 codec with BOM signature
+-------------------------------------------------------------
+
+.. module:: encodings.utf_8_sig
+ :synopsis: UTF-8 codec with BOM signature
+.. moduleauthor:: Walter Dörwald
+
+.. versionadded:: 2.5
+
+This module implements a variant of the UTF-8 codec: On encoding a UTF-8 encoded
+BOM will be prepended to the UTF-8 encoded bytes. For the stateful encoder this
+is only done once (on the first write to the byte stream). For decoding an
+optional UTF-8 encoded BOM at the start of the data will be skipped.
+
--- /dev/null
+
+:mod:`codeop` --- Compile Python code
+=====================================
+
+.. module:: codeop
+ :synopsis: Compile (possibly incomplete) Python code.
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+.. sectionauthor:: Michael Hudson <mwh@python.net>
+
+
+.. % LaTeXed from excellent doc-string.
+
+The :mod:`codeop` module provides utilities upon which the Python
+read-eval-print loop can be emulated, as is done in the :mod:`code` module. As
+a result, you probably don't want to use the module directly; if you want to
+include such a loop in your program you probably want to use the :mod:`code`
+module instead.
+
+There are two parts to this job:
+
+#. Being able to tell if a line of input completes a Python statement: in
+ short, telling whether to print '``>>>``' or '``...``' next.
+
+#. Remembering which future statements the user has entered, so subsequent
+ input can be compiled with these in effect.
+
+The :mod:`codeop` module provides a way of doing each of these things, and a way
+of doing them both.
+
+To do just the former:
+
+
+.. function:: compile_command(source[, filename[, symbol]])
+
+ Tries to compile *source*, which should be a string of Python code and return a
+ code object if *source* is valid Python code. In that case, the filename
+ attribute of the code object will be *filename*, which defaults to
+ ``'<input>'``. Returns ``None`` if *source* is *not* valid Python code, but is a
+ prefix of valid Python code.
+
+ If there is a problem with *source*, an exception will be raised.
+ :exc:`SyntaxError` is raised if there is invalid Python syntax, and
+ :exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal.
+
+ The *symbol* argument determines whether *source* is compiled as a statement
+ (``'single'``, the default) or as an expression (``'eval'``). Any other value
+ will cause :exc:`ValueError` to be raised.
+
+ **Caveat:** It is possible (but not likely) that the parser stops parsing with a
+ successful outcome before reaching the end of the source; in this case, trailing
+ symbols may be ignored instead of causing an error. For example, a backslash
+ followed by two newlines may be followed by arbitrary garbage. This will be
+ fixed once the API for the parser is better.
+
+
+.. class:: Compile()
+
+ Instances of this class have :meth:`__call__` methods identical in signature to
+ the built-in function :func:`compile`, but with the difference that if the
+ instance compiles program text containing a :mod:`__future__` statement, the
+ instance 'remembers' and compiles all subsequent program texts with the
+ statement in force.
+
+
+.. class:: CommandCompiler()
+
+ Instances of this class have :meth:`__call__` methods identical in signature to
+ :func:`compile_command`; the difference is that if the instance compiles program
+ text containing a ``__future__`` statement, the instance 'remembers' and
+ compiles all subsequent program texts with the statement in force.
+
+A note on version compatibility: the :class:`Compile` and
+:class:`CommandCompiler` are new in Python 2.2. If you want to enable the
+future-tracking features of 2.2 but also retain compatibility with 2.1 and
+earlier versions of Python you can either write ::
+
+ try:
+ from codeop import CommandCompiler
+ compile_command = CommandCompiler()
+ del CommandCompiler
+ except ImportError:
+ from codeop import compile_command
+
+which is a low-impact change, but introduces possibly unwanted global state into
+your program, or you can write::
+
+ try:
+ from codeop import CommandCompiler
+ except ImportError:
+ def CommandCompiler():
+ from codeop import compile_command
+ return compile_command
+
+and then call ``CommandCompiler`` every time you need a fresh compiler object.
+
--- /dev/null
+
+:mod:`collections` --- High-performance container datatypes
+===========================================================
+
+.. module:: collections
+ :synopsis: High-performance datatypes
+.. moduleauthor:: Raymond Hettinger <python@rcn.com>
+.. sectionauthor:: Raymond Hettinger <python@rcn.com>
+
+
+.. versionadded:: 2.4
+
+This module implements high-performance container datatypes. Currently,
+there are two datatypes, :class:`deque` and :class:`defaultdict`, and
+one datatype factory function, :func:`NamedTuple`. Python already
+includes built-in containers, :class:`dict`, :class:`list`,
+:class:`set`, and :class:`tuple`. In addition, the optional :mod:`bsddb`
+module has a :meth:`bsddb.btopen` method that can be used to create in-memory
+or file based ordered dictionaries with string keys.
+
+Future editions of the standard library may include balanced trees and
+ordered dictionaries.
+
+.. versionchanged:: 2.5
+ Added :class:`defaultdict`.
+
+.. versionchanged:: 2.6
+ Added :class:`NamedTuple`.
+
+
+.. _deque-objects:
+
+:class:`deque` objects
+----------------------
+
+
+.. class:: deque([iterable])
+
+ Returns a new deque object initialized left-to-right (using :meth:`append`) with
+ data from *iterable*. If *iterable* is not specified, the new deque is empty.
+
+ Deques are a generalization of stacks and queues (the name is pronounced "deck"
+ and is short for "double-ended queue"). Deques support thread-safe, memory
+ efficient appends and pops from either side of the deque with approximately the
+ same O(1) performance in either direction.
+
+ Though :class:`list` objects support similar operations, they are optimized for
+ fast fixed-length operations and incur O(n) memory movement costs for
+ ``pop(0)`` and ``insert(0, v)`` operations which change both the size and
+ position of the underlying data representation.
+
+ .. versionadded:: 2.4
+
+Deque objects support the following methods:
+
+
+.. method:: deque.append(x)
+
+ Add *x* to the right side of the deque.
+
+
+.. method:: deque.appendleft(x)
+
+ Add *x* to the left side of the deque.
+
+
+.. method:: deque.clear()
+
+ Remove all elements from the deque leaving it with length 0.
+
+
+.. method:: deque.extend(iterable)
+
+ Extend the right side of the deque by appending elements from the iterable
+ argument.
+
+
+.. method:: deque.extendleft(iterable)
+
+ Extend the left side of the deque by appending elements from *iterable*. Note,
+ the series of left appends results in reversing the order of elements in the
+ iterable argument.
+
+
+.. method:: deque.pop()
+
+ Remove and return an element from the right side of the deque. If no elements
+ are present, raises an :exc:`IndexError`.
+
+
+.. method:: deque.popleft()
+
+ Remove and return an element from the left side of the deque. If no elements are
+ present, raises an :exc:`IndexError`.
+
+
+.. method:: deque.remove(value)
+
+ Removed the first occurrence of *value*. If not found, raises a
+ :exc:`ValueError`.
+
+ .. versionadded:: 2.5
+
+
+.. method:: deque.rotate(n)
+
+ Rotate the deque *n* steps to the right. If *n* is negative, rotate to the
+ left. Rotating one step to the right is equivalent to:
+ ``d.appendleft(d.pop())``.
+
+In addition to the above, deques support iteration, pickling, ``len(d)``,
+``reversed(d)``, ``copy.copy(d)``, ``copy.deepcopy(d)``, membership testing with
+the :keyword:`in` operator, and subscript references such as ``d[-1]``.
+
+Example::
+
+ >>> from collections import deque
+ >>> d = deque('ghi') # make a new deque with three items
+ >>> for elem in d: # iterate over the deque's elements
+ ... print elem.upper()
+ G
+ H
+ I
+
+ >>> d.append('j') # add a new entry to the right side
+ >>> d.appendleft('f') # add a new entry to the left side
+ >>> d # show the representation of the deque
+ deque(['f', 'g', 'h', 'i', 'j'])
+
+ >>> d.pop() # return and remove the rightmost item
+ 'j'
+ >>> d.popleft() # return and remove the leftmost item
+ 'f'
+ >>> list(d) # list the contents of the deque
+ ['g', 'h', 'i']
+ >>> d[0] # peek at leftmost item
+ 'g'
+ >>> d[-1] # peek at rightmost item
+ 'i'
+
+ >>> list(reversed(d)) # list the contents of a deque in reverse
+ ['i', 'h', 'g']
+ >>> 'h' in d # search the deque
+ True
+ >>> d.extend('jkl') # add multiple elements at once
+ >>> d
+ deque(['g', 'h', 'i', 'j', 'k', 'l'])
+ >>> d.rotate(1) # right rotation
+ >>> d
+ deque(['l', 'g', 'h', 'i', 'j', 'k'])
+ >>> d.rotate(-1) # left rotation
+ >>> d
+ deque(['g', 'h', 'i', 'j', 'k', 'l'])
+
+ >>> deque(reversed(d)) # make a new deque in reverse order
+ deque(['l', 'k', 'j', 'i', 'h', 'g'])
+ >>> d.clear() # empty the deque
+ >>> d.pop() # cannot pop from an empty deque
+ Traceback (most recent call last):
+ File "<pyshell#6>", line 1, in -toplevel-
+ d.pop()
+ IndexError: pop from an empty deque
+
+ >>> d.extendleft('abc') # extendleft() reverses the input order
+ >>> d
+ deque(['c', 'b', 'a'])
+
+
+.. _deque-recipes:
+
+Recipes
+^^^^^^^
+
+This section shows various approaches to working with deques.
+
+The :meth:`rotate` method provides a way to implement :class:`deque` slicing and
+deletion. For example, a pure python implementation of ``del d[n]`` relies on
+the :meth:`rotate` method to position elements to be popped::
+
+ def delete_nth(d, n):
+ d.rotate(-n)
+ d.popleft()
+ d.rotate(n)
+
+To implement :class:`deque` slicing, use a similar approach applying
+:meth:`rotate` to bring a target element to the left side of the deque. Remove
+old entries with :meth:`popleft`, add new entries with :meth:`extend`, and then
+reverse the rotation.
+
+With minor variations on that approach, it is easy to implement Forth style
+stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
+``rot``, and ``roll``.
+
+A roundrobin task server can be built from a :class:`deque` using
+:meth:`popleft` to select the current task and :meth:`append` to add it back to
+the tasklist if the input stream is not exhausted::
+
+ >>> def roundrobin(*iterables):
+ ... pending = deque(iter(i) for i in iterables)
+ ... while pending:
+ ... task = pending.popleft()
+ ... try:
+ ... yield task.next()
+ ... except StopIteration:
+ ... continue
+ ... pending.append(task)
+ ...
+ >>> for value in roundrobin('abc', 'd', 'efgh'):
+ ... print value
+
+ a
+ d
+ e
+ b
+ f
+ c
+ g
+ h
+
+
+Multi-pass data reduction algorithms can be succinctly expressed and efficiently
+coded by extracting elements with multiple calls to :meth:`popleft`, applying
+the reduction function, and calling :meth:`append` to add the result back to the
+queue.
+
+For example, building a balanced binary tree of nested lists entails reducing
+two adjacent nodes into one by grouping them in a list::
+
+ >>> def maketree(iterable):
+ ... d = deque(iterable)
+ ... while len(d) > 1:
+ ... pair = [d.popleft(), d.popleft()]
+ ... d.append(pair)
+ ... return list(d)
+ ...
+ >>> print maketree('abcdefgh')
+ [[[['a', 'b'], ['c', 'd']], [['e', 'f'], ['g', 'h']]]]
+
+
+
+.. _defaultdict-objects:
+
+:class:`defaultdict` objects
+----------------------------
+
+
+.. class:: defaultdict([default_factory[, ...]])
+
+ Returns a new dictionary-like object. :class:`defaultdict` is a subclass of the
+ builtin :class:`dict` class. It overrides one method and adds one writable
+ instance variable. The remaining functionality is the same as for the
+ :class:`dict` class and is not documented here.
+
+ The first argument provides the initial value for the :attr:`default_factory`
+ attribute; it defaults to ``None``. All remaining arguments are treated the same
+ as if they were passed to the :class:`dict` constructor, including keyword
+ arguments.
+
+ .. versionadded:: 2.5
+
+:class:`defaultdict` objects support the following method in addition to the
+standard :class:`dict` operations:
+
+
+.. method:: defaultdict.__missing__(key)
+
+ If the :attr:`default_factory` attribute is ``None``, this raises an
+ :exc:`KeyError` exception with the *key* as argument.
+
+ If :attr:`default_factory` is not ``None``, it is called without arguments to
+ provide a default value for the given *key*, this value is inserted in the
+ dictionary for the *key*, and returned.
+
+ If calling :attr:`default_factory` raises an exception this exception is
+ propagated unchanged.
+
+ This method is called by the :meth:`__getitem__` method of the :class:`dict`
+ class when the requested key is not found; whatever it returns or raises is then
+ returned or raised by :meth:`__getitem__`.
+
+:class:`defaultdict` objects support the following instance variable:
+
+
+.. attribute:: defaultdict.default_factory
+
+ This attribute is used by the :meth:`__missing__` method; it is initialized from
+ the first argument to the constructor, if present, or to ``None``, if absent.
+
+
+.. _defaultdict-examples:
+
+:class:`defaultdict` Examples
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Using :class:`list` as the :attr:`default_factory`, it is easy to group a
+sequence of key-value pairs into a dictionary of lists::
+
+ >>> s = [('yellow', 1), ('blue', 2), ('yellow', 3), ('blue', 4), ('red', 1)]
+ >>> d = defaultdict(list)
+ >>> for k, v in s:
+ ... d[k].append(v)
+ ...
+ >>> d.items()
+ [('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
+
+When each key is encountered for the first time, it is not already in the
+mapping; so an entry is automatically created using the :attr:`default_factory`
+function which returns an empty :class:`list`. The :meth:`list.append`
+operation then attaches the value to the new list. When keys are encountered
+again, the look-up proceeds normally (returning the list for that key) and the
+:meth:`list.append` operation adds another value to the list. This technique is
+simpler and faster than an equivalent technique using :meth:`dict.setdefault`::
+
+ >>> d = {}
+ >>> for k, v in s:
+ ... d.setdefault(k, []).append(v)
+ ...
+ >>> d.items()
+ [('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
+
+Setting the :attr:`default_factory` to :class:`int` makes the
+:class:`defaultdict` useful for counting (like a bag or multiset in other
+languages)::
+
+ >>> s = 'mississippi'
+ >>> d = defaultdict(int)
+ >>> for k in s:
+ ... d[k] += 1
+ ...
+ >>> d.items()
+ [('i', 4), ('p', 2), ('s', 4), ('m', 1)]
+
+When a letter is first encountered, it is missing from the mapping, so the
+:attr:`default_factory` function calls :func:`int` to supply a default count of
+zero. The increment operation then builds up the count for each letter.
+
+The function :func:`int` which always returns zero is just a special case of
+constant functions. A faster and more flexible way to create constant functions
+is to use :func:`itertools.repeat` which can supply any constant value (not just
+zero)::
+
+ >>> def constant_factory(value):
+ ... return itertools.repeat(value).next
+ >>> d = defaultdict(constant_factory('<missing>'))
+ >>> d.update(name='John', action='ran')
+ >>> '%(name)s %(action)s to %(object)s' % d
+ 'John ran to <missing>'
+
+Setting the :attr:`default_factory` to :class:`set` makes the
+:class:`defaultdict` useful for building a dictionary of sets::
+
+ >>> s = [('red', 1), ('blue', 2), ('red', 3), ('blue', 4), ('red', 1), ('blue', 4)]
+ >>> d = defaultdict(set)
+ >>> for k, v in s:
+ ... d[k].add(v)
+ ...
+ >>> d.items()
+ [('blue', set([2, 4])), ('red', set([1, 3]))]
+
+
+.. _named-tuple-factory:
+
+:func:`NamedTuple` datatype factory function
+--------------------------------------------
+
+
+.. function:: NamedTuple(typename, fieldnames)
+
+ Returns a new tuple subclass named *typename*. The new subclass is used to
+ create tuple-like objects that have fields accessable by attribute lookup as
+ well as being indexable and iterable. Instances of the subclass also have a
+ helpful docstring (with typename and fieldnames) and a helpful :meth:`__repr__`
+ method which lists the tuple contents in a ``name=value`` format.
+
+ .. versionadded:: 2.6
+
+ The *fieldnames* are specified in a single string and are separated by spaces.
+ Any valid Python identifier may be used for a field name.
+
+ Example::
+
+ >>> Point = NamedTuple('Point', 'x y')
+ >>> Point.__doc__ # docstring for the new datatype
+ 'Point(x, y)'
+ >>> p = Point(11, y=22) # instantiate with positional or keyword arguments
+ >>> p[0] + p[1] # works just like the tuple (11, 22)
+ 33
+ >>> x, y = p # unpacks just like a tuple
+ >>> x, y
+ (11, 22)
+ >>> p.x + p.y # fields also accessable by name
+ 33
+ >>> p # readable __repr__ with name=value style
+ Point(x=11, y=22)
+
+ The use cases are the same as those for tuples. The named factories assign
+ meaning to each tuple position and allow for more readable, self-documenting
+ code. Named tuples can also be used to assign field names to tuples returned
+ by the :mod:`csv` or :mod:`sqlite3` modules. For example::
+
+ from itertools import starmap
+ import csv
+ EmployeeRecord = NamedTuple('EmployeeRecord', 'name age title department paygrade')
+ for record in starmap(EmployeeRecord, csv.reader(open("employees.csv", "rb"))):
+ print record
+
+ To cast an individual record stored as :class:`list`, :class:`tuple`, or some
+ other iterable type, use the star-operator to unpack the values::
+
+ >>> Color = NamedTuple('Color', 'name code')
+ >>> m = dict(red=1, green=2, blue=3)
+ >>> print Color(*m.popitem())
+ Color(name='blue', code=3)
+
--- /dev/null
+
+:mod:`ColorPicker` --- Color selection dialog
+=============================================
+
+.. module:: ColorPicker
+ :platform: Mac
+ :synopsis: Interface to the standard color selection dialog.
+.. moduleauthor:: Just van Rossum <just@letterror.com>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+The :mod:`ColorPicker` module provides access to the standard color picker
+dialog.
+
+
+.. function:: GetColor(prompt, rgb)
+
+ Show a standard color selection dialog and allow the user to select a color.
+ The user is given instruction by the *prompt* string, and the default color is
+ set to *rgb*. *rgb* must be a tuple giving the red, green, and blue components
+ of the color. :func:`GetColor` returns a tuple giving the user's selected color
+ and a flag indicating whether they accepted the selection of cancelled.
+
--- /dev/null
+
+:mod:`colorsys` --- Conversions between color systems
+=====================================================
+
+.. module:: colorsys
+ :synopsis: Conversion functions between RGB and other color systems.
+.. sectionauthor:: David Ascher <da@python.net>
+
+
+The :mod:`colorsys` module defines bidirectional conversions of color values
+between colors expressed in the RGB (Red Green Blue) color space used in
+computer monitors and three other coordinate systems: YIQ, HLS (Hue Lightness
+Saturation) and HSV (Hue Saturation Value). Coordinates in all of these color
+spaces are floating point values. In the YIQ space, the Y coordinate is between
+0 and 1, but the I and Q coordinates can be positive or negative. In all other
+spaces, the coordinates are all between 0 and 1.
+
+More information about color spaces can be found at
+http://www.poynton.com/ColorFAQ.html.
+
+The :mod:`colorsys` module defines the following functions:
+
+
+.. function:: rgb_to_yiq(r, g, b)
+
+ Convert the color from RGB coordinates to YIQ coordinates.
+
+
+.. function:: yiq_to_rgb(y, i, q)
+
+ Convert the color from YIQ coordinates to RGB coordinates.
+
+
+.. function:: rgb_to_hls(r, g, b)
+
+ Convert the color from RGB coordinates to HLS coordinates.
+
+
+.. function:: hls_to_rgb(h, l, s)
+
+ Convert the color from HLS coordinates to RGB coordinates.
+
+
+.. function:: rgb_to_hsv(r, g, b)
+
+ Convert the color from RGB coordinates to HSV coordinates.
+
+
+.. function:: hsv_to_rgb(h, s, v)
+
+ Convert the color from HSV coordinates to RGB coordinates.
+
+Example::
+
+ >>> import colorsys
+ >>> colorsys.rgb_to_hsv(.3, .4, .2)
+ (0.25, 0.5, 0.4)
+ >>> colorsys.hsv_to_rgb(0.25, 0.5, 0.4)
+ (0.3, 0.4, 0.2)
+
--- /dev/null
+
+:mod:`commands` --- Utilities for running commands
+==================================================
+
+.. module:: commands
+ :platform: Unix
+ :synopsis: Utility functions for running external commands.
+.. sectionauthor:: Sue Williams <sbw@provis.com>
+
+
+The :mod:`commands` module contains wrapper functions for :func:`os.popen` which
+take a system command as a string and return any output generated by the command
+and, optionally, the exit status.
+
+The :mod:`subprocess` module provides more powerful facilities for spawning new
+processes and retrieving their results. Using the :mod:`subprocess` module is
+preferable to using the :mod:`commands` module.
+
+The :mod:`commands` module defines the following functions:
+
+
+.. function:: getstatusoutput(cmd)
+
+ Execute the string *cmd* in a shell with :func:`os.popen` and return a 2-tuple
+ ``(status, output)``. *cmd* is actually run as ``{ cmd ; } 2>&1``, so that the
+ returned output will contain output or error messages. A trailing newline is
+ stripped from the output. The exit status for the command can be interpreted
+ according to the rules for the C function :cfunc:`wait`.
+
+
+.. function:: getoutput(cmd)
+
+ Like :func:`getstatusoutput`, except the exit status is ignored and the return
+ value is a string containing the command's output.
+
+
+.. function:: getstatus(file)
+
+ Return the output of ``ls -ld file`` as a string. This function uses the
+ :func:`getoutput` function, and properly escapes backslashes and dollar signs in
+ the argument.
+
+ .. deprecated:: 2.6
+ This function is nonobvious and useless, also the name is misleading in the
+ presence of :func:`getstatusoutput`.
+
+Example::
+
+ >>> import commands
+ >>> commands.getstatusoutput('ls /bin/ls')
+ (0, '/bin/ls')
+ >>> commands.getstatusoutput('cat /bin/junk')
+ (256, 'cat: /bin/junk: No such file or directory')
+ >>> commands.getstatusoutput('/bin/junk')
+ (256, 'sh: /bin/junk: not found')
+ >>> commands.getoutput('ls /bin/ls')
+ '/bin/ls'
+ >>> commands.getstatus('/bin/ls')
+ '-rwxr-xr-x 1 root 13352 Oct 14 1994 /bin/ls'
+
+
+.. seealso::
+
+ Module :mod:`subprocess`
+ Module for spawning and managing subprocesses.
+
--- /dev/null
+
+:mod:`compileall` --- Byte-compile Python libraries
+===================================================
+
+.. module:: compileall
+ :synopsis: Tools for byte-compiling all Python source files in a directory tree.
+
+
+This module provides some utility functions to support installing Python
+libraries. These functions compile Python source files in a directory tree,
+allowing users without permission to write to the libraries to take advantage of
+cached byte-code files.
+
+The source file for this module may also be used as a script to compile Python
+sources in directories named on the command line or in ``sys.path``.
+
+
+.. function:: compile_dir(dir[, maxlevels[, ddir[, force[, rx[, quiet]]]]])
+
+ Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
+ files along the way. The *maxlevels* parameter is used to limit the depth of
+ the recursion; it defaults to ``10``. If *ddir* is given, it is used as the
+ base path from which the filenames used in error messages will be generated.
+ If *force* is true, modules are re-compiled even if the timestamps are up to
+ date.
+
+ If *rx* is given, it specifies a regular expression of file names to exclude
+ from the search; that expression is searched for in the full path.
+
+ If *quiet* is true, nothing is printed to the standard output in normal
+ operation.
+
+
+.. function:: compile_path([skip_curdir[, maxlevels[, force]]])
+
+ Byte-compile all the :file:`.py` files found along ``sys.path``. If
+ *skip_curdir* is true (the default), the current directory is not included in
+ the search. The *maxlevels* and *force* parameters default to ``0`` and are
+ passed to the :func:`compile_dir` function.
+
+To force a recompile of all the :file:`.py` files in the :file:`Lib/`
+subdirectory and all its subdirectories::
+
+ import compileall
+
+ compileall.compile_dir('Lib/', force=True)
+
+ # Perform same compilation, excluding files in .svn directories.
+ import re
+ compileall.compile_dir('Lib/', rx=re.compile('/[.]svn'), force=True)
+
+
+.. seealso::
+
+ Module :mod:`py_compile`
+ Byte-compile a single source file.
+
--- /dev/null
+
+.. _compiler:
+
+***********************
+Python compiler package
+***********************
+
+.. sectionauthor:: Jeremy Hylton <jeremy@zope.com>
+
+
+The Python compiler package is a tool for analyzing Python source code and
+generating Python bytecode. The compiler contains libraries to generate an
+abstract syntax tree from Python source code and to generate Python bytecode
+from the tree.
+
+The :mod:`compiler` package is a Python source to bytecode translator written in
+Python. It uses the built-in parser and standard :mod:`parser` module to
+generated a concrete syntax tree. This tree is used to generate an abstract
+syntax tree (AST) and then Python bytecode.
+
+The full functionality of the package duplicates the builtin compiler provided
+with the Python interpreter. It is intended to match its behavior almost
+exactly. Why implement another compiler that does the same thing? The package
+is useful for a variety of purposes. It can be modified more easily than the
+builtin compiler. The AST it generates is useful for analyzing Python source
+code.
+
+This chapter explains how the various components of the :mod:`compiler` package
+work. It blends reference material with a tutorial.
+
+The following modules are part of the :mod:`compiler` package:
+
+.. toctree::
+
+ _ast.rst
+
+
+The basic interface
+===================
+
+.. module:: compiler
+ :synopsis: Python code compiler written in Python.
+
+
+The top-level of the package defines four functions. If you import
+:mod:`compiler`, you will get these functions and a collection of modules
+contained in the package.
+
+
+.. function:: parse(buf)
+
+ Returns an abstract syntax tree for the Python source code in *buf*. The
+ function raises :exc:`SyntaxError` if there is an error in the source code. The
+ return value is a :class:`compiler.ast.Module` instance that contains the tree.
+
+
+.. function:: parseFile(path)
+
+ Return an abstract syntax tree for the Python source code in the file specified
+ by *path*. It is equivalent to ``parse(open(path).read())``.
+
+
+.. function:: walk(ast, visitor[, verbose])
+
+ Do a pre-order walk over the abstract syntax tree *ast*. Call the appropriate
+ method on the *visitor* instance for each node encountered.
+
+
+.. function:: compile(source, filename, mode, flags=None, dont_inherit=None)
+
+ Compile the string *source*, a Python module, statement or expression, into a
+ code object that can be executed by the exec statement or :func:`eval`. This
+ function is a replacement for the built-in :func:`compile` function.
+
+ The *filename* will be used for run-time error messages.
+
+ The *mode* must be 'exec' to compile a module, 'single' to compile a single
+ (interactive) statement, or 'eval' to compile an expression.
+
+ The *flags* and *dont_inherit* arguments affect future-related statements, but
+ are not supported yet.
+
+
+.. function:: compileFile(source)
+
+ Compiles the file *source* and generates a .pyc file.
+
+The :mod:`compiler` package contains the following modules: :mod:`ast`,
+:mod:`consts`, :mod:`future`, :mod:`misc`, :mod:`pyassem`, :mod:`pycodegen`,
+:mod:`symbols`, :mod:`transformer`, and :mod:`visitor`.
+
+
+Limitations
+===========
+
+There are some problems with the error checking of the compiler package. The
+interpreter detects syntax errors in two distinct phases. One set of errors is
+detected by the interpreter's parser, the other set by the compiler. The
+compiler package relies on the interpreter's parser, so it get the first phases
+of error checking for free. It implements the second phase itself, and that
+implementation is incomplete. For example, the compiler package does not raise
+an error if a name appears more than once in an argument list: ``def f(x, x):
+...``
+
+A future version of the compiler should fix these problems.
+
+
+Python Abstract Syntax
+======================
+
+The :mod:`compiler.ast` module defines an abstract syntax for Python. In the
+abstract syntax tree, each node represents a syntactic construct. The root of
+the tree is :class:`Module` object.
+
+The abstract syntax offers a higher level interface to parsed Python source
+code. The :mod:`parser` module and the compiler written in C for the Python
+interpreter use a concrete syntax tree. The concrete syntax is tied closely to
+the grammar description used for the Python parser. Instead of a single node
+for a construct, there are often several levels of nested nodes that are
+introduced by Python's precedence rules.
+
+The abstract syntax tree is created by the :mod:`compiler.transformer` module.
+The transformer relies on the builtin Python parser to generate a concrete
+syntax tree. It generates an abstract syntax tree from the concrete tree.
+
+.. index::
+ single: Stein, Greg
+ single: Tutt, Bill
+
+The :mod:`transformer` module was created by Greg Stein and Bill Tutt for an
+experimental Python-to-C compiler. The current version contains a number of
+modifications and improvements, but the basic form of the abstract syntax and of
+the transformer are due to Stein and Tutt.
+
+
+AST Nodes
+---------
+
+.. module:: compiler.ast
+
+
+The :mod:`compiler.ast` module is generated from a text file that describes each
+node type and its elements. Each node type is represented as a class that
+inherits from the abstract base class :class:`compiler.ast.Node` and defines a
+set of named attributes for child nodes.
+
+
+.. class:: Node()
+
+ The :class:`Node` instances are created automatically by the parser generator.
+ The recommended interface for specific :class:`Node` instances is to use the
+ public attributes to access child nodes. A public attribute may be bound to a
+ single node or to a sequence of nodes, depending on the :class:`Node` type. For
+ example, the :attr:`bases` attribute of the :class:`Class` node, is bound to a
+ list of base class nodes, and the :attr:`doc` attribute is bound to a single
+ node.
+
+ Each :class:`Node` instance has a :attr:`lineno` attribute which may be
+ ``None``. XXX Not sure what the rules are for which nodes will have a useful
+ lineno.
+
+All :class:`Node` objects offer the following methods:
+
+
+.. method:: Node.getChildren()
+
+ Returns a flattened list of the child nodes and objects in the order they occur.
+ Specifically, the order of the nodes is the order in which they appear in the
+ Python grammar. Not all of the children are :class:`Node` instances. The names
+ of functions and classes, for example, are plain strings.
+
+
+.. method:: Node.getChildNodes()
+
+ Returns a flattened list of the child nodes in the order they occur. This
+ method is like :meth:`getChildren`, except that it only returns those children
+ that are :class:`Node` instances.
+
+Two examples illustrate the general structure of :class:`Node` classes. The
+:keyword:`while` statement is defined by the following grammar production::
+
+ while_stmt: "while" expression ":" suite
+ ["else" ":" suite]
+
+The :class:`While` node has three attributes: :attr:`test`, :attr:`body`, and
+:attr:`else_`. (If the natural name for an attribute is also a Python reserved
+word, it can't be used as an attribute name. An underscore is appended to the
+word to make it a legal identifier, hence :attr:`else_` instead of
+:keyword:`else`.)
+
+The :keyword:`if` statement is more complicated because it can include several
+tests. ::
+
+ if_stmt: 'if' test ':' suite ('elif' test ':' suite)* ['else' ':' suite]
+
+The :class:`If` node only defines two attributes: :attr:`tests` and
+:attr:`else_`. The :attr:`tests` attribute is a sequence of test expression,
+consequent body pairs. There is one pair for each :keyword:`if`/:keyword:`elif`
+clause. The first element of the pair is the test expression. The second
+elements is a :class:`Stmt` node that contains the code to execute if the test
+is true.
+
+The :meth:`getChildren` method of :class:`If` returns a flat list of child
+nodes. If there are three :keyword:`if`/:keyword:`elif` clauses and no
+:keyword:`else` clause, then :meth:`getChildren` will return a list of six
+elements: the first test expression, the first :class:`Stmt`, the second text
+expression, etc.
+
+The following table lists each of the :class:`Node` subclasses defined in
+:mod:`compiler.ast` and each of the public attributes available on their
+instances. The values of most of the attributes are themselves :class:`Node`
+instances or sequences of instances. When the value is something other than an
+instance, the type is noted in the comment. The attributes are listed in the
+order in which they are returned by :meth:`getChildren` and
+:meth:`getChildNodes`.
+
++-----------------------+--------------------+---------------------------------+
+| Node type | Attribute | Value |
++=======================+====================+=================================+
+| :class:`Add` | :attr:`left` | left operand |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`right` | right operand |
++-----------------------+--------------------+---------------------------------+
+| :class:`And` | :attr:`nodes` | list of operands |
++-----------------------+--------------------+---------------------------------+
+| :class:`AssAttr` | | *attribute as target of |
+| | | assignment* |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`expr` | expression on the left-hand |
+| | | side of the dot |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`attrname` | the attribute name, a string |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`flags` | XXX |
++-----------------------+--------------------+---------------------------------+
+| :class:`AssList` | :attr:`nodes` | list of list elements being |
+| | | assigned to |
++-----------------------+--------------------+---------------------------------+
+| :class:`AssName` | :attr:`name` | name being assigned to |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`flags` | XXX |
++-----------------------+--------------------+---------------------------------+
+| :class:`AssTuple` | :attr:`nodes` | list of tuple elements being |
+| | | assigned to |
++-----------------------+--------------------+---------------------------------+
+| :class:`Assert` | :attr:`test` | the expression to be tested |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`fail` | the value of the |
+| | | :exc:`AssertionError` |
++-----------------------+--------------------+---------------------------------+
+| :class:`Assign` | :attr:`nodes` | a list of assignment targets, |
+| | | one per equal sign |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`expr` | the value being assigned |
++-----------------------+--------------------+---------------------------------+
+| :class:`AugAssign` | :attr:`node` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`op` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Backquote` | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Bitand` | :attr:`nodes` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Bitor` | :attr:`nodes` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Bitxor` | :attr:`nodes` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Break` | | |
++-----------------------+--------------------+---------------------------------+
+| :class:`CallFunc` | :attr:`node` | expression for the callee |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`args` | a list of arguments |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`star_args` | the extended \*-arg value |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`dstar_args` | the extended \*\*-arg value |
++-----------------------+--------------------+---------------------------------+
+| :class:`Class` | :attr:`name` | the name of the class, a string |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`bases` | a list of base classes |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`doc` | doc string, a string or |
+| | | ``None`` |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`code` | the body of the class statement |
++-----------------------+--------------------+---------------------------------+
+| :class:`Compare` | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`ops` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Const` | :attr:`value` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Continue` | | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Decorators` | :attr:`nodes` | List of function decorator |
+| | | expressions |
++-----------------------+--------------------+---------------------------------+
+| :class:`Dict` | :attr:`items` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Discard` | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Div` | :attr:`left` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`right` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Ellipsis` | | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Expression` | :attr:`node` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Exec` | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`locals` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`globals` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`FloorDiv` | :attr:`left` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`right` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`For` | :attr:`assign` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`list` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`body` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`else_` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`From` | :attr:`modname` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`names` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Function` | :attr:`decorators` | :class:`Decorators` or ``None`` |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`name` | name used in def, a string |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`argnames` | list of argument names, as |
+| | | strings |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`defaults` | list of default values |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`flags` | xxx |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`doc` | doc string, a string or |
+| | | ``None`` |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`code` | the body of the function |
++-----------------------+--------------------+---------------------------------+
+| :class:`GenExpr` | :attr:`code` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`GenExprFor` | :attr:`assign` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`iter` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`ifs` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`GenExprIf` | :attr:`test` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`GenExprInner` | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`quals` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Getattr` | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`attrname` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Global` | :attr:`names` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`If` | :attr:`tests` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`else_` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Import` | :attr:`names` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Invert` | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Keyword` | :attr:`name` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Lambda` | :attr:`argnames` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`defaults` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`flags` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`code` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`LeftShift` | :attr:`left` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`right` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`List` | :attr:`nodes` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`ListComp` | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`quals` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`ListCompFor` | :attr:`assign` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`list` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`ifs` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`ListCompIf` | :attr:`test` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Mod` | :attr:`left` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`right` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Module` | :attr:`doc` | doc string, a string or |
+| | | ``None`` |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`node` | body of the module, a |
+| | | :class:`Stmt` |
++-----------------------+--------------------+---------------------------------+
+| :class:`Mul` | :attr:`left` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`right` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Name` | :attr:`name` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Not` | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Or` | :attr:`nodes` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Pass` | | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Power` | :attr:`left` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`right` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Print` | :attr:`nodes` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`dest` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Printnl` | :attr:`nodes` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`dest` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Raise` | :attr:`expr1` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`expr2` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`expr3` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Return` | :attr:`value` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`RightShift` | :attr:`left` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`right` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Slice` | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`flags` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`lower` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`upper` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Sliceobj` | :attr:`nodes` | list of statements |
++-----------------------+--------------------+---------------------------------+
+| :class:`Stmt` | :attr:`nodes` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Sub` | :attr:`left` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`right` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Subscript` | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`flags` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`subs` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`TryExcept` | :attr:`body` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`handlers` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`else_` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`TryFinally` | :attr:`body` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`final` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Tuple` | :attr:`nodes` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`UnaryAdd` | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`UnarySub` | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`While` | :attr:`test` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`body` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`else_` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`With` | :attr:`expr` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`vars` | |
++-----------------------+--------------------+---------------------------------+
+| | :attr:`body` | |
++-----------------------+--------------------+---------------------------------+
+| :class:`Yield` | :attr:`value` | |
++-----------------------+--------------------+---------------------------------+
+
+
+Assignment nodes
+----------------
+
+There is a collection of nodes used to represent assignments. Each assignment
+statement in the source code becomes a single :class:`Assign` node in the AST.
+The :attr:`nodes` attribute is a list that contains a node for each assignment
+target. This is necessary because assignment can be chained, e.g. ``a = b =
+2``. Each :class:`Node` in the list will be one of the following classes:
+:class:`AssAttr`, :class:`AssList`, :class:`AssName`, or :class:`AssTuple`.
+
+Each target assignment node will describe the kind of object being assigned to:
+:class:`AssName` for a simple name, e.g. ``a = 1``. :class:`AssAttr` for an
+attribute assigned, e.g. ``a.x = 1``. :class:`AssList` and :class:`AssTuple` for
+list and tuple expansion respectively, e.g. ``a, b, c = a_tuple``.
+
+The target assignment nodes also have a :attr:`flags` attribute that indicates
+whether the node is being used for assignment or in a delete statement. The
+:class:`AssName` is also used to represent a delete statement, e.g. :class:`del
+x`.
+
+When an expression contains several attribute references, an assignment or
+delete statement will contain only one :class:`AssAttr` node -- for the final
+attribute reference. The other attribute references will be represented as
+:class:`Getattr` nodes in the :attr:`expr` attribute of the :class:`AssAttr`
+instance.
+
+
+Examples
+--------
+
+This section shows several simple examples of ASTs for Python source code. The
+examples demonstrate how to use the :func:`parse` function, what the repr of an
+AST looks like, and how to access attributes of an AST node.
+
+The first module defines a single function. Assume it is stored in
+:file:`/tmp/doublelib.py`. ::
+
+ """This is an example module.
+
+ This is the docstring.
+ """
+
+ def double(x):
+ "Return twice the argument"
+ return x * 2
+
+In the interactive interpreter session below, I have reformatted the long AST
+reprs for readability. The AST reprs use unqualified class names. If you want
+to create an instance from a repr, you must import the class names from the
+:mod:`compiler.ast` module. ::
+
+ >>> import compiler
+ >>> mod = compiler.parseFile("/tmp/doublelib.py")
+ >>> mod
+ Module('This is an example module.\n\nThis is the docstring.\n',
+ Stmt([Function(None, 'double', ['x'], [], 0,
+ 'Return twice the argument',
+ Stmt([Return(Mul((Name('x'), Const(2))))]))]))
+ >>> from compiler.ast import *
+ >>> Module('This is an example module.\n\nThis is the docstring.\n',
+ ... Stmt([Function(None, 'double', ['x'], [], 0,
+ ... 'Return twice the argument',
+ ... Stmt([Return(Mul((Name('x'), Const(2))))]))]))
+ Module('This is an example module.\n\nThis is the docstring.\n',
+ Stmt([Function(None, 'double', ['x'], [], 0,
+ 'Return twice the argument',
+ Stmt([Return(Mul((Name('x'), Const(2))))]))]))
+ >>> mod.doc
+ 'This is an example module.\n\nThis is the docstring.\n'
+ >>> for node in mod.node.nodes:
+ ... print node
+ ...
+ Function(None, 'double', ['x'], [], 0, 'Return twice the argument',
+ Stmt([Return(Mul((Name('x'), Const(2))))]))
+ >>> func = mod.node.nodes[0]
+ >>> func.code
+ Stmt([Return(Mul((Name('x'), Const(2))))])
+
+
+Using Visitors to Walk ASTs
+===========================
+
+.. module:: compiler.visitor
+
+
+The visitor pattern is ... The :mod:`compiler` package uses a variant on the
+visitor pattern that takes advantage of Python's introspection features to
+eliminate the need for much of the visitor's infrastructure.
+
+The classes being visited do not need to be programmed to accept visitors. The
+visitor need only define visit methods for classes it is specifically interested
+in; a default visit method can handle the rest.
+
+XXX The magic :meth:`visit` method for visitors.
+
+
+.. function:: walk(tree, visitor[, verbose])
+
+
+.. class:: ASTVisitor()
+
+ The :class:`ASTVisitor` is responsible for walking over the tree in the correct
+ order. A walk begins with a call to :meth:`preorder`. For each node, it checks
+ the *visitor* argument to :meth:`preorder` for a method named 'visitNodeType,'
+ where NodeType is the name of the node's class, e.g. for a :class:`While` node a
+ :meth:`visitWhile` would be called. If the method exists, it is called with the
+ node as its first argument.
+
+ The visitor method for a particular node type can control how child nodes are
+ visited during the walk. The :class:`ASTVisitor` modifies the visitor argument
+ by adding a visit method to the visitor; this method can be used to visit a
+ particular child node. If no visitor is found for a particular node type, the
+ :meth:`default` method is called.
+
+:class:`ASTVisitor` objects have the following methods:
+
+XXX describe extra arguments
+
+
+.. method:: ASTVisitor.default(node[, ...])
+
+
+.. method:: ASTVisitor.dispatch(node[, ...])
+
+
+.. method:: ASTVisitor.preorder(tree, visitor)
+
+
+Bytecode Generation
+===================
+
+The code generator is a visitor that emits bytecodes. Each visit method can
+call the :meth:`emit` method to emit a new bytecode. The basic code generator
+is specialized for modules, classes, and functions. An assembler converts that
+emitted instructions to the low-level bytecode format. It handles things like
+generator of constant lists of code objects and calculation of jump offsets.
+
--- /dev/null
+
+:mod:`ConfigParser` --- Configuration file parser
+=================================================
+
+.. module:: ConfigParser
+ :synopsis: Configuration file parser.
+.. moduleauthor:: Ken Manheimer <klm@zope.com>
+.. moduleauthor:: Barry Warsaw <bwarsaw@python.org>
+.. moduleauthor:: Eric S. Raymond <esr@thyrsus.com>
+.. sectionauthor:: Christopher G. Petrilli <petrilli@amber.org>
+
+
+.. index::
+ pair: .ini; file
+ pair: configuration; file
+ single: ini file
+ single: Windows ini file
+
+This module defines the class :class:`ConfigParser`. The :class:`ConfigParser`
+class implements a basic configuration file parser language which provides a
+structure similar to what you would find on Microsoft Windows INI files. You
+can use this to write Python programs which can be customized by end users
+easily.
+
+.. warning::
+
+ This library does *not* interpret or write the value-type prefixes used in the
+ Windows Registry extended version of INI syntax.
+
+The configuration file consists of sections, led by a ``[section]`` header and
+followed by ``name: value`` entries, with continuations in the style of
+:rfc:`822`; ``name=value`` is also accepted. Note that leading whitespace is
+removed from values. The optional values can contain format strings which refer
+to other values in the same section, or values in a special ``DEFAULT`` section.
+Additional defaults can be provided on initialization and retrieval. Lines
+beginning with ``'#'`` or ``';'`` are ignored and may be used to provide
+comments.
+
+For example::
+
+ [My Section]
+ foodir: %(dir)s/whatever
+ dir=frob
+
+would resolve the ``%(dir)s`` to the value of ``dir`` (``frob`` in this case).
+All reference expansions are done on demand.
+
+Default values can be specified by passing them into the :class:`ConfigParser`
+constructor as a dictionary. Additional defaults may be passed into the
+:meth:`get` method which will override all others.
+
+Sections are normally stored in a builtin dictionary. An alternative dictionary
+type can be passed to the :class:`ConfigParser` constructor. For example, if a
+dictionary type is passed that sorts its keys, the sections will be sorted on
+write-back, as will be the keys within each section.
+
+
+.. class:: RawConfigParser([defaults[, dict_type]])
+
+ The basic configuration object. When *defaults* is given, it is initialized
+ into the dictionary of intrinsic defaults. When *dict_type* is given, it will
+ be used to create the dictionary objects for the list of sections, for the
+ options within a section, and for the default values. This class does not
+ support the magical interpolation behavior.
+
+ .. versionadded:: 2.3
+
+ .. versionchanged:: 2.6
+ *dict_type* was added.
+
+
+.. class:: ConfigParser([defaults])
+
+ Derived class of :class:`RawConfigParser` that implements the magical
+ interpolation feature and adds optional arguments to the :meth:`get` and
+ :meth:`items` methods. The values in *defaults* must be appropriate for the
+ ``%()s`` string interpolation. Note that *__name__* is an intrinsic default;
+ its value is the section name, and will override any value provided in
+ *defaults*.
+
+ All option names used in interpolation will be passed through the
+ :meth:`optionxform` method just like any other option name reference. For
+ example, using the default implementation of :meth:`optionxform` (which converts
+ option names to lower case), the values ``foo %(bar)s`` and ``foo %(BAR)s`` are
+ equivalent.
+
+
+.. class:: SafeConfigParser([defaults])
+
+ Derived class of :class:`ConfigParser` that implements a more-sane variant of
+ the magical interpolation feature. This implementation is more predictable as
+ well. New applications should prefer this version if they don't need to be
+ compatible with older versions of Python.
+
+ .. % XXX Need to explain what's safer/more predictable about it.
+
+ .. versionadded:: 2.3
+
+
+.. exception:: NoSectionError
+
+ Exception raised when a specified section is not found.
+
+
+.. exception:: DuplicateSectionError
+
+ Exception raised if :meth:`add_section` is called with the name of a section
+ that is already present.
+
+
+.. exception:: NoOptionError
+
+ Exception raised when a specified option is not found in the specified section.
+
+
+.. exception:: InterpolationError
+
+ Base class for exceptions raised when problems occur performing string
+ interpolation.
+
+
+.. exception:: InterpolationDepthError
+
+ Exception raised when string interpolation cannot be completed because the
+ number of iterations exceeds :const:`MAX_INTERPOLATION_DEPTH`. Subclass of
+ :exc:`InterpolationError`.
+
+
+.. exception:: InterpolationMissingOptionError
+
+ Exception raised when an option referenced from a value does not exist. Subclass
+ of :exc:`InterpolationError`.
+
+ .. versionadded:: 2.3
+
+
+.. exception:: InterpolationSyntaxError
+
+ Exception raised when the source text into which substitutions are made does not
+ conform to the required syntax. Subclass of :exc:`InterpolationError`.
+
+ .. versionadded:: 2.3
+
+
+.. exception:: MissingSectionHeaderError
+
+ Exception raised when attempting to parse a file which has no section headers.
+
+
+.. exception:: ParsingError
+
+ Exception raised when errors occur attempting to parse a file.
+
+
+.. data:: MAX_INTERPOLATION_DEPTH
+
+ The maximum depth for recursive interpolation for :meth:`get` when the *raw*
+ parameter is false. This is relevant only for the :class:`ConfigParser` class.
+
+
+.. seealso::
+
+ Module :mod:`shlex`
+ Support for a creating Unix shell-like mini-languages which can be used as an
+ alternate format for application configuration files.
+
+
+.. _rawconfigparser-objects:
+
+RawConfigParser Objects
+-----------------------
+
+:class:`RawConfigParser` instances have the following methods:
+
+
+.. method:: RawConfigParser.defaults()
+
+ Return a dictionary containing the instance-wide defaults.
+
+
+.. method:: RawConfigParser.sections()
+
+ Return a list of the sections available; ``DEFAULT`` is not included in the
+ list.
+
+
+.. method:: RawConfigParser.add_section(section)
+
+ Add a section named *section* to the instance. If a section by the given name
+ already exists, :exc:`DuplicateSectionError` is raised.
+
+
+.. method:: RawConfigParser.has_section(section)
+
+ Indicates whether the named section is present in the configuration. The
+ ``DEFAULT`` section is not acknowledged.
+
+
+.. method:: RawConfigParser.options(section)
+
+ Returns a list of options available in the specified *section*.
+
+
+.. method:: RawConfigParser.has_option(section, option)
+
+ If the given section exists, and contains the given option, return
+ :const:`True`; otherwise return :const:`False`.
+
+ .. versionadded:: 1.6
+
+
+.. method:: RawConfigParser.read(filenames)
+
+ Attempt to read and parse a list of filenames, returning a list of filenames
+ which were successfully parsed. If *filenames* is a string or Unicode string,
+ it is treated as a single filename. If a file named in *filenames* cannot be
+ opened, that file will be ignored. This is designed so that you can specify a
+ list of potential configuration file locations (for example, the current
+ directory, the user's home directory, and some system-wide directory), and all
+ existing configuration files in the list will be read. If none of the named
+ files exist, the :class:`ConfigParser` instance will contain an empty dataset.
+ An application which requires initial values to be loaded from a file should
+ load the required file or files using :meth:`readfp` before calling :meth:`read`
+ for any optional files::
+
+ import ConfigParser, os
+
+ config = ConfigParser.ConfigParser()
+ config.readfp(open('defaults.cfg'))
+ config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
+
+ .. versionchanged:: 2.4
+ Returns list of successfully parsed filenames.
+
+
+.. method:: RawConfigParser.readfp(fp[, filename])
+
+ Read and parse configuration data from the file or file-like object in *fp*
+ (only the :meth:`readline` method is used). If *filename* is omitted and *fp*
+ has a :attr:`name` attribute, that is used for *filename*; the default is
+ ``<???>``.
+
+
+.. method:: RawConfigParser.get(section, option)
+
+ Get an *option* value for the named *section*.
+
+
+.. method:: RawConfigParser.getint(section, option)
+
+ A convenience method which coerces the *option* in the specified *section* to an
+ integer.
+
+
+.. method:: RawConfigParser.getfloat(section, option)
+
+ A convenience method which coerces the *option* in the specified *section* to a
+ floating point number.
+
+
+.. method:: RawConfigParser.getboolean(section, option)
+
+ A convenience method which coerces the *option* in the specified *section* to a
+ Boolean value. Note that the accepted values for the option are ``"1"``,
+ ``"yes"``, ``"true"``, and ``"on"``, which cause this method to return ``True``,
+ and ``"0"``, ``"no"``, ``"false"``, and ``"off"``, which cause it to return
+ ``False``. These string values are checked in a case-insensitive manner. Any
+ other value will cause it to raise :exc:`ValueError`.
+
+
+.. method:: RawConfigParser.items(section)
+
+ Return a list of ``(name, value)`` pairs for each option in the given *section*.
+
+
+.. method:: RawConfigParser.set(section, option, value)
+
+ If the given section exists, set the given option to the specified value;
+ otherwise raise :exc:`NoSectionError`. While it is possible to use
+ :class:`RawConfigParser` (or :class:`ConfigParser` with *raw* parameters set to
+ true) for *internal* storage of non-string values, full functionality (including
+ interpolation and output to files) can only be achieved using string values.
+
+ .. versionadded:: 1.6
+
+
+.. method:: RawConfigParser.write(fileobject)
+
+ Write a representation of the configuration to the specified file object. This
+ representation can be parsed by a future :meth:`read` call.
+
+ .. versionadded:: 1.6
+
+
+.. method:: RawConfigParser.remove_option(section, option)
+
+ Remove the specified *option* from the specified *section*. If the section does
+ not exist, raise :exc:`NoSectionError`. If the option existed to be removed,
+ return :const:`True`; otherwise return :const:`False`.
+
+ .. versionadded:: 1.6
+
+
+.. method:: RawConfigParser.remove_section(section)
+
+ Remove the specified *section* from the configuration. If the section in fact
+ existed, return ``True``. Otherwise return ``False``.
+
+
+.. method:: RawConfigParser.optionxform(option)
+
+ Transforms the option name *option* as found in an input file or as passed in by
+ client code to the form that should be used in the internal structures. The
+ default implementation returns a lower-case version of *option*; subclasses may
+ override this or client code can set an attribute of this name on instances to
+ affect this behavior. Setting this to :func:`str`, for example, would make
+ option names case sensitive.
+
+
+.. _configparser-objects:
+
+ConfigParser Objects
+--------------------
+
+The :class:`ConfigParser` class extends some methods of the
+:class:`RawConfigParser` interface, adding some optional arguments.
+
+
+.. method:: ConfigParser.get(section, option[, raw[, vars]])
+
+ Get an *option* value for the named *section*. All the ``'%'`` interpolations
+ are expanded in the return values, based on the defaults passed into the
+ constructor, as well as the options *vars* provided, unless the *raw* argument
+ is true.
+
+
+.. method:: ConfigParser.items(section[, raw[, vars]])
+
+ Return a list of ``(name, value)`` pairs for each option in the given *section*.
+ Optional arguments have the same meaning as for the :meth:`get` method.
+
+ .. versionadded:: 2.3
+
+
+.. _safeconfigparser-objects:
+
+SafeConfigParser Objects
+------------------------
+
+The :class:`SafeConfigParser` class implements the same extended interface as
+:class:`ConfigParser`, with the following addition:
+
+
+.. method:: SafeConfigParser.set(section, option, value)
+
+ If the given section exists, set the given option to the specified value;
+ otherwise raise :exc:`NoSectionError`. *value* must be a string (:class:`str`
+ or :class:`unicode`); if not, :exc:`TypeError` is raised.
+
+ .. versionadded:: 2.4
+
--- /dev/null
+
+Built-in Constants
+==================
+
+A small number of constants live in the built-in namespace. They are:
+
+
+.. data:: False
+
+ The false value of the :class:`bool` type.
+
+ .. versionadded:: 2.3
+
+
+.. data:: True
+
+ The true value of the :class:`bool` type.
+
+ .. versionadded:: 2.3
+
+
+.. data:: None
+
+ The sole value of :attr:`types.NoneType`. ``None`` is frequently used to
+ represent the absence of a value, as when default arguments are not passed to a
+ function.
+
+
+.. data:: NotImplemented
+
+ Special value which can be returned by the "rich comparison" special methods
+ (:meth:`__eq__`, :meth:`__lt__`, and friends), to indicate that the comparison
+ is not implemented with respect to the other type.
+
+
+.. data:: Ellipsis
+
+ Special value used in conjunction with extended slicing syntax.
+
+ .. % XXX Someone who understands extended slicing should fill in here.
+
--- /dev/null
+
+:mod:`contextlib` --- Utilities for :keyword:`with`\ -statement contexts.
+=========================================================================
+
+.. module:: contextlib
+ :synopsis: Utilities for with-statement contexts.
+
+
+.. versionadded:: 2.5
+
+This module provides utilities for common tasks involving the :keyword:`with`
+statement. For more information see also :ref:`typecontextmanager` and
+:ref:`context-managers`.
+
+Functions provided:
+
+
+.. function:: contextmanager(func)
+
+ This function is a decorator that can be used to define a factory function for
+ :keyword:`with` statement context managers, without needing to create a class or
+ separate :meth:`__enter__` and :meth:`__exit__` methods.
+
+ A simple example (this is not recommended as a real way of generating HTML!)::
+
+ from __future__ import with_statement
+ from contextlib import contextmanager
+
+ @contextmanager
+ def tag(name):
+ print "<%s>" % name
+ yield
+ print "</%s>" % name
+
+ >>> with tag("h1"):
+ ... print "foo"
+ ...
+ <h1>
+ foo
+ </h1>
+
+ The function being decorated must return a generator-iterator when called. This
+ iterator must yield exactly one value, which will be bound to the targets in the
+ :keyword:`with` statement's :keyword:`as` clause, if any.
+
+ At the point where the generator yields, the block nested in the :keyword:`with`
+ statement is executed. The generator is then resumed after the block is exited.
+ If an unhandled exception occurs in the block, it is reraised inside the
+ generator at the point where the yield occurred. Thus, you can use a
+ :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally` statement to trap
+ the error (if any), or ensure that some cleanup takes place. If an exception is
+ trapped merely in order to log it or to perform some action (rather than to
+ suppress it entirely), the generator must reraise that exception. Otherwise the
+ generator context manager will indicate to the :keyword:`with` statement that
+ the exception has been handled, and execution will resume with the statement
+ immediately following the :keyword:`with` statement.
+
+
+.. function:: nested(mgr1[, mgr2[, ...]])
+
+ Combine multiple context managers into a single nested context manager.
+
+ Code like this::
+
+ from contextlib import nested
+
+ with nested(A, B, C) as (X, Y, Z):
+ do_something()
+
+ is equivalent to this::
+
+ with A as X:
+ with B as Y:
+ with C as Z:
+ do_something()
+
+ Note that if the :meth:`__exit__` method of one of the nested context managers
+ indicates an exception should be suppressed, no exception information will be
+ passed to any remaining outer context managers. Similarly, if the
+ :meth:`__exit__` method of one of the nested managers raises an exception, any
+ previous exception state will be lost; the new exception will be passed to the
+ :meth:`__exit__` methods of any remaining outer context managers. In general,
+ :meth:`__exit__` methods should avoid raising exceptions, and in particular they
+ should not re-raise a passed-in exception.
+
+
+.. function:: closing(thing)
+
+ Return a context manager that closes *thing* upon completion of the block. This
+ is basically equivalent to::
+
+ from contextlib import contextmanager
+
+ @contextmanager
+ def closing(thing):
+ try:
+ yield thing
+ finally:
+ thing.close()
+
+ And lets you write code like this::
+
+ from __future__ import with_statement
+ from contextlib import closing
+ import urllib
+
+ with closing(urllib.urlopen('http://www.python.org')) as page:
+ for line in page:
+ print line
+
+ without needing to explicitly close ``page``. Even if an error occurs,
+ ``page.close()`` will be called when the :keyword:`with` block is exited.
+
+
+.. seealso::
+
+ :pep:`0343` - The "with" statement
+ The specification, background, and examples for the Python :keyword:`with`
+ statement.
+
--- /dev/null
+
+:mod:`Cookie` --- HTTP state management
+=======================================
+
+.. module:: Cookie
+ :synopsis: Support for HTTP state management (cookies).
+.. moduleauthor:: Timothy O'Malley <timo@alum.mit.edu>
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+
+
+The :mod:`Cookie` module defines classes for abstracting the concept of
+cookies, an HTTP state management mechanism. It supports both simple string-only
+cookies, and provides an abstraction for having any serializable data-type as
+cookie value.
+
+The module formerly strictly applied the parsing rules described in the
+:rfc:`2109` and :rfc:`2068` specifications. It has since been discovered that
+MSIE 3.0x doesn't follow the character rules outlined in those specs. As a
+result, the parsing rules used are a bit less strict.
+
+
+.. exception:: CookieError
+
+ Exception failing because of :rfc:`2109` invalidity: incorrect attributes,
+ incorrect :mailheader:`Set-Cookie` header, etc.
+
+
+.. class:: BaseCookie([input])
+
+ This class is a dictionary-like object whose keys are strings and whose values
+ are :class:`Morsel` instances. Note that upon setting a key to a value, the
+ value is first converted to a :class:`Morsel` containing the key and the value.
+
+ If *input* is given, it is passed to the :meth:`load` method.
+
+
+.. class:: SimpleCookie([input])
+
+ This class derives from :class:`BaseCookie` and overrides :meth:`value_decode`
+ and :meth:`value_encode` to be the identity and :func:`str` respectively.
+
+
+.. class:: SerialCookie([input])
+
+ This class derives from :class:`BaseCookie` and overrides :meth:`value_decode`
+ and :meth:`value_encode` to be the :func:`pickle.loads` and
+ :func:`pickle.dumps`.
+
+ .. deprecated:: 2.3
+ Reading pickled values from untrusted cookie data is a huge security hole, as
+ pickle strings can be crafted to cause arbitrary code to execute on your server.
+ It is supported for backwards compatibility only, and may eventually go away.
+
+
+.. class:: SmartCookie([input])
+
+ This class derives from :class:`BaseCookie`. It overrides :meth:`value_decode`
+ to be :func:`pickle.loads` if it is a valid pickle, and otherwise the value
+ itself. It overrides :meth:`value_encode` to be :func:`pickle.dumps` unless it
+ is a string, in which case it returns the value itself.
+
+ .. deprecated:: 2.3
+ The same security warning from :class:`SerialCookie` applies here.
+
+A further security note is warranted. For backwards compatibility, the
+:mod:`Cookie` module exports a class named :class:`Cookie` which is just an
+alias for :class:`SmartCookie`. This is probably a mistake and will likely be
+removed in a future version. You should not use the :class:`Cookie` class in
+your applications, for the same reason why you should not use the
+:class:`SerialCookie` class.
+
+
+.. seealso::
+
+ Module :mod:`cookielib`
+ HTTP cookie handling for web *clients*. The :mod:`cookielib` and :mod:`Cookie`
+ modules do not depend on each other.
+
+ :rfc:`2109` - HTTP State Management Mechanism
+ This is the state management specification implemented by this module.
+
+
+.. _cookie-objects:
+
+Cookie Objects
+--------------
+
+
+.. method:: BaseCookie.value_decode(val)
+
+ Return a decoded value from a string representation. Return value can be any
+ type. This method does nothing in :class:`BaseCookie` --- it exists so it can be
+ overridden.
+
+
+.. method:: BaseCookie.value_encode(val)
+
+ Return an encoded value. *val* can be any type, but return value must be a
+ string. This method does nothing in :class:`BaseCookie` --- it exists so it can
+ be overridden
+
+ In general, it should be the case that :meth:`value_encode` and
+ :meth:`value_decode` are inverses on the range of *value_decode*.
+
+
+.. method:: BaseCookie.output([attrs[, header[, sep]]])
+
+ Return a string representation suitable to be sent as HTTP headers. *attrs* and
+ *header* are sent to each :class:`Morsel`'s :meth:`output` method. *sep* is used
+ to join the headers together, and is by default the combination ``'\r\n'``
+ (CRLF).
+
+ .. versionchanged:: 2.5
+ The default separator has been changed from ``'\n'`` to match the cookie
+ specification.
+
+
+.. method:: BaseCookie.js_output([attrs])
+
+ Return an embeddable JavaScript snippet, which, if run on a browser which
+ supports JavaScript, will act the same as if the HTTP headers was sent.
+
+ The meaning for *attrs* is the same as in :meth:`output`.
+
+
+.. method:: BaseCookie.load(rawdata)
+
+ If *rawdata* is a string, parse it as an ``HTTP_COOKIE`` and add the values
+ found there as :class:`Morsel`\ s. If it is a dictionary, it is equivalent to::
+
+ for k, v in rawdata.items():
+ cookie[k] = v
+
+
+.. _morsel-objects:
+
+Morsel Objects
+--------------
+
+
+.. class:: Morsel()
+
+ Abstract a key/value pair, which has some :rfc:`2109` attributes.
+
+ Morsels are dictionary-like objects, whose set of keys is constant --- the valid
+ :rfc:`2109` attributes, which are
+
+ * ``expires``
+ * ``path``
+ * ``comment``
+ * ``domain``
+ * ``max-age``
+ * ``secure``
+ * ``version``
+
+ The keys are case-insensitive.
+
+
+.. attribute:: Morsel.value
+
+ The value of the cookie.
+
+
+.. attribute:: Morsel.coded_value
+
+ The encoded value of the cookie --- this is what should be sent.
+
+
+.. attribute:: Morsel.key
+
+ The name of the cookie.
+
+
+.. method:: Morsel.set(key, value, coded_value)
+
+ Set the *key*, *value* and *coded_value* members.
+
+
+.. method:: Morsel.isReservedKey(K)
+
+ Whether *K* is a member of the set of keys of a :class:`Morsel`.
+
+
+.. method:: Morsel.output([attrs[, header]])
+
+ Return a string representation of the Morsel, suitable to be sent as an HTTP
+ header. By default, all the attributes are included, unless *attrs* is given, in
+ which case it should be a list of attributes to use. *header* is by default
+ ``"Set-Cookie:"``.
+
+
+.. method:: Morsel.js_output([attrs])
+
+ Return an embeddable JavaScript snippet, which, if run on a browser which
+ supports JavaScript, will act the same as if the HTTP header was sent.
+
+ The meaning for *attrs* is the same as in :meth:`output`.
+
+
+.. method:: Morsel.OutputString([attrs])
+
+ Return a string representing the Morsel, without any surrounding HTTP or
+ JavaScript.
+
+ The meaning for *attrs* is the same as in :meth:`output`.
+
+
+.. _cookie-example:
+
+Example
+-------
+
+The following example demonstrates how to use the :mod:`Cookie` module. ::
+
+ >>> import Cookie
+ >>> C = Cookie.SimpleCookie()
+ >>> C = Cookie.SerialCookie()
+ >>> C = Cookie.SmartCookie()
+ >>> C["fig"] = "newton"
+ >>> C["sugar"] = "wafer"
+ >>> print C # generate HTTP headers
+ Set-Cookie: sugar=wafer
+ Set-Cookie: fig=newton
+ >>> print C.output() # same thing
+ Set-Cookie: sugar=wafer
+ Set-Cookie: fig=newton
+ >>> C = Cookie.SmartCookie()
+ >>> C["rocky"] = "road"
+ >>> C["rocky"]["path"] = "/cookie"
+ >>> print C.output(header="Cookie:")
+ Cookie: rocky=road; Path=/cookie
+ >>> print C.output(attrs=[], header="Cookie:")
+ Cookie: rocky=road
+ >>> C = Cookie.SmartCookie()
+ >>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
+ >>> print C
+ Set-Cookie: vienna=finger
+ Set-Cookie: chips=ahoy
+ >>> C = Cookie.SmartCookie()
+ >>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
+ >>> print C
+ Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
+ >>> C = Cookie.SmartCookie()
+ >>> C["oreo"] = "doublestuff"
+ >>> C["oreo"]["path"] = "/"
+ >>> print C
+ Set-Cookie: oreo=doublestuff; Path=/
+ >>> C = Cookie.SmartCookie()
+ >>> C["twix"] = "none for you"
+ >>> C["twix"].value
+ 'none for you'
+ >>> C = Cookie.SimpleCookie()
+ >>> C["number"] = 7 # equivalent to C["number"] = str(7)
+ >>> C["string"] = "seven"
+ >>> C["number"].value
+ '7'
+ >>> C["string"].value
+ 'seven'
+ >>> print C
+ Set-Cookie: number=7
+ Set-Cookie: string=seven
+ >>> C = Cookie.SerialCookie()
+ >>> C["number"] = 7
+ >>> C["string"] = "seven"
+ >>> C["number"].value
+ 7
+ >>> C["string"].value
+ 'seven'
+ >>> print C
+ Set-Cookie: number="I7\012."
+ Set-Cookie: string="S'seven'\012p1\012."
+ >>> C = Cookie.SmartCookie()
+ >>> C["number"] = 7
+ >>> C["string"] = "seven"
+ >>> C["number"].value
+ 7
+ >>> C["string"].value
+ 'seven'
+ >>> print C
+ Set-Cookie: number="I7\012."
+ Set-Cookie: string=seven
+
--- /dev/null
+
+:mod:`cookielib` --- Cookie handling for HTTP clients
+=====================================================
+
+.. module:: cookielib
+ :synopsis: Classes for automatic handling of HTTP cookies.
+.. moduleauthor:: John J. Lee <jjl@pobox.com>
+.. sectionauthor:: John J. Lee <jjl@pobox.com>
+
+
+.. versionadded:: 2.4
+
+
+
+The :mod:`cookielib` module defines classes for automatic handling of HTTP
+cookies. It is useful for accessing web sites that require small pieces of data
+-- :dfn:`cookies` -- to be set on the client machine by an HTTP response from a
+web server, and then returned to the server in later HTTP requests.
+
+Both the regular Netscape cookie protocol and the protocol defined by
+:rfc:`2965` are handled. RFC 2965 handling is switched off by default.
+:rfc:`2109` cookies are parsed as Netscape cookies and subsequently treated
+either as Netscape or RFC 2965 cookies according to the 'policy' in effect.
+Note that the great majority of cookies on the Internet are Netscape cookies.
+:mod:`cookielib` attempts to follow the de-facto Netscape cookie protocol (which
+differs substantially from that set out in the original Netscape specification),
+including taking note of the ``max-age`` and ``port`` cookie-attributes
+introduced with RFC 2965.
+
+.. note::
+
+ The various named parameters found in :mailheader:`Set-Cookie` and
+ :mailheader:`Set-Cookie2` headers (eg. ``domain`` and ``expires``) are
+ conventionally referred to as :dfn:`attributes`. To distinguish them from
+ Python attributes, the documentation for this module uses the term
+ :dfn:`cookie-attribute` instead.
+
+
+The module defines the following exception:
+
+
+.. exception:: LoadError
+
+ Instances of :class:`FileCookieJar` raise this exception on failure to load
+ cookies from a file.
+
+ .. note::
+
+ For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`),
+ :exc:`LoadError` is a subclass of :exc:`IOError`.
+
+
+The following classes are provided:
+
+
+.. class:: CookieJar(policy=None)
+
+ *policy* is an object implementing the :class:`CookiePolicy` interface.
+
+ The :class:`CookieJar` class stores HTTP cookies. It extracts cookies from HTTP
+ requests, and returns them in HTTP responses. :class:`CookieJar` instances
+ automatically expire contained cookies when necessary. Subclasses are also
+ responsible for storing and retrieving cookies from a file or database.
+
+
+.. class:: FileCookieJar(filename, delayload=None, policy=None)
+
+ *policy* is an object implementing the :class:`CookiePolicy` interface. For the
+ other arguments, see the documentation for the corresponding attributes.
+
+ A :class:`CookieJar` which can load cookies from, and perhaps save cookies to, a
+ file on disk. Cookies are **NOT** loaded from the named file until either the
+ :meth:`load` or :meth:`revert` method is called. Subclasses of this class are
+ documented in section :ref:`file-cookie-jar-classes`.
+
+
+.. class:: CookiePolicy()
+
+ This class is responsible for deciding whether each cookie should be accepted
+ from / returned to the server.
+
+
+.. class:: DefaultCookiePolicy( blocked_domains=None, allowed_domains=None, netscape=True, rfc2965=False, rfc2109_as_netscape=None, hide_cookie2=False, strict_domain=False, strict_rfc2965_unverifiable=True, strict_ns_unverifiable=False, strict_ns_domain=DefaultCookiePolicy.DomainLiberal, strict_ns_set_initial_dollar=False, strict_ns_set_path=False )
+
+ Constructor arguments should be passed as keyword arguments only.
+ *blocked_domains* is a sequence of domain names that we never accept cookies
+ from, nor return cookies to. *allowed_domains* if not :const:`None`, this is a
+ sequence of the only domains for which we accept and return cookies. For all
+ other arguments, see the documentation for :class:`CookiePolicy` and
+ :class:`DefaultCookiePolicy` objects.
+
+ :class:`DefaultCookiePolicy` implements the standard accept / reject rules for
+ Netscape and RFC 2965 cookies. By default, RFC 2109 cookies (ie. cookies
+ received in a :mailheader:`Set-Cookie` header with a version cookie-attribute of
+ 1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling
+ is turned off or :attr:`rfc2109_as_netscape` is True, RFC 2109 cookies are
+ 'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by
+ setting the :attr:`version` attribute of the :class:`Cookie` instance to 0.
+ :class:`DefaultCookiePolicy` also provides some parameters to allow some
+ fine-tuning of policy.
+
+
+.. class:: Cookie()
+
+ This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is not
+ expected that users of :mod:`cookielib` construct their own :class:`Cookie`
+ instances. Instead, if necessary, call :meth:`make_cookies` on a
+ :class:`CookieJar` instance.
+
+
+.. seealso::
+
+ Module :mod:`urllib2`
+ URL opening with automatic cookie handling.
+
+ Module :mod:`Cookie`
+ HTTP cookie classes, principally useful for server-side code. The
+ :mod:`cookielib` and :mod:`Cookie` modules do not depend on each other.
+
+ http://wwwsearch.sf.net/ClientCookie/
+ Extensions to this module, including a class for reading Microsoft Internet
+ Explorer cookies on Windows.
+
+ http://www.netscape.com/newsref/std/cookie_spec.html
+ The specification of the original Netscape cookie protocol. Though this is
+ still the dominant protocol, the 'Netscape cookie protocol' implemented by all
+ the major browsers (and :mod:`cookielib`) only bears a passing resemblance to
+ the one sketched out in ``cookie_spec.html``.
+
+ :rfc:`2109` - HTTP State Management Mechanism
+ Obsoleted by RFC 2965. Uses :mailheader:`Set-Cookie` with version=1.
+
+ :rfc:`2965` - HTTP State Management Mechanism
+ The Netscape protocol with the bugs fixed. Uses :mailheader:`Set-Cookie2` in
+ place of :mailheader:`Set-Cookie`. Not widely used.
+
+ http://kristol.org/cookie/errata.html
+ Unfinished errata to RFC 2965.
+
+ :rfc:`2964` - Use of HTTP State Management
+
+.. _cookie-jar-objects:
+
+CookieJar and FileCookieJar Objects
+-----------------------------------
+
+:class:`CookieJar` objects support the iterator protocol for iterating over
+contained :class:`Cookie` objects.
+
+:class:`CookieJar` has the following methods:
+
+
+.. method:: CookieJar.add_cookie_header(request)
+
+ Add correct :mailheader:`Cookie` header to *request*.
+
+ If policy allows (ie. the :attr:`rfc2965` and :attr:`hide_cookie2` attributes of
+ the :class:`CookieJar`'s :class:`CookiePolicy` instance are true and false
+ respectively), the :mailheader:`Cookie2` header is also added when appropriate.
+
+ The *request* object (usually a :class:`urllib2.Request` instance) must support
+ the methods :meth:`get_full_url`, :meth:`get_host`, :meth:`get_type`,
+ :meth:`unverifiable`, :meth:`get_origin_req_host`, :meth:`has_header`,
+ :meth:`get_header`, :meth:`header_items`, and :meth:`add_unredirected_header`,as
+ documented by :mod:`urllib2`.
+
+
+.. method:: CookieJar.extract_cookies(response, request)
+
+ Extract cookies from HTTP *response* and store them in the :class:`CookieJar`,
+ where allowed by policy.
+
+ The :class:`CookieJar` will look for allowable :mailheader:`Set-Cookie` and
+ :mailheader:`Set-Cookie2` headers in the *response* argument, and store cookies
+ as appropriate (subject to the :meth:`CookiePolicy.set_ok` method's approval).
+
+ The *response* object (usually the result of a call to :meth:`urllib2.urlopen`,
+ or similar) should support an :meth:`info` method, which returns an object with
+ a :meth:`getallmatchingheaders` method (usually a :class:`mimetools.Message`
+ instance).
+
+ The *request* object (usually a :class:`urllib2.Request` instance) must support
+ the methods :meth:`get_full_url`, :meth:`get_host`, :meth:`unverifiable`, and
+ :meth:`get_origin_req_host`, as documented by :mod:`urllib2`. The request is
+ used to set default values for cookie-attributes as well as for checking that
+ the cookie is allowed to be set.
+
+
+.. method:: CookieJar.set_policy(policy)
+
+ Set the :class:`CookiePolicy` instance to be used.
+
+
+.. method:: CookieJar.make_cookies(response, request)
+
+ Return sequence of :class:`Cookie` objects extracted from *response* object.
+
+ See the documentation for :meth:`extract_cookies` for the interfaces required of
+ the *response* and *request* arguments.
+
+
+.. method:: CookieJar.set_cookie_if_ok(cookie, request)
+
+ Set a :class:`Cookie` if policy says it's OK to do so.
+
+
+.. method:: CookieJar.set_cookie(cookie)
+
+ Set a :class:`Cookie`, without checking with policy to see whether or not it
+ should be set.
+
+
+.. method:: CookieJar.clear([domain[, path[, name]]])
+
+ Clear some cookies.
+
+ If invoked without arguments, clear all cookies. If given a single argument,
+ only cookies belonging to that *domain* will be removed. If given two arguments,
+ cookies belonging to the specified *domain* and URL *path* are removed. If
+ given three arguments, then the cookie with the specified *domain*, *path* and
+ *name* is removed.
+
+ Raises :exc:`KeyError` if no matching cookie exists.
+
+
+.. method:: CookieJar.clear_session_cookies()
+
+ Discard all session cookies.
+
+ Discards all contained cookies that have a true :attr:`discard` attribute
+ (usually because they had either no ``max-age`` or ``expires`` cookie-attribute,
+ or an explicit ``discard`` cookie-attribute). For interactive browsers, the end
+ of a session usually corresponds to closing the browser window.
+
+ Note that the :meth:`save` method won't save session cookies anyway, unless you
+ ask otherwise by passing a true *ignore_discard* argument.
+
+:class:`FileCookieJar` implements the following additional methods:
+
+
+.. method:: FileCookieJar.save(filename=None, ignore_discard=False, ignore_expires=False)
+
+ Save cookies to a file.
+
+ This base class raises :exc:`NotImplementedError`. Subclasses may leave this
+ method unimplemented.
+
+ *filename* is the name of file in which to save cookies. If *filename* is not
+ specified, :attr:`self.filename` is used (whose default is the value passed to
+ the constructor, if any); if :attr:`self.filename` is :const:`None`,
+ :exc:`ValueError` is raised.
+
+ *ignore_discard*: save even cookies set to be discarded. *ignore_expires*: save
+ even cookies that have expired
+
+ The file is overwritten if it already exists, thus wiping all the cookies it
+ contains. Saved cookies can be restored later using the :meth:`load` or
+ :meth:`revert` methods.
+
+
+.. method:: FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False)
+
+ Load cookies from a file.
+
+ Old cookies are kept unless overwritten by newly loaded ones.
+
+ Arguments are as for :meth:`save`.
+
+ The named file must be in the format understood by the class, or
+ :exc:`LoadError` will be raised. Also, :exc:`IOError` may be raised, for
+ example if the file does not exist.
+
+ .. note::
+
+ For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`),
+ :exc:`LoadError` is a subclass of :exc:`IOError`.
+
+
+.. method:: FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)
+
+ Clear all cookies and reload cookies from a saved file.
+
+ :meth:`revert` can raise the same exceptions as :meth:`load`. If there is a
+ failure, the object's state will not be altered.
+
+:class:`FileCookieJar` instances have the following public attributes:
+
+
+.. attribute:: FileCookieJar.filename
+
+ Filename of default file in which to keep cookies. This attribute may be
+ assigned to.
+
+
+.. attribute:: FileCookieJar.delayload
+
+ If true, load cookies lazily from disk. This attribute should not be assigned
+ to. This is only a hint, since this only affects performance, not behaviour
+ (unless the cookies on disk are changing). A :class:`CookieJar` object may
+ ignore it. None of the :class:`FileCookieJar` classes included in the standard
+ library lazily loads cookies.
+
+
+.. _file-cookie-jar-classes:
+
+FileCookieJar subclasses and co-operation with web browsers
+-----------------------------------------------------------
+
+The following :class:`CookieJar` subclasses are provided for reading and writing
+. Further :class:`CookieJar` subclasses, including one that reads Microsoft
+Internet Explorer cookies, are available at
+http://wwwsearch.sf.net/ClientCookie/.
+
+
+.. class:: MozillaCookieJar(filename, delayload=None, policy=None)
+
+ A :class:`FileCookieJar` that can load from and save cookies to disk in the
+ Mozilla ``cookies.txt`` file format (which is also used by the Lynx and Netscape
+ browsers).
+
+ .. note::
+
+ This loses information about RFC 2965 cookies, and also about newer or
+ non-standard cookie-attributes such as ``port``.
+
+ .. warning::
+
+ Back up your cookies before saving if you have cookies whose loss / corruption
+ would be inconvenient (there are some subtleties which may lead to slight
+ changes in the file over a load / save round-trip).
+
+ Also note that cookies saved while Mozilla is running will get clobbered by
+ Mozilla.
+
+
+.. class:: LWPCookieJar(filename, delayload=None, policy=None)
+
+ A :class:`FileCookieJar` that can load from and save cookies to disk in format
+ compatible with the libwww-perl library's ``Set-Cookie3`` file format. This is
+ convenient if you want to store cookies in a human-readable file.
+
+
+.. _cookie-policy-objects:
+
+CookiePolicy Objects
+--------------------
+
+Objects implementing the :class:`CookiePolicy` interface have the following
+methods:
+
+
+.. method:: CookiePolicy.set_ok(cookie, request)
+
+ Return boolean value indicating whether cookie should be accepted from server.
+
+ *cookie* is a :class:`cookielib.Cookie` instance. *request* is an object
+ implementing the interface defined by the documentation for
+ :meth:`CookieJar.extract_cookies`.
+
+
+.. method:: CookiePolicy.return_ok(cookie, request)
+
+ Return boolean value indicating whether cookie should be returned to server.
+
+ *cookie* is a :class:`cookielib.Cookie` instance. *request* is an object
+ implementing the interface defined by the documentation for
+ :meth:`CookieJar.add_cookie_header`.
+
+
+.. method:: CookiePolicy.domain_return_ok(domain, request)
+
+ Return false if cookies should not be returned, given cookie domain.
+
+ This method is an optimization. It removes the need for checking every cookie
+ with a particular domain (which might involve reading many files). Returning
+ true from :meth:`domain_return_ok` and :meth:`path_return_ok` leaves all the
+ work to :meth:`return_ok`.
+
+ If :meth:`domain_return_ok` returns true for the cookie domain,
+ :meth:`path_return_ok` is called for the cookie path. Otherwise,
+ :meth:`path_return_ok` and :meth:`return_ok` are never called for that cookie
+ domain. If :meth:`path_return_ok` returns true, :meth:`return_ok` is called
+ with the :class:`Cookie` object itself for a full check. Otherwise,
+ :meth:`return_ok` is never called for that cookie path.
+
+ Note that :meth:`domain_return_ok` is called for every *cookie* domain, not just
+ for the *request* domain. For example, the function might be called with both
+ ``".example.com"`` and ``"www.example.com"`` if the request domain is
+ ``"www.example.com"``. The same goes for :meth:`path_return_ok`.
+
+ The *request* argument is as documented for :meth:`return_ok`.
+
+
+.. method:: CookiePolicy.path_return_ok(path, request)
+
+ Return false if cookies should not be returned, given cookie path.
+
+ See the documentation for :meth:`domain_return_ok`.
+
+In addition to implementing the methods above, implementations of the
+:class:`CookiePolicy` interface must also supply the following attributes,
+indicating which protocols should be used, and how. All of these attributes may
+be assigned to.
+
+
+.. attribute:: CookiePolicy.netscape
+
+ Implement Netscape protocol.
+
+
+.. attribute:: CookiePolicy.rfc2965
+
+ Implement RFC 2965 protocol.
+
+
+.. attribute:: CookiePolicy.hide_cookie2
+
+ Don't add :mailheader:`Cookie2` header to requests (the presence of this header
+ indicates to the server that we understand RFC 2965 cookies).
+
+The most useful way to define a :class:`CookiePolicy` class is by subclassing
+from :class:`DefaultCookiePolicy` and overriding some or all of the methods
+above. :class:`CookiePolicy` itself may be used as a 'null policy' to allow
+setting and receiving any and all cookies (this is unlikely to be useful).
+
+
+.. _default-cookie-policy-objects:
+
+DefaultCookiePolicy Objects
+---------------------------
+
+Implements the standard rules for accepting and returning cookies.
+
+Both RFC 2965 and Netscape cookies are covered. RFC 2965 handling is switched
+off by default.
+
+The easiest way to provide your own policy is to override this class and call
+its methods in your overridden implementations before adding your own additional
+checks::
+
+ import cookielib
+ class MyCookiePolicy(cookielib.DefaultCookiePolicy):
+ def set_ok(self, cookie, request):
+ if not cookielib.DefaultCookiePolicy.set_ok(self, cookie, request):
+ return False
+ if i_dont_want_to_store_this_cookie(cookie):
+ return False
+ return True
+
+In addition to the features required to implement the :class:`CookiePolicy`
+interface, this class allows you to block and allow domains from setting and
+receiving cookies. There are also some strictness switches that allow you to
+tighten up the rather loose Netscape protocol rules a little bit (at the cost of
+blocking some benign cookies).
+
+A domain blacklist and whitelist is provided (both off by default). Only domains
+not in the blacklist and present in the whitelist (if the whitelist is active)
+participate in cookie setting and returning. Use the *blocked_domains*
+constructor argument, and :meth:`blocked_domains` and
+:meth:`set_blocked_domains` methods (and the corresponding argument and methods
+for *allowed_domains*). If you set a whitelist, you can turn it off again by
+setting it to :const:`None`.
+
+Domains in block or allow lists that do not start with a dot must equal the
+cookie domain to be matched. For example, ``"example.com"`` matches a blacklist
+entry of ``"example.com"``, but ``"www.example.com"`` does not. Domains that do
+start with a dot are matched by more specific domains too. For example, both
+``"www.example.com"`` and ``"www.coyote.example.com"`` match ``".example.com"``
+(but ``"example.com"`` itself does not). IP addresses are an exception, and
+must match exactly. For example, if blocked_domains contains ``"192.168.1.2"``
+and ``".168.1.2"``, 192.168.1.2 is blocked, but 193.168.1.2 is not.
+
+:class:`DefaultCookiePolicy` implements the following additional methods:
+
+
+.. method:: DefaultCookiePolicy.blocked_domains()
+
+ Return the sequence of blocked domains (as a tuple).
+
+
+.. method:: DefaultCookiePolicy.set_blocked_domains(blocked_domains)
+
+ Set the sequence of blocked domains.
+
+
+.. method:: DefaultCookiePolicy.is_blocked(domain)
+
+ Return whether *domain* is on the blacklist for setting or receiving cookies.
+
+
+.. method:: DefaultCookiePolicy.allowed_domains()
+
+ Return :const:`None`, or the sequence of allowed domains (as a tuple).
+
+
+.. method:: DefaultCookiePolicy.set_allowed_domains(allowed_domains)
+
+ Set the sequence of allowed domains, or :const:`None`.
+
+
+.. method:: DefaultCookiePolicy.is_not_allowed(domain)
+
+ Return whether *domain* is not on the whitelist for setting or receiving
+ cookies.
+
+:class:`DefaultCookiePolicy` instances have the following attributes, which are
+all initialised from the constructor arguments of the same name, and which may
+all be assigned to.
+
+
+.. attribute:: DefaultCookiePolicy.rfc2109_as_netscape
+
+ If true, request that the :class:`CookieJar` instance downgrade RFC 2109 cookies
+ (ie. cookies received in a :mailheader:`Set-Cookie` header with a version
+ cookie-attribute of 1) to Netscape cookies by setting the version attribute of
+ the :class:`Cookie` instance to 0. The default value is :const:`None`, in which
+ case RFC 2109 cookies are downgraded if and only if RFC 2965 handling is turned
+ off. Therefore, RFC 2109 cookies are downgraded by default.
+
+ .. versionadded:: 2.5
+
+General strictness switches:
+
+
+.. attribute:: DefaultCookiePolicy.strict_domain
+
+ Don't allow sites to set two-component domains with country-code top-level
+ domains like ``.co.uk``, ``.gov.uk``, ``.co.nz``.etc. This is far from perfect
+ and isn't guaranteed to work!
+
+RFC 2965 protocol strictness switches:
+
+
+.. attribute:: DefaultCookiePolicy.strict_rfc2965_unverifiable
+
+ Follow RFC 2965 rules on unverifiable transactions (usually, an unverifiable
+ transaction is one resulting from a redirect or a request for an image hosted on
+ another site). If this is false, cookies are *never* blocked on the basis of
+ verifiability
+
+Netscape protocol strictness switches:
+
+
+.. attribute:: DefaultCookiePolicy.strict_ns_unverifiable
+
+ apply RFC 2965 rules on unverifiable transactions even to Netscape cookies
+
+
+.. attribute:: DefaultCookiePolicy.strict_ns_domain
+
+ Flags indicating how strict to be with domain-matching rules for Netscape
+ cookies. See below for acceptable values.
+
+
+.. attribute:: DefaultCookiePolicy.strict_ns_set_initial_dollar
+
+ Ignore cookies in Set-Cookie: headers that have names starting with ``'$'``.
+
+
+.. attribute:: DefaultCookiePolicy.strict_ns_set_path
+
+ Don't allow setting cookies whose path doesn't path-match request URI.
+
+:attr:`strict_ns_domain` is a collection of flags. Its value is constructed by
+or-ing together (for example, ``DomainStrictNoDots|DomainStrictNonDomain`` means
+both flags are set).
+
+
+.. attribute:: DefaultCookiePolicy.DomainStrictNoDots
+
+ When setting cookies, the 'host prefix' must not contain a dot (eg.
+ ``www.foo.bar.com`` can't set a cookie for ``.bar.com``, because ``www.foo``
+ contains a dot).
+
+
+.. attribute:: DefaultCookiePolicy.DomainStrictNonDomain
+
+ Cookies that did not explicitly specify a ``domain`` cookie-attribute can only
+ be returned to a domain equal to the domain that set the cookie (eg.
+ ``spam.example.com`` won't be returned cookies from ``example.com`` that had no
+ ``domain`` cookie-attribute).
+
+
+.. attribute:: DefaultCookiePolicy.DomainRFC2965Match
+
+ When setting cookies, require a full RFC 2965 domain-match.
+
+The following attributes are provided for convenience, and are the most useful
+combinations of the above flags:
+
+
+.. attribute:: DefaultCookiePolicy.DomainLiberal
+
+ Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched
+ off).
+
+
+.. attribute:: DefaultCookiePolicy.DomainStrict
+
+ Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``.
+
+
+.. _cookielib-cookie-objects:
+
+Cookie Objects
+--------------
+
+:class:`Cookie` instances have Python attributes roughly corresponding to the
+standard cookie-attributes specified in the various cookie standards. The
+correspondence is not one-to-one, because there are complicated rules for
+assigning default values, because the ``max-age`` and ``expires``
+cookie-attributes contain equivalent information, and because RFC 2109 cookies
+may be 'downgraded' by :mod:`cookielib` from version 1 to version 0 (Netscape)
+cookies.
+
+Assignment to these attributes should not be necessary other than in rare
+circumstances in a :class:`CookiePolicy` method. The class does not enforce
+internal consistency, so you should know what you're doing if you do that.
+
+
+.. attribute:: Cookie.version
+
+ Integer or :const:`None`. Netscape cookies have :attr:`version` 0. RFC 2965 and
+ RFC 2109 cookies have a ``version`` cookie-attribute of 1. However, note that
+ :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which
+ case :attr:`version` is 0.
+
+
+.. attribute:: Cookie.name
+
+ Cookie name (a string).
+
+
+.. attribute:: Cookie.value
+
+ Cookie value (a string), or :const:`None`.
+
+
+.. attribute:: Cookie.port
+
+ String representing a port or a set of ports (eg. '80', or '80,8080'), or
+ :const:`None`.
+
+
+.. attribute:: Cookie.path
+
+ Cookie path (a string, eg. ``'/acme/rocket_launchers'``).
+
+
+.. attribute:: Cookie.secure
+
+ True if cookie should only be returned over a secure connection.
+
+
+.. attribute:: Cookie.expires
+
+ Integer expiry date in seconds since epoch, or :const:`None`. See also the
+ :meth:`is_expired` method.
+
+
+.. attribute:: Cookie.discard
+
+ True if this is a session cookie.
+
+
+.. attribute:: Cookie.comment
+
+ String comment from the server explaining the function of this cookie, or
+ :const:`None`.
+
+
+.. attribute:: Cookie.comment_url
+
+ URL linking to a comment from the server explaining the function of this cookie,
+ or :const:`None`.
+
+
+.. attribute:: Cookie.rfc2109
+
+ True if this cookie was received as an RFC 2109 cookie (ie. the cookie
+ arrived in a :mailheader:`Set-Cookie` header, and the value of the Version
+ cookie-attribute in that header was 1). This attribute is provided because
+ :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in
+ which case :attr:`version` is 0.
+
+ .. versionadded:: 2.5
+
+
+.. attribute:: Cookie.port_specified
+
+ True if a port or set of ports was explicitly specified by the server (in the
+ :mailheader:`Set-Cookie` / :mailheader:`Set-Cookie2` header).
+
+
+.. attribute:: Cookie.domain_specified
+
+ True if a domain was explicitly specified by the server.
+
+
+.. attribute:: Cookie.domain_initial_dot
+
+ True if the domain explicitly specified by the server began with a dot
+ (``'.'``).
+
+Cookies may have additional non-standard cookie-attributes. These may be
+accessed using the following methods:
+
+
+.. method:: Cookie.has_nonstandard_attr(name)
+
+ Return true if cookie has the named cookie-attribute.
+
+
+.. method:: Cookie.get_nonstandard_attr(name, default=None)
+
+ If cookie has the named cookie-attribute, return its value. Otherwise, return
+ *default*.
+
+
+.. method:: Cookie.set_nonstandard_attr(name, value)
+
+ Set the value of the named cookie-attribute.
+
+The :class:`Cookie` class also defines the following method:
+
+
+.. method:: Cookie.is_expired([now=:const:`None`])
+
+ True if cookie has passed the time at which the server requested it should
+ expire. If *now* is given (in seconds since the epoch), return whether the
+ cookie has expired at the specified time.
+
+
+.. _cookielib-examples:
+
+Examples
+--------
+
+The first example shows the most common usage of :mod:`cookielib`::
+
+ import cookielib, urllib2
+ cj = cookielib.CookieJar()
+ opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
+ r = opener.open("http://example.com/")
+
+This example illustrates how to open a URL using your Netscape, Mozilla, or Lynx
+cookies (assumes Unix/Netscape convention for location of the cookies file)::
+
+ import os, cookielib, urllib2
+ cj = cookielib.MozillaCookieJar()
+ cj.load(os.path.join(os.environ["HOME"], ".netscape/cookies.txt"))
+ opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
+ r = opener.open("http://example.com/")
+
+The next example illustrates the use of :class:`DefaultCookiePolicy`. Turn on
+RFC 2965 cookies, be more strict about domains when setting and returning
+Netscape cookies, and block some domains from setting cookies or having them
+returned::
+
+ import urllib2
+ from cookielib import CookieJar, DefaultCookiePolicy
+ policy = DefaultCookiePolicy(
+ rfc2965=True, strict_ns_domain=Policy.DomainStrict,
+ blocked_domains=["ads.net", ".ads.net"])
+ cj = CookieJar(policy)
+ opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
+ r = opener.open("http://example.com/")
+
--- /dev/null
+
+:mod:`copy` --- Shallow and deep copy operations
+================================================
+
+.. module:: copy
+ :synopsis: Shallow and deep copy operations.
+
+
+.. index::
+ single: copy() (in copy)
+ single: deepcopy() (in copy)
+
+This module provides generic (shallow and deep) copying operations.
+
+Interface summary::
+
+ import copy
+
+ x = copy.copy(y) # make a shallow copy of y
+ x = copy.deepcopy(y) # make a deep copy of y
+
+For module specific errors, :exc:`copy.error` is raised.
+
+.. %
+
+The difference between shallow and deep copying is only relevant for compound
+objects (objects that contain other objects, like lists or class instances):
+
+* A *shallow copy* constructs a new compound object and then (to the extent
+ possible) inserts *references* into it to the objects found in the original.
+
+* A *deep copy* constructs a new compound object and then, recursively, inserts
+ *copies* into it of the objects found in the original.
+
+Two problems often exist with deep copy operations that don't exist with shallow
+copy operations:
+
+* Recursive objects (compound objects that, directly or indirectly, contain a
+ reference to themselves) may cause a recursive loop.
+
+* Because deep copy copies *everything* it may copy too much, e.g.,
+ administrative data structures that should be shared even between copies.
+
+The :func:`deepcopy` function avoids these problems by:
+
+* keeping a "memo" dictionary of objects already copied during the current
+ copying pass; and
+
+* letting user-defined classes override the copying operation or the set of
+ components copied.
+
+This module does not copy types like module, method, stack trace, stack frame,
+file, socket, window, array, or any similar types. It does "copy" functions and
+classes (shallow and deeply), by returning the original object unchanged; this
+is compatible with the way these are treated by the :mod:`pickle` module.
+
+.. versionchanged:: 2.5
+ Added copying functions.
+
+.. index:: module: pickle
+
+Classes can use the same interfaces to control copying that they use to control
+pickling. See the description of module :mod:`pickle` for information on these
+methods. The :mod:`copy` module does not use the :mod:`copy_reg` registration
+module.
+
+.. index::
+ single: __copy__() (copy protocol)
+ single: __deepcopy__() (copy protocol)
+
+In order for a class to define its own copy implementation, it can define
+special methods :meth:`__copy__` and :meth:`__deepcopy__`. The former is called
+to implement the shallow copy operation; no additional arguments are passed.
+The latter is called to implement the deep copy operation; it is passed one
+argument, the memo dictionary. If the :meth:`__deepcopy__` implementation needs
+to make a deep copy of a component, it should call the :func:`deepcopy` function
+with the component as first argument and the memo dictionary as second argument.
+
+
+.. seealso::
+
+ Module :mod:`pickle`
+ Discussion of the special methods used to support object state retrieval and
+ restoration.
+
--- /dev/null
+
+:mod:`copy_reg` --- Register :mod:`pickle` support functions
+============================================================
+
+.. module:: copy_reg
+ :synopsis: Register pickle support functions.
+
+
+.. index::
+ module: pickle
+ module: cPickle
+ module: copy
+
+The :mod:`copy_reg` module provides support for the :mod:`pickle` and
+:mod:`cPickle` modules. The :mod:`copy` module is likely to use this in the
+future as well. It provides configuration information about object constructors
+which are not classes. Such constructors may be factory functions or class
+instances.
+
+
+.. function:: constructor(object)
+
+ Declares *object* to be a valid constructor. If *object* is not callable (and
+ hence not valid as a constructor), raises :exc:`TypeError`.
+
+
+.. function:: pickle(type, function[, constructor])
+
+ Declares that *function* should be used as a "reduction" function for objects of
+ type *type*; *type* must not be a "classic" class object. (Classic classes are
+ handled differently; see the documentation for the :mod:`pickle` module for
+ details.) *function* should return either a string or a tuple containing two or
+ three elements.
+
+ The optional *constructor* parameter, if provided, is a callable object which
+ can be used to reconstruct the object when called with the tuple of arguments
+ returned by *function* at pickling time. :exc:`TypeError` will be raised if
+ *object* is a class or *constructor* is not callable.
+
+ See the :mod:`pickle` module for more details on the interface expected of
+ *function* and *constructor*.
+
--- /dev/null
+
+:mod:`crypt` --- Function to check Unix passwords
+=================================================
+
+.. module:: crypt
+ :platform: Unix
+ :synopsis: The crypt() function used to check Unix passwords.
+.. moduleauthor:: Steven D. Majewski <sdm7g@virginia.edu>
+.. sectionauthor:: Steven D. Majewski <sdm7g@virginia.edu>
+.. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
+
+
+.. index::
+ single: crypt(3)
+ pair: cipher; DES
+
+This module implements an interface to the :manpage:`crypt(3)` routine, which is
+a one-way hash function based upon a modified DES algorithm; see the Unix man
+page for further details. Possible uses include allowing Python scripts to
+accept typed passwords from the user, or attempting to crack Unix passwords with
+a dictionary.
+
+.. index:: single: crypt(3)
+
+Notice that the behavior of this module depends on the actual implementation of
+the :manpage:`crypt(3)` routine in the running system. Therefore, any
+extensions available on the current implementation will also be available on
+this module.
+
+
+.. function:: crypt(word, salt)
+
+ *word* will usually be a user's password as typed at a prompt or in a graphical
+ interface. *salt* is usually a random two-character string which will be used
+ to perturb the DES algorithm in one of 4096 ways. The characters in *salt* must
+ be in the set ``[./a-zA-Z0-9]``. Returns the hashed password as a string, which
+ will be composed of characters from the same alphabet as the salt (the first two
+ characters represent the salt itself).
+
+ .. index:: single: crypt(3)
+
+ Since a few :manpage:`crypt(3)` extensions allow different values, with
+ different sizes in the *salt*, it is recommended to use the full crypted
+ password as salt when checking for a password.
+
+A simple example illustrating typical use::
+
+ import crypt, getpass, pwd
+
+ def login():
+ username = raw_input('Python login:')
+ cryptedpasswd = pwd.getpwnam(username)[1]
+ if cryptedpasswd:
+ if cryptedpasswd == 'x' or cryptedpasswd == '*':
+ raise "Sorry, currently no support for shadow passwords"
+ cleartext = getpass.getpass()
+ return crypt.crypt(cleartext, cryptedpasswd) == cryptedpasswd
+ else:
+ return 1
+
--- /dev/null
+
+.. _crypto:
+
+**********************
+Cryptographic Services
+**********************
+
+.. index:: single: cryptography
+
+The modules described in this chapter implement various algorithms of a
+cryptographic nature. They are available at the discretion of the installation.
+Here's an overview:
+
+
+.. toctree::
+
+ hashlib.rst
+ hmac.rst
+ md5.rst
+ sha.rst
+.. index::
+ pair: AES; algorithm
+ single: cryptography
+ single: Kuchling, Andrew
+
+Hardcore cypherpunks will probably find the cryptographic modules written by
+A.M. Kuchling of further interest; the package contains modules for various
+encryption algorithms, most notably AES. These modules are not distributed with
+Python but available separately. See the URL
+http://www.amk.ca/python/code/crypto.html for more information.
+
--- /dev/null
+
+:mod:`csv` --- CSV File Reading and Writing
+===========================================
+
+.. module:: csv
+ :synopsis: Write and read tabular data to and from delimited files.
+.. sectionauthor:: Skip Montanaro <skip@pobox.com>
+
+
+.. versionadded:: 2.3
+
+.. index::
+ single: csv
+ pair: data; tabular
+
+The so-called CSV (Comma Separated Values) format is the most common import and
+export format for spreadsheets and databases. There is no "CSV standard", so
+the format is operationally defined by the many applications which read and
+write it. The lack of a standard means that subtle differences often exist in
+the data produced and consumed by different applications. These differences can
+make it annoying to process CSV files from multiple sources. Still, while the
+delimiters and quoting characters vary, the overall format is similar enough
+that it is possible to write a single module which can efficiently manipulate
+such data, hiding the details of reading and writing the data from the
+programmer.
+
+The :mod:`csv` module implements classes to read and write tabular data in CSV
+format. It allows programmers to say, "write this data in the format preferred
+by Excel," or "read data from this file which was generated by Excel," without
+knowing the precise details of the CSV format used by Excel. Programmers can
+also describe the CSV formats understood by other applications or define their
+own special-purpose CSV formats.
+
+The :mod:`csv` module's :class:`reader` and :class:`writer` objects read and
+write sequences. Programmers can also read and write data in dictionary form
+using the :class:`DictReader` and :class:`DictWriter` classes.
+
+.. note::
+
+ This version of the :mod:`csv` module doesn't support Unicode input. Also,
+ there are currently some issues regarding ASCII NUL characters. Accordingly,
+ all input should be UTF-8 or printable ASCII to be safe; see the examples in
+ section :ref:`csv-examples`. These restrictions will be removed in the future.
+
+
+.. seealso::
+
+ .. % \seemodule{array}{Arrays of uniformly types numeric values.}
+
+ :pep:`305` - CSV File API
+ The Python Enhancement Proposal which proposed this addition to Python.
+
+
+.. _csv-contents:
+
+Module Contents
+---------------
+
+The :mod:`csv` module defines the following functions:
+
+
+.. function:: reader(csvfile[, dialect='excel'][, fmtparam])
+
+ Return a reader object which will iterate over lines in the given *csvfile*.
+ *csvfile* can be any object which supports the iterator protocol and returns a
+ string each time its :meth:`next` method is called --- file objects and list
+ objects are both suitable. If *csvfile* is a file object, it must be opened
+ with the 'b' flag on platforms where that makes a difference. An optional
+ *dialect* parameter can be given which is used to define a set of parameters
+ specific to a particular CSV dialect. It may be an instance of a subclass of
+ the :class:`Dialect` class or one of the strings returned by the
+ :func:`list_dialects` function. The other optional *fmtparam* keyword arguments
+ can be given to override individual formatting parameters in the current
+ dialect. For full details about the dialect and formatting parameters, see
+ section :ref:`csv-fmt-params`.
+
+ All data read are returned as strings. No automatic data type conversion is
+ performed.
+
+ .. versionchanged:: 2.5
+ The parser is now stricter with respect to multi-line quoted fields. Previously,
+ if a line ended within a quoted field without a terminating newline character, a
+ newline would be inserted into the returned field. This behavior caused problems
+ when reading files which contained carriage return characters within fields.
+ The behavior was changed to return the field without inserting newlines. As a
+ consequence, if newlines embedded within fields are important, the input should
+ be split into lines in a manner which preserves the newline characters.
+
+
+.. function:: writer(csvfile[, dialect='excel'][, fmtparam])
+
+ Return a writer object responsible for converting the user's data into delimited
+ strings on the given file-like object. *csvfile* can be any object with a
+ :func:`write` method. If *csvfile* is a file object, it must be opened with the
+ 'b' flag on platforms where that makes a difference. An optional *dialect*
+ parameter can be given which is used to define a set of parameters specific to a
+ particular CSV dialect. It may be an instance of a subclass of the
+ :class:`Dialect` class or one of the strings returned by the
+ :func:`list_dialects` function. The other optional *fmtparam* keyword arguments
+ can be given to override individual formatting parameters in the current
+ dialect. For full details about the dialect and formatting parameters, see
+ section :ref:`csv-fmt-params`. To make it
+ as easy as possible to interface with modules which implement the DB API, the
+ value :const:`None` is written as the empty string. While this isn't a
+ reversible transformation, it makes it easier to dump SQL NULL data values to
+ CSV files without preprocessing the data returned from a ``cursor.fetch*`` call.
+ All other non-string data are stringified with :func:`str` before being written.
+
+
+.. function:: register_dialect(name[, dialect][, fmtparam])
+
+ Associate *dialect* with *name*. *name* must be a string or Unicode object. The
+ dialect can be specified either by passing a sub-class of :class:`Dialect`, or
+ by *fmtparam* keyword arguments, or both, with keyword arguments overriding
+ parameters of the dialect. For full details about the dialect and formatting
+ parameters, see section :ref:`csv-fmt-params`.
+
+
+.. function:: unregister_dialect(name)
+
+ Delete the dialect associated with *name* from the dialect registry. An
+ :exc:`Error` is raised if *name* is not a registered dialect name.
+
+
+.. function:: get_dialect(name)
+
+ Return the dialect associated with *name*. An :exc:`Error` is raised if *name*
+ is not a registered dialect name.
+
+
+.. function:: list_dialects()
+
+ Return the names of all registered dialects.
+
+
+.. function:: field_size_limit([new_limit])
+
+ Returns the current maximum field size allowed by the parser. If *new_limit* is
+ given, this becomes the new limit.
+
+ .. versionadded:: 2.5
+
+The :mod:`csv` module defines the following classes:
+
+
+.. class:: DictReader(csvfile[, fieldnames=:const:None,[, restkey=:const:None[, restval=None[, dialect='excel'[, *args, **kwds]]]]])
+
+ Create an object which operates like a regular reader but maps the information
+ read into a dict whose keys are given by the optional *fieldnames* parameter.
+ If the *fieldnames* parameter is omitted, the values in the first row of the
+ *csvfile* will be used as the fieldnames. If the row read has fewer fields than
+ the fieldnames sequence, the value of *restval* will be used as the default
+ value. If the row read has more fields than the fieldnames sequence, the
+ remaining data is added as a sequence keyed by the value of *restkey*. If the
+ row read has fewer fields than the fieldnames sequence, the remaining keys take
+ the value of the optional *restval* parameter. Any other optional or keyword
+ arguments are passed to the underlying :class:`reader` instance.
+
+
+.. class:: DictWriter(csvfile, fieldnames[, restval=''[, extrasaction='raise'[, dialect='excel'[, *args, **kwds]]]])
+
+ Create an object which operates like a regular writer but maps dictionaries onto
+ output rows. The *fieldnames* parameter identifies the order in which values in
+ the dictionary passed to the :meth:`writerow` method are written to the
+ *csvfile*. The optional *restval* parameter specifies the value to be written
+ if the dictionary is missing a key in *fieldnames*. If the dictionary passed to
+ the :meth:`writerow` method contains a key not found in *fieldnames*, the
+ optional *extrasaction* parameter indicates what action to take. If it is set
+ to ``'raise'`` a :exc:`ValueError` is raised. If it is set to ``'ignore'``,
+ extra values in the dictionary are ignored. Any other optional or keyword
+ arguments are passed to the underlying :class:`writer` instance.
+
+ Note that unlike the :class:`DictReader` class, the *fieldnames* parameter of
+ the :class:`DictWriter` is not optional. Since Python's :class:`dict` objects
+ are not ordered, there is not enough information available to deduce the order
+ in which the row should be written to the *csvfile*.
+
+
+.. class:: Dialect
+
+ The :class:`Dialect` class is a container class relied on primarily for its
+ attributes, which are used to define the parameters for a specific
+ :class:`reader` or :class:`writer` instance.
+
+
+.. class:: excel()
+
+ The :class:`excel` class defines the usual properties of an Excel-generated CSV
+ file. It is registered with the dialect name ``'excel'``.
+
+
+.. class:: excel_tab()
+
+ The :class:`excel_tab` class defines the usual properties of an Excel-generated
+ TAB-delimited file. It is registered with the dialect name ``'excel-tab'``.
+
+
+.. class:: Sniffer()
+
+ The :class:`Sniffer` class is used to deduce the format of a CSV file.
+
+The :class:`Sniffer` class provides two methods:
+
+
+.. method:: Sniffer.sniff(sample[, delimiters=None])
+
+ Analyze the given *sample* and return a :class:`Dialect` subclass reflecting the
+ parameters found. If the optional *delimiters* parameter is given, it is
+ interpreted as a string containing possible valid delimiter characters.
+
+
+.. method:: Sniffer.has_header(sample)
+
+ Analyze the sample text (presumed to be in CSV format) and return :const:`True`
+ if the first row appears to be a series of column headers.
+
+The :mod:`csv` module defines the following constants:
+
+
+.. data:: QUOTE_ALL
+
+ Instructs :class:`writer` objects to quote all fields.
+
+
+.. data:: QUOTE_MINIMAL
+
+ Instructs :class:`writer` objects to only quote those fields which contain
+ special characters such as *delimiter*, *quotechar* or any of the characters in
+ *lineterminator*.
+
+
+.. data:: QUOTE_NONNUMERIC
+
+ Instructs :class:`writer` objects to quote all non-numeric fields.
+
+ Instructs the reader to convert all non-quoted fields to type *float*.
+
+
+.. data:: QUOTE_NONE
+
+ Instructs :class:`writer` objects to never quote fields. When the current
+ *delimiter* occurs in output data it is preceded by the current *escapechar*
+ character. If *escapechar* is not set, the writer will raise :exc:`Error` if
+ any characters that require escaping are encountered.
+
+ Instructs :class:`reader` to perform no special processing of quote characters.
+
+The :mod:`csv` module defines the following exception:
+
+
+.. exception:: Error
+
+ Raised by any of the functions when an error is detected.
+
+
+.. _csv-fmt-params:
+
+Dialects and Formatting Parameters
+----------------------------------
+
+To make it easier to specify the format of input and output records, specific
+formatting parameters are grouped together into dialects. A dialect is a
+subclass of the :class:`Dialect` class having a set of specific methods and a
+single :meth:`validate` method. When creating :class:`reader` or
+:class:`writer` objects, the programmer can specify a string or a subclass of
+the :class:`Dialect` class as the dialect parameter. In addition to, or instead
+of, the *dialect* parameter, the programmer can also specify individual
+formatting parameters, which have the same names as the attributes defined below
+for the :class:`Dialect` class.
+
+Dialects support the following attributes:
+
+
+.. attribute:: Dialect.delimiter
+
+ A one-character string used to separate fields. It defaults to ``','``.
+
+
+.. attribute:: Dialect.doublequote
+
+ Controls how instances of *quotechar* appearing inside a field should be
+ themselves be quoted. When :const:`True`, the character is doubled. When
+ :const:`False`, the *escapechar* is used as a prefix to the *quotechar*. It
+ defaults to :const:`True`.
+
+ On output, if *doublequote* is :const:`False` and no *escapechar* is set,
+ :exc:`Error` is raised if a *quotechar* is found in a field.
+
+
+.. attribute:: Dialect.escapechar
+
+ A one-character string used by the writer to escape the *delimiter* if *quoting*
+ is set to :const:`QUOTE_NONE` and the *quotechar* if *doublequote* is
+ :const:`False`. On reading, the *escapechar* removes any special meaning from
+ the following character. It defaults to :const:`None`, which disables escaping.
+
+
+.. attribute:: Dialect.lineterminator
+
+ The string used to terminate lines produced by the :class:`writer`. It defaults
+ to ``'\r\n'``.
+
+ .. note::
+
+ The :class:`reader` is hard-coded to recognise either ``'\r'`` or ``'\n'`` as
+ end-of-line, and ignores *lineterminator*. This behavior may change in the
+ future.
+
+
+.. attribute:: Dialect.quotechar
+
+ A one-character string used to quote fields containing special characters, such
+ as the *delimiter* or *quotechar*, or which contain new-line characters. It
+ defaults to ``'"'``.
+
+
+.. attribute:: Dialect.quoting
+
+ Controls when quotes should be generated by the writer and recognised by the
+ reader. It can take on any of the :const:`QUOTE_\*` constants (see section
+ :ref:`csv-contents`) and defaults to :const:`QUOTE_MINIMAL`.
+
+
+.. attribute:: Dialect.skipinitialspace
+
+ When :const:`True`, whitespace immediately following the *delimiter* is ignored.
+ The default is :const:`False`.
+
+
+Reader Objects
+--------------
+
+Reader objects (:class:`DictReader` instances and objects returned by the
+:func:`reader` function) have the following public methods:
+
+
+.. method:: csvreader.next()
+
+ Return the next row of the reader's iterable object as a list, parsed according
+ to the current dialect.
+
+Reader objects have the following public attributes:
+
+
+.. attribute:: csvreader.dialect
+
+ A read-only description of the dialect in use by the parser.
+
+
+.. attribute:: csvreader.line_num
+
+ The number of lines read from the source iterator. This is not the same as the
+ number of records returned, as records can span multiple lines.
+
+ .. versionadded:: 2.5
+
+
+Writer Objects
+--------------
+
+:class:`Writer` objects (:class:`DictWriter` instances and objects returned by
+the :func:`writer` function) have the following public methods. A *row* must be
+a sequence of strings or numbers for :class:`Writer` objects and a dictionary
+mapping fieldnames to strings or numbers (by passing them through :func:`str`
+first) for :class:`DictWriter` objects. Note that complex numbers are written
+out surrounded by parens. This may cause some problems for other programs which
+read CSV files (assuming they support complex numbers at all).
+
+
+.. method:: csvwriter.writerow(row)
+
+ Write the *row* parameter to the writer's file object, formatted according to
+ the current dialect.
+
+
+.. method:: csvwriter.writerows(rows)
+
+ Write all the *rows* parameters (a list of *row* objects as described above) to
+ the writer's file object, formatted according to the current dialect.
+
+Writer objects have the following public attribute:
+
+
+.. attribute:: csvwriter.dialect
+
+ A read-only description of the dialect in use by the writer.
+
+
+.. _csv-examples:
+
+Examples
+--------
+
+The simplest example of reading a CSV file::
+
+ import csv
+ reader = csv.reader(open("some.csv", "rb"))
+ for row in reader:
+ print row
+
+Reading a file with an alternate format::
+
+ import csv
+ reader = csv.reader(open("passwd", "rb"), delimiter=':', quoting=csv.QUOTE_NONE)
+ for row in reader:
+ print row
+
+The corresponding simplest possible writing example is::
+
+ import csv
+ writer = csv.writer(open("some.csv", "wb"))
+ writer.writerows(someiterable)
+
+Registering a new dialect::
+
+ import csv
+
+ csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
+
+ reader = csv.reader(open("passwd", "rb"), 'unixpwd')
+
+A slightly more advanced use of the reader --- catching and reporting errors::
+
+ import csv, sys
+ filename = "some.csv"
+ reader = csv.reader(open(filename, "rb"))
+ try:
+ for row in reader:
+ print row
+ except csv.Error, e:
+ sys.exit('file %s, line %d: %s' % (filename, reader.line_num, e))
+
+And while the module doesn't directly support parsing strings, it can easily be
+done::
+
+ import csv
+ for row in csv.reader(['one,two,three']):
+ print row
+
+The :mod:`csv` module doesn't directly support reading and writing Unicode, but
+it is 8-bit-clean save for some problems with ASCII NUL characters. So you can
+write functions or classes that handle the encoding and decoding for you as long
+as you avoid encodings like UTF-16 that use NULs. UTF-8 is recommended.
+
+:func:`unicode_csv_reader` below is a generator that wraps :class:`csv.reader`
+to handle Unicode CSV data (a list of Unicode strings). :func:`utf_8_encoder`
+is a generator that encodes the Unicode strings as UTF-8, one string (or row) at
+a time. The encoded strings are parsed by the CSV reader, and
+:func:`unicode_csv_reader` decodes the UTF-8-encoded cells back into Unicode::
+
+ import csv
+
+ def unicode_csv_reader(unicode_csv_data, dialect=csv.excel, **kwargs):
+ # csv.py doesn't do Unicode; encode temporarily as UTF-8:
+ csv_reader = csv.reader(utf_8_encoder(unicode_csv_data),
+ dialect=dialect, **kwargs)
+ for row in csv_reader:
+ # decode UTF-8 back to Unicode, cell by cell:
+ yield [unicode(cell, 'utf-8') for cell in row]
+
+ def utf_8_encoder(unicode_csv_data):
+ for line in unicode_csv_data:
+ yield line.encode('utf-8')
+
+For all other encodings the following :class:`UnicodeReader` and
+:class:`UnicodeWriter` classes can be used. They take an additional *encoding*
+parameter in their constructor and make sure that the data passes the real
+reader or writer encoded as UTF-8::
+
+ import csv, codecs, cStringIO
+
+ class UTF8Recoder:
+ """
+ Iterator that reads an encoded stream and reencodes the input to UTF-8
+ """
+ def __init__(self, f, encoding):
+ self.reader = codecs.getreader(encoding)(f)
+
+ def __iter__(self):
+ return self
+
+ def next(self):
+ return self.reader.next().encode("utf-8")
+
+ class UnicodeReader:
+ """
+ A CSV reader which will iterate over lines in the CSV file "f",
+ which is encoded in the given encoding.
+ """
+
+ def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
+ f = UTF8Recoder(f, encoding)
+ self.reader = csv.reader(f, dialect=dialect, **kwds)
+
+ def next(self):
+ row = self.reader.next()
+ return [unicode(s, "utf-8") for s in row]
+
+ def __iter__(self):
+ return self
+
+ class UnicodeWriter:
+ """
+ A CSV writer which will write rows to CSV file "f",
+ which is encoded in the given encoding.
+ """
+
+ def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
+ # Redirect output to a queue
+ self.queue = cStringIO.StringIO()
+ self.writer = csv.writer(self.queue, dialect=dialect, **kwds)
+ self.stream = f
+ self.encoder = codecs.getincrementalencoder(encoding)()
+
+ def writerow(self, row):
+ self.writer.writerow([s.encode("utf-8") for s in row])
+ # Fetch UTF-8 output from the queue ...
+ data = self.queue.getvalue()
+ data = data.decode("utf-8")
+ # ... and reencode it into the target encoding
+ data = self.encoder.encode(data)
+ # write to the target stream
+ self.stream.write(data)
+ # empty queue
+ self.queue.truncate(0)
+
+ def writerows(self, rows):
+ for row in rows:
+ self.writerow(row)
+
--- /dev/null
+
+:mod:`ctypes` --- A foreign function library for Python.
+========================================================
+
+.. module:: ctypes
+ :synopsis: A foreign function library for Python.
+.. moduleauthor:: Thomas Heller <theller@python.net>
+
+
+.. versionadded:: 2.5
+
+``ctypes`` is a foreign function library for Python. It provides C compatible
+data types, and allows calling functions in dlls/shared libraries. It can be
+used to wrap these libraries in pure Python.
+
+
+.. _ctypes-ctypes-tutorial:
+
+ctypes tutorial
+---------------
+
+Note: The code samples in this tutorial use ``doctest`` to make sure that they
+actually work. Since some code samples behave differently under Linux, Windows,
+or Mac OS X, they contain doctest directives in comments.
+
+Note: Some code sample references the ctypes :class:`c_int` type. This type is
+an alias to the :class:`c_long` type on 32-bit systems. So, you should not be
+confused if :class:`c_long` is printed if you would expect :class:`c_int` ---
+they are actually the same type.
+
+
+.. _ctypes-loading-dynamic-link-libraries:
+
+Loading dynamic link libraries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``ctypes`` exports the *cdll*, and on Windows also *windll* and *oledll* objects
+to load dynamic link libraries.
+
+You load libraries by accessing them as attributes of these objects. *cdll*
+loads libraries which export functions using the standard ``cdecl`` calling
+convention, while *windll* libraries call functions using the ``stdcall``
+calling convention. *oledll* also uses the ``stdcall`` calling convention, and
+assumes the functions return a Windows :class:`HRESULT` error code. The error
+code is used to automatically raise :class:`WindowsError` Python exceptions when
+the function call fails.
+
+Here are some examples for Windows. Note that ``msvcrt`` is the MS standard C
+library containing most standard C functions, and uses the cdecl calling
+convention::
+
+ >>> from ctypes import *
+ >>> print windll.kernel32 # doctest: +WINDOWS
+ <WinDLL 'kernel32', handle ... at ...>
+ >>> print cdll.msvcrt # doctest: +WINDOWS
+ <CDLL 'msvcrt', handle ... at ...>
+ >>> libc = cdll.msvcrt # doctest: +WINDOWS
+ >>>
+
+Windows appends the usual '.dll' file suffix automatically.
+
+On Linux, it is required to specify the filename *including* the extension to
+load a library, so attribute access does not work. Either the
+:meth:`LoadLibrary` method of the dll loaders should be used, or you should load
+the library by creating an instance of CDLL by calling the constructor::
+
+ >>> cdll.LoadLibrary("libc.so.6") # doctest: +LINUX
+ <CDLL 'libc.so.6', handle ... at ...>
+ >>> libc = CDLL("libc.so.6") # doctest: +LINUX
+ >>> libc # doctest: +LINUX
+ <CDLL 'libc.so.6', handle ... at ...>
+ >>>
+
+.. % XXX Add section for Mac OS X.
+
+
+.. _ctypes-accessing-functions-from-loaded-dlls:
+
+Accessing functions from loaded dlls
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Functions are accessed as attributes of dll objects::
+
+ >>> from ctypes import *
+ >>> libc.printf
+ <_FuncPtr object at 0x...>
+ >>> print windll.kernel32.GetModuleHandleA # doctest: +WINDOWS
+ <_FuncPtr object at 0x...>
+ >>> print windll.kernel32.MyOwnFunction # doctest: +WINDOWS
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ File "ctypes.py", line 239, in __getattr__
+ func = _StdcallFuncPtr(name, self)
+ AttributeError: function 'MyOwnFunction' not found
+ >>>
+
+Note that win32 system dlls like ``kernel32`` and ``user32`` often export ANSI
+as well as UNICODE versions of a function. The UNICODE version is exported with
+an ``W`` appended to the name, while the ANSI version is exported with an ``A``
+appended to the name. The win32 ``GetModuleHandle`` function, which returns a
+*module handle* for a given module name, has the following C prototype, and a
+macro is used to expose one of them as ``GetModuleHandle`` depending on whether
+UNICODE is defined or not::
+
+ /* ANSI version */
+ HMODULE GetModuleHandleA(LPCSTR lpModuleName);
+ /* UNICODE version */
+ HMODULE GetModuleHandleW(LPCWSTR lpModuleName);
+
+*windll* does not try to select one of them by magic, you must access the
+version you need by specifying ``GetModuleHandleA`` or ``GetModuleHandleW``
+explicitely, and then call it with normal strings or unicode strings
+respectively.
+
+Sometimes, dlls export functions with names which aren't valid Python
+identifiers, like ``"??2@YAPAXI@Z"``. In this case you have to use ``getattr``
+to retrieve the function::
+
+ >>> getattr(cdll.msvcrt, "??2@YAPAXI@Z") # doctest: +WINDOWS
+ <_FuncPtr object at 0x...>
+ >>>
+
+On Windows, some dlls export functions not by name but by ordinal. These
+functions can be accessed by indexing the dll object with the ordinal number::
+
+ >>> cdll.kernel32[1] # doctest: +WINDOWS
+ <_FuncPtr object at 0x...>
+ >>> cdll.kernel32[0] # doctest: +WINDOWS
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ File "ctypes.py", line 310, in __getitem__
+ func = _StdcallFuncPtr(name, self)
+ AttributeError: function ordinal 0 not found
+ >>>
+
+
+.. _ctypes-calling-functions:
+
+Calling functions
+^^^^^^^^^^^^^^^^^
+
+You can call these functions like any other Python callable. This example uses
+the ``time()`` function, which returns system time in seconds since the Unix
+epoch, and the ``GetModuleHandleA()`` function, which returns a win32 module
+handle.
+
+This example calls both functions with a NULL pointer (``None`` should be used
+as the NULL pointer)::
+
+ >>> print libc.time(None) # doctest: +SKIP
+ 1150640792
+ >>> print hex(windll.kernel32.GetModuleHandleA(None)) # doctest: +WINDOWS
+ 0x1d000000
+ >>>
+
+``ctypes`` tries to protect you from calling functions with the wrong number of
+arguments or the wrong calling convention. Unfortunately this only works on
+Windows. It does this by examining the stack after the function returns, so
+although an error is raised the function *has* been called::
+
+ >>> windll.kernel32.GetModuleHandleA() # doctest: +WINDOWS
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ ValueError: Procedure probably called with not enough arguments (4 bytes missing)
+ >>> windll.kernel32.GetModuleHandleA(0, 0) # doctest: +WINDOWS
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ ValueError: Procedure probably called with too many arguments (4 bytes in excess)
+ >>>
+
+The same exception is raised when you call an ``stdcall`` function with the
+``cdecl`` calling convention, or vice versa::
+
+ >>> cdll.kernel32.GetModuleHandleA(None) # doctest: +WINDOWS
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ ValueError: Procedure probably called with not enough arguments (4 bytes missing)
+ >>>
+
+ >>> windll.msvcrt.printf("spam") # doctest: +WINDOWS
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ ValueError: Procedure probably called with too many arguments (4 bytes in excess)
+ >>>
+
+To find out the correct calling convention you have to look into the C header
+file or the documentation for the function you want to call.
+
+On Windows, ``ctypes`` uses win32 structured exception handling to prevent
+crashes from general protection faults when functions are called with invalid
+argument values::
+
+ >>> windll.kernel32.GetModuleHandleA(32) # doctest: +WINDOWS
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ WindowsError: exception: access violation reading 0x00000020
+ >>>
+
+There are, however, enough ways to crash Python with ``ctypes``, so you should
+be careful anyway.
+
+``None``, integers, longs, byte strings and unicode strings are the only native
+Python objects that can directly be used as parameters in these function calls.
+``None`` is passed as a C ``NULL`` pointer, byte strings and unicode strings are
+passed as pointer to the memory block that contains their data (``char *`` or
+``wchar_t *``). Python integers and Python longs are passed as the platforms
+default C ``int`` type, their value is masked to fit into the C type.
+
+Before we move on calling functions with other parameter types, we have to learn
+more about ``ctypes`` data types.
+
+
+.. _ctypes-fundamental-data-types:
+
+Fundamental data types
+^^^^^^^^^^^^^^^^^^^^^^
+
+``ctypes`` defines a number of primitive C compatible data types :
+
+ +----------------------+--------------------------------+----------------------------+
+ | ctypes type | C type | Python type |
+ +======================+================================+============================+
+ | :class:`c_char` | ``char`` | 1-character string |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_wchar` | ``wchar_t`` | 1-character unicode string |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_byte` | ``char`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_ubyte` | ``unsigned char`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_short` | ``short`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_ushort` | ``unsigned short`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_int` | ``int`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_uint` | ``unsigned int`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_long` | ``long`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_ulong` | ``unsigned long`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_longlong` | ``__int64`` or ``long long`` | int/long |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_ulonglong` | ``unsigned __int64`` or | int/long |
+ | | ``unsigned long long`` | |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_float` | ``float`` | float |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_double` | ``double`` | float |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_char_p` | ``char *`` (NUL terminated) | string or ``None`` |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_wchar_p` | ``wchar_t *`` (NUL terminated) | unicode or ``None`` |
+ +----------------------+--------------------------------+----------------------------+
+ | :class:`c_void_p` | ``void *`` | int/long or ``None`` |
+ +----------------------+--------------------------------+----------------------------+
+
+
+All these types can be created by calling them with an optional initializer of
+the correct type and value::
+
+ >>> c_int()
+ c_long(0)
+ >>> c_char_p("Hello, World")
+ c_char_p('Hello, World')
+ >>> c_ushort(-3)
+ c_ushort(65533)
+ >>>
+
+Since these types are mutable, their value can also be changed afterwards::
+
+ >>> i = c_int(42)
+ >>> print i
+ c_long(42)
+ >>> print i.value
+ 42
+ >>> i.value = -99
+ >>> print i.value
+ -99
+ >>>
+
+Assigning a new value to instances of the pointer types :class:`c_char_p`,
+:class:`c_wchar_p`, and :class:`c_void_p` changes the *memory location* they
+point to, *not the contents* of the memory block (of course not, because Python
+strings are immutable)::
+
+ >>> s = "Hello, World"
+ >>> c_s = c_char_p(s)
+ >>> print c_s
+ c_char_p('Hello, World')
+ >>> c_s.value = "Hi, there"
+ >>> print c_s
+ c_char_p('Hi, there')
+ >>> print s # first string is unchanged
+ Hello, World
+ >>>
+
+You should be careful, however, not to pass them to functions expecting pointers
+to mutable memory. If you need mutable memory blocks, ctypes has a
+``create_string_buffer`` function which creates these in various ways. The
+current memory block contents can be accessed (or changed) with the ``raw``
+property; if you want to access it as NUL terminated string, use the ``value``
+property::
+
+ >>> from ctypes import *
+ >>> p = create_string_buffer(3) # create a 3 byte buffer, initialized to NUL bytes
+ >>> print sizeof(p), repr(p.raw)
+ 3 '\x00\x00\x00'
+ >>> p = create_string_buffer("Hello") # create a buffer containing a NUL terminated string
+ >>> print sizeof(p), repr(p.raw)
+ 6 'Hello\x00'
+ >>> print repr(p.value)
+ 'Hello'
+ >>> p = create_string_buffer("Hello", 10) # create a 10 byte buffer
+ >>> print sizeof(p), repr(p.raw)
+ 10 'Hello\x00\x00\x00\x00\x00'
+ >>> p.value = "Hi"
+ >>> print sizeof(p), repr(p.raw)
+ 10 'Hi\x00lo\x00\x00\x00\x00\x00'
+ >>>
+
+The ``create_string_buffer`` function replaces the ``c_buffer`` function (which
+is still available as an alias), as well as the ``c_string`` function from
+earlier ctypes releases. To create a mutable memory block containing unicode
+characters of the C type ``wchar_t`` use the ``create_unicode_buffer`` function.
+
+
+.. _ctypes-calling-functions-continued:
+
+Calling functions, continued
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Note that printf prints to the real standard output channel, *not* to
+``sys.stdout``, so these examples will only work at the console prompt, not from
+within *IDLE* or *PythonWin*::
+
+ >>> printf = libc.printf
+ >>> printf("Hello, %s\n", "World!")
+ Hello, World!
+ 14
+ >>> printf("Hello, %S", u"World!")
+ Hello, World!
+ 13
+ >>> printf("%d bottles of beer\n", 42)
+ 42 bottles of beer
+ 19
+ >>> printf("%f bottles of beer\n", 42.5)
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ ArgumentError: argument 2: exceptions.TypeError: Don't know how to convert parameter 2
+ >>>
+
+As has been mentioned before, all Python types except integers, strings, and
+unicode strings have to be wrapped in their corresponding ``ctypes`` type, so
+that they can be converted to the required C data type::
+
+ >>> printf("An int %d, a double %f\n", 1234, c_double(3.14))
+ Integer 1234, double 3.1400001049
+ 31
+ >>>
+
+
+.. _ctypes-calling-functions-with-own-custom-data-types:
+
+Calling functions with your own custom data types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can also customize ``ctypes`` argument conversion to allow instances of your
+own classes be used as function arguments. ``ctypes`` looks for an
+:attr:`_as_parameter_` attribute and uses this as the function argument. Of
+course, it must be one of integer, string, or unicode::
+
+ >>> class Bottles(object):
+ ... def __init__(self, number):
+ ... self._as_parameter_ = number
+ ...
+ >>> bottles = Bottles(42)
+ >>> printf("%d bottles of beer\n", bottles)
+ 42 bottles of beer
+ 19
+ >>>
+
+If you don't want to store the instance's data in the :attr:`_as_parameter_`
+instance variable, you could define a ``property`` which makes the data
+avaiblable.
+
+
+.. _ctypes-specifying-required-argument-types:
+
+Specifying the required argument types (function prototypes)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to specify the required argument types of functions exported from
+DLLs by setting the :attr:`argtypes` attribute.
+
+:attr:`argtypes` must be a sequence of C data types (the ``printf`` function is
+probably not a good example here, because it takes a variable number and
+different types of parameters depending on the format string, on the other hand
+this is quite handy to experiment with this feature)::
+
+ >>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]
+ >>> printf("String '%s', Int %d, Double %f\n", "Hi", 10, 2.2)
+ String 'Hi', Int 10, Double 2.200000
+ 37
+ >>>
+
+Specifying a format protects against incompatible argument types (just as a
+prototype for a C function), and tries to convert the arguments to valid types::
+
+ >>> printf("%d %d %d", 1, 2, 3)
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ ArgumentError: argument 2: exceptions.TypeError: wrong type
+ >>> printf("%s %d %f", "X", 2, 3)
+ X 2 3.00000012
+ 12
+ >>>
+
+If you have defined your own classes which you pass to function calls, you have
+to implement a :meth:`from_param` class method for them to be able to use them
+in the :attr:`argtypes` sequence. The :meth:`from_param` class method receives
+the Python object passed to the function call, it should do a typecheck or
+whatever is needed to make sure this object is acceptable, and then return the
+object itself, it's :attr:`_as_parameter_` attribute, or whatever you want to
+pass as the C function argument in this case. Again, the result should be an
+integer, string, unicode, a ``ctypes`` instance, or something having the
+:attr:`_as_parameter_` attribute.
+
+
+.. _ctypes-return-types:
+
+Return types
+^^^^^^^^^^^^
+
+By default functions are assumed to return the C ``int`` type. Other return
+types can be specified by setting the :attr:`restype` attribute of the function
+object.
+
+Here is a more advanced example, it uses the ``strchr`` function, which expects
+a string pointer and a char, and returns a pointer to a string::
+
+ >>> strchr = libc.strchr
+ >>> strchr("abcdef", ord("d")) # doctest: +SKIP
+ 8059983
+ >>> strchr.restype = c_char_p # c_char_p is a pointer to a string
+ >>> strchr("abcdef", ord("d"))
+ 'def'
+ >>> print strchr("abcdef", ord("x"))
+ None
+ >>>
+
+If you want to avoid the ``ord("x")`` calls above, you can set the
+:attr:`argtypes` attribute, and the second argument will be converted from a
+single character Python string into a C char::
+
+ >>> strchr.restype = c_char_p
+ >>> strchr.argtypes = [c_char_p, c_char]
+ >>> strchr("abcdef", "d")
+ 'def'
+ >>> strchr("abcdef", "def")
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ ArgumentError: argument 2: exceptions.TypeError: one character string expected
+ >>> print strchr("abcdef", "x")
+ None
+ >>> strchr("abcdef", "d")
+ 'def'
+ >>>
+
+You can also use a callable Python object (a function or a class for example) as
+the :attr:`restype` attribute, if the foreign function returns an integer. The
+callable will be called with the ``integer`` the C function returns, and the
+result of this call will be used as the result of your function call. This is
+useful to check for error return values and automatically raise an exception::
+
+ >>> GetModuleHandle = windll.kernel32.GetModuleHandleA # doctest: +WINDOWS
+ >>> def ValidHandle(value):
+ ... if value == 0:
+ ... raise WinError()
+ ... return value
+ ...
+ >>>
+ >>> GetModuleHandle.restype = ValidHandle # doctest: +WINDOWS
+ >>> GetModuleHandle(None) # doctest: +WINDOWS
+ 486539264
+ >>> GetModuleHandle("something silly") # doctest: +WINDOWS
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ File "<stdin>", line 3, in ValidHandle
+ WindowsError: [Errno 126] The specified module could not be found.
+ >>>
+
+``WinError`` is a function which will call Windows ``FormatMessage()`` api to
+get the string representation of an error code, and *returns* an exception.
+``WinError`` takes an optional error code parameter, if no one is used, it calls
+:func:`GetLastError` to retrieve it.
+
+Please note that a much more powerful error checking mechanism is available
+through the :attr:`errcheck` attribute; see the reference manual for details.
+
+
+.. _ctypes-passing-pointers:
+
+Passing pointers (or: passing parameters by reference)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes a C api function expects a *pointer* to a data type as parameter,
+probably to write into the corresponding location, or if the data is too large
+to be passed by value. This is also known as *passing parameters by reference*.
+
+``ctypes`` exports the :func:`byref` function which is used to pass parameters
+by reference. The same effect can be achieved with the ``pointer`` function,
+although ``pointer`` does a lot more work since it constructs a real pointer
+object, so it is faster to use :func:`byref` if you don't need the pointer
+object in Python itself::
+
+ >>> i = c_int()
+ >>> f = c_float()
+ >>> s = create_string_buffer('\000' * 32)
+ >>> print i.value, f.value, repr(s.value)
+ 0 0.0 ''
+ >>> libc.sscanf("1 3.14 Hello", "%d %f %s",
+ ... byref(i), byref(f), s)
+ 3
+ >>> print i.value, f.value, repr(s.value)
+ 1 3.1400001049 'Hello'
+ >>>
+
+
+.. _ctypes-structures-unions:
+
+Structures and unions
+^^^^^^^^^^^^^^^^^^^^^
+
+Structures and unions must derive from the :class:`Structure` and :class:`Union`
+base classes which are defined in the ``ctypes`` module. Each subclass must
+define a :attr:`_fields_` attribute. :attr:`_fields_` must be a list of
+*2-tuples*, containing a *field name* and a *field type*.
+
+The field type must be a ``ctypes`` type like :class:`c_int`, or any other
+derived ``ctypes`` type: structure, union, array, pointer.
+
+Here is a simple example of a POINT structure, which contains two integers named
+``x`` and ``y``, and also shows how to initialize a structure in the
+constructor::
+
+ >>> from ctypes import *
+ >>> class POINT(Structure):
+ ... _fields_ = [("x", c_int),
+ ... ("y", c_int)]
+ ...
+ >>> point = POINT(10, 20)
+ >>> print point.x, point.y
+ 10 20
+ >>> point = POINT(y=5)
+ >>> print point.x, point.y
+ 0 5
+ >>> POINT(1, 2, 3)
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ ValueError: too many initializers
+ >>>
+
+You can, however, build much more complicated structures. Structures can itself
+contain other structures by using a structure as a field type.
+
+Here is a RECT structure which contains two POINTs named ``upperleft`` and
+``lowerright`` ::
+
+ >>> class RECT(Structure):
+ ... _fields_ = [("upperleft", POINT),
+ ... ("lowerright", POINT)]
+ ...
+ >>> rc = RECT(point)
+ >>> print rc.upperleft.x, rc.upperleft.y
+ 0 5
+ >>> print rc.lowerright.x, rc.lowerright.y
+ 0 0
+ >>>
+
+Nested structures can also be initialized in the constructor in several ways::
+
+ >>> r = RECT(POINT(1, 2), POINT(3, 4))
+ >>> r = RECT((1, 2), (3, 4))
+
+Fields descriptors can be retrieved from the *class*, they are useful for
+debugging because they can provide useful information::
+
+ >>> print POINT.x
+ <Field type=c_long, ofs=0, size=4>
+ >>> print POINT.y
+ <Field type=c_long, ofs=4, size=4>
+ >>>
+
+
+.. _ctypes-structureunion-alignment-byte-order:
+
+Structure/union alignment and byte order
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, Structure and Union fields are aligned in the same way the C
+compiler does it. It is possible to override this behaviour be specifying a
+:attr:`_pack_` class attribute in the subclass definition. This must be set to a
+positive integer and specifies the maximum alignment for the fields. This is
+what ``#pragma pack(n)`` also does in MSVC.
+
+``ctypes`` uses the native byte order for Structures and Unions. To build
+structures with non-native byte order, you can use one of the
+BigEndianStructure, LittleEndianStructure, BigEndianUnion, and LittleEndianUnion
+base classes. These classes cannot contain pointer fields.
+
+
+.. _ctypes-bit-fields-in-structures-unions:
+
+Bit fields in structures and unions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to create structures and unions containing bit fields. Bit fields
+are only possible for integer fields, the bit width is specified as the third
+item in the :attr:`_fields_` tuples::
+
+ >>> class Int(Structure):
+ ... _fields_ = [("first_16", c_int, 16),
+ ... ("second_16", c_int, 16)]
+ ...
+ >>> print Int.first_16
+ <Field type=c_long, ofs=0:0, bits=16>
+ >>> print Int.second_16
+ <Field type=c_long, ofs=0:16, bits=16>
+ >>>
+
+
+.. _ctypes-arrays:
+
+Arrays
+^^^^^^
+
+Arrays are sequences, containing a fixed number of instances of the same type.
+
+The recommended way to create array types is by multiplying a data type with a
+positive integer::
+
+ TenPointsArrayType = POINT * 10
+
+Here is an example of an somewhat artifical data type, a structure containing 4
+POINTs among other stuff::
+
+ >>> from ctypes import *
+ >>> class POINT(Structure):
+ ... _fields_ = ("x", c_int), ("y", c_int)
+ ...
+ >>> class MyStruct(Structure):
+ ... _fields_ = [("a", c_int),
+ ... ("b", c_float),
+ ... ("point_array", POINT * 4)]
+ >>>
+ >>> print len(MyStruct().point_array)
+ 4
+ >>>
+
+Instances are created in the usual way, by calling the class::
+
+ arr = TenPointsArrayType()
+ for pt in arr:
+ print pt.x, pt.y
+
+The above code print a series of ``0 0`` lines, because the array contents is
+initialized to zeros.
+
+Initializers of the correct type can also be specified::
+
+ >>> from ctypes import *
+ >>> TenIntegers = c_int * 10
+ >>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+ >>> print ii
+ <c_long_Array_10 object at 0x...>
+ >>> for i in ii: print i,
+ ...
+ 1 2 3 4 5 6 7 8 9 10
+ >>>
+
+
+.. _ctypes-pointers:
+
+Pointers
+^^^^^^^^
+
+Pointer instances are created by calling the ``pointer`` function on a
+``ctypes`` type::
+
+ >>> from ctypes import *
+ >>> i = c_int(42)
+ >>> pi = pointer(i)
+ >>>
+
+Pointer instances have a ``contents`` attribute which returns the object to
+which the pointer points, the ``i`` object above::
+
+ >>> pi.contents
+ c_long(42)
+ >>>
+
+Note that ``ctypes`` does not have OOR (original object return), it constructs a
+new, equivalent object each time you retrieve an attribute::
+
+ >>> pi.contents is i
+ False
+ >>> pi.contents is pi.contents
+ False
+ >>>
+
+Assigning another :class:`c_int` instance to the pointer's contents attribute
+would cause the pointer to point to the memory location where this is stored::
+
+ >>> i = c_int(99)
+ >>> pi.contents = i
+ >>> pi.contents
+ c_long(99)
+ >>>
+
+Pointer instances can also be indexed with integers::
+
+ >>> pi[0]
+ 99
+ >>>
+
+Assigning to an integer index changes the pointed to value::
+
+ >>> print i
+ c_long(99)
+ >>> pi[0] = 22
+ >>> print i
+ c_long(22)
+ >>>
+
+It is also possible to use indexes different from 0, but you must know what
+you're doing, just as in C: You can access or change arbitrary memory locations.
+Generally you only use this feature if you receive a pointer from a C function,
+and you *know* that the pointer actually points to an array instead of a single
+item.
+
+Behind the scenes, the ``pointer`` function does more than simply create pointer
+instances, it has to create pointer *types* first. This is done with the
+``POINTER`` function, which accepts any ``ctypes`` type, and returns a new
+type::
+
+ >>> PI = POINTER(c_int)
+ >>> PI
+ <class 'ctypes.LP_c_long'>
+ >>> PI(42)
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ TypeError: expected c_long instead of int
+ >>> PI(c_int(42))
+ <ctypes.LP_c_long object at 0x...>
+ >>>
+
+Calling the pointer type without an argument creates a ``NULL`` pointer.
+``NULL`` pointers have a ``False`` boolean value::
+
+ >>> null_ptr = POINTER(c_int)()
+ >>> print bool(null_ptr)
+ False
+ >>>
+
+``ctypes`` checks for ``NULL`` when dereferencing pointers (but dereferencing
+non-\ ``NULL`` pointers would crash Python)::
+
+ >>> null_ptr[0]
+ Traceback (most recent call last):
+ ....
+ ValueError: NULL pointer access
+ >>>
+
+ >>> null_ptr[0] = 1234
+ Traceback (most recent call last):
+ ....
+ ValueError: NULL pointer access
+ >>>
+
+
+.. _ctypes-type-conversions:
+
+Type conversions
+^^^^^^^^^^^^^^^^
+
+Usually, ctypes does strict type checking. This means, if you have
+``POINTER(c_int)`` in the :attr:`argtypes` list of a function or as the type of
+a member field in a structure definition, only instances of exactly the same
+type are accepted. There are some exceptions to this rule, where ctypes accepts
+other objects. For example, you can pass compatible array instances instead of
+pointer types. So, for ``POINTER(c_int)``, ctypes accepts an array of c_int::
+
+ >>> class Bar(Structure):
+ ... _fields_ = [("count", c_int), ("values", POINTER(c_int))]
+ ...
+ >>> bar = Bar()
+ >>> bar.values = (c_int * 3)(1, 2, 3)
+ >>> bar.count = 3
+ >>> for i in range(bar.count):
+ ... print bar.values[i]
+ ...
+ 1
+ 2
+ 3
+ >>>
+
+To set a POINTER type field to ``NULL``, you can assign ``None``::
+
+ >>> bar.values = None
+ >>>
+
+XXX list other conversions...
+
+Sometimes you have instances of incompatible types. In ``C``, you can cast one
+type into another type. ``ctypes`` provides a ``cast`` function which can be
+used in the same way. The ``Bar`` structure defined above accepts
+``POINTER(c_int)`` pointers or :class:`c_int` arrays for its ``values`` field,
+but not instances of other types::
+
+ >>> bar.values = (c_byte * 4)()
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance
+ >>>
+
+For these cases, the ``cast`` function is handy.
+
+The ``cast`` function can be used to cast a ctypes instance into a pointer to a
+different ctypes data type. ``cast`` takes two parameters, a ctypes object that
+is or can be converted to a pointer of some kind, and a ctypes pointer type. It
+returns an instance of the second argument, which references the same memory
+block as the first argument::
+
+ >>> a = (c_byte * 4)()
+ >>> cast(a, POINTER(c_int))
+ <ctypes.LP_c_long object at ...>
+ >>>
+
+So, ``cast`` can be used to assign to the ``values`` field of ``Bar`` the
+structure::
+
+ >>> bar = Bar()
+ >>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
+ >>> print bar.values[0]
+ 0
+ >>>
+
+
+.. _ctypes-incomplete-types:
+
+Incomplete Types
+^^^^^^^^^^^^^^^^
+
+*Incomplete Types* are structures, unions or arrays whose members are not yet
+specified. In C, they are specified by forward declarations, which are defined
+later::
+
+ struct cell; /* forward declaration */
+
+ struct {
+ char *name;
+ struct cell *next;
+ } cell;
+
+The straightforward translation into ctypes code would be this, but it does not
+work::
+
+ >>> class cell(Structure):
+ ... _fields_ = [("name", c_char_p),
+ ... ("next", POINTER(cell))]
+ ...
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ File "<stdin>", line 2, in cell
+ NameError: name 'cell' is not defined
+ >>>
+
+because the new ``class cell`` is not available in the class statement itself.
+In ``ctypes``, we can define the ``cell`` class and set the :attr:`_fields_`
+attribute later, after the class statement::
+
+ >>> from ctypes import *
+ >>> class cell(Structure):
+ ... pass
+ ...
+ >>> cell._fields_ = [("name", c_char_p),
+ ... ("next", POINTER(cell))]
+ >>>
+
+Lets try it. We create two instances of ``cell``, and let them point to each
+other, and finally follow the pointer chain a few times::
+
+ >>> c1 = cell()
+ >>> c1.name = "foo"
+ >>> c2 = cell()
+ >>> c2.name = "bar"
+ >>> c1.next = pointer(c2)
+ >>> c2.next = pointer(c1)
+ >>> p = c1
+ >>> for i in range(8):
+ ... print p.name,
+ ... p = p.next[0]
+ ...
+ foo bar foo bar foo bar foo bar
+ >>>
+
+
+.. _ctypes-callback-functions:
+
+Callback functions
+^^^^^^^^^^^^^^^^^^
+
+``ctypes`` allows to create C callable function pointers from Python callables.
+These are sometimes called *callback functions*.
+
+First, you must create a class for the callback function, the class knows the
+calling convention, the return type, and the number and types of arguments this
+function will receive.
+
+The CFUNCTYPE factory function creates types for callback functions using the
+normal cdecl calling convention, and, on Windows, the WINFUNCTYPE factory
+function creates types for callback functions using the stdcall calling
+convention.
+
+Both of these factory functions are called with the result type as first
+argument, and the callback functions expected argument types as the remaining
+arguments.
+
+I will present an example here which uses the standard C library's :func:`qsort`
+function, this is used to sort items with the help of a callback function.
+:func:`qsort` will be used to sort an array of integers::
+
+ >>> IntArray5 = c_int * 5
+ >>> ia = IntArray5(5, 1, 7, 33, 99)
+ >>> qsort = libc.qsort
+ >>> qsort.restype = None
+ >>>
+
+:func:`qsort` must be called with a pointer to the data to sort, the number of
+items in the data array, the size of one item, and a pointer to the comparison
+function, the callback. The callback will then be called with two pointers to
+items, and it must return a negative integer if the first item is smaller than
+the second, a zero if they are equal, and a positive integer else.
+
+So our callback function receives pointers to integers, and must return an
+integer. First we create the ``type`` for the callback function::
+
+ >>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
+ >>>
+
+For the first implementation of the callback function, we simply print the
+arguments we get, and return 0 (incremental development ;-)::
+
+ >>> def py_cmp_func(a, b):
+ ... print "py_cmp_func", a, b
+ ... return 0
+ ...
+ >>>
+
+Create the C callable callback::
+
+ >>> cmp_func = CMPFUNC(py_cmp_func)
+ >>>
+
+And we're ready to go::
+
+ >>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +WINDOWS
+ py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+ py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+ py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+ py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+ py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+ py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+ py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+ py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+ py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+ py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
+ >>>
+
+We know how to access the contents of a pointer, so lets redefine our callback::
+
+ >>> def py_cmp_func(a, b):
+ ... print "py_cmp_func", a[0], b[0]
+ ... return 0
+ ...
+ >>> cmp_func = CMPFUNC(py_cmp_func)
+ >>>
+
+Here is what we get on Windows::
+
+ >>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +WINDOWS
+ py_cmp_func 7 1
+ py_cmp_func 33 1
+ py_cmp_func 99 1
+ py_cmp_func 5 1
+ py_cmp_func 7 5
+ py_cmp_func 33 5
+ py_cmp_func 99 5
+ py_cmp_func 7 99
+ py_cmp_func 33 99
+ py_cmp_func 7 33
+ >>>
+
+It is funny to see that on linux the sort function seems to work much more
+efficient, it is doing less comparisons::
+
+ >>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +LINUX
+ py_cmp_func 5 1
+ py_cmp_func 33 99
+ py_cmp_func 7 33
+ py_cmp_func 5 7
+ py_cmp_func 1 7
+ >>>
+
+Ah, we're nearly done! The last step is to actually compare the two items and
+return a useful result::
+
+ >>> def py_cmp_func(a, b):
+ ... print "py_cmp_func", a[0], b[0]
+ ... return a[0] - b[0]
+ ...
+ >>>
+
+Final run on Windows::
+
+ >>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func)) # doctest: +WINDOWS
+ py_cmp_func 33 7
+ py_cmp_func 99 33
+ py_cmp_func 5 99
+ py_cmp_func 1 99
+ py_cmp_func 33 7
+ py_cmp_func 1 33
+ py_cmp_func 5 33
+ py_cmp_func 5 7
+ py_cmp_func 1 7
+ py_cmp_func 5 1
+ >>>
+
+and on Linux::
+
+ >>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func)) # doctest: +LINUX
+ py_cmp_func 5 1
+ py_cmp_func 33 99
+ py_cmp_func 7 33
+ py_cmp_func 1 7
+ py_cmp_func 5 7
+ >>>
+
+It is quite interesting to see that the Windows :func:`qsort` function needs
+more comparisons than the linux version!
+
+As we can easily check, our array is sorted now::
+
+ >>> for i in ia: print i,
+ ...
+ 1 5 7 33 99
+ >>>
+
+**Important note for callback functions:**
+
+Make sure you keep references to CFUNCTYPE objects as long as they are used from
+C code. ``ctypes`` doesn't, and if you don't, they may be garbage collected,
+crashing your program when a callback is made.
+
+
+.. _ctypes-accessing-values-exported-from-dlls:
+
+Accessing values exported from dlls
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes, a dll not only exports functions, it also exports variables. An
+example in the Python library itself is the ``Py_OptimizeFlag``, an integer set
+to 0, 1, or 2, depending on the :option:`-O` or :option:`-OO` flag given on
+startup.
+
+``ctypes`` can access values like this with the :meth:`in_dll` class methods of
+the type. *pythonapi* is a predefined symbol giving access to the Python C
+api::
+
+ >>> opt_flag = c_int.in_dll(pythonapi, "Py_OptimizeFlag")
+ >>> print opt_flag
+ c_long(0)
+ >>>
+
+If the interpreter would have been started with :option:`-O`, the sample would
+have printed ``c_long(1)``, or ``c_long(2)`` if :option:`-OO` would have been
+specified.
+
+An extended example which also demonstrates the use of pointers accesses the
+``PyImport_FrozenModules`` pointer exported by Python.
+
+Quoting the Python docs: *This pointer is initialized to point to an array of
+"struct _frozen" records, terminated by one whose members are all NULL or zero.
+When a frozen module is imported, it is searched in this table. Third-party code
+could play tricks with this to provide a dynamically created collection of
+frozen modules.*
+
+So manipulating this pointer could even prove useful. To restrict the example
+size, we show only how this table can be read with ``ctypes``::
+
+ >>> from ctypes import *
+ >>>
+ >>> class struct_frozen(Structure):
+ ... _fields_ = [("name", c_char_p),
+ ... ("code", POINTER(c_ubyte)),
+ ... ("size", c_int)]
+ ...
+ >>>
+
+We have defined the ``struct _frozen`` data type, so we can get the pointer to
+the table::
+
+ >>> FrozenTable = POINTER(struct_frozen)
+ >>> table = FrozenTable.in_dll(pythonapi, "PyImport_FrozenModules")
+ >>>
+
+Since ``table`` is a ``pointer`` to the array of ``struct_frozen`` records, we
+can iterate over it, but we just have to make sure that our loop terminates,
+because pointers have no size. Sooner or later it would probably crash with an
+access violation or whatever, so it's better to break out of the loop when we
+hit the NULL entry::
+
+ >>> for item in table:
+ ... print item.name, item.size
+ ... if item.name is None:
+ ... break
+ ...
+ __hello__ 104
+ __phello__ -104
+ __phello__.spam 104
+ None 0
+ >>>
+
+The fact that standard Python has a frozen module and a frozen package
+(indicated by the negative size member) is not wellknown, it is only used for
+testing. Try it out with ``import __hello__`` for example.
+
+
+.. _ctypes-surprises:
+
+Surprises
+^^^^^^^^^
+
+There are some edges in ``ctypes`` where you may be expect something else than
+what actually happens.
+
+Consider the following example::
+
+ >>> from ctypes import *
+ >>> class POINT(Structure):
+ ... _fields_ = ("x", c_int), ("y", c_int)
+ ...
+ >>> class RECT(Structure):
+ ... _fields_ = ("a", POINT), ("b", POINT)
+ ...
+ >>> p1 = POINT(1, 2)
+ >>> p2 = POINT(3, 4)
+ >>> rc = RECT(p1, p2)
+ >>> print rc.a.x, rc.a.y, rc.b.x, rc.b.y
+ 1 2 3 4
+ >>> # now swap the two points
+ >>> rc.a, rc.b = rc.b, rc.a
+ >>> print rc.a.x, rc.a.y, rc.b.x, rc.b.y
+ 3 4 3 4
+ >>>
+
+Hm. We certainly expected the last statement to print ``3 4 1 2``. What
+happended? Here are the steps of the ``rc.a, rc.b = rc.b, rc.a`` line above::
+
+ >>> temp0, temp1 = rc.b, rc.a
+ >>> rc.a = temp0
+ >>> rc.b = temp1
+ >>>
+
+Note that ``temp0`` and ``temp1`` are objects still using the internal buffer of
+the ``rc`` object above. So executing ``rc.a = temp0`` copies the buffer
+contents of ``temp0`` into ``rc`` 's buffer. This, in turn, changes the
+contents of ``temp1``. So, the last assignment ``rc.b = temp1``, doesn't have
+the expected effect.
+
+Keep in mind that retrieving subobjects from Structure, Unions, and Arrays
+doesn't *copy* the subobject, instead it retrieves a wrapper object accessing
+the root-object's underlying buffer.
+
+Another example that may behave different from what one would expect is this::
+
+ >>> s = c_char_p()
+ >>> s.value = "abc def ghi"
+ >>> s.value
+ 'abc def ghi'
+ >>> s.value is s.value
+ False
+ >>>
+
+Why is it printing ``False``? ctypes instances are objects containing a memory
+block plus some descriptors accessing the contents of the memory. Storing a
+Python object in the memory block does not store the object itself, instead the
+``contents`` of the object is stored. Accessing the contents again constructs a
+new Python each time!
+
+
+.. _ctypes-variable-sized-data-types:
+
+Variable-sized data types
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``ctypes`` provides some support for variable-sized arrays and structures (this
+was added in version 0.9.9.7).
+
+The ``resize`` function can be used to resize the memory buffer of an existing
+ctypes object. The function takes the object as first argument, and the
+requested size in bytes as the second argument. The memory block cannot be made
+smaller than the natural memory block specified by the objects type, a
+``ValueError`` is raised if this is tried::
+
+ >>> short_array = (c_short * 4)()
+ >>> print sizeof(short_array)
+ 8
+ >>> resize(short_array, 4)
+ Traceback (most recent call last):
+ ...
+ ValueError: minimum size is 8
+ >>> resize(short_array, 32)
+ >>> sizeof(short_array)
+ 32
+ >>> sizeof(type(short_array))
+ 8
+ >>>
+
+This is nice and fine, but how would one access the additional elements
+contained in this array? Since the type still only knows about 4 elements, we
+get errors accessing other elements::
+
+ >>> short_array[:]
+ [0, 0, 0, 0]
+ >>> short_array[7]
+ Traceback (most recent call last):
+ ...
+ IndexError: invalid index
+ >>>
+
+Another way to use variable-sized data types with ``ctypes`` is to use the
+dynamic nature of Python, and (re-)define the data type after the required size
+is already known, on a case by case basis.
+
+
+.. _ctypes-bugs-todo-non-implemented-things:
+
+Bugs, ToDo and non-implemented things
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enumeration types are not implemented. You can do it easily yourself, using
+:class:`c_int` as the base class.
+
+``long double`` is not implemented.
+
+.. % Local Variables:
+.. % compile-command: "make.bat"
+.. % End:
+
+
+.. _ctypes-ctypes-reference:
+
+ctypes reference
+----------------
+
+
+.. _ctypes-finding-shared-libraries:
+
+Finding shared libraries
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+When programming in a compiled language, shared libraries are accessed when
+compiling/linking a program, and when the program is run.
+
+The purpose of the ``find_library`` function is to locate a library in a way
+similar to what the compiler does (on platforms with several versions of a
+shared library the most recent should be loaded), while the ctypes library
+loaders act like when a program is run, and call the runtime loader directly.
+
+The ``ctypes.util`` module provides a function which can help to determine the
+library to load.
+
+
+.. data:: find_library(name)
+ :noindex:
+
+ Try to find a library and return a pathname. *name* is the library name without
+ any prefix like *lib*, suffix like ``.so``, ``.dylib`` or version number (this
+ is the form used for the posix linker option :option:`-l`). If no library can
+ be found, returns ``None``.
+
+The exact functionality is system dependend.
+
+On Linux, ``find_library`` tries to run external programs (/sbin/ldconfig, gcc,
+and objdump) to find the library file. It returns the filename of the library
+file. Here are sone examples::
+
+ >>> from ctypes.util import find_library
+ >>> find_library("m")
+ 'libm.so.6'
+ >>> find_library("c")
+ 'libc.so.6'
+ >>> find_library("bz2")
+ 'libbz2.so.1.0'
+ >>>
+
+On OS X, ``find_library`` tries several predefined naming schemes and paths to
+locate the library, and returns a full pathname if successfull::
+
+ >>> from ctypes.util import find_library
+ >>> find_library("c")
+ '/usr/lib/libc.dylib'
+ >>> find_library("m")
+ '/usr/lib/libm.dylib'
+ >>> find_library("bz2")
+ '/usr/lib/libbz2.dylib'
+ >>> find_library("AGL")
+ '/System/Library/Frameworks/AGL.framework/AGL'
+ >>>
+
+On Windows, ``find_library`` searches along the system search path, and returns
+the full pathname, but since there is no predefined naming scheme a call like
+``find_library("c")`` will fail and return ``None``.
+
+If wrapping a shared library with ``ctypes``, it *may* be better to determine
+the shared library name at development type, and hardcode that into the wrapper
+module instead of using ``find_library`` to locate the library at runtime.
+
+
+.. _ctypes-loading-shared-libraries:
+
+Loading shared libraries
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are several ways to loaded shared libraries into the Python process. One
+way is to instantiate one of the following classes:
+
+
+.. class:: CDLL(name, mode=DEFAULT_MODE, handle=None)
+
+ Instances of this class represent loaded shared libraries. Functions in these
+ libraries use the standard C calling convention, and are assumed to return
+ ``int``.
+
+
+.. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None)
+
+ Windows only: Instances of this class represent loaded shared libraries,
+ functions in these libraries use the ``stdcall`` calling convention, and are
+ assumed to return the windows specific :class:`HRESULT` code. :class:`HRESULT`
+ values contain information specifying whether the function call failed or
+ succeeded, together with additional error code. If the return value signals a
+ failure, an :class:`WindowsError` is automatically raised.
+
+
+.. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None)
+
+ Windows only: Instances of this class represent loaded shared libraries,
+ functions in these libraries use the ``stdcall`` calling convention, and are
+ assumed to return ``int`` by default.
+
+ On Windows CE only the standard calling convention is used, for convenience the
+ :class:`WinDLL` and :class:`OleDLL` use the standard calling convention on this
+ platform.
+
+The Python GIL is released before calling any function exported by these
+libraries, and reaquired afterwards.
+
+
+.. class:: PyDLL(name, mode=DEFAULT_MODE, handle=None)
+
+ Instances of this class behave like :class:`CDLL` instances, except that the
+ Python GIL is *not* released during the function call, and after the function
+ execution the Python error flag is checked. If the error flag is set, a Python
+ exception is raised.
+
+ Thus, this is only useful to call Python C api functions directly.
+
+All these classes can be instantiated by calling them with at least one
+argument, the pathname of the shared library. If you have an existing handle to
+an already loaded shard library, it can be passed as the ``handle`` named
+parameter, otherwise the underlying platforms ``dlopen`` or :meth:`LoadLibrary`
+function is used to load the library into the process, and to get a handle to
+it.
+
+The *mode* parameter can be used to specify how the library is loaded. For
+details, consult the ``dlopen(3)`` manpage, on Windows, *mode* is ignored.
+
+
+.. data:: RTLD_GLOBAL
+ :noindex:
+
+ Flag to use as *mode* parameter. On platforms where this flag is not available,
+ it is defined as the integer zero.
+
+
+.. data:: RTLD_LOCAL
+ :noindex:
+
+ Flag to use as *mode* parameter. On platforms where this is not available, it
+ is the same as *RTLD_GLOBAL*.
+
+
+.. data:: DEFAULT_MODE
+ :noindex:
+
+ The default mode which is used to load shared libraries. On OSX 10.3, this is
+ *RTLD_GLOBAL*, otherwise it is the same as *RTLD_LOCAL*.
+
+Instances of these classes have no public methods, however :meth:`__getattr__`
+and :meth:`__getitem__` have special behaviour: functions exported by the shared
+library can be accessed as attributes of by index. Please note that both
+:meth:`__getattr__` and :meth:`__getitem__` cache their result, so calling them
+repeatedly returns the same object each time.
+
+The following public attributes are available, their name starts with an
+underscore to not clash with exported function names:
+
+
+.. attribute:: PyDLL._handle
+
+ The system handle used to access the library.
+
+
+.. attribute:: PyDLL._name
+
+ The name of the library passed in the contructor.
+
+Shared libraries can also be loaded by using one of the prefabricated objects,
+which are instances of the :class:`LibraryLoader` class, either by calling the
+:meth:`LoadLibrary` method, or by retrieving the library as attribute of the
+loader instance.
+
+
+.. class:: LibraryLoader(dlltype)
+
+ Class which loads shared libraries. ``dlltype`` should be one of the
+ :class:`CDLL`, :class:`PyDLL`, :class:`WinDLL`, or :class:`OleDLL` types.
+
+ :meth:`__getattr__` has special behaviour: It allows to load a shared library by
+ accessing it as attribute of a library loader instance. The result is cached,
+ so repeated attribute accesses return the same library each time.
+
+
+.. method:: LibraryLoader.LoadLibrary(name)
+
+ Load a shared library into the process and return it. This method always
+ returns a new instance of the library.
+
+These prefabricated library loaders are available:
+
+
+.. data:: cdll
+ :noindex:
+
+ Creates :class:`CDLL` instances.
+
+
+.. data:: windll
+ :noindex:
+
+ Windows only: Creates :class:`WinDLL` instances.
+
+
+.. data:: oledll
+ :noindex:
+
+ Windows only: Creates :class:`OleDLL` instances.
+
+
+.. data:: pydll
+ :noindex:
+
+ Creates :class:`PyDLL` instances.
+
+For accessing the C Python api directly, a ready-to-use Python shared library
+object is available:
+
+
+.. data:: pythonapi
+ :noindex:
+
+ An instance of :class:`PyDLL` that exposes Python C api functions as attributes.
+ Note that all these functions are assumed to return C ``int``, which is of
+ course not always the truth, so you have to assign the correct :attr:`restype`
+ attribute to use these functions.
+
+
+.. _ctypes-foreign-functions:
+
+Foreign functions
+^^^^^^^^^^^^^^^^^
+
+As explained in the previous section, foreign functions can be accessed as
+attributes of loaded shared libraries. The function objects created in this way
+by default accept any number of arguments, accept any ctypes data instances as
+arguments, and return the default result type specified by the library loader.
+They are instances of a private class:
+
+
+.. class:: _FuncPtr
+
+ Base class for C callable foreign functions.
+
+Instances of foreign functions are also C compatible data types; they represent
+C function pointers.
+
+This behaviour can be customized by assigning to special attributes of the
+foreign function object.
+
+
+.. attribute:: _FuncPtr.restype
+
+ Assign a ctypes type to specify the result type of the foreign function. Use
+ ``None`` for ``void`` a function not returning anything.
+
+ It is possible to assign a callable Python object that is not a ctypes type, in
+ this case the function is assumed to return a C ``int``, and the callable will
+ be called with this integer, allowing to do further processing or error
+ checking. Using this is deprecated, for more flexible postprocessing or error
+ checking use a ctypes data type as :attr:`restype` and assign a callable to the
+ :attr:`errcheck` attribute.
+
+
+.. attribute:: _FuncPtr.argtypes
+
+ Assign a tuple of ctypes types to specify the argument types that the function
+ accepts. Functions using the ``stdcall`` calling convention can only be called
+ with the same number of arguments as the length of this tuple; functions using
+ the C calling convention accept additional, unspecified arguments as well.
+
+ When a foreign function is called, each actual argument is passed to the
+ :meth:`from_param` class method of the items in the :attr:`argtypes` tuple, this
+ method allows to adapt the actual argument to an object that the foreign
+ function accepts. For example, a :class:`c_char_p` item in the :attr:`argtypes`
+ tuple will convert a unicode string passed as argument into an byte string using
+ ctypes conversion rules.
+
+ New: It is now possible to put items in argtypes which are not ctypes types, but
+ each item must have a :meth:`from_param` method which returns a value usable as
+ argument (integer, string, ctypes instance). This allows to define adapters
+ that can adapt custom objects as function parameters.
+
+
+.. attribute:: _FuncPtr.errcheck
+
+ Assign a Python function or another callable to this attribute. The callable
+ will be called with three or more arguments:
+
+
+.. function:: callable(result, func, arguments)
+ :noindex:
+
+ ``result`` is what the foreign function returns, as specified by the
+ :attr:`restype` attribute.
+
+ ``func`` is the foreign function object itself, this allows to reuse the same
+ callable object to check or postprocess the results of several functions.
+
+ ``arguments`` is a tuple containing the parameters originally passed to the
+ function call, this allows to specialize the behaviour on the arguments used.
+
+ The object that this function returns will be returned from the foreign function
+ call, but it can also check the result value and raise an exception if the
+ foreign function call failed.
+
+
+.. exception:: ArgumentError()
+
+ This exception is raised when a foreign function call cannot convert one of the
+ passed arguments.
+
+
+.. _ctypes-function-prototypes:
+
+Function prototypes
+^^^^^^^^^^^^^^^^^^^
+
+Foreign functions can also be created by instantiating function prototypes.
+Function prototypes are similar to function prototypes in C; they describe a
+function (return type, argument types, calling convention) without defining an
+implementation. The factory functions must be called with the desired result
+type and the argument types of the function.
+
+
+.. function:: CFUNCTYPE(restype, *argtypes)
+
+ The returned function prototype creates functions that use the standard C
+ calling convention. The function will release the GIL during the call.
+
+
+.. function:: WINFUNCTYPE(restype, *argtypes)
+
+ Windows only: The returned function prototype creates functions that use the
+ ``stdcall`` calling convention, except on Windows CE where :func:`WINFUNCTYPE`
+ is the same as :func:`CFUNCTYPE`. The function will release the GIL during the
+ call.
+
+
+.. function:: PYFUNCTYPE(restype, *argtypes)
+
+ The returned function prototype creates functions that use the Python calling
+ convention. The function will *not* release the GIL during the call.
+
+Function prototypes created by the factory functions can be instantiated in
+different ways, depending on the type and number of the parameters in the call.
+
+
+.. function:: prototype(address)
+ :noindex:
+
+ Returns a foreign function at the specified address.
+
+
+.. function:: prototype(callable)
+ :noindex:
+
+ Create a C callable function (a callback function) from a Python ``callable``.
+
+
+.. function:: prototype(func_spec[, paramflags])
+ :noindex:
+
+ Returns a foreign function exported by a shared library. ``func_spec`` must be a
+ 2-tuple ``(name_or_ordinal, library)``. The first item is the name of the
+ exported function as string, or the ordinal of the exported function as small
+ integer. The second item is the shared library instance.
+
+
+.. function:: prototype(vtbl_index, name[, paramflags[, iid]])
+ :noindex:
+
+ Returns a foreign function that will call a COM method. ``vtbl_index`` is the
+ index into the virtual function table, a small nonnegative integer. *name* is
+ name of the COM method. *iid* is an optional pointer to the interface identifier
+ which is used in extended error reporting.
+
+ COM methods use a special calling convention: They require a pointer to the COM
+ interface as first argument, in addition to those parameters that are specified
+ in the :attr:`argtypes` tuple.
+
+The optional *paramflags* parameter creates foreign function wrappers with much
+more functionality than the features described above.
+
+*paramflags* must be a tuple of the same length as :attr:`argtypes`.
+
+Each item in this tuple contains further information about a parameter, it must
+be a tuple containing 1, 2, or 3 items.
+
+The first item is an integer containing flags for the parameter:
+
+
+.. data:: 1
+ :noindex:
+
+ Specifies an input parameter to the function.
+
+
+.. data:: 2
+ :noindex:
+
+ Output parameter. The foreign function fills in a value.
+
+
+.. data:: 4
+ :noindex:
+
+ Input parameter which defaults to the integer zero.
+
+The optional second item is the parameter name as string. If this is specified,
+the foreign function can be called with named parameters.
+
+The optional third item is the default value for this parameter.
+
+This example demonstrates how to wrap the Windows ``MessageBoxA`` function so
+that it supports default parameters and named arguments. The C declaration from
+the windows header file is this::
+
+ WINUSERAPI int WINAPI
+ MessageBoxA(
+ HWND hWnd ,
+ LPCSTR lpText,
+ LPCSTR lpCaption,
+ UINT uType);
+
+Here is the wrapping with ``ctypes``:
+
+ ::
+
+ >>> from ctypes import c_int, WINFUNCTYPE, windll
+ >>> from ctypes.wintypes import HWND, LPCSTR, UINT
+ >>> prototype = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, UINT)
+ >>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", None), (1, "flags", 0)
+ >>> MessageBox = prototype(("MessageBoxA", windll.user32), paramflags)
+ >>>
+
+The MessageBox foreign function can now be called in these ways::
+
+ >>> MessageBox()
+ >>> MessageBox(text="Spam, spam, spam")
+ >>> MessageBox(flags=2, text="foo bar")
+ >>>
+
+A second example demonstrates output parameters. The win32 ``GetWindowRect``
+function retrieves the dimensions of a specified window by copying them into
+``RECT`` structure that the caller has to supply. Here is the C declaration::
+
+ WINUSERAPI BOOL WINAPI
+ GetWindowRect(
+ HWND hWnd,
+ LPRECT lpRect);
+
+Here is the wrapping with ``ctypes``:
+
+ ::
+
+ >>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError
+ >>> from ctypes.wintypes import BOOL, HWND, RECT
+ >>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))
+ >>> paramflags = (1, "hwnd"), (2, "lprect")
+ >>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags)
+ >>>
+
+Functions with output parameters will automatically return the output parameter
+value if there is a single one, or a tuple containing the output parameter
+values when there are more than one, so the GetWindowRect function now returns a
+RECT instance, when called.
+
+Output parameters can be combined with the :attr:`errcheck` protocol to do
+further output processing and error checking. The win32 ``GetWindowRect`` api
+function returns a ``BOOL`` to signal success or failure, so this function could
+do the error checking, and raises an exception when the api call failed::
+
+ >>> def errcheck(result, func, args):
+ ... if not result:
+ ... raise WinError()
+ ... return args
+ >>> GetWindowRect.errcheck = errcheck
+ >>>
+
+If the :attr:`errcheck` function returns the argument tuple it receives
+unchanged, ``ctypes`` continues the normal processing it does on the output
+parameters. If you want to return a tuple of window coordinates instead of a
+``RECT`` instance, you can retrieve the fields in the function and return them
+instead, the normal processing will no longer take place::
+
+ >>> def errcheck(result, func, args):
+ ... if not result:
+ ... raise WinError()
+ ... rc = args[1]
+ ... return rc.left, rc.top, rc.bottom, rc.right
+ >>>
+ >>> GetWindowRect.errcheck = errcheck
+ >>>
+
+
+.. _ctypes-utility-functions:
+
+Utility functions
+^^^^^^^^^^^^^^^^^
+
+
+.. function:: addressof(obj)
+
+ Returns the address of the memory buffer as integer. ``obj`` must be an
+ instance of a ctypes type.
+
+
+.. function:: alignment(obj_or_type)
+
+ Returns the alignment requirements of a ctypes type. ``obj_or_type`` must be a
+ ctypes type or instance.
+
+
+.. function:: byref(obj)
+
+ Returns a light-weight pointer to ``obj``, which must be an instance of a ctypes
+ type. The returned object can only be used as a foreign function call parameter.
+ It behaves similar to ``pointer(obj)``, but the construction is a lot faster.
+
+
+.. function:: cast(obj, type)
+
+ This function is similar to the cast operator in C. It returns a new instance of
+ ``type`` which points to the same memory block as ``obj``. ``type`` must be a
+ pointer type, and ``obj`` must be an object that can be interpreted as a
+ pointer.
+
+
+.. function:: create_string_buffer(init_or_size[, size])
+
+ This function creates a mutable character buffer. The returned object is a
+ ctypes array of :class:`c_char`.
+
+ ``init_or_size`` must be an integer which specifies the size of the array, or a
+ string which will be used to initialize the array items.
+
+ If a string is specified as first argument, the buffer is made one item larger
+ than the length of the string so that the last element in the array is a NUL
+ termination character. An integer can be passed as second argument which allows
+ to specify the size of the array if the length of the string should not be used.
+
+ If the first parameter is a unicode string, it is converted into an 8-bit string
+ according to ctypes conversion rules.
+
+
+.. function:: create_unicode_buffer(init_or_size[, size])
+
+ This function creates a mutable unicode character buffer. The returned object is
+ a ctypes array of :class:`c_wchar`.
+
+ ``init_or_size`` must be an integer which specifies the size of the array, or a
+ unicode string which will be used to initialize the array items.
+
+ If a unicode string is specified as first argument, the buffer is made one item
+ larger than the length of the string so that the last element in the array is a
+ NUL termination character. An integer can be passed as second argument which
+ allows to specify the size of the array if the length of the string should not
+ be used.
+
+ If the first parameter is a 8-bit string, it is converted into an unicode string
+ according to ctypes conversion rules.
+
+
+.. function:: DllCanUnloadNow()
+
+ Windows only: This function is a hook which allows to implement inprocess COM
+ servers with ctypes. It is called from the DllCanUnloadNow function that the
+ _ctypes extension dll exports.
+
+
+.. function:: DllGetClassObject()
+
+ Windows only: This function is a hook which allows to implement inprocess COM
+ servers with ctypes. It is called from the DllGetClassObject function that the
+ ``_ctypes`` extension dll exports.
+
+
+.. function:: FormatError([code])
+
+ Windows only: Returns a textual description of the error code. If no error code
+ is specified, the last error code is used by calling the Windows api function
+ GetLastError.
+
+
+.. function:: GetLastError()
+
+ Windows only: Returns the last error code set by Windows in the calling thread.
+
+
+.. function:: memmove(dst, src, count)
+
+ Same as the standard C memmove library function: copies *count* bytes from
+ ``src`` to *dst*. *dst* and ``src`` must be integers or ctypes instances that
+ can be converted to pointers.
+
+
+.. function:: memset(dst, c, count)
+
+ Same as the standard C memset library function: fills the memory block at
+ address *dst* with *count* bytes of value *c*. *dst* must be an integer
+ specifying an address, or a ctypes instance.
+
+
+.. function:: POINTER(type)
+
+ This factory function creates and returns a new ctypes pointer type. Pointer
+ types are cached an reused internally, so calling this function repeatedly is
+ cheap. type must be a ctypes type.
+
+
+.. function:: pointer(obj)
+
+ This function creates a new pointer instance, pointing to ``obj``. The returned
+ object is of the type POINTER(type(obj)).
+
+ Note: If you just want to pass a pointer to an object to a foreign function
+ call, you should use ``byref(obj)`` which is much faster.
+
+
+.. function:: resize(obj, size)
+
+ This function resizes the internal memory buffer of obj, which must be an
+ instance of a ctypes type. It is not possible to make the buffer smaller than
+ the native size of the objects type, as given by sizeof(type(obj)), but it is
+ possible to enlarge the buffer.
+
+
+.. function:: set_conversion_mode(encoding, errors)
+
+ This function sets the rules that ctypes objects use when converting between
+ 8-bit strings and unicode strings. encoding must be a string specifying an
+ encoding, like ``'utf-8'`` or ``'mbcs'``, errors must be a string specifying the
+ error handling on encoding/decoding errors. Examples of possible values are
+ ``"strict"``, ``"replace"``, or ``"ignore"``.
+
+ ``set_conversion_mode`` returns a 2-tuple containing the previous conversion
+ rules. On windows, the initial conversion rules are ``('mbcs', 'ignore')``, on
+ other systems ``('ascii', 'strict')``.
+
+
+.. function:: sizeof(obj_or_type)
+
+ Returns the size in bytes of a ctypes type or instance memory buffer. Does the
+ same as the C ``sizeof()`` function.
+
+
+.. function:: string_at(address[, size])
+
+ This function returns the string starting at memory address address. If size
+ is specified, it is used as size, otherwise the string is assumed to be
+ zero-terminated.
+
+
+.. function:: WinError(code=None, descr=None)
+
+ Windows only: this function is probably the worst-named thing in ctypes. It
+ creates an instance of WindowsError. If *code* is not specified,
+ ``GetLastError`` is called to determine the error code. If ``descr`` is not
+ spcified, :func:`FormatError` is called to get a textual description of the
+ error.
+
+
+.. function:: wstring_at(address)
+
+ This function returns the wide character string starting at memory address
+ ``address`` as unicode string. If ``size`` is specified, it is used as the
+ number of characters of the string, otherwise the string is assumed to be
+ zero-terminated.
+
+
+.. _ctypes-data-types:
+
+Data types
+^^^^^^^^^^
+
+
+.. class:: _CData
+
+ This non-public class is the common base class of all ctypes data types. Among
+ other things, all ctypes type instances contain a memory block that hold C
+ compatible data; the address of the memory block is returned by the
+ ``addressof()`` helper function. Another instance variable is exposed as
+ :attr:`_objects`; this contains other Python objects that need to be kept alive
+ in case the memory block contains pointers.
+
+Common methods of ctypes data types, these are all class methods (to be exact,
+they are methods of the metaclass):
+
+
+.. method:: _CData.from_address(address)
+
+ This method returns a ctypes type instance using the memory specified by address
+ which must be an integer.
+
+
+.. method:: _CData.from_param(obj)
+
+ This method adapts obj to a ctypes type. It is called with the actual object
+ used in a foreign function call, when the type is present in the foreign
+ functions :attr:`argtypes` tuple; it must return an object that can be used as
+ function call parameter.
+
+ All ctypes data types have a default implementation of this classmethod,
+ normally it returns ``obj`` if that is an instance of the type. Some types
+ accept other objects as well.
+
+
+.. method:: _CData.in_dll(library, name)
+
+ This method returns a ctypes type instance exported by a shared library. *name*
+ is the name of the symbol that exports the data, *library* is the loaded shared
+ library.
+
+Common instance variables of ctypes data types:
+
+
+.. attribute:: _CData._b_base_
+
+ Sometimes ctypes data instances do not own the memory block they contain,
+ instead they share part of the memory block of a base object. The
+ :attr:`_b_base_` readonly member is the root ctypes object that owns the memory
+ block.
+
+
+.. attribute:: _CData._b_needsfree_
+
+ This readonly variable is true when the ctypes data instance has allocated the
+ memory block itself, false otherwise.
+
+
+.. attribute:: _CData._objects
+
+ This member is either ``None`` or a dictionary containing Python objects that
+ need to be kept alive so that the memory block contents is kept valid. This
+ object is only exposed for debugging; never modify the contents of this
+ dictionary.
+
+
+.. _ctypes-fundamental-data-types-2:
+
+Fundamental data types
+^^^^^^^^^^^^^^^^^^^^^^
+
+
+.. class:: _SimpleCData
+
+ This non-public class is the base class of all fundamental ctypes data types. It
+ is mentioned here because it contains the common attributes of the fundamental
+ ctypes data types. ``_SimpleCData`` is a subclass of ``_CData``, so it inherits
+ their methods and attributes.
+
+Instances have a single attribute:
+
+
+.. attribute:: _SimpleCData.value
+
+ This attribute contains the actual value of the instance. For integer and
+ pointer types, it is an integer, for character types, it is a single character
+ string, for character pointer types it is a Python string or unicode string.
+
+ When the ``value`` attribute is retrieved from a ctypes instance, usually a new
+ object is returned each time. ``ctypes`` does *not* implement original object
+ return, always a new object is constructed. The same is true for all other
+ ctypes object instances.
+
+Fundamental data types, when returned as foreign function call results, or, for
+example, by retrieving structure field members or array items, are transparently
+converted to native Python types. In other words, if a foreign function has a
+:attr:`restype` of :class:`c_char_p`, you will always receive a Python string,
+*not* a :class:`c_char_p` instance.
+
+Subclasses of fundamental data types do *not* inherit this behaviour. So, if a
+foreign functions :attr:`restype` is a subclass of :class:`c_void_p`, you will
+receive an instance of this subclass from the function call. Of course, you can
+get the value of the pointer by accessing the ``value`` attribute.
+
+These are the fundamental ctypes data types:
+
+
+.. class:: c_byte
+
+ Represents the C signed char datatype, and interprets the value as small
+ integer. The constructor accepts an optional integer initializer; no overflow
+ checking is done.
+
+
+.. class:: c_char
+
+ Represents the C char datatype, and interprets the value as a single character.
+ The constructor accepts an optional string initializer, the length of the string
+ must be exactly one character.
+
+
+.. class:: c_char_p
+
+ Represents the C char \* datatype, which must be a pointer to a zero-terminated
+ string. The constructor accepts an integer address, or a string.
+
+
+.. class:: c_double
+
+ Represents the C double datatype. The constructor accepts an optional float
+ initializer.
+
+
+.. class:: c_float
+
+ Represents the C double datatype. The constructor accepts an optional float
+ initializer.
+
+
+.. class:: c_int
+
+ Represents the C signed int datatype. The constructor accepts an optional
+ integer initializer; no overflow checking is done. On platforms where
+ ``sizeof(int) == sizeof(long)`` it is an alias to :class:`c_long`.
+
+
+.. class:: c_int8
+
+ Represents the C 8-bit ``signed int`` datatype. Usually an alias for
+ :class:`c_byte`.
+
+
+.. class:: c_int16
+
+ Represents the C 16-bit signed int datatype. Usually an alias for
+ :class:`c_short`.
+
+
+.. class:: c_int32
+
+ Represents the C 32-bit signed int datatype. Usually an alias for
+ :class:`c_int`.
+
+
+.. class:: c_int64
+
+ Represents the C 64-bit ``signed int`` datatype. Usually an alias for
+ :class:`c_longlong`.
+
+
+.. class:: c_long
+
+ Represents the C ``signed long`` datatype. The constructor accepts an optional
+ integer initializer; no overflow checking is done.
+
+
+.. class:: c_longlong
+
+ Represents the C ``signed long long`` datatype. The constructor accepts an
+ optional integer initializer; no overflow checking is done.
+
+
+.. class:: c_short
+
+ Represents the C ``signed short`` datatype. The constructor accepts an optional
+ integer initializer; no overflow checking is done.
+
+
+.. class:: c_size_t
+
+ Represents the C ``size_t`` datatype.
+
+
+.. class:: c_ubyte
+
+ Represents the C ``unsigned char`` datatype, it interprets the value as small
+ integer. The constructor accepts an optional integer initializer; no overflow
+ checking is done.
+
+
+.. class:: c_uint
+
+ Represents the C ``unsigned int`` datatype. The constructor accepts an optional
+ integer initializer; no overflow checking is done. On platforms where
+ ``sizeof(int) == sizeof(long)`` it is an alias for :class:`c_ulong`.
+
+
+.. class:: c_uint8
+
+ Represents the C 8-bit unsigned int datatype. Usually an alias for
+ :class:`c_ubyte`.
+
+
+.. class:: c_uint16
+
+ Represents the C 16-bit unsigned int datatype. Usually an alias for
+ :class:`c_ushort`.
+
+
+.. class:: c_uint32
+
+ Represents the C 32-bit unsigned int datatype. Usually an alias for
+ :class:`c_uint`.
+
+
+.. class:: c_uint64
+
+ Represents the C 64-bit unsigned int datatype. Usually an alias for
+ :class:`c_ulonglong`.
+
+
+.. class:: c_ulong
+
+ Represents the C ``unsigned long`` datatype. The constructor accepts an optional
+ integer initializer; no overflow checking is done.
+
+
+.. class:: c_ulonglong
+
+ Represents the C ``unsigned long long`` datatype. The constructor accepts an
+ optional integer initializer; no overflow checking is done.
+
+
+.. class:: c_ushort
+
+ Represents the C ``unsigned short`` datatype. The constructor accepts an
+ optional integer initializer; no overflow checking is done.
+
+
+.. class:: c_void_p
+
+ Represents the C ``void *`` type. The value is represented as integer. The
+ constructor accepts an optional integer initializer.
+
+
+.. class:: c_wchar
+
+ Represents the C ``wchar_t`` datatype, and interprets the value as a single
+ character unicode string. The constructor accepts an optional string
+ initializer, the length of the string must be exactly one character.
+
+
+.. class:: c_wchar_p
+
+ Represents the C ``wchar_t *`` datatype, which must be a pointer to a
+ zero-terminated wide character string. The constructor accepts an integer
+ address, or a string.
+
+
+.. class:: c_bool
+
+ Represent the C ``bool`` datatype (more accurately, _Bool from C99). Its value
+ can be True or False, and the constructor accepts any object that has a truth
+ value.
+
+ .. versionadded:: 2.6
+
+
+.. class:: HRESULT
+
+ Windows only: Represents a :class:`HRESULT` value, which contains success or
+ error information for a function or method call.
+
+
+.. class:: py_object
+
+ Represents the C ``PyObject *`` datatype. Calling this without an argument
+ creates a ``NULL`` ``PyObject *`` pointer.
+
+The ``ctypes.wintypes`` module provides quite some other Windows specific data
+types, for example ``HWND``, ``WPARAM``, or ``DWORD``. Some useful structures
+like ``MSG`` or ``RECT`` are also defined.
+
+
+.. _ctypes-structured-data-types:
+
+Structured data types
+^^^^^^^^^^^^^^^^^^^^^
+
+
+.. class:: Union(*args, **kw)
+
+ Abstract base class for unions in native byte order.
+
+
+.. class:: BigEndianStructure(*args, **kw)
+
+ Abstract base class for structures in *big endian* byte order.
+
+
+.. class:: LittleEndianStructure(*args, **kw)
+
+ Abstract base class for structures in *little endian* byte order.
+
+Structures with non-native byte order cannot contain pointer type fields, or any
+other data types containing pointer type fields.
+
+
+.. class:: Structure(*args, **kw)
+
+ Abstract base class for structures in *native* byte order.
+
+Concrete structure and union types must be created by subclassing one of these
+types, and at least define a :attr:`_fields_` class variable. ``ctypes`` will
+create descriptors which allow reading and writing the fields by direct
+attribute accesses. These are the
+
+
+.. attribute:: Structure._fields_
+
+ A sequence defining the structure fields. The items must be 2-tuples or
+ 3-tuples. The first item is the name of the field, the second item specifies
+ the type of the field; it can be any ctypes data type.
+
+ For integer type fields like :class:`c_int`, a third optional item can be given.
+ It must be a small positive integer defining the bit width of the field.
+
+ Field names must be unique within one structure or union. This is not checked,
+ only one field can be accessed when names are repeated.
+
+ It is possible to define the :attr:`_fields_` class variable *after* the class
+ statement that defines the Structure subclass, this allows to create data types
+ that directly or indirectly reference themselves::
+
+ class List(Structure):
+ pass
+ List._fields_ = [("pnext", POINTER(List)),
+ ...
+ ]
+
+ The :attr:`_fields_` class variable must, however, be defined before the type is
+ first used (an instance is created, ``sizeof()`` is called on it, and so on).
+ Later assignments to the :attr:`_fields_` class variable will raise an
+ AttributeError.
+
+ Structure and union subclass constructors accept both positional and named
+ arguments. Positional arguments are used to initialize the fields in the same
+ order as they appear in the :attr:`_fields_` definition, named arguments are
+ used to initialize the fields with the corresponding name.
+
+ It is possible to defined sub-subclasses of structure types, they inherit the
+ fields of the base class plus the :attr:`_fields_` defined in the sub-subclass,
+ if any.
+
+
+.. attribute:: Structure._pack_
+
+ An optional small integer that allows to override the alignment of structure
+ fields in the instance. :attr:`_pack_` must already be defined when
+ :attr:`_fields_` is assigned, otherwise it will have no effect.
+
+
+.. attribute:: Structure._anonymous_
+
+ An optional sequence that lists the names of unnamed (anonymous) fields.
+ ``_anonymous_`` must be already defined when :attr:`_fields_` is assigned,
+ otherwise it will have no effect.
+
+ The fields listed in this variable must be structure or union type fields.
+ ``ctypes`` will create descriptors in the structure type that allows to access
+ the nested fields directly, without the need to create the structure or union
+ field.
+
+ Here is an example type (Windows)::
+
+ class _U(Union):
+ _fields_ = [("lptdesc", POINTER(TYPEDESC)),
+ ("lpadesc", POINTER(ARRAYDESC)),
+ ("hreftype", HREFTYPE)]
+
+ class TYPEDESC(Structure):
+ _fields_ = [("u", _U),
+ ("vt", VARTYPE)]
+
+ _anonymous_ = ("u",)
+
+ The ``TYPEDESC`` structure describes a COM data type, the ``vt`` field specifies
+ which one of the union fields is valid. Since the ``u`` field is defined as
+ anonymous field, it is now possible to access the members directly off the
+ TYPEDESC instance. ``td.lptdesc`` and ``td.u.lptdesc`` are equivalent, but the
+ former is faster since it does not need to create a temporary union instance::
+
+ td = TYPEDESC()
+ td.vt = VT_PTR
+ td.lptdesc = POINTER(some_type)
+ td.u.lptdesc = POINTER(some_type)
+
+It is possible to defined sub-subclasses of structures, they inherit the fields
+of the base class. If the subclass definition has a separate :attr:`_fields_`
+variable, the fields specified in this are appended to the fields of the base
+class.
+
+Structure and union constructors accept both positional and keyword arguments.
+Positional arguments are used to initialize member fields in the same order as
+they are appear in :attr:`_fields_`. Keyword arguments in the constructor are
+interpreted as attribute assignments, so they will initialize :attr:`_fields_`
+with the same name, or create new attributes for names not present in
+:attr:`_fields_`.
+
+
+.. _ctypes-arrays-pointers:
+
+Arrays and pointers
+^^^^^^^^^^^^^^^^^^^
+
+Not yet written - please see the sections :ref:`ctypes-pointers` and
+section :ref:`ctypes-arrays` in the tutorial.
+
--- /dev/null
+
+:mod:`curses.ascii` --- Utilities for ASCII characters
+======================================================
+
+.. module:: curses.ascii
+ :synopsis: Constants and set-membership functions for ASCII characters.
+.. moduleauthor:: Eric S. Raymond <esr@thyrsus.com>
+.. sectionauthor:: Eric S. Raymond <esr@thyrsus.com>
+
+
+.. versionadded:: 1.6
+
+The :mod:`curses.ascii` module supplies name constants for ASCII characters and
+functions to test membership in various ASCII character classes. The constants
+supplied are names for control characters as follows:
+
++--------------+----------------------------------------------+
+| Name | Meaning |
++==============+==============================================+
+| :const:`NUL` | |
++--------------+----------------------------------------------+
+| :const:`SOH` | Start of heading, console interrupt |
++--------------+----------------------------------------------+
+| :const:`STX` | Start of text |
++--------------+----------------------------------------------+
+| :const:`ETX` | End of text |
++--------------+----------------------------------------------+
+| :const:`EOT` | End of transmission |
++--------------+----------------------------------------------+
+| :const:`ENQ` | Enquiry, goes with :const:`ACK` flow control |
++--------------+----------------------------------------------+
+| :const:`ACK` | Acknowledgement |
++--------------+----------------------------------------------+
+| :const:`BEL` | Bell |
++--------------+----------------------------------------------+
+| :const:`BS` | Backspace |
++--------------+----------------------------------------------+
+| :const:`TAB` | Tab |
++--------------+----------------------------------------------+
+| :const:`HT` | Alias for :const:`TAB`: "Horizontal tab" |
++--------------+----------------------------------------------+
+| :const:`LF` | Line feed |
++--------------+----------------------------------------------+
+| :const:`NL` | Alias for :const:`LF`: "New line" |
++--------------+----------------------------------------------+
+| :const:`VT` | Vertical tab |
++--------------+----------------------------------------------+
+| :const:`FF` | Form feed |
++--------------+----------------------------------------------+
+| :const:`CR` | Carriage return |
++--------------+----------------------------------------------+
+| :const:`SO` | Shift-out, begin alternate character set |
++--------------+----------------------------------------------+
+| :const:`SI` | Shift-in, resume default character set |
++--------------+----------------------------------------------+
+| :const:`DLE` | Data-link escape |
++--------------+----------------------------------------------+
+| :const:`DC1` | XON, for flow control |
++--------------+----------------------------------------------+
+| :const:`DC2` | Device control 2, block-mode flow control |
++--------------+----------------------------------------------+
+| :const:`DC3` | XOFF, for flow control |
++--------------+----------------------------------------------+
+| :const:`DC4` | Device control 4 |
++--------------+----------------------------------------------+
+| :const:`NAK` | Negative acknowledgement |
++--------------+----------------------------------------------+
+| :const:`SYN` | Synchronous idle |
++--------------+----------------------------------------------+
+| :const:`ETB` | End transmission block |
++--------------+----------------------------------------------+
+| :const:`CAN` | Cancel |
++--------------+----------------------------------------------+
+| :const:`EM` | End of medium |
++--------------+----------------------------------------------+
+| :const:`SUB` | Substitute |
++--------------+----------------------------------------------+
+| :const:`ESC` | Escape |
++--------------+----------------------------------------------+
+| :const:`FS` | File separator |
++--------------+----------------------------------------------+
+| :const:`GS` | Group separator |
++--------------+----------------------------------------------+
+| :const:`RS` | Record separator, block-mode terminator |
++--------------+----------------------------------------------+
+| :const:`US` | Unit separator |
++--------------+----------------------------------------------+
+| :const:`SP` | Space |
++--------------+----------------------------------------------+
+| :const:`DEL` | Delete |
++--------------+----------------------------------------------+
+
+Note that many of these have little practical significance in modern usage. The
+mnemonics derive from teleprinter conventions that predate digital computers.
+
+The module supplies the following functions, patterned on those in the standard
+C library:
+
+
+.. function:: isalnum(c)
+
+ Checks for an ASCII alphanumeric character; it is equivalent to ``isalpha(c) or
+ isdigit(c)``.
+
+
+.. function:: isalpha(c)
+
+ Checks for an ASCII alphabetic character; it is equivalent to ``isupper(c) or
+ islower(c)``.
+
+
+.. function:: isascii(c)
+
+ Checks for a character value that fits in the 7-bit ASCII set.
+
+
+.. function:: isblank(c)
+
+ Checks for an ASCII whitespace character.
+
+
+.. function:: iscntrl(c)
+
+ Checks for an ASCII control character (in the range 0x00 to 0x1f).
+
+
+.. function:: isdigit(c)
+
+ Checks for an ASCII decimal digit, ``'0'`` through ``'9'``. This is equivalent
+ to ``c in string.digits``.
+
+
+.. function:: isgraph(c)
+
+ Checks for ASCII any printable character except space.
+
+
+.. function:: islower(c)
+
+ Checks for an ASCII lower-case character.
+
+
+.. function:: isprint(c)
+
+ Checks for any ASCII printable character including space.
+
+
+.. function:: ispunct(c)
+
+ Checks for any printable ASCII character which is not a space or an alphanumeric
+ character.
+
+
+.. function:: isspace(c)
+
+ Checks for ASCII white-space characters; space, line feed, carriage return, form
+ feed, horizontal tab, vertical tab.
+
+
+.. function:: isupper(c)
+
+ Checks for an ASCII uppercase letter.
+
+
+.. function:: isxdigit(c)
+
+ Checks for an ASCII hexadecimal digit. This is equivalent to ``c in
+ string.hexdigits``.
+
+
+.. function:: isctrl(c)
+
+ Checks for an ASCII control character (ordinal values 0 to 31).
+
+
+.. function:: ismeta(c)
+
+ Checks for a non-ASCII character (ordinal values 0x80 and above).
+
+These functions accept either integers or strings; when the argument is a
+string, it is first converted using the built-in function :func:`ord`.
+
+Note that all these functions check ordinal bit values derived from the first
+character of the string you pass in; they do not actually know anything about
+the host machine's character encoding. For functions that know about the
+character encoding (and handle internationalization properly) see the
+:mod:`string` module.
+
+The following two functions take either a single-character string or integer
+byte value; they return a value of the same type.
+
+
+.. function:: ascii(c)
+
+ Return the ASCII value corresponding to the low 7 bits of *c*.
+
+
+.. function:: ctrl(c)
+
+ Return the control character corresponding to the given character (the character
+ bit value is bitwise-anded with 0x1f).
+
+
+.. function:: alt(c)
+
+ Return the 8-bit character corresponding to the given ASCII character (the
+ character bit value is bitwise-ored with 0x80).
+
+The following function takes either a single-character string or integer value;
+it returns a string.
+
+
+.. function:: unctrl(c)
+
+ Return a string representation of the ASCII character *c*. If *c* is printable,
+ this string is the character itself. If the character is a control character
+ (0x00-0x1f) the string consists of a caret (``'^'``) followed by the
+ corresponding uppercase letter. If the character is an ASCII delete (0x7f) the
+ string is ``'^?'``. If the character has its meta bit (0x80) set, the meta bit
+ is stripped, the preceding rules applied, and ``'!'`` prepended to the result.
+
+
+.. data:: controlnames
+
+ A 33-element string array that contains the ASCII mnemonics for the thirty-two
+ ASCII control characters from 0 (NUL) to 0x1f (US), in order, plus the mnemonic
+ ``SP`` for the space character.
+
--- /dev/null
+
+:mod:`curses.panel` --- A panel stack extension for curses.
+===========================================================
+
+.. module:: curses.panel
+ :synopsis: A panel stack extension that adds depth to curses windows.
+.. sectionauthor:: A.M. Kuchling <amk@amk.ca>
+
+
+Panels are windows with the added feature of depth, so they can be stacked on
+top of each other, and only the visible portions of each window will be
+displayed. Panels can be added, moved up or down in the stack, and removed.
+
+
+.. _cursespanel-functions:
+
+Functions
+---------
+
+The module :mod:`curses.panel` defines the following functions:
+
+
+.. function:: bottom_panel()
+
+ Returns the bottom panel in the panel stack.
+
+
+.. function:: new_panel(win)
+
+ Returns a panel object, associating it with the given window *win*. Be aware
+ that you need to keep the returned panel object referenced explicitly. If you
+ don't, the panel object is garbage collected and removed from the panel stack.
+
+
+.. function:: top_panel()
+
+ Returns the top panel in the panel stack.
+
+
+.. function:: update_panels()
+
+ Updates the virtual screen after changes in the panel stack. This does not call
+ :func:`curses.doupdate`, so you'll have to do this yourself.
+
+
+.. _curses-panel-objects:
+
+Panel Objects
+-------------
+
+Panel objects, as returned by :func:`new_panel` above, are windows with a
+stacking order. There's always a window associated with a panel which determines
+the content, while the panel methods are responsible for the window's depth in
+the panel stack.
+
+Panel objects have the following methods:
+
+
+.. method:: Panel.above()
+
+ Returns the panel above the current panel.
+
+
+.. method:: Panel.below()
+
+ Returns the panel below the current panel.
+
+
+.. method:: Panel.bottom()
+
+ Push the panel to the bottom of the stack.
+
+
+.. method:: Panel.hidden()
+
+ Returns true if the panel is hidden (not visible), false otherwise.
+
+
+.. method:: Panel.hide()
+
+ Hide the panel. This does not delete the object, it just makes the window on
+ screen invisible.
+
+
+.. method:: Panel.move(y, x)
+
+ Move the panel to the screen coordinates ``(y, x)``.
+
+
+.. method:: Panel.replace(win)
+
+ Change the window associated with the panel to the window *win*.
+
+
+.. method:: Panel.set_userptr(obj)
+
+ Set the panel's user pointer to *obj*. This is used to associate an arbitrary
+ piece of data with the panel, and can be any Python object.
+
+
+.. method:: Panel.show()
+
+ Display the panel (which might have been hidden).
+
+
+.. method:: Panel.top()
+
+ Push panel to the top of the stack.
+
+
+.. method:: Panel.userptr()
+
+ Returns the user pointer for the panel. This might be any Python object.
+
+
+.. method:: Panel.window()
+
+ Returns the window object associated with the panel.
+
--- /dev/null
+
+:mod:`curses` --- Terminal handling for character-cell displays
+===============================================================
+
+.. module:: curses
+ :synopsis: An interface to the curses library, providing portable terminal handling.
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+.. sectionauthor:: Eric Raymond <esr@thyrsus.com>
+
+
+.. versionchanged:: 1.6
+ Added support for the ``ncurses`` library and converted to a package.
+
+The :mod:`curses` module provides an interface to the curses library, the
+de-facto standard for portable advanced terminal handling.
+
+While curses is most widely used in the Unix environment, versions are available
+for DOS, OS/2, and possibly other systems as well. This extension module is
+designed to match the API of ncurses, an open-source curses library hosted on
+Linux and the BSD variants of Unix.
+
+
+.. seealso::
+
+ Module :mod:`curses.ascii`
+ Utilities for working with ASCII characters, regardless of your locale settings.
+
+ Module :mod:`curses.panel`
+ A panel stack extension that adds depth to curses windows.
+
+ Module :mod:`curses.textpad`
+ Editable text widget for curses supporting :program:`Emacs`\ -like bindings.
+
+ Module :mod:`curses.wrapper`
+ Convenience function to ensure proper terminal setup and resetting on
+ application entry and exit.
+
+ `Curses Programming with Python <http://www.python.org/doc/howto/curses/curses.html>`_
+ Tutorial material on using curses with Python, by Andrew Kuchling and Eric
+ Raymond, is available on the Python Web site.
+
+ The :file:`Demo/curses/` directory in the Python source distribution contains
+ some example programs using the curses bindings provided by this module.
+
+
+.. _curses-functions:
+
+Functions
+---------
+
+The module :mod:`curses` defines the following exception:
+
+
+.. exception:: error
+
+ Exception raised when a curses library function returns an error.
+
+.. note::
+
+ Whenever *x* or *y* arguments to a function or a method are optional, they
+ default to the current cursor location. Whenever *attr* is optional, it defaults
+ to :const:`A_NORMAL`.
+
+The module :mod:`curses` defines the following functions:
+
+
+.. function:: baudrate()
+
+ Returns the output speed of the terminal in bits per second. On software
+ terminal emulators it will have a fixed high value. Included for historical
+ reasons; in former times, it was used to write output loops for time delays and
+ occasionally to change interfaces depending on the line speed.
+
+
+.. function:: beep()
+
+ Emit a short attention sound.
+
+
+.. function:: can_change_color()
+
+ Returns true or false, depending on whether the programmer can change the colors
+ displayed by the terminal.
+
+
+.. function:: cbreak()
+
+ Enter cbreak mode. In cbreak mode (sometimes called "rare" mode) normal tty
+ line buffering is turned off and characters are available to be read one by one.
+ However, unlike raw mode, special characters (interrupt, quit, suspend, and flow
+ control) retain their effects on the tty driver and calling program. Calling
+ first :func:`raw` then :func:`cbreak` leaves the terminal in cbreak mode.
+
+
+.. function:: color_content(color_number)
+
+ Returns the intensity of the red, green, and blue (RGB) components in the color
+ *color_number*, which must be between ``0`` and :const:`COLORS`. A 3-tuple is
+ returned, containing the R,G,B values for the given color, which will be between
+ ``0`` (no component) and ``1000`` (maximum amount of component).
+
+
+.. function:: color_pair(color_number)
+
+ Returns the attribute value for displaying text in the specified color. This
+ attribute value can be combined with :const:`A_STANDOUT`, :const:`A_REVERSE`,
+ and the other :const:`A_\*` attributes. :func:`pair_number` is the counterpart
+ to this function.
+
+
+.. function:: curs_set(visibility)
+
+ Sets the cursor state. *visibility* can be set to 0, 1, or 2, for invisible,
+ normal, or very visible. If the terminal supports the visibility requested, the
+ previous cursor state is returned; otherwise, an exception is raised. On many
+ terminals, the "visible" mode is an underline cursor and the "very visible" mode
+ is a block cursor.
+
+
+.. function:: def_prog_mode()
+
+ Saves the current terminal mode as the "program" mode, the mode when the running
+ program is using curses. (Its counterpart is the "shell" mode, for when the
+ program is not in curses.) Subsequent calls to :func:`reset_prog_mode` will
+ restore this mode.
+
+
+.. function:: def_shell_mode()
+
+ Saves the current terminal mode as the "shell" mode, the mode when the running
+ program is not using curses. (Its counterpart is the "program" mode, when the
+ program is using curses capabilities.) Subsequent calls to
+ :func:`reset_shell_mode` will restore this mode.
+
+
+.. function:: delay_output(ms)
+
+ Inserts an *ms* millisecond pause in output.
+
+
+.. function:: doupdate()
+
+ Update the physical screen. The curses library keeps two data structures, one
+ representing the current physical screen contents and a virtual screen
+ representing the desired next state. The :func:`doupdate` ground updates the
+ physical screen to match the virtual screen.
+
+ The virtual screen may be updated by a :meth:`noutrefresh` call after write
+ operations such as :meth:`addstr` have been performed on a window. The normal
+ :meth:`refresh` call is simply :meth:`noutrefresh` followed by :func:`doupdate`;
+ if you have to update multiple windows, you can speed performance and perhaps
+ reduce screen flicker by issuing :meth:`noutrefresh` calls on all windows,
+ followed by a single :func:`doupdate`.
+
+
+.. function:: echo()
+
+ Enter echo mode. In echo mode, each character input is echoed to the screen as
+ it is entered.
+
+
+.. function:: endwin()
+
+ De-initialize the library, and return terminal to normal status.
+
+
+.. function:: erasechar()
+
+ Returns the user's current erase character. Under Unix operating systems this
+ is a property of the controlling tty of the curses program, and is not set by
+ the curses library itself.
+
+
+.. function:: filter()
+
+ The :func:`filter` routine, if used, must be called before :func:`initscr` is
+ called. The effect is that, during those calls, LINES is set to 1; the
+ capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home
+ string is set to the value of cr. The effect is that the cursor is confined to
+ the current line, and so are screen updates. This may be used for enabling
+ character-at-a-time line editing without touching the rest of the screen.
+
+
+.. function:: flash()
+
+ Flash the screen. That is, change it to reverse-video and then change it back
+ in a short interval. Some people prefer such as 'visible bell' to the audible
+ attention signal produced by :func:`beep`.
+
+
+.. function:: flushinp()
+
+ Flush all input buffers. This throws away any typeahead that has been typed
+ by the user and has not yet been processed by the program.
+
+
+.. function:: getmouse()
+
+ After :meth:`getch` returns :const:`KEY_MOUSE` to signal a mouse event, this
+ method should be call to retrieve the queued mouse event, represented as a
+ 5-tuple ``(id, x, y, z, bstate)``. *id* is an ID value used to distinguish
+ multiple devices, and *x*, *y*, *z* are the event's coordinates. (*z* is
+ currently unused.). *bstate* is an integer value whose bits will be set to
+ indicate the type of event, and will be the bitwise OR of one or more of the
+ following constants, where *n* is the button number from 1 to 4:
+ :const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:`BUTTONn_CLICKED`,
+ :const:`BUTTONn_DOUBLE_CLICKED`, :const:`BUTTONn_TRIPLE_CLICKED`,
+ :const:`BUTTON_SHIFT`, :const:`BUTTON_CTRL`, :const:`BUTTON_ALT`.
+
+
+.. function:: getsyx()
+
+ Returns the current coordinates of the virtual screen cursor in y and x. If
+ leaveok is currently true, then -1,-1 is returned.
+
+
+.. function:: getwin(file)
+
+ Reads window related data stored in the file by an earlier :func:`putwin` call.
+ The routine then creates and initializes a new window using that data, returning
+ the new window object.
+
+
+.. function:: has_colors()
+
+ Returns true if the terminal can display colors; otherwise, it returns false.
+
+
+.. function:: has_ic()
+
+ Returns true if the terminal has insert- and delete- character capabilities.
+ This function is included for historical reasons only, as all modern software
+ terminal emulators have such capabilities.
+
+
+.. function:: has_il()
+
+ Returns true if the terminal has insert- and delete-line capabilities, or can
+ simulate them using scrolling regions. This function is included for
+ historical reasons only, as all modern software terminal emulators have such
+ capabilities.
+
+
+.. function:: has_key(ch)
+
+ Takes a key value *ch*, and returns true if the current terminal type recognizes
+ a key with that value.
+
+
+.. function:: halfdelay(tenths)
+
+ Used for half-delay mode, which is similar to cbreak mode in that characters
+ typed by the user are immediately available to the program. However, after
+ blocking for *tenths* tenths of seconds, an exception is raised if nothing has
+ been typed. The value of *tenths* must be a number between 1 and 255. Use
+ :func:`nocbreak` to leave half-delay mode.
+
+
+.. function:: init_color(color_number, r, g, b)
+
+ Changes the definition of a color, taking the number of the color to be changed
+ followed by three RGB values (for the amounts of red, green, and blue
+ components). The value of *color_number* must be between ``0`` and
+ :const:`COLORS`. Each of *r*, *g*, *b*, must be a value between ``0`` and
+ ``1000``. When :func:`init_color` is used, all occurrences of that color on the
+ screen immediately change to the new definition. This function is a no-op on
+ most terminals; it is active only if :func:`can_change_color` returns ``1``.
+
+
+.. function:: init_pair(pair_number, fg, bg)
+
+ Changes the definition of a color-pair. It takes three arguments: the number of
+ the color-pair to be changed, the foreground color number, and the background
+ color number. The value of *pair_number* must be between ``1`` and
+ ``COLOR_PAIRS - 1`` (the ``0`` color pair is wired to white on black and cannot
+ be changed). The value of *fg* and *bg* arguments must be between ``0`` and
+ :const:`COLORS`. If the color-pair was previously initialized, the screen is
+ refreshed and all occurrences of that color-pair are changed to the new
+ definition.
+
+
+.. function:: initscr()
+
+ Initialize the library. Returns a :class:`WindowObject` which represents the
+ whole screen.
+
+ .. note::
+
+ If there is an error opening the terminal, the underlying curses library may
+ cause the interpreter to exit.
+
+
+.. function:: isendwin()
+
+ Returns true if :func:`endwin` has been called (that is, the curses library has
+ been deinitialized).
+
+
+.. function:: keyname(k)
+
+ Return the name of the key numbered *k*. The name of a key generating printable
+ ASCII character is the key's character. The name of a control-key combination
+ is a two-character string consisting of a caret followed by the corresponding
+ printable ASCII character. The name of an alt-key combination (128-255) is a
+ string consisting of the prefix 'M-' followed by the name of the corresponding
+ ASCII character.
+
+
+.. function:: killchar()
+
+ Returns the user's current line kill character. Under Unix operating systems
+ this is a property of the controlling tty of the curses program, and is not set
+ by the curses library itself.
+
+
+.. function:: longname()
+
+ Returns a string containing the terminfo long name field describing the current
+ terminal. The maximum length of a verbose description is 128 characters. It is
+ defined only after the call to :func:`initscr`.
+
+
+.. function:: meta(yes)
+
+ If *yes* is 1, allow 8-bit characters to be input. If *yes* is 0, allow only
+ 7-bit chars.
+
+
+.. function:: mouseinterval(interval)
+
+ Sets the maximum time in milliseconds that can elapse between press and release
+ events in order for them to be recognized as a click, and returns the previous
+ interval value. The default value is 200 msec, or one fifth of a second.
+
+
+.. function:: mousemask(mousemask)
+
+ Sets the mouse events to be reported, and returns a tuple ``(availmask,
+ oldmask)``. *availmask* indicates which of the specified mouse events can be
+ reported; on complete failure it returns 0. *oldmask* is the previous value of
+ the given window's mouse event mask. If this function is never called, no mouse
+ events are ever reported.
+
+
+.. function:: napms(ms)
+
+ Sleep for *ms* milliseconds.
+
+
+.. function:: newpad(nlines, ncols)
+
+ Creates and returns a pointer to a new pad data structure with the given number
+ of lines and columns. A pad is returned as a window object.
+
+ A pad is like a window, except that it is not restricted by the screen size, and
+ is not necessarily associated with a particular part of the screen. Pads can be
+ used when a large window is needed, and only a part of the window will be on the
+ screen at one time. Automatic refreshes of pads (such as from scrolling or
+ echoing of input) do not occur. The :meth:`refresh` and :meth:`noutrefresh`
+ methods of a pad require 6 arguments to specify the part of the pad to be
+ displayed and the location on the screen to be used for the display. The
+ arguments are pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol; the p
+ arguments refer to the upper left corner of the pad region to be displayed and
+ the s arguments define a clipping box on the screen within which the pad region
+ is to be displayed.
+
+
+.. function:: newwin([nlines, ncols,] begin_y, begin_x)
+
+ Return a new window, whose left-upper corner is at ``(begin_y, begin_x)``, and
+ whose height/width is *nlines*/*ncols*.
+
+ By default, the window will extend from the specified position to the lower
+ right corner of the screen.
+
+
+.. function:: nl()
+
+ Enter newline mode. This mode translates the return key into newline on input,
+ and translates newline into return and line-feed on output. Newline mode is
+ initially on.
+
+
+.. function:: nocbreak()
+
+ Leave cbreak mode. Return to normal "cooked" mode with line buffering.
+
+
+.. function:: noecho()
+
+ Leave echo mode. Echoing of input characters is turned off.
+
+
+.. function:: nonl()
+
+ Leave newline mode. Disable translation of return into newline on input, and
+ disable low-level translation of newline into newline/return on output (but this
+ does not change the behavior of ``addch('\n')``, which always does the
+ equivalent of return and line feed on the virtual screen). With translation
+ off, curses can sometimes speed up vertical motion a little; also, it will be
+ able to detect the return key on input.
+
+
+.. function:: noqiflush()
+
+ When the noqiflush routine is used, normal flush of input and output queues
+ associated with the INTR, QUIT and SUSP characters will not be done. You may
+ want to call :func:`noqiflush` in a signal handler if you want output to
+ continue as though the interrupt had not occurred, after the handler exits.
+
+
+.. function:: noraw()
+
+ Leave raw mode. Return to normal "cooked" mode with line buffering.
+
+
+.. function:: pair_content(pair_number)
+
+ Returns a tuple ``(fg, bg)`` containing the colors for the requested color pair.
+ The value of *pair_number* must be between ``1`` and ``COLOR_PAIRS - 1``.
+
+
+.. function:: pair_number(attr)
+
+ Returns the number of the color-pair set by the attribute value *attr*.
+ :func:`color_pair` is the counterpart to this function.
+
+
+.. function:: putp(string)
+
+ Equivalent to ``tputs(str, 1, putchar)``; emits the value of a specified
+ terminfo capability for the current terminal. Note that the output of putp
+ always goes to standard output.
+
+
+.. function:: qiflush( [flag] )
+
+ If *flag* is false, the effect is the same as calling :func:`noqiflush`. If
+ *flag* is true, or no argument is provided, the queues will be flushed when
+ these control characters are read.
+
+
+.. function:: raw()
+
+ Enter raw mode. In raw mode, normal line buffering and processing of
+ interrupt, quit, suspend, and flow control keys are turned off; characters are
+ presented to curses input functions one by one.
+
+
+.. function:: reset_prog_mode()
+
+ Restores the terminal to "program" mode, as previously saved by
+ :func:`def_prog_mode`.
+
+
+.. function:: reset_shell_mode()
+
+ Restores the terminal to "shell" mode, as previously saved by
+ :func:`def_shell_mode`.
+
+
+.. function:: setsyx(y, x)
+
+ Sets the virtual screen cursor to *y*, *x*. If *y* and *x* are both -1, then
+ leaveok is set.
+
+
+.. function:: setupterm([termstr, fd])
+
+ Initializes the terminal. *termstr* is a string giving the terminal name; if
+ omitted, the value of the TERM environment variable will be used. *fd* is the
+ file descriptor to which any initialization sequences will be sent; if not
+ supplied, the file descriptor for ``sys.stdout`` will be used.
+
+
+.. function:: start_color()
+
+ Must be called if the programmer wants to use colors, and before any other color
+ manipulation routine is called. It is good practice to call this routine right
+ after :func:`initscr`.
+
+ :func:`start_color` initializes eight basic colors (black, red, green, yellow,
+ blue, magenta, cyan, and white), and two global variables in the :mod:`curses`
+ module, :const:`COLORS` and :const:`COLOR_PAIRS`, containing the maximum number
+ of colors and color-pairs the terminal can support. It also restores the colors
+ on the terminal to the values they had when the terminal was just turned on.
+
+
+.. function:: termattrs()
+
+ Returns a logical OR of all video attributes supported by the terminal. This
+ information is useful when a curses program needs complete control over the
+ appearance of the screen.
+
+
+.. function:: termname()
+
+ Returns the value of the environment variable TERM, truncated to 14 characters.
+
+
+.. function:: tigetflag(capname)
+
+ Returns the value of the Boolean capability corresponding to the terminfo
+ capability name *capname*. The value ``-1`` is returned if *capname* is not a
+ Boolean capability, or ``0`` if it is canceled or absent from the terminal
+ description.
+
+
+.. function:: tigetnum(capname)
+
+ Returns the value of the numeric capability corresponding to the terminfo
+ capability name *capname*. The value ``-2`` is returned if *capname* is not a
+ numeric capability, or ``-1`` if it is canceled or absent from the terminal
+ description.
+
+
+.. function:: tigetstr(capname)
+
+ Returns the value of the string capability corresponding to the terminfo
+ capability name *capname*. ``None`` is returned if *capname* is not a string
+ capability, or is canceled or absent from the terminal description.
+
+
+.. function:: tparm(str[,...])
+
+ Instantiates the string *str* with the supplied parameters, where *str* should
+ be a parameterized string obtained from the terminfo database. E.g.
+ ``tparm(tigetstr("cup"), 5, 3)`` could result in ``'\033[6;4H'``, the exact
+ result depending on terminal type.
+
+
+.. function:: typeahead(fd)
+
+ Specifies that the file descriptor *fd* be used for typeahead checking. If *fd*
+ is ``-1``, then no typeahead checking is done.
+
+ The curses library does "line-breakout optimization" by looking for typeahead
+ periodically while updating the screen. If input is found, and it is coming
+ from a tty, the current update is postponed until refresh or doupdate is called
+ again, allowing faster response to commands typed in advance. This function
+ allows specifying a different file descriptor for typeahead checking.
+
+
+.. function:: unctrl(ch)
+
+ Returns a string which is a printable representation of the character *ch*.
+ Control characters are displayed as a caret followed by the character, for
+ example as ``^C``. Printing characters are left as they are.
+
+
+.. function:: ungetch(ch)
+
+ Push *ch* so the next :meth:`getch` will return it.
+
+ .. note::
+
+ Only one *ch* can be pushed before :meth:`getch` is called.
+
+
+.. function:: ungetmouse(id, x, y, z, bstate)
+
+ Push a :const:`KEY_MOUSE` event onto the input queue, associating the given
+ state data with it.
+
+
+.. function:: use_env(flag)
+
+ If used, this function should be called before :func:`initscr` or newterm are
+ called. When *flag* is false, the values of lines and columns specified in the
+ terminfo database will be used, even if environment variables :envvar:`LINES`
+ and :envvar:`COLUMNS` (used by default) are set, or if curses is running in a
+ window (in which case default behavior would be to use the window size if
+ :envvar:`LINES` and :envvar:`COLUMNS` are not set).
+
+
+.. function:: use_default_colors()
+
+ Allow use of default values for colors on terminals supporting this feature. Use
+ this to support transparency in your application. The default color is assigned
+ to the color number -1. After calling this function, ``init_pair(x,
+ curses.COLOR_RED, -1)`` initializes, for instance, color pair *x* to a red
+ foreground color on the default background.
+
+
+.. _curses-window-objects:
+
+Window Objects
+--------------
+
+Window objects, as returned by :func:`initscr` and :func:`newwin` above, have
+the following methods:
+
+
+.. method:: window.addch([y, x,] ch[, attr])
+
+ .. note::
+
+ A *character* means a C character (an ASCII code), rather then a Python
+ character (a string of length 1). (This note is true whenever the documentation
+ mentions a character.) The builtin :func:`ord` is handy for conveying strings to
+ codes.
+
+ Paint character *ch* at ``(y, x)`` with attributes *attr*, overwriting any
+ character previously painter at that location. By default, the character
+ position and attributes are the current settings for the window object.
+
+
+.. method:: window.addnstr([y, x,] str, n[, attr])
+
+ Paint at most *n* characters of the string *str* at ``(y, x)`` with attributes
+ *attr*, overwriting anything previously on the display.
+
+
+.. method:: window.addstr([y, x,] str[, attr])
+
+ Paint the string *str* at ``(y, x)`` with attributes *attr*, overwriting
+ anything previously on the display.
+
+
+.. method:: window.attroff(attr)
+
+ Remove attribute *attr* from the "background" set applied to all writes to the
+ current window.
+
+
+.. method:: window.attron(attr)
+
+ Add attribute *attr* from the "background" set applied to all writes to the
+ current window.
+
+
+.. method:: window.attrset(attr)
+
+ Set the "background" set of attributes to *attr*. This set is initially 0 (no
+ attributes).
+
+
+.. method:: window.bkgd(ch[, attr])
+
+ Sets the background property of the window to the character *ch*, with
+ attributes *attr*. The change is then applied to every character position in
+ that window:
+
+ * The attribute of every character in the window is changed to the new
+ background attribute.
+
+ * Wherever the former background character appears, it is changed to the new
+ background character.
+
+
+.. method:: window.bkgdset(ch[, attr])
+
+ Sets the window's background. A window's background consists of a character and
+ any combination of attributes. The attribute part of the background is combined
+ (OR'ed) with all non-blank characters that are written into the window. Both
+ the character and attribute parts of the background are combined with the blank
+ characters. The background becomes a property of the character and moves with
+ the character through any scrolling and insert/delete line/character operations.
+
+
+.. method:: window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])
+
+ Draw a border around the edges of the window. Each parameter specifies the
+ character to use for a specific part of the border; see the table below for more
+ details. The characters can be specified as integers or as one-character
+ strings.
+
+ .. note::
+
+ A ``0`` value for any parameter will cause the default character to be used for
+ that parameter. Keyword parameters can *not* be used. The defaults are listed
+ in this table:
+
+ +-----------+---------------------+-----------------------+
+ | Parameter | Description | Default value |
+ +===========+=====================+=======================+
+ | *ls* | Left side | :const:`ACS_VLINE` |
+ +-----------+---------------------+-----------------------+
+ | *rs* | Right side | :const:`ACS_VLINE` |
+ +-----------+---------------------+-----------------------+
+ | *ts* | Top | :const:`ACS_HLINE` |
+ +-----------+---------------------+-----------------------+
+ | *bs* | Bottom | :const:`ACS_HLINE` |
+ +-----------+---------------------+-----------------------+
+ | *tl* | Upper-left corner | :const:`ACS_ULCORNER` |
+ +-----------+---------------------+-----------------------+
+ | *tr* | Upper-right corner | :const:`ACS_URCORNER` |
+ +-----------+---------------------+-----------------------+
+ | *bl* | Bottom-left corner | :const:`ACS_LLCORNER` |
+ +-----------+---------------------+-----------------------+
+ | *br* | Bottom-right corner | :const:`ACS_LRCORNER` |
+ +-----------+---------------------+-----------------------+
+
+
+.. method:: window.box([vertch, horch])
+
+ Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* and
+ bs are *horch*. The default corner characters are always used by this function.
+
+
+.. method:: window.chgat([y, x, ] [num,] attr)
+
+ Sets the attributes of *num* characters at the current cursor position, or at
+ position ``(y, x)`` if supplied. If no value of *num* is given or *num* = -1,
+ the attribute will be set on all the characters to the end of the line. This
+ function does not move the cursor. The changed line will be touched using the
+ :meth:`touchline` method so that the contents will be redisplayed by the next
+ window refresh.
+
+
+.. method:: window.clear()
+
+ Like :meth:`erase`, but also causes the whole window to be repainted upon next
+ call to :meth:`refresh`.
+
+
+.. method:: window.clearok(yes)
+
+ If *yes* is 1, the next call to :meth:`refresh` will clear the window
+ completely.
+
+
+.. method:: window.clrtobot()
+
+ Erase from cursor to the end of the window: all lines below the cursor are
+ deleted, and then the equivalent of :meth:`clrtoeol` is performed.
+
+
+.. method:: window.clrtoeol()
+
+ Erase from cursor to the end of the line.
+
+
+.. method:: window.cursyncup()
+
+ Updates the current cursor position of all the ancestors of the window to
+ reflect the current cursor position of the window.
+
+
+.. method:: window.delch([y, x])
+
+ Delete any character at ``(y, x)``.
+
+
+.. method:: window.deleteln()
+
+ Delete the line under the cursor. All following lines are moved up by 1 line.
+
+
+.. method:: window.derwin([nlines, ncols,] begin_y, begin_x)
+
+ An abbreviation for "derive window", :meth:`derwin` is the same as calling
+ :meth:`subwin`, except that *begin_y* and *begin_x* are relative to the origin
+ of the window, rather than relative to the entire screen. Returns a window
+ object for the derived window.
+
+
+.. method:: window.echochar(ch[, attr])
+
+ Add character *ch* with attribute *attr*, and immediately call :meth:`refresh`
+ on the window.
+
+
+.. method:: window.enclose(y, x)
+
+ Tests whether the given pair of screen-relative character-cell coordinates are
+ enclosed by the given window, returning true or false. It is useful for
+ determining what subset of the screen windows enclose the location of a mouse
+ event.
+
+
+.. method:: window.erase()
+
+ Clear the window.
+
+
+.. method:: window.getbegyx()
+
+ Return a tuple ``(y, x)`` of co-ordinates of upper-left corner.
+
+
+.. method:: window.getch([y, x])
+
+ Get a character. Note that the integer returned does *not* have to be in ASCII
+ range: function keys, keypad keys and so on return numbers higher than 256. In
+ no-delay mode, -1 is returned if there is no input.
+
+
+.. method:: window.getkey([y, x])
+
+ Get a character, returning a string instead of an integer, as :meth:`getch`
+ does. Function keys, keypad keys and so on return a multibyte string containing
+ the key name. In no-delay mode, an exception is raised if there is no input.
+
+
+.. method:: window.getmaxyx()
+
+ Return a tuple ``(y, x)`` of the height and width of the window.
+
+
+.. method:: window.getparyx()
+
+ Returns the beginning coordinates of this window relative to its parent window
+ into two integer variables y and x. Returns ``-1,-1`` if this window has no
+ parent.
+
+
+.. method:: window.getstr([y, x])
+
+ Read a string from the user, with primitive line editing capacity.
+
+
+.. method:: window.getyx()
+
+ Return a tuple ``(y, x)`` of current cursor position relative to the window's
+ upper-left corner.
+
+
+.. method:: window.hline([y, x,] ch, n)
+
+ Display a horizontal line starting at ``(y, x)`` with length *n* consisting of
+ the character *ch*.
+
+
+.. method:: window.idcok(flag)
+
+ If *flag* is false, curses no longer considers using the hardware insert/delete
+ character feature of the terminal; if *flag* is true, use of character insertion
+ and deletion is enabled. When curses is first initialized, use of character
+ insert/delete is enabled by default.
+
+
+.. method:: window.idlok(yes)
+
+ If called with *yes* equal to 1, :mod:`curses` will try and use hardware line
+ editing facilities. Otherwise, line insertion/deletion are disabled.
+
+
+.. method:: window.immedok(flag)
+
+ If *flag* is true, any change in the window image automatically causes the
+ window to be refreshed; you no longer have to call :meth:`refresh` yourself.
+ However, it may degrade performance considerably, due to repeated calls to
+ wrefresh. This option is disabled by default.
+
+
+.. method:: window.inch([y, x])
+
+ Return the character at the given position in the window. The bottom 8 bits are
+ the character proper, and upper bits are the attributes.
+
+
+.. method:: window.insch([y, x,] ch[, attr])
+
+ Paint character *ch* at ``(y, x)`` with attributes *attr*, moving the line from
+ position *x* right by one character.
+
+
+.. method:: window.insdelln(nlines)
+
+ Inserts *nlines* lines into the specified window above the current line. The
+ *nlines* bottom lines are lost. For negative *nlines*, delete *nlines* lines
+ starting with the one under the cursor, and move the remaining lines up. The
+ bottom *nlines* lines are cleared. The current cursor position remains the
+ same.
+
+
+.. method:: window.insertln()
+
+ Insert a blank line under the cursor. All following lines are moved down by 1
+ line.
+
+
+.. method:: window.insnstr([y, x,] str, n [, attr])
+
+ Insert a character string (as many characters as will fit on the line) before
+ the character under the cursor, up to *n* characters. If *n* is zero or
+ negative, the entire string is inserted. All characters to the right of the
+ cursor are shifted right, with the rightmost characters on the line being lost.
+ The cursor position does not change (after moving to *y*, *x*, if specified).
+
+
+.. method:: window.insstr([y, x, ] str [, attr])
+
+ Insert a character string (as many characters as will fit on the line) before
+ the character under the cursor. All characters to the right of the cursor are
+ shifted right, with the rightmost characters on the line being lost. The cursor
+ position does not change (after moving to *y*, *x*, if specified).
+
+
+.. method:: window.instr([y, x] [, n])
+
+ Returns a string of characters, extracted from the window starting at the
+ current cursor position, or at *y*, *x* if specified. Attributes are stripped
+ from the characters. If *n* is specified, :meth:`instr` returns return a string
+ at most *n* characters long (exclusive of the trailing NUL).
+
+
+.. method:: window.is_linetouched(line)
+
+ Returns true if the specified line was modified since the last call to
+ :meth:`refresh`; otherwise returns false. Raises a :exc:`curses.error`
+ exception if *line* is not valid for the given window.
+
+
+.. method:: window.is_wintouched()
+
+ Returns true if the specified window was modified since the last call to
+ :meth:`refresh`; otherwise returns false.
+
+
+.. method:: window.keypad(yes)
+
+ If *yes* is 1, escape sequences generated by some keys (keypad, function keys)
+ will be interpreted by :mod:`curses`. If *yes* is 0, escape sequences will be
+ left as is in the input stream.
+
+
+.. method:: window.leaveok(yes)
+
+ If *yes* is 1, cursor is left where it is on update, instead of being at "cursor
+ position." This reduces cursor movement where possible. If possible the cursor
+ will be made invisible.
+
+ If *yes* is 0, cursor will always be at "cursor position" after an update.
+
+
+.. method:: window.move(new_y, new_x)
+
+ Move cursor to ``(new_y, new_x)``.
+
+
+.. method:: window.mvderwin(y, x)
+
+ Moves the window inside its parent window. The screen-relative parameters of
+ the window are not changed. This routine is used to display different parts of
+ the parent window at the same physical position on the screen.
+
+
+.. method:: window.mvwin(new_y, new_x)
+
+ Move the window so its upper-left corner is at ``(new_y, new_x)``.
+
+
+.. method:: window.nodelay(yes)
+
+ If *yes* is ``1``, :meth:`getch` will be non-blocking.
+
+
+.. method:: window.notimeout(yes)
+
+ If *yes* is ``1``, escape sequences will not be timed out.
+
+ If *yes* is ``0``, after a few milliseconds, an escape sequence will not be
+ interpreted, and will be left in the input stream as is.
+
+
+.. method:: window.noutrefresh()
+
+ Mark for refresh but wait. This function updates the data structure
+ representing the desired state of the window, but does not force an update of
+ the physical screen. To accomplish that, call :func:`doupdate`.
+
+
+.. method:: window.overlay(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])
+
+ Overlay the window on top of *destwin*. The windows need not be the same size,
+ only the overlapping region is copied. This copy is non-destructive, which means
+ that the current background character does not overwrite the old contents of
+ *destwin*.
+
+ To get fine-grained control over the copied region, the second form of
+ :meth:`overlay` can be used. *sminrow* and *smincol* are the upper-left
+ coordinates of the source window, and the other variables mark a rectangle in
+ the destination window.
+
+
+.. method:: window.overwrite(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])
+
+ Overwrite the window on top of *destwin*. The windows need not be the same size,
+ in which case only the overlapping region is copied. This copy is destructive,
+ which means that the current background character overwrites the old contents of
+ *destwin*.
+
+ To get fine-grained control over the copied region, the second form of
+ :meth:`overwrite` can be used. *sminrow* and *smincol* are the upper-left
+ coordinates of the source window, the other variables mark a rectangle in the
+ destination window.
+
+
+.. method:: window.putwin(file)
+
+ Writes all data associated with the window into the provided file object. This
+ information can be later retrieved using the :func:`getwin` function.
+
+
+.. method:: window.redrawln(beg, num)
+
+ Indicates that the *num* screen lines, starting at line *beg*, are corrupted and
+ should be completely redrawn on the next :meth:`refresh` call.
+
+
+.. method:: window.redrawwin()
+
+ Touches the entire window, causing it to be completely redrawn on the next
+ :meth:`refresh` call.
+
+
+.. method:: window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol])
+
+ Update the display immediately (sync actual screen with previous
+ drawing/deleting methods).
+
+ The 6 optional arguments can only be specified when the window is a pad created
+ with :func:`newpad`. The additional parameters are needed to indicate what part
+ of the pad and screen are involved. *pminrow* and *pmincol* specify the upper
+ left-hand corner of the rectangle to be displayed in the pad. *sminrow*,
+ *smincol*, *smaxrow*, and *smaxcol* specify the edges of the rectangle to be
+ displayed on the screen. The lower right-hand corner of the rectangle to be
+ displayed in the pad is calculated from the screen coordinates, since the
+ rectangles must be the same size. Both rectangles must be entirely contained
+ within their respective structures. Negative values of *pminrow*, *pmincol*,
+ *sminrow*, or *smincol* are treated as if they were zero.
+
+
+.. method:: window.scroll([lines=1])
+
+ Scroll the screen or scrolling region upward by *lines* lines.
+
+
+.. method:: window.scrollok(flag)
+
+ Controls what happens when the cursor of a window is moved off the edge of the
+ window or scrolling region, either as a result of a newline action on the bottom
+ line, or typing the last character of the last line. If *flag* is false, the
+ cursor is left on the bottom line. If *flag* is true, the window is scrolled up
+ one line. Note that in order to get the physical scrolling effect on the
+ terminal, it is also necessary to call :meth:`idlok`.
+
+
+.. method:: window.setscrreg(top, bottom)
+
+ Set the scrolling region from line *top* to line *bottom*. All scrolling actions
+ will take place in this region.
+
+
+.. method:: window.standend()
+
+ Turn off the standout attribute. On some terminals this has the side effect of
+ turning off all attributes.
+
+
+.. method:: window.standout()
+
+ Turn on attribute *A_STANDOUT*.
+
+
+.. method:: window.subpad([nlines, ncols,] begin_y, begin_x)
+
+ Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and
+ whose width/height is *ncols*/*nlines*.
+
+
+.. method:: window.subwin([nlines, ncols,] begin_y, begin_x)
+
+ Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and
+ whose width/height is *ncols*/*nlines*.
+
+ By default, the sub-window will extend from the specified position to the lower
+ right corner of the window.
+
+
+.. method:: window.syncdown()
+
+ Touches each location in the window that has been touched in any of its ancestor
+ windows. This routine is called by :meth:`refresh`, so it should almost never
+ be necessary to call it manually.
+
+
+.. method:: window.syncok(flag)
+
+ If called with *flag* set to true, then :meth:`syncup` is called automatically
+ whenever there is a change in the window.
+
+
+.. method:: window.syncup()
+
+ Touches all locations in ancestors of the window that have been changed in the
+ window.
+
+
+.. method:: window.timeout(delay)
+
+ Sets blocking or non-blocking read behavior for the window. If *delay* is
+ negative, blocking read is used (which will wait indefinitely for input). If
+ *delay* is zero, then non-blocking read is used, and -1 will be returned by
+ :meth:`getch` if no input is waiting. If *delay* is positive, then
+ :meth:`getch` will block for *delay* milliseconds, and return -1 if there is
+ still no input at the end of that time.
+
+
+.. method:: window.touchline(start, count[, changed])
+
+ Pretend *count* lines have been changed, starting with line *start*. If
+ *changed* is supplied, it specifies whether the affected lines are marked as
+ having been changed (*changed*\ =1) or unchanged (*changed*\ =0).
+
+
+.. method:: window.touchwin()
+
+ Pretend the whole window has been changed, for purposes of drawing
+ optimizations.
+
+
+.. method:: window.untouchwin()
+
+ Marks all lines in the window as unchanged since the last call to
+ :meth:`refresh`.
+
+
+.. method:: window.vline([y, x,] ch, n)
+
+ Display a vertical line starting at ``(y, x)`` with length *n* consisting of the
+ character *ch*.
+
+
+Constants
+---------
+
+The :mod:`curses` module defines the following data members:
+
+
+.. data:: ERR
+
+ Some curses routines that return an integer, such as :func:`getch`, return
+ :const:`ERR` upon failure.
+
+
+.. data:: OK
+
+ Some curses routines that return an integer, such as :func:`napms`, return
+ :const:`OK` upon success.
+
+
+.. data:: version
+
+ A string representing the current version of the module. Also available as
+ :const:`__version__`.
+
+Several constants are available to specify character cell attributes:
+
++------------------+-------------------------------+
+| Attribute | Meaning |
++==================+===============================+
+| ``A_ALTCHARSET`` | Alternate character set mode. |
++------------------+-------------------------------+
+| ``A_BLINK`` | Blink mode. |
++------------------+-------------------------------+
+| ``A_BOLD`` | Bold mode. |
++------------------+-------------------------------+
+| ``A_DIM`` | Dim mode. |
++------------------+-------------------------------+
+| ``A_NORMAL`` | Normal attribute. |
++------------------+-------------------------------+
+| ``A_STANDOUT`` | Standout mode. |
++------------------+-------------------------------+
+| ``A_UNDERLINE`` | Underline mode. |
++------------------+-------------------------------+
+
+Keys are referred to by integer constants with names starting with ``KEY_``.
+The exact keycaps available are system dependent.
+
+.. % XXX this table is far too large!
+.. % XXX should this table be alphabetized?
+
++-------------------+--------------------------------------------+
+| Key constant | Key |
++===================+============================================+
+| ``KEY_MIN`` | Minimum key value |
++-------------------+--------------------------------------------+
+| ``KEY_BREAK`` | Break key (unreliable) |
++-------------------+--------------------------------------------+
+| ``KEY_DOWN`` | Down-arrow |
++-------------------+--------------------------------------------+
+| ``KEY_UP`` | Up-arrow |
++-------------------+--------------------------------------------+
+| ``KEY_LEFT`` | Left-arrow |
++-------------------+--------------------------------------------+
+| ``KEY_RIGHT`` | Right-arrow |
++-------------------+--------------------------------------------+
+| ``KEY_HOME`` | Home key (upward+left arrow) |
++-------------------+--------------------------------------------+
+| ``KEY_BACKSPACE`` | Backspace (unreliable) |
++-------------------+--------------------------------------------+
+| ``KEY_F0`` | Function keys. Up to 64 function keys are |
+| | supported. |
++-------------------+--------------------------------------------+
+| ``KEY_Fn`` | Value of function key *n* |
++-------------------+--------------------------------------------+
+| ``KEY_DL`` | Delete line |
++-------------------+--------------------------------------------+
+| ``KEY_IL`` | Insert line |
++-------------------+--------------------------------------------+
+| ``KEY_DC`` | Delete character |
++-------------------+--------------------------------------------+
+| ``KEY_IC`` | Insert char or enter insert mode |
++-------------------+--------------------------------------------+
+| ``KEY_EIC`` | Exit insert char mode |
++-------------------+--------------------------------------------+
+| ``KEY_CLEAR`` | Clear screen |
++-------------------+--------------------------------------------+
+| ``KEY_EOS`` | Clear to end of screen |
++-------------------+--------------------------------------------+
+| ``KEY_EOL`` | Clear to end of line |
++-------------------+--------------------------------------------+
+| ``KEY_SF`` | Scroll 1 line forward |
++-------------------+--------------------------------------------+
+| ``KEY_SR`` | Scroll 1 line backward (reverse) |
++-------------------+--------------------------------------------+
+| ``KEY_NPAGE`` | Next page |
++-------------------+--------------------------------------------+
+| ``KEY_PPAGE`` | Previous page |
++-------------------+--------------------------------------------+
+| ``KEY_STAB`` | Set tab |
++-------------------+--------------------------------------------+
+| ``KEY_CTAB`` | Clear tab |
++-------------------+--------------------------------------------+
+| ``KEY_CATAB`` | Clear all tabs |
++-------------------+--------------------------------------------+
+| ``KEY_ENTER`` | Enter or send (unreliable) |
++-------------------+--------------------------------------------+
+| ``KEY_SRESET`` | Soft (partial) reset (unreliable) |
++-------------------+--------------------------------------------+
+| ``KEY_RESET`` | Reset or hard reset (unreliable) |
++-------------------+--------------------------------------------+
+| ``KEY_PRINT`` | Print |
++-------------------+--------------------------------------------+
+| ``KEY_LL`` | Home down or bottom (lower left) |
++-------------------+--------------------------------------------+
+| ``KEY_A1`` | Upper left of keypad |
++-------------------+--------------------------------------------+
+| ``KEY_A3`` | Upper right of keypad |
++-------------------+--------------------------------------------+
+| ``KEY_B2`` | Center of keypad |
++-------------------+--------------------------------------------+
+| ``KEY_C1`` | Lower left of keypad |
++-------------------+--------------------------------------------+
+| ``KEY_C3`` | Lower right of keypad |
++-------------------+--------------------------------------------+
+| ``KEY_BTAB`` | Back tab |
++-------------------+--------------------------------------------+
+| ``KEY_BEG`` | Beg (beginning) |
++-------------------+--------------------------------------------+
+| ``KEY_CANCEL`` | Cancel |
++-------------------+--------------------------------------------+
+| ``KEY_CLOSE`` | Close |
++-------------------+--------------------------------------------+
+| ``KEY_COMMAND`` | Cmd (command) |
++-------------------+--------------------------------------------+
+| ``KEY_COPY`` | Copy |
++-------------------+--------------------------------------------+
+| ``KEY_CREATE`` | Create |
++-------------------+--------------------------------------------+
+| ``KEY_END`` | End |
++-------------------+--------------------------------------------+
+| ``KEY_EXIT`` | Exit |
++-------------------+--------------------------------------------+
+| ``KEY_FIND`` | Find |
++-------------------+--------------------------------------------+
+| ``KEY_HELP`` | Help |
++-------------------+--------------------------------------------+
+| ``KEY_MARK`` | Mark |
++-------------------+--------------------------------------------+
+| ``KEY_MESSAGE`` | Message |
++-------------------+--------------------------------------------+
+| ``KEY_MOVE`` | Move |
++-------------------+--------------------------------------------+
+| ``KEY_NEXT`` | Next |
++-------------------+--------------------------------------------+
+| ``KEY_OPEN`` | Open |
++-------------------+--------------------------------------------+
+| ``KEY_OPTIONS`` | Options |
++-------------------+--------------------------------------------+
+| ``KEY_PREVIOUS`` | Prev (previous) |
++-------------------+--------------------------------------------+
+| ``KEY_REDO`` | Redo |
++-------------------+--------------------------------------------+
+| ``KEY_REFERENCE`` | Ref (reference) |
++-------------------+--------------------------------------------+
+| ``KEY_REFRESH`` | Refresh |
++-------------------+--------------------------------------------+
+| ``KEY_REPLACE`` | Replace |
++-------------------+--------------------------------------------+
+| ``KEY_RESTART`` | Restart |
++-------------------+--------------------------------------------+
+| ``KEY_RESUME`` | Resume |
++-------------------+--------------------------------------------+
+| ``KEY_SAVE`` | Save |
++-------------------+--------------------------------------------+
+| ``KEY_SBEG`` | Shifted Beg (beginning) |
++-------------------+--------------------------------------------+
+| ``KEY_SCANCEL`` | Shifted Cancel |
++-------------------+--------------------------------------------+
+| ``KEY_SCOMMAND`` | Shifted Command |
++-------------------+--------------------------------------------+
+| ``KEY_SCOPY`` | Shifted Copy |
++-------------------+--------------------------------------------+
+| ``KEY_SCREATE`` | Shifted Create |
++-------------------+--------------------------------------------+
+| ``KEY_SDC`` | Shifted Delete char |
++-------------------+--------------------------------------------+
+| ``KEY_SDL`` | Shifted Delete line |
++-------------------+--------------------------------------------+
+| ``KEY_SELECT`` | Select |
++-------------------+--------------------------------------------+
+| ``KEY_SEND`` | Shifted End |
++-------------------+--------------------------------------------+
+| ``KEY_SEOL`` | Shifted Clear line |
++-------------------+--------------------------------------------+
+| ``KEY_SEXIT`` | Shifted Dxit |
++-------------------+--------------------------------------------+
+| ``KEY_SFIND`` | Shifted Find |
++-------------------+--------------------------------------------+
+| ``KEY_SHELP`` | Shifted Help |
++-------------------+--------------------------------------------+
+| ``KEY_SHOME`` | Shifted Home |
++-------------------+--------------------------------------------+
+| ``KEY_SIC`` | Shifted Input |
++-------------------+--------------------------------------------+
+| ``KEY_SLEFT`` | Shifted Left arrow |
++-------------------+--------------------------------------------+
+| ``KEY_SMESSAGE`` | Shifted Message |
++-------------------+--------------------------------------------+
+| ``KEY_SMOVE`` | Shifted Move |
++-------------------+--------------------------------------------+
+| ``KEY_SNEXT`` | Shifted Next |
++-------------------+--------------------------------------------+
+| ``KEY_SOPTIONS`` | Shifted Options |
++-------------------+--------------------------------------------+
+| ``KEY_SPREVIOUS`` | Shifted Prev |
++-------------------+--------------------------------------------+
+| ``KEY_SPRINT`` | Shifted Print |
++-------------------+--------------------------------------------+
+| ``KEY_SREDO`` | Shifted Redo |
++-------------------+--------------------------------------------+
+| ``KEY_SREPLACE`` | Shifted Replace |
++-------------------+--------------------------------------------+
+| ``KEY_SRIGHT`` | Shifted Right arrow |
++-------------------+--------------------------------------------+
+| ``KEY_SRSUME`` | Shifted Resume |
++-------------------+--------------------------------------------+
+| ``KEY_SSAVE`` | Shifted Save |
++-------------------+--------------------------------------------+
+| ``KEY_SSUSPEND`` | Shifted Suspend |
++-------------------+--------------------------------------------+
+| ``KEY_SUNDO`` | Shifted Undo |
++-------------------+--------------------------------------------+
+| ``KEY_SUSPEND`` | Suspend |
++-------------------+--------------------------------------------+
+| ``KEY_UNDO`` | Undo |
++-------------------+--------------------------------------------+
+| ``KEY_MOUSE`` | Mouse event has occurred |
++-------------------+--------------------------------------------+
+| ``KEY_RESIZE`` | Terminal resize event |
++-------------------+--------------------------------------------+
+| ``KEY_MAX`` | Maximum key value |
++-------------------+--------------------------------------------+
+
+On VT100s and their software emulations, such as X terminal emulators, there are
+normally at least four function keys (:const:`KEY_F1`, :const:`KEY_F2`,
+:const:`KEY_F3`, :const:`KEY_F4`) available, and the arrow keys mapped to
+:const:`KEY_UP`, :const:`KEY_DOWN`, :const:`KEY_LEFT` and :const:`KEY_RIGHT` in
+the obvious way. If your machine has a PC keyboard, it is safe to expect arrow
+keys and twelve function keys (older PC keyboards may have only ten function
+keys); also, the following keypad mappings are standard:
+
++------------------+-----------+
+| Keycap | Constant |
++==================+===========+
+| :kbd:`Insert` | KEY_IC |
++------------------+-----------+
+| :kbd:`Delete` | KEY_DC |
++------------------+-----------+
+| :kbd:`Home` | KEY_HOME |
++------------------+-----------+
+| :kbd:`End` | KEY_END |
++------------------+-----------+
+| :kbd:`Page Up` | KEY_NPAGE |
++------------------+-----------+
+| :kbd:`Page Down` | KEY_PPAGE |
++------------------+-----------+
+
+The following table lists characters from the alternate character set. These are
+inherited from the VT100 terminal, and will generally be available on software
+emulations such as X terminals. When there is no graphic available, curses
+falls back on a crude printable ASCII approximation.
+
+.. note::
+
+ These are available only after :func:`initscr` has been called.
+
++------------------+------------------------------------------+
+| ACS code | Meaning |
++==================+==========================================+
+| ``ACS_BBSS`` | alternate name for upper right corner |
++------------------+------------------------------------------+
+| ``ACS_BLOCK`` | solid square block |
++------------------+------------------------------------------+
+| ``ACS_BOARD`` | board of squares |
++------------------+------------------------------------------+
+| ``ACS_BSBS`` | alternate name for horizontal line |
++------------------+------------------------------------------+
+| ``ACS_BSSB`` | alternate name for upper left corner |
++------------------+------------------------------------------+
+| ``ACS_BSSS`` | alternate name for top tee |
++------------------+------------------------------------------+
+| ``ACS_BTEE`` | bottom tee |
++------------------+------------------------------------------+
+| ``ACS_BULLET`` | bullet |
++------------------+------------------------------------------+
+| ``ACS_CKBOARD`` | checker board (stipple) |
++------------------+------------------------------------------+
+| ``ACS_DARROW`` | arrow pointing down |
++------------------+------------------------------------------+
+| ``ACS_DEGREE`` | degree symbol |
++------------------+------------------------------------------+
+| ``ACS_DIAMOND`` | diamond |
++------------------+------------------------------------------+
+| ``ACS_GEQUAL`` | greater-than-or-equal-to |
++------------------+------------------------------------------+
+| ``ACS_HLINE`` | horizontal line |
++------------------+------------------------------------------+
+| ``ACS_LANTERN`` | lantern symbol |
++------------------+------------------------------------------+
+| ``ACS_LARROW`` | left arrow |
++------------------+------------------------------------------+
+| ``ACS_LEQUAL`` | less-than-or-equal-to |
++------------------+------------------------------------------+
+| ``ACS_LLCORNER`` | lower left-hand corner |
++------------------+------------------------------------------+
+| ``ACS_LRCORNER`` | lower right-hand corner |
++------------------+------------------------------------------+
+| ``ACS_LTEE`` | left tee |
++------------------+------------------------------------------+
+| ``ACS_NEQUAL`` | not-equal sign |
++------------------+------------------------------------------+
+| ``ACS_PI`` | letter pi |
++------------------+------------------------------------------+
+| ``ACS_PLMINUS`` | plus-or-minus sign |
++------------------+------------------------------------------+
+| ``ACS_PLUS`` | big plus sign |
++------------------+------------------------------------------+
+| ``ACS_RARROW`` | right arrow |
++------------------+------------------------------------------+
+| ``ACS_RTEE`` | right tee |
++------------------+------------------------------------------+
+| ``ACS_S1`` | scan line 1 |
++------------------+------------------------------------------+
+| ``ACS_S3`` | scan line 3 |
++------------------+------------------------------------------+
+| ``ACS_S7`` | scan line 7 |
++------------------+------------------------------------------+
+| ``ACS_S9`` | scan line 9 |
++------------------+------------------------------------------+
+| ``ACS_SBBS`` | alternate name for lower right corner |
++------------------+------------------------------------------+
+| ``ACS_SBSB`` | alternate name for vertical line |
++------------------+------------------------------------------+
+| ``ACS_SBSS`` | alternate name for right tee |
++------------------+------------------------------------------+
+| ``ACS_SSBB`` | alternate name for lower left corner |
++------------------+------------------------------------------+
+| ``ACS_SSBS`` | alternate name for bottom tee |
++------------------+------------------------------------------+
+| ``ACS_SSSB`` | alternate name for left tee |
++------------------+------------------------------------------+
+| ``ACS_SSSS`` | alternate name for crossover or big plus |
++------------------+------------------------------------------+
+| ``ACS_STERLING`` | pound sterling |
++------------------+------------------------------------------+
+| ``ACS_TTEE`` | top tee |
++------------------+------------------------------------------+
+| ``ACS_UARROW`` | up arrow |
++------------------+------------------------------------------+
+| ``ACS_ULCORNER`` | upper left corner |
++------------------+------------------------------------------+
+| ``ACS_URCORNER`` | upper right corner |
++------------------+------------------------------------------+
+| ``ACS_VLINE`` | vertical line |
++------------------+------------------------------------------+
+
+The following table lists the predefined colors:
+
++-------------------+----------------------------+
+| Constant | Color |
++===================+============================+
+| ``COLOR_BLACK`` | Black |
++-------------------+----------------------------+
+| ``COLOR_BLUE`` | Blue |
++-------------------+----------------------------+
+| ``COLOR_CYAN`` | Cyan (light greenish blue) |
++-------------------+----------------------------+
+| ``COLOR_GREEN`` | Green |
++-------------------+----------------------------+
+| ``COLOR_MAGENTA`` | Magenta (purplish red) |
++-------------------+----------------------------+
+| ``COLOR_RED`` | Red |
++-------------------+----------------------------+
+| ``COLOR_WHITE`` | White |
++-------------------+----------------------------+
+| ``COLOR_YELLOW`` | Yellow |
++-------------------+----------------------------+
+
+
+:mod:`curses.textpad` --- Text input widget for curses programs
+===============================================================
+
+.. module:: curses.textpad
+ :synopsis: Emacs-like input editing in a curses window.
+.. moduleauthor:: Eric Raymond <esr@thyrsus.com>
+.. sectionauthor:: Eric Raymond <esr@thyrsus.com>
+
+
+.. versionadded:: 1.6
+
+The :mod:`curses.textpad` module provides a :class:`Textbox` class that handles
+elementary text editing in a curses window, supporting a set of keybindings
+resembling those of Emacs (thus, also of Netscape Navigator, BBedit 6.x,
+FrameMaker, and many other programs). The module also provides a
+rectangle-drawing function useful for framing text boxes or for other purposes.
+
+The module :mod:`curses.textpad` defines the following function:
+
+
+.. function:: rectangle(win, uly, ulx, lry, lrx)
+
+ Draw a rectangle. The first argument must be a window object; the remaining
+ arguments are coordinates relative to that window. The second and third
+ arguments are the y and x coordinates of the upper left hand corner of the
+ rectangle to be drawn; the fourth and fifth arguments are the y and x
+ coordinates of the lower right hand corner. The rectangle will be drawn using
+ VT100/IBM PC forms characters on terminals that make this possible (including
+ xterm and most other software terminal emulators). Otherwise it will be drawn
+ with ASCII dashes, vertical bars, and plus signs.
+
+
+.. _curses-textpad-objects:
+
+Textbox objects
+---------------
+
+You can instantiate a :class:`Textbox` object as follows:
+
+
+.. class:: Textbox(win)
+
+ Return a textbox widget object. The *win* argument should be a curses
+ :class:`WindowObject` in which the textbox is to be contained. The edit cursor
+ of the textbox is initially located at the upper left hand corner of the
+ containing window, with coordinates ``(0, 0)``. The instance's
+ :attr:`stripspaces` flag is initially on.
+
+:class:`Textbox` objects have the following methods:
+
+
+.. method:: Textbox.edit([validator])
+
+ This is the entry point you will normally use. It accepts editing keystrokes
+ until one of the termination keystrokes is entered. If *validator* is supplied,
+ it must be a function. It will be called for each keystroke entered with the
+ keystroke as a parameter; command dispatch is done on the result. This method
+ returns the window contents as a string; whether blanks in the window are
+ included is affected by the :attr:`stripspaces` member.
+
+
+.. method:: Textbox.do_command(ch)
+
+ Process a single command keystroke. Here are the supported special keystrokes:
+
+ +------------------+-------------------------------------------+
+ | Keystroke | Action |
+ +==================+===========================================+
+ | :kbd:`Control-A` | Go to left edge of window. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-B` | Cursor left, wrapping to previous line if |
+ | | appropriate. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-D` | Delete character under cursor. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-E` | Go to right edge (stripspaces off) or end |
+ | | of line (stripspaces on). |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-F` | Cursor right, wrapping to next line when |
+ | | appropriate. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-G` | Terminate, returning the window contents. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-H` | Delete character backward. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-J` | Terminate if the window is 1 line, |
+ | | otherwise insert newline. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-K` | If line is blank, delete it, otherwise |
+ | | clear to end of line. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-L` | Refresh screen. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-N` | Cursor down; move down one line. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-O` | Insert a blank line at cursor location. |
+ +------------------+-------------------------------------------+
+ | :kbd:`Control-P` | Cursor up; move up one line. |
+ +------------------+-------------------------------------------+
+
+ Move operations do nothing if the cursor is at an edge where the movement is not
+ possible. The following synonyms are supported where possible:
+
+ +------------------------+------------------+
+ | Constant | Keystroke |
+ +========================+==================+
+ | :const:`KEY_LEFT` | :kbd:`Control-B` |
+ +------------------------+------------------+
+ | :const:`KEY_RIGHT` | :kbd:`Control-F` |
+ +------------------------+------------------+
+ | :const:`KEY_UP` | :kbd:`Control-P` |
+ +------------------------+------------------+
+ | :const:`KEY_DOWN` | :kbd:`Control-N` |
+ +------------------------+------------------+
+ | :const:`KEY_BACKSPACE` | :kbd:`Control-h` |
+ +------------------------+------------------+
+
+ All other keystrokes are treated as a command to insert the given character and
+ move right (with line wrapping).
+
+
+.. method:: Textbox.gather()
+
+ This method returns the window contents as a string; whether blanks in the
+ window are included is affected by the :attr:`stripspaces` member.
+
+
+.. attribute:: Textbox.stripspaces
+
+ This data member is a flag which controls the interpretation of blanks in the
+ window. When it is on, trailing blanks on each line are ignored; any cursor
+ motion that would land the cursor on a trailing blank goes to the end of that
+ line instead, and trailing blanks are stripped when the window contents are
+ gathered.
+
+
+:mod:`curses.wrapper` --- Terminal handler for curses programs
+==============================================================
+
+.. module:: curses.wrapper
+ :synopsis: Terminal configuration wrapper for curses programs.
+.. moduleauthor:: Eric Raymond <esr@thyrsus.com>
+.. sectionauthor:: Eric Raymond <esr@thyrsus.com>
+
+
+.. versionadded:: 1.6
+
+This module supplies one function, :func:`wrapper`, which runs another function
+which should be the rest of your curses-using application. If the application
+raises an exception, :func:`wrapper` will restore the terminal to a sane state
+before re-raising the exception and generating a traceback.
+
+
+.. function:: wrapper(func, ...)
+
+ Wrapper function that initializes curses and calls another function, *func*,
+ restoring normal keyboard/screen behavior on error. The callable object *func*
+ is then passed the main window 'stdscr' as its first argument, followed by any
+ other arguments passed to :func:`wrapper`.
+
+Before calling the hook function, :func:`wrapper` turns on cbreak mode, turns
+off echo, enables the terminal keypad, and initializes colors if the terminal
+has color support. On exit (whether normally or by exception) it restores
+cooked mode, turns on echo, and disables the terminal keypad.
+
--- /dev/null
+
+.. _custominterp:
+
+**************************
+Custom Python Interpreters
+**************************
+
+The modules described in this chapter allow writing interfaces similar to
+Python's interactive interpreter. If you want a Python interpreter that
+supports some special feature in addition to the Python language, you should
+look at the :mod:`code` module. (The :mod:`codeop` module is lower-level, used
+to support compiling a possibly-incomplete chunk of Python code.)
+
+The full list of modules described in this chapter is:
+
+
+.. toctree::
+
+ code.rst
+ codeop.rst
--- /dev/null
+
+.. _datatypes:
+
+**********
+Data Types
+**********
+
+The modules described in this chapter provide a variety of specialized data
+types such as dates and times, fixed-type arrays, heap queues, synchronized
+queues, and sets.
+
+Python also provides some built-in data types, in particular,
+:class:`dict`, :class:`list`, :class:`set` (which along with
+:class:`frozenset`, replaces the deprecated :mod:`sets` module), and
+:class:`tuple`. The :class:`str` class can be used to handle binary data
+and 8-bit text, and the :class:`unicode` class to handle Unicode text.
+
+The following modules are documented in this chapter:
+
+
+.. toctree::
+
+ datetime.rst
+ calendar.rst
+ collections.rst
+ heapq.rst
+ bisect.rst
+ array.rst
+ sets.rst
+ sched.rst
+ mutex.rst
+ queue.rst
+ weakref.rst
+ userdict.rst
+ types.rst
+ new.rst
+ copy.rst
+ pprint.rst
+ repr.rst
--- /dev/null
+.. % XXX what order should the types be discussed in?
+
+
+:mod:`datetime` --- Basic date and time types
+=============================================
+
+.. module:: datetime
+ :synopsis: Basic date and time types.
+.. moduleauthor:: Tim Peters <tim@zope.com>
+.. sectionauthor:: Tim Peters <tim@zope.com>
+.. sectionauthor:: A.M. Kuchling <amk@amk.ca>
+
+
+.. versionadded:: 2.3
+
+The :mod:`datetime` module supplies classes for manipulating dates and times in
+both simple and complex ways. While date and time arithmetic is supported, the
+focus of the implementation is on efficient member extraction for output
+formatting and manipulation. For related
+functionality, see also the :mod:`time` and :mod:`calendar` modules.
+
+There are two kinds of date and time objects: "naive" and "aware". This
+distinction refers to whether the object has any notion of time zone, daylight
+saving time, or other kind of algorithmic or political time adjustment. Whether
+a naive :class:`datetime` object represents Coordinated Universal Time (UTC),
+local time, or time in some other timezone is purely up to the program, just
+like it's up to the program whether a particular number represents metres,
+miles, or mass. Naive :class:`datetime` objects are easy to understand and to
+work with, at the cost of ignoring some aspects of reality.
+
+For applications requiring more, :class:`datetime` and :class:`time` objects
+have an optional time zone information member, :attr:`tzinfo`, that can contain
+an instance of a subclass of the abstract :class:`tzinfo` class. These
+:class:`tzinfo` objects capture information about the offset from UTC time, the
+time zone name, and whether Daylight Saving Time is in effect. Note that no
+concrete :class:`tzinfo` classes are supplied by the :mod:`datetime` module.
+Supporting timezones at whatever level of detail is required is up to the
+application. The rules for time adjustment across the world are more political
+than rational, and there is no standard suitable for every application.
+
+The :mod:`datetime` module exports the following constants:
+
+
+.. data:: MINYEAR
+
+ The smallest year number allowed in a :class:`date` or :class:`datetime` object.
+ :const:`MINYEAR` is ``1``.
+
+
+.. data:: MAXYEAR
+
+ The largest year number allowed in a :class:`date` or :class:`datetime` object.
+ :const:`MAXYEAR` is ``9999``.
+
+
+.. seealso::
+
+ Module :mod:`calendar`
+ General calendar related functions.
+
+ Module :mod:`time`
+ Time access and conversions.
+
+
+Available Types
+---------------
+
+
+.. class:: date
+
+ An idealized naive date, assuming the current Gregorian calendar always was, and
+ always will be, in effect. Attributes: :attr:`year`, :attr:`month`, and
+ :attr:`day`.
+
+
+.. class:: time
+
+ An idealized time, independent of any particular day, assuming that every day
+ has exactly 24\*60\*60 seconds (there is no notion of "leap seconds" here).
+ Attributes: :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
+ and :attr:`tzinfo`.
+
+
+.. class:: datetime
+
+ A combination of a date and a time. Attributes: :attr:`year`, :attr:`month`,
+ :attr:`day`, :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
+ and :attr:`tzinfo`.
+
+
+.. class:: timedelta
+
+ A duration expressing the difference between two :class:`date`, :class:`time`,
+ or :class:`datetime` instances to microsecond resolution.
+
+
+.. class:: tzinfo
+
+ An abstract base class for time zone information objects. These are used by the
+ :class:`datetime` and :class:`time` classes to provide a customizable notion of
+ time adjustment (for example, to account for time zone and/or daylight saving
+ time).
+
+Objects of these types are immutable.
+
+Objects of the :class:`date` type are always naive.
+
+An object *d* of type :class:`time` or :class:`datetime` may be naive or aware.
+*d* is aware if ``d.tzinfo`` is not ``None`` and ``d.tzinfo.utcoffset(d)`` does
+not return ``None``. If ``d.tzinfo`` is ``None``, or if ``d.tzinfo`` is not
+``None`` but ``d.tzinfo.utcoffset(d)`` returns ``None``, *d* is naive.
+
+The distinction between naive and aware doesn't apply to :class:`timedelta`
+objects.
+
+Subclass relationships::
+
+ object
+ timedelta
+ tzinfo
+ time
+ date
+ datetime
+
+
+.. _datetime-timedelta:
+
+:class:`timedelta` Objects
+--------------------------
+
+A :class:`timedelta` object represents a duration, the difference between two
+dates or times.
+
+
+.. class:: timedelta([days[, seconds[, microseconds[, milliseconds[, minutes[, hours[, weeks]]]]]]])
+
+ All arguments are optional and default to ``0``. Arguments may be ints, longs,
+ or floats, and may be positive or negative.
+
+ Only *days*, *seconds* and *microseconds* are stored internally. Arguments are
+ converted to those units:
+
+ * A millisecond is converted to 1000 microseconds.
+ * A minute is converted to 60 seconds.
+ * An hour is converted to 3600 seconds.
+ * A week is converted to 7 days.
+
+ and days, seconds and microseconds are then normalized so that the
+ representation is unique, with
+
+ * ``0 <= microseconds < 1000000``
+ * ``0 <= seconds < 3600*24`` (the number of seconds in one day)
+ * ``-999999999 <= days <= 999999999``
+
+ If any argument is a float and there are fractional microseconds, the fractional
+ microseconds left over from all arguments are combined and their sum is rounded
+ to the nearest microsecond. If no argument is a float, the conversion and
+ normalization processes are exact (no information is lost).
+
+ If the normalized value of days lies outside the indicated range,
+ :exc:`OverflowError` is raised.
+
+ Note that normalization of negative values may be surprising at first. For
+ example, ::
+
+ >>> d = timedelta(microseconds=-1)
+ >>> (d.days, d.seconds, d.microseconds)
+ (-1, 86399, 999999)
+
+Class attributes are:
+
+
+.. attribute:: timedelta.min
+
+ The most negative :class:`timedelta` object, ``timedelta(-999999999)``.
+
+
+.. attribute:: timedelta.max
+
+ The most positive :class:`timedelta` object, ``timedelta(days=999999999,
+ hours=23, minutes=59, seconds=59, microseconds=999999)``.
+
+
+.. attribute:: timedelta.resolution
+
+ The smallest possible difference between non-equal :class:`timedelta` objects,
+ ``timedelta(microseconds=1)``.
+
+Note that, because of normalization, ``timedelta.max`` > ``-timedelta.min``.
+``-timedelta.max`` is not representable as a :class:`timedelta` object.
+
+Instance attributes (read-only):
+
++------------------+--------------------------------------------+
+| Attribute | Value |
++==================+============================================+
+| ``days`` | Between -999999999 and 999999999 inclusive |
++------------------+--------------------------------------------+
+| ``seconds`` | Between 0 and 86399 inclusive |
++------------------+--------------------------------------------+
+| ``microseconds`` | Between 0 and 999999 inclusive |
++------------------+--------------------------------------------+
+
+Supported operations:
+
+.. % XXX this table is too wide!
+
++--------------------------------+-----------------------------------------------+
+| Operation | Result |
++================================+===============================================+
+| ``t1 = t2 + t3`` | Sum of *t2* and *t3*. Afterwards *t1*-*t2* == |
+| | *t3* and *t1*-*t3* == *t2* are true. (1) |
++--------------------------------+-----------------------------------------------+
+| ``t1 = t2 - t3`` | Difference of *t2* and *t3*. Afterwards *t1* |
+| | == *t2* - *t3* and *t2* == *t1* + *t3* are |
+| | true. (1) |
++--------------------------------+-----------------------------------------------+
+| ``t1 = t2 * i or t1 = i * t2`` | Delta multiplied by an integer or long. |
+| | Afterwards *t1* // i == *t2* is true, |
+| | provided ``i != 0``. |
++--------------------------------+-----------------------------------------------+
+| | In general, *t1* \* i == *t1* \* (i-1) + *t1* |
+| | is true. (1) |
++--------------------------------+-----------------------------------------------+
+| ``t1 = t2 // i`` | The floor is computed and the remainder (if |
+| | any) is thrown away. (3) |
++--------------------------------+-----------------------------------------------+
+| ``+t1`` | Returns a :class:`timedelta` object with the |
+| | same value. (2) |
++--------------------------------+-----------------------------------------------+
+| ``-t1`` | equivalent to :class:`timedelta`\ |
+| | (-*t1.days*, -*t1.seconds*, |
+| | -*t1.microseconds*), and to *t1*\* -1. (1)(4) |
++--------------------------------+-----------------------------------------------+
+| ``abs(t)`` | equivalent to +*t* when ``t.days >= 0``, and |
+| | to -*t* when ``t.days < 0``. (2) |
++--------------------------------+-----------------------------------------------+
+
+Notes:
+
+(1)
+ This is exact, but may overflow.
+
+(2)
+ This is exact, and cannot overflow.
+
+(3)
+ Division by 0 raises :exc:`ZeroDivisionError`.
+
+(4)
+ -*timedelta.max* is not representable as a :class:`timedelta` object.
+
+In addition to the operations listed above :class:`timedelta` objects support
+certain additions and subtractions with :class:`date` and :class:`datetime`
+objects (see below).
+
+Comparisons of :class:`timedelta` objects are supported with the
+:class:`timedelta` object representing the smaller duration considered to be the
+smaller timedelta. In order to stop mixed-type comparisons from falling back to
+the default comparison by object address, when a :class:`timedelta` object is
+compared to an object of a different type, :exc:`TypeError` is raised unless the
+comparison is ``==`` or ``!=``. The latter cases return :const:`False` or
+:const:`True`, respectively.
+
+:class:`timedelta` objects are hashable (usable as dictionary keys), support
+efficient pickling, and in Boolean contexts, a :class:`timedelta` object is
+considered to be true if and only if it isn't equal to ``timedelta(0)``.
+
+
+.. _datetime-date:
+
+:class:`date` Objects
+---------------------
+
+A :class:`date` object represents a date (year, month and day) in an idealized
+calendar, the current Gregorian calendar indefinitely extended in both
+directions. January 1 of year 1 is called day number 1, January 2 of year 1 is
+called day number 2, and so on. This matches the definition of the "proleptic
+Gregorian" calendar in Dershowitz and Reingold's book Calendrical Calculations,
+where it's the base calendar for all computations. See the book for algorithms
+for converting between proleptic Gregorian ordinals and many other calendar
+systems.
+
+
+.. class:: date(year, month, day)
+
+ All arguments are required. Arguments may be ints or longs, in the following
+ ranges:
+
+ * ``MINYEAR <= year <= MAXYEAR``
+ * ``1 <= month <= 12``
+ * ``1 <= day <= number of days in the given month and year``
+
+ If an argument outside those ranges is given, :exc:`ValueError` is raised.
+
+Other constructors, all class methods:
+
+
+.. method:: date.today()
+
+ Return the current local date. This is equivalent to
+ ``date.fromtimestamp(time.time())``.
+
+
+.. method:: date.fromtimestamp(timestamp)
+
+ Return the local date corresponding to the POSIX timestamp, such as is returned
+ by :func:`time.time`. This may raise :exc:`ValueError`, if the timestamp is out
+ of the range of values supported by the platform C :cfunc:`localtime` function.
+ It's common for this to be restricted to years from 1970 through 2038. Note
+ that on non-POSIX systems that include leap seconds in their notion of a
+ timestamp, leap seconds are ignored by :meth:`fromtimestamp`.
+
+
+.. method:: date.fromordinal(ordinal)
+
+ Return the date corresponding to the proleptic Gregorian ordinal, where January
+ 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1 <= ordinal <=
+ date.max.toordinal()``. For any date *d*, ``date.fromordinal(d.toordinal()) ==
+ d``.
+
+Class attributes:
+
+
+.. attribute:: date.min
+
+ The earliest representable date, ``date(MINYEAR, 1, 1)``.
+
+
+.. attribute:: date.max
+
+ The latest representable date, ``date(MAXYEAR, 12, 31)``.
+
+
+.. attribute:: date.resolution
+
+ The smallest possible difference between non-equal date objects,
+ ``timedelta(days=1)``.
+
+Instance attributes (read-only):
+
+
+.. attribute:: date.year
+
+ Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive.
+
+
+.. attribute:: date.month
+
+ Between 1 and 12 inclusive.
+
+
+.. attribute:: date.day
+
+ Between 1 and the number of days in the given month of the given year.
+
+Supported operations:
+
++-------------------------------+----------------------------------------------+
+| Operation | Result |
++===============================+==============================================+
+| ``date2 = date1 + timedelta`` | *date2* is ``timedelta.days`` days removed |
+| | from *date1*. (1) |
++-------------------------------+----------------------------------------------+
+| ``date2 = date1 - timedelta`` | Computes *date2* such that ``date2 + |
+| | timedelta == date1``. (2) |
++-------------------------------+----------------------------------------------+
+| ``timedelta = date1 - date2`` | \(3) |
++-------------------------------+----------------------------------------------+
+| ``date1 < date2`` | *date1* is considered less than *date2* when |
+| | *date1* precedes *date2* in time. (4) |
++-------------------------------+----------------------------------------------+
+
+Notes:
+
+(1)
+ *date2* is moved forward in time if ``timedelta.days > 0``, or backward if
+ ``timedelta.days < 0``. Afterward ``date2 - date1 == timedelta.days``.
+ ``timedelta.seconds`` and ``timedelta.microseconds`` are ignored.
+ :exc:`OverflowError` is raised if ``date2.year`` would be smaller than
+ :const:`MINYEAR` or larger than :const:`MAXYEAR`.
+
+(2)
+ This isn't quite equivalent to date1 + (-timedelta), because -timedelta in
+ isolation can overflow in cases where date1 - timedelta does not.
+ ``timedelta.seconds`` and ``timedelta.microseconds`` are ignored.
+
+(3)
+ This is exact, and cannot overflow. timedelta.seconds and
+ timedelta.microseconds are 0, and date2 + timedelta == date1 after.
+
+(4)
+ In other words, ``date1 < date2`` if and only if ``date1.toordinal() <
+ date2.toordinal()``. In order to stop comparison from falling back to the
+ default scheme of comparing object addresses, date comparison normally raises
+ :exc:`TypeError` if the other comparand isn't also a :class:`date` object.
+ However, ``NotImplemented`` is returned instead if the other comparand has a
+ :meth:`timetuple` attribute. This hook gives other kinds of date objects a
+ chance at implementing mixed-type comparison. If not, when a :class:`date`
+ object is compared to an object of a different type, :exc:`TypeError` is raised
+ unless the comparison is ``==`` or ``!=``. The latter cases return
+ :const:`False` or :const:`True`, respectively.
+
+Dates can be used as dictionary keys. In Boolean contexts, all :class:`date`
+objects are considered to be true.
+
+Instance methods:
+
+
+.. method:: date.replace(year, month, day)
+
+ Return a date with the same value, except for those members given new values by
+ whichever keyword arguments are specified. For example, if ``d == date(2002,
+ 12, 31)``, then ``d.replace(day=26) == date(2002, 12, 26)``.
+
+
+.. method:: date.timetuple()
+
+ Return a :class:`time.struct_time` such as returned by :func:`time.localtime`.
+ The hours, minutes and seconds are 0, and the DST flag is -1. ``d.timetuple()``
+ is equivalent to ``time.struct_time((d.year, d.month, d.day, 0, 0, 0,
+ d.weekday(), d.toordinal() - date(d.year, 1, 1).toordinal() + 1, -1))``
+
+
+.. method:: date.toordinal()
+
+ Return the proleptic Gregorian ordinal of the date, where January 1 of year 1
+ has ordinal 1. For any :class:`date` object *d*,
+ ``date.fromordinal(d.toordinal()) == d``.
+
+
+.. method:: date.weekday()
+
+ Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
+ For example, ``date(2002, 12, 4).weekday() == 2``, a Wednesday. See also
+ :meth:`isoweekday`.
+
+
+.. method:: date.isoweekday()
+
+ Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
+ For example, ``date(2002, 12, 4).isoweekday() == 3``, a Wednesday. See also
+ :meth:`weekday`, :meth:`isocalendar`.
+
+
+.. method:: date.isocalendar()
+
+ Return a 3-tuple, (ISO year, ISO week number, ISO weekday).
+
+ The ISO calendar is a widely used variant of the Gregorian calendar. See
+ http://www.phys.uu.nl/ vgent/calendar/isocalendar.htm for a good explanation.
+
+ The ISO year consists of 52 or 53 full weeks, and where a week starts on a
+ Monday and ends on a Sunday. The first week of an ISO year is the first
+ (Gregorian) calendar week of a year containing a Thursday. This is called week
+ number 1, and the ISO year of that Thursday is the same as its Gregorian year.
+
+ For example, 2004 begins on a Thursday, so the first week of ISO year 2004
+ begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004, so that
+ ``date(2003, 12, 29).isocalendar() == (2004, 1, 1)`` and ``date(2004, 1,
+ 4).isocalendar() == (2004, 1, 7)``.
+
+
+.. method:: date.isoformat()
+
+ Return a string representing the date in ISO 8601 format, 'YYYY-MM-DD'. For
+ example, ``date(2002, 12, 4).isoformat() == '2002-12-04'``.
+
+
+.. method:: date.__str__()
+
+ For a date *d*, ``str(d)`` is equivalent to ``d.isoformat()``.
+
+
+.. method:: date.ctime()
+
+ Return a string representing the date, for example ``date(2002, 12,
+ 4).ctime() == 'Wed Dec 4 00:00:00 2002'``. ``d.ctime()`` is equivalent to
+ ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the native C
+ :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which
+ :meth:`date.ctime` does not invoke) conforms to the C standard.
+
+
+.. method:: date.strftime(format)
+
+ Return a string representing the date, controlled by an explicit format string.
+ Format codes referring to hours, minutes or seconds will see 0 values. See
+ section :ref:`strftime-behavior`.
+
+
+.. _datetime-datetime:
+
+:class:`datetime` Objects
+-------------------------
+
+A :class:`datetime` object is a single object containing all the information
+from a :class:`date` object and a :class:`time` object. Like a :class:`date`
+object, :class:`datetime` assumes the current Gregorian calendar extended in
+both directions; like a time object, :class:`datetime` assumes there are exactly
+3600\*24 seconds in every day.
+
+Constructor:
+
+
+.. class:: datetime(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])
+
+ The year, month and day arguments are required. *tzinfo* may be ``None``, or an
+ instance of a :class:`tzinfo` subclass. The remaining arguments may be ints or
+ longs, in the following ranges:
+
+ * ``MINYEAR <= year <= MAXYEAR``
+ * ``1 <= month <= 12``
+ * ``1 <= day <= number of days in the given month and year``
+ * ``0 <= hour < 24``
+ * ``0 <= minute < 60``
+ * ``0 <= second < 60``
+ * ``0 <= microsecond < 1000000``
+
+ If an argument outside those ranges is given, :exc:`ValueError` is raised.
+
+Other constructors, all class methods:
+
+
+.. method:: datetime.today()
+
+ Return the current local datetime, with :attr:`tzinfo` ``None``. This is
+ equivalent to ``datetime.fromtimestamp(time.time())``. See also :meth:`now`,
+ :meth:`fromtimestamp`.
+
+
+.. method:: datetime.now([tz])
+
+ Return the current local date and time. If optional argument *tz* is ``None``
+ or not specified, this is like :meth:`today`, but, if possible, supplies more
+ precision than can be gotten from going through a :func:`time.time` timestamp
+ (for example, this may be possible on platforms supplying the C
+ :cfunc:`gettimeofday` function).
+
+ Else *tz* must be an instance of a class :class:`tzinfo` subclass, and the
+ current date and time are converted to *tz*'s time zone. In this case the
+ result is equivalent to ``tz.fromutc(datetime.utcnow().replace(tzinfo=tz))``.
+ See also :meth:`today`, :meth:`utcnow`.
+
+
+.. method:: datetime.utcnow()
+
+ Return the current UTC date and time, with :attr:`tzinfo` ``None``. This is like
+ :meth:`now`, but returns the current UTC date and time, as a naive
+ :class:`datetime` object. See also :meth:`now`.
+
+
+.. method:: datetime.fromtimestamp(timestamp[, tz])
+
+ Return the local date and time corresponding to the POSIX timestamp, such as is
+ returned by :func:`time.time`. If optional argument *tz* is ``None`` or not
+ specified, the timestamp is converted to the platform's local date and time, and
+ the returned :class:`datetime` object is naive.
+
+ Else *tz* must be an instance of a class :class:`tzinfo` subclass, and the
+ timestamp is converted to *tz*'s time zone. In this case the result is
+ equivalent to
+ ``tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(tzinfo=tz))``.
+
+ :meth:`fromtimestamp` may raise :exc:`ValueError`, if the timestamp is out of
+ the range of values supported by the platform C :cfunc:`localtime` or
+ :cfunc:`gmtime` functions. It's common for this to be restricted to years in
+ 1970 through 2038. Note that on non-POSIX systems that include leap seconds in
+ their notion of a timestamp, leap seconds are ignored by :meth:`fromtimestamp`,
+ and then it's possible to have two timestamps differing by a second that yield
+ identical :class:`datetime` objects. See also :meth:`utcfromtimestamp`.
+
+
+.. method:: datetime.utcfromtimestamp(timestamp)
+
+ Return the UTC :class:`datetime` corresponding to the POSIX timestamp, with
+ :attr:`tzinfo` ``None``. This may raise :exc:`ValueError`, if the timestamp is
+ out of the range of values supported by the platform C :cfunc:`gmtime` function.
+ It's common for this to be restricted to years in 1970 through 2038. See also
+ :meth:`fromtimestamp`.
+
+
+.. method:: datetime.fromordinal(ordinal)
+
+ Return the :class:`datetime` corresponding to the proleptic Gregorian ordinal,
+ where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1
+ <= ordinal <= datetime.max.toordinal()``. The hour, minute, second and
+ microsecond of the result are all 0, and :attr:`tzinfo` is ``None``.
+
+
+.. method:: datetime.combine(date, time)
+
+ Return a new :class:`datetime` object whose date members are equal to the given
+ :class:`date` object's, and whose time and :attr:`tzinfo` members are equal to
+ the given :class:`time` object's. For any :class:`datetime` object *d*, ``d ==
+ datetime.combine(d.date(), d.timetz())``. If date is a :class:`datetime`
+ object, its time and :attr:`tzinfo` members are ignored.
+
+
+.. method:: datetime.strptime(date_string, format)
+
+ Return a :class:`datetime` corresponding to *date_string*, parsed according to
+ *format*. This is equivalent to ``datetime(*(time.strptime(date_string,
+ format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format
+ can't be parsed by :func:`time.strptime` or if it returns a value which isn't a
+ time tuple.
+
+ .. versionadded:: 2.5
+
+Class attributes:
+
+
+.. attribute:: datetime.min
+
+ The earliest representable :class:`datetime`, ``datetime(MINYEAR, 1, 1,
+ tzinfo=None)``.
+
+
+.. attribute:: datetime.max
+
+ The latest representable :class:`datetime`, ``datetime(MAXYEAR, 12, 31, 23, 59,
+ 59, 999999, tzinfo=None)``.
+
+
+.. attribute:: datetime.resolution
+
+ The smallest possible difference between non-equal :class:`datetime` objects,
+ ``timedelta(microseconds=1)``.
+
+Instance attributes (read-only):
+
+
+.. attribute:: datetime.year
+
+ Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive.
+
+
+.. attribute:: datetime.month
+
+ Between 1 and 12 inclusive.
+
+
+.. attribute:: datetime.day
+
+ Between 1 and the number of days in the given month of the given year.
+
+
+.. attribute:: datetime.hour
+
+ In ``range(24)``.
+
+
+.. attribute:: datetime.minute
+
+ In ``range(60)``.
+
+
+.. attribute:: datetime.second
+
+ In ``range(60)``.
+
+
+.. attribute:: datetime.microsecond
+
+ In ``range(1000000)``.
+
+
+.. attribute:: datetime.tzinfo
+
+ The object passed as the *tzinfo* argument to the :class:`datetime` constructor,
+ or ``None`` if none was passed.
+
+Supported operations:
+
++---------------------------------------+-------------------------------+
+| Operation | Result |
++=======================================+===============================+
+| ``datetime2 = datetime1 + timedelta`` | \(1) |
++---------------------------------------+-------------------------------+
+| ``datetime2 = datetime1 - timedelta`` | \(2) |
++---------------------------------------+-------------------------------+
+| ``timedelta = datetime1 - datetime2`` | \(3) |
++---------------------------------------+-------------------------------+
+| ``datetime1 < datetime2`` | Compares :class:`datetime` to |
+| | :class:`datetime`. (4) |
++---------------------------------------+-------------------------------+
+
+(1)
+ datetime2 is a duration of timedelta removed from datetime1, moving forward in
+ time if ``timedelta.days`` > 0, or backward if ``timedelta.days`` < 0. The
+ result has the same :attr:`tzinfo` member as the input datetime, and datetime2 -
+ datetime1 == timedelta after. :exc:`OverflowError` is raised if datetime2.year
+ would be smaller than :const:`MINYEAR` or larger than :const:`MAXYEAR`. Note
+ that no time zone adjustments are done even if the input is an aware object.
+
+(2)
+ Computes the datetime2 such that datetime2 + timedelta == datetime1. As for
+ addition, the result has the same :attr:`tzinfo` member as the input datetime,
+ and no time zone adjustments are done even if the input is aware. This isn't
+ quite equivalent to datetime1 + (-timedelta), because -timedelta in isolation
+ can overflow in cases where datetime1 - timedelta does not.
+
+(3)
+ Subtraction of a :class:`datetime` from a :class:`datetime` is defined only if
+ both operands are naive, or if both are aware. If one is aware and the other is
+ naive, :exc:`TypeError` is raised.
+
+ If both are naive, or both are aware and have the same :attr:`tzinfo` member,
+ the :attr:`tzinfo` members are ignored, and the result is a :class:`timedelta`
+ object *t* such that ``datetime2 + t == datetime1``. No time zone adjustments
+ are done in this case.
+
+ If both are aware and have different :attr:`tzinfo` members, ``a-b`` acts as if
+ *a* and *b* were first converted to naive UTC datetimes first. The result is
+ ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) -
+ b.utcoffset())`` except that the implementation never overflows.
+
+(4)
+ *datetime1* is considered less than *datetime2* when *datetime1* precedes
+ *datetime2* in time.
+
+ If one comparand is naive and the other is aware, :exc:`TypeError` is raised.
+ If both comparands are aware, and have the same :attr:`tzinfo` member, the
+ common :attr:`tzinfo` member is ignored and the base datetimes are compared. If
+ both comparands are aware and have different :attr:`tzinfo` members, the
+ comparands are first adjusted by subtracting their UTC offsets (obtained from
+ ``self.utcoffset()``).
+
+ .. note::
+
+ In order to stop comparison from falling back to the default scheme of comparing
+ object addresses, datetime comparison normally raises :exc:`TypeError` if the
+ other comparand isn't also a :class:`datetime` object. However,
+ ``NotImplemented`` is returned instead if the other comparand has a
+ :meth:`timetuple` attribute. This hook gives other kinds of date objects a
+ chance at implementing mixed-type comparison. If not, when a :class:`datetime`
+ object is compared to an object of a different type, :exc:`TypeError` is raised
+ unless the comparison is ``==`` or ``!=``. The latter cases return
+ :const:`False` or :const:`True`, respectively.
+
+:class:`datetime` objects can be used as dictionary keys. In Boolean contexts,
+all :class:`datetime` objects are considered to be true.
+
+Instance methods:
+
+
+.. method:: datetime.date()
+
+ Return :class:`date` object with same year, month and day.
+
+
+.. method:: datetime.time()
+
+ Return :class:`time` object with same hour, minute, second and microsecond.
+ :attr:`tzinfo` is ``None``. See also method :meth:`timetz`.
+
+
+.. method:: datetime.timetz()
+
+ Return :class:`time` object with same hour, minute, second, microsecond, and
+ tzinfo members. See also method :meth:`time`.
+
+
+.. method:: datetime.replace([year[, month[, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]]]]])
+
+ Return a datetime with the same members, except for those members given new
+ values by whichever keyword arguments are specified. Note that ``tzinfo=None``
+ can be specified to create a naive datetime from an aware datetime with no
+ conversion of date and time members.
+
+
+.. method:: datetime.astimezone(tz)
+
+ Return a :class:`datetime` object with new :attr:`tzinfo` member *tz*, adjusting
+ the date and time members so the result is the same UTC time as *self*, but in
+ *tz*'s local time.
+
+ *tz* must be an instance of a :class:`tzinfo` subclass, and its
+ :meth:`utcoffset` and :meth:`dst` methods must not return ``None``. *self* must
+ be aware (``self.tzinfo`` must not be ``None``, and ``self.utcoffset()`` must
+ not return ``None``).
+
+ If ``self.tzinfo`` is *tz*, ``self.astimezone(tz)`` is equal to *self*: no
+ adjustment of date or time members is performed. Else the result is local time
+ in time zone *tz*, representing the same UTC time as *self*: after ``astz =
+ dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will usually have the same date
+ and time members as ``dt - dt.utcoffset()``. The discussion of class
+ :class:`tzinfo` explains the cases at Daylight Saving Time transition boundaries
+ where this cannot be achieved (an issue only if *tz* models both standard and
+ daylight time).
+
+ If you merely want to attach a time zone object *tz* to a datetime *dt* without
+ adjustment of date and time members, use ``dt.replace(tzinfo=tz)``. If you
+ merely want to remove the time zone object from an aware datetime *dt* without
+ conversion of date and time members, use ``dt.replace(tzinfo=None)``.
+
+ Note that the default :meth:`tzinfo.fromutc` method can be overridden in a
+ :class:`tzinfo` subclass to affect the result returned by :meth:`astimezone`.
+ Ignoring error cases, :meth:`astimezone` acts like::
+
+ def astimezone(self, tz):
+ if self.tzinfo is tz:
+ return self
+ # Convert self to UTC, and attach the new time zone object.
+ utc = (self - self.utcoffset()).replace(tzinfo=tz)
+ # Convert from UTC to tz's local time.
+ return tz.fromutc(utc)
+
+
+.. method:: datetime.utcoffset()
+
+ If :attr:`tzinfo` is ``None``, returns ``None``, else returns
+ ``self.tzinfo.utcoffset(self)``, and raises an exception if the latter doesn't
+ return ``None``, or a :class:`timedelta` object representing a whole number of
+ minutes with magnitude less than one day.
+
+
+.. method:: datetime.dst()
+
+ If :attr:`tzinfo` is ``None``, returns ``None``, else returns
+ ``self.tzinfo.dst(self)``, and raises an exception if the latter doesn't return
+ ``None``, or a :class:`timedelta` object representing a whole number of minutes
+ with magnitude less than one day.
+
+
+.. method:: datetime.tzname()
+
+ If :attr:`tzinfo` is ``None``, returns ``None``, else returns
+ ``self.tzinfo.tzname(self)``, raises an exception if the latter doesn't return
+ ``None`` or a string object,
+
+
+.. method:: datetime.timetuple()
+
+ Return a :class:`time.struct_time` such as returned by :func:`time.localtime`.
+ ``d.timetuple()`` is equivalent to ``time.struct_time((d.year, d.month, d.day,
+ d.hour, d.minute, d.second, d.weekday(), d.toordinal() - date(d.year, 1,
+ 1).toordinal() + 1, dst))`` The :attr:`tm_isdst` flag of the result is set
+ according to the :meth:`dst` method: :attr:`tzinfo` is ``None`` or :meth:`dst`
+ returns ``None``, :attr:`tm_isdst` is set to ``-1``; else if :meth:`dst`
+ returns a non-zero value, :attr:`tm_isdst` is set to ``1``; else ``tm_isdst`` is
+ set to ``0``.
+
+
+.. method:: datetime.utctimetuple()
+
+ If :class:`datetime` instance *d* is naive, this is the same as
+ ``d.timetuple()`` except that :attr:`tm_isdst` is forced to 0 regardless of what
+ ``d.dst()`` returns. DST is never in effect for a UTC time.
+
+ If *d* is aware, *d* is normalized to UTC time, by subtracting
+ ``d.utcoffset()``, and a :class:`time.struct_time` for the normalized time is
+ returned. :attr:`tm_isdst` is forced to 0. Note that the result's
+ :attr:`tm_year` member may be :const:`MINYEAR`\ -1 or :const:`MAXYEAR`\ +1, if
+ *d*.year was ``MINYEAR`` or ``MAXYEAR`` and UTC adjustment spills over a year
+ boundary.
+
+
+.. method:: datetime.toordinal()
+
+ Return the proleptic Gregorian ordinal of the date. The same as
+ ``self.date().toordinal()``.
+
+
+.. method:: datetime.weekday()
+
+ Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
+ The same as ``self.date().weekday()``. See also :meth:`isoweekday`.
+
+
+.. method:: datetime.isoweekday()
+
+ Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
+ The same as ``self.date().isoweekday()``. See also :meth:`weekday`,
+ :meth:`isocalendar`.
+
+
+.. method:: datetime.isocalendar()
+
+ Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The same as
+ ``self.date().isocalendar()``.
+
+
+.. method:: datetime.isoformat([sep])
+
+ Return a string representing the date and time in ISO 8601 format,
+ YYYY-MM-DDTHH:MM:SS.mmmmmm or, if :attr:`microsecond` is 0,
+ YYYY-MM-DDTHH:MM:SS
+
+ If :meth:`utcoffset` does not return ``None``, a 6-character string is
+ appended, giving the UTC offset in (signed) hours and minutes:
+ YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM or, if :attr:`microsecond` is 0
+ YYYY-MM-DDTHH:MM:SS+HH:MM
+
+ The optional argument *sep* (default ``'T'``) is a one-character separator,
+ placed between the date and time portions of the result. For example, ::
+
+ >>> from datetime import tzinfo, timedelta, datetime
+ >>> class TZ(tzinfo):
+ ... def utcoffset(self, dt): return timedelta(minutes=-399)
+ ...
+ >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
+ '2002-12-25 00:00:00-06:39'
+
+
+.. method:: datetime.__str__()
+
+ For a :class:`datetime` instance *d*, ``str(d)`` is equivalent to
+ ``d.isoformat(' ')``.
+
+
+.. method:: datetime.ctime()
+
+ Return a string representing the date and time, for example ``datetime(2002, 12,
+ 4, 20, 30, 40).ctime() == 'Wed Dec 4 20:30:40 2002'``. ``d.ctime()`` is
+ equivalent to ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the
+ native C :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which
+ :meth:`datetime.ctime` does not invoke) conforms to the C standard.
+
+
+.. method:: datetime.strftime(format)
+
+ Return a string representing the date and time, controlled by an explicit format
+ string. See section :ref:`strftime-behavior`.
+
+
+.. _datetime-time:
+
+:class:`time` Objects
+---------------------
+
+A time object represents a (local) time of day, independent of any particular
+day, and subject to adjustment via a :class:`tzinfo` object.
+
+
+.. class:: time(hour[, minute[, second[, microsecond[, tzinfo]]]])
+
+ All arguments are optional. *tzinfo* may be ``None``, or an instance of a
+ :class:`tzinfo` subclass. The remaining arguments may be ints or longs, in the
+ following ranges:
+
+ * ``0 <= hour < 24``
+ * ``0 <= minute < 60``
+ * ``0 <= second < 60``
+ * ``0 <= microsecond < 1000000``.
+
+ If an argument outside those ranges is given, :exc:`ValueError` is raised. All
+ default to ``0`` except *tzinfo*, which defaults to :const:`None`.
+
+Class attributes:
+
+
+.. attribute:: time.min
+
+ The earliest representable :class:`time`, ``time(0, 0, 0, 0)``.
+
+
+.. attribute:: time.max
+
+ The latest representable :class:`time`, ``time(23, 59, 59, 999999)``.
+
+
+.. attribute:: time.resolution
+
+ The smallest possible difference between non-equal :class:`time` objects,
+ ``timedelta(microseconds=1)``, although note that arithmetic on :class:`time`
+ objects is not supported.
+
+Instance attributes (read-only):
+
+
+.. attribute:: time.hour
+
+ In ``range(24)``.
+
+
+.. attribute:: time.minute
+
+ In ``range(60)``.
+
+
+.. attribute:: time.second
+
+ In ``range(60)``.
+
+
+.. attribute:: time.microsecond
+
+ In ``range(1000000)``.
+
+
+.. attribute:: time.tzinfo
+
+ The object passed as the tzinfo argument to the :class:`time` constructor, or
+ ``None`` if none was passed.
+
+Supported operations:
+
+* comparison of :class:`time` to :class:`time`, where *a* is considered less
+ than *b* when *a* precedes *b* in time. If one comparand is naive and the other
+ is aware, :exc:`TypeError` is raised. If both comparands are aware, and have
+ the same :attr:`tzinfo` member, the common :attr:`tzinfo` member is ignored and
+ the base times are compared. If both comparands are aware and have different
+ :attr:`tzinfo` members, the comparands are first adjusted by subtracting their
+ UTC offsets (obtained from ``self.utcoffset()``). In order to stop mixed-type
+ comparisons from falling back to the default comparison by object address, when
+ a :class:`time` object is compared to an object of a different type,
+ :exc:`TypeError` is raised unless the comparison is ``==`` or ``!=``. The
+ latter cases return :const:`False` or :const:`True`, respectively.
+
+* hash, use as dict key
+
+* efficient pickling
+
+* in Boolean contexts, a :class:`time` object is considered to be true if and
+ only if, after converting it to minutes and subtracting :meth:`utcoffset` (or
+ ``0`` if that's ``None``), the result is non-zero.
+
+Instance methods:
+
+
+.. method:: time.replace([hour[, minute[, second[, microsecond[, tzinfo]]]]])
+
+ Return a :class:`time` with the same value, except for those members given new
+ values by whichever keyword arguments are specified. Note that ``tzinfo=None``
+ can be specified to create a naive :class:`time` from an aware :class:`time`,
+ without conversion of the time members.
+
+
+.. method:: time.isoformat()
+
+ Return a string representing the time in ISO 8601 format, HH:MM:SS.mmmmmm or, if
+ self.microsecond is 0, HH:MM:SS If :meth:`utcoffset` does not return ``None``, a
+ 6-character string is appended, giving the UTC offset in (signed) hours and
+ minutes: HH:MM:SS.mmmmmm+HH:MM or, if self.microsecond is 0, HH:MM:SS+HH:MM
+
+
+.. method:: time.__str__()
+
+ For a time *t*, ``str(t)`` is equivalent to ``t.isoformat()``.
+
+
+.. method:: time.strftime(format)
+
+ Return a string representing the time, controlled by an explicit format string.
+ See section :ref:`strftime-behavior`.
+
+
+.. method:: time.utcoffset()
+
+ If :attr:`tzinfo` is ``None``, returns ``None``, else returns
+ ``self.tzinfo.utcoffset(None)``, and raises an exception if the latter doesn't
+ return ``None`` or a :class:`timedelta` object representing a whole number of
+ minutes with magnitude less than one day.
+
+
+.. method:: time.dst()
+
+ If :attr:`tzinfo` is ``None``, returns ``None``, else returns
+ ``self.tzinfo.dst(None)``, and raises an exception if the latter doesn't return
+ ``None``, or a :class:`timedelta` object representing a whole number of minutes
+ with magnitude less than one day.
+
+
+.. method:: time.tzname()
+
+ If :attr:`tzinfo` is ``None``, returns ``None``, else returns
+ ``self.tzinfo.tzname(None)``, or raises an exception if the latter doesn't
+ return ``None`` or a string object.
+
+
+.. _datetime-tzinfo:
+
+:class:`tzinfo` Objects
+-----------------------
+
+:class:`tzinfo` is an abstract base clase, meaning that this class should not be
+instantiated directly. You need to derive a concrete subclass, and (at least)
+supply implementations of the standard :class:`tzinfo` methods needed by the
+:class:`datetime` methods you use. The :mod:`datetime` module does not supply
+any concrete subclasses of :class:`tzinfo`.
+
+An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the
+constructors for :class:`datetime` and :class:`time` objects. The latter objects
+view their members as being in local time, and the :class:`tzinfo` object
+supports methods revealing offset of local time from UTC, the name of the time
+zone, and DST offset, all relative to a date or time object passed to them.
+
+Special requirement for pickling: A :class:`tzinfo` subclass must have an
+:meth:`__init__` method that can be called with no arguments, else it can be
+pickled but possibly not unpickled again. This is a technical requirement that
+may be relaxed in the future.
+
+A concrete subclass of :class:`tzinfo` may need to implement the following
+methods. Exactly which methods are needed depends on the uses made of aware
+:mod:`datetime` objects. If in doubt, simply implement all of them.
+
+
+.. method:: tzinfo.utcoffset(self, dt)
+
+ Return offset of local time from UTC, in minutes east of UTC. If local time is
+ west of UTC, this should be negative. Note that this is intended to be the
+ total offset from UTC; for example, if a :class:`tzinfo` object represents both
+ time zone and DST adjustments, :meth:`utcoffset` should return their sum. If
+ the UTC offset isn't known, return ``None``. Else the value returned must be a
+ :class:`timedelta` object specifying a whole number of minutes in the range
+ -1439 to 1439 inclusive (1440 = 24\*60; the magnitude of the offset must be less
+ than one day). Most implementations of :meth:`utcoffset` will probably look
+ like one of these two::
+
+ return CONSTANT # fixed-offset class
+ return CONSTANT + self.dst(dt) # daylight-aware class
+
+ If :meth:`utcoffset` does not return ``None``, :meth:`dst` should not return
+ ``None`` either.
+
+ The default implementation of :meth:`utcoffset` raises
+ :exc:`NotImplementedError`.
+
+
+.. method:: tzinfo.dst(self, dt)
+
+ Return the daylight saving time (DST) adjustment, in minutes east of UTC, or
+ ``None`` if DST information isn't known. Return ``timedelta(0)`` if DST is not
+ in effect. If DST is in effect, return the offset as a :class:`timedelta` object
+ (see :meth:`utcoffset` for details). Note that DST offset, if applicable, has
+ already been added to the UTC offset returned by :meth:`utcoffset`, so there's
+ no need to consult :meth:`dst` unless you're interested in obtaining DST info
+ separately. For example, :meth:`datetime.timetuple` calls its :attr:`tzinfo`
+ member's :meth:`dst` method to determine how the :attr:`tm_isdst` flag should be
+ set, and :meth:`tzinfo.fromutc` calls :meth:`dst` to account for DST changes
+ when crossing time zones.
+
+ An instance *tz* of a :class:`tzinfo` subclass that models both standard and
+ daylight times must be consistent in this sense:
+
+ ``tz.utcoffset(dt) - tz.dst(dt)``
+
+ must return the same result for every :class:`datetime` *dt* with ``dt.tzinfo ==
+ tz`` For sane :class:`tzinfo` subclasses, this expression yields the time
+ zone's "standard offset", which should not depend on the date or the time, but
+ only on geographic location. The implementation of :meth:`datetime.astimezone`
+ relies on this, but cannot detect violations; it's the programmer's
+ responsibility to ensure it. If a :class:`tzinfo` subclass cannot guarantee
+ this, it may be able to override the default implementation of
+ :meth:`tzinfo.fromutc` to work correctly with :meth:`astimezone` regardless.
+
+ Most implementations of :meth:`dst` will probably look like one of these two::
+
+ def dst(self):
+ # a fixed-offset class: doesn't account for DST
+ return timedelta(0)
+
+ or ::
+
+ def dst(self):
+ # Code to set dston and dstoff to the time zone's DST
+ # transition times based on the input dt.year, and expressed
+ # in standard local time. Then
+
+ if dston <= dt.replace(tzinfo=None) < dstoff:
+ return timedelta(hours=1)
+ else:
+ return timedelta(0)
+
+ The default implementation of :meth:`dst` raises :exc:`NotImplementedError`.
+
+
+.. method:: tzinfo.tzname(self, dt)
+
+ Return the time zone name corresponding to the :class:`datetime` object *dt*, as
+ a string. Nothing about string names is defined by the :mod:`datetime` module,
+ and there's no requirement that it mean anything in particular. For example,
+ "GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" are all
+ valid replies. Return ``None`` if a string name isn't known. Note that this is
+ a method rather than a fixed string primarily because some :class:`tzinfo`
+ subclasses will wish to return different names depending on the specific value
+ of *dt* passed, especially if the :class:`tzinfo` class is accounting for
+ daylight time.
+
+ The default implementation of :meth:`tzname` raises :exc:`NotImplementedError`.
+
+These methods are called by a :class:`datetime` or :class:`time` object, in
+response to their methods of the same names. A :class:`datetime` object passes
+itself as the argument, and a :class:`time` object passes ``None`` as the
+argument. A :class:`tzinfo` subclass's methods should therefore be prepared to
+accept a *dt* argument of ``None``, or of class :class:`datetime`.
+
+When ``None`` is passed, it's up to the class designer to decide the best
+response. For example, returning ``None`` is appropriate if the class wishes to
+say that time objects don't participate in the :class:`tzinfo` protocols. It
+may be more useful for ``utcoffset(None)`` to return the standard UTC offset, as
+there is no other convention for discovering the standard offset.
+
+When a :class:`datetime` object is passed in response to a :class:`datetime`
+method, ``dt.tzinfo`` is the same object as *self*. :class:`tzinfo` methods can
+rely on this, unless user code calls :class:`tzinfo` methods directly. The
+intent is that the :class:`tzinfo` methods interpret *dt* as being in local
+time, and not need worry about objects in other timezones.
+
+There is one more :class:`tzinfo` method that a subclass may wish to override:
+
+
+.. method:: tzinfo.fromutc(self, dt)
+
+ This is called from the default :class:`datetime.astimezone()` implementation.
+ When called from that, ``dt.tzinfo`` is *self*, and *dt*'s date and time members
+ are to be viewed as expressing a UTC time. The purpose of :meth:`fromutc` is to
+ adjust the date and time members, returning an equivalent datetime in *self*'s
+ local time.
+
+ Most :class:`tzinfo` subclasses should be able to inherit the default
+ :meth:`fromutc` implementation without problems. It's strong enough to handle
+ fixed-offset time zones, and time zones accounting for both standard and
+ daylight time, and the latter even if the DST transition times differ in
+ different years. An example of a time zone the default :meth:`fromutc`
+ implementation may not handle correctly in all cases is one where the standard
+ offset (from UTC) depends on the specific date and time passed, which can happen
+ for political reasons. The default implementations of :meth:`astimezone` and
+ :meth:`fromutc` may not produce the result you want if the result is one of the
+ hours straddling the moment the standard offset changes.
+
+ Skipping code for error cases, the default :meth:`fromutc` implementation acts
+ like::
+
+ def fromutc(self, dt):
+ # raise ValueError error if dt.tzinfo is not self
+ dtoff = dt.utcoffset()
+ dtdst = dt.dst()
+ # raise ValueError if dtoff is None or dtdst is None
+ delta = dtoff - dtdst # this is self's standard offset
+ if delta:
+ dt += delta # convert to standard local time
+ dtdst = dt.dst()
+ # raise ValueError if dtdst is None
+ if dtdst:
+ return dt + dtdst
+ else:
+ return dt
+
+Example :class:`tzinfo` classes:
+
+.. literalinclude:: ../includes/tzinfo-examples.py
+
+
+Note that there are unavoidable subtleties twice per year in a :class:`tzinfo`
+subclass accounting for both standard and daylight time, at the DST transition
+points. For concreteness, consider US Eastern (UTC -0500), where EDT begins the
+minute after 1:59 (EST) on the first Sunday in April, and ends the minute after
+1:59 (EDT) on the last Sunday in October::
+
+ UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM
+ EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM
+ EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM
+
+ start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM
+
+ end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM
+
+When DST starts (the "start" line), the local wall clock leaps from 1:59 to
+3:00. A wall time of the form 2:MM doesn't really make sense on that day, so
+``astimezone(Eastern)`` won't deliver a result with ``hour == 2`` on the day DST
+begins. In order for :meth:`astimezone` to make this guarantee, the
+:meth:`rzinfo.dst` method must consider times in the "missing hour" (2:MM for
+Eastern) to be in daylight time.
+
+When DST ends (the "end" line), there's a potentially worse problem: there's an
+hour that can't be spelled unambiguously in local wall time: the last hour of
+daylight time. In Eastern, that's times of the form 5:MM UTC on the day
+daylight time ends. The local wall clock leaps from 1:59 (daylight time) back
+to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous.
+:meth:`astimezone` mimics the local clock's behavior by mapping two adjacent UTC
+hours into the same local hour then. In the Eastern example, UTC times of the
+form 5:MM and 6:MM both map to 1:MM when converted to Eastern. In order for
+:meth:`astimezone` to make this guarantee, the :meth:`tzinfo.dst` method must
+consider times in the "repeated hour" to be in standard time. This is easily
+arranged, as in the example, by expressing DST switch times in the time zone's
+standard local time.
+
+Applications that can't bear such ambiguities should avoid using hybrid
+:class:`tzinfo` subclasses; there are no ambiguities when using UTC, or any
+other fixed-offset :class:`tzinfo` subclass (such as a class representing only
+EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).
+
+
+.. _strftime-behavior:
+
+:meth:`strftime` Behavior
+-------------------------
+
+:class:`date`, :class:`datetime`, and :class:`time` objects all support a
+``strftime(format)`` method, to create a string representing the time under the
+control of an explicit format string. Broadly speaking, ``d.strftime(fmt)``
+acts like the :mod:`time` module's ``time.strftime(fmt, d.timetuple())``
+although not all objects support a :meth:`timetuple` method.
+
+For :class:`time` objects, the format codes for year, month, and day should not
+be used, as time objects have no such values. If they're used anyway, ``1900``
+is substituted for the year, and ``0`` for the month and day.
+
+For :class:`date` objects, the format codes for hours, minutes, and seconds
+should not be used, as :class:`date` objects have no such values. If they're
+used anyway, ``0`` is substituted for them.
+
+For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty
+strings.
+
+For an aware object:
+
+``%z``
+ :meth:`utcoffset` is transformed into a 5-character string of the form +HHMM or
+ -HHMM, where HH is a 2-digit string giving the number of UTC offset hours, and
+ MM is a 2-digit string giving the number of UTC offset minutes. For example, if
+ :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is
+ replaced with the string ``'-0330'``.
+
+``%Z``
+ If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty string.
+ Otherwise ``%Z`` is replaced by the returned value, which must be a string.
+
+The full set of format codes supported varies across platforms, because Python
+calls the platform C library's :func:`strftime` function, and platform
+variations are common. The documentation for Python's :mod:`time` module lists
+the format codes that the C standard (1989 version) requires, and those work on
+all platforms with a standard C implementation. Note that the 1999 version of
+the C standard added additional format codes.
+
+The exact range of years for which :meth:`strftime` works also varies across
+platforms. Regardless of platform, years before 1900 cannot be used.
+
+.. % %% This example is obsolete, since strptime is now supported by datetime.
+.. %
+.. % \subsection{Examples}
+.. %
+.. % \subsubsection{Creating Datetime Objects from Formatted Strings}
+.. %
+.. % The \class{datetime} class does not directly support parsing formatted time
+.. % strings. You can use \function{time.strptime} to do the parsing and create
+.. % a \class{datetime} object from the tuple it returns:
+.. %
+.. % \begin{verbatim}
+.. % >>> s = "2005-12-06T12:13:14"
+.. % >>> from datetime import datetime
+.. % >>> from time import strptime
+.. % >>> datetime(*strptime(s, "%Y-%m-%dT%H:%M:%S")[0:6])
+.. % datetime.datetime(2005, 12, 6, 12, 13, 14)
+.. % \end{verbatim}
+.. %
+
--- /dev/null
+
+:mod:`dbhash` --- DBM-style interface to the BSD database library
+=================================================================
+
+.. module:: dbhash
+ :synopsis: DBM-style interface to the BSD database library.
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+.. index:: module: bsddb
+
+The :mod:`dbhash` module provides a function to open databases using the BSD
+``db`` library. This module mirrors the interface of the other Python database
+modules that provide access to DBM-style databases. The :mod:`bsddb` module is
+required to use :mod:`dbhash`.
+
+This module provides an exception and a function:
+
+
+.. exception:: error
+
+ Exception raised on database errors other than :exc:`KeyError`. It is a synonym
+ for :exc:`bsddb.error`.
+
+
+.. function:: open(path[, flag[, mode]])
+
+ Open a ``db`` database and return the database object. The *path* argument is
+ the name of the database file.
+
+ The *flag* argument can be:
+
+ +---------+-------------------------------------------+
+ | Value | Meaning |
+ +=========+===========================================+
+ | ``'r'`` | Open existing database for reading only |
+ | | (default) |
+ +---------+-------------------------------------------+
+ | ``'w'`` | Open existing database for reading and |
+ | | writing |
+ +---------+-------------------------------------------+
+ | ``'c'`` | Open database for reading and writing, |
+ | | creating it if it doesn't exist |
+ +---------+-------------------------------------------+
+ | ``'n'`` | Always create a new, empty database, open |
+ | | for reading and writing |
+ +---------+-------------------------------------------+
+
+ For platforms on which the BSD ``db`` library supports locking, an ``'l'``
+ can be appended to indicate that locking should be used.
+
+ The optional *mode* parameter is used to indicate the Unix permission bits that
+ should be set if a new database must be created; this will be masked by the
+ current umask value for the process.
+
+
+.. seealso::
+
+ Module :mod:`anydbm`
+ Generic interface to ``dbm``\ -style databases.
+
+ Module :mod:`bsddb`
+ Lower-level interface to the BSD ``db`` library.
+
+ Module :mod:`whichdb`
+ Utility module used to determine the type of an existing database.
+
+
+.. _dbhash-objects:
+
+Database Objects
+----------------
+
+The database objects returned by :func:`open` provide the methods common to all
+the DBM-style databases and mapping objects. The following methods are
+available in addition to the standard methods.
+
+
+.. method:: dbhash.first()
+
+ It's possible to loop over every key/value pair in the database using this
+ method and the :meth:`next` method. The traversal is ordered by the databases
+ internal hash values, and won't be sorted by the key values. This method
+ returns the starting key.
+
+
+.. method:: dbhash.last()
+
+ Return the last key/value pair in a database traversal. This may be used to
+ begin a reverse-order traversal; see :meth:`previous`.
+
+
+.. method:: dbhash.next()
+
+ Returns the key next key/value pair in a database traversal. The following code
+ prints every key in the database ``db``, without having to create a list in
+ memory that contains them all::
+
+ print db.first()
+ for i in xrange(1, len(db)):
+ print db.next()
+
+
+.. method:: dbhash.previous()
+
+ Returns the previous key/value pair in a forward-traversal of the database. In
+ conjunction with :meth:`last`, this may be used to implement a reverse-order
+ traversal.
+
+
+.. method:: dbhash.sync()
+
+ This method forces any unwritten data to be written to the disk.
+
--- /dev/null
+
+:mod:`dbm` --- Simple "database" interface
+==========================================
+
+.. module:: dbm
+ :platform: Unix
+ :synopsis: The standard "database" interface, based on ndbm.
+
+
+The :mod:`dbm` module provides an interface to the Unix "(n)dbm" library. Dbm
+objects behave like mappings (dictionaries), except that keys and values are
+always strings. Printing a dbm object doesn't print the keys and values, and the
+:meth:`items` and :meth:`values` methods are not supported.
+
+This module can be used with the "classic" ndbm interface, the BSD DB
+compatibility interface, or the GNU GDBM compatibility interface. On Unix, the
+:program:`configure` script will attempt to locate the appropriate header file
+to simplify building this module.
+
+The module defines the following:
+
+
+.. exception:: error
+
+ Raised on dbm-specific errors, such as I/O errors. :exc:`KeyError` is raised for
+ general mapping errors like specifying an incorrect key.
+
+
+.. data:: library
+
+ Name of the ``ndbm`` implementation library used.
+
+
+.. function:: open(filename[, flag[, mode]])
+
+ Open a dbm database and return a dbm object. The *filename* argument is the
+ name of the database file (without the :file:`.dir` or :file:`.pag` extensions;
+ note that the BSD DB implementation of the interface will append the extension
+ :file:`.db` and only create one file).
+
+ The optional *flag* argument must be one of these values:
+
+ +---------+-------------------------------------------+
+ | Value | Meaning |
+ +=========+===========================================+
+ | ``'r'`` | Open existing database for reading only |
+ | | (default) |
+ +---------+-------------------------------------------+
+ | ``'w'`` | Open existing database for reading and |
+ | | writing |
+ +---------+-------------------------------------------+
+ | ``'c'`` | Open database for reading and writing, |
+ | | creating it if it doesn't exist |
+ +---------+-------------------------------------------+
+ | ``'n'`` | Always create a new, empty database, open |
+ | | for reading and writing |
+ +---------+-------------------------------------------+
+
+ The optional *mode* argument is the Unix mode of the file, used only when the
+ database has to be created. It defaults to octal ``0666`` (and will be
+ modified by the prevailing umask).
+
+
+.. seealso::
+
+ Module :mod:`anydbm`
+ Generic interface to ``dbm``\ -style databases.
+
+ Module :mod:`gdbm`
+ Similar interface to the GNU GDBM library.
+
+ Module :mod:`whichdb`
+ Utility module used to determine the type of an existing database.
+
--- /dev/null
+
+:mod:`decimal` --- Decimal floating point arithmetic
+====================================================
+
+.. module:: decimal
+ :synopsis: Implementation of the General Decimal Arithmetic Specification.
+
+
+.. moduleauthor:: Eric Price <eprice at tjhsst.edu>
+.. moduleauthor:: Facundo Batista <facundo at taniquetil.com.ar>
+.. moduleauthor:: Raymond Hettinger <python at rcn.com>
+.. moduleauthor:: Aahz <aahz at pobox.com>
+.. moduleauthor:: Tim Peters <tim.one at comcast.net>
+
+
+.. sectionauthor:: Raymond D. Hettinger <python at rcn.com>
+
+
+.. versionadded:: 2.4
+
+The :mod:`decimal` module provides support for decimal floating point
+arithmetic. It offers several advantages over the :class:`float()` datatype:
+
+* Decimal numbers can be represented exactly. In contrast, numbers like
+ :const:`1.1` do not have an exact representation in binary floating point. End
+ users typically would not expect :const:`1.1` to display as
+ :const:`1.1000000000000001` as it does with binary floating point.
+
+* The exactness carries over into arithmetic. In decimal floating point, ``0.1
+ + 0.1 + 0.1 - 0.3`` is exactly equal to zero. In binary floating point, result
+ is :const:`5.5511151231257827e-017`. While near to zero, the differences
+ prevent reliable equality testing and differences can accumulate. For this
+ reason, decimal would be preferred in accounting applications which have strict
+ equality invariants.
+
+* The decimal module incorporates a notion of significant places so that ``1.30
+ + 1.20`` is :const:`2.50`. The trailing zero is kept to indicate significance.
+ This is the customary presentation for monetary applications. For
+ multiplication, the "schoolbook" approach uses all the figures in the
+ multiplicands. For instance, ``1.3 * 1.2`` gives :const:`1.56` while ``1.30 *
+ 1.20`` gives :const:`1.5600`.
+
+* Unlike hardware based binary floating point, the decimal module has a user
+ settable precision (defaulting to 28 places) which can be as large as needed for
+ a given problem::
+
+ >>> getcontext().prec = 6
+ >>> Decimal(1) / Decimal(7)
+ Decimal("0.142857")
+ >>> getcontext().prec = 28
+ >>> Decimal(1) / Decimal(7)
+ Decimal("0.1428571428571428571428571429")
+
+* Both binary and decimal floating point are implemented in terms of published
+ standards. While the built-in float type exposes only a modest portion of its
+ capabilities, the decimal module exposes all required parts of the standard.
+ When needed, the programmer has full control over rounding and signal handling.
+
+The module design is centered around three concepts: the decimal number, the
+context for arithmetic, and signals.
+
+A decimal number is immutable. It has a sign, coefficient digits, and an
+exponent. To preserve significance, the coefficient digits do not truncate
+trailing zeroes. Decimals also include special values such as
+:const:`Infinity`, :const:`-Infinity`, and :const:`NaN`. The standard also
+differentiates :const:`-0` from :const:`+0`.
+
+The context for arithmetic is an environment specifying precision, rounding
+rules, limits on exponents, flags indicating the results of operations, and trap
+enablers which determine whether signals are treated as exceptions. Rounding
+options include :const:`ROUND_CEILING`, :const:`ROUND_DOWN`,
+:const:`ROUND_FLOOR`, :const:`ROUND_HALF_DOWN`, :const:`ROUND_HALF_EVEN`,
+:const:`ROUND_HALF_UP`, and :const:`ROUND_UP`.
+
+Signals are groups of exceptional conditions arising during the course of
+computation. Depending on the needs of the application, signals may be ignored,
+considered as informational, or treated as exceptions. The signals in the
+decimal module are: :const:`Clamped`, :const:`InvalidOperation`,
+:const:`DivisionByZero`, :const:`Inexact`, :const:`Rounded`, :const:`Subnormal`,
+:const:`Overflow`, and :const:`Underflow`.
+
+For each signal there is a flag and a trap enabler. When a signal is
+encountered, its flag is incremented from zero and, then, if the trap enabler is
+set to one, an exception is raised. Flags are sticky, so the user needs to
+reset them before monitoring a calculation.
+
+
+.. seealso::
+
+ IBM's General Decimal Arithmetic Specification, `The General Decimal Arithmetic
+ Specification <http://www2.hursley.ibm.com/decimal/decarith.html>`_.
+
+ IEEE standard 854-1987, `Unofficial IEEE 854 Text
+ <http://www.cs.berkeley.edu/~ejr/projects/754/private/drafts/854-1987/dir.html>`_.
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-tutorial:
+
+Quick-start Tutorial
+--------------------
+
+The usual start to using decimals is importing the module, viewing the current
+context with :func:`getcontext` and, if necessary, setting new values for
+precision, rounding, or enabled traps::
+
+ >>> from decimal import *
+ >>> getcontext()
+ Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
+ capitals=1, flags=[], traps=[Overflow, InvalidOperation,
+ DivisionByZero])
+
+ >>> getcontext().prec = 7 # Set a new precision
+
+Decimal instances can be constructed from integers, strings, or tuples. To
+create a Decimal from a :class:`float`, first convert it to a string. This
+serves as an explicit reminder of the details of the conversion (including
+representation error). Decimal numbers include special values such as
+:const:`NaN` which stands for "Not a number", positive and negative
+:const:`Infinity`, and :const:`-0`. ::
+
+ >>> Decimal(10)
+ Decimal("10")
+ >>> Decimal("3.14")
+ Decimal("3.14")
+ >>> Decimal((0, (3, 1, 4), -2))
+ Decimal("3.14")
+ >>> Decimal(str(2.0 ** 0.5))
+ Decimal("1.41421356237")
+ >>> Decimal("NaN")
+ Decimal("NaN")
+ >>> Decimal("-Infinity")
+ Decimal("-Infinity")
+
+The significance of a new Decimal is determined solely by the number of digits
+input. Context precision and rounding only come into play during arithmetic
+operations. ::
+
+ >>> getcontext().prec = 6
+ >>> Decimal('3.0')
+ Decimal("3.0")
+ >>> Decimal('3.1415926535')
+ Decimal("3.1415926535")
+ >>> Decimal('3.1415926535') + Decimal('2.7182818285')
+ Decimal("5.85987")
+ >>> getcontext().rounding = ROUND_UP
+ >>> Decimal('3.1415926535') + Decimal('2.7182818285')
+ Decimal("5.85988")
+
+Decimals interact well with much of the rest of Python. Here is a small decimal
+floating point flying circus::
+
+ >>> data = map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split())
+ >>> max(data)
+ Decimal("9.25")
+ >>> min(data)
+ Decimal("0.03")
+ >>> sorted(data)
+ [Decimal("0.03"), Decimal("1.00"), Decimal("1.34"), Decimal("1.87"),
+ Decimal("2.35"), Decimal("3.45"), Decimal("9.25")]
+ >>> sum(data)
+ Decimal("19.29")
+ >>> a,b,c = data[:3]
+ >>> str(a)
+ '1.34'
+ >>> float(a)
+ 1.3400000000000001
+ >>> round(a, 1) # round() first converts to binary floating point
+ 1.3
+ >>> int(a)
+ 1
+ >>> a * 5
+ Decimal("6.70")
+ >>> a * b
+ Decimal("2.5058")
+ >>> c % a
+ Decimal("0.77")
+
+The :meth:`quantize` method rounds a number to a fixed exponent. This method is
+useful for monetary applications that often round results to a fixed number of
+places::
+
+ >>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
+ Decimal("7.32")
+ >>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
+ Decimal("8")
+
+As shown above, the :func:`getcontext` function accesses the current context and
+allows the settings to be changed. This approach meets the needs of most
+applications.
+
+For more advanced work, it may be useful to create alternate contexts using the
+Context() constructor. To make an alternate active, use the :func:`setcontext`
+function.
+
+In accordance with the standard, the :mod:`Decimal` module provides two ready to
+use standard contexts, :const:`BasicContext` and :const:`ExtendedContext`. The
+former is especially useful for debugging because many of the traps are
+enabled::
+
+ >>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)
+ >>> setcontext(myothercontext)
+ >>> Decimal(1) / Decimal(7)
+ Decimal("0.142857142857142857142857142857142857142857142857142857142857")
+
+ >>> ExtendedContext
+ Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
+ capitals=1, flags=[], traps=[])
+ >>> setcontext(ExtendedContext)
+ >>> Decimal(1) / Decimal(7)
+ Decimal("0.142857143")
+ >>> Decimal(42) / Decimal(0)
+ Decimal("Infinity")
+
+ >>> setcontext(BasicContext)
+ >>> Decimal(42) / Decimal(0)
+ Traceback (most recent call last):
+ File "<pyshell#143>", line 1, in -toplevel-
+ Decimal(42) / Decimal(0)
+ DivisionByZero: x / 0
+
+Contexts also have signal flags for monitoring exceptional conditions
+encountered during computations. The flags remain set until explicitly cleared,
+so it is best to clear the flags before each set of monitored computations by
+using the :meth:`clear_flags` method. ::
+
+ >>> setcontext(ExtendedContext)
+ >>> getcontext().clear_flags()
+ >>> Decimal(355) / Decimal(113)
+ Decimal("3.14159292")
+ >>> getcontext()
+ Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
+ capitals=1, flags=[Inexact, Rounded], traps=[])
+
+The *flags* entry shows that the rational approximation to :const:`Pi` was
+rounded (digits beyond the context precision were thrown away) and that the
+result is inexact (some of the discarded digits were non-zero).
+
+Individual traps are set using the dictionary in the :attr:`traps` field of a
+context::
+
+ >>> Decimal(1) / Decimal(0)
+ Decimal("Infinity")
+ >>> getcontext().traps[DivisionByZero] = 1
+ >>> Decimal(1) / Decimal(0)
+ Traceback (most recent call last):
+ File "<pyshell#112>", line 1, in -toplevel-
+ Decimal(1) / Decimal(0)
+ DivisionByZero: x / 0
+
+Most programs adjust the current context only once, at the beginning of the
+program. And, in many applications, data is converted to :class:`Decimal` with
+a single cast inside a loop. With context set and decimals created, the bulk of
+the program manipulates the data no differently than with other Python numeric
+types.
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-decimal:
+
+Decimal objects
+---------------
+
+
+.. class:: Decimal([value [, context]])
+
+ Constructs a new :class:`Decimal` object based from *value*.
+
+ *value* can be an integer, string, tuple, or another :class:`Decimal` object. If
+ no *value* is given, returns ``Decimal("0")``. If *value* is a string, it
+ should conform to the decimal numeric string syntax::
+
+ sign ::= '+' | '-'
+ digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
+ indicator ::= 'e' | 'E'
+ digits ::= digit [digit]...
+ decimal-part ::= digits '.' [digits] | ['.'] digits
+ exponent-part ::= indicator [sign] digits
+ infinity ::= 'Infinity' | 'Inf'
+ nan ::= 'NaN' [digits] | 'sNaN' [digits]
+ numeric-value ::= decimal-part [exponent-part] | infinity
+ numeric-string ::= [sign] numeric-value | [sign] nan
+
+ If *value* is a :class:`tuple`, it should have three components, a sign
+ (:const:`0` for positive or :const:`1` for negative), a :class:`tuple` of
+ digits, and an integer exponent. For example, ``Decimal((0, (1, 4, 1, 4), -3))``
+ returns ``Decimal("1.414")``.
+
+ The *context* precision does not affect how many digits are stored. That is
+ determined exclusively by the number of digits in *value*. For example,
+ ``Decimal("3.00000")`` records all five zeroes even if the context precision is
+ only three.
+
+ The purpose of the *context* argument is determining what to do if *value* is a
+ malformed string. If the context traps :const:`InvalidOperation`, an exception
+ is raised; otherwise, the constructor returns a new Decimal with the value of
+ :const:`NaN`.
+
+ Once constructed, :class:`Decimal` objects are immutable.
+
+Decimal floating point objects share many properties with the other builtin
+numeric types such as :class:`float` and :class:`int`. All of the usual math
+operations and special methods apply. Likewise, decimal objects can be copied,
+pickled, printed, used as dictionary keys, used as set elements, compared,
+sorted, and coerced to another type (such as :class:`float` or :class:`long`).
+
+In addition to the standard numeric properties, decimal floating point objects
+also have a number of specialized methods:
+
+
+.. method:: Decimal.adjusted()
+
+ Return the adjusted exponent after shifting out the coefficient's rightmost
+ digits until only the lead digit remains: ``Decimal("321e+5").adjusted()``
+ returns seven. Used for determining the position of the most significant digit
+ with respect to the decimal point.
+
+
+.. method:: Decimal.as_tuple()
+
+ Returns a tuple representation of the number: ``(sign, digittuple, exponent)``.
+
+
+.. method:: Decimal.compare(other[, context])
+
+ Compares like :meth:`__cmp__` but returns a decimal instance::
+
+ a or b is a NaN ==> Decimal("NaN")
+ a < b ==> Decimal("-1")
+ a == b ==> Decimal("0")
+ a > b ==> Decimal("1")
+
+
+.. method:: Decimal.max(other[, context])
+
+ Like ``max(self, other)`` except that the context rounding rule is applied
+ before returning and that :const:`NaN` values are either signalled or ignored
+ (depending on the context and whether they are signaling or quiet).
+
+
+.. method:: Decimal.min(other[, context])
+
+ Like ``min(self, other)`` except that the context rounding rule is applied
+ before returning and that :const:`NaN` values are either signalled or ignored
+ (depending on the context and whether they are signaling or quiet).
+
+
+.. method:: Decimal.normalize([context])
+
+ Normalize the number by stripping the rightmost trailing zeroes and converting
+ any result equal to :const:`Decimal("0")` to :const:`Decimal("0e0")`. Used for
+ producing canonical values for members of an equivalence class. For example,
+ ``Decimal("32.100")`` and ``Decimal("0.321000e+2")`` both normalize to the
+ equivalent value ``Decimal("32.1")``.
+
+
+.. method:: Decimal.quantize(exp [, rounding[, context[, watchexp]]])
+
+ Quantize makes the exponent the same as *exp*. Searches for a rounding method
+ in *rounding*, then in *context*, and then in the current context.
+
+ If *watchexp* is set (default), then an error is returned whenever the resulting
+ exponent is greater than :attr:`Emax` or less than :attr:`Etiny`.
+
+
+.. method:: Decimal.remainder_near(other[, context])
+
+ Computes the modulo as either a positive or negative value depending on which is
+ closest to zero. For instance, ``Decimal(10).remainder_near(6)`` returns
+ ``Decimal("-2")`` which is closer to zero than ``Decimal("4")``.
+
+ If both are equally close, the one chosen will have the same sign as *self*.
+
+
+.. method:: Decimal.same_quantum(other[, context])
+
+ Test whether self and other have the same exponent or whether both are
+ :const:`NaN`.
+
+
+.. method:: Decimal.sqrt([context])
+
+ Return the square root to full precision.
+
+
+.. method:: Decimal.to_eng_string([context])
+
+ Convert to an engineering-type string.
+
+ Engineering notation has an exponent which is a multiple of 3, so there are up
+ to 3 digits left of the decimal place. For example, converts
+ ``Decimal('123E+1')`` to ``Decimal("1.23E+3")``
+
+
+.. method:: Decimal.to_integral([rounding[, context]])
+
+ Rounds to the nearest integer without signaling :const:`Inexact` or
+ :const:`Rounded`. If given, applies *rounding*; otherwise, uses the rounding
+ method in either the supplied *context* or the current context.
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-context:
+
+Context objects
+---------------
+
+Contexts are environments for arithmetic operations. They govern precision, set
+rules for rounding, determine which signals are treated as exceptions, and limit
+the range for exponents.
+
+Each thread has its own current context which is accessed or changed using the
+:func:`getcontext` and :func:`setcontext` functions:
+
+
+.. function:: getcontext()
+
+ Return the current context for the active thread.
+
+
+.. function:: setcontext(c)
+
+ Set the current context for the active thread to *c*.
+
+Beginning with Python 2.5, you can also use the :keyword:`with` statement and
+the :func:`localcontext` function to temporarily change the active context.
+
+
+.. function:: localcontext([c])
+
+ Return a context manager that will set the current context for the active thread
+ to a copy of *c* on entry to the with-statement and restore the previous context
+ when exiting the with-statement. If no context is specified, a copy of the
+ current context is used.
+
+ .. versionadded:: 2.5
+
+ For example, the following code sets the current decimal precision to 42 places,
+ performs a calculation, and then automatically restores the previous context::
+
+ from __future__ import with_statement
+ from decimal import localcontext
+
+ with localcontext() as ctx:
+ ctx.prec = 42 # Perform a high precision calculation
+ s = calculate_something()
+ s = +s # Round the final result back to the default precision
+
+New contexts can also be created using the :class:`Context` constructor
+described below. In addition, the module provides three pre-made contexts:
+
+
+.. class:: BasicContext
+
+ This is a standard context defined by the General Decimal Arithmetic
+ Specification. Precision is set to nine. Rounding is set to
+ :const:`ROUND_HALF_UP`. All flags are cleared. All traps are enabled (treated
+ as exceptions) except :const:`Inexact`, :const:`Rounded`, and
+ :const:`Subnormal`.
+
+ Because many of the traps are enabled, this context is useful for debugging.
+
+
+.. class:: ExtendedContext
+
+ This is a standard context defined by the General Decimal Arithmetic
+ Specification. Precision is set to nine. Rounding is set to
+ :const:`ROUND_HALF_EVEN`. All flags are cleared. No traps are enabled (so that
+ exceptions are not raised during computations).
+
+ Because the trapped are disabled, this context is useful for applications that
+ prefer to have result value of :const:`NaN` or :const:`Infinity` instead of
+ raising exceptions. This allows an application to complete a run in the
+ presence of conditions that would otherwise halt the program.
+
+
+.. class:: DefaultContext
+
+ This context is used by the :class:`Context` constructor as a prototype for new
+ contexts. Changing a field (such a precision) has the effect of changing the
+ default for new contexts creating by the :class:`Context` constructor.
+
+ This context is most useful in multi-threaded environments. Changing one of the
+ fields before threads are started has the effect of setting system-wide
+ defaults. Changing the fields after threads have started is not recommended as
+ it would require thread synchronization to prevent race conditions.
+
+ In single threaded environments, it is preferable to not use this context at
+ all. Instead, simply create contexts explicitly as described below.
+
+ The default values are precision=28, rounding=ROUND_HALF_EVEN, and enabled traps
+ for Overflow, InvalidOperation, and DivisionByZero.
+
+In addition to the three supplied contexts, new contexts can be created with the
+:class:`Context` constructor.
+
+
+.. class:: Context(prec=None, rounding=None, traps=None, flags=None, Emin=None, Emax=None, capitals=1)
+
+ Creates a new context. If a field is not specified or is :const:`None`, the
+ default values are copied from the :const:`DefaultContext`. If the *flags*
+ field is not specified or is :const:`None`, all flags are cleared.
+
+ The *prec* field is a positive integer that sets the precision for arithmetic
+ operations in the context.
+
+ The *rounding* option is one of:
+
+ * :const:`ROUND_CEILING` (towards :const:`Infinity`),
+ * :const:`ROUND_DOWN` (towards zero),
+ * :const:`ROUND_FLOOR` (towards :const:`-Infinity`),
+ * :const:`ROUND_HALF_DOWN` (to nearest with ties going towards zero),
+ * :const:`ROUND_HALF_EVEN` (to nearest with ties going to nearest even integer),
+ * :const:`ROUND_HALF_UP` (to nearest with ties going away from zero), or
+ * :const:`ROUND_UP` (away from zero).
+
+ The *traps* and *flags* fields list any signals to be set. Generally, new
+ contexts should only set traps and leave the flags clear.
+
+ The *Emin* and *Emax* fields are integers specifying the outer limits allowable
+ for exponents.
+
+ The *capitals* field is either :const:`0` or :const:`1` (the default). If set to
+ :const:`1`, exponents are printed with a capital :const:`E`; otherwise, a
+ lowercase :const:`e` is used: :const:`Decimal('6.02e+23')`.
+
+The :class:`Context` class defines several general purpose methods as well as a
+large number of methods for doing arithmetic directly in a given context.
+
+
+.. method:: Context.clear_flags()
+
+ Resets all of the flags to :const:`0`.
+
+
+.. method:: Context.copy()
+
+ Return a duplicate of the context.
+
+
+.. method:: Context.create_decimal(num)
+
+ Creates a new Decimal instance from *num* but using *self* as context. Unlike
+ the :class:`Decimal` constructor, the context precision, rounding method, flags,
+ and traps are applied to the conversion.
+
+ This is useful because constants are often given to a greater precision than is
+ needed by the application. Another benefit is that rounding immediately
+ eliminates unintended effects from digits beyond the current precision. In the
+ following example, using unrounded inputs means that adding zero to a sum can
+ change the result::
+
+ >>> getcontext().prec = 3
+ >>> Decimal("3.4445") + Decimal("1.0023")
+ Decimal("4.45")
+ >>> Decimal("3.4445") + Decimal(0) + Decimal("1.0023")
+ Decimal("4.44")
+
+
+.. method:: Context.Etiny()
+
+ Returns a value equal to ``Emin - prec + 1`` which is the minimum exponent value
+ for subnormal results. When underflow occurs, the exponent is set to
+ :const:`Etiny`.
+
+
+.. method:: Context.Etop()
+
+ Returns a value equal to ``Emax - prec + 1``.
+
+The usual approach to working with decimals is to create :class:`Decimal`
+instances and then apply arithmetic operations which take place within the
+current context for the active thread. An alternate approach is to use context
+methods for calculating within a specific context. The methods are similar to
+those for the :class:`Decimal` class and are only briefly recounted here.
+
+
+.. method:: Context.abs(x)
+
+ Returns the absolute value of *x*.
+
+
+.. method:: Context.add(x, y)
+
+ Return the sum of *x* and *y*.
+
+
+.. method:: Context.compare(x, y)
+
+ Compares values numerically.
+
+ Like :meth:`__cmp__` but returns a decimal instance::
+
+ a or b is a NaN ==> Decimal("NaN")
+ a < b ==> Decimal("-1")
+ a == b ==> Decimal("0")
+ a > b ==> Decimal("1")
+
+
+.. method:: Context.divide(x, y)
+
+ Return *x* divided by *y*.
+
+
+.. method:: Context.divmod(x, y)
+
+ Divides two numbers and returns the integer part of the result.
+
+
+.. method:: Context.max(x, y)
+
+ Compare two values numerically and return the maximum.
+
+ If they are numerically equal then the left-hand operand is chosen as the
+ result.
+
+
+.. method:: Context.min(x, y)
+
+ Compare two values numerically and return the minimum.
+
+ If they are numerically equal then the left-hand operand is chosen as the
+ result.
+
+
+.. method:: Context.minus(x)
+
+ Minus corresponds to the unary prefix minus operator in Python.
+
+
+.. method:: Context.multiply(x, y)
+
+ Return the product of *x* and *y*.
+
+
+.. method:: Context.normalize(x)
+
+ Normalize reduces an operand to its simplest form.
+
+ Essentially a :meth:`plus` operation with all trailing zeros removed from the
+ result.
+
+
+.. method:: Context.plus(x)
+
+ Plus corresponds to the unary prefix plus operator in Python. This operation
+ applies the context precision and rounding, so it is *not* an identity
+ operation.
+
+
+.. method:: Context.power(x, y[, modulo])
+
+ Return ``x ** y`` to the *modulo* if given.
+
+ The right-hand operand must be a whole number whose integer part (after any
+ exponent has been applied) has no more than 9 digits and whose fractional part
+ (if any) is all zeros before any rounding. The operand may be positive,
+ negative, or zero; if negative, the absolute value of the power is used, and the
+ left-hand operand is inverted (divided into 1) before use.
+
+ If the increased precision needed for the intermediate calculations exceeds the
+ capabilities of the implementation then an :const:`InvalidOperation` condition
+ is signaled.
+
+ If, when raising to a negative power, an underflow occurs during the division
+ into 1, the operation is not halted at that point but continues.
+
+
+.. method:: Context.quantize(x, y)
+
+ Returns a value equal to *x* after rounding and having the exponent of *y*.
+
+ Unlike other operations, if the length of the coefficient after the quantize
+ operation would be greater than precision, then an :const:`InvalidOperation` is
+ signaled. This guarantees that, unless there is an error condition, the
+ quantized exponent is always equal to that of the right-hand operand.
+
+ Also unlike other operations, quantize never signals Underflow, even if the
+ result is subnormal and inexact.
+
+
+.. method:: Context.remainder(x, y)
+
+ Returns the remainder from integer division.
+
+ The sign of the result, if non-zero, is the same as that of the original
+ dividend.
+
+
+.. method:: Context.remainder_near(x, y)
+
+ Computed the modulo as either a positive or negative value depending on which is
+ closest to zero. For instance, ``Decimal(10).remainder_near(6)`` returns
+ ``Decimal("-2")`` which is closer to zero than ``Decimal("4")``.
+
+ If both are equally close, the one chosen will have the same sign as *self*.
+
+
+.. method:: Context.same_quantum(x, y)
+
+ Test whether *x* and *y* have the same exponent or whether both are
+ :const:`NaN`.
+
+
+.. method:: Context.sqrt(x)
+
+ Return the square root of *x* to full precision.
+
+
+.. method:: Context.subtract(x, y)
+
+ Return the difference between *x* and *y*.
+
+
+.. method:: Context.to_eng_string()
+
+ Convert to engineering-type string.
+
+ Engineering notation has an exponent which is a multiple of 3, so there are up
+ to 3 digits left of the decimal place. For example, converts
+ ``Decimal('123E+1')`` to ``Decimal("1.23E+3")``
+
+
+.. method:: Context.to_integral(x)
+
+ Rounds to the nearest integer without signaling :const:`Inexact` or
+ :const:`Rounded`.
+
+
+.. method:: Context.to_sci_string(x)
+
+ Converts a number to a string using scientific notation.
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-signals:
+
+Signals
+-------
+
+Signals represent conditions that arise during computation. Each corresponds to
+one context flag and one context trap enabler.
+
+The context flag is incremented whenever the condition is encountered. After the
+computation, flags may be checked for informational purposes (for instance, to
+determine whether a computation was exact). After checking the flags, be sure to
+clear all flags before starting the next computation.
+
+If the context's trap enabler is set for the signal, then the condition causes a
+Python exception to be raised. For example, if the :class:`DivisionByZero` trap
+is set, then a :exc:`DivisionByZero` exception is raised upon encountering the
+condition.
+
+
+.. class:: Clamped
+
+ Altered an exponent to fit representation constraints.
+
+ Typically, clamping occurs when an exponent falls outside the context's
+ :attr:`Emin` and :attr:`Emax` limits. If possible, the exponent is reduced to
+ fit by adding zeroes to the coefficient.
+
+
+.. class:: DecimalException
+
+ Base class for other signals and a subclass of :exc:`ArithmeticError`.
+
+
+.. class:: DivisionByZero
+
+ Signals the division of a non-infinite number by zero.
+
+ Can occur with division, modulo division, or when raising a number to a negative
+ power. If this signal is not trapped, returns :const:`Infinity` or
+ :const:`-Infinity` with the sign determined by the inputs to the calculation.
+
+
+.. class:: Inexact
+
+ Indicates that rounding occurred and the result is not exact.
+
+ Signals when non-zero digits were discarded during rounding. The rounded result
+ is returned. The signal flag or trap is used to detect when results are
+ inexact.
+
+
+.. class:: InvalidOperation
+
+ An invalid operation was performed.
+
+ Indicates that an operation was requested that does not make sense. If not
+ trapped, returns :const:`NaN`. Possible causes include::
+
+ Infinity - Infinity
+ 0 * Infinity
+ Infinity / Infinity
+ x % 0
+ Infinity % x
+ x._rescale( non-integer )
+ sqrt(-x) and x > 0
+ 0 ** 0
+ x ** (non-integer)
+ x ** Infinity
+
+
+.. class:: Overflow
+
+ Numerical overflow.
+
+ Indicates the exponent is larger than :attr:`Emax` after rounding has occurred.
+ If not trapped, the result depends on the rounding mode, either pulling inward
+ to the largest representable finite number or rounding outward to
+ :const:`Infinity`. In either case, :class:`Inexact` and :class:`Rounded` are
+ also signaled.
+
+
+.. class:: Rounded
+
+ Rounding occurred though possibly no information was lost.
+
+ Signaled whenever rounding discards digits; even if those digits are zero (such
+ as rounding :const:`5.00` to :const:`5.0`). If not trapped, returns the result
+ unchanged. This signal is used to detect loss of significant digits.
+
+
+.. class:: Subnormal
+
+ Exponent was lower than :attr:`Emin` prior to rounding.
+
+ Occurs when an operation result is subnormal (the exponent is too small). If not
+ trapped, returns the result unchanged.
+
+
+.. class:: Underflow
+
+ Numerical underflow with result rounded to zero.
+
+ Occurs when a subnormal result is pushed to zero by rounding. :class:`Inexact`
+ and :class:`Subnormal` are also signaled.
+
+The following table summarizes the hierarchy of signals::
+
+ exceptions.ArithmeticError(exceptions.StandardError)
+ DecimalException
+ Clamped
+ DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
+ Inexact
+ Overflow(Inexact, Rounded)
+ Underflow(Inexact, Rounded, Subnormal)
+ InvalidOperation
+ Rounded
+ Subnormal
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-notes:
+
+Floating Point Notes
+--------------------
+
+
+Mitigating round-off error with increased precision
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The use of decimal floating point eliminates decimal representation error
+(making it possible to represent :const:`0.1` exactly); however, some operations
+can still incur round-off error when non-zero digits exceed the fixed precision.
+
+The effects of round-off error can be amplified by the addition or subtraction
+of nearly offsetting quantities resulting in loss of significance. Knuth
+provides two instructive examples where rounded floating point arithmetic with
+insufficient precision causes the breakdown of the associative and distributive
+properties of addition::
+
+ # Examples from Seminumerical Algorithms, Section 4.2.2.
+ >>> from decimal import Decimal, getcontext
+ >>> getcontext().prec = 8
+
+ >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
+ >>> (u + v) + w
+ Decimal("9.5111111")
+ >>> u + (v + w)
+ Decimal("10")
+
+ >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
+ >>> (u*v) + (u*w)
+ Decimal("0.01")
+ >>> u * (v+w)
+ Decimal("0.0060000")
+
+The :mod:`decimal` module makes it possible to restore the identities by
+expanding the precision sufficiently to avoid loss of significance::
+
+ >>> getcontext().prec = 20
+ >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
+ >>> (u + v) + w
+ Decimal("9.51111111")
+ >>> u + (v + w)
+ Decimal("9.51111111")
+ >>>
+ >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
+ >>> (u*v) + (u*w)
+ Decimal("0.0060000")
+ >>> u * (v+w)
+ Decimal("0.0060000")
+
+
+Special values
+^^^^^^^^^^^^^^
+
+The number system for the :mod:`decimal` module provides special values
+including :const:`NaN`, :const:`sNaN`, :const:`-Infinity`, :const:`Infinity`,
+and two zeroes, :const:`+0` and :const:`-0`.
+
+Infinities can be constructed directly with: ``Decimal('Infinity')``. Also,
+they can arise from dividing by zero when the :exc:`DivisionByZero` signal is
+not trapped. Likewise, when the :exc:`Overflow` signal is not trapped, infinity
+can result from rounding beyond the limits of the largest representable number.
+
+The infinities are signed (affine) and can be used in arithmetic operations
+where they get treated as very large, indeterminate numbers. For instance,
+adding a constant to infinity gives another infinite result.
+
+Some operations are indeterminate and return :const:`NaN`, or if the
+:exc:`InvalidOperation` signal is trapped, raise an exception. For example,
+``0/0`` returns :const:`NaN` which means "not a number". This variety of
+:const:`NaN` is quiet and, once created, will flow through other computations
+always resulting in another :const:`NaN`. This behavior can be useful for a
+series of computations that occasionally have missing inputs --- it allows the
+calculation to proceed while flagging specific results as invalid.
+
+A variant is :const:`sNaN` which signals rather than remaining quiet after every
+operation. This is a useful return value when an invalid result needs to
+interrupt a calculation for special handling.
+
+The signed zeros can result from calculations that underflow. They keep the sign
+that would have resulted if the calculation had been carried out to greater
+precision. Since their magnitude is zero, both positive and negative zeros are
+treated as equal and their sign is informational.
+
+In addition to the two signed zeros which are distinct yet equal, there are
+various representations of zero with differing precisions yet equivalent in
+value. This takes a bit of getting used to. For an eye accustomed to
+normalized floating point representations, it is not immediately obvious that
+the following calculation returns a value equal to zero::
+
+ >>> 1 / Decimal('Infinity')
+ Decimal("0E-1000000026")
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-threads:
+
+Working with threads
+--------------------
+
+The :func:`getcontext` function accesses a different :class:`Context` object for
+each thread. Having separate thread contexts means that threads may make
+changes (such as ``getcontext.prec=10``) without interfering with other threads.
+
+Likewise, the :func:`setcontext` function automatically assigns its target to
+the current thread.
+
+If :func:`setcontext` has not been called before :func:`getcontext`, then
+:func:`getcontext` will automatically create a new context for use in the
+current thread.
+
+The new context is copied from a prototype context called *DefaultContext*. To
+control the defaults so that each thread will use the same values throughout the
+application, directly modify the *DefaultContext* object. This should be done
+*before* any threads are started so that there won't be a race condition between
+threads calling :func:`getcontext`. For example::
+
+ # Set applicationwide defaults for all threads about to be launched
+ DefaultContext.prec = 12
+ DefaultContext.rounding = ROUND_DOWN
+ DefaultContext.traps = ExtendedContext.traps.copy()
+ DefaultContext.traps[InvalidOperation] = 1
+ setcontext(DefaultContext)
+
+ # Afterwards, the threads can be started
+ t1.start()
+ t2.start()
+ t3.start()
+ . . .
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-recipes:
+
+Recipes
+-------
+
+Here are a few recipes that serve as utility functions and that demonstrate ways
+to work with the :class:`Decimal` class::
+
+ def moneyfmt(value, places=2, curr='', sep=',', dp='.',
+ pos='', neg='-', trailneg=''):
+ """Convert Decimal to a money formatted string.
+
+ places: required number of places after the decimal point
+ curr: optional currency symbol before the sign (may be blank)
+ sep: optional grouping separator (comma, period, space, or blank)
+ dp: decimal point indicator (comma or period)
+ only specify as blank when places is zero
+ pos: optional sign for positive numbers: '+', space or blank
+ neg: optional sign for negative numbers: '-', '(', space or blank
+ trailneg:optional trailing minus indicator: '-', ')', space or blank
+
+ >>> d = Decimal('-1234567.8901')
+ >>> moneyfmt(d, curr='$')
+ '-$1,234,567.89'
+ >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')
+ '1.234.568-'
+ >>> moneyfmt(d, curr='$', neg='(', trailneg=')')
+ '($1,234,567.89)'
+ >>> moneyfmt(Decimal(123456789), sep=' ')
+ '123 456 789.00'
+ >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')
+ '<.02>'
+
+ """
+ q = Decimal((0, (1,), -places)) # 2 places --> '0.01'
+ sign, digits, exp = value.quantize(q).as_tuple()
+ assert exp == -places
+ result = []
+ digits = map(str, digits)
+ build, next = result.append, digits.pop
+ if sign:
+ build(trailneg)
+ for i in range(places):
+ if digits:
+ build(next())
+ else:
+ build('0')
+ build(dp)
+ i = 0
+ while digits:
+ build(next())
+ i += 1
+ if i == 3 and digits:
+ i = 0
+ build(sep)
+ build(curr)
+ if sign:
+ build(neg)
+ else:
+ build(pos)
+ result.reverse()
+ return ''.join(result)
+
+ def pi():
+ """Compute Pi to the current precision.
+
+ >>> print pi()
+ 3.141592653589793238462643383
+
+ """
+ getcontext().prec += 2 # extra digits for intermediate steps
+ three = Decimal(3) # substitute "three=3.0" for regular floats
+ lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24
+ while s != lasts:
+ lasts = s
+ n, na = n+na, na+8
+ d, da = d+da, da+32
+ t = (t * n) / d
+ s += t
+ getcontext().prec -= 2
+ return +s # unary plus applies the new precision
+
+ def exp(x):
+ """Return e raised to the power of x. Result type matches input type.
+
+ >>> print exp(Decimal(1))
+ 2.718281828459045235360287471
+ >>> print exp(Decimal(2))
+ 7.389056098930650227230427461
+ >>> print exp(2.0)
+ 7.38905609893
+ >>> print exp(2+0j)
+ (7.38905609893+0j)
+
+ """
+ getcontext().prec += 2
+ i, lasts, s, fact, num = 0, 0, 1, 1, 1
+ while s != lasts:
+ lasts = s
+ i += 1
+ fact *= i
+ num *= x
+ s += num / fact
+ getcontext().prec -= 2
+ return +s
+
+ def cos(x):
+ """Return the cosine of x as measured in radians.
+
+ >>> print cos(Decimal('0.5'))
+ 0.8775825618903727161162815826
+ >>> print cos(0.5)
+ 0.87758256189
+ >>> print cos(0.5+0j)
+ (0.87758256189+0j)
+
+ """
+ getcontext().prec += 2
+ i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1
+ while s != lasts:
+ lasts = s
+ i += 2
+ fact *= i * (i-1)
+ num *= x * x
+ sign *= -1
+ s += num / fact * sign
+ getcontext().prec -= 2
+ return +s
+
+ def sin(x):
+ """Return the sine of x as measured in radians.
+
+ >>> print sin(Decimal('0.5'))
+ 0.4794255386042030002732879352
+ >>> print sin(0.5)
+ 0.479425538604
+ >>> print sin(0.5+0j)
+ (0.479425538604+0j)
+
+ """
+ getcontext().prec += 2
+ i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1
+ while s != lasts:
+ lasts = s
+ i += 2
+ fact *= i * (i-1)
+ num *= x * x
+ sign *= -1
+ s += num / fact * sign
+ getcontext().prec -= 2
+ return +s
+
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-faq:
+
+Decimal FAQ
+-----------
+
+Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to
+minimize typing when using the interactive interpreter?
+
+\A. Some users abbreviate the constructor to just a single letter::
+
+ >>> D = decimal.Decimal
+ >>> D('1.23') + D('3.45')
+ Decimal("4.68")
+
+Q. In a fixed-point application with two decimal places, some inputs have many
+places and need to be rounded. Others are not supposed to have excess digits
+and need to be validated. What methods should be used?
+
+A. The :meth:`quantize` method rounds to a fixed number of decimal places. If
+the :const:`Inexact` trap is set, it is also useful for validation::
+
+ >>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01')
+
+ >>> # Round to two places
+ >>> Decimal("3.214").quantize(TWOPLACES)
+ Decimal("3.21")
+
+ >>> # Validate that a number does not exceed two places
+ >>> Decimal("3.21").quantize(TWOPLACES, context=Context(traps=[Inexact]))
+ Decimal("3.21")
+
+ >>> Decimal("3.214").quantize(TWOPLACES, context=Context(traps=[Inexact]))
+ Traceback (most recent call last):
+ ...
+ Inexact: Changed in rounding
+
+Q. Once I have valid two place inputs, how do I maintain that invariant
+throughout an application?
+
+A. Some operations like addition and subtraction automatically preserve fixed
+point. Others, like multiplication and division, change the number of decimal
+places and need to be followed-up with a :meth:`quantize` step.
+
+Q. There are many ways to express the same value. The numbers :const:`200`,
+:const:`200.000`, :const:`2E2`, and :const:`.02E+4` all have the same value at
+various precisions. Is there a way to transform them to a single recognizable
+canonical value?
+
+A. The :meth:`normalize` method maps all equivalent values to a single
+representative::
+
+ >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
+ >>> [v.normalize() for v in values]
+ [Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2")]
+
+Q. Some decimal values always print with exponential notation. Is there a way
+to get a non-exponential representation?
+
+A. For some values, exponential notation is the only way to express the number
+of significant places in the coefficient. For example, expressing
+:const:`5.0E+3` as :const:`5000` keeps the value constant but cannot show the
+original's two-place significance.
+
+Q. Is there a way to convert a regular float to a :class:`Decimal`?
+
+A. Yes, all binary floating point numbers can be exactly expressed as a
+Decimal. An exact conversion may take more precision than intuition would
+suggest, so trapping :const:`Inexact` will signal a need for more precision::
+
+ def floatToDecimal(f):
+ "Convert a floating point number to a Decimal with no loss of information"
+ # Transform (exactly) a float to a mantissa (0.5 <= abs(m) < 1.0) and an
+ # exponent. Double the mantissa until it is an integer. Use the integer
+ # mantissa and exponent to compute an equivalent Decimal. If this cannot
+ # be done exactly, then retry with more precision.
+
+ mantissa, exponent = math.frexp(f)
+ while mantissa != int(mantissa):
+ mantissa *= 2.0
+ exponent -= 1
+ mantissa = int(mantissa)
+
+ oldcontext = getcontext()
+ setcontext(Context(traps=[Inexact]))
+ try:
+ while True:
+ try:
+ return mantissa * Decimal(2) ** exponent
+ except Inexact:
+ getcontext().prec += 1
+ finally:
+ setcontext(oldcontext)
+
+Q. Why isn't the :func:`floatToDecimal` routine included in the module?
+
+A. There is some question about whether it is advisable to mix binary and
+decimal floating point. Also, its use requires some care to avoid the
+representation issues associated with binary floating point::
+
+ >>> floatToDecimal(1.1)
+ Decimal("1.100000000000000088817841970012523233890533447265625")
+
+Q. Within a complex calculation, how can I make sure that I haven't gotten a
+spurious result because of insufficient precision or rounding anomalies.
+
+A. The decimal module makes it easy to test results. A best practice is to
+re-run calculations using greater precision and with various rounding modes.
+Widely differing results indicate insufficient precision, rounding mode issues,
+ill-conditioned inputs, or a numerically unstable algorithm.
+
+Q. I noticed that context precision is applied to the results of operations but
+not to the inputs. Is there anything to watch out for when mixing values of
+different precisions?
+
+A. Yes. The principle is that all values are considered to be exact and so is
+the arithmetic on those values. Only the results are rounded. The advantage
+for inputs is that "what you type is what you get". A disadvantage is that the
+results can look odd if you forget that the inputs haven't been rounded::
+
+ >>> getcontext().prec = 3
+ >>> Decimal('3.104') + D('2.104')
+ Decimal("5.21")
+ >>> Decimal('3.104') + D('0.000') + D('2.104')
+ Decimal("5.20")
+
+The solution is either to increase precision or to force rounding of inputs
+using the unary plus operation::
+
+ >>> getcontext().prec = 3
+ >>> +Decimal('1.23456789') # unary plus triggers rounding
+ Decimal("1.23")
+
+Alternatively, inputs can be rounded upon creation using the
+:meth:`Context.create_decimal` method::
+
+ >>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
+ Decimal("1.2345")
+
--- /dev/null
+
+.. _development:
+
+*****************
+Development Tools
+*****************
+
+The modules described in this chapter help you write software. For example, the
+:mod:`pydoc` module takes a module and generates documentation based on the
+module's contents. The :mod:`doctest` and :mod:`unittest` modules contains
+frameworks for writing unit tests that automatically exercise code and verify
+that the expected output is produced.
+
+The list of modules described in this chapter is:
+
+
+.. toctree::
+
+ pydoc.rst
+ doctest.rst
+ unittest.rst
+ test.rst
--- /dev/null
+
+:mod:`difflib` --- Helpers for computing deltas
+===============================================
+
+.. module:: difflib
+ :synopsis: Helpers for computing differences between objects.
+.. moduleauthor:: Tim Peters <tim_one@users.sourceforge.net>
+.. sectionauthor:: Tim Peters <tim_one@users.sourceforge.net>
+
+
+.. % LaTeXification by Fred L. Drake, Jr. <fdrake@acm.org>.
+
+.. versionadded:: 2.1
+
+
+.. class:: SequenceMatcher
+
+ This is a flexible class for comparing pairs of sequences of any type, so long
+ as the sequence elements are hashable. The basic algorithm predates, and is a
+ little fancier than, an algorithm published in the late 1980's by Ratcliff and
+ Obershelp under the hyperbolic name "gestalt pattern matching." The idea is to
+ find the longest contiguous matching subsequence that contains no "junk"
+ elements (the Ratcliff and Obershelp algorithm doesn't address junk). The same
+ idea is then applied recursively to the pieces of the sequences to the left and
+ to the right of the matching subsequence. This does not yield minimal edit
+ sequences, but does tend to yield matches that "look right" to people.
+
+ **Timing:** The basic Ratcliff-Obershelp algorithm is cubic time in the worst
+ case and quadratic time in the expected case. :class:`SequenceMatcher` is
+ quadratic time for the worst case and has expected-case behavior dependent in a
+ complicated way on how many elements the sequences have in common; best case
+ time is linear.
+
+
+.. class:: Differ
+
+ This is a class for comparing sequences of lines of text, and producing
+ human-readable differences or deltas. Differ uses :class:`SequenceMatcher`
+ both to compare sequences of lines, and to compare sequences of characters
+ within similar (near-matching) lines.
+
+ Each line of a :class:`Differ` delta begins with a two-letter code:
+
+ +----------+-------------------------------------------+
+ | Code | Meaning |
+ +==========+===========================================+
+ | ``'- '`` | line unique to sequence 1 |
+ +----------+-------------------------------------------+
+ | ``'+ '`` | line unique to sequence 2 |
+ +----------+-------------------------------------------+
+ | ``' '`` | line common to both sequences |
+ +----------+-------------------------------------------+
+ | ``'? '`` | line not present in either input sequence |
+ +----------+-------------------------------------------+
+
+ Lines beginning with '``?``' attempt to guide the eye to intraline differences,
+ and were not present in either input sequence. These lines can be confusing if
+ the sequences contain tab characters.
+
+
+.. class:: HtmlDiff
+
+ This class can be used to create an HTML table (or a complete HTML file
+ containing the table) showing a side by side, line by line comparison of text
+ with inter-line and intra-line change highlights. The table can be generated in
+ either full or contextual difference mode.
+
+ The constructor for this class is:
+
+
+ .. function:: __init__([tabsize][, wrapcolumn][, linejunk][, charjunk])
+
+ Initializes instance of :class:`HtmlDiff`.
+
+ *tabsize* is an optional keyword argument to specify tab stop spacing and
+ defaults to ``8``.
+
+ *wrapcolumn* is an optional keyword to specify column number where lines are
+ broken and wrapped, defaults to ``None`` where lines are not wrapped.
+
+ *linejunk* and *charjunk* are optional keyword arguments passed into ``ndiff()``
+ (used by :class:`HtmlDiff` to generate the side by side HTML differences). See
+ ``ndiff()`` documentation for argument default values and descriptions.
+
+ The following methods are public:
+
+
+ .. function:: make_file(fromlines, tolines [, fromdesc][, todesc][, context][, numlines])
+
+ Compares *fromlines* and *tolines* (lists of strings) and returns a string which
+ is a complete HTML file containing a table showing line by line differences with
+ inter-line and intra-line changes highlighted.
+
+ *fromdesc* and *todesc* are optional keyword arguments to specify from/to file
+ column header strings (both default to an empty string).
+
+ *context* and *numlines* are both optional keyword arguments. Set *context* to
+ ``True`` when contextual differences are to be shown, else the default is
+ ``False`` to show the full files. *numlines* defaults to ``5``. When *context*
+ is ``True`` *numlines* controls the number of context lines which surround the
+ difference highlights. When *context* is ``False`` *numlines* controls the
+ number of lines which are shown before a difference highlight when using the
+ "next" hyperlinks (setting to zero would cause the "next" hyperlinks to place
+ the next difference highlight at the top of the browser without any leading
+ context).
+
+
+ .. function:: make_table(fromlines, tolines [, fromdesc][, todesc][, context][, numlines])
+
+ Compares *fromlines* and *tolines* (lists of strings) and returns a string which
+ is a complete HTML table showing line by line differences with inter-line and
+ intra-line changes highlighted.
+
+ The arguments for this method are the same as those for the :meth:`make_file`
+ method.
+
+ :file:`Tools/scripts/diff.py` is a command-line front-end to this class and
+ contains a good example of its use.
+
+ .. versionadded:: 2.4
+
+
+.. function:: context_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm])
+
+ Compare *a* and *b* (lists of strings); return a delta (a generator generating
+ the delta lines) in context diff format.
+
+ Context diffs are a compact way of showing just the lines that have changed plus
+ a few lines of context. The changes are shown in a before/after style. The
+ number of context lines is set by *n* which defaults to three.
+
+ By default, the diff control lines (those with ``***`` or ``---``) are created
+ with a trailing newline. This is helpful so that inputs created from
+ :func:`file.readlines` result in diffs that are suitable for use with
+ :func:`file.writelines` since both the inputs and outputs have trailing
+ newlines.
+
+ For inputs that do not have trailing newlines, set the *lineterm* argument to
+ ``""`` so that the output will be uniformly newline free.
+
+ The context diff format normally has a header for filenames and modification
+ times. Any or all of these may be specified using strings for *fromfile*,
+ *tofile*, *fromfiledate*, and *tofiledate*. The modification times are normally
+ expressed in the format returned by :func:`time.ctime`. If not specified, the
+ strings default to blanks.
+
+ :file:`Tools/scripts/diff.py` is a command-line front-end for this function.
+
+ .. versionadded:: 2.3
+
+
+.. function:: get_close_matches(word, possibilities[, n][, cutoff])
+
+ Return a list of the best "good enough" matches. *word* is a sequence for which
+ close matches are desired (typically a string), and *possibilities* is a list of
+ sequences against which to match *word* (typically a list of strings).
+
+ Optional argument *n* (default ``3``) is the maximum number of close matches to
+ return; *n* must be greater than ``0``.
+
+ Optional argument *cutoff* (default ``0.6``) is a float in the range [0, 1].
+ Possibilities that don't score at least that similar to *word* are ignored.
+
+ The best (no more than *n*) matches among the possibilities are returned in a
+ list, sorted by similarity score, most similar first. ::
+
+ >>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])
+ ['apple', 'ape']
+ >>> import keyword
+ >>> get_close_matches('wheel', keyword.kwlist)
+ ['while']
+ >>> get_close_matches('apple', keyword.kwlist)
+ []
+ >>> get_close_matches('accept', keyword.kwlist)
+ ['except']
+
+
+.. function:: ndiff(a, b[, linejunk][, charjunk])
+
+ Compare *a* and *b* (lists of strings); return a :class:`Differ`\ -style delta
+ (a generator generating the delta lines).
+
+ Optional keyword parameters *linejunk* and *charjunk* are for filter functions
+ (or ``None``):
+
+ *linejunk*: A function that accepts a single string argument, and returns true
+ if the string is junk, or false if not. The default is (``None``), starting with
+ Python 2.3. Before then, the default was the module-level function
+ :func:`IS_LINE_JUNK`, which filters out lines without visible characters, except
+ for at most one pound character (``'#'``). As of Python 2.3, the underlying
+ :class:`SequenceMatcher` class does a dynamic analysis of which lines are so
+ frequent as to constitute noise, and this usually works better than the pre-2.3
+ default.
+
+ *charjunk*: A function that accepts a character (a string of length 1), and
+ returns if the character is junk, or false if not. The default is module-level
+ function :func:`IS_CHARACTER_JUNK`, which filters out whitespace characters (a
+ blank or tab; note: bad idea to include newline in this!).
+
+ :file:`Tools/scripts/ndiff.py` is a command-line front-end to this function. ::
+
+ >>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
+ ... 'ore\ntree\nemu\n'.splitlines(1))
+ >>> print ''.join(diff),
+ - one
+ ? ^
+ + ore
+ ? ^
+ - two
+ - three
+ ? -
+ + tree
+ + emu
+
+
+.. function:: restore(sequence, which)
+
+ Return one of the two sequences that generated a delta.
+
+ Given a *sequence* produced by :meth:`Differ.compare` or :func:`ndiff`, extract
+ lines originating from file 1 or 2 (parameter *which*), stripping off line
+ prefixes.
+
+ Example::
+
+ >>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
+ ... 'ore\ntree\nemu\n'.splitlines(1))
+ >>> diff = list(diff) # materialize the generated delta into a list
+ >>> print ''.join(restore(diff, 1)),
+ one
+ two
+ three
+ >>> print ''.join(restore(diff, 2)),
+ ore
+ tree
+ emu
+
+
+.. function:: unified_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm])
+
+ Compare *a* and *b* (lists of strings); return a delta (a generator generating
+ the delta lines) in unified diff format.
+
+ Unified diffs are a compact way of showing just the lines that have changed plus
+ a few lines of context. The changes are shown in a inline style (instead of
+ separate before/after blocks). The number of context lines is set by *n* which
+ defaults to three.
+
+ By default, the diff control lines (those with ``---``, ``+++``, or ``@@``) are
+ created with a trailing newline. This is helpful so that inputs created from
+ :func:`file.readlines` result in diffs that are suitable for use with
+ :func:`file.writelines` since both the inputs and outputs have trailing
+ newlines.
+
+ For inputs that do not have trailing newlines, set the *lineterm* argument to
+ ``""`` so that the output will be uniformly newline free.
+
+ The context diff format normally has a header for filenames and modification
+ times. Any or all of these may be specified using strings for *fromfile*,
+ *tofile*, *fromfiledate*, and *tofiledate*. The modification times are normally
+ expressed in the format returned by :func:`time.ctime`. If not specified, the
+ strings default to blanks.
+
+ :file:`Tools/scripts/diff.py` is a command-line front-end for this function.
+
+ .. versionadded:: 2.3
+
+
+.. function:: IS_LINE_JUNK(line)
+
+ Return true for ignorable lines. The line *line* is ignorable if *line* is
+ blank or contains a single ``'#'``, otherwise it is not ignorable. Used as a
+ default for parameter *linejunk* in :func:`ndiff` before Python 2.3.
+
+
+.. function:: IS_CHARACTER_JUNK(ch)
+
+ Return true for ignorable characters. The character *ch* is ignorable if *ch*
+ is a space or tab, otherwise it is not ignorable. Used as a default for
+ parameter *charjunk* in :func:`ndiff`.
+
+
+.. seealso::
+
+ `Pattern Matching: The Gestalt Approach <http://www.ddj.com/184407970?pgno=5>`_
+ Discussion of a similar algorithm by John W. Ratcliff and D. E. Metzener. This
+ was published in `Dr. Dobb's Journal <http://www.ddj.com/>`_ in July, 1988.
+
+
+.. _sequence-matcher:
+
+SequenceMatcher Objects
+-----------------------
+
+The :class:`SequenceMatcher` class has this constructor:
+
+
+.. class:: SequenceMatcher([isjunk[, a[, b]]])
+
+ Optional argument *isjunk* must be ``None`` (the default) or a one-argument
+ function that takes a sequence element and returns true if and only if the
+ element is "junk" and should be ignored. Passing ``None`` for *isjunk* is
+ equivalent to passing ``lambda x: 0``; in other words, no elements are ignored.
+ For example, pass::
+
+ lambda x: x in " \t"
+
+ if you're comparing lines as sequences of characters, and don't want to synch up
+ on blanks or hard tabs.
+
+ The optional arguments *a* and *b* are sequences to be compared; both default to
+ empty strings. The elements of both sequences must be hashable.
+
+:class:`SequenceMatcher` objects have the following methods:
+
+
+.. method:: SequenceMatcher.set_seqs(a, b)
+
+ Set the two sequences to be compared.
+
+:class:`SequenceMatcher` computes and caches detailed information about the
+second sequence, so if you want to compare one sequence against many sequences,
+use :meth:`set_seq2` to set the commonly used sequence once and call
+:meth:`set_seq1` repeatedly, once for each of the other sequences.
+
+
+.. method:: SequenceMatcher.set_seq1(a)
+
+ Set the first sequence to be compared. The second sequence to be compared is
+ not changed.
+
+
+.. method:: SequenceMatcher.set_seq2(b)
+
+ Set the second sequence to be compared. The first sequence to be compared is
+ not changed.
+
+
+.. method:: SequenceMatcher.find_longest_match(alo, ahi, blo, bhi)
+
+ Find longest matching block in ``a[alo:ahi]`` and ``b[blo:bhi]``.
+
+ If *isjunk* was omitted or ``None``, :meth:`get_longest_match` returns ``(i, j,
+ k)`` such that ``a[i:i+k]`` is equal to ``b[j:j+k]``, where ``alo <= i <= i+k <=
+ ahi`` and ``blo <= j <= j+k <= bhi``. For all ``(i', j', k')`` meeting those
+ conditions, the additional conditions ``k >= k'``, ``i <= i'``, and if ``i ==
+ i'``, ``j <= j'`` are also met. In other words, of all maximal matching blocks,
+ return one that starts earliest in *a*, and of all those maximal matching blocks
+ that start earliest in *a*, return the one that starts earliest in *b*. ::
+
+ >>> s = SequenceMatcher(None, " abcd", "abcd abcd")
+ >>> s.find_longest_match(0, 5, 0, 9)
+ (0, 4, 5)
+
+ If *isjunk* was provided, first the longest matching block is determined as
+ above, but with the additional restriction that no junk element appears in the
+ block. Then that block is extended as far as possible by matching (only) junk
+ elements on both sides. So the resulting block never matches on junk except as
+ identical junk happens to be adjacent to an interesting match.
+
+ Here's the same example as before, but considering blanks to be junk. That
+ prevents ``' abcd'`` from matching the ``' abcd'`` at the tail end of the second
+ sequence directly. Instead only the ``'abcd'`` can match, and matches the
+ leftmost ``'abcd'`` in the second sequence::
+
+ >>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
+ >>> s.find_longest_match(0, 5, 0, 9)
+ (1, 0, 4)
+
+ If no blocks match, this returns ``(alo, blo, 0)``.
+
+
+.. method:: SequenceMatcher.get_matching_blocks()
+
+ Return list of triples describing matching subsequences. Each triple is of the
+ form ``(i, j, n)``, and means that ``a[i:i+n] == b[j:j+n]``. The triples are
+ monotonically increasing in *i* and *j*.
+
+ The last triple is a dummy, and has the value ``(len(a), len(b), 0)``. It is
+ the only triple with ``n == 0``. If ``(i, j, n)`` and ``(i', j', n')`` are
+ adjacent triples in the list, and the second is not the last triple in the list,
+ then ``i+n != i'`` or ``j+n != j'``; in other words, adjacent triples always
+ describe non-adjacent equal blocks.
+
+ .. % Explain why a dummy is used!
+
+ .. versionchanged:: 2.5
+ The guarantee that adjacent triples always describe non-adjacent blocks was
+ implemented.
+
+ ::
+
+ >>> s = SequenceMatcher(None, "abxcd", "abcd")
+ >>> s.get_matching_blocks()
+ [(0, 0, 2), (3, 2, 2), (5, 4, 0)]
+
+
+.. method:: SequenceMatcher.get_opcodes()
+
+ Return list of 5-tuples describing how to turn *a* into *b*. Each tuple is of
+ the form ``(tag, i1, i2, j1, j2)``. The first tuple has ``i1 == j1 == 0``, and
+ remaining tuples have *i1* equal to the *i2* from the preceding tuple, and,
+ likewise, *j1* equal to the previous *j2*.
+
+ The *tag* values are strings, with these meanings:
+
+ +---------------+---------------------------------------------+
+ | Value | Meaning |
+ +===============+=============================================+
+ | ``'replace'`` | ``a[i1:i2]`` should be replaced by |
+ | | ``b[j1:j2]``. |
+ +---------------+---------------------------------------------+
+ | ``'delete'`` | ``a[i1:i2]`` should be deleted. Note that |
+ | | ``j1 == j2`` in this case. |
+ +---------------+---------------------------------------------+
+ | ``'insert'`` | ``b[j1:j2]`` should be inserted at |
+ | | ``a[i1:i1]``. Note that ``i1 == i2`` in |
+ | | this case. |
+ +---------------+---------------------------------------------+
+ | ``'equal'`` | ``a[i1:i2] == b[j1:j2]`` (the sub-sequences |
+ | | are equal). |
+ +---------------+---------------------------------------------+
+
+ For example::
+
+ >>> a = "qabxcd"
+ >>> b = "abycdf"
+ >>> s = SequenceMatcher(None, a, b)
+ >>> for tag, i1, i2, j1, j2 in s.get_opcodes():
+ ... print ("%7s a[%d:%d] (%s) b[%d:%d] (%s)" %
+ ... (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2]))
+ delete a[0:1] (q) b[0:0] ()
+ equal a[1:3] (ab) b[0:2] (ab)
+ replace a[3:4] (x) b[2:3] (y)
+ equal a[4:6] (cd) b[3:5] (cd)
+ insert a[6:6] () b[5:6] (f)
+
+
+.. method:: SequenceMatcher.get_grouped_opcodes([n])
+
+ Return a generator of groups with up to *n* lines of context.
+
+ Starting with the groups returned by :meth:`get_opcodes`, this method splits out
+ smaller change clusters and eliminates intervening ranges which have no changes.
+
+ The groups are returned in the same format as :meth:`get_opcodes`.
+
+ .. versionadded:: 2.3
+
+
+.. method:: SequenceMatcher.ratio()
+
+ Return a measure of the sequences' similarity as a float in the range [0, 1].
+
+ Where T is the total number of elements in both sequences, and M is the number
+ of matches, this is 2.0\*M / T. Note that this is ``1.0`` if the sequences are
+ identical, and ``0.0`` if they have nothing in common.
+
+ This is expensive to compute if :meth:`get_matching_blocks` or
+ :meth:`get_opcodes` hasn't already been called, in which case you may want to
+ try :meth:`quick_ratio` or :meth:`real_quick_ratio` first to get an upper bound.
+
+
+.. method:: SequenceMatcher.quick_ratio()
+
+ Return an upper bound on :meth:`ratio` relatively quickly.
+
+ This isn't defined beyond that it is an upper bound on :meth:`ratio`, and is
+ faster to compute.
+
+
+.. method:: SequenceMatcher.real_quick_ratio()
+
+ Return an upper bound on :meth:`ratio` very quickly.
+
+ This isn't defined beyond that it is an upper bound on :meth:`ratio`, and is
+ faster to compute than either :meth:`ratio` or :meth:`quick_ratio`.
+
+The three methods that return the ratio of matching to total characters can give
+different results due to differing levels of approximation, although
+:meth:`quick_ratio` and :meth:`real_quick_ratio` are always at least as large as
+:meth:`ratio`::
+
+ >>> s = SequenceMatcher(None, "abcd", "bcde")
+ >>> s.ratio()
+ 0.75
+ >>> s.quick_ratio()
+ 0.75
+ >>> s.real_quick_ratio()
+ 1.0
+
+
+.. _sequencematcher-examples:
+
+SequenceMatcher Examples
+------------------------
+
+This example compares two strings, considering blanks to be "junk:" ::
+
+ >>> s = SequenceMatcher(lambda x: x == " ",
+ ... "private Thread currentThread;",
+ ... "private volatile Thread currentThread;")
+
+:meth:`ratio` returns a float in [0, 1], measuring the similarity of the
+sequences. As a rule of thumb, a :meth:`ratio` value over 0.6 means the
+sequences are close matches::
+
+ >>> print round(s.ratio(), 3)
+ 0.866
+
+If you're only interested in where the sequences match,
+:meth:`get_matching_blocks` is handy::
+
+ >>> for block in s.get_matching_blocks():
+ ... print "a[%d] and b[%d] match for %d elements" % block
+ a[0] and b[0] match for 8 elements
+ a[8] and b[17] match for 6 elements
+ a[14] and b[23] match for 15 elements
+ a[29] and b[38] match for 0 elements
+
+Note that the last tuple returned by :meth:`get_matching_blocks` is always a
+dummy, ``(len(a), len(b), 0)``, and this is the only case in which the last
+tuple element (number of elements matched) is ``0``.
+
+If you want to know how to change the first sequence into the second, use
+:meth:`get_opcodes`::
+
+ >>> for opcode in s.get_opcodes():
+ ... print "%6s a[%d:%d] b[%d:%d]" % opcode
+ equal a[0:8] b[0:8]
+ insert a[8:8] b[8:17]
+ equal a[8:14] b[17:23]
+ equal a[14:29] b[23:38]
+
+See also the function :func:`get_close_matches` in this module, which shows how
+simple code building on :class:`SequenceMatcher` can be used to do useful work.
+
+
+.. _differ-objects:
+
+Differ Objects
+--------------
+
+Note that :class:`Differ`\ -generated deltas make no claim to be **minimal**
+diffs. To the contrary, minimal diffs are often counter-intuitive, because they
+synch up anywhere possible, sometimes accidental matches 100 pages apart.
+Restricting synch points to contiguous matches preserves some notion of
+locality, at the occasional cost of producing a longer diff.
+
+The :class:`Differ` class has this constructor:
+
+
+.. class:: Differ([linejunk[, charjunk]])
+
+ Optional keyword parameters *linejunk* and *charjunk* are for filter functions
+ (or ``None``):
+
+ *linejunk*: A function that accepts a single string argument, and returns true
+ if the string is junk. The default is ``None``, meaning that no line is
+ considered junk.
+
+ *charjunk*: A function that accepts a single character argument (a string of
+ length 1), and returns true if the character is junk. The default is ``None``,
+ meaning that no character is considered junk.
+
+:class:`Differ` objects are used (deltas generated) via a single method:
+
+
+.. method:: Differ.compare(a, b)
+
+ Compare two sequences of lines, and generate the delta (a sequence of lines).
+
+ Each sequence must contain individual single-line strings ending with newlines.
+ Such sequences can be obtained from the :meth:`readlines` method of file-like
+ objects. The delta generated also consists of newline-terminated strings, ready
+ to be printed as-is via the :meth:`writelines` method of a file-like object.
+
+
+.. _differ-examples:
+
+Differ Example
+--------------
+
+This example compares two texts. First we set up the texts, sequences of
+individual single-line strings ending with newlines (such sequences can also be
+obtained from the :meth:`readlines` method of file-like objects)::
+
+ >>> text1 = ''' 1. Beautiful is better than ugly.
+ ... 2. Explicit is better than implicit.
+ ... 3. Simple is better than complex.
+ ... 4. Complex is better than complicated.
+ ... '''.splitlines(1)
+ >>> len(text1)
+ 4
+ >>> text1[0][-1]
+ '\n'
+ >>> text2 = ''' 1. Beautiful is better than ugly.
+ ... 3. Simple is better than complex.
+ ... 4. Complicated is better than complex.
+ ... 5. Flat is better than nested.
+ ... '''.splitlines(1)
+
+Next we instantiate a Differ object::
+
+ >>> d = Differ()
+
+Note that when instantiating a :class:`Differ` object we may pass functions to
+filter out line and character "junk." See the :meth:`Differ` constructor for
+details.
+
+Finally, we compare the two::
+
+ >>> result = list(d.compare(text1, text2))
+
+``result`` is a list of strings, so let's pretty-print it::
+
+ >>> from pprint import pprint
+ >>> pprint(result)
+ [' 1. Beautiful is better than ugly.\n',
+ '- 2. Explicit is better than implicit.\n',
+ '- 3. Simple is better than complex.\n',
+ '+ 3. Simple is better than complex.\n',
+ '? ++ \n',
+ '- 4. Complex is better than complicated.\n',
+ '? ^ ---- ^ \n',
+ '+ 4. Complicated is better than complex.\n',
+ '? ++++ ^ ^ \n',
+ '+ 5. Flat is better than nested.\n']
+
+As a single multi-line string it looks like this::
+
+ >>> import sys
+ >>> sys.stdout.writelines(result)
+ 1. Beautiful is better than ugly.
+ - 2. Explicit is better than implicit.
+ - 3. Simple is better than complex.
+ + 3. Simple is better than complex.
+ ? ++
+ - 4. Complex is better than complicated.
+ ? ^ ---- ^
+ + 4. Complicated is better than complex.
+ ? ++++ ^ ^
+ + 5. Flat is better than nested.
+
--- /dev/null
+
+:mod:`dircache` --- Cached directory listings
+=============================================
+
+.. module:: dircache
+ :synopsis: Return directory listing, with cache mechanism.
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+
+
+The :mod:`dircache` module defines a function for reading directory listing
+using a cache, and cache invalidation using the *mtime* of the directory.
+Additionally, it defines a function to annotate directories by appending a
+slash.
+
+The :mod:`dircache` module defines the following functions:
+
+
+.. function:: reset()
+
+ Resets the directory cache.
+
+
+.. function:: listdir(path)
+
+ Return a directory listing of *path*, as gotten from :func:`os.listdir`. Note
+ that unless *path* changes, further call to :func:`listdir` will not re-read the
+ directory structure.
+
+ Note that the list returned should be regarded as read-only. (Perhaps a future
+ version should change it to return a tuple?)
+
+
+.. function:: opendir(path)
+
+ Same as :func:`listdir`. Defined for backwards compatibility.
+
+
+.. function:: annotate(head, list)
+
+ Assume *list* is a list of paths relative to *head*, and append, in place, a
+ ``'/'`` to each path which points to a directory.
+
+::
+
+ >>> import dircache
+ >>> a = dircache.listdir('/')
+ >>> a = a[:] # Copy the return value so we can change 'a'
+ >>> a
+ ['bin', 'boot', 'cdrom', 'dev', 'etc', 'floppy', 'home', 'initrd', 'lib', 'lost+
+ found', 'mnt', 'proc', 'root', 'sbin', 'tmp', 'usr', 'var', 'vmlinuz']
+ >>> dircache.annotate('/', a)
+ >>> a
+ ['bin/', 'boot/', 'cdrom/', 'dev/', 'etc/', 'floppy/', 'home/', 'initrd/', 'lib/
+ ', 'lost+found/', 'mnt/', 'proc/', 'root/', 'sbin/', 'tmp/', 'usr/', 'var/', 'vm
+ linuz']
+
--- /dev/null
+
+:mod:`dis` --- Disassembler for Python byte code
+================================================
+
+.. module:: dis
+ :synopsis: Disassembler for Python byte code.
+
+
+The :mod:`dis` module supports the analysis of Python byte code by disassembling
+it. Since there is no Python assembler, this module defines the Python assembly
+language. The Python byte code which this module takes as an input is defined
+in the file :file:`Include/opcode.h` and used by the compiler and the
+interpreter.
+
+Example: Given the function :func:`myfunc`::
+
+ def myfunc(alist):
+ return len(alist)
+
+the following command can be used to get the disassembly of :func:`myfunc`::
+
+ >>> dis.dis(myfunc)
+ 2 0 LOAD_GLOBAL 0 (len)
+ 3 LOAD_FAST 0 (alist)
+ 6 CALL_FUNCTION 1
+ 9 RETURN_VALUE
+
+(The "2" is a line number).
+
+The :mod:`dis` module defines the following functions and constants:
+
+
+.. function:: dis([bytesource])
+
+ Disassemble the *bytesource* object. *bytesource* can denote either a module, a
+ class, a method, a function, or a code object. For a module, it disassembles
+ all functions. For a class, it disassembles all methods. For a single code
+ sequence, it prints one line per byte code instruction. If no object is
+ provided, it disassembles the last traceback.
+
+
+.. function:: distb([tb])
+
+ Disassembles the top-of-stack function of a traceback, using the last traceback
+ if none was passed. The instruction causing the exception is indicated.
+
+
+.. function:: disassemble(code[, lasti])
+
+ Disassembles a code object, indicating the last instruction if *lasti* was
+ provided. The output is divided in the following columns:
+
+ #. the line number, for the first instruction of each line
+ #. the current instruction, indicated as ``-->``,
+ #. a labelled instruction, indicated with ``>>``,
+ #. the address of the instruction,
+ #. the operation code name,
+ #. operation parameters, and
+ #. interpretation of the parameters in parentheses.
+
+ The parameter interpretation recognizes local and global variable names,
+ constant values, branch targets, and compare operators.
+
+
+.. function:: disco(code[, lasti])
+
+ A synonym for disassemble. It is more convenient to type, and kept for
+ compatibility with earlier Python releases.
+
+
+.. data:: opname
+
+ Sequence of operation names, indexable using the byte code.
+
+
+.. data:: opmap
+
+ Dictionary mapping byte codes to operation names.
+
+
+.. data:: cmp_op
+
+ Sequence of all compare operation names.
+
+
+.. data:: hasconst
+
+ Sequence of byte codes that have a constant parameter.
+
+
+.. data:: hasfree
+
+ Sequence of byte codes that access a free variable.
+
+
+.. data:: hasname
+
+ Sequence of byte codes that access an attribute by name.
+
+
+.. data:: hasjrel
+
+ Sequence of byte codes that have a relative jump target.
+
+
+.. data:: hasjabs
+
+ Sequence of byte codes that have an absolute jump target.
+
+
+.. data:: haslocal
+
+ Sequence of byte codes that access a local variable.
+
+
+.. data:: hascompare
+
+ Sequence of byte codes of Boolean operations.
+
+
+.. _bytecodes:
+
+Python Byte Code Instructions
+-----------------------------
+
+The Python compiler currently generates the following byte code instructions.
+
+
+.. opcode:: STOP_CODE ()
+
+ Indicates end-of-code to the compiler, not used by the interpreter.
+
+
+.. opcode:: NOP ()
+
+ Do nothing code. Used as a placeholder by the bytecode optimizer.
+
+
+.. opcode:: POP_TOP ()
+
+ Removes the top-of-stack (TOS) item.
+
+
+.. opcode:: ROT_TWO ()
+
+ Swaps the two top-most stack items.
+
+
+.. opcode:: ROT_THREE ()
+
+ Lifts second and third stack item one position up, moves top down to position
+ three.
+
+
+.. opcode:: ROT_FOUR ()
+
+ Lifts second, third and forth stack item one position up, moves top down to
+ position four.
+
+
+.. opcode:: DUP_TOP ()
+
+ Duplicates the reference on top of the stack.
+
+Unary Operations take the top of the stack, apply the operation, and push the
+result back on the stack.
+
+
+.. opcode:: UNARY_POSITIVE ()
+
+ Implements ``TOS = +TOS``.
+
+
+.. opcode:: UNARY_NEGATIVE ()
+
+ Implements ``TOS = -TOS``.
+
+
+.. opcode:: UNARY_NOT ()
+
+ Implements ``TOS = not TOS``.
+
+
+.. opcode:: UNARY_CONVERT ()
+
+ Implements ``TOS = `TOS```.
+
+
+.. opcode:: UNARY_INVERT ()
+
+ Implements ``TOS = ~TOS``.
+
+
+.. opcode:: GET_ITER ()
+
+ Implements ``TOS = iter(TOS)``.
+
+Binary operations remove the top of the stack (TOS) and the second top-most
+stack item (TOS1) from the stack. They perform the operation, and put the
+result back on the stack.
+
+
+.. opcode:: BINARY_POWER ()
+
+ Implements ``TOS = TOS1 ** TOS``.
+
+
+.. opcode:: BINARY_MULTIPLY ()
+
+ Implements ``TOS = TOS1 * TOS``.
+
+
+.. opcode:: BINARY_DIVIDE ()
+
+ Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is not
+ in effect.
+
+
+.. opcode:: BINARY_FLOOR_DIVIDE ()
+
+ Implements ``TOS = TOS1 // TOS``.
+
+
+.. opcode:: BINARY_TRUE_DIVIDE ()
+
+ Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is in
+ effect.
+
+
+.. opcode:: BINARY_MODULO ()
+
+ Implements ``TOS = TOS1 % TOS``.
+
+
+.. opcode:: BINARY_ADD ()
+
+ Implements ``TOS = TOS1 + TOS``.
+
+
+.. opcode:: BINARY_SUBTRACT ()
+
+ Implements ``TOS = TOS1 - TOS``.
+
+
+.. opcode:: BINARY_SUBSCR ()
+
+ Implements ``TOS = TOS1[TOS]``.
+
+
+.. opcode:: BINARY_LSHIFT ()
+
+ Implements ``TOS = TOS1 << TOS``.
+
+
+.. opcode:: BINARY_RSHIFT ()
+
+ Implements ``TOS = TOS1 >> TOS``.
+
+
+.. opcode:: BINARY_AND ()
+
+ Implements ``TOS = TOS1 & TOS``.
+
+
+.. opcode:: BINARY_XOR ()
+
+ Implements ``TOS = TOS1 ^ TOS``.
+
+
+.. opcode:: BINARY_OR ()
+
+ Implements ``TOS = TOS1 | TOS``.
+
+In-place operations are like binary operations, in that they remove TOS and
+TOS1, and push the result back on the stack, but the operation is done in-place
+when TOS1 supports it, and the resulting TOS may be (but does not have to be)
+the original TOS1.
+
+
+.. opcode:: INPLACE_POWER ()
+
+ Implements in-place ``TOS = TOS1 ** TOS``.
+
+
+.. opcode:: INPLACE_MULTIPLY ()
+
+ Implements in-place ``TOS = TOS1 * TOS``.
+
+
+.. opcode:: INPLACE_DIVIDE ()
+
+ Implements in-place ``TOS = TOS1 / TOS`` when ``from __future__ import
+ division`` is not in effect.
+
+
+.. opcode:: INPLACE_FLOOR_DIVIDE ()
+
+ Implements in-place ``TOS = TOS1 // TOS``.
+
+
+.. opcode:: INPLACE_TRUE_DIVIDE ()
+
+ Implements in-place ``TOS = TOS1 / TOS`` when ``from __future__ import
+ division`` is in effect.
+
+
+.. opcode:: INPLACE_MODULO ()
+
+ Implements in-place ``TOS = TOS1 % TOS``.
+
+
+.. opcode:: INPLACE_ADD ()
+
+ Implements in-place ``TOS = TOS1 + TOS``.
+
+
+.. opcode:: INPLACE_SUBTRACT ()
+
+ Implements in-place ``TOS = TOS1 - TOS``.
+
+
+.. opcode:: INPLACE_LSHIFT ()
+
+ Implements in-place ``TOS = TOS1 << TOS``.
+
+
+.. opcode:: INPLACE_RSHIFT ()
+
+ Implements in-place ``TOS = TOS1 >> TOS``.
+
+
+.. opcode:: INPLACE_AND ()
+
+ Implements in-place ``TOS = TOS1 & TOS``.
+
+
+.. opcode:: INPLACE_XOR ()
+
+ Implements in-place ``TOS = TOS1 ^ TOS``.
+
+
+.. opcode:: INPLACE_OR ()
+
+ Implements in-place ``TOS = TOS1 | TOS``.
+
+The slice opcodes take up to three parameters.
+
+
+.. opcode:: SLICE+0 ()
+
+ Implements ``TOS = TOS[:]``.
+
+
+.. opcode:: SLICE+1 ()
+
+ Implements ``TOS = TOS1[TOS:]``.
+
+
+.. opcode:: SLICE+2 ()
+
+ Implements ``TOS = TOS1[:TOS]``.
+
+
+.. opcode:: SLICE+3 ()
+
+ Implements ``TOS = TOS2[TOS1:TOS]``.
+
+Slice assignment needs even an additional parameter. As any statement, they put
+nothing on the stack.
+
+
+.. opcode:: STORE_SLICE+0 ()
+
+ Implements ``TOS[:] = TOS1``.
+
+
+.. opcode:: STORE_SLICE+1 ()
+
+ Implements ``TOS1[TOS:] = TOS2``.
+
+
+.. opcode:: STORE_SLICE+2 ()
+
+ Implements ``TOS1[:TOS] = TOS2``.
+
+
+.. opcode:: STORE_SLICE+3 ()
+
+ Implements ``TOS2[TOS1:TOS] = TOS3``.
+
+
+.. opcode:: DELETE_SLICE+0 ()
+
+ Implements ``del TOS[:]``.
+
+
+.. opcode:: DELETE_SLICE+1 ()
+
+ Implements ``del TOS1[TOS:]``.
+
+
+.. opcode:: DELETE_SLICE+2 ()
+
+ Implements ``del TOS1[:TOS]``.
+
+
+.. opcode:: DELETE_SLICE+3 ()
+
+ Implements ``del TOS2[TOS1:TOS]``.
+
+
+.. opcode:: STORE_SUBSCR ()
+
+ Implements ``TOS1[TOS] = TOS2``.
+
+
+.. opcode:: DELETE_SUBSCR ()
+
+ Implements ``del TOS1[TOS]``.
+
+Miscellaneous opcodes.
+
+
+.. opcode:: PRINT_EXPR ()
+
+ Implements the expression statement for the interactive mode. TOS is removed
+ from the stack and printed. In non-interactive mode, an expression statement is
+ terminated with ``POP_STACK``.
+
+
+.. opcode:: PRINT_ITEM ()
+
+ Prints TOS to the file-like object bound to ``sys.stdout``. There is one such
+ instruction for each item in the :keyword:`print` statement.
+
+
+.. opcode:: PRINT_ITEM_TO ()
+
+ Like ``PRINT_ITEM``, but prints the item second from TOS to the file-like object
+ at TOS. This is used by the extended print statement.
+
+
+.. opcode:: PRINT_NEWLINE ()
+
+ Prints a new line on ``sys.stdout``. This is generated as the last operation of
+ a :keyword:`print` statement, unless the statement ends with a comma.
+
+
+.. opcode:: PRINT_NEWLINE_TO ()
+
+ Like ``PRINT_NEWLINE``, but prints the new line on the file-like object on the
+ TOS. This is used by the extended print statement.
+
+
+.. opcode:: BREAK_LOOP ()
+
+ Terminates a loop due to a :keyword:`break` statement.
+
+
+.. opcode:: CONTINUE_LOOP (target)
+
+ Continues a loop due to a :keyword:`continue` statement. *target* is the
+ address to jump to (which should be a ``FOR_ITER`` instruction).
+
+
+.. opcode:: LIST_APPEND ()
+
+ Calls ``list.append(TOS1, TOS)``. Used to implement list comprehensions.
+
+
+.. opcode:: LOAD_LOCALS ()
+
+ Pushes a reference to the locals of the current scope on the stack. This is used
+ in the code for a class definition: After the class body is evaluated, the
+ locals are passed to the class definition.
+
+
+.. opcode:: RETURN_VALUE ()
+
+ Returns with TOS to the caller of the function.
+
+
+.. opcode:: YIELD_VALUE ()
+
+ Pops ``TOS`` and yields it from a generator.
+
+
+.. opcode:: IMPORT_STAR ()
+
+ Loads all symbols not starting with ``'_'`` directly from the module TOS to the
+ local namespace. The module is popped after loading all names. This opcode
+ implements ``from module import *``.
+
+
+.. opcode:: EXEC_STMT ()
+
+ Implements ``exec TOS2,TOS1,TOS``. The compiler fills missing optional
+ parameters with ``None``.
+
+
+.. opcode:: POP_BLOCK ()
+
+ Removes one block from the block stack. Per frame, there is a stack of blocks,
+ denoting nested loops, try statements, and such.
+
+
+.. opcode:: END_FINALLY ()
+
+ Terminates a :keyword:`finally` clause. The interpreter recalls whether the
+ exception has to be re-raised, or whether the function returns, and continues
+ with the outer-next block.
+
+
+.. opcode:: BUILD_CLASS ()
+
+ Creates a new class object. TOS is the methods dictionary, TOS1 the tuple of
+ the names of the base classes, and TOS2 the class name.
+
+All of the following opcodes expect arguments. An argument is two bytes, with
+the more significant byte last.
+
+
+.. opcode:: STORE_NAME (namei)
+
+ Implements ``name = TOS``. *namei* is the index of *name* in the attribute
+ :attr:`co_names` of the code object. The compiler tries to use ``STORE_LOCAL``
+ or ``STORE_GLOBAL`` if possible.
+
+
+.. opcode:: DELETE_NAME (namei)
+
+ Implements ``del name``, where *namei* is the index into :attr:`co_names`
+ attribute of the code object.
+
+
+.. opcode:: UNPACK_SEQUENCE (count)
+
+ Unpacks TOS into *count* individual values, which are put onto the stack
+ right-to-left.
+
+.. % \begin{opcodedesc}{UNPACK_LIST}{count}
+.. % This opcode is obsolete.
+.. % \end{opcodedesc}
+.. % \begin{opcodedesc}{UNPACK_ARG}{count}
+.. % This opcode is obsolete.
+.. % \end{opcodedesc}
+
+
+.. opcode:: DUP_TOPX (count)
+
+ Duplicate *count* items, keeping them in the same order. Due to implementation
+ limits, *count* should be between 1 and 5 inclusive.
+
+
+.. opcode:: STORE_ATTR (namei)
+
+ Implements ``TOS.name = TOS1``, where *namei* is the index of name in
+ :attr:`co_names`.
+
+
+.. opcode:: DELETE_ATTR (namei)
+
+ Implements ``del TOS.name``, using *namei* as index into :attr:`co_names`.
+
+
+.. opcode:: STORE_GLOBAL (namei)
+
+ Works as ``STORE_NAME``, but stores the name as a global.
+
+
+.. opcode:: DELETE_GLOBAL (namei)
+
+ Works as ``DELETE_NAME``, but deletes a global name.
+
+.. % \begin{opcodedesc}{UNPACK_VARARG}{argc}
+.. % This opcode is obsolete.
+.. % \end{opcodedesc}
+
+
+.. opcode:: LOAD_CONST (consti)
+
+ Pushes ``co_consts[consti]`` onto the stack.
+
+
+.. opcode:: LOAD_NAME (namei)
+
+ Pushes the value associated with ``co_names[namei]`` onto the stack.
+
+
+.. opcode:: BUILD_TUPLE (count)
+
+ Creates a tuple consuming *count* items from the stack, and pushes the resulting
+ tuple onto the stack.
+
+
+.. opcode:: BUILD_LIST (count)
+
+ Works as ``BUILD_TUPLE``, but creates a list.
+
+
+.. opcode:: BUILD_MAP (zero)
+
+ Pushes a new empty dictionary object onto the stack. The argument is ignored
+ and set to zero by the compiler.
+
+
+.. opcode:: LOAD_ATTR (namei)
+
+ Replaces TOS with ``getattr(TOS, co_names[namei])``.
+
+
+.. opcode:: COMPARE_OP (opname)
+
+ Performs a Boolean operation. The operation name can be found in
+ ``cmp_op[opname]``.
+
+
+.. opcode:: IMPORT_NAME (namei)
+
+ Imports the module ``co_names[namei]``. The module object is pushed onto the
+ stack. The current namespace is not affected: for a proper import statement, a
+ subsequent ``STORE_FAST`` instruction modifies the namespace.
+
+
+.. opcode:: IMPORT_FROM (namei)
+
+ Loads the attribute ``co_names[namei]`` from the module found in TOS. The
+ resulting object is pushed onto the stack, to be subsequently stored by a
+ ``STORE_FAST`` instruction.
+
+
+.. opcode:: JUMP_FORWARD (delta)
+
+ Increments byte code counter by *delta*.
+
+
+.. opcode:: JUMP_IF_TRUE (delta)
+
+ If TOS is true, increment the byte code counter by *delta*. TOS is left on the
+ stack.
+
+
+.. opcode:: JUMP_IF_FALSE (delta)
+
+ If TOS is false, increment the byte code counter by *delta*. TOS is not
+ changed.
+
+
+.. opcode:: JUMP_ABSOLUTE (target)
+
+ Set byte code counter to *target*.
+
+
+.. opcode:: FOR_ITER (delta)
+
+ ``TOS`` is an iterator. Call its :meth:`next` method. If this yields a new
+ value, push it on the stack (leaving the iterator below it). If the iterator
+ indicates it is exhausted ``TOS`` is popped, and the byte code counter is
+ incremented by *delta*.
+
+.. % \begin{opcodedesc}{FOR_LOOP}{delta}
+.. % This opcode is obsolete.
+.. % \end{opcodedesc}
+.. % \begin{opcodedesc}{LOAD_LOCAL}{namei}
+.. % This opcode is obsolete.
+.. % \end{opcodedesc}
+
+
+.. opcode:: LOAD_GLOBAL (namei)
+
+ Loads the global named ``co_names[namei]`` onto the stack.
+
+.. % \begin{opcodedesc}{SET_FUNC_ARGS}{argc}
+.. % This opcode is obsolete.
+.. % \end{opcodedesc}
+
+
+.. opcode:: SETUP_LOOP (delta)
+
+ Pushes a block for a loop onto the block stack. The block spans from the
+ current instruction with a size of *delta* bytes.
+
+
+.. opcode:: SETUP_EXCEPT (delta)
+
+ Pushes a try block from a try-except clause onto the block stack. *delta* points
+ to the first except block.
+
+
+.. opcode:: SETUP_FINALLY (delta)
+
+ Pushes a try block from a try-except clause onto the block stack. *delta* points
+ to the finally block.
+
+
+.. opcode:: LOAD_FAST (var_num)
+
+ Pushes a reference to the local ``co_varnames[var_num]`` onto the stack.
+
+
+.. opcode:: STORE_FAST (var_num)
+
+ Stores TOS into the local ``co_varnames[var_num]``.
+
+
+.. opcode:: DELETE_FAST (var_num)
+
+ Deletes local ``co_varnames[var_num]``.
+
+
+.. opcode:: LOAD_CLOSURE (i)
+
+ Pushes a reference to the cell contained in slot *i* of the cell and free
+ variable storage. The name of the variable is ``co_cellvars[i]`` if *i* is
+ less than the length of *co_cellvars*. Otherwise it is ``co_freevars[i -
+ len(co_cellvars)]``.
+
+
+.. opcode:: LOAD_DEREF (i)
+
+ Loads the cell contained in slot *i* of the cell and free variable storage.
+ Pushes a reference to the object the cell contains on the stack.
+
+
+.. opcode:: STORE_DEREF (i)
+
+ Stores TOS into the cell contained in slot *i* of the cell and free variable
+ storage.
+
+
+.. opcode:: SET_LINENO (lineno)
+
+ This opcode is obsolete.
+
+
+.. opcode:: RAISE_VARARGS (argc)
+
+ Raises an exception. *argc* indicates the number of parameters to the raise
+ statement, ranging from 0 to 3. The handler will find the traceback as TOS2,
+ the parameter as TOS1, and the exception as TOS.
+
+
+.. opcode:: CALL_FUNCTION (argc)
+
+ Calls a function. The low byte of *argc* indicates the number of positional
+ parameters, the high byte the number of keyword parameters. On the stack, the
+ opcode finds the keyword parameters first. For each keyword argument, the value
+ is on top of the key. Below the keyword parameters, the positional parameters
+ are on the stack, with the right-most parameter on top. Below the parameters,
+ the function object to call is on the stack.
+
+
+.. opcode:: MAKE_FUNCTION (argc)
+
+ Pushes a new function object on the stack. TOS is the code associated with the
+ function. The function object is defined to have *argc* default parameters,
+ which are found below TOS.
+
+
+.. opcode:: MAKE_CLOSURE (argc)
+
+ Creates a new function object, sets its *func_closure* slot, and pushes it on
+ the stack. TOS is the code associated with the function. If the code object has
+ N free variables, the next N items on the stack are the cells for these
+ variables. The function also has *argc* default parameters, where are found
+ before the cells.
+
+
+.. opcode:: BUILD_SLICE (argc)
+
+ .. index:: builtin: slice
+
+ Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2,
+ ``slice(TOS1, TOS)`` is pushed; if it is 3, ``slice(TOS2, TOS1, TOS)`` is
+ pushed. See the ``slice()`` built-in function for more information.
+
+
+.. opcode:: EXTENDED_ARG (ext)
+
+ Prefixes any opcode which has an argument too big to fit into the default two
+ bytes. *ext* holds two additional bytes which, taken together with the
+ subsequent opcode's argument, comprise a four-byte argument, *ext* being the two
+ most-significant bytes.
+
+
+.. opcode:: CALL_FUNCTION_VAR (argc)
+
+ Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element
+ on the stack contains the variable argument list, followed by keyword and
+ positional arguments.
+
+
+.. opcode:: CALL_FUNCTION_KW (argc)
+
+ Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element
+ on the stack contains the keyword arguments dictionary, followed by explicit
+ keyword and positional arguments.
+
+
+.. opcode:: CALL_FUNCTION_VAR_KW (argc)
+
+ Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top
+ element on the stack contains the keyword arguments dictionary, followed by the
+ variable-arguments tuple, followed by explicit keyword and positional arguments.
+
+
+.. opcode:: HAVE_ARGUMENT ()
+
+ This is not really an opcode. It identifies the dividing line between opcodes
+ which don't take arguments ``< HAVE_ARGUMENT`` and those which do ``>=
+ HAVE_ARGUMENT``.
+
--- /dev/null
+
+:mod:`distutils` --- Building and installing Python modules
+===========================================================
+
+.. module:: distutils
+ :synopsis: Support for building and installing Python modules into an existing Python
+ installation.
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+The :mod:`distutils` package provides support for building and installing
+additional modules into a Python installation. The new modules may be either
+100%-pure Python, or may be extension modules written in C, or may be
+collections of Python packages which include modules coded in both Python and C.
+
+This package is discussed in two separate chapters:
+
+
+.. seealso::
+
+ :ref:`distutils-index`
+ The manual for developers and packagers of Python modules. This describes how
+ to prepare :mod:`distutils`\ -based packages so that they may be easily
+ installed into an existing Python installation.
+
+ :ref:`install-index`
+ An "administrators" manual which includes information on installing modules into
+ an existing Python installation. You do not need to be a Python programmer to
+ read this manual.
+
--- /dev/null
+
+:mod:`dl` --- Call C functions in shared objects
+================================================
+
+.. module:: dl
+ :platform: Unix
+ :synopsis: Call C functions in shared objects.
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+
+
+.. % ?????????? Anyone????????????
+
+The :mod:`dl` module defines an interface to the :cfunc:`dlopen` function, which
+is the most common interface on Unix platforms for handling dynamically linked
+libraries. It allows the program to call arbitrary functions in such a library.
+
+.. warning::
+
+ The :mod:`dl` module bypasses the Python type system and error handling. If
+ used incorrectly it may cause segmentation faults, crashes or other incorrect
+ behaviour.
+
+.. note::
+
+ This module will not work unless ``sizeof(int) == sizeof(long) == sizeof(char
+ *)`` If this is not the case, :exc:`SystemError` will be raised on import.
+
+The :mod:`dl` module defines the following function:
+
+
+.. function:: open(name[, mode=RTLD_LAZY])
+
+ Open a shared object file, and return a handle. Mode signifies late binding
+ (:const:`RTLD_LAZY`) or immediate binding (:const:`RTLD_NOW`). Default is
+ :const:`RTLD_LAZY`. Note that some systems do not support :const:`RTLD_NOW`.
+
+ Return value is a :class:`dlobject`.
+
+The :mod:`dl` module defines the following constants:
+
+
+.. data:: RTLD_LAZY
+
+ Useful as an argument to :func:`open`.
+
+
+.. data:: RTLD_NOW
+
+ Useful as an argument to :func:`open`. Note that on systems which do not
+ support immediate binding, this constant will not appear in the module. For
+ maximum portability, use :func:`hasattr` to determine if the system supports
+ immediate binding.
+
+The :mod:`dl` module defines the following exception:
+
+
+.. exception:: error
+
+ Exception raised when an error has occurred inside the dynamic loading and
+ linking routines.
+
+Example::
+
+ >>> import dl, time
+ >>> a=dl.open('/lib/libc.so.6')
+ >>> a.call('time'), time.time()
+ (929723914, 929723914.498)
+
+This example was tried on a Debian GNU/Linux system, and is a good example of
+the fact that using this module is usually a bad alternative.
+
+
+.. _dl-objects:
+
+Dl Objects
+----------
+
+Dl objects, as returned by :func:`open` above, have the following methods:
+
+
+.. method:: dl.close()
+
+ Free all resources, except the memory.
+
+
+.. method:: dl.sym(name)
+
+ Return the pointer for the function named *name*, as a number, if it exists in
+ the referenced shared object, otherwise ``None``. This is useful in code like::
+
+ >>> if a.sym('time'):
+ ... a.call('time')
+ ... else:
+ ... time.time()
+
+ (Note that this function will return a non-zero number, as zero is the *NULL*
+ pointer)
+
+
+.. method:: dl.call(name[, arg1[, arg2...]])
+
+ Call the function named *name* in the referenced shared object. The arguments
+ must be either Python integers, which will be passed as is, Python strings, to
+ which a pointer will be passed, or ``None``, which will be passed as *NULL*.
+ Note that strings should only be passed to functions as :ctype:`const char\*`,
+ as Python will not like its string mutated.
+
+ There must be at most 10 arguments, and arguments not given will be treated as
+ ``None``. The function's return value must be a C :ctype:`long`, which is a
+ Python integer.
+
--- /dev/null
+:mod:`doctest` --- Test interactive Python examples
+===================================================
+
+.. module:: doctest
+ :synopsis: Test pieces of code within docstrings.
+.. moduleauthor:: Tim Peters <tim@python.org>
+.. sectionauthor:: Tim Peters <tim@python.org>
+.. sectionauthor:: Moshe Zadka <moshez@debian.org>
+.. sectionauthor:: Edward Loper <edloper@users.sourceforge.net>
+
+
+The :mod:`doctest` module searches for pieces of text that look like interactive
+Python sessions, and then executes those sessions to verify that they work
+exactly as shown. There are several common ways to use doctest:
+
+* To check that a module's docstrings are up-to-date by verifying that all
+ interactive examples still work as documented.
+
+* To perform regression testing by verifying that interactive examples from a
+ test file or a test object work as expected.
+
+* To write tutorial documentation for a package, liberally illustrated with
+ input-output examples. Depending on whether the examples or the expository text
+ are emphasized, this has the flavor of "literate testing" or "executable
+ documentation".
+
+Here's a complete but small example module::
+
+ """
+ This is the "example" module.
+
+ The example module supplies one function, factorial(). For example,
+
+ >>> factorial(5)
+ 120
+ """
+
+ def factorial(n):
+ """Return the factorial of n, an exact integer >= 0.
+
+ If the result is small enough to fit in an int, return an int.
+ Else return a long.
+
+ >>> [factorial(n) for n in range(6)]
+ [1, 1, 2, 6, 24, 120]
+ >>> [factorial(long(n)) for n in range(6)]
+ [1, 1, 2, 6, 24, 120]
+ >>> factorial(30)
+ 265252859812191058636308480000000L
+ >>> factorial(30L)
+ 265252859812191058636308480000000L
+ >>> factorial(-1)
+ Traceback (most recent call last):
+ ...
+ ValueError: n must be >= 0
+
+ Factorials of floats are OK, but the float must be an exact integer:
+ >>> factorial(30.1)
+ Traceback (most recent call last):
+ ...
+ ValueError: n must be exact integer
+ >>> factorial(30.0)
+ 265252859812191058636308480000000L
+
+ It must also not be ridiculously large:
+ >>> factorial(1e100)
+ Traceback (most recent call last):
+ ...
+ OverflowError: n too large
+ """
+
+
+.. % allow LaTeX to break here.
+
+::
+
+ import math
+ if not n >= 0:
+ raise ValueError("n must be >= 0")
+ if math.floor(n) != n:
+ raise ValueError("n must be exact integer")
+ if n+1 == n: # catch a value like 1e300
+ raise OverflowError("n too large")
+ result = 1
+ factor = 2
+ while factor <= n:
+ result *= factor
+ factor += 1
+ return result
+
+ def _test():
+ import doctest
+ doctest.testmod()
+
+ if __name__ == "__main__":
+ _test()
+
+If you run :file:`example.py` directly from the command line, :mod:`doctest`
+works its magic::
+
+ $ python example.py
+ $
+
+There's no output! That's normal, and it means all the examples worked. Pass
+:option:`-v` to the script, and :mod:`doctest` prints a detailed log of what
+it's trying, and prints a summary at the end::
+
+ $ python example.py -v
+ Trying:
+ factorial(5)
+ Expecting:
+ 120
+ ok
+ Trying:
+ [factorial(n) for n in range(6)]
+ Expecting:
+ [1, 1, 2, 6, 24, 120]
+ ok
+ Trying:
+ [factorial(long(n)) for n in range(6)]
+ Expecting:
+ [1, 1, 2, 6, 24, 120]
+ ok
+
+And so on, eventually ending with::
+
+ Trying:
+ factorial(1e100)
+ Expecting:
+ Traceback (most recent call last):
+ ...
+ OverflowError: n too large
+ ok
+ 1 items had no tests:
+ __main__._test
+ 2 items passed all tests:
+ 1 tests in __main__
+ 8 tests in __main__.factorial
+ 9 tests in 3 items.
+ 9 passed and 0 failed.
+ Test passed.
+ $
+
+That's all you need to know to start making productive use of :mod:`doctest`!
+Jump in. The following sections provide full details. Note that there are many
+examples of doctests in the standard Python test suite and libraries.
+Especially useful examples can be found in the standard test file
+:file:`Lib/test/test_doctest.py`.
+
+
+.. _doctest-simple-testmod:
+
+Simple Usage: Checking Examples in Docstrings
+---------------------------------------------
+
+The simplest way to start using doctest (but not necessarily the way you'll
+continue to do it) is to end each module :mod:`M` with::
+
+ def _test():
+ import doctest
+ doctest.testmod()
+
+ if __name__ == "__main__":
+ _test()
+
+:mod:`doctest` then examines docstrings in module :mod:`M`.
+
+Running the module as a script causes the examples in the docstrings to get
+executed and verified::
+
+ python M.py
+
+This won't display anything unless an example fails, in which case the failing
+example(s) and the cause(s) of the failure(s) are printed to stdout, and the
+final line of output is ``***Test Failed*** N failures.``, where *N* is the
+number of examples that failed.
+
+Run it with the :option:`-v` switch instead::
+
+ python M.py -v
+
+and a detailed report of all examples tried is printed to standard output, along
+with assorted summaries at the end.
+
+You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or
+prohibit it by passing ``verbose=False``. In either of those cases,
+``sys.argv`` is not examined by :func:`testmod` (so passing :option:`-v` or not
+has no effect).
+
+Since Python 2.6, there is also a command line shortcut for running
+:func:`testmod`. You can instruct the Python interpreter to run the doctest
+module directly from the standard library and pass the module name(s) on the
+command line::
+
+ python -m doctest -v example.py
+
+This will import :file:`example.py` as a standalone module and run
+:func:`testmod` on it. Note that this may not work correctly if the file is
+part of a package and imports other submodules from that package.
+
+For more information on :func:`testmod`, see section :ref:`doctest-basic-api`.
+
+
+.. _doctest-simple-testfile:
+
+Simple Usage: Checking Examples in a Text File
+----------------------------------------------
+
+Another simple application of doctest is testing interactive examples in a text
+file. This can be done with the :func:`testfile` function::
+
+ import doctest
+ doctest.testfile("example.txt")
+
+That short script executes and verifies any interactive Python examples
+contained in the file :file:`example.txt`. The file content is treated as if it
+were a single giant docstring; the file doesn't need to contain a Python
+program! For example, perhaps :file:`example.txt` contains this::
+
+ The ``example`` module
+ ======================
+
+ Using ``factorial``
+ -------------------
+
+ This is an example text file in reStructuredText format. First import
+ ``factorial`` from the ``example`` module:
+
+ >>> from example import factorial
+
+ Now use it:
+
+ >>> factorial(6)
+ 120
+
+Running ``doctest.testfile("example.txt")`` then finds the error in this
+documentation::
+
+ File "./example.txt", line 14, in example.txt
+ Failed example:
+ factorial(6)
+ Expected:
+ 120
+ Got:
+ 720
+
+As with :func:`testmod`, :func:`testfile` won't display anything unless an
+example fails. If an example does fail, then the failing example(s) and the
+cause(s) of the failure(s) are printed to stdout, using the same format as
+:func:`testmod`.
+
+By default, :func:`testfile` looks for files in the calling module's directory.
+See section :ref:`doctest-basic-api` for a description of the optional arguments
+that can be used to tell it to look for files in other locations.
+
+Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the
+:option:`-v` command-line switch or with the optional keyword argument
+*verbose*.
+
+Since Python 2.6, there is also a command line shortcut for running
+:func:`testfile`. You can instruct the Python interpreter to run the doctest
+module directly from the standard library and pass the file name(s) on the
+command line::
+
+ python -m doctest -v example.txt
+
+Because the file name does not end with :file:`.py`, :mod:`doctest` infers that
+it must be run with :func:`testfile`, not :func:`testmod`.
+
+For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
+
+
+.. _doctest-how-it-works:
+
+How It Works
+------------
+
+This section examines in detail how doctest works: which docstrings it looks at,
+how it finds interactive examples, what execution context it uses, how it
+handles exceptions, and how option flags can be used to control its behavior.
+This is the information that you need to know to write doctest examples; for
+information about actually running doctest on these examples, see the following
+sections.
+
+
+.. _doctest-which-docstrings:
+
+Which Docstrings Are Examined?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The module docstring, and all function, class and method docstrings are
+searched. Objects imported into the module are not searched.
+
+In addition, if ``M.__test__`` exists and "is true", it must be a dict, and each
+entry maps a (string) name to a function object, class object, or string.
+Function and class object docstrings found from ``M.__test__`` are searched, and
+strings are treated as if they were docstrings. In output, a key ``K`` in
+``M.__test__`` appears with name ::
+
+ <name of M>.__test__.K
+
+Any classes found are recursively searched similarly, to test docstrings in
+their contained methods and nested classes.
+
+.. versionchanged:: 2.4
+ A "private name" concept is deprecated and no longer documented.
+
+
+.. _doctest-finding-examples:
+
+How are Docstring Examples Recognized?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In most cases a copy-and-paste of an interactive console session works fine, but
+doctest isn't trying to do an exact emulation of any specific Python shell. All
+hard tab characters are expanded to spaces, using 8-column tab stops. If you
+don't believe tabs should mean that, too bad: don't use hard tabs, or write
+your own :class:`DocTestParser` class.
+
+.. versionchanged:: 2.4
+ Expanding tabs to spaces is new; previous versions tried to preserve hard tabs,
+ with confusing results.
+
+::
+
+ >>> # comments are ignored
+ >>> x = 12
+ >>> x
+ 12
+ >>> if x == 13:
+ ... print "yes"
+ ... else:
+ ... print "no"
+ ... print "NO"
+ ... print "NO!!!"
+ ...
+ no
+ NO
+ NO!!!
+ >>>
+
+Any expected output must immediately follow the final ``'>>> '`` or ``'... '``
+line containing the code, and the expected output (if any) extends to the next
+``'>>> '`` or all-whitespace line.
+
+The fine print:
+
+* Expected output cannot contain an all-whitespace line, since such a line is
+ taken to signal the end of expected output. If expected output does contain a
+ blank line, put ``<BLANKLINE>`` in your doctest example each place a blank line
+ is expected.
+
+ .. versionchanged:: 2.4
+ ``<BLANKLINE>`` was added; there was no way to use expected output containing
+ empty lines in previous versions.
+
+* Output to stdout is captured, but not output to stderr (exception tracebacks
+ are captured via a different means).
+
+* If you continue a line via backslashing in an interactive session, or for any
+ other reason use a backslash, you should use a raw docstring, which will
+ preserve your backslashes exactly as you type them::
+
+ >>> def f(x):
+ ... r'''Backslashes in a raw docstring: m\n'''
+ >>> print f.__doc__
+ Backslashes in a raw docstring: m\n
+
+ Otherwise, the backslash will be interpreted as part of the string. For example,
+ the "\\" above would be interpreted as a newline character. Alternatively, you
+ can double each backslash in the doctest version (and not use a raw string)::
+
+ >>> def f(x):
+ ... '''Backslashes in a raw docstring: m\\n'''
+ >>> print f.__doc__
+ Backslashes in a raw docstring: m\n
+
+* The starting column doesn't matter::
+
+ >>> assert "Easy!"
+ >>> import math
+ >>> math.floor(1.9)
+ 1.0
+
+ and as many leading whitespace characters are stripped from the expected output
+ as appeared in the initial ``'>>> '`` line that started the example.
+
+
+.. _doctest-execution-context:
+
+What's the Execution Context?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, each time :mod:`doctest` finds a docstring to test, it uses a
+*shallow copy* of :mod:`M`'s globals, so that running tests doesn't change the
+module's real globals, and so that one test in :mod:`M` can't leave behind
+crumbs that accidentally allow another test to work. This means examples can
+freely use any names defined at top-level in :mod:`M`, and names defined earlier
+in the docstring being run. Examples cannot see names defined in other
+docstrings.
+
+You can force use of your own dict as the execution context by passing
+``globs=your_dict`` to :func:`testmod` or :func:`testfile` instead.
+
+
+.. _doctest-exceptions:
+
+What About Exceptions?
+^^^^^^^^^^^^^^^^^^^^^^
+
+No problem, provided that the traceback is the only output produced by the
+example: just paste in the traceback. [#]_ Since tracebacks contain details
+that are likely to change rapidly (for example, exact file paths and line
+numbers), this is one case where doctest works hard to be flexible in what it
+accepts.
+
+Simple example::
+
+ >>> [1, 2, 3].remove(42)
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ ValueError: list.remove(x): x not in list
+
+That doctest succeeds if :exc:`ValueError` is raised, with the ``list.remove(x):
+x not in list`` detail as shown.
+
+The expected output for an exception must start with a traceback header, which
+may be either of the following two lines, indented the same as the first line of
+the example::
+
+ Traceback (most recent call last):
+ Traceback (innermost last):
+
+The traceback header is followed by an optional traceback stack, whose contents
+are ignored by doctest. The traceback stack is typically omitted, or copied
+verbatim from an interactive session.
+
+The traceback stack is followed by the most interesting part: the line(s)
+containing the exception type and detail. This is usually the last line of a
+traceback, but can extend across multiple lines if the exception has a
+multi-line detail::
+
+ >>> raise ValueError('multi\n line\ndetail')
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ ValueError: multi
+ line
+ detail
+
+The last three lines (starting with :exc:`ValueError`) are compared against the
+exception's type and detail, and the rest are ignored.
+
+Best practice is to omit the traceback stack, unless it adds significant
+documentation value to the example. So the last example is probably better as::
+
+ >>> raise ValueError('multi\n line\ndetail')
+ Traceback (most recent call last):
+ ...
+ ValueError: multi
+ line
+ detail
+
+Note that tracebacks are treated very specially. In particular, in the
+rewritten example, the use of ``...`` is independent of doctest's
+:const:`ELLIPSIS` option. The ellipsis in that example could be left out, or
+could just as well be three (or three hundred) commas or digits, or an indented
+transcript of a Monty Python skit.
+
+Some details you should read once, but won't need to remember:
+
+* Doctest can't guess whether your expected output came from an exception
+ traceback or from ordinary printing. So, e.g., an example that expects
+ ``ValueError: 42 is prime`` will pass whether :exc:`ValueError` is actually
+ raised or if the example merely prints that traceback text. In practice,
+ ordinary output rarely begins with a traceback header line, so this doesn't
+ create real problems.
+
+* Each line of the traceback stack (if present) must be indented further than
+ the first line of the example, *or* start with a non-alphanumeric character.
+ The first line following the traceback header indented the same and starting
+ with an alphanumeric is taken to be the start of the exception detail. Of
+ course this does the right thing for genuine tracebacks.
+
+* When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is is specified,
+ everything following the leftmost colon is ignored.
+
+* The interactive shell omits the traceback header line for some
+ :exc:`SyntaxError`\ s. But doctest uses the traceback header line to
+ distinguish exceptions from non-exceptions. So in the rare case where you need
+ to test a :exc:`SyntaxError` that omits the traceback header, you will need to
+ manually add the traceback header line to your test example.
+
+* For some :exc:`SyntaxError`\ s, Python displays the character position of the
+ syntax error, using a ``^`` marker::
+
+ >>> 1 1
+ File "<stdin>", line 1
+ 1 1
+ ^
+ SyntaxError: invalid syntax
+
+ Since the lines showing the position of the error come before the exception type
+ and detail, they are not checked by doctest. For example, the following test
+ would pass, even though it puts the ``^`` marker in the wrong location::
+
+ >>> 1 1
+ Traceback (most recent call last):
+ File "<stdin>", line 1
+ 1 1
+ ^
+ SyntaxError: invalid syntax
+
+.. versionchanged:: 2.4
+ The ability to handle a multi-line exception detail, and the
+ :const:`IGNORE_EXCEPTION_DETAIL` doctest option, were added.
+
+
+.. _doctest-options:
+
+Option Flags and Directives
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A number of option flags control various aspects of doctest's behavior.
+Symbolic names for the flags are supplied as module constants, which can be
+or'ed together and passed to various functions. The names can also be used in
+doctest directives (see below).
+
+The first group of options define test semantics, controlling aspects of how
+doctest decides whether actual output matches an example's expected output:
+
+
+.. data:: DONT_ACCEPT_TRUE_FOR_1
+
+ By default, if an expected output block contains just ``1``, an actual output
+ block containing just ``1`` or just ``True`` is considered to be a match, and
+ similarly for ``0`` versus ``False``. When :const:`DONT_ACCEPT_TRUE_FOR_1` is
+ specified, neither substitution is allowed. The default behavior caters to that
+ Python changed the return type of many functions from integer to boolean;
+ doctests expecting "little integer" output still work in these cases. This
+ option will probably go away, but not for several years.
+
+
+.. data:: DONT_ACCEPT_BLANKLINE
+
+ By default, if an expected output block contains a line containing only the
+ string ``<BLANKLINE>``, then that line will match a blank line in the actual
+ output. Because a genuinely blank line delimits the expected output, this is
+ the only way to communicate that a blank line is expected. When
+ :const:`DONT_ACCEPT_BLANKLINE` is specified, this substitution is not allowed.
+
+
+.. data:: NORMALIZE_WHITESPACE
+
+ When specified, all sequences of whitespace (blanks and newlines) are treated as
+ equal. Any sequence of whitespace within the expected output will match any
+ sequence of whitespace within the actual output. By default, whitespace must
+ match exactly. :const:`NORMALIZE_WHITESPACE` is especially useful when a line of
+ expected output is very long, and you want to wrap it across multiple lines in
+ your source.
+
+
+.. data:: ELLIPSIS
+
+ When specified, an ellipsis marker (``...``) in the expected output can match
+ any substring in the actual output. This includes substrings that span line
+ boundaries, and empty substrings, so it's best to keep usage of this simple.
+ Complicated uses can lead to the same kinds of "oops, it matched too much!"
+ surprises that ``.*`` is prone to in regular expressions.
+
+
+.. data:: IGNORE_EXCEPTION_DETAIL
+
+ When specified, an example that expects an exception passes if an exception of
+ the expected type is raised, even if the exception detail does not match. For
+ example, an example expecting ``ValueError: 42`` will pass if the actual
+ exception raised is ``ValueError: 3*14``, but will fail, e.g., if
+ :exc:`TypeError` is raised.
+
+ Note that a similar effect can be obtained using :const:`ELLIPSIS`, and
+ :const:`IGNORE_EXCEPTION_DETAIL` may go away when Python releases prior to 2.4
+ become uninteresting. Until then, :const:`IGNORE_EXCEPTION_DETAIL` is the only
+ clear way to write a doctest that doesn't care about the exception detail yet
+ continues to pass under Python releases prior to 2.4 (doctest directives appear
+ to be comments to them). For example, ::
+
+ >>> (1, 2)[3] = 'moo' #doctest: +IGNORE_EXCEPTION_DETAIL
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ TypeError: object doesn't support item assignment
+
+ passes under Python 2.4 and Python 2.3. The detail changed in 2.4, to say "does
+ not" instead of "doesn't".
+
+
+.. data:: SKIP
+
+ When specified, do not run the example at all. This can be useful in contexts
+ where doctest examples serve as both documentation and test cases, and an
+ example should be included for documentation purposes, but should not be
+ checked. E.g., the example's output might be random; or the example might
+ depend on resources which would be unavailable to the test driver.
+
+ The SKIP flag can also be used for temporarily "commenting out" examples.
+
+
+.. data:: COMPARISON_FLAGS
+
+ A bitmask or'ing together all the comparison flags above.
+
+The second group of options controls how test failures are reported:
+
+
+.. data:: REPORT_UDIFF
+
+ When specified, failures that involve multi-line expected and actual outputs are
+ displayed using a unified diff.
+
+
+.. data:: REPORT_CDIFF
+
+ When specified, failures that involve multi-line expected and actual outputs
+ will be displayed using a context diff.
+
+
+.. data:: REPORT_NDIFF
+
+ When specified, differences are computed by ``difflib.Differ``, using the same
+ algorithm as the popular :file:`ndiff.py` utility. This is the only method that
+ marks differences within lines as well as across lines. For example, if a line
+ of expected output contains digit ``1`` where actual output contains letter
+ ``l``, a line is inserted with a caret marking the mismatching column positions.
+
+
+.. data:: REPORT_ONLY_FIRST_FAILURE
+
+ When specified, display the first failing example in each doctest, but suppress
+ output for all remaining examples. This will prevent doctest from reporting
+ correct examples that break because of earlier failures; but it might also hide
+ incorrect examples that fail independently of the first failure. When
+ :const:`REPORT_ONLY_FIRST_FAILURE` is specified, the remaining examples are
+ still run, and still count towards the total number of failures reported; only
+ the output is suppressed.
+
+
+.. data:: REPORTING_FLAGS
+
+ A bitmask or'ing together all the reporting flags above.
+
+"Doctest directives" may be used to modify the option flags for individual
+examples. Doctest directives are expressed as a special Python comment
+following an example's source code:
+
+.. productionlist:: doctest
+ directive: "#" "doctest:" `directive_options`
+ directive_options: `directive_option` ("," `directive_option`)\*
+ directive_option: `on_or_off` `directive_option_name`
+ on_or_off: "+" \| "-"
+ directive_option_name: "DONT_ACCEPT_BLANKLINE" \| "NORMALIZE_WHITESPACE" \| ...
+
+Whitespace is not allowed between the ``+`` or ``-`` and the directive option
+name. The directive option name can be any of the option flag names explained
+above.
+
+An example's doctest directives modify doctest's behavior for that single
+example. Use ``+`` to enable the named behavior, or ``-`` to disable it.
+
+For example, this test passes::
+
+ >>> print range(20) #doctest: +NORMALIZE_WHITESPACE
+ [0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
+ 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
+
+Without the directive it would fail, both because the actual output doesn't have
+two blanks before the single-digit list elements, and because the actual output
+is on a single line. This test also passes, and also requires a directive to do
+so::
+
+ >>> print range(20) # doctest:+ELLIPSIS
+ [0, 1, ..., 18, 19]
+
+Multiple directives can be used on a single physical line, separated by commas::
+
+ >>> print range(20) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
+ [0, 1, ..., 18, 19]
+
+If multiple directive comments are used for a single example, then they are
+combined::
+
+ >>> print range(20) # doctest: +ELLIPSIS
+ ... # doctest: +NORMALIZE_WHITESPACE
+ [0, 1, ..., 18, 19]
+
+As the previous example shows, you can add ``...`` lines to your example
+containing only directives. This can be useful when an example is too long for
+a directive to comfortably fit on the same line::
+
+ >>> print range(5) + range(10,20) + range(30,40) + range(50,60)
+ ... # doctest: +ELLIPSIS
+ [0, ..., 4, 10, ..., 19, 30, ..., 39, 50, ..., 59]
+
+Note that since all options are disabled by default, and directives apply only
+to the example they appear in, enabling options (via ``+`` in a directive) is
+usually the only meaningful choice. However, option flags can also be passed to
+functions that run doctests, establishing different defaults. In such cases,
+disabling an option via ``-`` in a directive can be useful.
+
+.. versionchanged:: 2.4
+ Constants :const:`DONT_ACCEPT_BLANKLINE`, :const:`NORMALIZE_WHITESPACE`,
+ :const:`ELLIPSIS`, :const:`IGNORE_EXCEPTION_DETAIL`, :const:`REPORT_UDIFF`,
+ :const:`REPORT_CDIFF`, :const:`REPORT_NDIFF`,
+ :const:`REPORT_ONLY_FIRST_FAILURE`, :const:`COMPARISON_FLAGS` and
+ :const:`REPORTING_FLAGS` were added; by default ``<BLANKLINE>`` in expected
+ output matches an empty line in actual output; and doctest directives were
+ added.
+
+.. versionchanged:: 2.5
+ Constant :const:`SKIP` was added.
+
+There's also a way to register new option flag names, although this isn't useful
+unless you intend to extend :mod:`doctest` internals via subclassing:
+
+
+.. function:: register_optionflag(name)
+
+ Create a new option flag with a given name, and return the new flag's integer
+ value. :func:`register_optionflag` can be used when subclassing
+ :class:`OutputChecker` or :class:`DocTestRunner` to create new options that are
+ supported by your subclasses. :func:`register_optionflag` should always be
+ called using the following idiom::
+
+ MY_FLAG = register_optionflag('MY_FLAG')
+
+ .. versionadded:: 2.4
+
+
+.. _doctest-warnings:
+
+Warnings
+^^^^^^^^
+
+:mod:`doctest` is serious about requiring exact matches in expected output. If
+even a single character doesn't match, the test fails. This will probably
+surprise you a few times, as you learn exactly what Python does and doesn't
+guarantee about output. For example, when printing a dict, Python doesn't
+guarantee that the key-value pairs will be printed in any particular order, so a
+test like
+
+.. % Hey! What happened to Monty Python examples?
+.. % Tim: ask Guido -- it's his example!
+
+::
+
+ >>> foo()
+ {"Hermione": "hippogryph", "Harry": "broomstick"}
+
+is vulnerable! One workaround is to do ::
+
+ >>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
+ True
+
+instead. Another is to do ::
+
+ >>> d = foo().items()
+ >>> d.sort()
+ >>> d
+ [('Harry', 'broomstick'), ('Hermione', 'hippogryph')]
+
+There are others, but you get the idea.
+
+Another bad idea is to print things that embed an object address, like ::
+
+ >>> id(1.0) # certain to fail some of the time
+ 7948648
+ >>> class C: pass
+ >>> C() # the default repr() for instances embeds an address
+ <__main__.C instance at 0x00AC18F0>
+
+The :const:`ELLIPSIS` directive gives a nice approach for the last example::
+
+ >>> C() #doctest: +ELLIPSIS
+ <__main__.C instance at 0x...>
+
+Floating-point numbers are also subject to small output variations across
+platforms, because Python defers to the platform C library for float formatting,
+and C libraries vary widely in quality here. ::
+
+ >>> 1./7 # risky
+ 0.14285714285714285
+ >>> print 1./7 # safer
+ 0.142857142857
+ >>> print round(1./7, 6) # much safer
+ 0.142857
+
+Numbers of the form ``I/2.**J`` are safe across all platforms, and I often
+contrive doctest examples to produce numbers of that form::
+
+ >>> 3./4 # utterly safe
+ 0.75
+
+Simple fractions are also easier for people to understand, and that makes for
+better documentation.
+
+
+.. _doctest-basic-api:
+
+Basic API
+---------
+
+The functions :func:`testmod` and :func:`testfile` provide a simple interface to
+doctest that should be sufficient for most basic uses. For a less formal
+introduction to these two functions, see sections :ref:`doctest-simple-testmod`
+and :ref:`doctest-simple-testfile`.
+
+
+.. function:: testfile(filename[, module_relative][, name][, package][, globs][, verbose][, report][, optionflags][, extraglobs][, raise_on_error][, parser][, encoding])
+
+ All arguments except *filename* are optional, and should be specified in keyword
+ form.
+
+ Test examples in the file named *filename*. Return ``(failure_count,
+ test_count)``.
+
+ Optional argument *module_relative* specifies how the filename should be
+ interpreted:
+
+ * If *module_relative* is ``True`` (the default), then *filename* specifies an
+ OS-independent module-relative path. By default, this path is relative to the
+ calling module's directory; but if the *package* argument is specified, then it
+ is relative to that package. To ensure OS-independence, *filename* should use
+ ``/`` characters to separate path segments, and may not be an absolute path
+ (i.e., it may not begin with ``/``).
+
+ * If *module_relative* is ``False``, then *filename* specifies an OS-specific
+ path. The path may be absolute or relative; relative paths are resolved with
+ respect to the current working directory.
+
+ Optional argument *name* gives the name of the test; by default, or if ``None``,
+ ``os.path.basename(filename)`` is used.
+
+ Optional argument *package* is a Python package or the name of a Python package
+ whose directory should be used as the base directory for a module-relative
+ filename. If no package is specified, then the calling module's directory is
+ used as the base directory for module-relative filenames. It is an error to
+ specify *package* if *module_relative* is ``False``.
+
+ Optional argument *globs* gives a dict to be used as the globals when executing
+ examples. A new shallow copy of this dict is created for the doctest, so its
+ examples start with a clean slate. By default, or if ``None``, a new empty dict
+ is used.
+
+ Optional argument *extraglobs* gives a dict merged into the globals used to
+ execute examples. This works like :meth:`dict.update`: if *globs* and
+ *extraglobs* have a common key, the associated value in *extraglobs* appears in
+ the combined dict. By default, or if ``None``, no extra globals are used. This
+ is an advanced feature that allows parameterization of doctests. For example, a
+ doctest can be written for a base class, using a generic name for the class,
+ then reused to test any number of subclasses by passing an *extraglobs* dict
+ mapping the generic name to the subclass to be tested.
+
+ Optional argument *verbose* prints lots of stuff if true, and prints only
+ failures if false; by default, or if ``None``, it's true if and only if ``'-v'``
+ is in ``sys.argv``.
+
+ Optional argument *report* prints a summary at the end when true, else prints
+ nothing at the end. In verbose mode, the summary is detailed, else the summary
+ is very brief (in fact, empty if all tests passed).
+
+ Optional argument *optionflags* or's together option flags. See section
+ :ref:`doctest-options`.
+
+ Optional argument *raise_on_error* defaults to false. If true, an exception is
+ raised upon the first failure or unexpected exception in an example. This
+ allows failures to be post-mortem debugged. Default behavior is to continue
+ running examples.
+
+ Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) that
+ should be used to extract tests from the files. It defaults to a normal parser
+ (i.e., ``DocTestParser()``).
+
+ Optional argument *encoding* specifies an encoding that should be used to
+ convert the file to unicode.
+
+ .. versionadded:: 2.4
+
+ .. versionchanged:: 2.5
+ The parameter *encoding* was added.
+
+
+.. function:: testmod([m][, name][, globs][, verbose][, report][, optionflags][, extraglobs][, raise_on_error][, exclude_empty])
+
+ All arguments are optional, and all except for *m* should be specified in
+ keyword form.
+
+ Test examples in docstrings in functions and classes reachable from module *m*
+ (or module :mod:`__main__` if *m* is not supplied or is ``None``), starting with
+ ``m.__doc__``.
+
+ Also test examples reachable from dict ``m.__test__``, if it exists and is not
+ ``None``. ``m.__test__`` maps names (strings) to functions, classes and
+ strings; function and class docstrings are searched for examples; strings are
+ searched directly, as if they were docstrings.
+
+ Only docstrings attached to objects belonging to module *m* are searched.
+
+ Return ``(failure_count, test_count)``.
+
+ Optional argument *name* gives the name of the module; by default, or if
+ ``None``, ``m.__name__`` is used.
+
+ Optional argument *exclude_empty* defaults to false. If true, objects for which
+ no doctests are found are excluded from consideration. The default is a backward
+ compatibility hack, so that code still using :meth:`doctest.master.summarize` in
+ conjunction with :func:`testmod` continues to get output for objects with no
+ tests. The *exclude_empty* argument to the newer :class:`DocTestFinder`
+ constructor defaults to true.
+
+ Optional arguments *extraglobs*, *verbose*, *report*, *optionflags*,
+ *raise_on_error*, and *globs* are the same as for function :func:`testfile`
+ above, except that *globs* defaults to ``m.__dict__``.
+
+ .. versionchanged:: 2.3
+ The parameter *optionflags* was added.
+
+ .. versionchanged:: 2.4
+ The parameters *extraglobs*, *raise_on_error* and *exclude_empty* were added.
+
+ .. versionchanged:: 2.5
+ The optional argument *isprivate*, deprecated in 2.4, was removed.
+
+There's also a function to run the doctests associated with a single object.
+This function is provided for backward compatibility. There are no plans to
+deprecate it, but it's rarely useful:
+
+
+.. function:: run_docstring_examples(f, globs[, verbose][, name][, compileflags][, optionflags])
+
+ Test examples associated with object *f*; for example, *f* may be a module,
+ function, or class object.
+
+ A shallow copy of dictionary argument *globs* is used for the execution context.
+
+ Optional argument *name* is used in failure messages, and defaults to
+ ``"NoName"``.
+
+ If optional argument *verbose* is true, output is generated even if there are no
+ failures. By default, output is generated only in case of an example failure.
+
+ Optional argument *compileflags* gives the set of flags that should be used by
+ the Python compiler when running the examples. By default, or if ``None``,
+ flags are deduced corresponding to the set of future features found in *globs*.
+
+ Optional argument *optionflags* works as for function :func:`testfile` above.
+
+
+.. _doctest-unittest-api:
+
+Unittest API
+------------
+
+As your collection of doctest'ed modules grows, you'll want a way to run all
+their doctests systematically. Prior to Python 2.4, :mod:`doctest` had a barely
+documented :class:`Tester` class that supplied a rudimentary way to combine
+doctests from multiple modules. :class:`Tester` was feeble, and in practice most
+serious Python testing frameworks build on the :mod:`unittest` module, which
+supplies many flexible ways to combine tests from multiple sources. So, in
+Python 2.4, :mod:`doctest`'s :class:`Tester` class is deprecated, and
+:mod:`doctest` provides two functions that can be used to create :mod:`unittest`
+test suites from modules and text files containing doctests. These test suites
+can then be run using :mod:`unittest` test runners::
+
+ import unittest
+ import doctest
+ import my_module_with_doctests, and_another
+
+ suite = unittest.TestSuite()
+ for mod in my_module_with_doctests, and_another:
+ suite.addTest(doctest.DocTestSuite(mod))
+ runner = unittest.TextTestRunner()
+ runner.run(suite)
+
+There are two main functions for creating :class:`unittest.TestSuite` instances
+from text files and modules with doctests:
+
+
+.. function:: DocFileSuite([module_relative][, package][, setUp][, tearDown][, globs][, optionflags][, parser][, encoding])
+
+ Convert doctest tests from one or more text files to a
+ :class:`unittest.TestSuite`.
+
+ The returned :class:`unittest.TestSuite` is to be run by the unittest framework
+ and runs the interactive examples in each file. If an example in any file
+ fails, then the synthesized unit test fails, and a :exc:`failureException`
+ exception is raised showing the name of the file containing the test and a
+ (sometimes approximate) line number.
+
+ Pass one or more paths (as strings) to text files to be examined.
+
+ Options may be provided as keyword arguments:
+
+ Optional argument *module_relative* specifies how the filenames in *paths*
+ should be interpreted:
+
+ * If *module_relative* is ``True`` (the default), then each filename specifies
+ an OS-independent module-relative path. By default, this path is relative to
+ the calling module's directory; but if the *package* argument is specified, then
+ it is relative to that package. To ensure OS-independence, each filename should
+ use ``/`` characters to separate path segments, and may not be an absolute path
+ (i.e., it may not begin with ``/``).
+
+ * If *module_relative* is ``False``, then each filename specifies an OS-specific
+ path. The path may be absolute or relative; relative paths are resolved with
+ respect to the current working directory.
+
+ Optional argument *package* is a Python package or the name of a Python package
+ whose directory should be used as the base directory for module-relative
+ filenames. If no package is specified, then the calling module's directory is
+ used as the base directory for module-relative filenames. It is an error to
+ specify *package* if *module_relative* is ``False``.
+
+ Optional argument *setUp* specifies a set-up function for the test suite. This
+ is called before running the tests in each file. The *setUp* function will be
+ passed a :class:`DocTest` object. The setUp function can access the test
+ globals as the *globs* attribute of the test passed.
+
+ Optional argument *tearDown* specifies a tear-down function for the test suite.
+ This is called after running the tests in each file. The *tearDown* function
+ will be passed a :class:`DocTest` object. The setUp function can access the
+ test globals as the *globs* attribute of the test passed.
+
+ Optional argument *globs* is a dictionary containing the initial global
+ variables for the tests. A new copy of this dictionary is created for each
+ test. By default, *globs* is a new empty dictionary.
+
+ Optional argument *optionflags* specifies the default doctest options for the
+ tests, created by or-ing together individual option flags. See section
+ :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below for
+ a better way to set reporting options.
+
+ Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) that
+ should be used to extract tests from the files. It defaults to a normal parser
+ (i.e., ``DocTestParser()``).
+
+ Optional argument *encoding* specifies an encoding that should be used to
+ convert the file to unicode.
+
+ .. versionadded:: 2.4
+
+ .. versionchanged:: 2.5
+ The global ``__file__`` was added to the globals provided to doctests loaded
+ from a text file using :func:`DocFileSuite`.
+
+ .. versionchanged:: 2.5
+ The parameter *encoding* was added.
+
+
+.. function:: DocTestSuite([module][, globs][, extraglobs][, test_finder][, setUp][, tearDown][, checker])
+
+ Convert doctest tests for a module to a :class:`unittest.TestSuite`.
+
+ The returned :class:`unittest.TestSuite` is to be run by the unittest framework
+ and runs each doctest in the module. If any of the doctests fail, then the
+ synthesized unit test fails, and a :exc:`failureException` exception is raised
+ showing the name of the file containing the test and a (sometimes approximate)
+ line number.
+
+ Optional argument *module* provides the module to be tested. It can be a module
+ object or a (possibly dotted) module name. If not specified, the module calling
+ this function is used.
+
+ Optional argument *globs* is a dictionary containing the initial global
+ variables for the tests. A new copy of this dictionary is created for each
+ test. By default, *globs* is a new empty dictionary.
+
+ Optional argument *extraglobs* specifies an extra set of global variables, which
+ is merged into *globs*. By default, no extra globals are used.
+
+ Optional argument *test_finder* is the :class:`DocTestFinder` object (or a
+ drop-in replacement) that is used to extract doctests from the module.
+
+ Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as for
+ function :func:`DocFileSuite` above.
+
+ .. versionadded:: 2.3
+
+ .. versionchanged:: 2.4
+ The parameters *globs*, *extraglobs*, *test_finder*, *setUp*, *tearDown*, and
+ *optionflags* were added; this function now uses the same search technique as
+ :func:`testmod`.
+
+Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` out
+of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a
+subclass of :class:`unittest.TestCase`. :class:`DocTestCase` isn't documented
+here (it's an internal detail), but studying its code can answer questions about
+the exact details of :mod:`unittest` integration.
+
+Similarly, :func:`DocFileSuite` creates a :class:`unittest.TestSuite` out of
+:class:`doctest.DocFileCase` instances, and :class:`DocFileCase` is a subclass
+of :class:`DocTestCase`.
+
+So both ways of creating a :class:`unittest.TestSuite` run instances of
+:class:`DocTestCase`. This is important for a subtle reason: when you run
+:mod:`doctest` functions yourself, you can control the :mod:`doctest` options in
+use directly, by passing option flags to :mod:`doctest` functions. However, if
+you're writing a :mod:`unittest` framework, :mod:`unittest` ultimately controls
+when and how tests get run. The framework author typically wants to control
+:mod:`doctest` reporting options (perhaps, e.g., specified by command line
+options), but there's no way to pass options through :mod:`unittest` to
+:mod:`doctest` test runners.
+
+For this reason, :mod:`doctest` also supports a notion of :mod:`doctest`
+reporting flags specific to :mod:`unittest` support, via this function:
+
+
+.. function:: set_unittest_reportflags(flags)
+
+ Set the :mod:`doctest` reporting flags to use.
+
+ Argument *flags* or's together option flags. See section
+ :ref:`doctest-options`. Only "reporting flags" can be used.
+
+ This is a module-global setting, and affects all future doctests run by module
+ :mod:`unittest`: the :meth:`runTest` method of :class:`DocTestCase` looks at
+ the option flags specified for the test case when the :class:`DocTestCase`
+ instance was constructed. If no reporting flags were specified (which is the
+ typical and expected case), :mod:`doctest`'s :mod:`unittest` reporting flags are
+ or'ed into the option flags, and the option flags so augmented are passed to the
+ :class:`DocTestRunner` instance created to run the doctest. If any reporting
+ flags were specified when the :class:`DocTestCase` instance was constructed,
+ :mod:`doctest`'s :mod:`unittest` reporting flags are ignored.
+
+ The value of the :mod:`unittest` reporting flags in effect before the function
+ was called is returned by the function.
+
+ .. versionadded:: 2.4
+
+
+.. _doctest-advanced-api:
+
+Advanced API
+------------
+
+The basic API is a simple wrapper that's intended to make doctest easy to use.
+It is fairly flexible, and should meet most users' needs; however, if you
+require more fine-grained control over testing, or wish to extend doctest's
+capabilities, then you should use the advanced API.
+
+The advanced API revolves around two container classes, which are used to store
+the interactive examples extracted from doctest cases:
+
+* :class:`Example`: A single python statement, paired with its expected output.
+
+* :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted
+ from a single docstring or text file.
+
+Additional processing classes are defined to find, parse, and run, and check
+doctest examples:
+
+* :class:`DocTestFinder`: Finds all docstrings in a given module, and uses a
+ :class:`DocTestParser` to create a :class:`DocTest` from every docstring that
+ contains interactive examples.
+
+* :class:`DocTestParser`: Creates a :class:`DocTest` object from a string (such
+ as an object's docstring).
+
+* :class:`DocTestRunner`: Executes the examples in a :class:`DocTest`, and uses
+ an :class:`OutputChecker` to verify their output.
+
+* :class:`OutputChecker`: Compares the actual output from a doctest example with
+ the expected output, and decides whether they match.
+
+The relationships among these processing classes are summarized in the following
+diagram::
+
+ list of:
+ +------+ +---------+
+ |module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
+ +------+ | ^ +---------+ | ^ (printed)
+ | | | Example | | |
+ v | | ... | v |
+ DocTestParser | Example | OutputChecker
+ +---------+
+
+
+.. _doctest-doctest:
+
+DocTest Objects
+^^^^^^^^^^^^^^^
+
+
+.. class:: DocTest(examples, globs, name, filename, lineno, docstring)
+
+ A collection of doctest examples that should be run in a single namespace. The
+ constructor arguments are used to initialize the member variables of the same
+ names.
+
+ .. versionadded:: 2.4
+
+:class:`DocTest` defines the following member variables. They are initialized
+by the constructor, and should not be modified directly.
+
+
+.. attribute:: DocTest.examples
+
+ A list of :class:`Example` objects encoding the individual interactive Python
+ examples that should be run by this test.
+
+
+.. attribute:: DocTest.globs
+
+ The namespace (aka globals) that the examples should be run in. This is a
+ dictionary mapping names to values. Any changes to the namespace made by the
+ examples (such as binding new variables) will be reflected in :attr:`globs`
+ after the test is run.
+
+
+.. attribute:: DocTest.name
+
+ A string name identifying the :class:`DocTest`. Typically, this is the name of
+ the object or file that the test was extracted from.
+
+
+.. attribute:: DocTest.filename
+
+ The name of the file that this :class:`DocTest` was extracted from; or ``None``
+ if the filename is unknown, or if the :class:`DocTest` was not extracted from a
+ file.
+
+
+.. attribute:: DocTest.lineno
+
+ The line number within :attr:`filename` where this :class:`DocTest` begins, or
+ ``None`` if the line number is unavailable. This line number is zero-based with
+ respect to the beginning of the file.
+
+
+.. attribute:: DocTest.docstring
+
+ The string that the test was extracted from, or 'None' if the string is
+ unavailable, or if the test was not extracted from a string.
+
+
+.. _doctest-example:
+
+Example Objects
+^^^^^^^^^^^^^^^
+
+
+.. class:: Example(source, want[, exc_msg][, lineno][, indent][, options])
+
+ A single interactive example, consisting of a Python statement and its expected
+ output. The constructor arguments are used to initialize the member variables
+ of the same names.
+
+ .. versionadded:: 2.4
+
+:class:`Example` defines the following member variables. They are initialized
+by the constructor, and should not be modified directly.
+
+
+.. attribute:: Example.source
+
+ A string containing the example's source code. This source code consists of a
+ single Python statement, and always ends with a newline; the constructor adds a
+ newline when necessary.
+
+
+.. attribute:: Example.want
+
+ The expected output from running the example's source code (either from stdout,
+ or a traceback in case of exception). :attr:`want` ends with a newline unless
+ no output is expected, in which case it's an empty string. The constructor adds
+ a newline when necessary.
+
+
+.. attribute:: Example.exc_msg
+
+ The exception message generated by the example, if the example is expected to
+ generate an exception; or ``None`` if it is not expected to generate an
+ exception. This exception message is compared against the return value of
+ :func:`traceback.format_exception_only`. :attr:`exc_msg` ends with a newline
+ unless it's ``None``. The constructor adds a newline if needed.
+
+
+.. attribute:: Example.lineno
+
+ The line number within the string containing this example where the example
+ begins. This line number is zero-based with respect to the beginning of the
+ containing string.
+
+
+.. attribute:: Example.indent
+
+ The example's indentation in the containing string, i.e., the number of space
+ characters that precede the example's first prompt.
+
+
+.. attribute:: Example.options
+
+ A dictionary mapping from option flags to ``True`` or ``False``, which is used
+ to override default options for this example. Any option flags not contained in
+ this dictionary are left at their default value (as specified by the
+ :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
+
+
+.. _doctest-doctestfinder:
+
+DocTestFinder objects
+^^^^^^^^^^^^^^^^^^^^^
+
+
+.. class:: DocTestFinder([verbose][, parser][, recurse][, exclude_empty])
+
+ A processing class used to extract the :class:`DocTest`\ s that are relevant to
+ a given object, from its docstring and the docstrings of its contained objects.
+ :class:`DocTest`\ s can currently be extracted from the following object types:
+ modules, functions, classes, methods, staticmethods, classmethods, and
+ properties.
+
+ The optional argument *verbose* can be used to display the objects searched by
+ the finder. It defaults to ``False`` (no output).
+
+ The optional argument *parser* specifies the :class:`DocTestParser` object (or a
+ drop-in replacement) that is used to extract doctests from docstrings.
+
+ If the optional argument *recurse* is false, then :meth:`DocTestFinder.find`
+ will only examine the given object, and not any contained objects.
+
+ If the optional argument *exclude_empty* is false, then
+ :meth:`DocTestFinder.find` will include tests for objects with empty docstrings.
+
+ .. versionadded:: 2.4
+
+:class:`DocTestFinder` defines the following method:
+
+
+.. method:: DocTestFinder.find(obj[, name][, module][, globs][, extraglobs])
+
+ Return a list of the :class:`DocTest`\ s that are defined by *obj*'s docstring,
+ or by any of its contained objects' docstrings.
+
+ The optional argument *name* specifies the object's name; this name will be used
+ to construct names for the returned :class:`DocTest`\ s. If *name* is not
+ specified, then ``obj.__name__`` is used.
+
+ The optional parameter *module* is the module that contains the given object.
+ If the module is not specified or is None, then the test finder will attempt to
+ automatically determine the correct module. The object's module is used:
+
+ * As a default namespace, if *globs* is not specified.
+
+ * To prevent the DocTestFinder from extracting DocTests from objects that are
+ imported from other modules. (Contained objects with modules other than
+ *module* are ignored.)
+
+ * To find the name of the file containing the object.
+
+ * To help find the line number of the object within its file.
+
+ If *module* is ``False``, no attempt to find the module will be made. This is
+ obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
+ is ``None`` but cannot be found automatically, then all objects are considered
+ to belong to the (non-existent) module, so all contained objects will
+ (recursively) be searched for doctests.
+
+ The globals for each :class:`DocTest` is formed by combining *globs* and
+ *extraglobs* (bindings in *extraglobs* override bindings in *globs*). A new
+ shallow copy of the globals dictionary is created for each :class:`DocTest`. If
+ *globs* is not specified, then it defaults to the module's *__dict__*, if
+ specified, or ``{}`` otherwise. If *extraglobs* is not specified, then it
+ defaults to ``{}``.
+
+
+.. _doctest-doctestparser:
+
+DocTestParser objects
+^^^^^^^^^^^^^^^^^^^^^
+
+
+.. class:: DocTestParser()
+
+ A processing class used to extract interactive examples from a string, and use
+ them to create a :class:`DocTest` object.
+
+ .. versionadded:: 2.4
+
+:class:`DocTestParser` defines the following methods:
+
+
+.. method:: DocTestParser.get_doctest(string, globs, name, filename, lineno)
+
+ Extract all doctest examples from the given string, and collect them into a
+ :class:`DocTest` object.
+
+ *globs*, *name*, *filename*, and *lineno* are attributes for the new
+ :class:`DocTest` object. See the documentation for :class:`DocTest` for more
+ information.
+
+
+.. method:: DocTestParser.get_examples(string[, name])
+
+ Extract all doctest examples from the given string, and return them as a list of
+ :class:`Example` objects. Line numbers are 0-based. The optional argument
+ *name* is a name identifying this string, and is only used for error messages.
+
+
+.. method:: DocTestParser.parse(string[, name])
+
+ Divide the given string into examples and intervening text, and return them as a
+ list of alternating :class:`Example`\ s and strings. Line numbers for the
+ :class:`Example`\ s are 0-based. The optional argument *name* is a name
+ identifying this string, and is only used for error messages.
+
+
+.. _doctest-doctestrunner:
+
+DocTestRunner objects
+^^^^^^^^^^^^^^^^^^^^^
+
+
+.. class:: DocTestRunner([checker][, verbose][, optionflags])
+
+ A processing class used to execute and verify the interactive examples in a
+ :class:`DocTest`.
+
+ The comparison between expected outputs and actual outputs is done by an
+ :class:`OutputChecker`. This comparison may be customized with a number of
+ option flags; see section :ref:`doctest-options` for more information. If the
+ option flags are insufficient, then the comparison may also be customized by
+ passing a subclass of :class:`OutputChecker` to the constructor.
+
+ The test runner's display output can be controlled in two ways. First, an output
+ function can be passed to :meth:`TestRunner.run`; this function will be called
+ with strings that should be displayed. It defaults to ``sys.stdout.write``. If
+ capturing the output is not sufficient, then the display output can be also
+ customized by subclassing DocTestRunner, and overriding the methods
+ :meth:`report_start`, :meth:`report_success`,
+ :meth:`report_unexpected_exception`, and :meth:`report_failure`.
+
+ The optional keyword argument *checker* specifies the :class:`OutputChecker`
+ object (or drop-in replacement) that should be used to compare the expected
+ outputs to the actual outputs of doctest examples.
+
+ The optional keyword argument *verbose* controls the :class:`DocTestRunner`'s
+ verbosity. If *verbose* is ``True``, then information is printed about each
+ example, as it is run. If *verbose* is ``False``, then only failures are
+ printed. If *verbose* is unspecified, or ``None``, then verbose output is used
+ iff the command-line switch :option:`-v` is used.
+
+ The optional keyword argument *optionflags* can be used to control how the test
+ runner compares expected output to actual output, and how it displays failures.
+ For more information, see section :ref:`doctest-options`.
+
+ .. versionadded:: 2.4
+
+:class:`DocTestParser` defines the following methods:
+
+
+.. method:: DocTestRunner.report_start(out, test, example)
+
+ Report that the test runner is about to process the given example. This method
+ is provided to allow subclasses of :class:`DocTestRunner` to customize their
+ output; it should not be called directly.
+
+ *example* is the example about to be processed. *test* is the test containing
+ *example*. *out* is the output function that was passed to
+ :meth:`DocTestRunner.run`.
+
+
+.. method:: DocTestRunner.report_success(out, test, example, got)
+
+ Report that the given example ran successfully. This method is provided to
+ allow subclasses of :class:`DocTestRunner` to customize their output; it should
+ not be called directly.
+
+ *example* is the example about to be processed. *got* is the actual output from
+ the example. *test* is the test containing *example*. *out* is the output
+ function that was passed to :meth:`DocTestRunner.run`.
+
+
+.. method:: DocTestRunner.report_failure(out, test, example, got)
+
+ Report that the given example failed. This method is provided to allow
+ subclasses of :class:`DocTestRunner` to customize their output; it should not be
+ called directly.
+
+ *example* is the example about to be processed. *got* is the actual output from
+ the example. *test* is the test containing *example*. *out* is the output
+ function that was passed to :meth:`DocTestRunner.run`.
+
+
+.. method:: DocTestRunner.report_unexpected_exception(out, test, example, exc_info)
+
+ Report that the given example raised an unexpected exception. This method is
+ provided to allow subclasses of :class:`DocTestRunner` to customize their
+ output; it should not be called directly.
+
+ *example* is the example about to be processed. *exc_info* is a tuple containing
+ information about the unexpected exception (as returned by
+ :func:`sys.exc_info`). *test* is the test containing *example*. *out* is the
+ output function that was passed to :meth:`DocTestRunner.run`.
+
+
+.. method:: DocTestRunner.run(test[, compileflags][, out][, clear_globs])
+
+ Run the examples in *test* (a :class:`DocTest` object), and display the results
+ using the writer function *out*.
+
+ The examples are run in the namespace ``test.globs``. If *clear_globs* is true
+ (the default), then this namespace will be cleared after the test runs, to help
+ with garbage collection. If you would like to examine the namespace after the
+ test completes, then use *clear_globs=False*.
+
+ *compileflags* gives the set of flags that should be used by the Python compiler
+ when running the examples. If not specified, then it will default to the set of
+ future-import flags that apply to *globs*.
+
+ The output of each example is checked using the :class:`DocTestRunner`'s output
+ checker, and the results are formatted by the :meth:`DocTestRunner.report_\*`
+ methods.
+
+
+.. method:: DocTestRunner.summarize([verbose])
+
+ Print a summary of all the test cases that have been run by this DocTestRunner,
+ and return a tuple ``(failure_count, test_count)``.
+
+ The optional *verbose* argument controls how detailed the summary is. If the
+ verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is used.
+
+
+.. _doctest-outputchecker:
+
+OutputChecker objects
+^^^^^^^^^^^^^^^^^^^^^
+
+
+.. class:: OutputChecker()
+
+ A class used to check the whether the actual output from a doctest example
+ matches the expected output. :class:`OutputChecker` defines two methods:
+ :meth:`check_output`, which compares a given pair of outputs, and returns true
+ if they match; and :meth:`output_difference`, which returns a string describing
+ the differences between two outputs.
+
+ .. versionadded:: 2.4
+
+:class:`OutputChecker` defines the following methods:
+
+
+.. method:: OutputChecker.check_output(want, got, optionflags)
+
+ Return ``True`` iff the actual output from an example (*got*) matches the
+ expected output (*want*). These strings are always considered to match if they
+ are identical; but depending on what option flags the test runner is using,
+ several non-exact match types are also possible. See section
+ :ref:`doctest-options` for more information about option flags.
+
+
+.. method:: OutputChecker.output_difference(example, got, optionflags)
+
+ Return a string describing the differences between the expected output for a
+ given example (*example*) and the actual output (*got*). *optionflags* is the
+ set of option flags used to compare *want* and *got*.
+
+
+.. _doctest-debugging:
+
+Debugging
+---------
+
+Doctest provides several mechanisms for debugging doctest examples:
+
+* Several functions convert doctests to executable Python programs, which can be
+ run under the Python debugger, :mod:`pdb`.
+
+* The :class:`DebugRunner` class is a subclass of :class:`DocTestRunner` that
+ raises an exception for the first failing example, containing information about
+ that example. This information can be used to perform post-mortem debugging on
+ the example.
+
+* The :mod:`unittest` cases generated by :func:`DocTestSuite` support the
+ :meth:`debug` method defined by :class:`unittest.TestCase`.
+
+* You can add a call to :func:`pdb.set_trace` in a doctest example, and you'll
+ drop into the Python debugger when that line is executed. Then you can inspect
+ current values of variables, and so on. For example, suppose :file:`a.py`
+ contains just this module docstring::
+
+ """
+ >>> def f(x):
+ ... g(x*2)
+ >>> def g(x):
+ ... print x+3
+ ... import pdb; pdb.set_trace()
+ >>> f(3)
+ 9
+ """
+
+ Then an interactive Python session may look like this::
+
+ >>> import a, doctest
+ >>> doctest.testmod(a)
+ --Return--
+ > <doctest a[1]>(3)g()->None
+ -> import pdb; pdb.set_trace()
+ (Pdb) list
+ 1 def g(x):
+ 2 print x+3
+ 3 -> import pdb; pdb.set_trace()
+ [EOF]
+ (Pdb) print x
+ 6
+ (Pdb) step
+ --Return--
+ > <doctest a[0]>(2)f()->None
+ -> g(x*2)
+ (Pdb) list
+ 1 def f(x):
+ 2 -> g(x*2)
+ [EOF]
+ (Pdb) print x
+ 3
+ (Pdb) step
+ --Return--
+ > <doctest a[2]>(1)?()->None
+ -> f(3)
+ (Pdb) cont
+ (0, 3)
+ >>>
+
+ .. versionchanged:: 2.4
+ The ability to use :func:`pdb.set_trace` usefully inside doctests was added.
+
+Functions that convert doctests to Python code, and possibly run the synthesized
+code under the debugger:
+
+
+.. function:: script_from_examples(s)
+
+ Convert text with examples to a script.
+
+ Argument *s* is a string containing doctest examples. The string is converted
+ to a Python script, where doctest examples in *s* are converted to regular code,
+ and everything else is converted to Python comments. The generated script is
+ returned as a string. For example, ::
+
+ import doctest
+ print doctest.script_from_examples(r"""
+ Set x and y to 1 and 2.
+ >>> x, y = 1, 2
+
+ Print their sum:
+ >>> print x+y
+ 3
+ """)
+
+ displays::
+
+ # Set x and y to 1 and 2.
+ x, y = 1, 2
+ #
+ # Print their sum:
+ print x+y
+ # Expected:
+ ## 3
+
+ This function is used internally by other functions (see below), but can also be
+ useful when you want to transform an interactive Python session into a Python
+ script.
+
+ .. versionadded:: 2.4
+
+
+.. function:: testsource(module, name)
+
+ Convert the doctest for an object to a script.
+
+ Argument *module* is a module object, or dotted name of a module, containing the
+ object whose doctests are of interest. Argument *name* is the name (within the
+ module) of the object with the doctests of interest. The result is a string,
+ containing the object's docstring converted to a Python script, as described for
+ :func:`script_from_examples` above. For example, if module :file:`a.py`
+ contains a top-level function :func:`f`, then ::
+
+ import a, doctest
+ print doctest.testsource(a, "a.f")
+
+ prints a script version of function :func:`f`'s docstring, with doctests
+ converted to code, and the rest placed in comments.
+
+ .. versionadded:: 2.3
+
+
+.. function:: debug(module, name[, pm])
+
+ Debug the doctests for an object.
+
+ The *module* and *name* arguments are the same as for function
+ :func:`testsource` above. The synthesized Python script for the named object's
+ docstring is written to a temporary file, and then that file is run under the
+ control of the Python debugger, :mod:`pdb`.
+
+ A shallow copy of ``module.__dict__`` is used for both local and global
+ execution context.
+
+ Optional argument *pm* controls whether post-mortem debugging is used. If *pm*
+ has a true value, the script file is run directly, and the debugger gets
+ involved only if the script terminates via raising an unhandled exception. If
+ it does, then post-mortem debugging is invoked, via :func:`pdb.post_mortem`,
+ passing the traceback object from the unhandled exception. If *pm* is not
+ specified, or is false, the script is run under the debugger from the start, via
+ passing an appropriate :func:`execfile` call to :func:`pdb.run`.
+
+ .. versionadded:: 2.3
+
+ .. versionchanged:: 2.4
+ The *pm* argument was added.
+
+
+.. function:: debug_src(src[, pm][, globs])
+
+ Debug the doctests in a string.
+
+ This is like function :func:`debug` above, except that a string containing
+ doctest examples is specified directly, via the *src* argument.
+
+ Optional argument *pm* has the same meaning as in function :func:`debug` above.
+
+ Optional argument *globs* gives a dictionary to use as both local and global
+ execution context. If not specified, or ``None``, an empty dictionary is used.
+ If specified, a shallow copy of the dictionary is used.
+
+ .. versionadded:: 2.4
+
+The :class:`DebugRunner` class, and the special exceptions it may raise, are of
+most interest to testing framework authors, and will only be sketched here. See
+the source code, and especially :class:`DebugRunner`'s docstring (which is a
+doctest!) for more details:
+
+
+.. class:: DebugRunner([checker][, verbose][, optionflags])
+
+ A subclass of :class:`DocTestRunner` that raises an exception as soon as a
+ failure is encountered. If an unexpected exception occurs, an
+ :exc:`UnexpectedException` exception is raised, containing the test, the
+ example, and the original exception. If the output doesn't match, then a
+ :exc:`DocTestFailure` exception is raised, containing the test, the example, and
+ the actual output.
+
+ For information about the constructor parameters and methods, see the
+ documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-api`.
+
+There are two exceptions that may be raised by :class:`DebugRunner` instances:
+
+
+.. exception:: DocTestFailure(test, example, got)
+
+ An exception thrown by :class:`DocTestRunner` to signal that a doctest example's
+ actual output did not match its expected output. The constructor arguments are
+ used to initialize the member variables of the same names.
+
+:exc:`DocTestFailure` defines the following member variables:
+
+
+.. attribute:: DocTestFailure.test
+
+ The :class:`DocTest` object that was being run when the example failed.
+
+
+.. attribute:: DocTestFailure.example
+
+ The :class:`Example` that failed.
+
+
+.. attribute:: DocTestFailure.got
+
+ The example's actual output.
+
+
+.. exception:: UnexpectedException(test, example, exc_info)
+
+ An exception thrown by :class:`DocTestRunner` to signal that a doctest example
+ raised an unexpected exception. The constructor arguments are used to
+ initialize the member variables of the same names.
+
+:exc:`UnexpectedException` defines the following member variables:
+
+
+.. attribute:: UnexpectedException.test
+
+ The :class:`DocTest` object that was being run when the example failed.
+
+
+.. attribute:: UnexpectedException.example
+
+ The :class:`Example` that failed.
+
+
+.. attribute:: UnexpectedException.exc_info
+
+ A tuple containing information about the unexpected exception, as returned by
+ :func:`sys.exc_info`.
+
+
+.. _doctest-soapbox:
+
+Soapbox
+-------
+
+As mentioned in the introduction, :mod:`doctest` has grown to have three primary
+uses:
+
+#. Checking examples in docstrings.
+
+#. Regression testing.
+
+#. Executable documentation / literate testing.
+
+These uses have different requirements, and it is important to distinguish them.
+In particular, filling your docstrings with obscure test cases makes for bad
+documentation.
+
+When writing a docstring, choose docstring examples with care. There's an art to
+this that needs to be learned---it may not be natural at first. Examples should
+add genuine value to the documentation. A good example can often be worth many
+words. If done with care, the examples will be invaluable for your users, and
+will pay back the time it takes to collect them many times over as the years go
+by and things change. I'm still amazed at how often one of my :mod:`doctest`
+examples stops working after a "harmless" change.
+
+Doctest also makes an excellent tool for regression testing, especially if you
+don't skimp on explanatory text. By interleaving prose and examples, it becomes
+much easier to keep track of what's actually being tested, and why. When a test
+fails, good prose can make it much easier to figure out what the problem is, and
+how it should be fixed. It's true that you could write extensive comments in
+code-based testing, but few programmers do. Many have found that using doctest
+approaches instead leads to much clearer tests. Perhaps this is simply because
+doctest makes writing prose a little easier than writing code, while writing
+comments in code is a little harder. I think it goes deeper than just that:
+the natural attitude when writing a doctest-based test is that you want to
+explain the fine points of your software, and illustrate them with examples.
+This in turn naturally leads to test files that start with the simplest
+features, and logically progress to complications and edge cases. A coherent
+narrative is the result, instead of a collection of isolated functions that test
+isolated bits of functionality seemingly at random. It's a different attitude,
+and produces different results, blurring the distinction between testing and
+explaining.
+
+Regression testing is best confined to dedicated objects or files. There are
+several options for organizing tests:
+
+* Write text files containing test cases as interactive examples, and test the
+ files using :func:`testfile` or :func:`DocFileSuite`. This is recommended,
+ although is easiest to do for new projects, designed from the start to use
+ doctest.
+
+* Define functions named ``_regrtest_topic`` that consist of single docstrings,
+ containing test cases for the named topics. These functions can be included in
+ the same file as the module, or separated out into a separate test file.
+
+* Define a ``__test__`` dictionary mapping from regression test topics to
+ docstrings containing test cases.
+
+.. rubric:: Footnotes
+
+.. [#] Examples containing both expected output and an exception are not supported.
+ Trying to guess where one ends and the other begins is too error-prone, and that
+ also makes for a confusing test.
+
--- /dev/null
+
+:mod:`DocXMLRPCServer` --- Self-documenting XML-RPC server
+==========================================================
+
+.. module:: DocXMLRPCServer
+ :synopsis: Self-documenting XML-RPC server implementation.
+.. moduleauthor:: Brian Quinlan <brianq@activestate.com>
+.. sectionauthor:: Brian Quinlan <brianq@activestate.com>
+
+
+.. versionadded:: 2.3
+
+The :mod:`DocXMLRPCServer` module extends the classes found in
+:mod:`SimpleXMLRPCServer` to serve HTML documentation in response to HTTP GET
+requests. Servers can either be free standing, using :class:`DocXMLRPCServer`,
+or embedded in a CGI environment, using :class:`DocCGIXMLRPCRequestHandler`.
+
+
+.. class:: DocXMLRPCServer(addr[, requestHandler[, logRequests[, allow_none[, encoding[, bind_and_activate]]]]])
+
+ Create a new server instance. All parameters have the same meaning as for
+ :class:`SimpleXMLRPCServer.SimpleXMLRPCServer`; *requestHandler* defaults to
+ :class:`DocXMLRPCRequestHandler`.
+
+
+.. class:: DocCGIXMLRPCRequestHandler()
+
+ Create a new instance to handle XML-RPC requests in a CGI environment.
+
+
+.. class:: DocXMLRPCRequestHandler()
+
+ Create a new request handler instance. This request handler supports XML-RPC
+ POST requests, documentation GET requests, and modifies logging so that the
+ *logRequests* parameter to the :class:`DocXMLRPCServer` constructor parameter is
+ honored.
+
+
+.. _doc-xmlrpc-servers:
+
+DocXMLRPCServer Objects
+-----------------------
+
+The :class:`DocXMLRPCServer` class is derived from
+:class:`SimpleXMLRPCServer.SimpleXMLRPCServer` and provides a means of creating
+self-documenting, stand alone XML-RPC servers. HTTP POST requests are handled as
+XML-RPC method calls. HTTP GET requests are handled by generating pydoc-style
+HTML documentation. This allows a server to provide its own web-based
+documentation.
+
+
+.. method:: DocXMLRPCServer.set_server_title(server_title)
+
+ Set the title used in the generated HTML documentation. This title will be used
+ inside the HTML "title" element.
+
+
+.. method:: DocXMLRPCServer.set_server_name(server_name)
+
+ Set the name used in the generated HTML documentation. This name will appear at
+ the top of the generated documentation inside a "h1" element.
+
+
+.. method:: DocXMLRPCServer.set_server_documentation(server_documentation)
+
+ Set the description used in the generated HTML documentation. This description
+ will appear as a paragraph, below the server name, in the documentation.
+
+
+DocCGIXMLRPCRequestHandler
+--------------------------
+
+The :class:`DocCGIXMLRPCRequestHandler` class is derived from
+:class:`SimpleXMLRPCServer.CGIXMLRPCRequestHandler` and provides a means of
+creating self-documenting, XML-RPC CGI scripts. HTTP POST requests are handled
+as XML-RPC method calls. HTTP GET requests are handled by generating pydoc-style
+HTML documentation. This allows a server to provide its own web-based
+documentation.
+
+
+.. method:: DocCGIXMLRPCRequestHandler.set_server_title(server_title)
+
+ Set the title used in the generated HTML documentation. This title will be used
+ inside the HTML "title" element.
+
+
+.. method:: DocCGIXMLRPCRequestHandler.set_server_name(server_name)
+
+ Set the name used in the generated HTML documentation. This name will appear at
+ the top of the generated documentation inside a "h1" element.
+
+
+.. method:: DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)
+
+ Set the description used in the generated HTML documentation. This description
+ will appear as a paragraph, below the server name, in the documentation.
+
--- /dev/null
+
+:mod:`dumbdbm` --- Portable DBM implementation
+==============================================
+
+.. module:: dumbdbm
+ :synopsis: Portable implementation of the simple DBM interface.
+
+
+.. index:: single: databases
+
+.. note::
+
+ The :mod:`dumbdbm` module is intended as a last resort fallback for the
+ :mod:`anydbm` module when no more robust module is available. The :mod:`dumbdbm`
+ module is not written for speed and is not nearly as heavily used as the other
+ database modules.
+
+The :mod:`dumbdbm` module provides a persistent dictionary-like interface which
+is written entirely in Python. Unlike other modules such as :mod:`gdbm` and
+:mod:`bsddb`, no external library is required. As with other persistent
+mappings, the keys and values must always be strings.
+
+The module defines the following:
+
+
+.. exception:: error
+
+ Raised on dumbdbm-specific errors, such as I/O errors. :exc:`KeyError` is
+ raised for general mapping errors like specifying an incorrect key.
+
+
+.. function:: open(filename[, flag[, mode]])
+
+ Open a dumbdbm database and return a dumbdbm object. The *filename* argument is
+ the basename of the database file (without any specific extensions). When a
+ dumbdbm database is created, files with :file:`.dat` and :file:`.dir` extensions
+ are created.
+
+ The optional *flag* argument is currently ignored; the database is always opened
+ for update, and will be created if it does not exist.
+
+ The optional *mode* argument is the Unix mode of the file, used only when the
+ database has to be created. It defaults to octal ``0666`` (and will be modified
+ by the prevailing umask).
+
+ .. versionchanged:: 2.2
+ The *mode* argument was ignored in earlier versions.
+
+
+.. seealso::
+
+ Module :mod:`anydbm`
+ Generic interface to ``dbm``\ -style databases.
+
+ Module :mod:`dbm`
+ Similar interface to the DBM/NDBM library.
+
+ Module :mod:`gdbm`
+ Similar interface to the GNU GDBM library.
+
+ Module :mod:`shelve`
+ Persistence module which stores non-string data.
+
+ Module :mod:`whichdb`
+ Utility module used to determine the type of an existing database.
+
+
+.. _dumbdbm-objects:
+
+Dumbdbm Objects
+---------------
+
+In addition to the methods provided by the :class:`UserDict.DictMixin` class,
+:class:`dumbdbm` objects provide the following methods.
+
+
+.. method:: dumbdbm.sync()
+
+ Synchronize the on-disk directory and data files. This method is called by the
+ :meth:`sync` method of :class:`Shelve` objects.
+
--- /dev/null
+
+:mod:`dummy_thread` --- Drop-in replacement for the :mod:`thread` module
+========================================================================
+
+.. module:: dummy_thread
+ :synopsis: Drop-in replacement for the thread module.
+
+
+This module provides a duplicate interface to the :mod:`thread` module. It is
+meant to be imported when the :mod:`thread` module is not provided on a
+platform.
+
+Suggested usage is::
+
+ try:
+ import thread as _thread
+ except ImportError:
+ import dummy_thread as _thread
+
+Be careful to not use this module where deadlock might occur from a thread
+being created that blocks waiting for another thread to be created. This often
+occurs with blocking I/O.
+
--- /dev/null
+
+:mod:`dummy_threading` --- Drop-in replacement for the :mod:`threading` module
+==============================================================================
+
+.. module:: dummy_threading
+ :synopsis: Drop-in replacement for the threading module.
+
+
+This module provides a duplicate interface to the :mod:`threading` module. It
+is meant to be imported when the :mod:`thread` module is not provided on a
+platform.
+
+Suggested usage is::
+
+ try:
+ import threading as _threading
+ except ImportError:
+ import dummy_threading as _threading
+
+Be careful to not use this module where deadlock might occur from a thread
+being created that blocks waiting for another thread to be created. This often
+occurs with blocking I/O.
+
--- /dev/null
+
+:mod:`EasyDialogs` --- Basic Macintosh dialogs
+==============================================
+
+.. module:: EasyDialogs
+ :platform: Mac
+ :synopsis: Basic Macintosh dialogs.
+
+
+The :mod:`EasyDialogs` module contains some simple dialogs for the Macintosh.
+All routines take an optional resource ID parameter *id* with which one can
+override the :const:`DLOG` resource used for the dialog, provided that the
+dialog items correspond (both type and item number) to those in the default
+:const:`DLOG` resource. See source code for details.
+
+The :mod:`EasyDialogs` module defines the following functions:
+
+
+.. function:: Message(str[, id[, ok]])
+
+ Displays a modal dialog with the message text *str*, which should be at most 255
+ characters long. The button text defaults to "OK", but is set to the string
+ argument *ok* if the latter is supplied. Control is returned when the user
+ clicks the "OK" button.
+
+
+.. function:: AskString(prompt[, default[, id[, ok[, cancel]]]])
+
+ Asks the user to input a string value via a modal dialog. *prompt* is the prompt
+ message, and the optional *default* supplies the initial value for the string
+ (otherwise ``""`` is used). The text of the "OK" and "Cancel" buttons can be
+ changed with the *ok* and *cancel* arguments. All strings can be at most 255
+ bytes long. :func:`AskString` returns the string entered or :const:`None` in
+ case the user cancelled.
+
+
+.. function:: AskPassword(prompt[, default[, id[, ok[, cancel]]]])
+
+ Asks the user to input a string value via a modal dialog. Like
+ :func:`AskString`, but with the text shown as bullets. The arguments have the
+ same meaning as for :func:`AskString`.
+
+
+.. function:: AskYesNoCancel(question[, default[, yes[, no[, cancel[, id]]]]])
+
+ Presents a dialog with prompt *question* and three buttons labelled "Yes", "No",
+ and "Cancel". Returns ``1`` for "Yes", ``0`` for "No" and ``-1`` for "Cancel".
+ The value of *default* (or ``0`` if *default* is not supplied) is returned when
+ the :kbd:`RETURN` key is pressed. The text of the buttons can be changed with
+ the *yes*, *no*, and *cancel* arguments; to prevent a button from appearing,
+ supply ``""`` for the corresponding argument.
+
+
+.. function:: ProgressBar([title[, maxval[, label[, id]]]])
+
+ Displays a modeless progress-bar dialog. This is the constructor for the
+ :class:`ProgressBar` class described below. *title* is the text string displayed
+ (default "Working..."), *maxval* is the value at which progress is complete
+ (default ``0``, indicating that an indeterminate amount of work remains to be
+ done), and *label* is the text that is displayed above the progress bar itself.
+
+
+.. function:: GetArgv([optionlist[ commandlist[, addoldfile[, addnewfile[, addfolder[, id]]]]]])
+
+ Displays a dialog which aids the user in constructing a command-line argument
+ list. Returns the list in ``sys.argv`` format, suitable for passing as an
+ argument to :func:`getopt.getopt`. *addoldfile*, *addnewfile*, and *addfolder*
+ are boolean arguments. When nonzero, they enable the user to insert into the
+ command line paths to an existing file, a (possibly) not-yet-existent file, and
+ a folder, respectively. (Note: Option arguments must appear in the command line
+ before file and folder arguments in order to be recognized by
+ :func:`getopt.getopt`.) Arguments containing spaces can be specified by
+ enclosing them within single or double quotes. A :exc:`SystemExit` exception is
+ raised if the user presses the "Cancel" button.
+
+ *optionlist* is a list that determines a popup menu from which the allowed
+ options are selected. Its items can take one of two forms: *optstr* or
+ ``(optstr, descr)``. When present, *descr* is a short descriptive string that
+ is displayed in the dialog while this option is selected in the popup menu. The
+ correspondence between *optstr*\s and command-line arguments is:
+
+ +----------------------+------------------------------------------+
+ | *optstr* format | Command-line format |
+ +======================+==========================================+
+ | ``x`` | :option:`-x` (short option) |
+ +----------------------+------------------------------------------+
+ | ``x:`` or ``x=`` | :option:`-x` (short option with value) |
+ +----------------------+------------------------------------------+
+ | ``xyz`` | :option:`--xyz` (long option) |
+ +----------------------+------------------------------------------+
+ | ``xyz:`` or ``xyz=`` | :option:`--xyz` (long option with value) |
+ +----------------------+------------------------------------------+
+
+ *commandlist* is a list of items of the form *cmdstr* or ``(cmdstr, descr)``,
+ where *descr* is as above. The *cmdstr*s will appear in a popup menu. When
+ chosen, the text of *cmdstr* will be appended to the command line as is, except
+ that a trailing ``':'`` or ``'='`` (if present) will be trimmed off.
+
+ .. versionadded:: 2.0
+
+
+.. function:: AskFileForOpen( [message] [, typeList] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, previewProc] [, filterProc] [, wanted] )
+
+ Post a dialog asking the user for a file to open, and return the file selected
+ or :const:`None` if the user cancelled. *message* is a text message to display,
+ *typeList* is a list of 4-char filetypes allowable, *defaultLocation* is the
+ pathname, :class:`FSSpec` or :class:`FSRef` of the folder to show initially,
+ *location* is the ``(x, y)`` position on the screen where the dialog is shown,
+ *actionButtonLabel* is a string to show instead of "Open" in the OK button,
+ *cancelButtonLabel* is a string to show instead of "Cancel" in the cancel
+ button, *wanted* is the type of value wanted as a return: :class:`str`,
+ :class:`unicode`, :class:`FSSpec`, :class:`FSRef` and subtypes thereof are
+ acceptable.
+
+ .. index:: single: Navigation Services
+
+ For a description of the other arguments please see the Apple Navigation
+ Services documentation and the :mod:`EasyDialogs` source code.
+
+
+.. function:: AskFileForSave( [message] [, savedFileName] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, fileType] [, fileCreator] [, eventProc] [, wanted] )
+
+ Post a dialog asking the user for a file to save to, and return the file
+ selected or :const:`None` if the user cancelled. *savedFileName* is the default
+ for the file name to save to (the return value). See :func:`AskFileForOpen` for
+ a description of the other arguments.
+
+
+.. function:: AskFolder( [message] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, filterProc] [, wanted] )
+
+ Post a dialog asking the user to select a folder, and return the folder selected
+ or :const:`None` if the user cancelled. See :func:`AskFileForOpen` for a
+ description of the arguments.
+
+
+.. seealso::
+
+ `Navigation Services Reference <http://developer.apple.com/documentation/Carbon/Reference/Navigation_Services_Ref/>`_
+ Programmer's reference documentation for the Navigation Services, a part of the
+ Carbon framework.
+
+
+.. _progressbar-objects:
+
+ProgressBar Objects
+-------------------
+
+:class:`ProgressBar` objects provide support for modeless progress-bar dialogs.
+Both determinate (thermometer style) and indeterminate (barber-pole style)
+progress bars are supported. The bar will be determinate if its maximum value
+is greater than zero; otherwise it will be indeterminate.
+
+.. versionchanged:: 2.2
+ Support for indeterminate-style progress bars was added.
+
+The dialog is displayed immediately after creation. If the dialog's "Cancel"
+button is pressed, or if :kbd:`Cmd-.` or :kbd:`ESC` is typed, the dialog window
+is hidden and :exc:`KeyboardInterrupt` is raised (but note that this response
+does not occur until the progress bar is next updated, typically via a call to
+:meth:`inc` or :meth:`set`). Otherwise, the bar remains visible until the
+:class:`ProgressBar` object is discarded.
+
+:class:`ProgressBar` objects possess the following attributes and methods:
+
+
+.. attribute:: ProgressBar.curval
+
+ The current value (of type integer or long integer) of the progress bar. The
+ normal access methods coerce :attr:`curval` between ``0`` and :attr:`maxval`.
+ This attribute should not be altered directly.
+
+
+.. attribute:: ProgressBar.maxval
+
+ The maximum value (of type integer or long integer) of the progress bar; the
+ progress bar (thermometer style) is full when :attr:`curval` equals
+ :attr:`maxval`. If :attr:`maxval` is ``0``, the bar will be indeterminate
+ (barber-pole). This attribute should not be altered directly.
+
+
+.. method:: ProgressBar.title([newstr])
+
+ Sets the text in the title bar of the progress dialog to *newstr*.
+
+
+.. method:: ProgressBar.label([newstr])
+
+ Sets the text in the progress box of the progress dialog to *newstr*.
+
+
+.. method:: ProgressBar.set(value[, max])
+
+ Sets the progress bar's :attr:`curval` to *value*, and also :attr:`maxval` to
+ *max* if the latter is provided. *value* is first coerced between 0 and
+ :attr:`maxval`. The thermometer bar is updated to reflect the changes,
+ including a change from indeterminate to determinate or vice versa.
+
+
+.. method:: ProgressBar.inc([n])
+
+ Increments the progress bar's :attr:`curval` by *n*, or by ``1`` if *n* is not
+ provided. (Note that *n* may be negative, in which case the effect is a
+ decrement.) The progress bar is updated to reflect the change. If the bar is
+ indeterminate, this causes one "spin" of the barber pole. The resulting
+ :attr:`curval` is coerced between 0 and :attr:`maxval` if incrementing causes it
+ to fall outside this range.
+
--- /dev/null
+:mod:`email`: Examples
+----------------------
+
+Here are a few examples of how to use the :mod:`email` package to read, write,
+and send simple email messages, as well as more complex MIME messages.
+
+First, let's see how to create and send a simple text message:
+
+.. literalinclude:: ../includes/email-simple.py
+
+
+Here's an example of how to send a MIME message containing a bunch of family
+pictures that may be residing in a directory:
+
+.. literalinclude:: ../includes/email-mime.py
+
+
+Here's an example of how to send the entire contents of a directory as an email
+message: [1]_
+
+.. literalinclude:: ../includes/email-dir.py
+
+
+And finally, here's an example of how to unpack a MIME message like the one
+above, into a directory of files:
+
+.. literalinclude:: ../includes/email-unpack.py
+
+
+.. rubric:: Footnotes
+
+.. [1] Thanks to Matthew Dixon Cowles for the original inspiration and examples.
+
--- /dev/null
+:mod:`email`: Representing character sets
+-----------------------------------------
+
+.. module:: email.charset
+ :synopsis: Character Sets
+
+
+This module provides a class :class:`Charset` for representing character sets
+and character set conversions in email messages, as well as a character set
+registry and several convenience methods for manipulating this registry.
+Instances of :class:`Charset` are used in several other modules within the
+:mod:`email` package.
+
+Import this class from the :mod:`email.charset` module.
+
+.. versionadded:: 2.2.2
+
+
+.. class:: Charset([input_charset])
+
+ Map character sets to their email properties.
+
+ This class provides information about the requirements imposed on email for a
+ specific character set. It also provides convenience routines for converting
+ between character sets, given the availability of the applicable codecs. Given
+ a character set, it will do its best to provide information on how to use that
+ character set in an email message in an RFC-compliant way.
+
+ Certain character sets must be encoded with quoted-printable or base64 when used
+ in email headers or bodies. Certain character sets must be converted outright,
+ and are not allowed in email.
+
+ Optional *input_charset* is as described below; it is always coerced to lower
+ case. After being alias normalized it is also used as a lookup into the
+ registry of character sets to find out the header encoding, body encoding, and
+ output conversion codec to be used for the character set. For example, if
+ *input_charset* is ``iso-8859-1``, then headers and bodies will be encoded using
+ quoted-printable and no output conversion codec is necessary. If
+ *input_charset* is ``euc-jp``, then headers will be encoded with base64, bodies
+ will not be encoded, but output text will be converted from the ``euc-jp``
+ character set to the ``iso-2022-jp`` character set.
+
+:class:`Charset` instances have the following data attributes:
+
+
+.. data:: input_charset
+
+ The initial character set specified. Common aliases are converted to their
+ *official* email names (e.g. ``latin_1`` is converted to ``iso-8859-1``).
+ Defaults to 7-bit ``us-ascii``.
+
+
+.. data:: header_encoding
+
+ If the character set must be encoded before it can be used in an email header,
+ this attribute will be set to ``Charset.QP`` (for quoted-printable),
+ ``Charset.BASE64`` (for base64 encoding), or ``Charset.SHORTEST`` for the
+ shortest of QP or BASE64 encoding. Otherwise, it will be ``None``.
+
+
+.. data:: body_encoding
+
+ Same as *header_encoding*, but describes the encoding for the mail message's
+ body, which indeed may be different than the header encoding.
+ ``Charset.SHORTEST`` is not allowed for *body_encoding*.
+
+
+.. data:: output_charset
+
+ Some character sets must be converted before they can be used in email headers
+ or bodies. If the *input_charset* is one of them, this attribute will contain
+ the name of the character set output will be converted to. Otherwise, it will
+ be ``None``.
+
+
+.. data:: input_codec
+
+ The name of the Python codec used to convert the *input_charset* to Unicode. If
+ no conversion codec is necessary, this attribute will be ``None``.
+
+
+.. data:: output_codec
+
+ The name of the Python codec used to convert Unicode to the *output_charset*.
+ If no conversion codec is necessary, this attribute will have the same value as
+ the *input_codec*.
+
+:class:`Charset` instances also have the following methods:
+
+
+.. method:: Charset.get_body_encoding()
+
+ Return the content transfer encoding used for body encoding.
+
+ This is either the string ``quoted-printable`` or ``base64`` depending on the
+ encoding used, or it is a function, in which case you should call the function
+ with a single argument, the Message object being encoded. The function should
+ then set the :mailheader:`Content-Transfer-Encoding` header itself to whatever
+ is appropriate.
+
+ Returns the string ``quoted-printable`` if *body_encoding* is ``QP``, returns
+ the string ``base64`` if *body_encoding* is ``BASE64``, and returns the string
+ ``7bit`` otherwise.
+
+
+.. method:: Charset.convert(s)
+
+ Convert the string *s* from the *input_codec* to the *output_codec*.
+
+
+.. method:: Charset.to_splittable(s)
+
+ Convert a possibly multibyte string to a safely splittable format. *s* is the
+ string to split.
+
+ Uses the *input_codec* to try and convert the string to Unicode, so it can be
+ safely split on character boundaries (even for multibyte characters).
+
+ Returns the string as-is if it isn't known how to convert *s* to Unicode with
+ the *input_charset*.
+
+ Characters that could not be converted to Unicode will be replaced with the
+ Unicode replacement character ``'U+FFFD'``.
+
+
+.. method:: Charset.from_splittable(ustr[, to_output])
+
+ Convert a splittable string back into an encoded string. *ustr* is a Unicode
+ string to "unsplit".
+
+ This method uses the proper codec to try and convert the string from Unicode
+ back into an encoded format. Return the string as-is if it is not Unicode, or
+ if it could not be converted from Unicode.
+
+ Characters that could not be converted from Unicode will be replaced with an
+ appropriate character (usually ``'?'``).
+
+ If *to_output* is ``True`` (the default), uses *output_codec* to convert to an
+ encoded format. If *to_output* is ``False``, it uses *input_codec*.
+
+
+.. method:: Charset.get_output_charset()
+
+ Return the output character set.
+
+ This is the *output_charset* attribute if that is not ``None``, otherwise it is
+ *input_charset*.
+
+
+.. method:: Charset.encoded_header_len()
+
+ Return the length of the encoded header string, properly calculating for
+ quoted-printable or base64 encoding.
+
+
+.. method:: Charset.header_encode(s[, convert])
+
+ Header-encode the string *s*.
+
+ If *convert* is ``True``, the string will be converted from the input charset to
+ the output charset automatically. This is not useful for multibyte character
+ sets, which have line length issues (multibyte characters must be split on a
+ character, not a byte boundary); use the higher-level :class:`Header` class to
+ deal with these issues (see :mod:`email.header`). *convert* defaults to
+ ``False``.
+
+ The type of encoding (base64 or quoted-printable) will be based on the
+ *header_encoding* attribute.
+
+
+.. method:: Charset.body_encode(s[, convert])
+
+ Body-encode the string *s*.
+
+ If *convert* is ``True`` (the default), the string will be converted from the
+ input charset to output charset automatically. Unlike :meth:`header_encode`,
+ there are no issues with byte boundaries and multibyte charsets in email bodies,
+ so this is usually pretty safe.
+
+ The type of encoding (base64 or quoted-printable) will be based on the
+ *body_encoding* attribute.
+
+The :class:`Charset` class also provides a number of methods to support standard
+operations and built-in functions.
+
+
+.. method:: Charset.__str__()
+
+ Returns *input_charset* as a string coerced to lower case. :meth:`__repr__` is
+ an alias for :meth:`__str__`.
+
+
+.. method:: Charset.__eq__(other)
+
+ This method allows you to compare two :class:`Charset` instances for equality.
+
+
+.. method:: Header.__ne__(other)
+
+ This method allows you to compare two :class:`Charset` instances for inequality.
+
+The :mod:`email.charset` module also provides the following functions for adding
+new entries to the global character set, alias, and codec registries:
+
+
+.. function:: add_charset(charset[, header_enc[, body_enc[, output_charset]]])
+
+ Add character properties to the global registry.
+
+ *charset* is the input character set, and must be the canonical name of a
+ character set.
+
+ Optional *header_enc* and *body_enc* is either ``Charset.QP`` for
+ quoted-printable, ``Charset.BASE64`` for base64 encoding,
+ ``Charset.SHORTEST`` for the shortest of quoted-printable or base64 encoding,
+ or ``None`` for no encoding. ``SHORTEST`` is only valid for
+ *header_enc*. The default is ``None`` for no encoding.
+
+ Optional *output_charset* is the character set that the output should be in.
+ Conversions will proceed from input charset, to Unicode, to the output charset
+ when the method :meth:`Charset.convert` is called. The default is to output in
+ the same character set as the input.
+
+ Both *input_charset* and *output_charset* must have Unicode codec entries in the
+ module's character set-to-codec mapping; use :func:`add_codec` to add codecs the
+ module does not know about. See the :mod:`codecs` module's documentation for
+ more information.
+
+ The global character set registry is kept in the module global dictionary
+ ``CHARSETS``.
+
+
+.. function:: add_alias(alias, canonical)
+
+ Add a character set alias. *alias* is the alias name, e.g. ``latin-1``.
+ *canonical* is the character set's canonical name, e.g. ``iso-8859-1``.
+
+ The global charset alias registry is kept in the module global dictionary
+ ``ALIASES``.
+
+
+.. function:: add_codec(charset, codecname)
+
+ Add a codec that map characters in the given character set to and from Unicode.
+
+ *charset* is the canonical name of a character set. *codecname* is the name of a
+ Python codec, as appropriate for the second argument to the :func:`unicode`
+ built-in, or to the :meth:`encode` method of a Unicode string.
+
--- /dev/null
+:mod:`email`: Encoders
+----------------------
+
+.. module:: email.encoders
+ :synopsis: Encoders for email message payloads.
+
+
+When creating :class:`Message` objects from scratch, you often need to encode
+the payloads for transport through compliant mail servers. This is especially
+true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages containing
+binary data.
+
+The :mod:`email` package provides some convenient encodings in its
+:mod:`encoders` module. These encoders are actually used by the
+:class:`MIMEAudio` and :class:`MIMEImage` class constructors to provide default
+encodings. All encoder functions take exactly one argument, the message object
+to encode. They usually extract the payload, encode it, and reset the payload
+to this newly encoded value. They should also set the
+:mailheader:`Content-Transfer-Encoding` header as appropriate.
+
+Here are the encoding functions provided:
+
+
+.. function:: encode_quopri(msg)
+
+ Encodes the payload into quoted-printable form and sets the
+ :mailheader:`Content-Transfer-Encoding` header to ``quoted-printable`` [#]_.
+ This is a good encoding to use when most of your payload is normal printable
+ data, but contains a few unprintable characters.
+
+
+.. function:: encode_base64(msg)
+
+ Encodes the payload into base64 form and sets the
+ :mailheader:`Content-Transfer-Encoding` header to ``base64``. This is a good
+ encoding to use when most of your payload is unprintable data since it is a more
+ compact form than quoted-printable. The drawback of base64 encoding is that it
+ renders the text non-human readable.
+
+
+.. function:: encode_7or8bit(msg)
+
+ This doesn't actually modify the message's payload, but it does set the
+ :mailheader:`Content-Transfer-Encoding` header to either ``7bit`` or ``8bit`` as
+ appropriate, based on the payload data.
+
+
+.. function:: encode_noop(msg)
+
+ This does nothing; it doesn't even set the
+ :mailheader:`Content-Transfer-Encoding` header.
+
+.. rubric:: Footnotes
+
+.. [#] Note that encoding with :meth:`encode_quopri` also encodes all tabs and space
+ characters in the data.
+
--- /dev/null
+:mod:`email`: Exception and Defect classes
+------------------------------------------
+
+.. module:: email.errors
+ :synopsis: The exception classes used by the email package.
+
+
+The following exception classes are defined in the :mod:`email.errors` module:
+
+
+.. exception:: MessageError()
+
+ This is the base class for all exceptions that the :mod:`email` package can
+ raise. It is derived from the standard :exc:`Exception` class and defines no
+ additional methods.
+
+
+.. exception:: MessageParseError()
+
+ This is the base class for exceptions thrown by the :class:`Parser` class. It
+ is derived from :exc:`MessageError`.
+
+
+.. exception:: HeaderParseError()
+
+ Raised under some error conditions when parsing the :rfc:`2822` headers of a
+ message, this class is derived from :exc:`MessageParseError`. It can be raised
+ from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods.
+
+ Situations where it can be raised include finding an envelope header after the
+ first :rfc:`2822` header of the message, finding a continuation line before the
+ first :rfc:`2822` header is found, or finding a line in the headers which is
+ neither a header or a continuation line.
+
+
+.. exception:: BoundaryError()
+
+ Raised under some error conditions when parsing the :rfc:`2822` headers of a
+ message, this class is derived from :exc:`MessageParseError`. It can be raised
+ from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods.
+
+ Situations where it can be raised include not being able to find the starting or
+ terminating boundary in a :mimetype:`multipart/\*` message when strict parsing
+ is used.
+
+
+.. exception:: MultipartConversionError()
+
+ Raised when a payload is added to a :class:`Message` object using
+ :meth:`add_payload`, but the payload is already a scalar and the message's
+ :mailheader:`Content-Type` main type is not either :mimetype:`multipart` or
+ missing. :exc:`MultipartConversionError` multiply inherits from
+ :exc:`MessageError` and the built-in :exc:`TypeError`.
+
+ Since :meth:`Message.add_payload` is deprecated, this exception is rarely raised
+ in practice. However the exception may also be raised if the :meth:`attach`
+ method is called on an instance of a class derived from
+ :class:`MIMENonMultipart` (e.g. :class:`MIMEImage`).
+
+Here's the list of the defects that the :class:`FeedParser` can find while
+parsing messages. Note that the defects are added to the message where the
+problem was found, so for example, if a message nested inside a
+:mimetype:`multipart/alternative` had a malformed header, that nested message
+object would have a defect, but the containing messages would not.
+
+All defect classes are subclassed from :class:`email.errors.MessageDefect`, but
+this class is *not* an exception!
+
+.. versionadded:: 2.4
+ All the defect classes were added.
+
+* :class:`NoBoundaryInMultipartDefect` -- A message claimed to be a multipart,
+ but had no :mimetype:`boundary` parameter.
+
+* :class:`StartBoundaryNotFoundDefect` -- The start boundary claimed in the
+ :mailheader:`Content-Type` header was never found.
+
+* :class:`FirstHeaderLineIsContinuationDefect` -- The message had a continuation
+ line as its first header line.
+
+* :class:`MisplacedEnvelopeHeaderDefect` - A "Unix From" header was found in the
+ middle of a header block.
+
+* :class:`MalformedHeaderDefect` -- A header was found that was missing a colon,
+ or was otherwise malformed.
+
+* :class:`MultipartInvariantViolationDefect` -- A message claimed to be a
+ :mimetype:`multipart`, but no subparts were found. Note that when a message has
+ this defect, its :meth:`is_multipart` method may return false even though its
+ content type claims to be :mimetype:`multipart`.
+
--- /dev/null
+:mod:`email`: Generating MIME documents
+---------------------------------------
+
+.. module:: email.generator
+ :synopsis: Generate flat text email messages from a message structure.
+
+
+One of the most common tasks is to generate the flat text of the email message
+represented by a message object structure. You will need to do this if you want
+to send your message via the :mod:`smtplib` module or the :mod:`nntplib` module,
+or print the message on the console. Taking a message object structure and
+producing a flat text document is the job of the :class:`Generator` class.
+
+Again, as with the :mod:`email.parser` module, you aren't limited to the
+functionality of the bundled generator; you could write one from scratch
+yourself. However the bundled generator knows how to generate most email in a
+standards-compliant way, should handle MIME and non-MIME email messages just
+fine, and is designed so that the transformation from flat text, to a message
+structure via the :class:`Parser` class, and back to flat text, is idempotent
+(the input is identical to the output).
+
+Here are the public methods of the :class:`Generator` class, imported from the
+:mod:`email.generator` module:
+
+
+.. class:: Generator(outfp[, mangle_from_[, maxheaderlen]])
+
+ The constructor for the :class:`Generator` class takes a file-like object called
+ *outfp* for an argument. *outfp* must support the :meth:`write` method and be
+ usable as the output file in a Python extended print statement.
+
+ Optional *mangle_from_* is a flag that, when ``True``, puts a ``>`` character in
+ front of any line in the body that starts exactly as ``From``, i.e. ``From``
+ followed by a space at the beginning of the line. This is the only guaranteed
+ portable way to avoid having such lines be mistaken for a Unix mailbox format
+ envelope header separator (see `WHY THE CONTENT-LENGTH FORMAT IS BAD
+ <http://www.jwz.org/doc/content-length.html>`_ for details). *mangle_from_*
+ defaults to ``True``, but you might want to set this to ``False`` if you are not
+ writing Unix mailbox format files.
+
+ Optional *maxheaderlen* specifies the longest length for a non-continued header.
+ When a header line is longer than *maxheaderlen* (in characters, with tabs
+ expanded to 8 spaces), the header will be split as defined in the
+ :mod:`email.header.Header` class. Set to zero to disable header wrapping. The
+ default is 78, as recommended (but not required) by :rfc:`2822`.
+
+The other public :class:`Generator` methods are:
+
+
+.. method:: Generator.flatten(msg[, unixfrom])
+
+ Print the textual representation of the message object structure rooted at *msg*
+ to the output file specified when the :class:`Generator` instance was created.
+ Subparts are visited depth-first and the resulting text will be properly MIME
+ encoded.
+
+ Optional *unixfrom* is a flag that forces the printing of the envelope header
+ delimiter before the first :rfc:`2822` header of the root message object. If
+ the root object has no envelope header, a standard one is crafted. By default,
+ this is set to ``False`` to inhibit the printing of the envelope delimiter.
+
+ Note that for subparts, no envelope header is ever printed.
+
+ .. versionadded:: 2.2.2
+
+
+.. method:: Generator.clone(fp)
+
+ Return an independent clone of this :class:`Generator` instance with the exact
+ same options.
+
+ .. versionadded:: 2.2.2
+
+
+.. method:: Generator.write(s)
+
+ Write the string *s* to the underlying file object, i.e. *outfp* passed to
+ :class:`Generator`'s constructor. This provides just enough file-like API for
+ :class:`Generator` instances to be used in extended print statements.
+
+As a convenience, see the methods :meth:`Message.as_string` and
+``str(aMessage)``, a.k.a. :meth:`Message.__str__`, which simplify the generation
+of a formatted string representation of a message object. For more detail, see
+:mod:`email.message`.
+
+The :mod:`email.generator` module also provides a derived class, called
+:class:`DecodedGenerator` which is like the :class:`Generator` base class,
+except that non-\ :mimetype:`text` parts are substituted with a format string
+representing the part.
+
+
+.. class:: DecodedGenerator(outfp[, mangle_from_[, maxheaderlen[, fmt]]])
+
+ This class, derived from :class:`Generator` walks through all the subparts of a
+ message. If the subpart is of main type :mimetype:`text`, then it prints the
+ decoded payload of the subpart. Optional *_mangle_from_* and *maxheaderlen* are
+ as with the :class:`Generator` base class.
+
+ If the subpart is not of main type :mimetype:`text`, optional *fmt* is a format
+ string that is used instead of the message payload. *fmt* is expanded with the
+ following keywords, ``%(keyword)s`` format:
+
+ * ``type`` -- Full MIME type of the non-\ :mimetype:`text` part
+
+ * ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part
+
+ * ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part
+
+ * ``filename`` -- Filename of the non-\ :mimetype:`text` part
+
+ * ``description`` -- Description associated with the non-\ :mimetype:`text` part
+
+ * ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part
+
+ The default value for *fmt* is ``None``, meaning ::
+
+ [Non-text (%(type)s) part of message omitted, filename %(filename)s]
+
+ .. versionadded:: 2.2.2
+
+.. versionchanged:: 2.5
+ The previously deprecated method :meth:`__call__` was removed.
+
--- /dev/null
+:mod:`email`: Internationalized headers
+---------------------------------------
+
+.. module:: email.header
+ :synopsis: Representing non-ASCII headers
+
+
+:rfc:`2822` is the base standard that describes the format of email messages.
+It derives from the older :rfc:`822` standard which came into widespread use at
+a time when most email was composed of ASCII characters only. :rfc:`2822` is a
+specification written assuming email contains only 7-bit ASCII characters.
+
+Of course, as email has been deployed worldwide, it has become
+internationalized, such that language specific character sets can now be used in
+email messages. The base standard still requires email messages to be
+transferred using only 7-bit ASCII characters, so a slew of RFCs have been
+written describing how to encode email containing non-ASCII characters into
+:rfc:`2822`\ -compliant format. These RFCs include :rfc:`2045`, :rfc:`2046`,
+:rfc:`2047`, and :rfc:`2231`. The :mod:`email` package supports these standards
+in its :mod:`email.header` and :mod:`email.charset` modules.
+
+If you want to include non-ASCII characters in your email headers, say in the
+:mailheader:`Subject` or :mailheader:`To` fields, you should use the
+:class:`Header` class and assign the field in the :class:`Message` object to an
+instance of :class:`Header` instead of using a string for the header value.
+Import the :class:`Header` class from the :mod:`email.header` module. For
+example::
+
+ >>> from email.message import Message
+ >>> from email.header import Header
+ >>> msg = Message()
+ >>> h = Header('p\xf6stal', 'iso-8859-1')
+ >>> msg['Subject'] = h
+ >>> print msg.as_string()
+ Subject: =?iso-8859-1?q?p=F6stal?=
+
+
+
+Notice here how we wanted the :mailheader:`Subject` field to contain a non-ASCII
+character? We did this by creating a :class:`Header` instance and passing in
+the character set that the byte string was encoded in. When the subsequent
+:class:`Message` instance was flattened, the :mailheader:`Subject` field was
+properly :rfc:`2047` encoded. MIME-aware mail readers would show this header
+using the embedded ISO-8859-1 character.
+
+.. versionadded:: 2.2.2
+
+Here is the :class:`Header` class description:
+
+
+.. class:: Header([s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]])
+
+ Create a MIME-compliant header that can contain strings in different character
+ sets.
+
+ Optional *s* is the initial header value. If ``None`` (the default), the
+ initial header value is not set. You can later append to the header with
+ :meth:`append` method calls. *s* may be a byte string or a Unicode string, but
+ see the :meth:`append` documentation for semantics.
+
+ Optional *charset* serves two purposes: it has the same meaning as the *charset*
+ argument to the :meth:`append` method. It also sets the default character set
+ for all subsequent :meth:`append` calls that omit the *charset* argument. If
+ *charset* is not provided in the constructor (the default), the ``us-ascii``
+ character set is used both as *s*'s initial charset and as the default for
+ subsequent :meth:`append` calls.
+
+ The maximum line length can be specified explicit via *maxlinelen*. For
+ splitting the first line to a shorter value (to account for the field header
+ which isn't included in *s*, e.g. :mailheader:`Subject`) pass in the name of the
+ field in *header_name*. The default *maxlinelen* is 76, and the default value
+ for *header_name* is ``None``, meaning it is not taken into account for the
+ first line of a long, split header.
+
+ Optional *continuation_ws* must be :rfc:`2822`\ -compliant folding whitespace,
+ and is usually either a space or a hard tab character. This character will be
+ prepended to continuation lines.
+
+Optional *errors* is passed straight through to the :meth:`append` method.
+
+
+.. method:: Header.append(s[, charset[, errors]])
+
+ Append the string *s* to the MIME header.
+
+ Optional *charset*, if given, should be a :class:`Charset` instance (see
+ :mod:`email.charset`) or the name of a character set, which will be converted to
+ a :class:`Charset` instance. A value of ``None`` (the default) means that the
+ *charset* given in the constructor is used.
+
+ *s* may be a byte string or a Unicode string. If it is a byte string (i.e.
+ ``isinstance(s, str)`` is true), then *charset* is the encoding of that byte
+ string, and a :exc:`UnicodeError` will be raised if the string cannot be decoded
+ with that character set.
+
+ If *s* is a Unicode string, then *charset* is a hint specifying the character
+ set of the characters in the string. In this case, when producing an
+ :rfc:`2822`\ -compliant header using :rfc:`2047` rules, the Unicode string will
+ be encoded using the following charsets in order: ``us-ascii``, the *charset*
+ hint, ``utf-8``. The first character set to not provoke a :exc:`UnicodeError`
+ is used.
+
+ Optional *errors* is passed through to any :func:`unicode` or
+ :func:`ustr.encode` call, and defaults to "strict".
+
+
+.. method:: Header.encode([splitchars])
+
+ Encode a message header into an RFC-compliant format, possibly wrapping long
+ lines and encapsulating non-ASCII parts in base64 or quoted-printable encodings.
+ Optional *splitchars* is a string containing characters to split long ASCII
+ lines on, in rough support of :rfc:`2822`'s *highest level syntactic breaks*.
+ This doesn't affect :rfc:`2047` encoded lines.
+
+The :class:`Header` class also provides a number of methods to support standard
+operators and built-in functions.
+
+
+.. method:: Header.__str__()
+
+ A synonym for :meth:`Header.encode`. Useful for ``str(aHeader)``.
+
+
+.. method:: Header.__unicode__()
+
+ A helper for the built-in :func:`unicode` function. Returns the header as a
+ Unicode string.
+
+
+.. method:: Header.__eq__(other)
+
+ This method allows you to compare two :class:`Header` instances for equality.
+
+
+.. method:: Header.__ne__(other)
+
+ This method allows you to compare two :class:`Header` instances for inequality.
+
+The :mod:`email.header` module also provides the following convenient functions.
+
+
+.. function:: decode_header(header)
+
+ Decode a message header value without converting the character set. The header
+ value is in *header*.
+
+ This function returns a list of ``(decoded_string, charset)`` pairs containing
+ each of the decoded parts of the header. *charset* is ``None`` for non-encoded
+ parts of the header, otherwise a lower case string containing the name of the
+ character set specified in the encoded string.
+
+ Here's an example::
+
+ >>> from email.header import decode_header
+ >>> decode_header('=?iso-8859-1?q?p=F6stal?=')
+ [('p\xf6stal', 'iso-8859-1')]
+
+
+.. function:: make_header(decoded_seq[, maxlinelen[, header_name[, continuation_ws]]])
+
+ Create a :class:`Header` instance from a sequence of pairs as returned by
+ :func:`decode_header`.
+
+ :func:`decode_header` takes a header value string and returns a sequence of
+ pairs of the format ``(decoded_string, charset)`` where *charset* is the name of
+ the character set.
+
+ This function takes one of those sequence of pairs and returns a :class:`Header`
+ instance. Optional *maxlinelen*, *header_name*, and *continuation_ws* are as in
+ the :class:`Header` constructor.
+
--- /dev/null
+:mod:`email`: Iterators
+-----------------------
+
+.. module:: email.iterators
+ :synopsis: Iterate over a message object tree.
+
+
+Iterating over a message object tree is fairly easy with the
+:meth:`Message.walk` method. The :mod:`email.iterators` module provides some
+useful higher level iterations over message object trees.
+
+
+.. function:: body_line_iterator(msg[, decode])
+
+ This iterates over all the payloads in all the subparts of *msg*, returning the
+ string payloads line-by-line. It skips over all the subpart headers, and it
+ skips over any subpart with a payload that isn't a Python string. This is
+ somewhat equivalent to reading the flat text representation of the message from
+ a file using :meth:`readline`, skipping over all the intervening headers.
+
+ Optional *decode* is passed through to :meth:`Message.get_payload`.
+
+
+.. function:: typed_subpart_iterator(msg[, maintype[, subtype]])
+
+ This iterates over all the subparts of *msg*, returning only those subparts that
+ match the MIME type specified by *maintype* and *subtype*.
+
+ Note that *subtype* is optional; if omitted, then subpart MIME type matching is
+ done only with the main type. *maintype* is optional too; it defaults to
+ :mimetype:`text`.
+
+ Thus, by default :func:`typed_subpart_iterator` returns each subpart that has a
+ MIME type of :mimetype:`text/\*`.
+
+The following function has been added as a useful debugging tool. It should
+*not* be considered part of the supported public interface for the package.
+
+
+.. function:: _structure(msg[, fp[, level]])
+
+ Prints an indented representation of the content types of the message object
+ structure. For example::
+
+ >>> msg = email.message_from_file(somefile)
+ >>> _structure(msg)
+ multipart/mixed
+ text/plain
+ text/plain
+ multipart/digest
+ message/rfc822
+ text/plain
+ message/rfc822
+ text/plain
+ message/rfc822
+ text/plain
+ message/rfc822
+ text/plain
+ message/rfc822
+ text/plain
+ text/plain
+
+ Optional *fp* is a file-like object to print the output to. It must be suitable
+ for Python's extended print statement. *level* is used internally.
+
--- /dev/null
+:mod:`email`: Representing an email message
+-------------------------------------------
+
+.. module:: email.message
+ :synopsis: The base class representing email messages.
+
+
+The central class in the :mod:`email` package is the :class:`Message` class,
+imported from the :mod:`email.message` module. It is the base class for the
+:mod:`email` object model. :class:`Message` provides the core functionality for
+setting and querying header fields, and for accessing message bodies.
+
+Conceptually, a :class:`Message` object consists of *headers* and *payloads*.
+Headers are :rfc:`2822` style field names and values where the field name and
+value are separated by a colon. The colon is not part of either the field name
+or the field value.
+
+Headers are stored and returned in case-preserving form but are matched
+case-insensitively. There may also be a single envelope header, also known as
+the *Unix-From* header or the ``From_`` header. The payload is either a string
+in the case of simple message objects or a list of :class:`Message` objects for
+MIME container documents (e.g. :mimetype:`multipart/\*` and
+:mimetype:`message/rfc822`).
+
+:class:`Message` objects provide a mapping style interface for accessing the
+message headers, and an explicit interface for accessing both the headers and
+the payload. It provides convenience methods for generating a flat text
+representation of the message object tree, for accessing commonly used header
+parameters, and for recursively walking over the object tree.
+
+Here are the methods of the :class:`Message` class:
+
+
+.. class:: Message()
+
+ The constructor takes no arguments.
+
+
+.. method:: Message.as_string([unixfrom])
+
+ Return the entire message flatten as a string. When optional *unixfrom* is
+ ``True``, the envelope header is included in the returned string. *unixfrom*
+ defaults to ``False``.
+
+ Note that this method is provided as a convenience and may not always format the
+ message the way you want. For example, by default it mangles lines that begin
+ with ``From``. For more flexibility, instantiate a :class:`Generator` instance
+ and use its :meth:`flatten` method directly. For example::
+
+ from cStringIO import StringIO
+ from email.generator import Generator
+ fp = StringIO()
+ g = Generator(fp, mangle_from_=False, maxheaderlen=60)
+ g.flatten(msg)
+ text = fp.getvalue()
+
+
+.. method:: Message.__str__()
+
+ Equivalent to ``as_string(unixfrom=True)``.
+
+
+.. method:: Message.is_multipart()
+
+ Return ``True`` if the message's payload is a list of sub-\ :class:`Message`
+ objects, otherwise return ``False``. When :meth:`is_multipart` returns False,
+ the payload should be a string object.
+
+
+.. method:: Message.set_unixfrom(unixfrom)
+
+ Set the message's envelope header to *unixfrom*, which should be a string.
+
+
+.. method:: Message.get_unixfrom()
+
+ Return the message's envelope header. Defaults to ``None`` if the envelope
+ header was never set.
+
+
+.. method:: Message.attach(payload)
+
+ Add the given *payload* to the current payload, which must be ``None`` or a list
+ of :class:`Message` objects before the call. After the call, the payload will
+ always be a list of :class:`Message` objects. If you want to set the payload to
+ a scalar object (e.g. a string), use :meth:`set_payload` instead.
+
+
+.. method:: Message.get_payload([i[, decode]])
+
+ Return a reference the current payload, which will be a list of :class:`Message`
+ objects when :meth:`is_multipart` is ``True``, or a string when
+ :meth:`is_multipart` is ``False``. If the payload is a list and you mutate the
+ list object, you modify the message's payload in place.
+
+ With optional argument *i*, :meth:`get_payload` will return the *i*-th element
+ of the payload, counting from zero, if :meth:`is_multipart` is ``True``. An
+ :exc:`IndexError` will be raised if *i* is less than 0 or greater than or equal
+ to the number of items in the payload. If the payload is a string (i.e.
+ :meth:`is_multipart` is ``False``) and *i* is given, a :exc:`TypeError` is
+ raised.
+
+ Optional *decode* is a flag indicating whether the payload should be decoded or
+ not, according to the :mailheader:`Content-Transfer-Encoding` header. When
+ ``True`` and the message is not a multipart, the payload will be decoded if this
+ header's value is ``quoted-printable`` or ``base64``. If some other encoding is
+ used, or :mailheader:`Content-Transfer-Encoding` header is missing, or if the
+ payload has bogus base64 data, the payload is returned as-is (undecoded). If
+ the message is a multipart and the *decode* flag is ``True``, then ``None`` is
+ returned. The default for *decode* is ``False``.
+
+
+.. method:: Message.set_payload(payload[, charset])
+
+ Set the entire message object's payload to *payload*. It is the client's
+ responsibility to ensure the payload invariants. Optional *charset* sets the
+ message's default character set; see :meth:`set_charset` for details.
+
+ .. versionchanged:: 2.2.2
+ *charset* argument added.
+
+
+.. method:: Message.set_charset(charset)
+
+ Set the character set of the payload to *charset*, which can either be a
+ :class:`Charset` instance (see :mod:`email.charset`), a string naming a
+ character set, or ``None``. If it is a string, it will be converted to a
+ :class:`Charset` instance. If *charset* is ``None``, the ``charset`` parameter
+ will be removed from the :mailheader:`Content-Type` header. Anything else will
+ generate a :exc:`TypeError`.
+
+ The message will be assumed to be of type :mimetype:`text/\*` encoded with
+ *charset.input_charset*. It will be converted to *charset.output_charset* and
+ encoded properly, if needed, when generating the plain text representation of
+ the message. MIME headers (:mailheader:`MIME-Version`,
+ :mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) will be
+ added as needed.
+
+ .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_charset()
+
+ Return the :class:`Charset` instance associated with the message's payload.
+
+ .. versionadded:: 2.2.2
+
+The following methods implement a mapping-like interface for accessing the
+message's :rfc:`2822` headers. Note that there are some semantic differences
+between these methods and a normal mapping (i.e. dictionary) interface. For
+example, in a dictionary there are no duplicate keys, but here there may be
+duplicate message headers. Also, in dictionaries there is no guaranteed order
+to the keys returned by :meth:`keys`, but in a :class:`Message` object, headers
+are always returned in the order they appeared in the original message, or were
+added to the message later. Any header deleted and then re-added are always
+appended to the end of the header list.
+
+These semantic differences are intentional and are biased toward maximal
+convenience.
+
+Note that in all cases, any envelope header present in the message is not
+included in the mapping interface.
+
+
+.. method:: Message.__len__()
+
+ Return the total number of headers, including duplicates.
+
+
+.. method:: Message.__contains__(name)
+
+ Return true if the message object has a field named *name*. Matching is done
+ case-insensitively and *name* should not include the trailing colon. Used for
+ the ``in`` operator, e.g.::
+
+ if 'message-id' in myMessage:
+ print 'Message-ID:', myMessage['message-id']
+
+
+.. method:: Message.__getitem__(name)
+
+ Return the value of the named header field. *name* should not include the colon
+ field separator. If the header is missing, ``None`` is returned; a
+ :exc:`KeyError` is never raised.
+
+ Note that if the named field appears more than once in the message's headers,
+ exactly which of those field values will be returned is undefined. Use the
+ :meth:`get_all` method to get the values of all the extant named headers.
+
+
+.. method:: Message.__setitem__(name, val)
+
+ Add a header to the message with field name *name* and value *val*. The field
+ is appended to the end of the message's existing fields.
+
+ Note that this does *not* overwrite or delete any existing header with the same
+ name. If you want to ensure that the new header is the only one present in the
+ message with field name *name*, delete the field first, e.g.::
+
+ del msg['subject']
+ msg['subject'] = 'Python roolz!'
+
+
+.. method:: Message.__delitem__(name)
+
+ Delete all occurrences of the field with name *name* from the message's headers.
+ No exception is raised if the named field isn't present in the headers.
+
+
+.. method:: Message.has_key(name)
+
+ Return true if the message contains a header field named *name*, otherwise
+ return false.
+
+
+.. method:: Message.keys()
+
+ Return a list of all the message's header field names.
+
+
+.. method:: Message.values()
+
+ Return a list of all the message's field values.
+
+
+.. method:: Message.items()
+
+ Return a list of 2-tuples containing all the message's field headers and values.
+
+
+.. method:: Message.get(name[, failobj])
+
+ Return the value of the named header field. This is identical to
+ :meth:`__getitem__` except that optional *failobj* is returned if the named
+ header is missing (defaults to ``None``).
+
+Here are some additional useful methods:
+
+
+.. method:: Message.get_all(name[, failobj])
+
+ Return a list of all the values for the field named *name*. If there are no such
+ named headers in the message, *failobj* is returned (defaults to ``None``).
+
+
+.. method:: Message.add_header(_name, _value, **_params)
+
+ Extended header setting. This method is similar to :meth:`__setitem__` except
+ that additional header parameters can be provided as keyword arguments. *_name*
+ is the header field to add and *_value* is the *primary* value for the header.
+
+ For each item in the keyword argument dictionary *_params*, the key is taken as
+ the parameter name, with underscores converted to dashes (since dashes are
+ illegal in Python identifiers). Normally, the parameter will be added as
+ ``key="value"`` unless the value is ``None``, in which case only the key will be
+ added.
+
+ Here's an example::
+
+ msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
+
+ This will add a header that looks like ::
+
+ Content-Disposition: attachment; filename="bud.gif"
+
+
+.. method:: Message.replace_header(_name, _value)
+
+ Replace a header. Replace the first header found in the message that matches
+ *_name*, retaining header order and field name case. If no matching header was
+ found, a :exc:`KeyError` is raised.
+
+ .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_content_type()
+
+ Return the message's content type. The returned string is coerced to lower case
+ of the form :mimetype:`maintype/subtype`. If there was no
+ :mailheader:`Content-Type` header in the message the default type as given by
+ :meth:`get_default_type` will be returned. Since according to :rfc:`2045`,
+ messages always have a default type, :meth:`get_content_type` will always return
+ a value.
+
+ :rfc:`2045` defines a message's default type to be :mimetype:`text/plain` unless
+ it appears inside a :mimetype:`multipart/digest` container, in which case it
+ would be :mimetype:`message/rfc822`. If the :mailheader:`Content-Type` header
+ has an invalid type specification, :rfc:`2045` mandates that the default type be
+ :mimetype:`text/plain`.
+
+ .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_content_maintype()
+
+ Return the message's main content type. This is the :mimetype:`maintype` part
+ of the string returned by :meth:`get_content_type`.
+
+ .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_content_subtype()
+
+ Return the message's sub-content type. This is the :mimetype:`subtype` part of
+ the string returned by :meth:`get_content_type`.
+
+ .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_default_type()
+
+ Return the default content type. Most messages have a default content type of
+ :mimetype:`text/plain`, except for messages that are subparts of
+ :mimetype:`multipart/digest` containers. Such subparts have a default content
+ type of :mimetype:`message/rfc822`.
+
+ .. versionadded:: 2.2.2
+
+
+.. method:: Message.set_default_type(ctype)
+
+ Set the default content type. *ctype* should either be :mimetype:`text/plain`
+ or :mimetype:`message/rfc822`, although this is not enforced. The default
+ content type is not stored in the :mailheader:`Content-Type` header.
+
+ .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_params([failobj[, header[, unquote]]])
+
+ Return the message's :mailheader:`Content-Type` parameters, as a list. The
+ elements of the returned list are 2-tuples of key/value pairs, as split on the
+ ``'='`` sign. The left hand side of the ``'='`` is the key, while the right
+ hand side is the value. If there is no ``'='`` sign in the parameter the value
+ is the empty string, otherwise the value is as described in :meth:`get_param`
+ and is unquoted if optional *unquote* is ``True`` (the default).
+
+ Optional *failobj* is the object to return if there is no
+ :mailheader:`Content-Type` header. Optional *header* is the header to search
+ instead of :mailheader:`Content-Type`.
+
+ .. versionchanged:: 2.2.2
+ *unquote* argument added.
+
+
+.. method:: Message.get_param(param[, failobj[, header[, unquote]]])
+
+ Return the value of the :mailheader:`Content-Type` header's parameter *param* as
+ a string. If the message has no :mailheader:`Content-Type` header or if there
+ is no such parameter, then *failobj* is returned (defaults to ``None``).
+
+ Optional *header* if given, specifies the message header to use instead of
+ :mailheader:`Content-Type`.
+
+ Parameter keys are always compared case insensitively. The return value can
+ either be a string, or a 3-tuple if the parameter was :rfc:`2231` encoded. When
+ it's a 3-tuple, the elements of the value are of the form ``(CHARSET, LANGUAGE,
+ VALUE)``. Note that both ``CHARSET`` and ``LANGUAGE`` can be ``None``, in which
+ case you should consider ``VALUE`` to be encoded in the ``us-ascii`` charset.
+ You can usually ignore ``LANGUAGE``.
+
+ If your application doesn't care whether the parameter was encoded as in
+ :rfc:`2231`, you can collapse the parameter value by calling
+ :func:`email.Utils.collapse_rfc2231_value`, passing in the return value from
+ :meth:`get_param`. This will return a suitably decoded Unicode string whn the
+ value is a tuple, or the original string unquoted if it isn't. For example::
+
+ rawparam = msg.get_param('foo')
+ param = email.Utils.collapse_rfc2231_value(rawparam)
+
+ In any case, the parameter value (either the returned string, or the ``VALUE``
+ item in the 3-tuple) is always unquoted, unless *unquote* is set to ``False``.
+
+ .. versionchanged:: 2.2.2
+ *unquote* argument added, and 3-tuple return value possible.
+
+
+.. method:: Message.set_param(param, value[, header[, requote[, charset[, language]]]])
+
+ Set a parameter in the :mailheader:`Content-Type` header. If the parameter
+ already exists in the header, its value will be replaced with *value*. If the
+ :mailheader:`Content-Type` header as not yet been defined for this message, it
+ will be set to :mimetype:`text/plain` and the new parameter value will be
+ appended as per :rfc:`2045`.
+
+ Optional *header* specifies an alternative header to :mailheader:`Content-Type`,
+ and all parameters will be quoted as necessary unless optional *requote* is
+ ``False`` (the default is ``True``).
+
+ If optional *charset* is specified, the parameter will be encoded according to
+ :rfc:`2231`. Optional *language* specifies the RFC 2231 language, defaulting to
+ the empty string. Both *charset* and *language* should be strings.
+
+ .. versionadded:: 2.2.2
+
+
+.. method:: Message.del_param(param[, header[, requote]])
+
+ Remove the given parameter completely from the :mailheader:`Content-Type`
+ header. The header will be re-written in place without the parameter or its
+ value. All values will be quoted as necessary unless *requote* is ``False``
+ (the default is ``True``). Optional *header* specifies an alternative to
+ :mailheader:`Content-Type`.
+
+ .. versionadded:: 2.2.2
+
+
+.. method:: Message.set_type(type[, header][, requote])
+
+ Set the main type and subtype for the :mailheader:`Content-Type` header. *type*
+ must be a string in the form :mimetype:`maintype/subtype`, otherwise a
+ :exc:`ValueError` is raised.
+
+ This method replaces the :mailheader:`Content-Type` header, keeping all the
+ parameters in place. If *requote* is ``False``, this leaves the existing
+ header's quoting as is, otherwise the parameters will be quoted (the default).
+
+ An alternative header can be specified in the *header* argument. When the
+ :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version` header is
+ also added.
+
+ .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_filename([failobj])
+
+ Return the value of the ``filename`` parameter of the
+ :mailheader:`Content-Disposition` header of the message. If the header does not
+ have a ``filename`` parameter, this method falls back to looking for the
+ ``name`` parameter. If neither is found, or the header is missing, then
+ *failobj* is returned. The returned string will always be unquoted as per
+ :meth:`Utils.unquote`.
+
+
+.. method:: Message.get_boundary([failobj])
+
+ Return the value of the ``boundary`` parameter of the :mailheader:`Content-Type`
+ header of the message, or *failobj* if either the header is missing, or has no
+ ``boundary`` parameter. The returned string will always be unquoted as per
+ :meth:`Utils.unquote`.
+
+
+.. method:: Message.set_boundary(boundary)
+
+ Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
+ *boundary*. :meth:`set_boundary` will always quote *boundary* if necessary. A
+ :exc:`HeaderParseError` is raised if the message object has no
+ :mailheader:`Content-Type` header.
+
+ Note that using this method is subtly different than deleting the old
+ :mailheader:`Content-Type` header and adding a new one with the new boundary via
+ :meth:`add_header`, because :meth:`set_boundary` preserves the order of the
+ :mailheader:`Content-Type` header in the list of headers. However, it does *not*
+ preserve any continuation lines which may have been present in the original
+ :mailheader:`Content-Type` header.
+
+
+.. method:: Message.get_content_charset([failobj])
+
+ Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
+ coerced to lower case. If there is no :mailheader:`Content-Type` header, or if
+ that header has no ``charset`` parameter, *failobj* is returned.
+
+ Note that this method differs from :meth:`get_charset` which returns the
+ :class:`Charset` instance for the default encoding of the message body.
+
+ .. versionadded:: 2.2.2
+
+
+.. method:: Message.get_charsets([failobj])
+
+ Return a list containing the character set names in the message. If the message
+ is a :mimetype:`multipart`, then the list will contain one element for each
+ subpart in the payload, otherwise, it will be a list of length 1.
+
+ Each item in the list will be a string which is the value of the ``charset``
+ parameter in the :mailheader:`Content-Type` header for the represented subpart.
+ However, if the subpart has no :mailheader:`Content-Type` header, no ``charset``
+ parameter, or is not of the :mimetype:`text` main MIME type, then that item in
+ the returned list will be *failobj*.
+
+
+.. method:: Message.walk()
+
+ The :meth:`walk` method is an all-purpose generator which can be used to iterate
+ over all the parts and subparts of a message object tree, in depth-first
+ traversal order. You will typically use :meth:`walk` as the iterator in a
+ ``for`` loop; each iteration returns the next subpart.
+
+ Here's an example that prints the MIME type of every part of a multipart message
+ structure::
+
+ >>> for part in msg.walk():
+ ... print part.get_content_type()
+ multipart/report
+ text/plain
+ message/delivery-status
+ text/plain
+ text/plain
+ message/rfc822
+
+.. versionchanged:: 2.5
+ The previously deprecated methods :meth:`get_type`, :meth:`get_main_type`, and
+ :meth:`get_subtype` were removed.
+
+:class:`Message` objects can also optionally contain two instance attributes,
+which can be used when generating the plain text of a MIME message.
+
+
+.. data:: preamble
+
+ The format of a MIME document allows for some text between the blank line
+ following the headers, and the first multipart boundary string. Normally, this
+ text is never visible in a MIME-aware mail reader because it falls outside the
+ standard MIME armor. However, when viewing the raw text of the message, or when
+ viewing the message in a non-MIME aware reader, this text can become visible.
+
+ The *preamble* attribute contains this leading extra-armor text for MIME
+ documents. When the :class:`Parser` discovers some text after the headers but
+ before the first boundary string, it assigns this text to the message's
+ *preamble* attribute. When the :class:`Generator` is writing out the plain text
+ representation of a MIME message, and it finds the message has a *preamble*
+ attribute, it will write this text in the area between the headers and the first
+ boundary. See :mod:`email.parser` and :mod:`email.generator` for details.
+
+ Note that if the message object has no preamble, the *preamble* attribute will
+ be ``None``.
+
+
+.. data:: epilogue
+
+ The *epilogue* attribute acts the same way as the *preamble* attribute, except
+ that it contains text that appears between the last boundary and the end of the
+ message.
+
+ .. versionchanged:: 2.5
+ You do not need to set the epilogue to the empty string in order for the
+ :class:`Generator` to print a newline at the end of the file.
+
+
+.. data:: defects
+
+ The *defects* attribute contains a list of all the problems found when parsing
+ this message. See :mod:`email.errors` for a detailed description of the
+ possible parsing defects.
+
+ .. versionadded:: 2.4
+
--- /dev/null
+:mod:`email`: Creating email and MIME objects from scratch
+----------------------------------------------------------
+
+.. module:: email.mime
+ :synopsis: Build MIME messages.
+
+
+Ordinarily, you get a message object structure by passing a file or some text to
+a parser, which parses the text and returns the root message object. However
+you can also build a complete message structure from scratch, or even individual
+:class:`Message` objects by hand. In fact, you can also take an existing
+structure and add new :class:`Message` objects, move them around, etc. This
+makes a very convenient interface for slicing-and-dicing MIME messages.
+
+You can create a new object structure by creating :class:`Message` instances,
+adding attachments and all the appropriate headers manually. For MIME messages
+though, the :mod:`email` package provides some convenient subclasses to make
+things easier.
+
+Here are the classes:
+
+
+.. class:: MIMEBase(_maintype, _subtype, **_params)
+
+ Module: :mod:`email.mime.base`
+
+ This is the base class for all the MIME-specific subclasses of :class:`Message`.
+ Ordinarily you won't create instances specifically of :class:`MIMEBase`,
+ although you could. :class:`MIMEBase` is provided primarily as a convenient
+ base class for more specific MIME-aware subclasses.
+
+ *_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
+ or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
+ type (e.g. :mimetype:`plain` or :mimetype:`gif`). *_params* is a parameter
+ key/value dictionary and is passed directly to :meth:`Message.add_header`.
+
+ The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header
+ (based on *_maintype*, *_subtype*, and *_params*), and a
+ :mailheader:`MIME-Version` header (always set to ``1.0``).
+
+
+.. class:: MIMENonMultipart()
+
+ Module: :mod:`email.mime.nonmultipart`
+
+ A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME
+ messages that are not :mimetype:`multipart`. The primary purpose of this class
+ is to prevent the use of the :meth:`attach` method, which only makes sense for
+ :mimetype:`multipart` messages. If :meth:`attach` is called, a
+ :exc:`MultipartConversionError` exception is raised.
+
+ .. versionadded:: 2.2.2
+
+
+.. class:: MIMEMultipart([subtype[, boundary[, _subparts[, _params]]]])
+
+ Module: :mod:`email.mime.multipart`
+
+ A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME
+ messages that are :mimetype:`multipart`. Optional *_subtype* defaults to
+ :mimetype:`mixed`, but can be used to specify the subtype of the message. A
+ :mailheader:`Content-Type` header of :mimetype:`multipart/`*_subtype* will be
+ added to the message object. A :mailheader:`MIME-Version` header will also be
+ added.
+
+ Optional *boundary* is the multipart boundary string. When ``None`` (the
+ default), the boundary is calculated when needed.
+
+ *_subparts* is a sequence of initial subparts for the payload. It must be
+ possible to convert this sequence to a list. You can always attach new subparts
+ to the message by using the :meth:`Message.attach` method.
+
+ Additional parameters for the :mailheader:`Content-Type` header are taken from
+ the keyword arguments, or passed into the *_params* argument, which is a keyword
+ dictionary.
+
+ .. versionadded:: 2.2.2
+
+
+.. class:: MIMEApplication(_data[, _subtype[, _encoder[, **_params]]])
+
+ Module: :mod:`email.mime.application`
+
+ A subclass of :class:`MIMENonMultipart`, the :class:`MIMEApplication` class is
+ used to represent MIME message objects of major type :mimetype:`application`.
+ *_data* is a string containing the raw byte data. Optional *_subtype* specifies
+ the MIME subtype and defaults to :mimetype:`octet-stream`.
+
+ Optional *_encoder* is a callable (i.e. function) which will perform the actual
+ encoding of the data for transport. This callable takes one argument, which is
+ the :class:`MIMEApplication` instance. It should use :meth:`get_payload` and
+ :meth:`set_payload` to change the payload to encoded form. It should also add
+ any :mailheader:`Content-Transfer-Encoding` or other headers to the message
+ object as necessary. The default encoding is base64. See the
+ :mod:`email.encoders` module for a list of the built-in encoders.
+
+ *_params* are passed straight through to the base class constructor.
+
+ .. versionadded:: 2.5
+
+
+.. class:: MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]])
+
+ Module: :mod:`email.mime.audio`
+
+ A subclass of :class:`MIMENonMultipart`, the :class:`MIMEAudio` class is used to
+ create MIME message objects of major type :mimetype:`audio`. *_audiodata* is a
+ string containing the raw audio data. If this data can be decoded by the
+ standard Python module :mod:`sndhdr`, then the subtype will be automatically
+ included in the :mailheader:`Content-Type` header. Otherwise you can explicitly
+ specify the audio subtype via the *_subtype* parameter. If the minor type could
+ not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.
+
+ Optional *_encoder* is a callable (i.e. function) which will perform the actual
+ encoding of the audio data for transport. This callable takes one argument,
+ which is the :class:`MIMEAudio` instance. It should use :meth:`get_payload` and
+ :meth:`set_payload` to change the payload to encoded form. It should also add
+ any :mailheader:`Content-Transfer-Encoding` or other headers to the message
+ object as necessary. The default encoding is base64. See the
+ :mod:`email.encoders` module for a list of the built-in encoders.
+
+ *_params* are passed straight through to the base class constructor.
+
+
+.. class:: MIMEImage(_imagedata[, _subtype[, _encoder[, **_params]]])
+
+ Module: :mod:`email.mime.image`
+
+ A subclass of :class:`MIMENonMultipart`, the :class:`MIMEImage` class is used to
+ create MIME message objects of major type :mimetype:`image`. *_imagedata* is a
+ string containing the raw image data. If this data can be decoded by the
+ standard Python module :mod:`imghdr`, then the subtype will be automatically
+ included in the :mailheader:`Content-Type` header. Otherwise you can explicitly
+ specify the image subtype via the *_subtype* parameter. If the minor type could
+ not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.
+
+ Optional *_encoder* is a callable (i.e. function) which will perform the actual
+ encoding of the image data for transport. This callable takes one argument,
+ which is the :class:`MIMEImage` instance. It should use :meth:`get_payload` and
+ :meth:`set_payload` to change the payload to encoded form. It should also add
+ any :mailheader:`Content-Transfer-Encoding` or other headers to the message
+ object as necessary. The default encoding is base64. See the
+ :mod:`email.encoders` module for a list of the built-in encoders.
+
+ *_params* are passed straight through to the :class:`MIMEBase` constructor.
+
+
+.. class:: MIMEMessage(_msg[, _subtype])
+
+ Module: :mod:`email.mime.message`
+
+ A subclass of :class:`MIMENonMultipart`, the :class:`MIMEMessage` class is used
+ to create MIME objects of main type :mimetype:`message`. *_msg* is used as the
+ payload, and must be an instance of class :class:`Message` (or a subclass
+ thereof), otherwise a :exc:`TypeError` is raised.
+
+ Optional *_subtype* sets the subtype of the message; it defaults to
+ :mimetype:`rfc822`.
+
+
+.. class:: MIMEText(_text[, _subtype[, _charset]])
+
+ Module: :mod:`email.mime.text`
+
+ A subclass of :class:`MIMENonMultipart`, the :class:`MIMEText` class is used to
+ create MIME objects of major type :mimetype:`text`. *_text* is the string for
+ the payload. *_subtype* is the minor type and defaults to :mimetype:`plain`.
+ *_charset* is the character set of the text and is passed as a parameter to the
+ :class:`MIMENonMultipart` constructor; it defaults to ``us-ascii``. No guessing
+ or encoding is performed on the text data.
+
+ .. versionchanged:: 2.4
+ The previously deprecated *_encoding* argument has been removed. Encoding
+ happens implicitly based on the *_charset* argument.
+
--- /dev/null
+:mod:`email`: Parsing email messages
+------------------------------------
+
+.. module:: email.parser
+ :synopsis: Parse flat text email messages to produce a message object structure.
+
+
+Message object structures can be created in one of two ways: they can be created
+from whole cloth by instantiating :class:`Message` objects and stringing them
+together via :meth:`attach` and :meth:`set_payload` calls, or they can be
+created by parsing a flat text representation of the email message.
+
+The :mod:`email` package provides a standard parser that understands most email
+document structures, including MIME documents. You can pass the parser a string
+or a file object, and the parser will return to you the root :class:`Message`
+instance of the object structure. For simple, non-MIME messages the payload of
+this root object will likely be a string containing the text of the message.
+For MIME messages, the root object will return ``True`` from its
+:meth:`is_multipart` method, and the subparts can be accessed via the
+:meth:`get_payload` and :meth:`walk` methods.
+
+There are actually two parser interfaces available for use, the classic
+:class:`Parser` API and the incremental :class:`FeedParser` API. The classic
+:class:`Parser` API is fine if you have the entire text of the message in memory
+as a string, or if the entire message lives in a file on the file system.
+:class:`FeedParser` is more appropriate for when you're reading the message from
+a stream which might block waiting for more input (e.g. reading an email message
+from a socket). The :class:`FeedParser` can consume and parse the message
+incrementally, and only returns the root object when you close the parser [#]_.
+
+Note that the parser can be extended in limited ways, and of course you can
+implement your own parser completely from scratch. There is no magical
+connection between the :mod:`email` package's bundled parser and the
+:class:`Message` class, so your custom parser can create message object trees
+any way it finds necessary.
+
+
+FeedParser API
+^^^^^^^^^^^^^^
+
+.. versionadded:: 2.4
+
+The :class:`FeedParser`, imported from the :mod:`email.feedparser` module,
+provides an API that is conducive to incremental parsing of email messages, such
+as would be necessary when reading the text of an email message from a source
+that can block (e.g. a socket). The :class:`FeedParser` can of course be used
+to parse an email message fully contained in a string or a file, but the classic
+:class:`Parser` API may be more convenient for such use cases. The semantics
+and results of the two parser APIs are identical.
+
+The :class:`FeedParser`'s API is simple; you create an instance, feed it a bunch
+of text until there's no more to feed it, then close the parser to retrieve the
+root message object. The :class:`FeedParser` is extremely accurate when parsing
+standards-compliant messages, and it does a very good job of parsing
+non-compliant messages, providing information about how a message was deemed
+broken. It will populate a message object's *defects* attribute with a list of
+any problems it found in a message. See the :mod:`email.errors` module for the
+list of defects that it can find.
+
+Here is the API for the :class:`FeedParser`:
+
+
+.. class:: FeedParser([_factory])
+
+ Create a :class:`FeedParser` instance. Optional *_factory* is a no-argument
+ callable that will be called whenever a new message object is needed. It
+ defaults to the :class:`email.message.Message` class.
+
+
+.. method:: FeedParser.feed(data)
+
+ Feed the :class:`FeedParser` some more data. *data* should be a string
+ containing one or more lines. The lines can be partial and the
+ :class:`FeedParser` will stitch such partial lines together properly. The lines
+ in the string can have any of the common three line endings, carriage return,
+ newline, or carriage return and newline (they can even be mixed).
+
+
+.. method:: FeedParser.close()
+
+ Closing a :class:`FeedParser` completes the parsing of all previously fed data,
+ and returns the root message object. It is undefined what happens if you feed
+ more data to a closed :class:`FeedParser`.
+
+
+Parser class API
+^^^^^^^^^^^^^^^^
+
+The :class:`Parser` class, imported from the :mod:`email.parser` module,
+provides an API that can be used to parse a message when the complete contents
+of the message are available in a string or file. The :mod:`email.parser`
+module also provides a second class, called :class:`HeaderParser` which can be
+used if you're only interested in the headers of the message.
+:class:`HeaderParser` can be much faster in these situations, since it does not
+attempt to parse the message body, instead setting the payload to the raw body
+as a string. :class:`HeaderParser` has the same API as the :class:`Parser`
+class.
+
+
+.. class:: Parser([_class])
+
+ The constructor for the :class:`Parser` class takes an optional argument
+ *_class*. This must be a callable factory (such as a function or a class), and
+ it is used whenever a sub-message object needs to be created. It defaults to
+ :class:`Message` (see :mod:`email.message`). The factory will be called without
+ arguments.
+
+ The optional *strict* flag is ignored.
+
+ .. deprecated:: 2.4
+ Because the :class:`Parser` class is a backward compatible API wrapper
+ around the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is
+ effectively non-strict. You should simply stop passing a *strict* flag to
+ the :class:`Parser` constructor.
+
+ .. versionchanged:: 2.2.2
+ The *strict* flag was added.
+
+ .. versionchanged:: 2.4
+ The *strict* flag was deprecated.
+
+The other public :class:`Parser` methods are:
+
+
+.. method:: Parser.parse(fp[, headersonly])
+
+ Read all the data from the file-like object *fp*, parse the resulting text, and
+ return the root message object. *fp* must support both the :meth:`readline` and
+ the :meth:`read` methods on file-like objects.
+
+ The text contained in *fp* must be formatted as a block of :rfc:`2822` style
+ headers and header continuation lines, optionally preceded by a envelope
+ header. The header block is terminated either by the end of the data or by a
+ blank line. Following the header block is the body of the message (which may
+ contain MIME-encoded subparts).
+
+ Optional *headersonly* is as with the :meth:`parse` method.
+
+ .. versionchanged:: 2.2.2
+ The *headersonly* flag was added.
+
+
+.. method:: Parser.parsestr(text[, headersonly])
+
+ Similar to the :meth:`parse` method, except it takes a string object instead of
+ a file-like object. Calling this method on a string is exactly equivalent to
+ wrapping *text* in a :class:`StringIO` instance first and calling :meth:`parse`.
+
+ Optional *headersonly* is a flag specifying whether to stop parsing after
+ reading the headers or not. The default is ``False``, meaning it parses the
+ entire contents of the file.
+
+ .. versionchanged:: 2.2.2
+ The *headersonly* flag was added.
+
+Since creating a message object structure from a string or a file object is such
+a common task, two functions are provided as a convenience. They are available
+in the top-level :mod:`email` package namespace.
+
+
+.. function:: message_from_string(s[, _class[, strict]])
+
+ Return a message object structure from a string. This is exactly equivalent to
+ ``Parser().parsestr(s)``. Optional *_class* and *strict* are interpreted as
+ with the :class:`Parser` class constructor.
+
+ .. versionchanged:: 2.2.2
+ The *strict* flag was added.
+
+
+.. function:: message_from_file(fp[, _class[, strict]])
+
+ Return a message object structure tree from an open file object. This is
+ exactly equivalent to ``Parser().parse(fp)``. Optional *_class* and *strict*
+ are interpreted as with the :class:`Parser` class constructor.
+
+ .. versionchanged:: 2.2.2
+ The *strict* flag was added.
+
+Here's an example of how you might use this at an interactive Python prompt::
+
+ >>> import email
+ >>> msg = email.message_from_string(myString)
+
+
+Additional notes
+^^^^^^^^^^^^^^^^
+
+Here are some notes on the parsing semantics:
+
+* Most non-\ :mimetype:`multipart` type messages are parsed as a single message
+ object with a string payload. These objects will return ``False`` for
+ :meth:`is_multipart`. Their :meth:`get_payload` method will return a string
+ object.
+
+* All :mimetype:`multipart` type messages will be parsed as a container message
+ object with a list of sub-message objects for their payload. The outer
+ container message will return ``True`` for :meth:`is_multipart` and their
+ :meth:`get_payload` method will return the list of :class:`Message` subparts.
+
+* Most messages with a content type of :mimetype:`message/\*` (e.g.
+ :mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be
+ parsed as container object containing a list payload of length 1. Their
+ :meth:`is_multipart` method will return ``True``. The single element in the
+ list payload will be a sub-message object.
+
+* Some non-standards compliant messages may not be internally consistent about
+ their :mimetype:`multipart`\ -edness. Such messages may have a
+ :mailheader:`Content-Type` header of type :mimetype:`multipart`, but their
+ :meth:`is_multipart` method may return ``False``. If such messages were parsed
+ with the :class:`FeedParser`, they will have an instance of the
+ :class:`MultipartInvariantViolationDefect` class in their *defects* attribute
+ list. See :mod:`email.errors` for details.
+
+.. rubric:: Footnotes
+
+.. [#] As of email package version 3.0, introduced in Python 2.4, the classic
+ :class:`Parser` was re-implemented in terms of the :class:`FeedParser`, so the
+ semantics and results are identical between the two parsers.
+
--- /dev/null
+.. % Copyright (C) 2001-2007 Python Software Foundation
+.. % Author: barry@python.org (Barry Warsaw)
+
+
+:mod:`email` --- An email and MIME handling package
+===================================================
+
+.. module:: email
+ :synopsis: Package supporting the parsing, manipulating, and generating email messages,
+ including MIME documents.
+.. moduleauthor:: Barry A. Warsaw <barry@python.org>
+.. sectionauthor:: Barry A. Warsaw <barry@python.org>
+
+
+.. versionadded:: 2.2
+
+The :mod:`email` package is a library for managing email messages, including
+MIME and other :rfc:`2822`\ -based message documents. It subsumes most of the
+functionality in several older standard modules such as :mod:`rfc822`,
+:mod:`mimetools`, :mod:`multifile`, and other non-standard packages such as
+:mod:`mimecntl`. It is specifically *not* designed to do any sending of email
+messages to SMTP (:rfc:`2821`), NNTP, or other servers; those are functions of
+modules such as :mod:`smtplib` and :mod:`nntplib`. The :mod:`email` package
+attempts to be as RFC-compliant as possible, supporting in addition to
+:rfc:`2822`, such MIME-related RFCs as :rfc:`2045`, :rfc:`2046`, :rfc:`2047`,
+and :rfc:`2231`.
+
+The primary distinguishing feature of the :mod:`email` package is that it splits
+the parsing and generating of email messages from the internal *object model*
+representation of email. Applications using the :mod:`email` package deal
+primarily with objects; you can add sub-objects to messages, remove sub-objects
+from messages, completely re-arrange the contents, etc. There is a separate
+parser and a separate generator which handles the transformation from flat text
+to the object model, and then back to flat text again. There are also handy
+subclasses for some common MIME object types, and a few miscellaneous utilities
+that help with such common tasks as extracting and parsing message field values,
+creating RFC-compliant dates, etc.
+
+The following sections describe the functionality of the :mod:`email` package.
+The ordering follows a progression that should be common in applications: an
+email message is read as flat text from a file or other source, the text is
+parsed to produce the object structure of the email message, this structure is
+manipulated, and finally, the object tree is rendered back into flat text.
+
+It is perfectly feasible to create the object structure out of whole cloth ---
+i.e. completely from scratch. From there, a similar progression can be taken as
+above.
+
+Also included are detailed specifications of all the classes and modules that
+the :mod:`email` package provides, the exception classes you might encounter
+while using the :mod:`email` package, some auxiliary utilities, and a few
+examples. For users of the older :mod:`mimelib` package, or previous versions
+of the :mod:`email` package, a section on differences and porting is provided.
+
+Contents of the :mod:`email` package documentation:
+
+.. toctree::
+
+ email.message.rst
+ email.parser.rst
+ email.generator.rst
+ email.mime.rst
+ email.header.rst
+ email.charset.rst
+ email.encoders.rst
+ email.errors.rst
+ email.util.rst
+ email.iterators.rst
+ email-examples.rst
+
+
+.. seealso::
+
+ Module :mod:`smtplib`
+ SMTP protocol client
+
+ Module :mod:`nntplib`
+ NNTP protocol client
+
+
+.. _email-pkg-history:
+
+Package History
+---------------
+
+This table describes the release history of the email package, corresponding to
+the version of Python that the package was released with. For purposes of this
+document, when you see a note about change or added versions, these refer to the
+Python version the change was made in, *not* the email package version. This
+table also describes the Python compatibility of each version of the package.
+
++---------------+------------------------------+-----------------------+
+| email version | distributed with | compatible with |
++===============+==============================+=======================+
+| :const:`1.x` | Python 2.2.0 to Python 2.2.1 | *no longer supported* |
++---------------+------------------------------+-----------------------+
+| :const:`2.5` | Python 2.2.2+ and Python 2.3 | Python 2.1 to 2.5 |
++---------------+------------------------------+-----------------------+
+| :const:`3.0` | Python 2.4 | Python 2.3 to 2.5 |
++---------------+------------------------------+-----------------------+
+| :const:`4.0` | Python 2.5 | Python 2.3 to 2.5 |
++---------------+------------------------------+-----------------------+
+
+Here are the major differences between :mod:`email` version 4 and version 3:
+
+* All modules have been renamed according to :pep:`8` standards. For example,
+ the version 3 module :mod:`email.Message` was renamed to :mod:`email.message` in
+ version 4.
+
+* A new subpackage :mod:`email.mime` was added and all the version 3
+ :mod:`email.MIME\*` modules were renamed and situated into the :mod:`email.mime`
+ subpackage. For example, the version 3 module :mod:`email.MIMEText` was renamed
+ to :mod:`email.mime.text`.
+
+ *Note that the version 3 names will continue to work until Python 2.6*.
+
+* The :mod:`email.mime.application` module was added, which contains the
+ :class:`MIMEApplication` class.
+
+* Methods that were deprecated in version 3 have been removed. These include
+ :meth:`Generator.__call__`, :meth:`Message.get_type`,
+ :meth:`Message.get_main_type`, :meth:`Message.get_subtype`.
+
+* Fixes have been added for :rfc:`2231` support which can change some of the
+ return types for :func:`Message.get_param` and friends. Under some
+ circumstances, values which used to return a 3-tuple now return simple strings
+ (specifically, if all extended parameter segments were unencoded, there is no
+ language and charset designation expected, so the return type is now a simple
+ string). Also, %-decoding used to be done for both encoded and unencoded
+ segments; this decoding is now done only for encoded segments.
+
+Here are the major differences between :mod:`email` version 3 and version 2:
+
+* The :class:`FeedParser` class was introduced, and the :class:`Parser` class
+ was implemented in terms of the :class:`FeedParser`. All parsing therefore is
+ non-strict, and parsing will make a best effort never to raise an exception.
+ Problems found while parsing messages are stored in the message's *defect*
+ attribute.
+
+* All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2
+ have been removed. These include the *_encoder* argument to the
+ :class:`MIMEText` constructor, the :meth:`Message.add_payload` method, the
+ :func:`Utils.dump_address_pair` function, and the functions :func:`Utils.decode`
+ and :func:`Utils.encode`.
+
+* New :exc:`DeprecationWarning`\ s have been added to:
+ :meth:`Generator.__call__`, :meth:`Message.get_type`,
+ :meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict*
+ argument to the :class:`Parser` class. These are expected to be removed in
+ future versions.
+
+* Support for Pythons earlier than 2.3 has been removed.
+
+Here are the differences between :mod:`email` version 2 and version 1:
+
+* The :mod:`email.Header` and :mod:`email.Charset` modules have been added.
+
+* The pickle format for :class:`Message` instances has changed. Since this was
+ never (and still isn't) formally defined, this isn't considered a backward
+ incompatibility. However if your application pickles and unpickles
+ :class:`Message` instances, be aware that in :mod:`email` version 2,
+ :class:`Message` instances now have private variables *_charset* and
+ *_default_type*.
+
+* Several methods in the :class:`Message` class have been deprecated, or their
+ signatures changed. Also, many new methods have been added. See the
+ documentation for the :class:`Message` class for details. The changes should be
+ completely backward compatible.
+
+* The object structure has changed in the face of :mimetype:`message/rfc822`
+ content types. In :mod:`email` version 1, such a type would be represented by a
+ scalar payload, i.e. the container message's :meth:`is_multipart` returned
+ false, :meth:`get_payload` was not a list object, but a single :class:`Message`
+ instance.
+
+ This structure was inconsistent with the rest of the package, so the object
+ representation for :mimetype:`message/rfc822` content types was changed. In
+ :mod:`email` version 2, the container *does* return ``True`` from
+ :meth:`is_multipart`, and :meth:`get_payload` returns a list containing a single
+ :class:`Message` item.
+
+ Note that this is one place that backward compatibility could not be completely
+ maintained. However, if you're already testing the return type of
+ :meth:`get_payload`, you should be fine. You just need to make sure your code
+ doesn't do a :meth:`set_payload` with a :class:`Message` instance on a container
+ with a content type of :mimetype:`message/rfc822`.
+
+* The :class:`Parser` constructor's *strict* argument was added, and its
+ :meth:`parse` and :meth:`parsestr` methods grew a *headersonly* argument. The
+ *strict* flag was also added to functions :func:`email.message_from_file` and
+ :func:`email.message_from_string`.
+
+* :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten`
+ instead. The :class:`Generator` class has also grown the :meth:`clone` method.
+
+* The :class:`DecodedGenerator` class in the :mod:`email.Generator` module was
+ added.
+
+* The intermediate base classes :class:`MIMENonMultipart` and
+ :class:`MIMEMultipart` have been added, and interposed in the class hierarchy
+ for most of the other MIME-related derived classes.
+
+* The *_encoder* argument to the :class:`MIMEText` constructor has been
+ deprecated. Encoding now happens implicitly based on the *_charset* argument.
+
+* The following functions in the :mod:`email.Utils` module have been deprecated:
+ :func:`dump_address_pairs`, :func:`decode`, and :func:`encode`. The following
+ functions have been added to the module: :func:`make_msgid`,
+ :func:`decode_rfc2231`, :func:`encode_rfc2231`, and :func:`decode_params`.
+
+* The non-public function :func:`email.Iterators._structure` was added.
+
+
+Differences from :mod:`mimelib`
+-------------------------------
+
+The :mod:`email` package was originally prototyped as a separate library called
+`mimelib <http://mimelib.sf.net/>`_. Changes have been made so that method names
+are more consistent, and some methods or modules have either been added or
+removed. The semantics of some of the methods have also changed. For the most
+part, any functionality available in :mod:`mimelib` is still available in the
+:mod:`email` package, albeit often in a different way. Backward compatibility
+between the :mod:`mimelib` package and the :mod:`email` package was not a
+priority.
+
+Here is a brief description of the differences between the :mod:`mimelib` and
+the :mod:`email` packages, along with hints on how to port your applications.
+
+Of course, the most visible difference between the two packages is that the
+package name has been changed to :mod:`email`. In addition, the top-level
+package has the following differences:
+
+* :func:`messageFromString` has been renamed to :func:`message_from_string`.
+
+* :func:`messageFromFile` has been renamed to :func:`message_from_file`.
+
+The :class:`Message` class has the following differences:
+
+* The method :meth:`asString` was renamed to :meth:`as_string`.
+
+* The method :meth:`ismultipart` was renamed to :meth:`is_multipart`.
+
+* The :meth:`get_payload` method has grown a *decode* optional argument.
+
+* The method :meth:`getall` was renamed to :meth:`get_all`.
+
+* The method :meth:`addheader` was renamed to :meth:`add_header`.
+
+* The method :meth:`gettype` was renamed to :meth:`get_type`.
+
+* The method :meth:`getmaintype` was renamed to :meth:`get_main_type`.
+
+* The method :meth:`getsubtype` was renamed to :meth:`get_subtype`.
+
+* The method :meth:`getparams` was renamed to :meth:`get_params`. Also, whereas
+ :meth:`getparams` returned a list of strings, :meth:`get_params` returns a list
+ of 2-tuples, effectively the key/value pairs of the parameters, split on the
+ ``'='`` sign.
+
+* The method :meth:`getparam` was renamed to :meth:`get_param`.
+
+* The method :meth:`getcharsets` was renamed to :meth:`get_charsets`.
+
+* The method :meth:`getfilename` was renamed to :meth:`get_filename`.
+
+* The method :meth:`getboundary` was renamed to :meth:`get_boundary`.
+
+* The method :meth:`setboundary` was renamed to :meth:`set_boundary`.
+
+* The method :meth:`getdecodedpayload` was removed. To get similar
+ functionality, pass the value 1 to the *decode* flag of the get_payload()
+ method.
+
+* The method :meth:`getpayloadastext` was removed. Similar functionality is
+ supported by the :class:`DecodedGenerator` class in the :mod:`email.generator`
+ module.
+
+* The method :meth:`getbodyastext` was removed. You can get similar
+ functionality by creating an iterator with :func:`typed_subpart_iterator` in the
+ :mod:`email.iterators` module.
+
+The :class:`Parser` class has no differences in its public interface. It does
+have some additional smarts to recognize :mimetype:`message/delivery-status`
+type messages, which it represents as a :class:`Message` instance containing
+separate :class:`Message` subparts for each header block in the delivery status
+notification [#]_.
+
+The :class:`Generator` class has no differences in its public interface. There
+is a new class in the :mod:`email.generator` module though, called
+:class:`DecodedGenerator` which provides most of the functionality previously
+available in the :meth:`Message.getpayloadastext` method.
+
+The following modules and classes have been changed:
+
+* The :class:`MIMEBase` class constructor arguments *_major* and *_minor* have
+ changed to *_maintype* and *_subtype* respectively.
+
+* The ``Image`` class/module has been renamed to ``MIMEImage``. The *_minor*
+ argument has been renamed to *_subtype*.
+
+* The ``Text`` class/module has been renamed to ``MIMEText``. The *_minor*
+ argument has been renamed to *_subtype*.
+
+* The ``MessageRFC822`` class/module has been renamed to ``MIMEMessage``. Note
+ that an earlier version of :mod:`mimelib` called this class/module ``RFC822``,
+ but that clashed with the Python standard library module :mod:`rfc822` on some
+ case-insensitive file systems.
+
+ Also, the :class:`MIMEMessage` class now represents any kind of MIME message
+ with main type :mimetype:`message`. It takes an optional argument *_subtype*
+ which is used to set the MIME subtype. *_subtype* defaults to
+ :mimetype:`rfc822`.
+
+:mod:`mimelib` provided some utility functions in its :mod:`address` and
+:mod:`date` modules. All of these functions have been moved to the
+:mod:`email.utils` module.
+
+The ``MsgReader`` class/module has been removed. Its functionality is most
+closely supported in the :func:`body_line_iterator` function in the
+:mod:`email.iterators` module.
+
+.. rubric:: Footnotes
+
+.. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`.
--- /dev/null
+:mod:`email`: Miscellaneous utilities
+-------------------------------------
+
+.. module:: email.utils
+ :synopsis: Miscellaneous email package utilities.
+
+
+There are several useful utilities provided in the :mod:`email.utils` module:
+
+
+.. function:: quote(str)
+
+ Return a new string with backslashes in *str* replaced by two backslashes, and
+ double quotes replaced by backslash-double quote.
+
+
+.. function:: unquote(str)
+
+ Return a new string which is an *unquoted* version of *str*. If *str* ends and
+ begins with double quotes, they are stripped off. Likewise if *str* ends and
+ begins with angle brackets, they are stripped off.
+
+
+.. function:: parseaddr(address)
+
+ Parse address -- which should be the value of some address-containing field such
+ as :mailheader:`To` or :mailheader:`Cc` -- into its constituent *realname* and
+ *email address* parts. Returns a tuple of that information, unless the parse
+ fails, in which case a 2-tuple of ``('', '')`` is returned.
+
+
+.. function:: formataddr(pair)
+
+ The inverse of :meth:`parseaddr`, this takes a 2-tuple of the form ``(realname,
+ email_address)`` and returns the string value suitable for a :mailheader:`To` or
+ :mailheader:`Cc` header. If the first element of *pair* is false, then the
+ second element is returned unmodified.
+
+
+.. function:: getaddresses(fieldvalues)
+
+ This method returns a list of 2-tuples of the form returned by ``parseaddr()``.
+ *fieldvalues* is a sequence of header field values as might be returned by
+ :meth:`Message.get_all`. Here's a simple example that gets all the recipients
+ of a message::
+
+ from email.utils import getaddresses
+
+ tos = msg.get_all('to', [])
+ ccs = msg.get_all('cc', [])
+ resent_tos = msg.get_all('resent-to', [])
+ resent_ccs = msg.get_all('resent-cc', [])
+ all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
+
+
+.. function:: parsedate(date)
+
+ Attempts to parse a date according to the rules in :rfc:`2822`. however, some
+ mailers don't follow that format as specified, so :func:`parsedate` tries to
+ guess correctly in such cases. *date* is a string containing an :rfc:`2822`
+ date, such as ``"Mon, 20 Nov 1995 19:12:08 -0500"``. If it succeeds in parsing
+ the date, :func:`parsedate` returns a 9-tuple that can be passed directly to
+ :func:`time.mktime`; otherwise ``None`` will be returned. Note that indexes 6,
+ 7, and 8 of the result tuple are not usable.
+
+
+.. function:: parsedate_tz(date)
+
+ Performs the same function as :func:`parsedate`, but returns either ``None`` or
+ a 10-tuple; the first 9 elements make up a tuple that can be passed directly to
+ :func:`time.mktime`, and the tenth is the offset of the date's timezone from UTC
+ (which is the official term for Greenwich Mean Time) [#]_. If the input string
+ has no timezone, the last element of the tuple returned is ``None``. Note that
+ indexes 6, 7, and 8 of the result tuple are not usable.
+
+
+.. function:: mktime_tz(tuple)
+
+ Turn a 10-tuple as returned by :func:`parsedate_tz` into a UTC timestamp. It
+ the timezone item in the tuple is ``None``, assume local time. Minor
+ deficiency: :func:`mktime_tz` interprets the first 8 elements of *tuple* as a
+ local time and then compensates for the timezone difference. This may yield a
+ slight error around changes in daylight savings time, though not worth worrying
+ about for common use.
+
+
+.. function:: formatdate([timeval[, localtime][, usegmt]])
+
+ Returns a date string as per :rfc:`2822`, e.g.::
+
+ Fri, 09 Nov 2001 01:08:47 -0000
+
+ Optional *timeval* if given is a floating point time value as accepted by
+ :func:`time.gmtime` and :func:`time.localtime`, otherwise the current time is
+ used.
+
+ Optional *localtime* is a flag that when ``True``, interprets *timeval*, and
+ returns a date relative to the local timezone instead of UTC, properly taking
+ daylight savings time into account. The default is ``False`` meaning UTC is
+ used.
+
+ Optional *usegmt* is a flag that when ``True``, outputs a date string with the
+ timezone as an ascii string ``GMT``, rather than a numeric ``-0000``. This is
+ needed for some protocols (such as HTTP). This only applies when *localtime* is
+ ``False``.
+
+ .. versionadded:: 2.4
+
+
+.. function:: make_msgid([idstring])
+
+ Returns a string suitable for an :rfc:`2822`\ -compliant
+ :mailheader:`Message-ID` header. Optional *idstring* if given, is a string used
+ to strengthen the uniqueness of the message id.
+
+
+.. function:: decode_rfc2231(s)
+
+ Decode the string *s* according to :rfc:`2231`.
+
+
+.. function:: encode_rfc2231(s[, charset[, language]])
+
+ Encode the string *s* according to :rfc:`2231`. Optional *charset* and
+ *language*, if given is the character set name and language name to use. If
+ neither is given, *s* is returned as-is. If *charset* is given but *language*
+ is not, the string is encoded using the empty string for *language*.
+
+
+.. function:: collapse_rfc2231_value(value[, errors[, fallback_charset]])
+
+ When a header parameter is encoded in :rfc:`2231` format,
+ :meth:`Message.get_param` may return a 3-tuple containing the character set,
+ language, and value. :func:`collapse_rfc2231_value` turns this into a unicode
+ string. Optional *errors* is passed to the *errors* argument of the built-in
+ :func:`unicode` function; it defaults to ``replace``. Optional
+ *fallback_charset* specifies the character set to use if the one in the
+ :rfc:`2231` header is not known by Python; it defaults to ``us-ascii``.
+
+ For convenience, if the *value* passed to :func:`collapse_rfc2231_value` is not
+ a tuple, it should be a string and it is returned unquoted.
+
+
+.. function:: decode_params(params)
+
+ Decode parameters list according to :rfc:`2231`. *params* is a sequence of
+ 2-tuples containing elements of the form ``(content-type, string-value)``.
+
+.. versionchanged:: 2.4
+ The :func:`dump_address_pair` function has been removed; use :func:`formataddr`
+ instead.
+
+.. versionchanged:: 2.4
+ The :func:`decode` function has been removed; use the
+ :meth:`Header.decode_header` method instead.
+
+.. versionchanged:: 2.4
+ The :func:`encode` function has been removed; use the :meth:`Header.encode`
+ method instead.
+
+.. rubric:: Footnotes
+
+.. [#] Note that the sign of the timezone offset is the opposite of the sign of the
+ ``time.timezone`` variable for the same timezone; the latter variable follows
+ the POSIX standard while this module follows :rfc:`2822`.
+
--- /dev/null
+
+:mod:`errno` --- Standard errno system symbols
+==============================================
+
+.. module:: errno
+ :synopsis: Standard errno system symbols.
+
+
+This module makes available standard ``errno`` system symbols. The value of each
+symbol is the corresponding integer value. The names and descriptions are
+borrowed from :file:`linux/include/errno.h`, which should be pretty
+all-inclusive.
+
+
+.. data:: errorcode
+
+ Dictionary providing a mapping from the errno value to the string name in the
+ underlying system. For instance, ``errno.errorcode[errno.EPERM]`` maps to
+ ``'EPERM'``.
+
+To translate a numeric error code to an error message, use :func:`os.strerror`.
+
+Of the following list, symbols that are not used on the current platform are not
+defined by the module. The specific list of defined symbols is available as
+``errno.errorcode.keys()``. Symbols available can include:
+
+
+.. data:: EPERM
+
+ Operation not permitted
+
+
+.. data:: ENOENT
+
+ No such file or directory
+
+
+.. data:: ESRCH
+
+ No such process
+
+
+.. data:: EINTR
+
+ Interrupted system call
+
+
+.. data:: EIO
+
+ I/O error
+
+
+.. data:: ENXIO
+
+ No such device or address
+
+
+.. data:: E2BIG
+
+ Arg list too long
+
+
+.. data:: ENOEXEC
+
+ Exec format error
+
+
+.. data:: EBADF
+
+ Bad file number
+
+
+.. data:: ECHILD
+
+ No child processes
+
+
+.. data:: EAGAIN
+
+ Try again
+
+
+.. data:: ENOMEM
+
+ Out of memory
+
+
+.. data:: EACCES
+
+ Permission denied
+
+
+.. data:: EFAULT
+
+ Bad address
+
+
+.. data:: ENOTBLK
+
+ Block device required
+
+
+.. data:: EBUSY
+
+ Device or resource busy
+
+
+.. data:: EEXIST
+
+ File exists
+
+
+.. data:: EXDEV
+
+ Cross-device link
+
+
+.. data:: ENODEV
+
+ No such device
+
+
+.. data:: ENOTDIR
+
+ Not a directory
+
+
+.. data:: EISDIR
+
+ Is a directory
+
+
+.. data:: EINVAL
+
+ Invalid argument
+
+
+.. data:: ENFILE
+
+ File table overflow
+
+
+.. data:: EMFILE
+
+ Too many open files
+
+
+.. data:: ENOTTY
+
+ Not a typewriter
+
+
+.. data:: ETXTBSY
+
+ Text file busy
+
+
+.. data:: EFBIG
+
+ File too large
+
+
+.. data:: ENOSPC
+
+ No space left on device
+
+
+.. data:: ESPIPE
+
+ Illegal seek
+
+
+.. data:: EROFS
+
+ Read-only file system
+
+
+.. data:: EMLINK
+
+ Too many links
+
+
+.. data:: EPIPE
+
+ Broken pipe
+
+
+.. data:: EDOM
+
+ Math argument out of domain of func
+
+
+.. data:: ERANGE
+
+ Math result not representable
+
+
+.. data:: EDEADLK
+
+ Resource deadlock would occur
+
+
+.. data:: ENAMETOOLONG
+
+ File name too long
+
+
+.. data:: ENOLCK
+
+ No record locks available
+
+
+.. data:: ENOSYS
+
+ Function not implemented
+
+
+.. data:: ENOTEMPTY
+
+ Directory not empty
+
+
+.. data:: ELOOP
+
+ Too many symbolic links encountered
+
+
+.. data:: EWOULDBLOCK
+
+ Operation would block
+
+
+.. data:: ENOMSG
+
+ No message of desired type
+
+
+.. data:: EIDRM
+
+ Identifier removed
+
+
+.. data:: ECHRNG
+
+ Channel number out of range
+
+
+.. data:: EL2NSYNC
+
+ Level 2 not synchronized
+
+
+.. data:: EL3HLT
+
+ Level 3 halted
+
+
+.. data:: EL3RST
+
+ Level 3 reset
+
+
+.. data:: ELNRNG
+
+ Link number out of range
+
+
+.. data:: EUNATCH
+
+ Protocol driver not attached
+
+
+.. data:: ENOCSI
+
+ No CSI structure available
+
+
+.. data:: EL2HLT
+
+ Level 2 halted
+
+
+.. data:: EBADE
+
+ Invalid exchange
+
+
+.. data:: EBADR
+
+ Invalid request descriptor
+
+
+.. data:: EXFULL
+
+ Exchange full
+
+
+.. data:: ENOANO
+
+ No anode
+
+
+.. data:: EBADRQC
+
+ Invalid request code
+
+
+.. data:: EBADSLT
+
+ Invalid slot
+
+
+.. data:: EDEADLOCK
+
+ File locking deadlock error
+
+
+.. data:: EBFONT
+
+ Bad font file format
+
+
+.. data:: ENOSTR
+
+ Device not a stream
+
+
+.. data:: ENODATA
+
+ No data available
+
+
+.. data:: ETIME
+
+ Timer expired
+
+
+.. data:: ENOSR
+
+ Out of streams resources
+
+
+.. data:: ENONET
+
+ Machine is not on the network
+
+
+.. data:: ENOPKG
+
+ Package not installed
+
+
+.. data:: EREMOTE
+
+ Object is remote
+
+
+.. data:: ENOLINK
+
+ Link has been severed
+
+
+.. data:: EADV
+
+ Advertise error
+
+
+.. data:: ESRMNT
+
+ Srmount error
+
+
+.. data:: ECOMM
+
+ Communication error on send
+
+
+.. data:: EPROTO
+
+ Protocol error
+
+
+.. data:: EMULTIHOP
+
+ Multihop attempted
+
+
+.. data:: EDOTDOT
+
+ RFS specific error
+
+
+.. data:: EBADMSG
+
+ Not a data message
+
+
+.. data:: EOVERFLOW
+
+ Value too large for defined data type
+
+
+.. data:: ENOTUNIQ
+
+ Name not unique on network
+
+
+.. data:: EBADFD
+
+ File descriptor in bad state
+
+
+.. data:: EREMCHG
+
+ Remote address changed
+
+
+.. data:: ELIBACC
+
+ Can not access a needed shared library
+
+
+.. data:: ELIBBAD
+
+ Accessing a corrupted shared library
+
+
+.. data:: ELIBSCN
+
+ .lib section in a.out corrupted
+
+
+.. data:: ELIBMAX
+
+ Attempting to link in too many shared libraries
+
+
+.. data:: ELIBEXEC
+
+ Cannot exec a shared library directly
+
+
+.. data:: EILSEQ
+
+ Illegal byte sequence
+
+
+.. data:: ERESTART
+
+ Interrupted system call should be restarted
+
+
+.. data:: ESTRPIPE
+
+ Streams pipe error
+
+
+.. data:: EUSERS
+
+ Too many users
+
+
+.. data:: ENOTSOCK
+
+ Socket operation on non-socket
+
+
+.. data:: EDESTADDRREQ
+
+ Destination address required
+
+
+.. data:: EMSGSIZE
+
+ Message too long
+
+
+.. data:: EPROTOTYPE
+
+ Protocol wrong type for socket
+
+
+.. data:: ENOPROTOOPT
+
+ Protocol not available
+
+
+.. data:: EPROTONOSUPPORT
+
+ Protocol not supported
+
+
+.. data:: ESOCKTNOSUPPORT
+
+ Socket type not supported
+
+
+.. data:: EOPNOTSUPP
+
+ Operation not supported on transport endpoint
+
+
+.. data:: EPFNOSUPPORT
+
+ Protocol family not supported
+
+
+.. data:: EAFNOSUPPORT
+
+ Address family not supported by protocol
+
+
+.. data:: EADDRINUSE
+
+ Address already in use
+
+
+.. data:: EADDRNOTAVAIL
+
+ Cannot assign requested address
+
+
+.. data:: ENETDOWN
+
+ Network is down
+
+
+.. data:: ENETUNREACH
+
+ Network is unreachable
+
+
+.. data:: ENETRESET
+
+ Network dropped connection because of reset
+
+
+.. data:: ECONNABORTED
+
+ Software caused connection abort
+
+
+.. data:: ECONNRESET
+
+ Connection reset by peer
+
+
+.. data:: ENOBUFS
+
+ No buffer space available
+
+
+.. data:: EISCONN
+
+ Transport endpoint is already connected
+
+
+.. data:: ENOTCONN
+
+ Transport endpoint is not connected
+
+
+.. data:: ESHUTDOWN
+
+ Cannot send after transport endpoint shutdown
+
+
+.. data:: ETOOMANYREFS
+
+ Too many references: cannot splice
+
+
+.. data:: ETIMEDOUT
+
+ Connection timed out
+
+
+.. data:: ECONNREFUSED
+
+ Connection refused
+
+
+.. data:: EHOSTDOWN
+
+ Host is down
+
+
+.. data:: EHOSTUNREACH
+
+ No route to host
+
+
+.. data:: EALREADY
+
+ Operation already in progress
+
+
+.. data:: EINPROGRESS
+
+ Operation now in progress
+
+
+.. data:: ESTALE
+
+ Stale NFS file handle
+
+
+.. data:: EUCLEAN
+
+ Structure needs cleaning
+
+
+.. data:: ENOTNAM
+
+ Not a XENIX named type file
+
+
+.. data:: ENAVAIL
+
+ No XENIX semaphores available
+
+
+.. data:: EISNAM
+
+ Is a named type file
+
+
+.. data:: EREMOTEIO
+
+ Remote I/O error
+
+
+.. data:: EDQUOT
+
+ Quota exceeded
+
--- /dev/null
+.. _bltin-exceptions:
+
+Built-in Exceptions
+===================
+
+.. module:: exceptions
+ :synopsis: Standard exception classes.
+
+
+Exceptions should be class objects. The exceptions are defined in the module
+:mod:`exceptions`. This module never needs to be imported explicitly: the
+exceptions are provided in the built-in namespace as well as the
+:mod:`exceptions` module.
+
+.. index::
+ statement: try
+ statement: except
+
+For class exceptions, in a :keyword:`try` statement with an :keyword:`except`
+clause that mentions a particular class, that clause also handles any exception
+classes derived from that class (but not exception classes from which *it* is
+derived). Two exception classes that are not related via subclassing are never
+equivalent, even if they have the same name.
+
+.. index:: statement: raise
+
+The built-in exceptions listed below can be generated by the interpreter or
+built-in functions. Except where mentioned, they have an "associated value"
+indicating the detailed cause of the error. This may be a string or a tuple
+containing several items of information (e.g., an error code and a string
+explaining the code). The associated value is the second argument to the
+:keyword:`raise` statement. If the exception class is derived from the standard
+root class :exc:`BaseException`, the associated value is present as the
+exception instance's :attr:`args` attribute.
+
+User code can raise built-in exceptions. This can be used to test an exception
+handler or to report an error condition "just like" the situation in which the
+interpreter raises the same exception; but beware that there is nothing to
+prevent user code from raising an inappropriate error.
+
+The built-in exception classes can be sub-classed to define new exceptions;
+programmers are encouraged to at least derive new exceptions from the
+:exc:`Exception` class and not :exc:`BaseException`. More information on
+defining exceptions is available in the Python Tutorial under
+:ref:`tut-userexceptions`.
+
+The following exceptions are only used as base classes for other exceptions.
+
+
+.. exception:: BaseException
+
+ The base class for all built-in exceptions. It is not meant to be directly
+ inherited by user-defined classes (for that use :exc:`Exception`). If
+ :func:`str` or :func:`unicode` is called on an instance of this class, the
+ representation of the argument(s) to the instance are returned or the emptry
+ string when there were no arguments. All arguments are stored in :attr:`args`
+ as a tuple.
+
+ .. versionadded:: 2.5
+
+
+.. exception:: Exception
+
+ All built-in, non-system-exiting exceptions are derived from this class. All
+ user-defined exceptions should also be derived from this class.
+
+ .. versionchanged:: 2.5
+ Changed to inherit from :exc:`BaseException`.
+
+
+.. exception:: StandardError
+
+ The base class for all built-in exceptions except :exc:`StopIteration`,
+ :exc:`GeneratorExit`, :exc:`KeyboardInterrupt` and :exc:`SystemExit`.
+ :exc:`StandardError` itself is derived from :exc:`Exception`.
+
+
+.. exception:: ArithmeticError
+
+ The base class for those built-in exceptions that are raised for various
+ arithmetic errors: :exc:`OverflowError`, :exc:`ZeroDivisionError`,
+ :exc:`FloatingPointError`.
+
+
+.. exception:: LookupError
+
+ The base class for the exceptions that are raised when a key or index used on a
+ mapping or sequence is invalid: :exc:`IndexError`, :exc:`KeyError`. This can be
+ raised directly by :func:`sys.setdefaultencoding`.
+
+
+.. exception:: EnvironmentError
+
+ The base class for exceptions that can occur outside the Python system:
+ :exc:`IOError`, :exc:`OSError`. When exceptions of this type are created with a
+ 2-tuple, the first item is available on the instance's :attr:`errno` attribute
+ (it is assumed to be an error number), and the second item is available on the
+ :attr:`strerror` attribute (it is usually the associated error message). The
+ tuple itself is also available on the :attr:`args` attribute.
+
+ .. versionadded:: 1.5.2
+
+ When an :exc:`EnvironmentError` exception is instantiated with a 3-tuple, the
+ first two items are available as above, while the third item is available on the
+ :attr:`filename` attribute. However, for backwards compatibility, the
+ :attr:`args` attribute contains only a 2-tuple of the first two constructor
+ arguments.
+
+ The :attr:`filename` attribute is ``None`` when this exception is created with
+ other than 3 arguments. The :attr:`errno` and :attr:`strerror` attributes are
+ also ``None`` when the instance was created with other than 2 or 3 arguments.
+ In this last case, :attr:`args` contains the verbatim constructor arguments as a
+ tuple.
+
+The following exceptions are the exceptions that are actually raised.
+
+
+.. exception:: AssertionError
+
+ .. index:: statement: assert
+
+ Raised when an :keyword:`assert` statement fails.
+
+
+.. exception:: AttributeError
+
+ Raised when an attribute reference or assignment fails. (When an object does
+ not support attribute references or attribute assignments at all,
+ :exc:`TypeError` is raised.)
+
+ .. % xref to attribute reference?
+
+
+.. exception:: EOFError
+
+ Raised when one of the built-in functions (:func:`input` or :func:`raw_input`)
+ hits an end-of-file condition (EOF) without reading any data. (N.B.: the
+ :meth:`read` and :meth:`readline` methods of file objects return an empty string
+ when they hit EOF.)
+
+ .. % XXXJH xrefs here
+ .. % XXXJH xrefs here
+
+
+.. exception:: FloatingPointError
+
+ Raised when a floating point operation fails. This exception is always defined,
+ but can only be raised when Python is configured with the
+ :option:`--with-fpectl` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is
+ defined in the :file:`pyconfig.h` file.
+
+
+.. exception:: GeneratorExit
+
+ Raise when a generator's :meth:`close` method is called. It directly inherits
+ from :exc:`Exception` instead of :exc:`StandardError` since it is technically
+ not an error.
+
+ .. versionadded:: 2.5
+
+
+.. exception:: IOError
+
+ Raised when an I/O operation (such as a :keyword:`print` statement, the built-in
+ :func:`open` function or a method of a file object) fails for an I/O-related
+ reason, e.g., "file not found" or "disk full".
+
+ .. % XXXJH xrefs here
+
+ This class is derived from :exc:`EnvironmentError`. See the discussion above
+ for more information on exception instance attributes.
+
+
+.. exception:: ImportError
+
+ Raised when an :keyword:`import` statement fails to find the module definition
+ or when a ``from ... import`` fails to find a name that is to be imported.
+
+ .. % XXXJH xref to import statement?
+
+
+.. exception:: IndexError
+
+ Raised when a sequence subscript is out of range. (Slice indices are silently
+ truncated to fall in the allowed range; if an index is not a plain integer,
+ :exc:`TypeError` is raised.)
+
+ .. % XXXJH xref to sequences
+
+
+.. exception:: KeyError
+
+ Raised when a mapping (dictionary) key is not found in the set of existing keys.
+
+ .. % XXXJH xref to mapping objects?
+
+
+.. exception:: KeyboardInterrupt
+
+ Raised when the user hits the interrupt key (normally :kbd:`Control-C` or
+ :kbd:`Delete`). During execution, a check for interrupts is made regularly.
+ Interrupts typed when a built-in function :func:`input` or :func:`raw_input` is
+ waiting for input also raise this exception. The exception inherits from
+ :exc:`BaseException` so as to not be accidentally caught by code that catches
+ :exc:`Exception` and thus prevent the interpreter from exiting.
+
+ .. % XXX(hylton) xrefs here
+
+ .. versionchanged:: 2.5
+ Changed to inherit from :exc:`BaseException`.
+
+
+.. exception:: MemoryError
+
+ Raised when an operation runs out of memory but the situation may still be
+ rescued (by deleting some objects). The associated value is a string indicating
+ what kind of (internal) operation ran out of memory. Note that because of the
+ underlying memory management architecture (C's :cfunc:`malloc` function), the
+ interpreter may not always be able to completely recover from this situation; it
+ nevertheless raises an exception so that a stack traceback can be printed, in
+ case a run-away program was the cause.
+
+
+.. exception:: NameError
+
+ Raised when a local or global name is not found. This applies only to
+ unqualified names. The associated value is an error message that includes the
+ name that could not be found.
+
+
+.. exception:: NotImplementedError
+
+ This exception is derived from :exc:`RuntimeError`. In user defined base
+ classes, abstract methods should raise this exception when they require derived
+ classes to override the method.
+
+ .. versionadded:: 1.5.2
+
+
+.. exception:: OSError
+
+ This class is derived from :exc:`EnvironmentError` and is used primarily as the
+ :mod:`os` module's ``os.error`` exception. See :exc:`EnvironmentError` above for
+ a description of the possible associated values.
+
+ .. % xref for os module
+
+ .. versionadded:: 1.5.2
+
+
+.. exception:: OverflowError
+
+ Raised when the result of an arithmetic operation is too large to be
+ represented. This cannot occur for long integers (which would rather raise
+ :exc:`MemoryError` than give up). Because of the lack of standardization of
+ floating point exception handling in C, most floating point operations also
+ aren't checked. For plain integers, all operations that can overflow are
+ checked except left shift, where typical applications prefer to drop bits than
+ raise an exception.
+
+ .. % XXXJH reference to long's and/or int's?
+
+
+.. exception:: ReferenceError
+
+ This exception is raised when a weak reference proxy, created by the
+ :func:`weakref.proxy` function, is used to access an attribute of the referent
+ after it has been garbage collected. For more information on weak references,
+ see the :mod:`weakref` module.
+
+ .. versionadded:: 2.2
+ Previously known as the :exc:`weakref.ReferenceError` exception.
+
+
+.. exception:: RuntimeError
+
+ Raised when an error is detected that doesn't fall in any of the other
+ categories. The associated value is a string indicating what precisely went
+ wrong. (This exception is mostly a relic from a previous version of the
+ interpreter; it is not used very much any more.)
+
+
+.. exception:: StopIteration
+
+ Raised by an iterator's :meth:`next` method to signal that there are no further
+ values. This is derived from :exc:`Exception` rather than :exc:`StandardError`,
+ since this is not considered an error in its normal application.
+
+ .. versionadded:: 2.2
+
+
+.. exception:: SyntaxError
+
+ Raised when the parser encounters a syntax error. This may occur in an
+ :keyword:`import` statement, in an :keyword:`exec` statement, in a call to the
+ built-in function :func:`eval` or :func:`input`, or when reading the initial
+ script or standard input (also interactively).
+
+ .. % XXXJH xref to these functions?
+
+ Instances of this class have attributes :attr:`filename`, :attr:`lineno`,
+ :attr:`offset` and :attr:`text` for easier access to the details. :func:`str`
+ of the exception instance returns only the message.
+
+
+.. exception:: SystemError
+
+ Raised when the interpreter finds an internal error, but the situation does not
+ look so serious to cause it to abandon all hope. The associated value is a
+ string indicating what went wrong (in low-level terms).
+
+ You should report this to the author or maintainer of your Python interpreter.
+ Be sure to report the version of the Python interpreter (``sys.version``; it is
+ also printed at the start of an interactive Python session), the exact error
+ message (the exception's associated value) and if possible the source of the
+ program that triggered the error.
+
+
+.. exception:: SystemExit
+
+ This exception is raised by the :func:`sys.exit` function. When it is not
+ handled, the Python interpreter exits; no stack traceback is printed. If the
+ associated value is a plain integer, it specifies the system exit status (passed
+ to C's :cfunc:`exit` function); if it is ``None``, the exit status is zero; if
+ it has another type (such as a string), the object's value is printed and the
+ exit status is one.
+
+ .. % XXX(hylton) xref to module sys?
+
+ Instances have an attribute :attr:`code` which is set to the proposed exit
+ status or error message (defaulting to ``None``). Also, this exception derives
+ directly from :exc:`BaseException` and not :exc:`StandardError`, since it is not
+ technically an error.
+
+ A call to :func:`sys.exit` is translated into an exception so that clean-up
+ handlers (:keyword:`finally` clauses of :keyword:`try` statements) can be
+ executed, and so that a debugger can execute a script without running the risk
+ of losing control. The :func:`os._exit` function can be used if it is
+ absolutely positively necessary to exit immediately (for example, in the child
+ process after a call to :func:`fork`).
+
+ The exception inherits from :exc:`BaseException` instead of :exc:`StandardError`
+ or :exc:`Exception` so that it is not accidentally caught by code that catches
+ :exc:`Exception`. This allows the exception to properly propagate up and cause
+ the interpreter to exit.
+
+ .. versionchanged:: 2.5
+ Changed to inherit from :exc:`BaseException`.
+
+
+.. exception:: TypeError
+
+ Raised when an operation or function is applied to an object of inappropriate
+ type. The associated value is a string giving details about the type mismatch.
+
+
+.. exception:: UnboundLocalError
+
+ Raised when a reference is made to a local variable in a function or method, but
+ no value has been bound to that variable. This is a subclass of
+ :exc:`NameError`.
+
+ .. versionadded:: 2.0
+
+
+.. exception:: UnicodeError
+
+ Raised when a Unicode-related encoding or decoding error occurs. It is a
+ subclass of :exc:`ValueError`.
+
+ .. versionadded:: 2.0
+
+
+.. exception:: UnicodeEncodeError
+
+ Raised when a Unicode-related error occurs during encoding. It is a subclass of
+ :exc:`UnicodeError`.
+
+ .. versionadded:: 2.3
+
+
+.. exception:: UnicodeDecodeError
+
+ Raised when a Unicode-related error occurs during decoding. It is a subclass of
+ :exc:`UnicodeError`.
+
+ .. versionadded:: 2.3
+
+
+.. exception:: UnicodeTranslateError
+
+ Raised when a Unicode-related error occurs during translating. It is a subclass
+ of :exc:`UnicodeError`.
+
+ .. versionadded:: 2.3
+
+
+.. exception:: ValueError
+
+ Raised when a built-in operation or function receives an argument that has the
+ right type but an inappropriate value, and the situation is not described by a
+ more precise exception such as :exc:`IndexError`.
+
+
+.. exception:: WindowsError
+
+ Raised when a Windows-specific error occurs or when the error number does not
+ correspond to an :cdata:`errno` value. The :attr:`winerror` and
+ :attr:`strerror` values are created from the return values of the
+ :cfunc:`GetLastError` and :cfunc:`FormatMessage` functions from the Windows
+ Platform API. The :attr:`errno` value maps the :attr:`winerror` value to
+ corresponding ``errno.h`` values. This is a subclass of :exc:`OSError`.
+
+ .. versionadded:: 2.0
+
+ .. versionchanged:: 2.5
+ Previous versions put the :cfunc:`GetLastError` codes into :attr:`errno`.
+
+
+.. exception:: ZeroDivisionError
+
+ Raised when the second argument of a division or modulo operation is zero. The
+ associated value is a string indicating the type of the operands and the
+ operation.
+
+The following exceptions are used as warning categories; see the :mod:`warnings`
+module for more information.
+
+
+.. exception:: Warning
+
+ Base class for warning categories.
+
+
+.. exception:: UserWarning
+
+ Base class for warnings generated by user code.
+
+
+.. exception:: DeprecationWarning
+
+ Base class for warnings about deprecated features.
+
+
+.. exception:: PendingDeprecationWarning
+
+ Base class for warnings about features which will be deprecated in the future.
+
+
+.. exception:: SyntaxWarning
+
+ Base class for warnings about dubious syntax
+
+
+.. exception:: RuntimeWarning
+
+ Base class for warnings about dubious runtime behavior.
+
+
+.. exception:: FutureWarning
+
+ Base class for warnings about constructs that will change semantically in the
+ future.
+
+
+.. exception:: ImportWarning
+
+ Base class for warnings about probable mistakes in module imports.
+
+ .. versionadded:: 2.5
+
+
+.. exception:: UnicodeWarning
+
+ Base class for warnings related to Unicode.
+
+ .. versionadded:: 2.5
+
+The class hierarchy for built-in exceptions is:
+
+
+.. literalinclude:: ../../Lib/test/exception_hierarchy.txt
--- /dev/null
+
+:mod:`fcntl` --- The :func:`fcntl` and :func:`ioctl` system calls
+=================================================================
+
+.. module:: fcntl
+ :platform: Unix
+ :synopsis: The fcntl() and ioctl() system calls.
+.. sectionauthor:: Jaap Vermeulen
+
+
+.. index::
+ pair: UNIX@Unix; file control
+ pair: UNIX@Unix; I/O control
+
+This module performs file control and I/O control on file descriptors. It is an
+interface to the :cfunc:`fcntl` and :cfunc:`ioctl` Unix routines.
+
+All functions in this module take a file descriptor *fd* as their first
+argument. This can be an integer file descriptor, such as returned by
+``sys.stdin.fileno()``, or a file object, such as ``sys.stdin`` itself, which
+provides a :meth:`fileno` which returns a genuine file descriptor.
+
+The module defines the following functions:
+
+
+.. function:: fcntl(fd, op[, arg])
+
+ Perform the requested operation on file descriptor *fd* (file objects providing
+ a :meth:`fileno` method are accepted as well). The operation is defined by *op*
+ and is operating system dependent. These codes are also found in the
+ :mod:`fcntl` module. The argument *arg* is optional, and defaults to the integer
+ value ``0``. When present, it can either be an integer value, or a string.
+ With the argument missing or an integer value, the return value of this function
+ is the integer return value of the C :cfunc:`fcntl` call. When the argument is
+ a string it represents a binary structure, e.g. created by :func:`struct.pack`.
+ The binary data is copied to a buffer whose address is passed to the C
+ :cfunc:`fcntl` call. The return value after a successful call is the contents
+ of the buffer, converted to a string object. The length of the returned string
+ will be the same as the length of the *arg* argument. This is limited to 1024
+ bytes. If the information returned in the buffer by the operating system is
+ larger than 1024 bytes, this is most likely to result in a segmentation
+ violation or a more subtle data corruption.
+
+ If the :cfunc:`fcntl` fails, an :exc:`IOError` is raised.
+
+
+.. function:: ioctl(fd, op[, arg[, mutate_flag]])
+
+ This function is identical to the :func:`fcntl` function, except that the
+ operations are typically defined in the library module :mod:`termios` and the
+ argument handling is even more complicated.
+
+ The parameter *arg* can be one of an integer, absent (treated identically to the
+ integer ``0``), an object supporting the read-only buffer interface (most likely
+ a plain Python string) or an object supporting the read-write buffer interface.
+
+ In all but the last case, behaviour is as for the :func:`fcntl` function.
+
+ If a mutable buffer is passed, then the behaviour is determined by the value of
+ the *mutate_flag* parameter.
+
+ If it is false, the buffer's mutability is ignored and behaviour is as for a
+ read-only buffer, except that the 1024 byte limit mentioned above is avoided --
+ so long as the buffer you pass is as least as long as what the operating system
+ wants to put there, things should work.
+
+ If *mutate_flag* is true, then the buffer is (in effect) passed to the
+ underlying :func:`ioctl` system call, the latter's return code is passed back to
+ the calling Python, and the buffer's new contents reflect the action of the
+ :func:`ioctl`. This is a slight simplification, because if the supplied buffer
+ is less than 1024 bytes long it is first copied into a static buffer 1024 bytes
+ long which is then passed to :func:`ioctl` and copied back into the supplied
+ buffer.
+
+ If *mutate_flag* is not supplied, then from Python 2.5 it defaults to true,
+ which is a change from versions 2.3 and 2.4. Supply the argument explicitly if
+ version portability is a priority.
+
+ An example::
+
+ >>> import array, fcntl, struct, termios, os
+ >>> os.getpgrp()
+ 13341
+ >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0]
+ 13341
+ >>> buf = array.array('h', [0])
+ >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
+ 0
+ >>> buf
+ array('h', [13341])
+
+
+.. function:: flock(fd, op)
+
+ Perform the lock operation *op* on file descriptor *fd* (file objects providing
+ a :meth:`fileno` method are accepted as well). See the Unix manual
+ :manpage:`flock(3)` for details. (On some systems, this function is emulated
+ using :cfunc:`fcntl`.)
+
+
+.. function:: lockf(fd, operation, [length, [start, [whence]]])
+
+ This is essentially a wrapper around the :func:`fcntl` locking calls. *fd* is
+ the file descriptor of the file to lock or unlock, and *operation* is one of the
+ following values:
+
+ * :const:`LOCK_UN` -- unlock
+ * :const:`LOCK_SH` -- acquire a shared lock
+ * :const:`LOCK_EX` -- acquire an exclusive lock
+
+ When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be
+ bit-wise OR'd with :const:`LOCK_NB` to avoid blocking on lock acquisition.
+ If :const:`LOCK_NB` is used and the lock cannot be acquired, an
+ :exc:`IOError` will be raised and the exception will have an *errno*
+ attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the
+ operating system; for portability, check for both values). On at least some
+ systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a
+ file opened for writing.
+
+ *length* is the number of bytes to lock, *start* is the byte offset at which the
+ lock starts, relative to *whence*, and *whence* is as with :func:`fileobj.seek`,
+ specifically:
+
+ * :const:`0` -- relative to the start of the file (:const:`SEEK_SET`)
+ * :const:`1` -- relative to the current buffer position (:const:`SEEK_CUR`)
+ * :const:`2` -- relative to the end of the file (:const:`SEEK_END`)
+
+ The default for *start* is 0, which means to start at the beginning of the file.
+ The default for *length* is 0 which means to lock to the end of the file. The
+ default for *whence* is also 0.
+
+Examples (all on a SVR4 compliant system)::
+
+ import struct, fcntl, os
+
+ f = open(...)
+ rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)
+
+ lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
+ rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
+
+Note that in the first example the return value variable *rv* will hold an
+integer value; in the second example it will hold a string value. The structure
+lay-out for the *lockdata* variable is system dependent --- therefore using the
+:func:`flock` call may be better.
+
+
+.. seealso::
+
+ Module :mod:`os`
+ If the locking flags :const:`O_SHLOCK` and :const:`O_EXLOCK` are present
+ in the :mod:`os` module, the :func:`os.open` function provides a more
+ platform-independent alternative to the :func:`lockf` and :func:`flock`
+ functions.
+
--- /dev/null
+
+:mod:`filecmp` --- File and Directory Comparisons
+=================================================
+
+.. module:: filecmp
+ :synopsis: Compare files efficiently.
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+
+
+The :mod:`filecmp` module defines functions to compare files and directories,
+with various optional time/correctness trade-offs.
+
+The :mod:`filecmp` module defines the following functions:
+
+
+.. function:: cmp(f1, f2[, shallow])
+
+ Compare the files named *f1* and *f2*, returning ``True`` if they seem equal,
+ ``False`` otherwise.
+
+ Unless *shallow* is given and is false, files with identical :func:`os.stat`
+ signatures are taken to be equal.
+
+ Files that were compared using this function will not be compared again unless
+ their :func:`os.stat` signature changes.
+
+ Note that no external programs are called from this function, giving it
+ portability and efficiency.
+
+
+.. function:: cmpfiles(dir1, dir2, common[, shallow])
+
+ Returns three lists of file names: *match*, *mismatch*, *errors*. *match*
+ contains the list of files match in both directories, *mismatch* includes the
+ names of those that don't, and *errros* lists the names of files which could not
+ be compared. Files may be listed in *errors* because the user may lack
+ permission to read them or many other reasons, but always that the comparison
+ could not be done for some reason.
+
+ The *common* parameter is a list of file names found in both directories. The
+ *shallow* parameter has the same meaning and default value as for
+ :func:`filecmp.cmp`.
+
+Example::
+
+ >>> import filecmp
+ >>> filecmp.cmp('undoc.rst', 'undoc.rst')
+ True
+ >>> filecmp.cmp('undoc.rst', 'index.rst')
+ False
+
+
+.. _dircmp-objects:
+
+The :class:`dircmp` class
+-------------------------
+
+:class:`dircmp` instances are built using this constructor:
+
+
+.. class:: dircmp(a, b[, ignore[, hide]])
+
+ Construct a new directory comparison object, to compare the directories *a* and
+ *b*. *ignore* is a list of names to ignore, and defaults to ``['RCS', 'CVS',
+ 'tags']``. *hide* is a list of names to hide, and defaults to ``[os.curdir,
+ os.pardir]``.
+
+The :class:`dircmp` class provides the following methods:
+
+
+.. method:: dircmp.report()
+
+ Print (to ``sys.stdout``) a comparison between *a* and *b*.
+
+
+.. method:: dircmp.report_partial_closure()
+
+ Print a comparison between *a* and *b* and common immediate subdirectories.
+
+
+.. method:: dircmp.report_full_closure()
+
+ Print a comparison between *a* and *b* and common subdirectories (recursively).
+
+The :class:`dircmp` offers a number of interesting attributes that may be used
+to get various bits of information about the directory trees being compared.
+
+Note that via :meth:`__getattr__` hooks, all attributes are computed lazily, so
+there is no speed penalty if only those attributes which are lightweight to
+compute are used.
+
+
+.. attribute:: dircmp.left_list
+
+ Files and subdirectories in *a*, filtered by *hide* and *ignore*.
+
+
+.. attribute:: dircmp.right_list
+
+ Files and subdirectories in *b*, filtered by *hide* and *ignore*.
+
+
+.. attribute:: dircmp.common
+
+ Files and subdirectories in both *a* and *b*.
+
+
+.. attribute:: dircmp.left_only
+
+ Files and subdirectories only in *a*.
+
+
+.. attribute:: dircmp.right_only
+
+ Files and subdirectories only in *b*.
+
+
+.. attribute:: dircmp.common_dirs
+
+ Subdirectories in both *a* and *b*.
+
+
+.. attribute:: dircmp.common_files
+
+ Files in both *a* and *b*
+
+
+.. attribute:: dircmp.common_funny
+
+ Names in both *a* and *b*, such that the type differs between the directories,
+ or names for which :func:`os.stat` reports an error.
+
+
+.. attribute:: dircmp.same_files
+
+ Files which are identical in both *a* and *b*.
+
+
+.. attribute:: dircmp.diff_files
+
+ Files which are in both *a* and *b*, whose contents differ.
+
+
+.. attribute:: dircmp.funny_files
+
+ Files which are in both *a* and *b*, but could not be compared.
+
+
+.. attribute:: dircmp.subdirs
+
+ A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects.
+
--- /dev/null
+
+.. _fileformats:
+
+************
+File Formats
+************
+
+The modules described in this chapter parse various miscellaneous file formats
+that aren't markup languages or are related to e-mail.
+
+
+.. toctree::
+
+ csv.rst
+ configparser.rst
+ robotparser.rst
+ netrc.rst
+ xdrlib.rst
--- /dev/null
+:mod:`fileinput` --- Iterate over lines from multiple input streams
+===================================================================
+
+.. module:: fileinput
+ :synopsis: Loop over standard input or a list of files.
+.. moduleauthor:: Guido van Rossum <guido@python.org>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+This module implements a helper class and functions to quickly write a loop over
+standard input or a list of files.
+
+The typical use is::
+
+ import fileinput
+ for line in fileinput.input():
+ process(line)
+
+This iterates over the lines of all files listed in ``sys.argv[1:]``, defaulting
+to ``sys.stdin`` if the list is empty. If a filename is ``'-'``, it is also
+replaced by ``sys.stdin``. To specify an alternative list of filenames, pass it
+as the first argument to :func:`input`. A single file name is also allowed.
+
+All files are opened in text mode by default, but you can override this by
+specifying the *mode* parameter in the call to :func:`input` or
+:class:`FileInput()`. If an I/O error occurs during opening or reading a file,
+:exc:`IOError` is raised.
+
+If ``sys.stdin`` is used more than once, the second and further use will return
+no lines, except perhaps for interactive use, or if it has been explicitly reset
+(e.g. using ``sys.stdin.seek(0)``).
+
+Empty files are opened and immediately closed; the only time their presence in
+the list of filenames is noticeable at all is when the last file opened is
+empty.
+
+Lines are returned with any newlines intact, which means that the last line in
+a file may not have one.
+
+You can control how files are opened by providing an opening hook via the
+*openhook* parameter to :func:`fileinput.input` or :class:`FileInput()`. The
+hook must be a function that takes two arguments, *filename* and *mode*, and
+returns an accordingly opened file-like object. Two useful hooks are already
+provided by this module.
+
+The following function is the primary interface of this module:
+
+
+.. function:: input([files[, inplace[, backup[, mode[, openhook]]]]])
+
+ Create an instance of the :class:`FileInput` class. The instance will be used
+ as global state for the functions of this module, and is also returned to use
+ during iteration. The parameters to this function will be passed along to the
+ constructor of the :class:`FileInput` class.
+
+ .. versionchanged:: 2.5
+ Added the *mode* and *openhook* parameters.
+
+The following functions use the global state created by :func:`fileinput.input`;
+if there is no active state, :exc:`RuntimeError` is raised.
+
+
+.. function:: filename()
+
+ Return the name of the file currently being read. Before the first line has
+ been read, returns ``None``.
+
+
+.. function:: fileno()
+
+ Return the integer "file descriptor" for the current file. When no file is
+ opened (before the first line and between files), returns ``-1``.
+
+ .. versionadded:: 2.5
+
+
+.. function:: lineno()
+
+ Return the cumulative line number of the line that has just been read. Before
+ the first line has been read, returns ``0``. After the last line of the last
+ file has been read, returns the line number of that line.
+
+
+.. function:: filelineno()
+
+ Return the line number in the current file. Before the first line has been
+ read, returns ``0``. After the last line of the last file has been read,
+ returns the line number of that line within the file.
+
+
+.. function:: isfirstline()
+
+ Returns true if the line just read is the first line of its file, otherwise
+ returns false.
+
+
+.. function:: isstdin()
+
+ Returns true if the last line was read from ``sys.stdin``, otherwise returns
+ false.
+
+
+.. function:: nextfile()
+
+ Close the current file so that the next iteration will read the first line from
+ the next file (if any); lines not read from the file will not count towards the
+ cumulative line count. The filename is not changed until after the first line
+ of the next file has been read. Before the first line has been read, this
+ function has no effect; it cannot be used to skip the first file. After the
+ last line of the last file has been read, this function has no effect.
+
+
+.. function:: close()
+
+ Close the sequence.
+
+The class which implements the sequence behavior provided by the module is
+available for subclassing as well:
+
+
+.. class:: FileInput([files[, inplace[, backup[, mode[, openhook]]]]])
+
+ Class :class:`FileInput` is the implementation; its methods :meth:`filename`,
+ :meth:`fileno`, :meth:`lineno`, :meth:`filelineno`, :meth:`isfirstline`,
+ :meth:`isstdin`, :meth:`nextfile` and :meth:`close` correspond to the functions
+ of the same name in the module. In addition it has a :meth:`readline` method
+ which returns the next input line, and a :meth:`__getitem__` method which
+ implements the sequence behavior. The sequence must be accessed in strictly
+ sequential order; random access and :meth:`readline` cannot be mixed.
+
+ With *mode* you can specify which file mode will be passed to :func:`open`. It
+ must be one of ``'r'``, ``'rU'``, ``'U'`` and ``'rb'``.
+
+ The *openhook*, when given, must be a function that takes two arguments,
+ *filename* and *mode*, and returns an accordingly opened file-like object. You
+ cannot use *inplace* and *openhook* together.
+
+ .. versionchanged:: 2.5
+ Added the *mode* and *openhook* parameters.
+
+**Optional in-place filtering:** if the keyword argument ``inplace=1`` is passed
+to :func:`fileinput.input` or to the :class:`FileInput` constructor, the file is
+moved to a backup file and standard output is directed to the input file (if a
+file of the same name as the backup file already exists, it will be replaced
+silently). This makes it possible to write a filter that rewrites its input
+file in place. If the *backup* parameter is given (typically as
+``backup='.<some extension>'``), it specifies the extension for the backup file,
+and the backup file remains around; by default, the extension is ``'.bak'`` and
+it is deleted when the output file is closed. In-place filtering is disabled
+when standard input is read.
+
+**Caveat:** The current implementation does not work for MS-DOS 8+3 filesystems.
+
+The two following opening hooks are provided by this module:
+
+
+.. function:: hook_compressed(filename, mode)
+
+ Transparently opens files compressed with gzip and bzip2 (recognized by the
+ extensions ``'.gz'`` and ``'.bz2'``) using the :mod:`gzip` and :mod:`bz2`
+ modules. If the filename extension is not ``'.gz'`` or ``'.bz2'``, the file is
+ opened normally (ie, using :func:`open` without any decompression).
+
+ Usage example: ``fi = fileinput.FileInput(openhook=fileinput.hook_compressed)``
+
+ .. versionadded:: 2.5
+
+
+.. function:: hook_encoded(encoding)
+
+ Returns a hook which opens each file with :func:`codecs.open`, using the given
+ *encoding* to read the file.
+
+ Usage example: ``fi =
+ fileinput.FileInput(openhook=fileinput.hook_encoded("iso-8859-1"))``
+
+ .. note::
+
+ With this hook, :class:`FileInput` might return Unicode strings depending on the
+ specified *encoding*.
+
+ .. versionadded:: 2.5
+
--- /dev/null
+
+.. _filesys:
+
+*************************
+File and Directory Access
+*************************
+
+The modules described in this chapter deal with disk files and directories. For
+example, there are modules for reading the properties of files, manipulating
+paths in a portable way, and creating temporary files. The full list of modules
+in this chapter is:
+
+
+.. toctree::
+
+ os.path.rst
+ fileinput.rst
+ stat.rst
+ statvfs.rst
+ filecmp.rst
+ tempfile.rst
+ glob.rst
+ fnmatch.rst
+ linecache.rst
+ shutil.rst
+ dircache.rst
+ macpath.rst
+
+
+.. seealso::
+
+ Section :ref:`bltin-file-objects`
+ A description of Python's built-in file objects.
+
+ Module :mod:`os`
+ Operating system interfaces, including functions to work with files at a lower
+ level than the built-in file object.
+
--- /dev/null
+
+:mod:`fl` --- FORMS library for graphical user interfaces
+=========================================================
+
+.. module:: fl
+ :platform: IRIX
+ :synopsis: FORMS library for applications with graphical user interfaces.
+
+
+.. index::
+ single: FORMS Library
+ single: Overmars, Mark
+
+This module provides an interface to the FORMS Library by Mark Overmars. The
+source for the library can be retrieved by anonymous ftp from host
+``ftp.cs.ruu.nl``, directory :file:`SGI/FORMS`. It was last tested with version
+2.0b.
+
+Most functions are literal translations of their C equivalents, dropping the
+initial ``fl_`` from their name. Constants used by the library are defined in
+module :mod:`FL` described below.
+
+The creation of objects is a little different in Python than in C: instead of
+the 'current form' maintained by the library to which new FORMS objects are
+added, all functions that add a FORMS object to a form are methods of the Python
+object representing the form. Consequently, there are no Python equivalents for
+the C functions :cfunc:`fl_addto_form` and :cfunc:`fl_end_form`, and the
+equivalent of :cfunc:`fl_bgn_form` is called :func:`fl.make_form`.
+
+Watch out for the somewhat confusing terminology: FORMS uses the word
+:dfn:`object` for the buttons, sliders etc. that you can place in a form. In
+Python, 'object' means any value. The Python interface to FORMS introduces two
+new Python object types: form objects (representing an entire form) and FORMS
+objects (representing one button, slider etc.). Hopefully this isn't too
+confusing.
+
+There are no 'free objects' in the Python interface to FORMS, nor is there an
+easy way to add object classes written in Python. The FORMS interface to GL
+event handling is available, though, so you can mix FORMS with pure GL windows.
+
+**Please note:** importing :mod:`fl` implies a call to the GL function
+:cfunc:`foreground` and to the FORMS routine :cfunc:`fl_init`.
+
+
+.. _fl-functions:
+
+Functions Defined in Module :mod:`fl`
+-------------------------------------
+
+Module :mod:`fl` defines the following functions. For more information about
+what they do, see the description of the equivalent C function in the FORMS
+documentation:
+
+
+.. function:: make_form(type, width, height)
+
+ Create a form with given type, width and height. This returns a :dfn:`form`
+ object, whose methods are described below.
+
+
+.. function:: do_forms()
+
+ The standard FORMS main loop. Returns a Python object representing the FORMS
+ object needing interaction, or the special value :const:`FL.EVENT`.
+
+
+.. function:: check_forms()
+
+ Check for FORMS events. Returns what :func:`do_forms` above returns, or
+ ``None`` if there is no event that immediately needs interaction.
+
+
+.. function:: set_event_call_back(function)
+
+ Set the event callback function.
+
+
+.. function:: set_graphics_mode(rgbmode, doublebuffering)
+
+ Set the graphics modes.
+
+
+.. function:: get_rgbmode()
+
+ Return the current rgb mode. This is the value of the C global variable
+ :cdata:`fl_rgbmode`.
+
+
+.. function:: show_message(str1, str2, str3)
+
+ Show a dialog box with a three-line message and an OK button.
+
+
+.. function:: show_question(str1, str2, str3)
+
+ Show a dialog box with a three-line message and YES and NO buttons. It returns
+ ``1`` if the user pressed YES, ``0`` if NO.
+
+
+.. function:: show_choice(str1, str2, str3, but1[, but2[, but3]])
+
+ Show a dialog box with a three-line message and up to three buttons. It returns
+ the number of the button clicked by the user (``1``, ``2`` or ``3``).
+
+
+.. function:: show_input(prompt, default)
+
+ Show a dialog box with a one-line prompt message and text field in which the
+ user can enter a string. The second argument is the default input string. It
+ returns the string value as edited by the user.
+
+
+.. function:: show_file_selector(message, directory, pattern, default)
+
+ Show a dialog box in which the user can select a file. It returns the absolute
+ filename selected by the user, or ``None`` if the user presses Cancel.
+
+
+.. function:: get_directory()
+ get_pattern()
+ get_filename()
+
+ These functions return the directory, pattern and filename (the tail part only)
+ selected by the user in the last :func:`show_file_selector` call.
+
+
+.. function:: qdevice(dev)
+ unqdevice(dev)
+ isqueued(dev)
+ qtest()
+ qread()
+ qreset()
+ qenter(dev, val)
+ get_mouse()
+ tie(button, valuator1, valuator2)
+
+ These functions are the FORMS interfaces to the corresponding GL functions. Use
+ these if you want to handle some GL events yourself when using
+ :func:`fl.do_events`. When a GL event is detected that FORMS cannot handle,
+ :func:`fl.do_forms` returns the special value :const:`FL.EVENT` and you should
+ call :func:`fl.qread` to read the event from the queue. Don't use the
+ equivalent GL functions!
+
+ .. % \funcline{blkqread}{?}
+
+
+.. function:: color()
+ mapcolor()
+ getmcolor()
+
+ See the description in the FORMS documentation of :cfunc:`fl_color`,
+ :cfunc:`fl_mapcolor` and :cfunc:`fl_getmcolor`.
+
+
+.. _form-objects:
+
+Form Objects
+------------
+
+Form objects (returned by :func:`make_form` above) have the following methods.
+Each method corresponds to a C function whose name is prefixed with ``fl_``; and
+whose first argument is a form pointer; please refer to the official FORMS
+documentation for descriptions.
+
+All the :meth:`add_\*` methods return a Python object representing the FORMS
+object. Methods of FORMS objects are described below. Most kinds of FORMS
+object also have some methods specific to that kind; these methods are listed
+here.
+
+
+.. method:: form.show_form(placement, bordertype, name)
+
+ Show the form.
+
+
+.. method:: form.hide_form()
+
+ Hide the form.
+
+
+.. method:: form.redraw_form()
+
+ Redraw the form.
+
+
+.. method:: form.set_form_position(x, y)
+
+ Set the form's position.
+
+
+.. method:: form.freeze_form()
+
+ Freeze the form.
+
+
+.. method:: form.unfreeze_form()
+
+ Unfreeze the form.
+
+
+.. method:: form.activate_form()
+
+ Activate the form.
+
+
+.. method:: form.deactivate_form()
+
+ Deactivate the form.
+
+
+.. method:: form.bgn_group()
+
+ Begin a new group of objects; return a group object.
+
+
+.. method:: form.end_group()
+
+ End the current group of objects.
+
+
+.. method:: form.find_first()
+
+ Find the first object in the form.
+
+
+.. method:: form.find_last()
+
+ Find the last object in the form.
+
+.. % ---
+
+
+.. method:: form.add_box(type, x, y, w, h, name)
+
+ Add a box object to the form. No extra methods.
+
+
+.. method:: form.add_text(type, x, y, w, h, name)
+
+ Add a text object to the form. No extra methods.
+
+.. % \begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name}
+.. % Add a bitmap object to the form.
+.. % \end{methoddesc}
+
+
+.. method:: form.add_clock(type, x, y, w, h, name)
+
+ Add a clock object to the form. --- Method: :meth:`get_clock`.
+
+.. % ---
+
+
+.. method:: form.add_button(type, x, y, w, h, name)
+
+ Add a button object to the form. --- Methods: :meth:`get_button`,
+ :meth:`set_button`.
+
+
+.. method:: form.add_lightbutton(type, x, y, w, h, name)
+
+ Add a lightbutton object to the form. --- Methods: :meth:`get_button`,
+ :meth:`set_button`.
+
+
+.. method:: form.add_roundbutton(type, x, y, w, h, name)
+
+ Add a roundbutton object to the form. --- Methods: :meth:`get_button`,
+ :meth:`set_button`.
+
+.. % ---
+
+
+.. method:: form.add_slider(type, x, y, w, h, name)
+
+ Add a slider object to the form. --- Methods: :meth:`set_slider_value`,
+ :meth:`get_slider_value`, :meth:`set_slider_bounds`, :meth:`get_slider_bounds`,
+ :meth:`set_slider_return`, :meth:`set_slider_size`,
+ :meth:`set_slider_precision`, :meth:`set_slider_step`.
+
+
+.. method:: form.add_valslider(type, x, y, w, h, name)
+
+ Add a valslider object to the form. --- Methods: :meth:`set_slider_value`,
+ :meth:`get_slider_value`, :meth:`set_slider_bounds`, :meth:`get_slider_bounds`,
+ :meth:`set_slider_return`, :meth:`set_slider_size`,
+ :meth:`set_slider_precision`, :meth:`set_slider_step`.
+
+
+.. method:: form.add_dial(type, x, y, w, h, name)
+
+ Add a dial object to the form. --- Methods: :meth:`set_dial_value`,
+ :meth:`get_dial_value`, :meth:`set_dial_bounds`, :meth:`get_dial_bounds`.
+
+
+.. method:: form.add_positioner(type, x, y, w, h, name)
+
+ Add a positioner object to the form. --- Methods:
+ :meth:`set_positioner_xvalue`, :meth:`set_positioner_yvalue`,
+ :meth:`set_positioner_xbounds`, :meth:`set_positioner_ybounds`,
+ :meth:`get_positioner_xvalue`, :meth:`get_positioner_yvalue`,
+ :meth:`get_positioner_xbounds`, :meth:`get_positioner_ybounds`.
+
+
+.. method:: form.add_counter(type, x, y, w, h, name)
+
+ Add a counter object to the form. --- Methods: :meth:`set_counter_value`,
+ :meth:`get_counter_value`, :meth:`set_counter_bounds`, :meth:`set_counter_step`,
+ :meth:`set_counter_precision`, :meth:`set_counter_return`.
+
+.. % ---
+
+
+.. method:: form.add_input(type, x, y, w, h, name)
+
+ Add a input object to the form. --- Methods: :meth:`set_input`,
+ :meth:`get_input`, :meth:`set_input_color`, :meth:`set_input_return`.
+
+.. % ---
+
+
+.. method:: form.add_menu(type, x, y, w, h, name)
+
+ Add a menu object to the form. --- Methods: :meth:`set_menu`,
+ :meth:`get_menu`, :meth:`addto_menu`.
+
+
+.. method:: form.add_choice(type, x, y, w, h, name)
+
+ Add a choice object to the form. --- Methods: :meth:`set_choice`,
+ :meth:`get_choice`, :meth:`clear_choice`, :meth:`addto_choice`,
+ :meth:`replace_choice`, :meth:`delete_choice`, :meth:`get_choice_text`,
+ :meth:`set_choice_fontsize`, :meth:`set_choice_fontstyle`.
+
+
+.. method:: form.add_browser(type, x, y, w, h, name)
+
+ Add a browser object to the form. --- Methods: :meth:`set_browser_topline`,
+ :meth:`clear_browser`, :meth:`add_browser_line`, :meth:`addto_browser`,
+ :meth:`insert_browser_line`, :meth:`delete_browser_line`,
+ :meth:`replace_browser_line`, :meth:`get_browser_line`, :meth:`load_browser`,
+ :meth:`get_browser_maxline`, :meth:`select_browser_line`,
+ :meth:`deselect_browser_line`, :meth:`deselect_browser`,
+ :meth:`isselected_browser_line`, :meth:`get_browser`,
+ :meth:`set_browser_fontsize`, :meth:`set_browser_fontstyle`,
+ :meth:`set_browser_specialkey`.
+
+.. % ---
+
+
+.. method:: form.add_timer(type, x, y, w, h, name)
+
+ Add a timer object to the form. --- Methods: :meth:`set_timer`,
+ :meth:`get_timer`.
+
+Form objects have the following data attributes; see the FORMS documentation:
+
++---------------------+-----------------+--------------------------------+
+| Name | C Type | Meaning |
++=====================+=================+================================+
+| :attr:`window` | int (read-only) | GL window id |
++---------------------+-----------------+--------------------------------+
+| :attr:`w` | float | form width |
++---------------------+-----------------+--------------------------------+
+| :attr:`h` | float | form height |
++---------------------+-----------------+--------------------------------+
+| :attr:`x` | float | form x origin |
++---------------------+-----------------+--------------------------------+
+| :attr:`y` | float | form y origin |
++---------------------+-----------------+--------------------------------+
+| :attr:`deactivated` | int | nonzero if form is deactivated |
++---------------------+-----------------+--------------------------------+
+| :attr:`visible` | int | nonzero if form is visible |
++---------------------+-----------------+--------------------------------+
+| :attr:`frozen` | int | nonzero if form is frozen |
++---------------------+-----------------+--------------------------------+
+| :attr:`doublebuf` | int | nonzero if double buffering on |
++---------------------+-----------------+--------------------------------+
+
+
+.. _forms-objects:
+
+FORMS Objects
+-------------
+
+Besides methods specific to particular kinds of FORMS objects, all FORMS objects
+also have the following methods:
+
+
+.. method:: FORMS object.set_call_back(function, argument)
+
+ Set the object's callback function and argument. When the object needs
+ interaction, the callback function will be called with two arguments: the
+ object, and the callback argument. (FORMS objects without a callback function
+ are returned by :func:`fl.do_forms` or :func:`fl.check_forms` when they need
+ interaction.) Call this method without arguments to remove the callback
+ function.
+
+
+.. method:: FORMS object.delete_object()
+
+ Delete the object.
+
+
+.. method:: FORMS object.show_object()
+
+ Show the object.
+
+
+.. method:: FORMS object.hide_object()
+
+ Hide the object.
+
+
+.. method:: FORMS object.redraw_object()
+
+ Redraw the object.
+
+
+.. method:: FORMS object.freeze_object()
+
+ Freeze the object.
+
+
+.. method:: FORMS object.unfreeze_object()
+
+ Unfreeze the object.
+
+FORMS objects have these data attributes; see the FORMS documentation:
+
+.. % \begin{methoddesc}[FORMS object]{handle_object}{} XXX
+.. % \end{methoddesc}
+.. % \begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX
+.. % \end{methoddesc}
+
++--------------------+-----------------+------------------+
+| Name | C Type | Meaning |
++====================+=================+==================+
+| :attr:`objclass` | int (read-only) | object class |
++--------------------+-----------------+------------------+
+| :attr:`type` | int (read-only) | object type |
++--------------------+-----------------+------------------+
+| :attr:`boxtype` | int | box type |
++--------------------+-----------------+------------------+
+| :attr:`x` | float | x origin |
++--------------------+-----------------+------------------+
+| :attr:`y` | float | y origin |
++--------------------+-----------------+------------------+
+| :attr:`w` | float | width |
++--------------------+-----------------+------------------+
+| :attr:`h` | float | height |
++--------------------+-----------------+------------------+
+| :attr:`col1` | int | primary color |
++--------------------+-----------------+------------------+
+| :attr:`col2` | int | secondary color |
++--------------------+-----------------+------------------+
+| :attr:`align` | int | alignment |
++--------------------+-----------------+------------------+
+| :attr:`lcol` | int | label color |
++--------------------+-----------------+------------------+
+| :attr:`lsize` | float | label font size |
++--------------------+-----------------+------------------+
+| :attr:`label` | string | label string |
++--------------------+-----------------+------------------+
+| :attr:`lstyle` | int | label style |
++--------------------+-----------------+------------------+
+| :attr:`pushed` | int (read-only) | (see FORMS docs) |
++--------------------+-----------------+------------------+
+| :attr:`focus` | int (read-only) | (see FORMS docs) |
++--------------------+-----------------+------------------+
+| :attr:`belowmouse` | int (read-only) | (see FORMS docs) |
++--------------------+-----------------+------------------+
+| :attr:`frozen` | int (read-only) | (see FORMS docs) |
++--------------------+-----------------+------------------+
+| :attr:`active` | int (read-only) | (see FORMS docs) |
++--------------------+-----------------+------------------+
+| :attr:`input` | int (read-only) | (see FORMS docs) |
++--------------------+-----------------+------------------+
+| :attr:`visible` | int (read-only) | (see FORMS docs) |
++--------------------+-----------------+------------------+
+| :attr:`radio` | int (read-only) | (see FORMS docs) |
++--------------------+-----------------+------------------+
+| :attr:`automatic` | int (read-only) | (see FORMS docs) |
++--------------------+-----------------+------------------+
+
+
+:mod:`FL` --- Constants used with the :mod:`fl` module
+======================================================
+
+.. module:: FL
+ :platform: IRIX
+ :synopsis: Constants used with the fl module.
+
+
+This module defines symbolic constants needed to use the built-in module
+:mod:`fl` (see above); they are equivalent to those defined in the C header file
+``<forms.h>`` except that the name prefix ``FL_`` is omitted. Read the module
+source for a complete list of the defined names. Suggested use::
+
+ import fl
+ from FL import *
+
+
+:mod:`flp` --- Functions for loading stored FORMS designs
+=========================================================
+
+.. module:: flp
+ :platform: IRIX
+ :synopsis: Functions for loading stored FORMS designs.
+
+
+This module defines functions that can read form definitions created by the
+'form designer' (:program:`fdesign`) program that comes with the FORMS library
+(see module :mod:`fl` above).
+
+For now, see the file :file:`flp.doc` in the Python library source directory for
+a description.
+
+XXX A complete description should be inserted here!
+
--- /dev/null
+
+:mod:`fm` --- *Font Manager* interface
+======================================
+
+.. module:: fm
+ :platform: IRIX
+ :synopsis: Font Manager interface for SGI workstations.
+
+
+.. index::
+ single: Font Manager, IRIS
+ single: IRIS Font Manager
+
+This module provides access to the IRIS *Font Manager* library. It is
+available only on Silicon Graphics machines. See also: *4Sight User's Guide*,
+section 1, chapter 5: "Using the IRIS Font Manager."
+
+This is not yet a full interface to the IRIS Font Manager. Among the unsupported
+features are: matrix operations; cache operations; character operations (use
+string operations instead); some details of font info; individual glyph metrics;
+and printer matching.
+
+It supports the following operations:
+
+
+.. function:: init()
+
+ Initialization function. Calls :cfunc:`fminit`. It is normally not necessary to
+ call this function, since it is called automatically the first time the
+ :mod:`fm` module is imported.
+
+
+.. function:: findfont(fontname)
+
+ Return a font handle object. Calls ``fmfindfont(fontname)``.
+
+
+.. function:: enumerate()
+
+ Returns a list of available font names. This is an interface to
+ :cfunc:`fmenumerate`.
+
+
+.. function:: prstr(string)
+
+ Render a string using the current font (see the :func:`setfont` font handle
+ method below). Calls ``fmprstr(string)``.
+
+
+.. function:: setpath(string)
+
+ Sets the font search path. Calls ``fmsetpath(string)``. (XXX Does not work!?!)
+
+
+.. function:: fontpath()
+
+ Returns the current font search path.
+
+Font handle objects support the following operations:
+
+
+.. method:: font handle.scalefont(factor)
+
+ Returns a handle for a scaled version of this font. Calls ``fmscalefont(fh,
+ factor)``.
+
+
+.. method:: font handle.setfont()
+
+ Makes this font the current font. Note: the effect is undone silently when the
+ font handle object is deleted. Calls ``fmsetfont(fh)``.
+
+
+.. method:: font handle.getfontname()
+
+ Returns this font's name. Calls ``fmgetfontname(fh)``.
+
+
+.. method:: font handle.getcomment()
+
+ Returns the comment string associated with this font. Raises an exception if
+ there is none. Calls ``fmgetcomment(fh)``.
+
+
+.. method:: font handle.getfontinfo()
+
+ Returns a tuple giving some pertinent data about this font. This is an interface
+ to ``fmgetfontinfo()``. The returned tuple contains the following numbers:
+ ``(``*printermatched*, *fixed_width*, *xorig*, *yorig*, *xsize*, *ysize*,
+ *height*, *nglyphs*``)``.
+
+
+.. method:: font handle.getstrwidth(string)
+
+ Returns the width, in pixels, of *string* when drawn in this font. Calls
+ ``fmgetstrwidth(fh, string)``.
+
--- /dev/null
+
+:mod:`fnmatch` --- Unix filename pattern matching
+=================================================
+
+.. module:: fnmatch
+ :synopsis: Unix shell style filename pattern matching.
+
+
+.. index:: single: filenames; wildcard expansion
+
+.. index:: module: re
+
+This module provides support for Unix shell-style wildcards, which are *not* the
+same as regular expressions (which are documented in the :mod:`re` module). The
+special characters used in shell-style wildcards are:
+
++------------+------------------------------------+
+| Pattern | Meaning |
++============+====================================+
+| ``*`` | matches everything |
++------------+------------------------------------+
+| ``?`` | matches any single character |
++------------+------------------------------------+
+| ``[seq]`` | matches any character in *seq* |
++------------+------------------------------------+
+| ``[!seq]`` | matches any character not in *seq* |
++------------+------------------------------------+
+
+.. index:: module: glob
+
+Note that the filename separator (``'/'`` on Unix) is *not* special to this
+module. See module :mod:`glob` for pathname expansion (:mod:`glob` uses
+:func:`fnmatch` to match pathname segments). Similarly, filenames starting with
+a period are not special for this module, and are matched by the ``*`` and ``?``
+patterns.
+
+
+.. function:: fnmatch(filename, pattern)
+
+ Test whether the *filename* string matches the *pattern* string, returning true
+ or false. If the operating system is case-insensitive, then both parameters
+ will be normalized to all lower- or upper-case before the comparison is
+ performed. If you require a case-sensitive comparison regardless of whether
+ that's standard for your operating system, use :func:`fnmatchcase` instead.
+
+ This example will print all file names in the current directory with the
+ extension ``.txt``::
+
+ import fnmatch
+ import os
+
+ for file in os.listdir('.'):
+ if fnmatch.fnmatch(file, '*.txt'):
+ print file
+
+
+.. function:: fnmatchcase(filename, pattern)
+
+ Test whether *filename* matches *pattern*, returning true or false; the
+ comparison is case-sensitive.
+
+
+.. function:: filter(names, pattern)
+
+ Return the subset of the list of *names* that match *pattern*. It is the same as
+ ``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.
+
+ .. versionadded:: 2.2
+
+
+.. function:: translate(pattern)
+
+ Return the shell-style *pattern* converted to a regular expression.
+
+ Example::
+
+ >>> import fnmatch, re
+ >>>
+ >>> regex = fnmatch.translate('*.txt')
+ >>> regex
+ '.*\\.txt$'
+ >>> reobj = re.compile(regex)
+ >>> print reobj.match('foobar.txt')
+ <_sre.SRE_Match object at 0x...>
+
+
+.. seealso::
+
+ Module :mod:`glob`
+ Unix shell-style path expansion.
+
--- /dev/null
+
+:mod:`formatter` --- Generic output formatting
+==============================================
+
+.. module:: formatter
+ :synopsis: Generic output formatter and device interface.
+
+
+.. index:: single: HTMLParser (class in htmllib)
+
+This module supports two interface definitions, each with multiple
+implementations. The *formatter* interface is used by the :class:`HTMLParser`
+class of the :mod:`htmllib` module, and the *writer* interface is required by
+the formatter interface.
+
+Formatter objects transform an abstract flow of formatting events into specific
+output events on writer objects. Formatters manage several stack structures to
+allow various properties of a writer object to be changed and restored; writers
+need not be able to handle relative changes nor any sort of "change back"
+operation. Specific writer properties which may be controlled via formatter
+objects are horizontal alignment, font, and left margin indentations. A
+mechanism is provided which supports providing arbitrary, non-exclusive style
+settings to a writer as well. Additional interfaces facilitate formatting
+events which are not reversible, such as paragraph separation.
+
+Writer objects encapsulate device interfaces. Abstract devices, such as file
+formats, are supported as well as physical devices. The provided
+implementations all work with abstract devices. The interface makes available
+mechanisms for setting the properties which formatter objects manage and
+inserting data into the output.
+
+
+.. _formatter-interface:
+
+The Formatter Interface
+-----------------------
+
+Interfaces to create formatters are dependent on the specific formatter class
+being instantiated. The interfaces described below are the required interfaces
+which all formatters must support once initialized.
+
+One data element is defined at the module level:
+
+
+.. data:: AS_IS
+
+ Value which can be used in the font specification passed to the ``push_font()``
+ method described below, or as the new value to any other ``push_property()``
+ method. Pushing the ``AS_IS`` value allows the corresponding ``pop_property()``
+ method to be called without having to track whether the property was changed.
+
+The following attributes are defined for formatter instance objects:
+
+
+.. attribute:: formatter.writer
+
+ The writer instance with which the formatter interacts.
+
+
+.. method:: formatter.end_paragraph(blanklines)
+
+ Close any open paragraphs and insert at least *blanklines* before the next
+ paragraph.
+
+
+.. method:: formatter.add_line_break()
+
+ Add a hard line break if one does not already exist. This does not break the
+ logical paragraph.
+
+
+.. method:: formatter.add_hor_rule(*args, **kw)
+
+ Insert a horizontal rule in the output. A hard break is inserted if there is
+ data in the current paragraph, but the logical paragraph is not broken. The
+ arguments and keywords are passed on to the writer's :meth:`send_line_break`
+ method.
+
+
+.. method:: formatter.add_flowing_data(data)
+
+ Provide data which should be formatted with collapsed whitespace. Whitespace
+ from preceding and successive calls to :meth:`add_flowing_data` is considered as
+ well when the whitespace collapse is performed. The data which is passed to
+ this method is expected to be word-wrapped by the output device. Note that any
+ word-wrapping still must be performed by the writer object due to the need to
+ rely on device and font information.
+
+
+.. method:: formatter.add_literal_data(data)
+
+ Provide data which should be passed to the writer unchanged. Whitespace,
+ including newline and tab characters, are considered legal in the value of
+ *data*.
+
+
+.. method:: formatter.add_label_data(format, counter)
+
+ Insert a label which should be placed to the left of the current left margin.
+ This should be used for constructing bulleted or numbered lists. If the
+ *format* value is a string, it is interpreted as a format specification for
+ *counter*, which should be an integer. The result of this formatting becomes the
+ value of the label; if *format* is not a string it is used as the label value
+ directly. The label value is passed as the only argument to the writer's
+ :meth:`send_label_data` method. Interpretation of non-string label values is
+ dependent on the associated writer.
+
+ Format specifications are strings which, in combination with a counter value,
+ are used to compute label values. Each character in the format string is copied
+ to the label value, with some characters recognized to indicate a transform on
+ the counter value. Specifically, the character ``'1'`` represents the counter
+ value formatter as an Arabic number, the characters ``'A'`` and ``'a'``
+ represent alphabetic representations of the counter value in upper and lower
+ case, respectively, and ``'I'`` and ``'i'`` represent the counter value in Roman
+ numerals, in upper and lower case. Note that the alphabetic and roman
+ transforms require that the counter value be greater than zero.
+
+
+.. method:: formatter.flush_softspace()
+
+ Send any pending whitespace buffered from a previous call to
+ :meth:`add_flowing_data` to the associated writer object. This should be called
+ before any direct manipulation of the writer object.
+
+
+.. method:: formatter.push_alignment(align)
+
+ Push a new alignment setting onto the alignment stack. This may be
+ :const:`AS_IS` if no change is desired. If the alignment value is changed from
+ the previous setting, the writer's :meth:`new_alignment` method is called with
+ the *align* value.
+
+
+.. method:: formatter.pop_alignment()
+
+ Restore the previous alignment.
+
+
+.. method:: formatter.push_font((size, italic, bold, teletype))
+
+ Change some or all font properties of the writer object. Properties which are
+ not set to :const:`AS_IS` are set to the values passed in while others are
+ maintained at their current settings. The writer's :meth:`new_font` method is
+ called with the fully resolved font specification.
+
+
+.. method:: formatter.pop_font()
+
+ Restore the previous font.
+
+
+.. method:: formatter.push_margin(margin)
+
+ Increase the number of left margin indentations by one, associating the logical
+ tag *margin* with the new indentation. The initial margin level is ``0``.
+ Changed values of the logical tag must be true values; false values other than
+ :const:`AS_IS` are not sufficient to change the margin.
+
+
+.. method:: formatter.pop_margin()
+
+ Restore the previous margin.
+
+
+.. method:: formatter.push_style(*styles)
+
+ Push any number of arbitrary style specifications. All styles are pushed onto
+ the styles stack in order. A tuple representing the entire stack, including
+ :const:`AS_IS` values, is passed to the writer's :meth:`new_styles` method.
+
+
+.. method:: formatter.pop_style([n=1])
+
+ Pop the last *n* style specifications passed to :meth:`push_style`. A tuple
+ representing the revised stack, including :const:`AS_IS` values, is passed to
+ the writer's :meth:`new_styles` method.
+
+
+.. method:: formatter.set_spacing(spacing)
+
+ Set the spacing style for the writer.
+
+
+.. method:: formatter.assert_line_data([flag=1])
+
+ Inform the formatter that data has been added to the current paragraph
+ out-of-band. This should be used when the writer has been manipulated
+ directly. The optional *flag* argument can be set to false if the writer
+ manipulations produced a hard line break at the end of the output.
+
+
+.. _formatter-impls:
+
+Formatter Implementations
+-------------------------
+
+Two implementations of formatter objects are provided by this module. Most
+applications may use one of these classes without modification or subclassing.
+
+
+.. class:: NullFormatter([writer])
+
+ A formatter which does nothing. If *writer* is omitted, a :class:`NullWriter`
+ instance is created. No methods of the writer are called by
+ :class:`NullFormatter` instances. Implementations should inherit from this
+ class if implementing a writer interface but don't need to inherit any
+ implementation.
+
+
+.. class:: AbstractFormatter(writer)
+
+ The standard formatter. This implementation has demonstrated wide applicability
+ to many writers, and may be used directly in most circumstances. It has been
+ used to implement a full-featured World Wide Web browser.
+
+
+.. _writer-interface:
+
+The Writer Interface
+--------------------
+
+Interfaces to create writers are dependent on the specific writer class being
+instantiated. The interfaces described below are the required interfaces which
+all writers must support once initialized. Note that while most applications can
+use the :class:`AbstractFormatter` class as a formatter, the writer must
+typically be provided by the application.
+
+
+.. method:: writer.flush()
+
+ Flush any buffered output or device control events.
+
+
+.. method:: writer.new_alignment(align)
+
+ Set the alignment style. The *align* value can be any object, but by convention
+ is a string or ``None``, where ``None`` indicates that the writer's "preferred"
+ alignment should be used. Conventional *align* values are ``'left'``,
+ ``'center'``, ``'right'``, and ``'justify'``.
+
+
+.. method:: writer.new_font(font)
+
+ Set the font style. The value of *font* will be ``None``, indicating that the
+ device's default font should be used, or a tuple of the form ``(``*size*,
+ *italic*, *bold*, *teletype*``)``. Size will be a string indicating the size of
+ font that should be used; specific strings and their interpretation must be
+ defined by the application. The *italic*, *bold*, and *teletype* values are
+ Boolean values specifying which of those font attributes should be used.
+
+
+.. method:: writer.new_margin(margin, level)
+
+ Set the margin level to the integer *level* and the logical tag to *margin*.
+ Interpretation of the logical tag is at the writer's discretion; the only
+ restriction on the value of the logical tag is that it not be a false value for
+ non-zero values of *level*.
+
+
+.. method:: writer.new_spacing(spacing)
+
+ Set the spacing style to *spacing*.
+
+
+.. method:: writer.new_styles(styles)
+
+ Set additional styles. The *styles* value is a tuple of arbitrary values; the
+ value :const:`AS_IS` should be ignored. The *styles* tuple may be interpreted
+ either as a set or as a stack depending on the requirements of the application
+ and writer implementation.
+
+
+.. method:: writer.send_line_break()
+
+ Break the current line.
+
+
+.. method:: writer.send_paragraph(blankline)
+
+ Produce a paragraph separation of at least *blankline* blank lines, or the
+ equivalent. The *blankline* value will be an integer. Note that the
+ implementation will receive a call to :meth:`send_line_break` before this call
+ if a line break is needed; this method should not include ending the last line
+ of the paragraph. It is only responsible for vertical spacing between
+ paragraphs.
+
+
+.. method:: writer.send_hor_rule(*args, **kw)
+
+ Display a horizontal rule on the output device. The arguments to this method
+ are entirely application- and writer-specific, and should be interpreted with
+ care. The method implementation may assume that a line break has already been
+ issued via :meth:`send_line_break`.
+
+
+.. method:: writer.send_flowing_data(data)
+
+ Output character data which may be word-wrapped and re-flowed as needed. Within
+ any sequence of calls to this method, the writer may assume that spans of
+ multiple whitespace characters have been collapsed to single space characters.
+
+
+.. method:: writer.send_literal_data(data)
+
+ Output character data which has already been formatted for display. Generally,
+ this should be interpreted to mean that line breaks indicated by newline
+ characters should be preserved and no new line breaks should be introduced. The
+ data may contain embedded newline and tab characters, unlike data provided to
+ the :meth:`send_formatted_data` interface.
+
+
+.. method:: writer.send_label_data(data)
+
+ Set *data* to the left of the current left margin, if possible. The value of
+ *data* is not restricted; treatment of non-string values is entirely
+ application- and writer-dependent. This method will only be called at the
+ beginning of a line.
+
+
+.. _writer-impls:
+
+Writer Implementations
+----------------------
+
+Three implementations of the writer object interface are provided as examples by
+this module. Most applications will need to derive new writer classes from the
+:class:`NullWriter` class.
+
+
+.. class:: NullWriter()
+
+ A writer which only provides the interface definition; no actions are taken on
+ any methods. This should be the base class for all writers which do not need to
+ inherit any implementation methods.
+
+
+.. class:: AbstractWriter()
+
+ A writer which can be used in debugging formatters, but not much else. Each
+ method simply announces itself by printing its name and arguments on standard
+ output.
+
+
+.. class:: DumbWriter([file[, maxcol=72]])
+
+ Simple writer class which writes output on the file object passed in as *file*
+ or, if *file* is omitted, on standard output. The output is simply word-wrapped
+ to the number of columns specified by *maxcol*. This class is suitable for
+ reflowing a sequence of paragraphs.
+
--- /dev/null
+
+:mod:`fpectl` --- Floating point exception control
+==================================================
+
+.. module:: fpectl
+ :platform: Unix
+ :synopsis: Provide control for floating point exception handling.
+.. moduleauthor:: Lee Busby <busby1@llnl.gov>
+.. sectionauthor:: Lee Busby <busby1@llnl.gov>
+
+
+.. note::
+
+ The :mod:`fpectl` module is not built by default, and its usage is discouraged
+ and may be dangerous except in the hands of experts. See also the section
+ :ref:`fpectl-limitations` on limitations for more details.
+
+.. index:: single: IEEE-754
+
+Most computers carry out floating point operations in conformance with the
+so-called IEEE-754 standard. On any real computer, some floating point
+operations produce results that cannot be expressed as a normal floating point
+value. For example, try ::
+
+ >>> import math
+ >>> math.exp(1000)
+ inf
+ >>> math.exp(1000) / math.exp(1000)
+ nan
+
+(The example above will work on many platforms. DEC Alpha may be one exception.)
+"Inf" is a special, non-numeric value in IEEE-754 that stands for "infinity",
+and "nan" means "not a number." Note that, other than the non-numeric results,
+nothing special happened when you asked Python to carry out those calculations.
+That is in fact the default behaviour prescribed in the IEEE-754 standard, and
+if it works for you, stop reading now.
+
+In some circumstances, it would be better to raise an exception and stop
+processing at the point where the faulty operation was attempted. The
+:mod:`fpectl` module is for use in that situation. It provides control over
+floating point units from several hardware manufacturers, allowing the user to
+turn on the generation of :const:`SIGFPE` whenever any of the IEEE-754
+exceptions Division by Zero, Overflow, or Invalid Operation occurs. In tandem
+with a pair of wrapper macros that are inserted into the C code comprising your
+python system, :const:`SIGFPE` is trapped and converted into the Python
+:exc:`FloatingPointError` exception.
+
+The :mod:`fpectl` module defines the following functions and may raise the given
+exception:
+
+
+.. function:: turnon_sigfpe()
+
+ Turn on the generation of :const:`SIGFPE`, and set up an appropriate signal
+ handler.
+
+
+.. function:: turnoff_sigfpe()
+
+ Reset default handling of floating point exceptions.
+
+
+.. exception:: FloatingPointError
+
+ After :func:`turnon_sigfpe` has been executed, a floating point operation that
+ raises one of the IEEE-754 exceptions Division by Zero, Overflow, or Invalid
+ operation will in turn raise this standard Python exception.
+
+
+.. _fpectl-example:
+
+Example
+-------
+
+The following example demonstrates how to start up and test operation of the
+:mod:`fpectl` module. ::
+
+ >>> import fpectl
+ >>> import fpetest
+ >>> fpectl.turnon_sigfpe()
+ >>> fpetest.test()
+ overflow PASS
+ FloatingPointError: Overflow
+
+ div by 0 PASS
+ FloatingPointError: Division by zero
+ [ more output from test elided ]
+ >>> import math
+ >>> math.exp(1000)
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+ FloatingPointError: in math_1
+
+
+.. _fpectl-limitations:
+
+Limitations and other considerations
+------------------------------------
+
+Setting up a given processor to trap IEEE-754 floating point errors currently
+requires custom code on a per-architecture basis. You may have to modify
+:mod:`fpectl` to control your particular hardware.
+
+Conversion of an IEEE-754 exception to a Python exception requires that the
+wrapper macros ``PyFPE_START_PROTECT`` and ``PyFPE_END_PROTECT`` be inserted
+into your code in an appropriate fashion. Python itself has been modified to
+support the :mod:`fpectl` module, but many other codes of interest to numerical
+analysts have not.
+
+The :mod:`fpectl` module is not thread-safe.
+
+
+.. seealso::
+
+ Some files in the source distribution may be interesting in learning more about
+ how this module operates. The include file :file:`Include/pyfpe.h` discusses the
+ implementation of this module at some length. :file:`Modules/fpetestmodule.c`
+ gives several examples of use. Many additional examples can be found in
+ :file:`Objects/floatobject.c`.
+
--- /dev/null
+
+:mod:`fpformat` --- Floating point conversions
+==============================================
+
+.. module:: fpformat
+ :synopsis: General floating point formatting functions.
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+
+
+The :mod:`fpformat` module defines functions for dealing with floating point
+numbers representations in 100% pure Python.
+
+.. note::
+
+ This module is unneeded: everything here could be done via the ``%`` string
+ interpolation operator.
+
+The :mod:`fpformat` module defines the following functions and an exception:
+
+
+.. function:: fix(x, digs)
+
+ Format *x* as ``[-]ddd.ddd`` with *digs* digits after the point and at least one
+ digit before. If ``digs <= 0``, the decimal point is suppressed.
+
+ *x* can be either a number or a string that looks like one. *digs* is an
+ integer.
+
+ Return value is a string.
+
+
+.. function:: sci(x, digs)
+
+ Format *x* as ``[-]d.dddE[+-]ddd`` with *digs* digits after the point and
+ exactly one digit before. If ``digs <= 0``, one digit is kept and the point is
+ suppressed.
+
+ *x* can be either a real number, or a string that looks like one. *digs* is an
+ integer.
+
+ Return value is a string.
+
+
+.. exception:: NotANumber
+
+ Exception raised when a string passed to :func:`fix` or :func:`sci` as the *x*
+ parameter does not look like a number. This is a subclass of :exc:`ValueError`
+ when the standard exceptions are strings. The exception value is the improperly
+ formatted string that caused the exception to be raised.
+
+Example::
+
+ >>> import fpformat
+ >>> fpformat.fix(1.23, 1)
+ '1.2'
+
--- /dev/null
+
+:mod:`FrameWork` --- Interactive application framework
+======================================================
+
+.. module:: FrameWork
+ :platform: Mac
+ :synopsis: Interactive application framework.
+
+
+The :mod:`FrameWork` module contains classes that together provide a framework
+for an interactive Macintosh application. The programmer builds an application
+by creating subclasses that override various methods of the bases classes,
+thereby implementing the functionality wanted. Overriding functionality can
+often be done on various different levels, i.e. to handle clicks in a single
+dialog window in a non-standard way it is not necessary to override the complete
+event handling.
+
+Work on the :mod:`FrameWork` has pretty much stopped, now that :mod:`PyObjC` is
+available for full Cocoa access from Python, and the documentation describes
+only the most important functionality, and not in the most logical manner at
+that. Examine the source or the examples for more details. The following are
+some comments posted on the MacPython newsgroup about the strengths and
+limitations of :mod:`FrameWork`:
+
+
+.. epigraph::
+
+ The strong point of :mod:`FrameWork` is that it allows you to break into the
+ control-flow at many different places. :mod:`W`, for instance, uses a different
+ way to enable/disable menus and that plugs right in leaving the rest intact.
+ The weak points of :mod:`FrameWork` are that it has no abstract command
+ interface (but that shouldn't be difficult), that its dialog support is minimal
+ and that its control/toolbar support is non-existent.
+
+The :mod:`FrameWork` module defines the following functions:
+
+
+.. function:: Application()
+
+ An object representing the complete application. See below for a description of
+ the methods. The default :meth:`__init__` routine creates an empty window
+ dictionary and a menu bar with an apple menu.
+
+
+.. function:: MenuBar()
+
+ An object representing the menubar. This object is usually not created by the
+ user.
+
+
+.. function:: Menu(bar, title[, after])
+
+ An object representing a menu. Upon creation you pass the ``MenuBar`` the menu
+ appears in, the *title* string and a position (1-based) *after* where the menu
+ should appear (default: at the end).
+
+
+.. function:: MenuItem(menu, title[, shortcut, callback])
+
+ Create a menu item object. The arguments are the menu to create, the item title
+ string and optionally the keyboard shortcut and a callback routine. The callback
+ is called with the arguments menu-id, item number within menu (1-based), current
+ front window and the event record.
+
+ Instead of a callable object the callback can also be a string. In this case
+ menu selection causes the lookup of a method in the topmost window and the
+ application. The method name is the callback string with ``'domenu_'``
+ prepended.
+
+ Calling the ``MenuBar`` :meth:`fixmenudimstate` method sets the correct dimming
+ for all menu items based on the current front window.
+
+
+.. function:: Separator(menu)
+
+ Add a separator to the end of a menu.
+
+
+.. function:: SubMenu(menu, label)
+
+ Create a submenu named *label* under menu *menu*. The menu object is returned.
+
+
+.. function:: Window(parent)
+
+ Creates a (modeless) window. *Parent* is the application object to which the
+ window belongs. The window is not displayed until later.
+
+
+.. function:: DialogWindow(parent)
+
+ Creates a modeless dialog window.
+
+
+.. function:: windowbounds(width, height)
+
+ Return a ``(left, top, right, bottom)`` tuple suitable for creation of a window
+ of given width and height. The window will be staggered with respect to previous
+ windows, and an attempt is made to keep the whole window on-screen. However, the
+ window will however always be the exact size given, so parts may be offscreen.
+
+
+.. function:: setwatchcursor()
+
+ Set the mouse cursor to a watch.
+
+
+.. function:: setarrowcursor()
+
+ Set the mouse cursor to an arrow.
+
+
+.. _application-objects:
+
+Application Objects
+-------------------
+
+Application objects have the following methods, among others:
+
+
+.. method:: Application.makeusermenus()
+
+ Override this method if you need menus in your application. Append the menus to
+ the attribute :attr:`menubar`.
+
+
+.. method:: Application.getabouttext()
+
+ Override this method to return a text string describing your application.
+ Alternatively, override the :meth:`do_about` method for more elaborate "about"
+ messages.
+
+
+.. method:: Application.mainloop([mask[, wait]])
+
+ This routine is the main event loop, call it to set your application rolling.
+ *Mask* is the mask of events you want to handle, *wait* is the number of ticks
+ you want to leave to other concurrent application (default 0, which is probably
+ not a good idea). While raising *self* to exit the mainloop is still supported
+ it is not recommended: call ``self._quit()`` instead.
+
+ The event loop is split into many small parts, each of which can be overridden.
+ The default methods take care of dispatching events to windows and dialogs,
+ handling drags and resizes, Apple Events, events for non-FrameWork windows, etc.
+
+ In general, all event handlers should return ``1`` if the event is fully handled
+ and ``0`` otherwise (because the front window was not a FrameWork window, for
+ instance). This is needed so that update events and such can be passed on to
+ other windows like the Sioux console window. Calling :func:`MacOS.HandleEvent`
+ is not allowed within *our_dispatch* or its callees, since this may result in an
+ infinite loop if the code is called through the Python inner-loop event handler.
+
+
+.. method:: Application.asyncevents(onoff)
+
+ Call this method with a nonzero parameter to enable asynchronous event handling.
+ This will tell the inner interpreter loop to call the application event handler
+ *async_dispatch* whenever events are available. This will cause FrameWork window
+ updates and the user interface to remain working during long computations, but
+ will slow the interpreter down and may cause surprising results in non-reentrant
+ code (such as FrameWork itself). By default *async_dispatch* will immediately
+ call *our_dispatch* but you may override this to handle only certain events
+ asynchronously. Events you do not handle will be passed to Sioux and such.
+
+ The old on/off value is returned.
+
+
+.. method:: Application._quit()
+
+ Terminate the running :meth:`mainloop` call at the next convenient moment.
+
+
+.. method:: Application.do_char(c, event)
+
+ The user typed character *c*. The complete details of the event can be found in
+ the *event* structure. This method can also be provided in a ``Window`` object,
+ which overrides the application-wide handler if the window is frontmost.
+
+
+.. method:: Application.do_dialogevent(event)
+
+ Called early in the event loop to handle modeless dialog events. The default
+ method simply dispatches the event to the relevant dialog (not through the
+ ``DialogWindow`` object involved). Override if you need special handling of
+ dialog events (keyboard shortcuts, etc).
+
+
+.. method:: Application.idle(event)
+
+ Called by the main event loop when no events are available. The null-event is
+ passed (so you can look at mouse position, etc).
+
+
+.. _window-objects:
+
+Window Objects
+--------------
+
+Window objects have the following methods, among others:
+
+
+.. method:: Window.open()
+
+ Override this method to open a window. Store the MacOS window-id in
+ :attr:`self.wid` and call the :meth:`do_postopen` method to register the window
+ with the parent application.
+
+
+.. method:: Window.close()
+
+ Override this method to do any special processing on window close. Call the
+ :meth:`do_postclose` method to cleanup the parent state.
+
+
+.. method:: Window.do_postresize(width, height, macoswindowid)
+
+ Called after the window is resized. Override if more needs to be done than
+ calling ``InvalRect``.
+
+
+.. method:: Window.do_contentclick(local, modifiers, event)
+
+ The user clicked in the content part of a window. The arguments are the
+ coordinates (window-relative), the key modifiers and the raw event.
+
+
+.. method:: Window.do_update(macoswindowid, event)
+
+ An update event for the window was received. Redraw the window.
+
+
+.. method:: Window.do_activate(activate, event)
+
+ The window was activated (``activate == 1``) or deactivated (``activate == 0``).
+ Handle things like focus highlighting, etc.
+
+
+.. _controlswindow-object:
+
+ControlsWindow Object
+---------------------
+
+ControlsWindow objects have the following methods besides those of ``Window``
+objects:
+
+
+.. method:: ControlsWindow.do_controlhit(window, control, pcode, event)
+
+ Part *pcode* of control *control* was hit by the user. Tracking and such has
+ already been taken care of.
+
+
+.. _scrolledwindow-object:
+
+ScrolledWindow Object
+---------------------
+
+ScrolledWindow objects are ControlsWindow objects with the following extra
+methods:
+
+
+.. method:: ScrolledWindow.scrollbars([wantx[, wanty]])
+
+ Create (or destroy) horizontal and vertical scrollbars. The arguments specify
+ which you want (default: both). The scrollbars always have minimum ``0`` and
+ maximum ``32767``.
+
+
+.. method:: ScrolledWindow.getscrollbarvalues()
+
+ You must supply this method. It should return a tuple ``(x, y)`` giving the
+ current position of the scrollbars (between ``0`` and ``32767``). You can return
+ ``None`` for either to indicate the whole document is visible in that direction.
+
+
+.. method:: ScrolledWindow.updatescrollbars()
+
+ Call this method when the document has changed. It will call
+ :meth:`getscrollbarvalues` and update the scrollbars.
+
+
+.. method:: ScrolledWindow.scrollbar_callback(which, what, value)
+
+ Supplied by you and called after user interaction. *which* will be ``'x'`` or
+ ``'y'``, *what* will be ``'-'``, ``'--'``, ``'set'``, ``'++'`` or ``'+'``. For
+ ``'set'``, *value* will contain the new scrollbar position.
+
+
+.. method:: ScrolledWindow.scalebarvalues(absmin, absmax, curmin, curmax)
+
+ Auxiliary method to help you calculate values to return from
+ :meth:`getscrollbarvalues`. You pass document minimum and maximum value and
+ topmost (leftmost) and bottommost (rightmost) visible values and it returns the
+ correct number or ``None``.
+
+
+.. method:: ScrolledWindow.do_activate(onoff, event)
+
+ Takes care of dimming/highlighting scrollbars when a window becomes frontmost.
+ If you override this method, call this one at the end of your method.
+
+
+.. method:: ScrolledWindow.do_postresize(width, height, window)
+
+ Moves scrollbars to the correct position. Call this method initially if you
+ override it.
+
+
+.. method:: ScrolledWindow.do_controlhit(window, control, pcode, event)
+
+ Handles scrollbar interaction. If you override it call this method first, a
+ nonzero return value indicates the hit was in the scrollbars and has been
+ handled.
+
+
+.. _dialogwindow-objects:
+
+DialogWindow Objects
+--------------------
+
+DialogWindow objects have the following methods besides those of ``Window``
+objects:
+
+
+.. method:: DialogWindow.open(resid)
+
+ Create the dialog window, from the DLOG resource with id *resid*. The dialog
+ object is stored in :attr:`self.wid`.
+
+
+.. method:: DialogWindow.do_itemhit(item, event)
+
+ Item number *item* was hit. You are responsible for redrawing toggle buttons,
+ etc.
+
--- /dev/null
+
+.. _frameworks:
+
+******************
+Program Frameworks
+******************
+
+The modules described in this chapter are frameworks that will largely dictate
+the structure of your program. Currently the modules described here are all
+oriented toward writing command-line interfaces.
+
+The full list of modules described in this chapter is:
+
+
+.. toctree::
+
+ cmd.rst
+ shlex.rst
--- /dev/null
+
+:mod:`ftplib` --- FTP protocol client
+=====================================
+
+.. module:: ftplib
+ :synopsis: FTP protocol client (requires sockets).
+
+
+.. index::
+ pair: FTP; protocol
+ single: FTP; ftplib (standard module)
+
+This module defines the class :class:`FTP` and a few related items. The
+:class:`FTP` class implements the client side of the FTP protocol. You can use
+this to write Python programs that perform a variety of automated FTP jobs, such
+as mirroring other ftp servers. It is also used by the module :mod:`urllib` to
+handle URLs that use FTP. For more information on FTP (File Transfer Protocol),
+see Internet :rfc:`959`.
+
+Here's a sample session using the :mod:`ftplib` module::
+
+ >>> from ftplib import FTP
+ >>> ftp = FTP('ftp.cwi.nl') # connect to host, default port
+ >>> ftp.login() # user anonymous, passwd anonymous@
+ >>> ftp.retrlines('LIST') # list directory contents
+ total 24418
+ drwxrwsr-x 5 ftp-usr pdmaint 1536 Mar 20 09:48 .
+ dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 ..
+ -rw-r--r-- 1 ftp-usr pdmaint 5305 Mar 20 09:48 INDEX
+ .
+ .
+ .
+ >>> ftp.retrbinary('RETR README', open('README', 'wb').write)
+ '226 Transfer complete.'
+ >>> ftp.quit()
+
+The module defines the following items:
+
+
+.. class:: FTP([host[, user[, passwd[, acct[, timeout]]]]])
+
+ Return a new instance of the :class:`FTP` class. When *host* is given, the
+ method call ``connect(host)`` is made. When *user* is given, additionally the
+ method call ``login(user, passwd, acct)`` is made (where *passwd* and *acct*
+ default to the empty string when not given). The optional *timeout* parameter
+ specifies a timeout in seconds for the connection attempt (if is not specified,
+ or passed as None, the global default timeout setting will be used).
+
+ .. versionchanged:: 2.6
+ *timeout* was added.
+
+
+.. data:: all_errors
+
+ The set of all exceptions (as a tuple) that methods of :class:`FTP` instances
+ may raise as a result of problems with the FTP connection (as opposed to
+ programming errors made by the caller). This set includes the four exceptions
+ listed below as well as :exc:`socket.error` and :exc:`IOError`.
+
+
+.. exception:: error_reply
+
+ Exception raised when an unexpected reply is received from the server.
+
+
+.. exception:: error_temp
+
+ Exception raised when an error code in the range 400--499 is received.
+
+
+.. exception:: error_perm
+
+ Exception raised when an error code in the range 500--599 is received.
+
+
+.. exception:: error_proto
+
+ Exception raised when a reply is received from the server that does not begin
+ with a digit in the range 1--5.
+
+
+.. seealso::
+
+ Module :mod:`netrc`
+ Parser for the :file:`.netrc` file format. The file :file:`.netrc` is typically
+ used by FTP clients to load user authentication information before prompting the
+ user.
+
+ .. index:: single: ftpmirror.py
+
+ The file :file:`Tools/scripts/ftpmirror.py` in the Python source distribution is
+ a script that can mirror FTP sites, or portions thereof, using the :mod:`ftplib`
+ module. It can be used as an extended example that applies this module.
+
+
+.. _ftp-objects:
+
+FTP Objects
+-----------
+
+Several methods are available in two flavors: one for handling text files and
+another for binary files. These are named for the command which is used
+followed by ``lines`` for the text version or ``binary`` for the binary version.
+
+:class:`FTP` instances have the following methods:
+
+
+.. method:: FTP.set_debuglevel(level)
+
+ Set the instance's debugging level. This controls the amount of debugging
+ output printed. The default, ``0``, produces no debugging output. A value of
+ ``1`` produces a moderate amount of debugging output, generally a single line
+ per request. A value of ``2`` or higher produces the maximum amount of
+ debugging output, logging each line sent and received on the control connection.
+
+
+.. method:: FTP.connect(host[, port[, timeout]])
+
+ Connect to the given host and port. The default port number is ``21``, as
+ specified by the FTP protocol specification. It is rarely needed to specify a
+ different port number. This function should be called only once for each
+ instance; it should not be called at all if a host was given when the instance
+ was created. All other methods can only be used after a connection has been
+ made.
+
+ The optional *timeout* parameter specifies a timeout in seconds for the
+ connection attempt. If is not specified, or passed as None, the object timeout
+ is used (the timeout that you passed when instantiating the class); if the
+ object timeout is also None, the global default timeout setting will be used.
+
+ .. versionchanged:: 2.6
+ *timeout* was added.
+
+
+.. method:: FTP.getwelcome()
+
+ Return the welcome message sent by the server in reply to the initial
+ connection. (This message sometimes contains disclaimers or help information
+ that may be relevant to the user.)
+
+
+.. method:: FTP.login([user[, passwd[, acct]]])
+
+ Log in as the given *user*. The *passwd* and *acct* parameters are optional and
+ default to the empty string. If no *user* is specified, it defaults to
+ ``'anonymous'``. If *user* is ``'anonymous'``, the default *passwd* is
+ ``'anonymous@'``. This function should be called only once for each instance,
+ after a connection has been established; it should not be called at all if a
+ host and user were given when the instance was created. Most FTP commands are
+ only allowed after the client has logged in.
+
+
+.. method:: FTP.abort()
+
+ Abort a file transfer that is in progress. Using this does not always work, but
+ it's worth a try.
+
+
+.. method:: FTP.sendcmd(command)
+
+ Send a simple command string to the server and return the response string.
+
+
+.. method:: FTP.voidcmd(command)
+
+ Send a simple command string to the server and handle the response. Return
+ nothing if a response code in the range 200--299 is received. Raise an exception
+ otherwise.
+
+
+.. method:: FTP.retrbinary(command, callback[, maxblocksize[, rest]])
+
+ Retrieve a file in binary transfer mode. *command* should be an appropriate
+ ``RETR`` command: ``'RETR filename'``. The *callback* function is called for
+ each block of data received, with a single string argument giving the data
+ block. The optional *maxblocksize* argument specifies the maximum chunk size to
+ read on the low-level socket object created to do the actual transfer (which
+ will also be the largest size of the data blocks passed to *callback*). A
+ reasonable default is chosen. *rest* means the same thing as in the
+ :meth:`transfercmd` method.
+
+
+.. method:: FTP.retrlines(command[, callback])
+
+ Retrieve a file or directory listing in ASCII transfer mode. *command* should be
+ an appropriate ``RETR`` command (see :meth:`retrbinary`) or a ``LIST`` command
+ (usually just the string ``'LIST'``). The *callback* function is called for
+ each line, with the trailing CRLF stripped. The default *callback* prints the
+ line to ``sys.stdout``.
+
+
+.. method:: FTP.set_pasv(boolean)
+
+ Enable "passive" mode if *boolean* is true, other disable passive mode. (In
+ Python 2.0 and before, passive mode was off by default; in Python 2.1 and later,
+ it is on by default.)
+
+
+.. method:: FTP.storbinary(command, file[, blocksize])
+
+ Store a file in binary transfer mode. *command* should be an appropriate
+ ``STOR`` command: ``"STOR filename"``. *file* is an open file object which is
+ read until EOF using its :meth:`read` method in blocks of size *blocksize* to
+ provide the data to be stored. The *blocksize* argument defaults to 8192.
+
+ .. versionchanged:: 2.1
+ default for *blocksize* added.
+
+
+.. method:: FTP.storlines(command, file)
+
+ Store a file in ASCII transfer mode. *command* should be an appropriate
+ ``STOR`` command (see :meth:`storbinary`). Lines are read until EOF from the
+ open file object *file* using its :meth:`readline` method to provide the data to
+ be stored.
+
+
+.. method:: FTP.transfercmd(cmd[, rest])
+
+ Initiate a transfer over the data connection. If the transfer is active, send a
+ ``EPRT`` or ``PORT`` command and the transfer command specified by *cmd*, and
+ accept the connection. If the server is passive, send a ``EPSV`` or ``PASV``
+ command, connect to it, and start the transfer command. Either way, return the
+ socket for the connection.
+
+ If optional *rest* is given, a ``REST`` command is sent to the server, passing
+ *rest* as an argument. *rest* is usually a byte offset into the requested file,
+ telling the server to restart sending the file's bytes at the requested offset,
+ skipping over the initial bytes. Note however that RFC 959 requires only that
+ *rest* be a string containing characters in the printable range from ASCII code
+ 33 to ASCII code 126. The :meth:`transfercmd` method, therefore, converts
+ *rest* to a string, but no check is performed on the string's contents. If the
+ server does not recognize the ``REST`` command, an :exc:`error_reply` exception
+ will be raised. If this happens, simply call :meth:`transfercmd` without a
+ *rest* argument.
+
+
+.. method:: FTP.ntransfercmd(cmd[, rest])
+
+ Like :meth:`transfercmd`, but returns a tuple of the data connection and the
+ expected size of the data. If the expected size could not be computed, ``None``
+ will be returned as the expected size. *cmd* and *rest* means the same thing as
+ in :meth:`transfercmd`.
+
+
+.. method:: FTP.nlst(argument[, ...])
+
+ Return a list of files as returned by the ``NLST`` command. The optional
+ *argument* is a directory to list (default is the current server directory).
+ Multiple arguments can be used to pass non-standard options to the ``NLST``
+ command.
+
+
+.. method:: FTP.dir(argument[, ...])
+
+ Produce a directory listing as returned by the ``LIST`` command, printing it to
+ standard output. The optional *argument* is a directory to list (default is the
+ current server directory). Multiple arguments can be used to pass non-standard
+ options to the ``LIST`` command. If the last argument is a function, it is used
+ as a *callback* function as for :meth:`retrlines`; the default prints to
+ ``sys.stdout``. This method returns ``None``.
+
+
+.. method:: FTP.rename(fromname, toname)
+
+ Rename file *fromname* on the server to *toname*.
+
+
+.. method:: FTP.delete(filename)
+
+ Remove the file named *filename* from the server. If successful, returns the
+ text of the response, otherwise raises :exc:`error_perm` on permission errors or
+ :exc:`error_reply` on other errors.
+
+
+.. method:: FTP.cwd(pathname)
+
+ Set the current directory on the server.
+
+
+.. method:: FTP.mkd(pathname)
+
+ Create a new directory on the server.
+
+
+.. method:: FTP.pwd()
+
+ Return the pathname of the current directory on the server.
+
+
+.. method:: FTP.rmd(dirname)
+
+ Remove the directory named *dirname* on the server.
+
+
+.. method:: FTP.size(filename)
+
+ Request the size of the file named *filename* on the server. On success, the
+ size of the file is returned as an integer, otherwise ``None`` is returned.
+ Note that the ``SIZE`` command is not standardized, but is supported by many
+ common server implementations.
+
+
+.. method:: FTP.quit()
+
+ Send a ``QUIT`` command to the server and close the connection. This is the
+ "polite" way to close a connection, but it may raise an exception of the server
+ reponds with an error to the ``QUIT`` command. This implies a call to the
+ :meth:`close` method which renders the :class:`FTP` instance useless for
+ subsequent calls (see below).
+
+
+.. method:: FTP.close()
+
+ Close the connection unilaterally. This should not be applied to an already
+ closed connection such as after a successful call to :meth:`quit`. After this
+ call the :class:`FTP` instance should not be used any more (after a call to
+ :meth:`close` or :meth:`quit` you cannot reopen the connection by issuing
+ another :meth:`login` method).
+
--- /dev/null
+
+.. _built-in-funcs:
+
+Built-in Functions
+==================
+
+The Python interpreter has a number of functions built into it that are always
+available. They are listed here in alphabetical order.
+
+
+.. function:: __import__(name[, globals[, locals[, fromlist[, level]]]])
+
+ .. index::
+ statement: import
+ module: ihooks
+ module: rexec
+ module: imp
+
+ .. note::
+
+ This is an advanced function that is not needed in everyday Python
+ programming.
+
+ The function is invoked by the :keyword:`import` statement. It mainly exists
+ so that you can replace it with another function that has a compatible
+ interface, in order to change the semantics of the :keyword:`import` statement.
+ For examples of why and how you would do this, see the standard library modules
+ :mod:`ihooks` and :mod:`rexec`. See also the built-in module :mod:`imp`, which
+ defines some useful operations out of which you can build your own
+ :func:`__import__` function.
+
+ For example, the statement ``import spam`` results in the following call:
+ ``__import__('spam',`` ``globals(),`` ``locals(), [], -1)``; the statement
+ ``from spam.ham import eggs`` results in ``__import__('spam.ham', globals(),
+ locals(), ['eggs'], -1)``. Note that even though ``locals()`` and ``['eggs']``
+ are passed in as arguments, the :func:`__import__` function does not set the
+ local variable named ``eggs``; this is done by subsequent code that is generated
+ for the import statement. (In fact, the standard implementation does not use
+ its *locals* argument at all, and uses its *globals* only to determine the
+ package context of the :keyword:`import` statement.)
+
+ When the *name* variable is of the form ``package.module``, normally, the
+ top-level package (the name up till the first dot) is returned, *not* the
+ module named by *name*. However, when a non-empty *fromlist* argument is
+ given, the module named by *name* is returned. This is done for
+ compatibility with the bytecode generated for the different kinds of import
+ statement; when using ``import spam.ham.eggs``, the top-level package
+ :mod:`spam` must be placed in the importing namespace, but when using ``from
+ spam.ham import eggs``, the ``spam.ham`` subpackage must be used to find the
+ ``eggs`` variable. As a workaround for this behavior, use :func:`getattr` to
+ extract the desired components. For example, you could define the following
+ helper::
+
+ def my_import(name):
+ mod = __import__(name)
+ components = name.split('.')
+ for comp in components[1:]:
+ mod = getattr(mod, comp)
+ return mod
+
+ *level* specifies whether to use absolute or relative imports. The default is
+ ``-1`` which indicates both absolute and relative imports will be attempted.
+ ``0`` means only perform absolute imports. Positive values for *level* indicate
+ the number of parent directories to search relative to the directory of the
+ module calling :func:`__import__`.
+
+ .. versionchanged:: 2.5
+ The level parameter was added.
+
+ .. versionchanged:: 2.5
+ Keyword support for parameters was added.
+
+
+.. function:: abs(x)
+
+ Return the absolute value of a number. The argument may be a plain or long
+ integer or a floating point number. If the argument is a complex number, its
+ magnitude is returned.
+
+
+.. function:: all(iterable)
+
+ Return True if all elements of the *iterable* are true. Equivalent to::
+
+ def all(iterable):
+ for element in iterable:
+ if not element:
+ return False
+ return True
+
+ .. versionadded:: 2.5
+
+
+.. function:: any(iterable)
+
+ Return True if any element of the *iterable* is true. Equivalent to::
+
+ def any(iterable):
+ for element in iterable:
+ if element:
+ return True
+ return False
+
+ .. versionadded:: 2.5
+
+
+.. function:: basestring()
+
+ This abstract type is the superclass for :class:`str` and :class:`unicode`. It
+ cannot be called or instantiated, but it can be used to test whether an object
+ is an instance of :class:`str` or :class:`unicode`. ``isinstance(obj,
+ basestring)`` is equivalent to ``isinstance(obj, (str, unicode))``.
+
+ .. versionadded:: 2.3
+
+
+.. function:: bool([x])
+
+ Convert a value to a Boolean, using the standard truth testing procedure. If
+ *x* is false or omitted, this returns :const:`False`; otherwise it returns
+ :const:`True`. :class:`bool` is also a class, which is a subclass of
+ :class:`int`. Class :class:`bool` cannot be subclassed further. Its only
+ instances are :const:`False` and :const:`True`.
+
+ .. index:: pair: Boolean; type
+
+ .. versionadded:: 2.2.1
+
+ .. versionchanged:: 2.3
+ If no argument is given, this function returns :const:`False`.
+
+
+.. function:: callable(object)
+
+ Return :const:`True` if the *object* argument appears callable,
+ :const:`False` if not. If this
+ returns true, it is still possible that a call fails, but if it is false,
+ calling *object* will never succeed. Note that classes are callable (calling a
+ class returns a new instance); class instances are callable if they have a
+ :meth:`__call__` method.
+
+
+.. function:: chr(i)
+
+ Return a string of one character whose ASCII code is the integer *i*. For
+ example, ``chr(97)`` returns the string ``'a'``. This is the inverse of
+ :func:`ord`. The argument must be in the range [0..255], inclusive;
+ :exc:`ValueError` will be raised if *i* is outside that range. See
+ also :func:`unichr`.
+
+
+.. function:: classmethod(function)
+
+ Return a class method for *function*.
+
+ A class method receives the class as implicit first argument, just like an
+ instance method receives the instance. To declare a class method, use this
+ idiom::
+
+ class C:
+ @classmethod
+ def f(cls, arg1, arg2, ...): ...
+
+ The ``@classmethod`` form is a function decorator -- see the description of
+ function definitions in :ref:`function` for details.
+
+ It can be called either on the class (such as ``C.f()``) or on an instance (such
+ as ``C().f()``). The instance is ignored except for its class. If a class
+ method is called for a derived class, the derived class object is passed as the
+ implied first argument.
+
+ Class methods are different than C++ or Java static methods. If you want those,
+ see :func:`staticmethod` in this section.
+
+ For more information on class methods, consult the documentation on the standard
+ type hierarchy in :ref:`types`.
+
+ .. versionadded:: 2.2
+
+ .. versionchanged:: 2.4
+ Function decorator syntax added.
+
+
+.. function:: cmp(x, y)
+
+ Compare the two objects *x* and *y* and return an integer according to the
+ outcome. The return value is negative if ``x < y``, zero if ``x == y`` and
+ strictly positive if ``x > y``.
+
+
+.. function:: compile(source, filename, mode[, flags[, dont_inherit]])
+
+ Compile the *source* into a code object. Code objects can be executed by an
+ :keyword:`exec` statement or evaluated by a call to :func:`eval`. The
+ *filename* argument should give the file from which the code was read; pass some
+ recognizable value if it wasn't read from a file (``'<string>'`` is commonly
+ used). The *mode* argument specifies what kind of code must be compiled; it can
+ be ``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it
+ consists of a single expression, or ``'single'`` if it consists of a single
+ interactive statement (in the latter case, expression statements that evaluate
+ to something else than ``None`` will be printed).
+
+ When compiling multi-line statements, two caveats apply: line endings must be
+ represented by a single newline character (``'\n'``), and the input must be
+ terminated by at least one newline character. If line endings are represented
+ by ``'\r\n'``, use the string :meth:`replace` method to change them into
+ ``'\n'``.
+
+ The optional arguments *flags* and *dont_inherit* (which are new in Python 2.2)
+ control which future statements (see :pep:`236`) affect the compilation of
+ *source*. If neither is present (or both are zero) the code is compiled with
+ those future statements that are in effect in the code that is calling compile.
+ If the *flags* argument is given and *dont_inherit* is not (or is zero) then the
+ future statements specified by the *flags* argument are used in addition to
+ those that would be used anyway. If *dont_inherit* is a non-zero integer then
+ the *flags* argument is it -- the future statements in effect around the call to
+ compile are ignored.
+
+ Future statements are specified by bits which can be bitwise or-ed together to
+ specify multiple statements. The bitfield required to specify a given feature
+ can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature`
+ instance in the :mod:`__future__` module.
+
+
+.. function:: complex([real[, imag]])
+
+ Create a complex number with the value *real* + *imag*\*j or convert a string or
+ number to a complex number. If the first parameter is a string, it will be
+ interpreted as a complex number and the function must be called without a second
+ parameter. The second parameter can never be a string. Each argument may be any
+ numeric type (including complex). If *imag* is omitted, it defaults to zero and
+ the function serves as a numeric conversion function like :func:`int`,
+ :func:`long` and :func:`float`. If both arguments are omitted, returns ``0j``.
+
+ The complex type is described in :ref:`typesnumeric`.
+
+
+.. function:: delattr(object, name)
+
+ This is a relative of :func:`setattr`. The arguments are an object and a
+ string. The string must be the name of one of the object's attributes. The
+ function deletes the named attribute, provided the object allows it. For
+ example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
+
+
+.. function:: dict([arg])
+ :noindex:
+
+ Create a new data dictionary, optionally with items taken from *arg*.
+ The dictionary type is described in :ref:`typesmapping`.
+
+ For other containers see the built in :class:`list`, :class:`set`, and
+ :class:`tuple` classes, and the :mod:`collections` module.
+
+
+.. function:: dir([object])
+
+ Without arguments, return the list of names in the current local scope. With an
+ argument, attempt to return a list of valid attributes for that object.
+
+ If the object has a method named :meth:`__dir__`, this method will be called and
+ must return the list of attributes. This allows objects that implement a custom
+ :func:`__getattr__` or :func:`__getattribute__` function to customize the way
+ :func:`dir` reports their attributes.
+
+ If the object does not provide :meth:`__dir__`, the function tries its best to
+ gather information from the object's :attr:`__dict__` attribute, if defined, and
+ from its type object. The resulting list is not necessarily complete, and may
+ be inaccurate when the object has a custom :func:`__getattr__`.
+
+ The default :func:`dir` mechanism behaves differently with different types of
+ objects, as it attempts to produce the most relevant, rather than complete,
+ information:
+
+ * If the object is a module object, the list contains the names of the module's
+ attributes.
+
+ * If the object is a type or class object, the list contains the names of its
+ attributes, and recursively of the attributes of its bases.
+
+ * Otherwise, the list contains the object's attributes' names, the names of its
+ class's attributes, and recursively of the attributes of its class's base
+ classes.
+
+ The resulting list is sorted alphabetically. For example::
+
+ >>> import struct
+ >>> dir()
+ ['__builtins__', '__doc__', '__name__', 'struct']
+ >>> dir(struct)
+ ['__doc__', '__name__', 'calcsize', 'error', 'pack', 'unpack']
+ >>> class Foo(object):
+ ... def __dir__(self):
+ ... return ["kan", "ga", "roo"]
+ ...
+ >>> f = Foo()
+ >>> dir(f)
+ ['ga', 'kan', 'roo']
+
+ .. note::
+
+ Because :func:`dir` is supplied primarily as a convenience for use at an
+ interactive prompt, it tries to supply an interesting set of names more than it
+ tries to supply a rigorously or consistently defined set of names, and its
+ detailed behavior may change across releases.
+
+
+.. function:: divmod(a, b)
+
+ Take two (non complex) numbers as arguments and return a pair of numbers
+ consisting of their quotient and remainder when using long division. With mixed
+ operand types, the rules for binary arithmetic operators apply. For plain and
+ long integers, the result is the same as ``(a // b, a % b)``. For floating point
+ numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a / b)``
+ but may be 1 less than that. In any case ``q * b + a % b`` is very close to
+ *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0 <= abs(a % b)
+ < abs(b)``.
+
+ .. versionchanged:: 2.3
+ Using :func:`divmod` with complex numbers is deprecated.
+
+
+.. function:: enumerate(iterable)
+
+ Return an enumerate object. *iterable* must be a sequence, an iterator, or some
+ other object which supports iteration. The :meth:`next` method of the iterator
+ returned by :func:`enumerate` returns a tuple containing a count (from zero) and
+ the corresponding value obtained from iterating over *iterable*.
+ :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``,
+ ``(1, seq[1])``, ``(2, seq[2])``, .... For example::
+
+ >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter')]:
+ >>> print i, season
+ 0 Spring
+ 1 Summer
+ 2 Fall
+ 3 Winter
+
+ .. versionadded:: 2.3
+
+
+.. function:: eval(expression[, globals[, locals]])
+
+ The arguments are a string and optional globals and locals. If provided,
+ *globals* must be a dictionary. If provided, *locals* can be any mapping
+ object.
+
+ .. versionchanged:: 2.4
+ formerly *locals* was required to be a dictionary.
+
+ The *expression* argument is parsed and evaluated as a Python expression
+ (technically speaking, a condition list) using the *globals* and *locals*
+ dictionaries as global and local name space. If the *globals* dictionary is
+ present and lacks '__builtins__', the current globals are copied into *globals*
+ before *expression* is parsed. This means that *expression* normally has full
+ access to the standard :mod:`__builtin__` module and restricted environments are
+ propagated. If the *locals* dictionary is omitted it defaults to the *globals*
+ dictionary. If both dictionaries are omitted, the expression is executed in the
+ environment where :keyword:`eval` is called. The return value is the result of
+ the evaluated expression. Syntax errors are reported as exceptions. Example::
+
+ >>> x = 1
+ >>> print eval('x+1')
+ 2
+
+ This function can also be used to execute arbitrary code objects (such as those
+ created by :func:`compile`). In this case pass a code object instead of a
+ string. The code object must have been compiled passing ``'eval'`` as the
+ *kind* argument.
+
+ Hints: dynamic execution of statements is supported by the :keyword:`exec`
+ statement. Execution of statements from a file is supported by the
+ :func:`execfile` function. The :func:`globals` and :func:`locals` functions
+ returns the current global and local dictionary, respectively, which may be
+ useful to pass around for use by :func:`eval` or :func:`execfile`.
+
+
+.. function:: execfile(filename[, globals[, locals]])
+
+ This function is similar to the :keyword:`exec` statement, but parses a file
+ instead of a string. It is different from the :keyword:`import` statement in
+ that it does not use the module administration --- it reads the file
+ unconditionally and does not create a new module. [#]_
+
+ The arguments are a file name and two optional dictionaries. The file is parsed
+ and evaluated as a sequence of Python statements (similarly to a module) using
+ the *globals* and *locals* dictionaries as global and local namespace. If
+ provided, *locals* can be any mapping object.
+
+ .. versionchanged:: 2.4
+ formerly *locals* was required to be a dictionary.
+
+ If the *locals* dictionary is omitted it defaults to the *globals* dictionary.
+ If both dictionaries are omitted, the expression is executed in the environment
+ where :func:`execfile` is called. The return value is ``None``.
+
+ .. warning::
+
+ The default *locals* act as described for function :func:`locals` below:
+ modifications to the default *locals* dictionary should not be attempted. Pass
+ an explicit *locals* dictionary if you need to see effects of the code on
+ *locals* after function :func:`execfile` returns. :func:`execfile` cannot be
+ used reliably to modify a function's locals.
+
+
+.. function:: file(filename[, mode[, bufsize]])
+
+ Constructor function for the :class:`file` type, described further in section
+ :ref:`bltin-file-objects`. The constructor's arguments are the same as those
+ of the :func:`open` built-in function described below.
+
+ When opening a file, it's preferable to use :func:`open` instead of invoking
+ this constructor directly. :class:`file` is more suited to type testing (for
+ example, writing ``isinstance(f, file)``).
+
+ .. versionadded:: 2.2
+
+
+.. function:: filter(function, iterable)
+
+ Construct a list from those elements of *iterable* for which *function* returns
+ true. *iterable* may be either a sequence, a container which supports
+ iteration, or an iterator, If *iterable* is a string or a tuple, the result
+ also has that type; otherwise it is always a list. If *function* is ``None``,
+ the identity function is assumed, that is, all elements of *iterable* that are
+ false are removed.
+
+ Note that ``filter(function, iterable)`` is equivalent to ``[item for item in
+ iterable if function(item)]`` if function is not ``None`` and ``[item for item
+ in iterable if item]`` if function is ``None``.
+
+
+.. function:: float([x])
+
+ Convert a string or a number to floating point. If the argument is a string, it
+ must contain a possibly signed decimal or floating point number, possibly
+ embedded in whitespace. Otherwise, the argument may be a plain or long integer
+ or a floating point number, and a floating point number with the same value
+ (within Python's floating point precision) is returned. If no argument is
+ given, returns ``0.0``.
+
+ .. note::
+
+ .. index::
+ single: NaN
+ single: Infinity
+
+ When passing in a string, values for NaN and Infinity may be returned, depending
+ on the underlying C library. The specific set of strings accepted which cause
+ these values to be returned depends entirely on the C library and is known to
+ vary.
+
+ The float type is described in :ref:`typesnumeric`.
+
+.. function:: frozenset([iterable])
+ :noindex:
+
+ Return a frozenset object, optionally with elements taken from *iterable*.
+ The frozenset type is described in :ref:`types-set`.
+
+ For other containers see the built in :class:`dict`, :class:`list`, and
+ :class:`tuple` classes, and the :mod:`collections` module.
+
+ .. versionadded:: 2.4
+
+
+.. function:: getattr(object, name[, default])
+
+ Return the value of the named attributed of *object*. *name* must be a string.
+ If the string is the name of one of the object's attributes, the result is the
+ value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to
+ ``x.foobar``. If the named attribute does not exist, *default* is returned if
+ provided, otherwise :exc:`AttributeError` is raised.
+
+
+.. function:: globals()
+
+ Return a dictionary representing the current global symbol table. This is always
+ the dictionary of the current module (inside a function or method, this is the
+ module where it is defined, not the module from which it is called).
+
+
+.. function:: hasattr(object, name)
+
+ The arguments are an object and a string. The result is ``True`` if the string
+ is the name of one of the object's attributes, ``False`` if not. (This is
+ implemented by calling ``getattr(object, name)`` and seeing whether it raises an
+ exception or not.)
+
+
+.. function:: hash(object)
+
+ Return the hash value of the object (if it has one). Hash values are integers.
+ They are used to quickly compare dictionary keys during a dictionary lookup.
+ Numeric values that compare equal have the same hash value (even if they are of
+ different types, as is the case for 1 and 1.0).
+
+
+.. function:: help([object])
+
+ Invoke the built-in help system. (This function is intended for interactive
+ use.) If no argument is given, the interactive help system starts on the
+ interpreter console. If the argument is a string, then the string is looked up
+ as the name of a module, function, class, method, keyword, or documentation
+ topic, and a help page is printed on the console. If the argument is any other
+ kind of object, a help page on the object is generated.
+
+ .. versionadded:: 2.2
+
+
+.. function:: hex(x)
+
+ Convert an integer number (of any size) to a hexadecimal string. The result is a
+ valid Python expression.
+
+ .. versionchanged:: 2.4
+ Formerly only returned an unsigned literal.
+
+
+.. function:: id(object)
+
+ Return the "identity" of an object. This is an integer (or long integer) which
+ is guaranteed to be unique and constant for this object during its lifetime.
+ Two objects with non-overlapping lifetimes may have the same :func:`id` value.
+ (Implementation note: this is the address of the object.)
+
+
+.. function:: input([prompt])
+
+ Equivalent to ``eval(raw_input(prompt))``.
+
+ .. warning::
+
+ This function is not safe from user errors! It expects a valid Python
+ expression as input; if the input is not syntactically valid, a
+ :exc:`SyntaxError` will be raised. Other exceptions may be raised if there is an
+ error during evaluation. (On the other hand, sometimes this is exactly what you
+ need when writing a quick script for expert use.)
+
+ If the :mod:`readline` module was loaded, then :func:`input` will use it to
+ provide elaborate line editing and history features.
+
+ Consider using the :func:`raw_input` function for general input from users.
+
+
+.. function:: int([x[, radix]])
+
+ Convert a string or number to a plain integer. If the argument is a string, it
+ must contain a possibly signed decimal number representable as a Python integer,
+ possibly embedded in whitespace. The *radix* parameter gives the base for the
+ conversion and may be any integer in the range [2, 36], or zero. If *radix* is
+ zero, the proper radix is guessed based on the contents of string; the
+ interpretation is the same as for integer literals. If *radix* is specified and
+ *x* is not a string, :exc:`TypeError` is raised. Otherwise, the argument may be
+ a plain or long integer or a floating point number. Conversion of floating
+ point numbers to integers truncates (towards zero). If the argument is outside
+ the integer range a long object will be returned instead. If no arguments are
+ given, returns ``0``.
+
+ The integer type is described in :ref:`typesnumeric`.
+
+
+.. function:: isinstance(object, classinfo)
+
+ Return true if the *object* argument is an instance of the *classinfo* argument,
+ or of a (direct or indirect) subclass thereof. Also return true if *classinfo*
+ is a type object (new-style class) and *object* is an object of that type or of
+ a (direct or indirect) subclass thereof. If *object* is not a class instance or
+ an object of the given type, the function always returns false. If *classinfo*
+ is neither a class object nor a type object, it may be a tuple of class or type
+ objects, or may recursively contain other such tuples (other sequence types are
+ not accepted). If *classinfo* is not a class, type, or tuple of classes, types,
+ and such tuples, a :exc:`TypeError` exception is raised.
+
+ .. versionchanged:: 2.2
+ Support for a tuple of type information was added.
+
+
+.. function:: issubclass(class, classinfo)
+
+ Return true if *class* is a subclass (direct or indirect) of *classinfo*. A
+ class is considered a subclass of itself. *classinfo* may be a tuple of class
+ objects, in which case every entry in *classinfo* will be checked. In any other
+ case, a :exc:`TypeError` exception is raised.
+
+ .. versionchanged:: 2.3
+ Support for a tuple of type information was added.
+
+
+.. function:: iter(o[, sentinel])
+
+ Return an iterator object. The first argument is interpreted very differently
+ depending on the presence of the second argument. Without a second argument, *o*
+ must be a collection object which supports the iteration protocol (the
+ :meth:`__iter__` method), or it must support the sequence protocol (the
+ :meth:`__getitem__` method with integer arguments starting at ``0``). If it
+ does not support either of those protocols, :exc:`TypeError` is raised. If the
+ second argument, *sentinel*, is given, then *o* must be a callable object. The
+ iterator created in this case will call *o* with no arguments for each call to
+ its :meth:`next` method; if the value returned is equal to *sentinel*,
+ :exc:`StopIteration` will be raised, otherwise the value will be returned.
+
+ .. versionadded:: 2.2
+
+
+.. function:: len(s)
+
+ Return the length (the number of items) of an object. The argument may be a
+ sequence (string, tuple or list) or a mapping (dictionary).
+
+
+.. function:: list([iterable])
+
+ Return a list whose items are the same and in the same order as *iterable*'s
+ items. *iterable* may be either a sequence, a container that supports
+ iteration, or an iterator object. If *iterable* is already a list, a copy is
+ made and returned, similar to ``iterable[:]``. For instance, ``list('abc')``
+ returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``. If
+ no argument is given, returns a new empty list, ``[]``.
+
+ :class:`list` is a mutable sequence type, as documented in
+ :ref:`typesseq`. For other containers see the built in :class:`dict`,
+ :class:`set`, and :class:`tuple` classes, and the :mod:`collections` module.
+
+
+.. function:: locals()
+
+ Update and return a dictionary representing the current local symbol table.
+
+ .. warning::
+
+ The contents of this dictionary should not be modified; changes may not affect
+ the values of local variables used by the interpreter.
+
+ Free variables are returned by *locals* when it is called in a function block.
+ Modifications of free variables may not affect the values used by the
+ interpreter. Free variables are not returned in class blocks.
+
+
+.. function:: long([x[, radix]])
+
+ Convert a string or number to a long integer. If the argument is a string, it
+ must contain a possibly signed number of arbitrary size, possibly embedded in
+ whitespace. The *radix* argument is interpreted in the same way as for
+ :func:`int`, and may only be given when *x* is a string. Otherwise, the argument
+ may be a plain or long integer or a floating point number, and a long integer
+ with the same value is returned. Conversion of floating point numbers to
+ integers truncates (towards zero). If no arguments are given, returns ``0L``.
+
+ The long type is described in :ref:`typesnumeric`.
+
+.. function:: map(function, iterable, ...)
+
+ Apply *function* to every item of *iterable* and return a list of the results.
+ If additional *iterable* arguments are passed, *function* must take that many
+ arguments and is applied to the items from all iterables in parallel. If one
+ iterable is shorter than another it is assumed to be extended with ``None``
+ items. If *function* is ``None``, the identity function is assumed; if there
+ are multiple arguments, :func:`map` returns a list consisting of tuples
+ containing the corresponding items from all iterables (a kind of transpose
+ operation). The *iterable* arguments may be a sequence or any iterable object;
+ the result is always a list.
+
+
+.. function:: max(iterable[, args...][key])
+
+ With a single argument *iterable*, return the largest item of a non-empty
+ iterable (such as a string, tuple or list). With more than one argument, return
+ the largest of the arguments.
+
+ The optional *key* argument specifies a one-argument ordering function like that
+ used for :meth:`list.sort`. The *key* argument, if supplied, must be in keyword
+ form (for example, ``max(a,b,c,key=func)``).
+
+ .. versionchanged:: 2.5
+ Added support for the optional *key* argument.
+
+
+.. function:: min(iterable[, args...][key])
+
+ With a single argument *iterable*, return the smallest item of a non-empty
+ iterable (such as a string, tuple or list). With more than one argument, return
+ the smallest of the arguments.
+
+ The optional *key* argument specifies a one-argument ordering function like that
+ used for :meth:`list.sort`. The *key* argument, if supplied, must be in keyword
+ form (for example, ``min(a,b,c,key=func)``).
+
+ .. versionchanged:: 2.5
+ Added support for the optional *key* argument.
+
+
+.. function:: object()
+
+ Return a new featureless object. :class:`object` is a base for all new style
+ classes. It has the methods that are common to all instances of new style
+ classes.
+
+ .. versionadded:: 2.2
+
+ .. versionchanged:: 2.3
+ This function does not accept any arguments. Formerly, it accepted arguments but
+ ignored them.
+
+
+.. function:: oct(x)
+
+ Convert an integer number (of any size) to an octal string. The result is a
+ valid Python expression.
+
+ .. versionchanged:: 2.4
+ Formerly only returned an unsigned literal.
+
+
+.. function:: open(filename[, mode[, bufsize]])
+
+ Open a file, returning an object of the :class:`file` type described in
+ section :ref:`bltin-file-objects`. If the file cannot be opened,
+ :exc:`IOError` is raised. When opening a file, it's preferable to use
+ :func:`open` instead of invoking the :class:`file` constructor directly.
+
+ The first two arguments are the same as for ``stdio``'s :cfunc:`fopen`:
+ *filename* is the file name to be opened, and *mode* is a string indicating how
+ the file is to be opened.
+
+ The most commonly-used values of *mode* are ``'r'`` for reading, ``'w'`` for
+ writing (truncating the file if it already exists), and ``'a'`` for appending
+ (which on *some* Unix systems means that *all* writes append to the end of the
+ file regardless of the current seek position). If *mode* is omitted, it
+ defaults to ``'r'``. When opening a binary file, you should append ``'b'`` to
+ the *mode* value to open the file in binary mode, which will improve
+ portability. (Appending ``'b'`` is useful even on systems that don't treat
+ binary and text files differently, where it serves as documentation.) See below
+ for more possible values of *mode*.
+
+ .. index::
+ single: line-buffered I/O
+ single: unbuffered I/O
+ single: buffer size, I/O
+ single: I/O control; buffering
+
+ The optional *bufsize* argument specifies the file's desired buffer size: 0
+ means unbuffered, 1 means line buffered, any other positive value means use a
+ buffer of (approximately) that size. A negative *bufsize* means to use the
+ system default, which is usually line buffered for tty devices and fully
+ buffered for other files. If omitted, the system default is used. [#]_
+
+ Modes ``'r+'``, ``'w+'`` and ``'a+'`` open the file for updating (note that
+ ``'w+'`` truncates the file). Append ``'b'`` to the mode to open the file in
+ binary mode, on systems that differentiate between binary and text files; on
+ systems that don't have this distinction, adding the ``'b'`` has no effect.
+
+ In addition to the standard :cfunc:`fopen` values *mode* may be ``'U'`` or
+ ``'rU'``. Python is usually built with universal newline support; supplying
+ ``'U'`` opens the file as a text file, but lines may be terminated by any of the
+ following: the Unix end-of-line convention ``'\n'``, the Macintosh convention
+ ``'\r'``, or the Windows convention ``'\r\n'``. All of these external
+ representations are seen as ``'\n'`` by the Python program. If Python is built
+ without universal newline support a *mode* with ``'U'`` is the same as normal
+ text mode. Note that file objects so opened also have an attribute called
+ :attr:`newlines` which has a value of ``None`` (if no newlines have yet been
+ seen), ``'\n'``, ``'\r'``, ``'\r\n'``, or a tuple containing all the newline
+ types seen.
+
+ Python enforces that the mode, after stripping ``'U'``, begins with ``'r'``,
+ ``'w'`` or ``'a'``.
+
+ See also the :mod:`fileinput` module.
+
+ .. versionchanged:: 2.5
+ Restriction on first letter of mode string introduced.
+
+
+.. function:: ord(c)
+
+ Given a string of length one, return an integer representing the Unicode code
+ point of the character when the argument is a unicode object, or the value of
+ the byte when the argument is an 8-bit string. For example, ``ord('a')`` returns
+ the integer ``97``, ``ord(u'\u2020')`` returns ``8224``. This is the inverse of
+ :func:`chr` for 8-bit strings and of :func:`unichr` for unicode objects. If a
+ unicode argument is given and Python was built with UCS2 Unicode, then the
+ character's code point must be in the range [0..65535] inclusive; otherwise the
+ string length is two, and a :exc:`TypeError` will be raised.
+
+
+.. function:: pow(x, y[, z])
+
+ Return *x* to the power *y*; if *z* is present, return *x* to the power *y*,
+ modulo *z* (computed more efficiently than ``pow(x, y) % z``). The two-argument
+ form ``pow(x, y)`` is equivalent to using the power operator: ``x**y``.
+
+ The arguments must have numeric types. With mixed operand types, the coercion
+ rules for binary arithmetic operators apply. For int and long int operands, the
+ result has the same type as the operands (after coercion) unless the second
+ argument is negative; in that case, all arguments are converted to float and a
+ float result is delivered. For example, ``10**2`` returns ``100``, but
+ ``10**-2`` returns ``0.01``. (This last feature was added in Python 2.2. In
+ Python 2.1 and before, if both arguments were of integer types and the second
+ argument was negative, an exception was raised.) If the second argument is
+ negative, the third argument must be omitted. If *z* is present, *x* and *y*
+ must be of integer types, and *y* must be non-negative. (This restriction was
+ added in Python 2.2. In Python 2.1 and before, floating 3-argument ``pow()``
+ returned platform-dependent results depending on floating-point rounding
+ accidents.)
+
+
+.. function:: property([fget[, fset[, fdel[, doc]]]])
+
+ Return a property attribute for new-style classes (classes that derive from
+ :class:`object`).
+
+ *fget* is a function for getting an attribute value, likewise *fset* is a
+ function for setting, and *fdel* a function for del'ing, an attribute. Typical
+ use is to define a managed attribute x::
+
+ class C(object):
+ def __init__(self): self._x = None
+ def getx(self): return self._x
+ def setx(self, value): self._x = value
+ def delx(self): del self._x
+ x = property(getx, setx, delx, "I'm the 'x' property.")
+
+ If given, *doc* will be the docstring of the property attribute. Otherwise, the
+ property will copy *fget*'s docstring (if it exists). This makes it possible to
+ create read-only properties easily using :func:`property` as a decorator::
+
+ class Parrot(object):
+ def __init__(self):
+ self._voltage = 100000
+
+ @property
+ def voltage(self):
+ """Get the current voltage."""
+ return self._voltage
+
+ turns the :meth:`voltage` method into a "getter" for a read-only attribute with
+ the same name.
+
+ .. versionadded:: 2.2
+
+ .. versionchanged:: 2.5
+ Use *fget*'s docstring if no *doc* given.
+
+
+.. function:: range([start,] stop[, step])
+
+ This is a versatile function to create lists containing arithmetic progressions.
+ It is most often used in :keyword:`for` loops. The arguments must be plain
+ integers. If the *step* argument is omitted, it defaults to ``1``. If the
+ *start* argument is omitted, it defaults to ``0``. The full form returns a list
+ of plain integers ``[start, start + step, start + 2 * step, ...]``. If *step*
+ is positive, the last element is the largest ``start + i * step`` less than
+ *stop*; if *step* is negative, the last element is the smallest ``start + i *
+ step`` greater than *stop*. *step* must not be zero (or else :exc:`ValueError`
+ is raised). Example::
+
+ >>> range(10)
+ [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+ >>> range(1, 11)
+ [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ >>> range(0, 30, 5)
+ [0, 5, 10, 15, 20, 25]
+ >>> range(0, 10, 3)
+ [0, 3, 6, 9]
+ >>> range(0, -10, -1)
+ [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
+ >>> range(0)
+ []
+ >>> range(1, 0)
+ []
+
+
+.. function:: raw_input([prompt])
+
+ If the *prompt* argument is present, it is written to standard output without a
+ trailing newline. The function then reads a line from input, converts it to a
+ string (stripping a trailing newline), and returns that. When EOF is read,
+ :exc:`EOFError` is raised. Example::
+
+ >>> s = raw_input('--> ')
+ --> Monty Python's Flying Circus
+ >>> s
+ "Monty Python's Flying Circus"
+
+ If the :mod:`readline` module was loaded, then :func:`raw_input` will use it to
+ provide elaborate line editing and history features.
+
+
+.. function:: reduce(function, iterable[, initializer])
+
+ Apply *function* of two arguments cumulatively to the items of *iterable*, from
+ left to right, so as to reduce the iterable to a single value. For example,
+ ``reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])`` calculates ``((((1+2)+3)+4)+5)``.
+ The left argument, *x*, is the accumulated value and the right argument, *y*, is
+ the update value from the *iterable*. If the optional *initializer* is present,
+ it is placed before the items of the iterable in the calculation, and serves as
+ a default when the iterable is empty. If *initializer* is not given and
+ *iterable* contains only one item, the first item is returned.
+
+
+.. function:: reload(module)
+
+ Reload a previously imported *module*. The argument must be a module object, so
+ it must have been successfully imported before. This is useful if you have
+ edited the module source file using an external editor and want to try out the
+ new version without leaving the Python interpreter. The return value is the
+ module object (the same as the *module* argument).
+
+ When ``reload(module)`` is executed:
+
+ * Python modules' code is recompiled and the module-level code reexecuted,
+ defining a new set of objects which are bound to names in the module's
+ dictionary. The ``init`` function of extension modules is not called a second
+ time.
+
+ * As with all other objects in Python the old objects are only reclaimed after
+ their reference counts drop to zero.
+
+ * The names in the module namespace are updated to point to any new or changed
+ objects.
+
+ * Other references to the old objects (such as names external to the module) are
+ not rebound to refer to the new objects and must be updated in each namespace
+ where they occur if that is desired.
+
+ There are a number of other caveats:
+
+ If a module is syntactically correct but its initialization fails, the first
+ :keyword:`import` statement for it does not bind its name locally, but does
+ store a (partially initialized) module object in ``sys.modules``. To reload the
+ module you must first :keyword:`import` it again (this will bind the name to the
+ partially initialized module object) before you can :func:`reload` it.
+
+ When a module is reloaded, its dictionary (containing the module's global
+ variables) is retained. Redefinitions of names will override the old
+ definitions, so this is generally not a problem. If the new version of a module
+ does not define a name that was defined by the old version, the old definition
+ remains. This feature can be used to the module's advantage if it maintains a
+ global table or cache of objects --- with a :keyword:`try` statement it can test
+ for the table's presence and skip its initialization if desired::
+
+ try:
+ cache
+ except NameError:
+ cache = {}
+
+ It is legal though generally not very useful to reload built-in or dynamically
+ loaded modules, except for :mod:`sys`, :mod:`__main__` and :mod:`__builtin__`.
+ In many cases, however, extension modules are not designed to be initialized
+ more than once, and may fail in arbitrary ways when reloaded.
+
+ If a module imports objects from another module using :keyword:`from` ...
+ :keyword:`import` ..., calling :func:`reload` for the other module does not
+ redefine the objects imported from it --- one way around this is to re-execute
+ the :keyword:`from` statement, another is to use :keyword:`import` and qualified
+ names (*module*.*name*) instead.
+
+ If a module instantiates instances of a class, reloading the module that defines
+ the class does not affect the method definitions of the instances --- they
+ continue to use the old class definition. The same is true for derived classes.
+
+
+.. function:: repr(object)
+
+ Return a string containing a printable representation of an object. This is the
+ same value yielded by conversions (reverse quotes). It is sometimes useful to be
+ able to access this operation as an ordinary function. For many types, this
+ function makes an attempt to return a string that would yield an object with the
+ same value when passed to :func:`eval`.
+
+
+.. function:: reversed(seq)
+
+ Return a reverse iterator. *seq* must be an object which supports the sequence
+ protocol (the :meth:`__len__` method and the :meth:`__getitem__` method with
+ integer arguments starting at ``0``).
+
+ .. versionadded:: 2.4
+
+
+.. function:: round(x[, n])
+
+ Return the floating point value *x* rounded to *n* digits after the decimal
+ point. If *n* is omitted, it defaults to zero. The result is a floating point
+ number. Values are rounded to the closest multiple of 10 to the power minus
+ *n*; if two multiples are equally close, rounding is done away from 0 (so. for
+ example, ``round(0.5)`` is ``1.0`` and ``round(-0.5)`` is ``-1.0``).
+
+
+.. function:: set([iterable])
+ :noindex:
+
+ Return a new set, optionally with elements are taken from *iterable*.
+ The set type is described in :ref:`types-set`.
+
+ For other containers see the built in :class:`dict`, :class:`list`, and
+ :class:`tuple` classes, and the :mod:`collections` module.
+
+ .. versionadded:: 2.4
+
+
+.. function:: setattr(object, name, value)
+
+ This is the counterpart of :func:`getattr`. The arguments are an object, a
+ string and an arbitrary value. The string may name an existing attribute or a
+ new attribute. The function assigns the value to the attribute, provided the
+ object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to
+ ``x.foobar = 123``.
+
+
+.. function:: slice([start,] stop[, step])
+
+ .. index:: single: Numerical Python
+
+ Return a slice object representing the set of indices specified by
+ ``range(start, stop, step)``. The *start* and *step* arguments default to
+ ``None``. Slice objects have read-only data attributes :attr:`start`,
+ :attr:`stop` and :attr:`step` which merely return the argument values (or their
+ default). They have no other explicit functionality; however they are used by
+ Numerical Python and other third party extensions. Slice objects are also
+ generated when extended indexing syntax is used. For example:
+ ``a[start:stop:step]`` or ``a[start:stop, i]``.
+
+
+.. function:: sorted(iterable[, cmp[, key[, reverse]]])
+
+ Return a new sorted list from the items in *iterable*.
+
+ The optional arguments *cmp*, *key*, and *reverse* have the same meaning as
+ those for the :meth:`list.sort` method (described in section
+ :ref:`typesseq-mutable`).
+
+ *cmp* specifies a custom comparison function of two arguments (iterable
+ elements) which should return a negative, zero or positive number depending on
+ whether the first argument is considered smaller than, equal to, or larger than
+ the second argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())``
+
+ *key* specifies a function of one argument that is used to extract a comparison
+ key from each list element: ``key=str.lower``
+
+ *reverse* is a boolean value. If set to ``True``, then the list elements are
+ sorted as if each comparison were reversed.
+
+ In general, the *key* and *reverse* conversion processes are much faster than
+ specifying an equivalent *cmp* function. This is because *cmp* is called
+ multiple times for each list element while *key* and *reverse* touch each
+ element only once.
+
+ .. versionadded:: 2.4
+
+
+.. function:: staticmethod(function)
+
+ Return a static method for *function*.
+
+ A static method does not receive an implicit first argument. To declare a static
+ method, use this idiom::
+
+ class C:
+ @staticmethod
+ def f(arg1, arg2, ...): ...
+
+ The ``@staticmethod`` form is a function decorator -- see the description of
+ function definitions in :ref:`function` for details.
+
+ It can be called either on the class (such as ``C.f()``) or on an instance (such
+ as ``C().f()``). The instance is ignored except for its class.
+
+ Static methods in Python are similar to those found in Java or C++. For a more
+ advanced concept, see :func:`classmethod` in this section.
+
+ For more information on static methods, consult the documentation on the
+ standard type hierarchy in :ref:`types`.
+
+ .. versionadded:: 2.2
+
+ .. versionchanged:: 2.4
+ Function decorator syntax added.
+
+
+.. function:: str([object])
+
+ Return a string containing a nicely printable representation of an object. For
+ strings, this returns the string itself. The difference with ``repr(object)``
+ is that ``str(object)`` does not always attempt to return a string that is
+ acceptable to :func:`eval`; its goal is to return a printable string. If no
+ argument is given, returns the empty string, ``''``.
+
+ For more information on strings see :ref:`typesseq` which describes sequence
+ functionality (strings are sequences), and also the string-specific methods
+ described in the :ref:`string-methods` section. To output formatted strings
+ use template strings or the ``%`` operator described in the
+ :ref:`string-formatting` section. In addition see the :ref:`stringservices`
+ section. See also :func:`unicode`.
+
+
+.. function:: sum(iterable[, start])
+
+ Sums *start* and the items of an *iterable* from left to right and returns the
+ total. *start* defaults to ``0``. The *iterable*'s items are normally numbers,
+ and are not allowed to be strings. The fast, correct way to concatenate a
+ sequence of strings is by calling ``''.join(sequence)``. Note that
+ ``sum(range(n), m)`` is equivalent to ``reduce(operator.add, range(n), m)``
+
+ .. versionadded:: 2.3
+
+
+.. function:: super(type[, object-or-type])
+
+ Return the superclass of *type*. If the second argument is omitted the super
+ object returned is unbound. If the second argument is an object,
+ ``isinstance(obj, type)`` must be true. If the second argument is a type,
+ ``issubclass(type2, type)`` must be true. :func:`super` only works for new-style
+ classes.
+
+ A typical use for calling a cooperative superclass method is::
+
+ class C(B):
+ def meth(self, arg):
+ super(C, self).meth(arg)
+
+ Note that :func:`super` is implemented as part of the binding process for
+ explicit dotted attribute lookups such as ``super(C, self).__getitem__(name)``.
+ Accordingly, :func:`super` is undefined for implicit lookups using statements or
+ operators such as ``super(C, self)[name]``.
+
+ .. versionadded:: 2.2
+
+
+.. function:: tuple([iterable])
+
+ Return a tuple whose items are the same and in the same order as *iterable*'s
+ items. *iterable* may be a sequence, a container that supports iteration, or an
+ iterator object. If *iterable* is already a tuple, it is returned unchanged.
+ For instance, ``tuple('abc')`` returns ``('a', 'b', 'c')`` and ``tuple([1, 2,
+ 3])`` returns ``(1, 2, 3)``. If no argument is given, returns a new empty
+ tuple, ``()``.
+
+ :class:`tuple` is an immutable sequence type, as documented in
+ :ref:`typesseq`. For other containers see the built in :class:`dict`,
+ :class:`list`, and :class:`set` classes, and the :mod:`collections` module.
+
+
+.. function:: type(object)
+
+ .. index:: object: type
+
+ Return the type of an *object*. The return value is a type object. The
+ :func:`isinstance` built-in function is recommended for testing the type of an
+ object.
+
+ With three arguments, :func:`type` functions as a constructor as detailed below.
+
+
+.. function:: type(name, bases, dict)
+ :noindex:
+
+ Return a new type object. This is essentially a dynamic form of the
+ :keyword:`class` statement. The *name* string is the class name and becomes the
+ :attr:`__name__` attribute; the *bases* tuple itemizes the base classes and
+ becomes the :attr:`__bases__` attribute; and the *dict* dictionary is the
+ namespace containing definitions for class body and becomes the :attr:`__dict__`
+ attribute. For example, the following two statements create identical
+ :class:`type` objects::
+
+ >>> class X(object):
+ ... a = 1
+ ...
+ >>> X = type('X', (object,), dict(a=1))
+
+ .. versionadded:: 2.2
+
+
+.. function:: unichr(i)
+
+ Return the Unicode string of one character whose Unicode code is the integer
+ *i*. For example, ``unichr(97)`` returns the string ``u'a'``. This is the
+ inverse of :func:`ord` for Unicode strings. The valid range for the argument
+ depends how Python was configured -- it may be either UCS2 [0..0xFFFF] or UCS4
+ [0..0x10FFFF]. :exc:`ValueError` is raised otherwise. For ASCII and 8-bit
+ strings see :func:`chr`.
+
+ .. versionadded:: 2.0
+
+
+.. function:: unicode([object[, encoding [, errors]]])
+
+ Return the Unicode string version of *object* using one of the following modes:
+
+ If *encoding* and/or *errors* are given, ``unicode()`` will decode the object
+ which can either be an 8-bit string or a character buffer using the codec for
+ *encoding*. The *encoding* parameter is a string giving the name of an encoding;
+ if the encoding is not known, :exc:`LookupError` is raised. Error handling is
+ done according to *errors*; this specifies the treatment of characters which are
+ invalid in the input encoding. If *errors* is ``'strict'`` (the default), a
+ :exc:`ValueError` is raised on errors, while a value of ``'ignore'`` causes
+ errors to be silently ignored, and a value of ``'replace'`` causes the official
+ Unicode replacement character, ``U+FFFD``, to be used to replace input
+ characters which cannot be decoded. See also the :mod:`codecs` module.
+
+ If no optional parameters are given, ``unicode()`` will mimic the behaviour of
+ ``str()`` except that it returns Unicode strings instead of 8-bit strings. More
+ precisely, if *object* is a Unicode string or subclass it will return that
+ Unicode string without any additional decoding applied.
+
+ For objects which provide a :meth:`__unicode__` method, it will call this method
+ without arguments to create a Unicode string. For all other objects, the 8-bit
+ string version or representation is requested and then converted to a Unicode
+ string using the codec for the default encoding in ``'strict'`` mode.
+
+ For more information on Unicode strings see :ref:`typesseq` which describes
+ sequence functionality (Unicode strings are sequences), and also the
+ string-specific methods described in the :ref:`string-methods` section. To
+ output formatted strings use template strings or the ``%`` operator described
+ in the :ref:`string-formatting` section. In addition see the
+ :ref:`stringservices` section. See also :func:`str`.
+
+ .. versionadded:: 2.0
+
+ .. versionchanged:: 2.2
+ Support for :meth:`__unicode__` added.
+
+
+.. function:: vars([object])
+
+ Without arguments, return a dictionary corresponding to the current local symbol
+ table. With a module, class or class instance object as argument (or anything
+ else that has a :attr:`__dict__` attribute), returns a dictionary corresponding
+ to the object's symbol table. The returned dictionary should not be modified:
+ the effects on the corresponding symbol table are undefined. [#]_
+
+
+.. function:: xrange([start,] stop[, step])
+
+ This function is very similar to :func:`range`, but returns an "xrange object"
+ instead of a list. This is an opaque sequence type which yields the same values
+ as the corresponding list, without actually storing them all simultaneously.
+ The advantage of :func:`xrange` over :func:`range` is minimal (since
+ :func:`xrange` still has to create the values when asked for them) except when a
+ very large range is used on a memory-starved machine or when all of the range's
+ elements are never used (such as when the loop is usually terminated with
+ :keyword:`break`).
+
+ .. note::
+
+ :func:`xrange` is intended to be simple and fast. Implementations may impose
+ restrictions to achieve this. The C implementation of Python restricts all
+ arguments to native C longs ("short" Python integers), and also requires that
+ the number of elements fit in a native C long.
+
+
+.. function:: zip([iterable, ...])
+
+ This function returns a list of tuples, where the *i*-th tuple contains the
+ *i*-th element from each of the argument sequences or iterables. The returned
+ list is truncated in length to the length of the shortest argument sequence.
+ When there are multiple arguments which are all of the same length, :func:`zip`
+ is similar to :func:`map` with an initial argument of ``None``. With a single
+ sequence argument, it returns a list of 1-tuples. With no arguments, it returns
+ an empty list.
+
+ .. versionadded:: 2.0
+
+ .. versionchanged:: 2.4
+ Formerly, :func:`zip` required at least one argument and ``zip()`` raised a
+ :exc:`TypeError` instead of returning an empty list.
+
+.. % ---------------------------------------------------------------------------
+
+
+.. _non-essential-built-in-funcs:
+
+Non-essential Built-in Functions
+================================
+
+There are several built-in functions that are no longer essential to learn, know
+or use in modern Python programming. They have been kept here to maintain
+backwards compatibility with programs written for older versions of Python.
+
+Python programmers, trainers, students and bookwriters should feel free to
+bypass these functions without concerns about missing something important.
+
+
+.. function:: apply(function, args[, keywords])
+
+ The *function* argument must be a callable object (a user-defined or built-in
+ function or method, or a class object) and the *args* argument must be a
+ sequence. The *function* is called with *args* as the argument list; the number
+ of arguments is the length of the tuple. If the optional *keywords* argument is
+ present, it must be a dictionary whose keys are strings. It specifies keyword
+ arguments to be added to the end of the argument list. Calling :func:`apply` is
+ different from just calling ``function(args)``, since in that case there is
+ always exactly one argument. The use of :func:`apply` is equivalent to
+ ``function(*args, **keywords)``. Use of :func:`apply` is not necessary since the
+ "extended call syntax," as used in the last example, is completely equivalent.
+
+ .. deprecated:: 2.3
+ Use the extended call syntax instead, as described above.
+
+
+.. function:: buffer(object[, offset[, size]])
+
+ The *object* argument must be an object that supports the buffer call interface
+ (such as strings, arrays, and buffers). A new buffer object will be created
+ which references the *object* argument. The buffer object will be a slice from
+ the beginning of *object* (or from the specified *offset*). The slice will
+ extend to the end of *object* (or will have a length given by the *size*
+ argument).
+
+
+.. function:: coerce(x, y)
+
+ Return a tuple consisting of the two numeric arguments converted to a common
+ type, using the same rules as used by arithmetic operations. If coercion is not
+ possible, raise :exc:`TypeError`.
+
+
+.. function:: intern(string)
+
+ Enter *string* in the table of "interned" strings and return the interned string
+ -- which is *string* itself or a copy. Interning strings is useful to gain a
+ little performance on dictionary lookup -- if the keys in a dictionary are
+ interned, and the lookup key is interned, the key comparisons (after hashing)
+ can be done by a pointer compare instead of a string compare. Normally, the
+ names used in Python programs are automatically interned, and the dictionaries
+ used to hold module, class or instance attributes have interned keys.
+
+ .. versionchanged:: 2.3
+ Interned strings are not immortal (like they used to be in Python 2.2 and
+ before); you must keep a reference to the return value of :func:`intern` around
+ to benefit from it.
+
+.. rubric:: Footnotes
+
+.. [#] It is used relatively rarely so does not warrant being made into a statement.
+
+.. [#] Specifying a buffer size currently has no effect on systems that don't have
+ :cfunc:`setvbuf`. The interface to specify the buffer size is not done using a
+ method that calls :cfunc:`setvbuf`, because that may dump core when called after
+ any I/O has been performed, and there's no reliable way to determine whether
+ this is the case.
+
+.. [#] In the current implementation, local variable bindings cannot normally be
+ affected this way, but variables retrieved from other scopes (such as modules)
+ can be. This may change.
+
--- /dev/null
+:mod:`functools` --- Higher order functions and operations on callable objects
+==============================================================================
+
+.. module:: functools
+ :synopsis: Higher order functions and operations on callable objects.
+.. moduleauthor:: Peter Harris <scav@blueyonder.co.uk>
+.. moduleauthor:: Raymond Hettinger <python@rcn.com>
+.. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
+.. sectionauthor:: Peter Harris <scav@blueyonder.co.uk>
+
+
+.. versionadded:: 2.5
+
+The :mod:`functools` module is for higher-order functions: functions that act on
+or return other functions. In general, any callable object can be treated as a
+function for the purposes of this module.
+
+The :mod:`functools` module defines the following function:
+
+
+.. function:: partial(func[,*args][, **keywords])
+
+ Return a new :class:`partial` object which when called will behave like *func*
+ called with the positional arguments *args* and keyword arguments *keywords*. If
+ more arguments are supplied to the call, they are appended to *args*. If
+ additional keyword arguments are supplied, they extend and override *keywords*.
+ Roughly equivalent to::
+
+ def partial(func, *args, **keywords):
+ def newfunc(*fargs, **fkeywords):
+ newkeywords = keywords.copy()
+ newkeywords.update(fkeywords)
+ return func(*(args + fargs), **newkeywords)
+ newfunc.func = func
+ newfunc.args = args
+ newfunc.keywords = keywords
+ return newfunc
+
+ The :func:`partial` is used for partial function application which "freezes"
+ some portion of a function's arguments and/or keywords resulting in a new object
+ with a simplified signature. For example, :func:`partial` can be used to create
+ a callable that behaves like the :func:`int` function where the *base* argument
+ defaults to two::
+
+ >>> basetwo = partial(int, base=2)
+ >>> basetwo.__doc__ = 'Convert base 2 string to an int.'
+ >>> basetwo('10010')
+ 18
+
+
+.. function:: update_wrapper(wrapper, wrapped[, assigned][, updated])
+
+ Update a *wrapper* function to look like the *wrapped* function. The optional
+ arguments are tuples to specify which attributes of the original function are
+ assigned directly to the matching attributes on the wrapper function and which
+ attributes of the wrapper function are updated with the corresponding attributes
+ from the original function. The default values for these arguments are the
+ module level constants *WRAPPER_ASSIGNMENTS* (which assigns to the wrapper
+ function's *__name__*, *__module__* and *__doc__*, the documentation string) and
+ *WRAPPER_UPDATES* (which updates the wrapper function's *__dict__*, i.e. the
+ instance dictionary).
+
+ The main intended use for this function is in decorator functions which wrap the
+ decorated function and return the wrapper. If the wrapper function is not
+ updated, the metadata of the returned function will reflect the wrapper
+ definition rather than the original function definition, which is typically less
+ than helpful.
+
+
+.. function:: wraps(wrapped[, assigned][, updated])
+
+ This is a convenience function for invoking ``partial(update_wrapper,
+ wrapped=wrapped, assigned=assigned, updated=updated)`` as a function decorator
+ when defining a wrapper function. For example::
+
+ >>> def my_decorator(f):
+ ... @wraps(f)
+ ... def wrapper(*args, **kwds):
+ ... print 'Calling decorated function'
+ ... return f(*args, **kwds)
+ ... return wrapper
+ ...
+ >>> @my_decorator
+ ... def example():
+ ... """Docstring"""
+ ... print 'Called example function'
+ ...
+ >>> example()
+ Calling decorated function
+ Called example function
+ >>> example.__name__
+ 'example'
+ >>> example.__doc__
+ 'Docstring'
+
+ Without the use of this decorator factory, the name of the example function
+ would have been ``'wrapper'``, and the docstring of the original :func:`example`
+ would have been lost.
+
+
+.. _partial-objects:
+
+:class:`partial` Objects
+------------------------
+
+:class:`partial` objects are callable objects created by :func:`partial`. They
+have three read-only attributes:
+
+
+.. attribute:: partial.func
+
+ A callable object or function. Calls to the :class:`partial` object will be
+ forwarded to :attr:`func` with new arguments and keywords.
+
+
+.. attribute:: partial.args
+
+ The leftmost positional arguments that will be prepended to the positional
+ arguments provided to a :class:`partial` object call.
+
+
+.. attribute:: partial.keywords
+
+ The keyword arguments that will be supplied when the :class:`partial` object is
+ called.
+
+:class:`partial` objects are like :class:`function` objects in that they are
+callable, weak referencable, and can have attributes. There are some important
+differences. For instance, the :attr:`__name__` and :attr:`__doc__` attributes
+are not created automatically. Also, :class:`partial` objects defined in
+classes behave like static methods and do not transform into bound methods
+during instance attribute look-up.
+
--- /dev/null
+
+:mod:`gc` --- Garbage Collector interface
+=========================================
+
+.. module:: gc
+ :synopsis: Interface to the cycle-detecting garbage collector.
+.. moduleauthor:: Neil Schemenauer <nas@arctrix.com>
+.. sectionauthor:: Neil Schemenauer <nas@arctrix.com>
+
+
+This module provides an interface to the optional garbage collector. It
+provides the ability to disable the collector, tune the collection frequency,
+and set debugging options. It also provides access to unreachable objects that
+the collector found but cannot free. Since the collector supplements the
+reference counting already used in Python, you can disable the collector if you
+are sure your program does not create reference cycles. Automatic collection
+can be disabled by calling ``gc.disable()``. To debug a leaking program call
+``gc.set_debug(gc.DEBUG_LEAK)``. Notice that this includes
+``gc.DEBUG_SAVEALL``, causing garbage-collected objects to be saved in
+gc.garbage for inspection.
+
+The :mod:`gc` module provides the following functions:
+
+
+.. function:: enable()
+
+ Enable automatic garbage collection.
+
+
+.. function:: disable()
+
+ Disable automatic garbage collection.
+
+
+.. function:: isenabled()
+
+ Returns true if automatic collection is enabled.
+
+
+.. function:: collect([generation])
+
+ With no arguments, run a full collection. The optional argument *generation*
+ may be an integer specifying which generation to collect (from 0 to 2). A
+ :exc:`ValueError` is raised if the generation number is invalid. The number of
+ unreachable objects found is returned.
+
+ .. versionchanged:: 2.5
+ The optional *generation* argument was added.
+
+
+.. function:: set_debug(flags)
+
+ Set the garbage collection debugging flags. Debugging information will be
+ written to ``sys.stderr``. See below for a list of debugging flags which can be
+ combined using bit operations to control debugging.
+
+
+.. function:: get_debug()
+
+ Return the debugging flags currently set.
+
+
+.. function:: get_objects()
+
+ Returns a list of all objects tracked by the collector, excluding the list
+ returned.
+
+ .. versionadded:: 2.2
+
+
+.. function:: set_threshold(threshold0[, threshold1[, threshold2]])
+
+ Set the garbage collection thresholds (the collection frequency). Setting
+ *threshold0* to zero disables collection.
+
+ The GC classifies objects into three generations depending on how many
+ collection sweeps they have survived. New objects are placed in the youngest
+ generation (generation ``0``). If an object survives a collection it is moved
+ into the next older generation. Since generation ``2`` is the oldest
+ generation, objects in that generation remain there after a collection. In
+ order to decide when to run, the collector keeps track of the number object
+ allocations and deallocations since the last collection. When the number of
+ allocations minus the number of deallocations exceeds *threshold0*, collection
+ starts. Initially only generation ``0`` is examined. If generation ``0`` has
+ been examined more than *threshold1* times since generation ``1`` has been
+ examined, then generation ``1`` is examined as well. Similarly, *threshold2*
+ controls the number of collections of generation ``1`` before collecting
+ generation ``2``.
+
+
+.. function:: get_count()
+
+ Return the current collection counts as a tuple of ``(count0, count1,
+ count2)``.
+
+ .. versionadded:: 2.5
+
+
+.. function:: get_threshold()
+
+ Return the current collection thresholds as a tuple of ``(threshold0,
+ threshold1, threshold2)``.
+
+
+.. function:: get_referrers(*objs)
+
+ Return the list of objects that directly refer to any of objs. This function
+ will only locate those containers which support garbage collection; extension
+ types which do refer to other objects but do not support garbage collection will
+ not be found.
+
+ Note that objects which have already been dereferenced, but which live in cycles
+ and have not yet been collected by the garbage collector can be listed among the
+ resulting referrers. To get only currently live objects, call :func:`collect`
+ before calling :func:`get_referrers`.
+
+ Care must be taken when using objects returned by :func:`get_referrers` because
+ some of them could still be under construction and hence in a temporarily
+ invalid state. Avoid using :func:`get_referrers` for any purpose other than
+ debugging.
+
+ .. versionadded:: 2.2
+
+
+.. function:: get_referents(*objs)
+
+ Return a list of objects directly referred to by any of the arguments. The
+ referents returned are those objects visited by the arguments' C-level
+ :attr:`tp_traverse` methods (if any), and may not be all objects actually
+ directly reachable. :attr:`tp_traverse` methods are supported only by objects
+ that support garbage collection, and are only required to visit objects that may
+ be involved in a cycle. So, for example, if an integer is directly reachable
+ from an argument, that integer object may or may not appear in the result list.
+
+ .. versionadded:: 2.3
+
+The following variable is provided for read-only access (you can mutate its
+value but should not rebind it):
+
+
+.. data:: garbage
+
+ A list of objects which the collector found to be unreachable but could not be
+ freed (uncollectable objects). By default, this list contains only objects with
+ :meth:`__del__` methods. [#]_ Objects that have :meth:`__del__` methods and are
+ part of a reference cycle cause the entire reference cycle to be uncollectable,
+ including objects not necessarily in the cycle but reachable only from it.
+ Python doesn't collect such cycles automatically because, in general, it isn't
+ possible for Python to guess a safe order in which to run the :meth:`__del__`
+ methods. If you know a safe order, you can force the issue by examining the
+ *garbage* list, and explicitly breaking cycles due to your objects within the
+ list. Note that these objects are kept alive even so by virtue of being in the
+ *garbage* list, so they should be removed from *garbage* too. For example,
+ after breaking cycles, do ``del gc.garbage[:]`` to empty the list. It's
+ generally better to avoid the issue by not creating cycles containing objects
+ with :meth:`__del__` methods, and *garbage* can be examined in that case to
+ verify that no such cycles are being created.
+
+ If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be added to
+ this list rather than freed.
+
+The following constants are provided for use with :func:`set_debug`:
+
+
+.. data:: DEBUG_STATS
+
+ Print statistics during collection. This information can be useful when tuning
+ the collection frequency.
+
+
+.. data:: DEBUG_COLLECTABLE
+
+ Print information on collectable objects found.
+
+
+.. data:: DEBUG_UNCOLLECTABLE
+
+ Print information of uncollectable objects found (objects which are not
+ reachable but cannot be freed by the collector). These objects will be added to
+ the ``garbage`` list.
+
+
+.. data:: DEBUG_INSTANCES
+
+ When :const:`DEBUG_COLLECTABLE` or :const:`DEBUG_UNCOLLECTABLE` is set, print
+ information about instance objects found.
+
+
+.. data:: DEBUG_OBJECTS
+
+ When :const:`DEBUG_COLLECTABLE` or :const:`DEBUG_UNCOLLECTABLE` is set, print
+ information about objects other than instance objects found.
+
+
+.. data:: DEBUG_SAVEALL
+
+ When set, all unreachable objects found will be appended to *garbage* rather
+ than being freed. This can be useful for debugging a leaking program.
+
+
+.. data:: DEBUG_LEAK
+
+ The debugging flags necessary for the collector to print information about a
+ leaking program (equal to ``DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE |
+ DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALL``).
+
+.. rubric:: Footnotes
+
+.. [#] Prior to Python 2.2, the list contained all instance objects in unreachable
+ cycles, not only those with :meth:`__del__` methods.
+
--- /dev/null
+
+:mod:`gdbm` --- GNU's reinterpretation of dbm
+=============================================
+
+.. module:: gdbm
+ :platform: Unix
+ :synopsis: GNU's reinterpretation of dbm.
+
+
+.. index:: module: dbm
+
+This module is quite similar to the :mod:`dbm` module, but uses ``gdbm`` instead
+to provide some additional functionality. Please note that the file formats
+created by ``gdbm`` and ``dbm`` are incompatible.
+
+The :mod:`gdbm` module provides an interface to the GNU DBM library. ``gdbm``
+objects behave like mappings (dictionaries), except that keys and values are
+always strings. Printing a ``gdbm`` object doesn't print the keys and values,
+and the :meth:`items` and :meth:`values` methods are not supported.
+
+The module defines the following constant and functions:
+
+
+.. exception:: error
+
+ Raised on ``gdbm``\ -specific errors, such as I/O errors. :exc:`KeyError` is
+ raised for general mapping errors like specifying an incorrect key.
+
+
+.. function:: open(filename, [flag, [mode]])
+
+ Open a ``gdbm`` database and return a ``gdbm`` object. The *filename* argument
+ is the name of the database file.
+
+ The optional *flag* argument can be:
+
+ +---------+-------------------------------------------+
+ | Value | Meaning |
+ +=========+===========================================+
+ | ``'r'`` | Open existing database for reading only |
+ | | (default) |
+ +---------+-------------------------------------------+
+ | ``'w'`` | Open existing database for reading and |
+ | | writing |
+ +---------+-------------------------------------------+
+ | ``'c'`` | Open database for reading and writing, |
+ | | creating it if it doesn't exist |
+ +---------+-------------------------------------------+
+ | ``'n'`` | Always create a new, empty database, open |
+ | | for reading and writing |
+ +---------+-------------------------------------------+
+
+ The following additional characters may be appended to the flag to control
+ how the database is opened:
+
+ +---------+--------------------------------------------+
+ | Value | Meaning |
+ +=========+============================================+
+ | ``'f'`` | Open the database in fast mode. Writes |
+ | | to the database will not be synchronized. |
+ +---------+--------------------------------------------+
+ | ``'s'`` | Synchronized mode. This will cause changes |
+ | | to the database to be immediately written |
+ | | to the file. |
+ +---------+--------------------------------------------+
+ | ``'u'`` | Do not lock database. |
+ +---------+--------------------------------------------+
+
+ Not all flags are valid for all versions of ``gdbm``. The module constant
+ :const:`open_flags` is a string of supported flag characters. The exception
+ :exc:`error` is raised if an invalid flag is specified.
+
+ The optional *mode* argument is the Unix mode of the file, used only when the
+ database has to be created. It defaults to octal ``0666``.
+
+In addition to the dictionary-like methods, ``gdbm`` objects have the following
+methods:
+
+
+.. function:: firstkey()
+
+ It's possible to loop over every key in the database using this method and the
+ :meth:`nextkey` method. The traversal is ordered by ``gdbm``'s internal hash
+ values, and won't be sorted by the key values. This method returns the starting
+ key.
+
+
+.. function:: nextkey(key)
+
+ Returns the key that follows *key* in the traversal. The following code prints
+ every key in the database ``db``, without having to create a list in memory that
+ contains them all::
+
+ k = db.firstkey()
+ while k != None:
+ print k
+ k = db.nextkey(k)
+
+
+.. function:: reorganize()
+
+ If you have carried out a lot of deletions and would like to shrink the space
+ used by the ``gdbm`` file, this routine will reorganize the database. ``gdbm``
+ will not shorten the length of a database file except by using this
+ reorganization; otherwise, deleted file space will be kept and reused as new
+ (key, value) pairs are added.
+
+
+.. function:: sync()
+
+ When the database has been opened in fast mode, this method forces any
+ unwritten data to be written to the disk.
+
+
+.. seealso::
+
+ Module :mod:`anydbm`
+ Generic interface to ``dbm``\ -style databases.
+
+ Module :mod:`whichdb`
+ Utility module used to determine the type of an existing database.
+
--- /dev/null
+
+:mod:`gensuitemodule` --- Generate OSA stub packages
+====================================================
+
+.. module:: gensuitemodule
+ :platform: Mac
+ :synopsis: Create a stub package from an OSA dictionary
+.. sectionauthor:: Jack Jansen <Jack.Jansen@cwi.nl>
+
+
+.. % \moduleauthor{Jack Jansen?}{email}
+
+The :mod:`gensuitemodule` module creates a Python package implementing stub code
+for the AppleScript suites that are implemented by a specific application,
+according to its AppleScript dictionary.
+
+It is usually invoked by the user through the :program:`PythonIDE`, but it can
+also be run as a script from the command line (pass :option:`--help` for help on
+the options) or imported from Python code. For an example of its use see
+:file:`Mac/scripts/genallsuites.py` in a source distribution, which generates
+the stub packages that are included in the standard library.
+
+It defines the following public functions:
+
+
+.. function:: is_scriptable(application)
+
+ Returns true if ``application``, which should be passed as a pathname, appears
+ to be scriptable. Take the return value with a grain of salt: :program:`Internet
+ Explorer` appears not to be scriptable but definitely is.
+
+
+.. function:: processfile(application[, output, basepkgname, edit_modnames, creatorsignature, dump, verbose])
+
+ Create a stub package for ``application``, which should be passed as a full
+ pathname. For a :file:`.app` bundle this is the pathname to the bundle, not to
+ the executable inside the bundle; for an unbundled CFM application you pass the
+ filename of the application binary.
+
+ This function asks the application for its OSA terminology resources, decodes
+ these resources and uses the resultant data to create the Python code for the
+ package implementing the client stubs.
+
+ ``output`` is the pathname where the resulting package is stored, if not
+ specified a standard "save file as" dialog is presented to the user.
+ ``basepkgname`` is the base package on which this package will build, and
+ defaults to :mod:`StdSuites`. Only when generating :mod:`StdSuites` itself do
+ you need to specify this. ``edit_modnames`` is a dictionary that can be used to
+ change modulenames that are too ugly after name mangling. ``creator_signature``
+ can be used to override the 4-char creator code, which is normally obtained from
+ the :file:`PkgInfo` file in the package or from the CFM file creator signature.
+ When ``dump`` is given it should refer to a file object, and ``processfile``
+ will stop after decoding the resources and dump the Python representation of the
+ terminology resources to this file. ``verbose`` should also be a file object,
+ and specifying it will cause ``processfile`` to tell you what it is doing.
+
+
+.. function:: processfile_fromresource(application[, output, basepkgname, edit_modnames, creatorsignature, dump, verbose])
+
+ This function does the same as ``processfile``, except that it uses a different
+ method to get the terminology resources. It opens ``application`` as a resource
+ file and reads all ``"aete"`` and ``"aeut"`` resources from this file.
+
--- /dev/null
+
+:mod:`getopt` --- Parser for command line options
+=================================================
+
+.. module:: getopt
+ :synopsis: Portable parser for command line options; support both short and long option
+ names.
+
+
+This module helps scripts to parse the command line arguments in ``sys.argv``.
+It supports the same conventions as the Unix :cfunc:`getopt` function (including
+the special meanings of arguments of the form '``-``' and '``-``\ ``-``'). Long
+options similar to those supported by GNU software may be used as well via an
+optional third argument. This module provides a single function and an
+exception:
+
+.. % That's to fool latex2html into leaving the two hyphens alone!
+
+
+.. function:: getopt(args, options[, long_options])
+
+ Parses command line options and parameter list. *args* is the argument list to
+ be parsed, without the leading reference to the running program. Typically, this
+ means ``sys.argv[1:]``. *options* is the string of option letters that the
+ script wants to recognize, with options that require an argument followed by a
+ colon (``':'``; i.e., the same format that Unix :cfunc:`getopt` uses).
+
+ .. note::
+
+ Unlike GNU :cfunc:`getopt`, after a non-option argument, all further arguments
+ are considered also non-options. This is similar to the way non-GNU Unix systems
+ work.
+
+ *long_options*, if specified, must be a list of strings with the names of the
+ long options which should be supported. The leading ``'-``\ ``-'`` characters
+ should not be included in the option name. Long options which require an
+ argument should be followed by an equal sign (``'='``). To accept only long
+ options, *options* should be an empty string. Long options on the command line
+ can be recognized so long as they provide a prefix of the option name that
+ matches exactly one of the accepted options. For example, if *long_options* is
+ ``['foo', 'frob']``, the option :option:`--fo` will match as :option:`--foo`,
+ but :option:`--f` will not match uniquely, so :exc:`GetoptError` will be raised.
+
+ The return value consists of two elements: the first is a list of ``(option,
+ value)`` pairs; the second is the list of program arguments left after the
+ option list was stripped (this is a trailing slice of *args*). Each
+ option-and-value pair returned has the option as its first element, prefixed
+ with a hyphen for short options (e.g., ``'-x'``) or two hyphens for long
+ options (e.g., ``'-``\ ``-long-option'``), and the option argument as its
+ second element, or an empty string if the option has no argument. The
+ options occur in the list in the same order in which they were found, thus
+ allowing multiple occurrences. Long and short options may be mixed.
+
+
+.. function:: gnu_getopt(args, options[, long_options])
+
+ This function works like :func:`getopt`, except that GNU style scanning mode is
+ used by default. This means that option and non-option arguments may be
+ intermixed. The :func:`getopt` function stops processing options as soon as a
+ non-option argument is encountered.
+
+ If the first character of the option string is '+', or if the environment
+ variable POSIXLY_CORRECT is set, then option processing stops as soon as a
+ non-option argument is encountered.
+
+ .. versionadded:: 2.3
+
+
+.. exception:: GetoptError
+
+ This is raised when an unrecognized option is found in the argument list or when
+ an option requiring an argument is given none. The argument to the exception is
+ a string indicating the cause of the error. For long options, an argument given
+ to an option which does not require one will also cause this exception to be
+ raised. The attributes :attr:`msg` and :attr:`opt` give the error message and
+ related option; if there is no specific option to which the exception relates,
+ :attr:`opt` is an empty string.
+
+ .. versionchanged:: 1.6
+ Introduced :exc:`GetoptError` as a synonym for :exc:`error`.
+
+
+.. exception:: error
+
+ Alias for :exc:`GetoptError`; for backward compatibility.
+
+An example using only Unix style options::
+
+ >>> import getopt
+ >>> args = '-a -b -cfoo -d bar a1 a2'.split()
+ >>> args
+ ['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
+ >>> optlist, args = getopt.getopt(args, 'abc:d:')
+ >>> optlist
+ [('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
+ >>> args
+ ['a1', 'a2']
+
+Using long option names is equally easy::
+
+ >>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
+ >>> args = s.split()
+ >>> args
+ ['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
+ >>> optlist, args = getopt.getopt(args, 'x', [
+ ... 'condition=', 'output-file=', 'testing'])
+ >>> optlist
+ [('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x',
+ '')]
+ >>> args
+ ['a1', 'a2']
+
+In a script, typical usage is something like this::
+
+ import getopt, sys
+
+ def main():
+ try:
+ opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
+ except getopt.GetoptError, err:
+ # print help information and exit:
+ print str(err) # will print something like "option -a not recognized"
+ usage()
+ sys.exit(2)
+ output = None
+ verbose = False
+ for o, a in opts:
+ if o == "-v":
+ verbose = True
+ elif o in ("-h", "--help"):
+ usage()
+ sys.exit()
+ elif o in ("-o", "--output"):
+ output = a
+ else:
+ assert False, "unhandled option"
+ # ...
+
+ if __name__ == "__main__":
+ main()
+
+
+.. seealso::
+
+ Module :mod:`optparse`
+ More object-oriented command line option parsing.
+
--- /dev/null
+
+:mod:`getpass` --- Portable password input
+==========================================
+
+.. module:: getpass
+ :synopsis: Portable reading of passwords and retrieval of the userid.
+.. moduleauthor:: Piers Lauder <piers@cs.su.oz.au>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+.. % Windows (& Mac?) support by Guido van Rossum.
+
+The :mod:`getpass` module provides two functions:
+
+
+.. function:: getpass([prompt[, stream]])
+
+ Prompt the user for a password without echoing. The user is prompted using the
+ string *prompt*, which defaults to ``'Password: '``. On Unix, the prompt is
+ written to the file-like object *stream*, which defaults to ``sys.stdout`` (this
+ argument is ignored on Windows).
+
+ Availability: Macintosh, Unix, Windows.
+
+ .. versionchanged:: 2.5
+ The *stream* parameter was added.
+
+
+.. function:: getuser()
+
+ Return the "login name" of the user. Availability: Unix, Windows.
+
+ This function checks the environment variables :envvar:`LOGNAME`,
+ :envvar:`USER`, :envvar:`LNAME` and :envvar:`USERNAME`, in order, and returns
+ the value of the first one which is set to a non-empty string. If none are set,
+ the login name from the password database is returned on systems which support
+ the :mod:`pwd` module, otherwise, an exception is raised.
+
--- /dev/null
+
+:mod:`gettext` --- Multilingual internationalization services
+=============================================================
+
+.. module:: gettext
+ :synopsis: Multilingual internationalization services.
+.. moduleauthor:: Barry A. Warsaw <barry@zope.com>
+.. sectionauthor:: Barry A. Warsaw <barry@zope.com>
+
+
+The :mod:`gettext` module provides internationalization (I18N) and localization
+(L10N) services for your Python modules and applications. It supports both the
+GNU ``gettext`` message catalog API and a higher level, class-based API that may
+be more appropriate for Python files. The interface described below allows you
+to write your module and application messages in one natural language, and
+provide a catalog of translated messages for running under different natural
+languages.
+
+Some hints on localizing your Python modules and applications are also given.
+
+
+GNU :program:`gettext` API
+--------------------------
+
+The :mod:`gettext` module defines the following API, which is very similar to
+the GNU :program:`gettext` API. If you use this API you will affect the
+translation of your entire application globally. Often this is what you want if
+your application is monolingual, with the choice of language dependent on the
+locale of your user. If you are localizing a Python module, or if your
+application needs to switch languages on the fly, you probably want to use the
+class-based API instead.
+
+
+.. function:: bindtextdomain(domain[, localedir])
+
+ Bind the *domain* to the locale directory *localedir*. More concretely,
+ :mod:`gettext` will look for binary :file:`.mo` files for the given domain using
+ the path (on Unix): :file:`localedir/language/LC_MESSAGES/domain.mo`, where
+ *languages* is searched for in the environment variables :envvar:`LANGUAGE`,
+ :envvar:`LC_ALL`, :envvar:`LC_MESSAGES`, and :envvar:`LANG` respectively.
+
+ If *localedir* is omitted or ``None``, then the current binding for *domain* is
+ returned. [#]_
+
+
+.. function:: bind_textdomain_codeset(domain[, codeset])
+
+ Bind the *domain* to *codeset*, changing the encoding of strings returned by the
+ :func:`gettext` family of functions. If *codeset* is omitted, then the current
+ binding is returned.
+
+ .. versionadded:: 2.4
+
+
+.. function:: textdomain([domain])
+
+ Change or query the current global domain. If *domain* is ``None``, then the
+ current global domain is returned, otherwise the global domain is set to
+ *domain*, which is returned.
+
+
+.. function:: gettext(message)
+
+ Return the localized translation of *message*, based on the current global
+ domain, language, and locale directory. This function is usually aliased as
+ :func:`_` in the local namespace (see examples below).
+
+
+.. function:: lgettext(message)
+
+ Equivalent to :func:`gettext`, but the translation is returned in the preferred
+ system encoding, if no other encoding was explicitly set with
+ :func:`bind_textdomain_codeset`.
+
+ .. versionadded:: 2.4
+
+
+.. function:: dgettext(domain, message)
+
+ Like :func:`gettext`, but look the message up in the specified *domain*.
+
+
+.. function:: ldgettext(domain, message)
+
+ Equivalent to :func:`dgettext`, but the translation is returned in the preferred
+ system encoding, if no other encoding was explicitly set with
+ :func:`bind_textdomain_codeset`.
+
+ .. versionadded:: 2.4
+
+
+.. function:: ngettext(singular, plural, n)
+
+ Like :func:`gettext`, but consider plural forms. If a translation is found,
+ apply the plural formula to *n*, and return the resulting message (some
+ languages have more than two plural forms). If no translation is found, return
+ *singular* if *n* is 1; return *plural* otherwise.
+
+ The Plural formula is taken from the catalog header. It is a C or Python
+ expression that has a free variable *n*; the expression evaluates to the index
+ of the plural in the catalog. See the GNU gettext documentation for the precise
+ syntax to be used in :file:`.po` files and the formulas for a variety of
+ languages.
+
+ .. versionadded:: 2.3
+
+
+.. function:: lngettext(singular, plural, n)
+
+ Equivalent to :func:`ngettext`, but the translation is returned in the preferred
+ system encoding, if no other encoding was explicitly set with
+ :func:`bind_textdomain_codeset`.
+
+ .. versionadded:: 2.4
+
+
+.. function:: dngettext(domain, singular, plural, n)
+
+ Like :func:`ngettext`, but look the message up in the specified *domain*.
+
+ .. versionadded:: 2.3
+
+
+.. function:: ldngettext(domain, singular, plural, n)
+
+ Equivalent to :func:`dngettext`, but the translation is returned in the
+ preferred system encoding, if no other encoding was explicitly set with
+ :func:`bind_textdomain_codeset`.
+
+ .. versionadded:: 2.4
+
+Note that GNU :program:`gettext` also defines a :func:`dcgettext` method, but
+this was deemed not useful and so it is currently unimplemented.
+
+Here's an example of typical usage for this API::
+
+ import gettext
+ gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
+ gettext.textdomain('myapplication')
+ _ = gettext.gettext
+ # ...
+ print _('This is a translatable string.')
+
+
+Class-based API
+---------------
+
+The class-based API of the :mod:`gettext` module gives you more flexibility and
+greater convenience than the GNU :program:`gettext` API. It is the recommended
+way of localizing your Python applications and modules. :mod:`gettext` defines
+a "translations" class which implements the parsing of GNU :file:`.mo` format
+files, and has methods for returning either standard 8-bit strings or Unicode
+strings. Instances of this "translations" class can also install themselves in
+the built-in namespace as the function :func:`_`.
+
+
+.. function:: find(domain[, localedir[, languages[, all]]])
+
+ This function implements the standard :file:`.mo` file search algorithm. It
+ takes a *domain*, identical to what :func:`textdomain` takes. Optional
+ *localedir* is as in :func:`bindtextdomain` Optional *languages* is a list of
+ strings, where each string is a language code.
+
+ If *localedir* is not given, then the default system locale directory is used.
+ [#]_ If *languages* is not given, then the following environment variables are
+ searched: :envvar:`LANGUAGE`, :envvar:`LC_ALL`, :envvar:`LC_MESSAGES`, and
+ :envvar:`LANG`. The first one returning a non-empty value is used for the
+ *languages* variable. The environment variables should contain a colon separated
+ list of languages, which will be split on the colon to produce the expected list
+ of language code strings.
+
+ :func:`find` then expands and normalizes the languages, and then iterates
+ through them, searching for an existing file built of these components:
+
+ :file:`localedir/language/LC_MESSAGES/domain.mo`
+
+ The first such file name that exists is returned by :func:`find`. If no such
+ file is found, then ``None`` is returned. If *all* is given, it returns a list
+ of all file names, in the order in which they appear in the languages list or
+ the environment variables.
+
+
+.. function:: translation(domain[, localedir[, languages[, class_[, fallback[, codeset]]]]])
+
+ Return a :class:`Translations` instance based on the *domain*, *localedir*, and
+ *languages*, which are first passed to :func:`find` to get a list of the
+ associated :file:`.mo` file paths. Instances with identical :file:`.mo` file
+ names are cached. The actual class instantiated is either *class_* if provided,
+ otherwise :class:`GNUTranslations`. The class's constructor must take a single
+ file object argument. If provided, *codeset* will change the charset used to
+ encode translated strings.
+
+ If multiple files are found, later files are used as fallbacks for earlier ones.
+ To allow setting the fallback, :func:`copy.copy` is used to clone each
+ translation object from the cache; the actual instance data is still shared with
+ the cache.
+
+ If no :file:`.mo` file is found, this function raises :exc:`IOError` if
+ *fallback* is false (which is the default), and returns a
+ :class:`NullTranslations` instance if *fallback* is true.
+
+ .. versionchanged:: 2.4
+ Added the *codeset* parameter.
+
+
+.. function:: install(domain[, localedir[, unicode [, codeset[, names]]]])
+
+ This installs the function :func:`_` in Python's builtin namespace, based on
+ *domain*, *localedir*, and *codeset* which are passed to the function
+ :func:`translation`. The *unicode* flag is passed to the resulting translation
+ object's :meth:`install` method.
+
+ For the *names* parameter, please see the description of the translation
+ object's :meth:`install` method.
+
+ As seen below, you usually mark the strings in your application that are
+ candidates for translation, by wrapping them in a call to the :func:`_`
+ function, like this::
+
+ print _('This string will be translated.')
+
+ For convenience, you want the :func:`_` function to be installed in Python's
+ builtin namespace, so it is easily accessible in all modules of your
+ application.
+
+ .. versionchanged:: 2.4
+ Added the *codeset* parameter.
+
+ .. versionchanged:: 2.5
+ Added the *names* parameter.
+
+
+The :class:`NullTranslations` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Translation classes are what actually implement the translation of original
+source file message strings to translated message strings. The base class used
+by all translation classes is :class:`NullTranslations`; this provides the basic
+interface you can use to write your own specialized translation classes. Here
+are the methods of :class:`NullTranslations`:
+
+
+.. method:: NullTranslations.__init__([fp])
+
+ Takes an optional file object *fp*, which is ignored by the base class.
+ Initializes "protected" instance variables *_info* and *_charset* which are set
+ by derived classes, as well as *_fallback*, which is set through
+ :meth:`add_fallback`. It then calls ``self._parse(fp)`` if *fp* is not
+ ``None``.
+
+
+.. method:: NullTranslations._parse(fp)
+
+ No-op'd in the base class, this method takes file object *fp*, and reads the
+ data from the file, initializing its message catalog. If you have an
+ unsupported message catalog file format, you should override this method to
+ parse your format.
+
+
+.. method:: NullTranslations.add_fallback(fallback)
+
+ Add *fallback* as the fallback object for the current translation object. A
+ translation object should consult the fallback if it cannot provide a
+ translation for a given message.
+
+
+.. method:: NullTranslations.gettext(message)
+
+ If a fallback has been set, forward :meth:`gettext` to the fallback. Otherwise,
+ return the translated message. Overridden in derived classes.
+
+
+.. method:: NullTranslations.lgettext(message)
+
+ If a fallback has been set, forward :meth:`lgettext` to the fallback. Otherwise,
+ return the translated message. Overridden in derived classes.
+
+ .. versionadded:: 2.4
+
+
+.. method:: NullTranslations.ugettext(message)
+
+ If a fallback has been set, forward :meth:`ugettext` to the fallback. Otherwise,
+ return the translated message as a Unicode string. Overridden in derived
+ classes.
+
+
+.. method:: NullTranslations.ngettext(singular, plural, n)
+
+ If a fallback has been set, forward :meth:`ngettext` to the fallback. Otherwise,
+ return the translated message. Overridden in derived classes.
+
+ .. versionadded:: 2.3
+
+
+.. method:: NullTranslations.lngettext(singular, plural, n)
+
+ If a fallback has been set, forward :meth:`ngettext` to the fallback. Otherwise,
+ return the translated message. Overridden in derived classes.
+
+ .. versionadded:: 2.4
+
+
+.. method:: NullTranslations.ungettext(singular, plural, n)
+
+ If a fallback has been set, forward :meth:`ungettext` to the fallback.
+ Otherwise, return the translated message as a Unicode string. Overridden in
+ derived classes.
+
+ .. versionadded:: 2.3
+
+
+.. method:: NullTranslations.info()
+
+ Return the "protected" :attr:`_info` variable.
+
+
+.. method:: NullTranslations.charset()
+
+ Return the "protected" :attr:`_charset` variable.
+
+
+.. method:: NullTranslations.output_charset()
+
+ Return the "protected" :attr:`_output_charset` variable, which defines the
+ encoding used to return translated messages.
+
+ .. versionadded:: 2.4
+
+
+.. method:: NullTranslations.set_output_charset(charset)
+
+ Change the "protected" :attr:`_output_charset` variable, which defines the
+ encoding used to return translated messages.
+
+ .. versionadded:: 2.4
+
+
+.. method:: NullTranslations.install([unicode [, names]])
+
+ If the *unicode* flag is false, this method installs :meth:`self.gettext` into
+ the built-in namespace, binding it to ``_``. If *unicode* is true, it binds
+ :meth:`self.ugettext` instead. By default, *unicode* is false.
+
+ If the *names* parameter is given, it must be a sequence containing the names of
+ functions you want to install in the builtin namespace in addition to :func:`_`.
+ Supported names are ``'gettext'`` (bound to :meth:`self.gettext` or
+ :meth:`self.ugettext` according to the *unicode* flag), ``'ngettext'`` (bound to
+ :meth:`self.ngettext` or :meth:`self.ungettext` according to the *unicode*
+ flag), ``'lgettext'`` and ``'lngettext'``.
+
+ Note that this is only one way, albeit the most convenient way, to make the
+ :func:`_` function available to your application. Because it affects the entire
+ application globally, and specifically the built-in namespace, localized modules
+ should never install :func:`_`. Instead, they should use this code to make
+ :func:`_` available to their module::
+
+ import gettext
+ t = gettext.translation('mymodule', ...)
+ _ = t.gettext
+
+ This puts :func:`_` only in the module's global namespace and so only affects
+ calls within this module.
+
+ .. versionchanged:: 2.5
+ Added the *names* parameter.
+
+
+The :class:`GNUTranslations` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :mod:`gettext` module provides one additional class derived from
+:class:`NullTranslations`: :class:`GNUTranslations`. This class overrides
+:meth:`_parse` to enable reading GNU :program:`gettext` format :file:`.mo` files
+in both big-endian and little-endian format. It also coerces both message ids
+and message strings to Unicode.
+
+:class:`GNUTranslations` parses optional meta-data out of the translation
+catalog. It is convention with GNU :program:`gettext` to include meta-data as
+the translation for the empty string. This meta-data is in :rfc:`822`\ -style
+``key: value`` pairs, and should contain the ``Project-Id-Version`` key. If the
+key ``Content-Type`` is found, then the ``charset`` property is used to
+initialize the "protected" :attr:`_charset` instance variable, defaulting to
+``None`` if not found. If the charset encoding is specified, then all message
+ids and message strings read from the catalog are converted to Unicode using
+this encoding. The :meth:`ugettext` method always returns a Unicode, while the
+:meth:`gettext` returns an encoded 8-bit string. For the message id arguments
+of both methods, either Unicode strings or 8-bit strings containing only
+US-ASCII characters are acceptable. Note that the Unicode version of the
+methods (i.e. :meth:`ugettext` and :meth:`ungettext`) are the recommended
+interface to use for internationalized Python programs.
+
+The entire set of key/value pairs are placed into a dictionary and set as the
+"protected" :attr:`_info` instance variable.
+
+If the :file:`.mo` file's magic number is invalid, or if other problems occur
+while reading the file, instantiating a :class:`GNUTranslations` class can raise
+:exc:`IOError`.
+
+The following methods are overridden from the base class implementation:
+
+
+.. method:: GNUTranslations.gettext(message)
+
+ Look up the *message* id in the catalog and return the corresponding message
+ string, as an 8-bit string encoded with the catalog's charset encoding, if
+ known. If there is no entry in the catalog for the *message* id, and a fallback
+ has been set, the look up is forwarded to the fallback's :meth:`gettext` method.
+ Otherwise, the *message* id is returned.
+
+
+.. method:: GNUTranslations.lgettext(message)
+
+ Equivalent to :meth:`gettext`, but the translation is returned in the preferred
+ system encoding, if no other encoding was explicitly set with
+ :meth:`set_output_charset`.
+
+ .. versionadded:: 2.4
+
+
+.. method:: GNUTranslations.ugettext(message)
+
+ Look up the *message* id in the catalog and return the corresponding message
+ string, as a Unicode string. If there is no entry in the catalog for the
+ *message* id, and a fallback has been set, the look up is forwarded to the
+ fallback's :meth:`ugettext` method. Otherwise, the *message* id is returned.
+
+
+.. method:: GNUTranslations.ngettext(singular, plural, n)
+
+ Do a plural-forms lookup of a message id. *singular* is used as the message id
+ for purposes of lookup in the catalog, while *n* is used to determine which
+ plural form to use. The returned message string is an 8-bit string encoded with
+ the catalog's charset encoding, if known.
+
+ If the message id is not found in the catalog, and a fallback is specified, the
+ request is forwarded to the fallback's :meth:`ngettext` method. Otherwise, when
+ *n* is 1 *singular* is returned, and *plural* is returned in all other cases.
+
+ .. versionadded:: 2.3
+
+
+.. method:: GNUTranslations.lngettext(singular, plural, n)
+
+ Equivalent to :meth:`gettext`, but the translation is returned in the preferred
+ system encoding, if no other encoding was explicitly set with
+ :meth:`set_output_charset`.
+
+ .. versionadded:: 2.4
+
+
+.. method:: GNUTranslations.ungettext(singular, plural, n)
+
+ Do a plural-forms lookup of a message id. *singular* is used as the message id
+ for purposes of lookup in the catalog, while *n* is used to determine which
+ plural form to use. The returned message string is a Unicode string.
+
+ If the message id is not found in the catalog, and a fallback is specified, the
+ request is forwarded to the fallback's :meth:`ungettext` method. Otherwise,
+ when *n* is 1 *singular* is returned, and *plural* is returned in all other
+ cases.
+
+ Here is an example::
+
+ n = len(os.listdir('.'))
+ cat = GNUTranslations(somefile)
+ message = cat.ungettext(
+ 'There is %(num)d file in this directory',
+ 'There are %(num)d files in this directory',
+ n) % {'num': n}
+
+ .. versionadded:: 2.3
+
+
+Solaris message catalog support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Solaris operating system defines its own binary :file:`.mo` file format, but
+since no documentation can be found on this format, it is not supported at this
+time.
+
+
+The Catalog constructor
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. index:: single: GNOME
+
+GNOME uses a version of the :mod:`gettext` module by James Henstridge, but this
+version has a slightly different API. Its documented usage was::
+
+ import gettext
+ cat = gettext.Catalog(domain, localedir)
+ _ = cat.gettext
+ print _('hello world')
+
+For compatibility with this older module, the function :func:`Catalog` is an
+alias for the :func:`translation` function described above.
+
+One difference between this module and Henstridge's: his catalog objects
+supported access through a mapping API, but this appears to be unused and so is
+not currently supported.
+
+
+Internationalizing your programs and modules
+--------------------------------------------
+
+Internationalization (I18N) refers to the operation by which a program is made
+aware of multiple languages. Localization (L10N) refers to the adaptation of
+your program, once internationalized, to the local language and cultural habits.
+In order to provide multilingual messages for your Python programs, you need to
+take the following steps:
+
+#. prepare your program or module by specially marking translatable strings
+
+#. run a suite of tools over your marked files to generate raw messages catalogs
+
+#. create language specific translations of the message catalogs
+
+#. use the :mod:`gettext` module so that message strings are properly translated
+
+In order to prepare your code for I18N, you need to look at all the strings in
+your files. Any string that needs to be translated should be marked by wrapping
+it in ``_('...')`` --- that is, a call to the function :func:`_`. For example::
+
+ filename = 'mylog.txt'
+ message = _('writing a log message')
+ fp = open(filename, 'w')
+ fp.write(message)
+ fp.close()
+
+In this example, the string ``'writing a log message'`` is marked as a candidate
+for translation, while the strings ``'mylog.txt'`` and ``'w'`` are not.
+
+The Python distribution comes with two tools which help you generate the message
+catalogs once you've prepared your source code. These may or may not be
+available from a binary distribution, but they can be found in a source
+distribution, in the :file:`Tools/i18n` directory.
+
+The :program:`pygettext` [#]_ program scans all your Python source code looking
+for the strings you previously marked as translatable. It is similar to the GNU
+:program:`gettext` program except that it understands all the intricacies of
+Python source code, but knows nothing about C or C++ source code. You don't
+need GNU ``gettext`` unless you're also going to be translating C code (such as
+C extension modules).
+
+:program:`pygettext` generates textual Uniforum-style human readable message
+catalog :file:`.pot` files, essentially structured human readable files which
+contain every marked string in the source code, along with a placeholder for the
+translation strings. :program:`pygettext` is a command line script that supports
+a similar command line interface as :program:`xgettext`; for details on its use,
+run::
+
+ pygettext.py --help
+
+Copies of these :file:`.pot` files are then handed over to the individual human
+translators who write language-specific versions for every supported natural
+language. They send you back the filled in language-specific versions as a
+:file:`.po` file. Using the :program:`msgfmt.py` [#]_ program (in the
+:file:`Tools/i18n` directory), you take the :file:`.po` files from your
+translators and generate the machine-readable :file:`.mo` binary catalog files.
+The :file:`.mo` files are what the :mod:`gettext` module uses for the actual
+translation processing during run-time.
+
+How you use the :mod:`gettext` module in your code depends on whether you are
+internationalizing a single module or your entire application. The next two
+sections will discuss each case.
+
+
+Localizing your module
+^^^^^^^^^^^^^^^^^^^^^^
+
+If you are localizing your module, you must take care not to make global
+changes, e.g. to the built-in namespace. You should not use the GNU ``gettext``
+API but instead the class-based API.
+
+Let's say your module is called "spam" and the module's various natural language
+translation :file:`.mo` files reside in :file:`/usr/share/locale` in GNU
+:program:`gettext` format. Here's what you would put at the top of your
+module::
+
+ import gettext
+ t = gettext.translation('spam', '/usr/share/locale')
+ _ = t.lgettext
+
+If your translators were providing you with Unicode strings in their :file:`.po`
+files, you'd instead do::
+
+ import gettext
+ t = gettext.translation('spam', '/usr/share/locale')
+ _ = t.ugettext
+
+
+Localizing your application
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are localizing your application, you can install the :func:`_` function
+globally into the built-in namespace, usually in the main driver file of your
+application. This will let all your application-specific files just use
+``_('...')`` without having to explicitly install it in each file.
+
+In the simple case then, you need only add the following bit of code to the main
+driver file of your application::
+
+ import gettext
+ gettext.install('myapplication')
+
+If you need to set the locale directory or the *unicode* flag, you can pass
+these into the :func:`install` function::
+
+ import gettext
+ gettext.install('myapplication', '/usr/share/locale', unicode=1)
+
+
+Changing languages on the fly
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If your program needs to support many languages at the same time, you may want
+to create multiple translation instances and then switch between them
+explicitly, like so::
+
+ import gettext
+
+ lang1 = gettext.translation('myapplication', languages=['en'])
+ lang2 = gettext.translation('myapplication', languages=['fr'])
+ lang3 = gettext.translation('myapplication', languages=['de'])
+
+ # start by using language1
+ lang1.install()
+
+ # ... time goes by, user selects language 2
+ lang2.install()
+
+ # ... more time goes by, user selects language 3
+ lang3.install()
+
+
+Deferred translations
+^^^^^^^^^^^^^^^^^^^^^
+
+In most coding situations, strings are translated where they are coded.
+Occasionally however, you need to mark strings for translation, but defer actual
+translation until later. A classic example is::
+
+ animals = ['mollusk',
+ 'albatross',
+ 'rat',
+ 'penguin',
+ 'python',
+ ]
+ # ...
+ for a in animals:
+ print a
+
+Here, you want to mark the strings in the ``animals`` list as being
+translatable, but you don't actually want to translate them until they are
+printed.
+
+Here is one way you can handle this situation::
+
+ def _(message): return message
+
+ animals = [_('mollusk'),
+ _('albatross'),
+ _('rat'),
+ _('penguin'),
+ _('python'),
+ ]
+
+ del _
+
+ # ...
+ for a in animals:
+ print _(a)
+
+This works because the dummy definition of :func:`_` simply returns the string
+unchanged. And this dummy definition will temporarily override any definition
+of :func:`_` in the built-in namespace (until the :keyword:`del` command). Take
+care, though if you have a previous definition of :func:`_` in the local
+namespace.
+
+Note that the second use of :func:`_` will not identify "a" as being
+translatable to the :program:`pygettext` program, since it is not a string.
+
+Another way to handle this is with the following example::
+
+ def N_(message): return message
+
+ animals = [N_('mollusk'),
+ N_('albatross'),
+ N_('rat'),
+ N_('penguin'),
+ N_('python'),
+ ]
+
+ # ...
+ for a in animals:
+ print _(a)
+
+In this case, you are marking translatable strings with the function :func:`N_`,
+[#]_ which won't conflict with any definition of :func:`_`. However, you will
+need to teach your message extraction program to look for translatable strings
+marked with :func:`N_`. :program:`pygettext` and :program:`xpot` both support
+this through the use of command line switches.
+
+
+:func:`gettext` vs. :func:`lgettext`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In Python 2.4 the :func:`lgettext` family of functions were introduced. The
+intention of these functions is to provide an alternative which is more
+compliant with the current implementation of GNU gettext. Unlike
+:func:`gettext`, which returns strings encoded with the same codeset used in the
+translation file, :func:`lgettext` will return strings encoded with the
+preferred system encoding, as returned by :func:`locale.getpreferredencoding`.
+Also notice that Python 2.4 introduces new functions to explicitly choose the
+codeset used in translated strings. If a codeset is explicitly set, even
+:func:`lgettext` will return translated strings in the requested codeset, as
+would be expected in the GNU gettext implementation.
+
+
+Acknowledgements
+----------------
+
+The following people contributed code, feedback, design suggestions, previous
+implementations, and valuable experience to the creation of this module:
+
+* Peter Funk
+
+* James Henstridge
+
+* Juan David Ibáñez Palomar
+
+* Marc-André Lemburg
+
+* Martin von Löwis
+
+* François Pinard
+
+* Barry Warsaw
+
+* Gustavo Niemeyer
+
+.. rubric:: Footnotes
+
+.. [#] The default locale directory is system dependent; for example, on RedHat Linux
+ it is :file:`/usr/share/locale`, but on Solaris it is :file:`/usr/lib/locale`.
+ The :mod:`gettext` module does not try to support these system dependent
+ defaults; instead its default is :file:`sys.prefix/share/locale`. For this
+ reason, it is always best to call :func:`bindtextdomain` with an explicit
+ absolute path at the start of your application.
+
+.. [#] See the footnote for :func:`bindtextdomain` above.
+
+.. [#] François Pinard has written a program called :program:`xpot` which does a
+ similar job. It is available as part of his :program:`po-utils` package at http
+ ://po-utils.progiciels-bpi.ca/.
+
+.. [#] :program:`msgfmt.py` is binary compatible with GNU :program:`msgfmt` except that
+ it provides a simpler, all-Python implementation. With this and
+ :program:`pygettext.py`, you generally won't need to install the GNU
+ :program:`gettext` package to internationalize your Python applications.
+
+.. [#] The choice of :func:`N_` here is totally arbitrary; it could have just as easily
+ been :func:`MarkThisStringForTranslation`.
+
--- /dev/null
+
+:mod:`gl` --- *Graphics Library* interface
+==========================================
+
+.. module:: gl
+ :platform: IRIX
+ :synopsis: Functions from the Silicon Graphics Graphics Library.
+
+
+This module provides access to the Silicon Graphics *Graphics Library*. It is
+available only on Silicon Graphics machines.
+
+.. warning::
+
+ Some illegal calls to the GL library cause the Python interpreter to dump core.
+ In particular, the use of most GL calls is unsafe before the first window is
+ opened.
+
+The module is too large to document here in its entirety, but the following
+should help you to get started. The parameter conventions for the C functions
+are translated to Python as follows:
+
+* All (short, long, unsigned) int values are represented by Python integers.
+
+* All float and double values are represented by Python floating point numbers.
+ In most cases, Python integers are also allowed.
+
+* All arrays are represented by one-dimensional Python lists. In most cases,
+ tuples are also allowed.
+
+* All string and character arguments are represented by Python strings, for
+ instance, ``winopen('Hi There!')`` and ``rotate(900, 'z')``.
+
+* All (short, long, unsigned) integer arguments or return values that are only
+ used to specify the length of an array argument are omitted. For example, the C
+ call ::
+
+ lmdef(deftype, index, np, props)
+
+ is translated to Python as ::
+
+ lmdef(deftype, index, props)
+
+* Output arguments are omitted from the argument list; they are transmitted as
+ function return values instead. If more than one value must be returned, the
+ return value is a tuple. If the C function has both a regular return value (that
+ is not omitted because of the previous rule) and an output argument, the return
+ value comes first in the tuple. Examples: the C call ::
+
+ getmcolor(i, &red, &green, &blue)
+
+ is translated to Python as ::
+
+ red, green, blue = getmcolor(i)
+
+The following functions are non-standard or have special argument conventions:
+
+
+.. function:: varray(argument)
+
+ Equivalent to but faster than a number of ``v3d()`` calls. The *argument* is a
+ list (or tuple) of points. Each point must be a tuple of coordinates ``(x, y,
+ z)`` or ``(x, y)``. The points may be 2- or 3-dimensional but must all have the
+ same dimension. Float and int values may be mixed however. The points are always
+ converted to 3D double precision points by assuming ``z = 0.0`` if necessary (as
+ indicated in the man page), and for each point ``v3d()`` is called.
+
+ .. % JHXXX the argument-argument added
+
+
+.. function:: nvarray()
+
+ Equivalent to but faster than a number of ``n3f`` and ``v3f`` calls. The
+ argument is an array (list or tuple) of pairs of normals and points. Each pair
+ is a tuple of a point and a normal for that point. Each point or normal must be
+ a tuple of coordinates ``(x, y, z)``. Three coordinates must be given. Float and
+ int values may be mixed. For each pair, ``n3f()`` is called for the normal, and
+ then ``v3f()`` is called for the point.
+
+
+.. function:: vnarray()
+
+ Similar to ``nvarray()`` but the pairs have the point first and the normal
+ second.
+
+
+.. function:: nurbssurface(s_k, t_k, ctl, s_ord, t_ord, type)
+
+ Defines a nurbs surface. The dimensions of ``ctl[][]`` are computed as follows:
+ ``[len(s_k) - s_ord]``, ``[len(t_k) - t_ord]``.
+
+ .. % XXX s_k[], t_k[], ctl[][]
+
+
+.. function:: nurbscurve(knots, ctlpoints, order, type)
+
+ Defines a nurbs curve. The length of ctlpoints is ``len(knots) - order``.
+
+
+.. function:: pwlcurve(points, type)
+
+ Defines a piecewise-linear curve. *points* is a list of points. *type* must be
+ ``N_ST``.
+
+
+.. function:: pick(n)
+ select(n)
+
+ The only argument to these functions specifies the desired size of the pick or
+ select buffer.
+
+
+.. function:: endpick()
+ endselect()
+
+ These functions have no arguments. They return a list of integers representing
+ the used part of the pick/select buffer. No method is provided to detect buffer
+ overrun.
+
+Here is a tiny but complete example GL program in Python::
+
+ import gl, GL, time
+
+ def main():
+ gl.foreground()
+ gl.prefposition(500, 900, 500, 900)
+ w = gl.winopen('CrissCross')
+ gl.ortho2(0.0, 400.0, 0.0, 400.0)
+ gl.color(GL.WHITE)
+ gl.clear()
+ gl.color(GL.RED)
+ gl.bgnline()
+ gl.v2f(0.0, 0.0)
+ gl.v2f(400.0, 400.0)
+ gl.endline()
+ gl.bgnline()
+ gl.v2f(400.0, 0.0)
+ gl.v2f(0.0, 400.0)
+ gl.endline()
+ time.sleep(5)
+
+ main()
+
+
+.. seealso::
+
+ `PyOpenGL: The Python OpenGL Binding <http://pyopengl.sourceforge.net/>`_
+ .. index::
+ single: OpenGL
+ single: PyOpenGL
+
+ An interface to OpenGL is also available; see information about the **PyOpenGL**
+ project online at http://pyopengl.sourceforge.net/. This may be a better option
+ if support for SGI hardware from before about 1996 is not required.
+
+
+:mod:`DEVICE` --- Constants used with the :mod:`gl` module
+==========================================================
+
+.. module:: DEVICE
+ :platform: IRIX
+ :synopsis: Constants used with the gl module.
+
+
+This modules defines the constants used by the Silicon Graphics *Graphics
+Library* that C programmers find in the header file ``<gl/device.h>``. Read the
+module source file for details.
+
+
+:mod:`GL` --- Constants used with the :mod:`gl` module
+======================================================
+
+.. module:: GL
+ :platform: IRIX
+ :synopsis: Constants used with the gl module.
+
+
+This module contains constants used by the Silicon Graphics *Graphics Library*
+from the C header file ``<gl/gl.h>``. Read the module source file for details.
+
--- /dev/null
+
+:mod:`glob` --- Unix style pathname pattern expansion
+=====================================================
+
+.. module:: glob
+ :synopsis: Unix shell style pathname pattern expansion.
+
+
+.. index:: single: filenames; pathname expansion
+
+The :mod:`glob` module finds all the pathnames matching a specified pattern
+according to the rules used by the Unix shell. No tilde expansion is done, but
+``*``, ``?``, and character ranges expressed with ``[]`` will be correctly
+matched. This is done by using the :func:`os.listdir` and
+:func:`fnmatch.fnmatch` functions in concert, and not by actually invoking a
+subshell. (For tilde and shell variable expansion, use
+:func:`os.path.expanduser` and :func:`os.path.expandvars`.)
+
+
+.. function:: glob(pathname)
+
+ Return a possibly-empty list of path names that match *pathname*, which must be
+ a string containing a path specification. *pathname* can be either absolute
+ (like :file:`/usr/src/Python-1.5/Makefile`) or relative (like
+ :file:`../../Tools/\*/\*.gif`), and can contain shell-style wildcards. Broken
+ symlinks are included in the results (as in the shell).
+
+
+.. function:: iglob(pathname)
+
+ Return an iterator which yields the same values as :func:`glob` without actually
+ storing them all simultaneously.
+
+ .. versionadded:: 2.5
+
+For example, consider a directory containing only the following files:
+:file:`1.gif`, :file:`2.txt`, and :file:`card.gif`. :func:`glob` will produce
+the following results. Notice how any leading components of the path are
+preserved. ::
+
+ >>> import glob
+ >>> glob.glob('./[0-9].*')
+ ['./1.gif', './2.txt']
+ >>> glob.glob('*.gif')
+ ['1.gif', 'card.gif']
+ >>> glob.glob('?.gif')
+ ['1.gif']
+
+
+.. seealso::
+
+ Module :mod:`fnmatch`
+ Shell-style filename (not path) expansion
+
--- /dev/null
+
+:mod:`grp` --- The group database
+=================================
+
+.. module:: grp
+ :platform: Unix
+ :synopsis: The group database (getgrnam() and friends).
+
+
+This module provides access to the Unix group database. It is available on all
+Unix versions.
+
+Group database entries are reported as a tuple-like object, whose attributes
+correspond to the members of the ``group`` structure (Attribute field below, see
+``<pwd.h>``):
+
++-------+-----------+---------------------------------+
+| Index | Attribute | Meaning |
++=======+===========+=================================+
+| 0 | gr_name | the name of the group |
++-------+-----------+---------------------------------+
+| 1 | gr_passwd | the (encrypted) group password; |
+| | | often empty |
++-------+-----------+---------------------------------+
+| 2 | gr_gid | the numerical group ID |
++-------+-----------+---------------------------------+
+| 3 | gr_mem | all the group member's user |
+| | | names |
++-------+-----------+---------------------------------+
+
+The gid is an integer, name and password are strings, and the member list is a
+list of strings. (Note that most users are not explicitly listed as members of
+the group they are in according to the password database. Check both databases
+to get complete membership information.)
+
+It defines the following items:
+
+
+.. function:: getgrgid(gid)
+
+ Return the group database entry for the given numeric group ID. :exc:`KeyError`
+ is raised if the entry asked for cannot be found.
+
+
+.. function:: getgrnam(name)
+
+ Return the group database entry for the given group name. :exc:`KeyError` is
+ raised if the entry asked for cannot be found.
+
+
+.. function:: getgrall()
+
+ Return a list of all available group entries, in arbitrary order.
+
+
+.. seealso::
+
+ Module :mod:`pwd`
+ An interface to the user database, similar to this.
+
+ Module :mod:`spwd`
+ An interface to the shadow password database, similar to this.
+
--- /dev/null
+
+:mod:`gzip` --- Support for :program:`gzip` files
+=================================================
+
+.. module:: gzip
+ :synopsis: Interfaces for gzip compression and decompression using file objects.
+
+
+The data compression provided by the ``zlib`` module is compatible with that
+used by the GNU compression program :program:`gzip`. Accordingly, the
+:mod:`gzip` module provides the :class:`GzipFile` class to read and write
+:program:`gzip`\ -format files, automatically compressing or decompressing the
+data so it looks like an ordinary file object. Note that additional file
+formats which can be decompressed by the :program:`gzip` and :program:`gunzip`
+programs, such as those produced by :program:`compress` and :program:`pack`,
+are not supported by this module.
+
+The module defines the following items:
+
+
+.. class:: GzipFile([filename[, mode[, compresslevel[, fileobj]]]])
+
+ Constructor for the :class:`GzipFile` class, which simulates most of the methods
+ of a file object, with the exception of the :meth:`readinto` and
+ :meth:`truncate` methods. At least one of *fileobj* and *filename* must be
+ given a non-trivial value.
+
+ The new class instance is based on *fileobj*, which can be a regular file, a
+ :class:`StringIO` object, or any other object which simulates a file. It
+ defaults to ``None``, in which case *filename* is opened to provide a file
+ object.
+
+ When *fileobj* is not ``None``, the *filename* argument is only used to be
+ included in the :program:`gzip` file header, which may includes the original
+ filename of the uncompressed file. It defaults to the filename of *fileobj*, if
+ discernible; otherwise, it defaults to the empty string, and in this case the
+ original filename is not included in the header.
+
+ The *mode* argument can be any of ``'r'``, ``'rb'``, ``'a'``, ``'ab'``, ``'w'``,
+ or ``'wb'``, depending on whether the file will be read or written. The default
+ is the mode of *fileobj* if discernible; otherwise, the default is ``'rb'``. If
+ not given, the 'b' flag will be added to the mode to ensure the file is opened
+ in binary mode for cross-platform portability.
+
+ The *compresslevel* argument is an integer from ``1`` to ``9`` controlling the
+ level of compression; ``1`` is fastest and produces the least compression, and
+ ``9`` is slowest and produces the most compression. The default is ``9``.
+
+ Calling a :class:`GzipFile` object's :meth:`close` method does not close
+ *fileobj*, since you might wish to append more material after the compressed
+ data. This also allows you to pass a :class:`StringIO` object opened for
+ writing as *fileobj*, and retrieve the resulting memory buffer using the
+ :class:`StringIO` object's :meth:`getvalue` method.
+
+
+.. function:: open(filename[, mode[, compresslevel]])
+
+ This is a shorthand for ``GzipFile(filename,`` ``mode,`` ``compresslevel)``.
+ The *filename* argument is required; *mode* defaults to ``'rb'`` and
+ *compresslevel* defaults to ``9``.
+
+
+.. seealso::
+
+ Module :mod:`zlib`
+ The basic data compression module needed to support the :program:`gzip` file
+ format.
+
--- /dev/null
+
+:mod:`hashlib` --- Secure hashes and message digests
+====================================================
+
+.. module:: hashlib
+ :synopsis: Secure hash and message digest algorithms.
+.. moduleauthor:: Gregory P. Smith <greg@users.sourceforge.net>
+.. sectionauthor:: Gregory P. Smith <greg@users.sourceforge.net>
+
+
+.. versionadded:: 2.5
+
+.. index::
+ single: message digest, MD5
+ single: secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512
+
+This module implements a common interface to many different secure hash and
+message digest algorithms. Included are the FIPS secure hash algorithms SHA1,
+SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5
+algorithm (defined in Internet :rfc:`1321`). The terms secure hash and message
+digest are interchangeable. Older algorithms were called message digests. The
+modern term is secure hash.
+
+.. warning::
+
+ Some algorithms have known hash collision weaknesses, see the FAQ at the end.
+
+There is one constructor method named for each type of :dfn:`hash`. All return
+a hash object with the same simple interface. For example: use :func:`sha1` to
+create a SHA1 hash object. You can now feed this object with arbitrary strings
+using the :meth:`update` method. At any point you can ask it for the
+:dfn:`digest` of the concatenation of the strings fed to it so far using the
+:meth:`digest` or :meth:`hexdigest` methods.
+
+.. index:: single: OpenSSL
+
+Constructors for hash algorithms that are always present in this module are
+:func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, and
+:func:`sha512`. Additional algorithms may also be available depending upon the
+OpenSSL library that Python uses on your platform.
+
+For example, to obtain the digest of the string ``'Nobody inspects the spammish
+repetition'``::
+
+ >>> import hashlib
+ >>> m = hashlib.md5()
+ >>> m.update("Nobody inspects")
+ >>> m.update(" the spammish repetition")
+ >>> m.digest()
+ '\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
+
+More condensed::
+
+ >>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
+ 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
+
+A generic :func:`new` constructor that takes the string name of the desired
+algorithm as its first parameter also exists to allow access to the above listed
+hashes as well as any other algorithms that your OpenSSL library may offer. The
+named constructors are much faster than :func:`new` and should be preferred.
+
+Using :func:`new` with an algorithm provided by OpenSSL::
+
+ >>> h = hashlib.new('ripemd160')
+ >>> h.update("Nobody inspects the spammish repetition")
+ >>> h.hexdigest()
+ 'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
+
+The following values are provided as constant attributes of the hash objects
+returned by the constructors:
+
+
+.. data:: digest_size
+
+ The size of the resulting digest in bytes.
+
+A hash object has the following methods:
+
+
+.. method:: hash.update(arg)
+
+ Update the hash object with the string *arg*. Repeated calls are equivalent to
+ a single call with the concatenation of all the arguments: ``m.update(a);
+ m.update(b)`` is equivalent to ``m.update(a+b)``.
+
+
+.. method:: hash.digest()
+
+ Return the digest of the strings passed to the :meth:`update` method so far.
+ This is a string of :attr:`digest_size` bytes which may contain non-ASCII
+ characters, including null bytes.
+
+
+.. method:: hash.hexdigest()
+
+ Like :meth:`digest` except the digest is returned as a string of double length,
+ containing only hexadecimal digits. This may be used to exchange the value
+ safely in email or other non-binary environments.
+
+
+.. method:: hash.copy()
+
+ Return a copy ("clone") of the hash object. This can be used to efficiently
+ compute the digests of strings that share a common initial substring.
+
+
+.. seealso::
+
+ Module :mod:`hmac`
+ A module to generate message authentication codes using hashes.
+
+ Module :mod:`base64`
+ Another way to encode binary hashes for non-binary environments.
+
+ http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
+ The FIPS 180-2 publication on Secure Hash Algorithms.
+
+ http://www.cryptography.com/cnews/hash.html
+ Hash Collision FAQ with information on which algorithms have known issues and
+ what that means regarding their use.
+
--- /dev/null
+
+:mod:`heapq` --- Heap queue algorithm
+=====================================
+
+.. module:: heapq
+ :synopsis: Heap queue algorithm (a.k.a. priority queue).
+.. moduleauthor:: Kevin O'Connor
+.. sectionauthor:: Guido van Rossum <guido@python.org>
+.. sectionauthor:: François Pinard
+
+
+.. % Theoretical explanation:
+
+.. versionadded:: 2.3
+
+This module provides an implementation of the heap queue algorithm, also known
+as the priority queue algorithm.
+
+Heaps are arrays for which ``heap[k] <= heap[2*k+1]`` and ``heap[k] <=
+heap[2*k+2]`` for all *k*, counting elements from zero. For the sake of
+comparison, non-existing elements are considered to be infinite. The
+interesting property of a heap is that ``heap[0]`` is always its smallest
+element.
+
+The API below differs from textbook heap algorithms in two aspects: (a) We use
+zero-based indexing. This makes the relationship between the index for a node
+and the indexes for its children slightly less obvious, but is more suitable
+since Python uses zero-based indexing. (b) Our pop method returns the smallest
+item, not the largest (called a "min heap" in textbooks; a "max heap" is more
+common in texts because of its suitability for in-place sorting).
+
+These two make it possible to view the heap as a regular Python list without
+surprises: ``heap[0]`` is the smallest item, and ``heap.sort()`` maintains the
+heap invariant!
+
+To create a heap, use a list initialized to ``[]``, or you can transform a
+populated list into a heap via function :func:`heapify`.
+
+The following functions are provided:
+
+
+.. function:: heappush(heap, item)
+
+ Push the value *item* onto the *heap*, maintaining the heap invariant.
+
+
+.. function:: heappop(heap)
+
+ Pop and return the smallest item from the *heap*, maintaining the heap
+ invariant. If the heap is empty, :exc:`IndexError` is raised.
+
+
+.. function:: heapify(x)
+
+ Transform list *x* into a heap, in-place, in linear time.
+
+
+.. function:: heapreplace(heap, item)
+
+ Pop and return the smallest item from the *heap*, and also push the new *item*.
+ The heap size doesn't change. If the heap is empty, :exc:`IndexError` is raised.
+ This is more efficient than :func:`heappop` followed by :func:`heappush`, and
+ can be more appropriate when using a fixed-size heap. Note that the value
+ returned may be larger than *item*! That constrains reasonable uses of this
+ routine unless written as part of a conditional replacement::
+
+ if item > heap[0]:
+ item = heapreplace(heap, item)
+
+Example of use::
+
+ >>> from heapq import heappush, heappop
+ >>> heap = []
+ >>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
+ >>> for item in data:
+ ... heappush(heap, item)
+ ...
+ >>> ordered = []
+ >>> while heap:
+ ... ordered.append(heappop(heap))
+ ...
+ >>> print ordered
+ [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+ >>> data.sort()
+ >>> print data == ordered
+ True
+ >>>
+
+The module also offers three general purpose functions based on heaps.
+
+
+.. function:: merge(*iterables)
+
+ Merge multiple sorted inputs into a single sorted output (for example, merge
+ timestamped entries from multiple log files). Returns an iterator over over the
+ sorted values.
+
+ Similar to ``sorted(itertools.chain(*iterables))`` but returns an iterable, does
+ not pull the data into memory all at once, and assumes that each of the input
+ streams is already sorted (smallest to largest).
+
+ .. versionadded:: 2.6
+
+
+.. function:: nlargest(n, iterable[, key])
+
+ Return a list with the *n* largest elements from the dataset defined by
+ *iterable*. *key*, if provided, specifies a function of one argument that is
+ used to extract a comparison key from each element in the iterable:
+ ``key=str.lower`` Equivalent to: ``sorted(iterable, key=key,
+ reverse=True)[:n]``
+
+ .. versionadded:: 2.4
+
+ .. versionchanged:: 2.5
+ Added the optional *key* argument.
+
+
+.. function:: nsmallest(n, iterable[, key])
+
+ Return a list with the *n* smallest elements from the dataset defined by
+ *iterable*. *key*, if provided, specifies a function of one argument that is
+ used to extract a comparison key from each element in the iterable:
+ ``key=str.lower`` Equivalent to: ``sorted(iterable, key=key)[:n]``
+
+ .. versionadded:: 2.4
+
+ .. versionchanged:: 2.5
+ Added the optional *key* argument.
+
+The latter two functions perform best for smaller values of *n*. For larger
+values, it is more efficient to use the :func:`sorted` function. Also, when
+``n==1``, it is more efficient to use the builtin :func:`min` and :func:`max`
+functions.
+
+
+Theory
+------
+
+(This explanation is due to François Pinard. The Python code for this module
+was contributed by Kevin O'Connor.)
+
+Heaps are arrays for which ``a[k] <= a[2*k+1]`` and ``a[k] <= a[2*k+2]`` for all
+*k*, counting elements from 0. For the sake of comparison, non-existing
+elements are considered to be infinite. The interesting property of a heap is
+that ``a[0]`` is always its smallest element.
+
+The strange invariant above is meant to be an efficient memory representation
+for a tournament. The numbers below are *k*, not ``a[k]``::
+
+ 0
+
+ 1 2
+
+ 3 4 5 6
+
+ 7 8 9 10 11 12 13 14
+
+ 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
+
+In the tree above, each cell *k* is topping ``2*k+1`` and ``2*k+2``. In an usual
+binary tournament we see in sports, each cell is the winner over the two cells
+it tops, and we can trace the winner down the tree to see all opponents s/he
+had. However, in many computer applications of such tournaments, we do not need
+to trace the history of a winner. To be more memory efficient, when a winner is
+promoted, we try to replace it by something else at a lower level, and the rule
+becomes that a cell and the two cells it tops contain three different items, but
+the top cell "wins" over the two topped cells.
+
+If this heap invariant is protected at all time, index 0 is clearly the overall
+winner. The simplest algorithmic way to remove it and find the "next" winner is
+to move some loser (let's say cell 30 in the diagram above) into the 0 position,
+and then percolate this new 0 down the tree, exchanging values, until the
+invariant is re-established. This is clearly logarithmic on the total number of
+items in the tree. By iterating over all items, you get an O(n log n) sort.
+
+A nice feature of this sort is that you can efficiently insert new items while
+the sort is going on, provided that the inserted items are not "better" than the
+last 0'th element you extracted. This is especially useful in simulation
+contexts, where the tree holds all incoming events, and the "win" condition
+means the smallest scheduled time. When an event schedule other events for
+execution, they are scheduled into the future, so they can easily go into the
+heap. So, a heap is a good structure for implementing schedulers (this is what
+I used for my MIDI sequencer :-).
+
+Various structures for implementing schedulers have been extensively studied,
+and heaps are good for this, as they are reasonably speedy, the speed is almost
+constant, and the worst case is not much different than the average case.
+However, there are other representations which are more efficient overall, yet
+the worst cases might be terrible.
+
+Heaps are also very useful in big disk sorts. You most probably all know that a
+big sort implies producing "runs" (which are pre-sorted sequences, which size is
+usually related to the amount of CPU memory), followed by a merging passes for
+these runs, which merging is often very cleverly organised [#]_. It is very
+important that the initial sort produces the longest runs possible. Tournaments
+are a good way to that. If, using all the memory available to hold a
+tournament, you replace and percolate items that happen to fit the current run,
+you'll produce runs which are twice the size of the memory for random input, and
+much better for input fuzzily ordered.
+
+Moreover, if you output the 0'th item on disk and get an input which may not fit
+in the current tournament (because the value "wins" over the last output value),
+it cannot fit in the heap, so the size of the heap decreases. The freed memory
+could be cleverly reused immediately for progressively building a second heap,
+which grows at exactly the same rate the first heap is melting. When the first
+heap completely vanishes, you switch heaps and start a new run. Clever and
+quite effective!
+
+In a word, heaps are useful memory structures to know. I use them in a few
+applications, and I think it is good to keep a 'heap' module around. :-)
+
+.. rubric:: Footnotes
+
+.. [#] The disk balancing algorithms which are current, nowadays, are more annoying
+ than clever, and this is a consequence of the seeking capabilities of the disks.
+ On devices which cannot seek, like big tape drives, the story was quite
+ different, and one had to be very clever to ensure (far in advance) that each
+ tape movement will be the most effective possible (that is, will best
+ participate at "progressing" the merge). Some tapes were even able to read
+ backwards, and this was also used to avoid the rewinding time. Believe me, real
+ good tape sorts were quite spectacular to watch! From all times, sorting has
+ always been a Great Art! :-)
+
--- /dev/null
+
+:mod:`hmac` --- Keyed-Hashing for Message Authentication
+========================================================
+
+.. module:: hmac
+ :synopsis: Keyed-Hashing for Message Authentication (HMAC) implementation for Python.
+.. moduleauthor:: Gerhard Häring <ghaering@users.sourceforge.net>
+.. sectionauthor:: Gerhard Häring <ghaering@users.sourceforge.net>
+
+
+.. versionadded:: 2.2
+
+This module implements the HMAC algorithm as described by :rfc:`2104`.
+
+
+.. function:: new(key[, msg[, digestmod]])
+
+ Return a new hmac object. If *msg* is present, the method call ``update(msg)``
+ is made. *digestmod* is the digest constructor or module for the HMAC object to
+ use. It defaults to the :func:`hashlib.md5` constructor.
+
+ .. note::
+
+ The md5 hash has known weaknesses but remains the default for backwards
+ compatibility. Choose a better one for your application.
+
+An HMAC object has the following methods:
+
+
+.. method:: hmac.update(msg)
+
+ Update the hmac object with the string *msg*. Repeated calls are equivalent to
+ a single call with the concatenation of all the arguments: ``m.update(a);
+ m.update(b)`` is equivalent to ``m.update(a + b)``.
+
+
+.. method:: hmac.digest()
+
+ Return the digest of the strings passed to the :meth:`update` method so far.
+ This string will be the same length as the *digest_size* of the digest given to
+ the constructor. It may contain non-ASCII characters, including NUL bytes.
+
+
+.. method:: hmac.hexdigest()
+
+ Like :meth:`digest` except the digest is returned as a string twice the length
+ containing only hexadecimal digits. This may be used to exchange the value
+ safely in email or other non-binary environments.
+
+
+.. method:: hmac.copy()
+
+ Return a copy ("clone") of the hmac object. This can be used to efficiently
+ compute the digests of strings that share a common initial substring.
+
+
+.. seealso::
+
+ Module :mod:`hashlib`
+ The python module providing secure hash functions.
+
--- /dev/null
+
+:mod:`hotshot` --- High performance logging profiler
+====================================================
+
+.. module:: hotshot
+ :synopsis: High performance logging profiler, mostly written in C.
+.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+.. sectionauthor:: Anthony Baxter <anthony@interlink.com.au>
+
+
+.. versionadded:: 2.2
+
+This module provides a nicer interface to the :mod:`_hotshot` C module. Hotshot
+is a replacement for the existing :mod:`profile` module. As it's written mostly
+in C, it should result in a much smaller performance impact than the existing
+:mod:`profile` module.
+
+.. note::
+
+ The :mod:`hotshot` module focuses on minimizing the overhead while profiling, at
+ the expense of long data post-processing times. For common usages it is
+ recommended to use :mod:`cProfile` instead. :mod:`hotshot` is not maintained and
+ might be removed from the standard library in the future.
+
+.. versionchanged:: 2.5
+ the results should be more meaningful than in the past: the timing core
+ contained a critical bug.
+
+.. warning::
+
+ The :mod:`hotshot` profiler does not yet work well with threads. It is useful to
+ use an unthreaded script to run the profiler over the code you're interested in
+ measuring if at all possible.
+
+
+.. class:: Profile(logfile[, lineevents[, linetimings]])
+
+ The profiler object. The argument *logfile* is the name of a log file to use for
+ logged profile data. The argument *lineevents* specifies whether to generate
+ events for every source line, or just on function call/return. It defaults to
+ ``0`` (only log function call/return). The argument *linetimings* specifies
+ whether to record timing information. It defaults to ``1`` (store timing
+ information).
+
+
+.. _hotshot-objects:
+
+Profile Objects
+---------------
+
+Profile objects have the following methods:
+
+
+.. method:: Profile.addinfo(key, value)
+
+ Add an arbitrary labelled value to the profile output.
+
+
+.. method:: Profile.close()
+
+ Close the logfile and terminate the profiler.
+
+
+.. method:: Profile.fileno()
+
+ Return the file descriptor of the profiler's log file.
+
+
+.. method:: Profile.run(cmd)
+
+ Profile an :keyword:`exec`\ -compatible string in the script environment. The
+ globals from the :mod:`__main__` module are used as both the globals and locals
+ for the script.
+
+
+.. method:: Profile.runcall(func, *args, **keywords)
+
+ Profile a single call of a callable. Additional positional and keyword arguments
+ may be passed along; the result of the call is returned, and exceptions are
+ allowed to propagate cleanly, while ensuring that profiling is disabled on the
+ way out.
+
+
+.. method:: Profile.runctx(cmd, globals, locals)
+
+ Evaluate an :keyword:`exec`\ -compatible string in a specific environment. The
+ string is compiled before profiling begins.
+
+
+.. method:: Profile.start()
+
+ Start the profiler.
+
+
+.. method:: Profile.stop()
+
+ Stop the profiler.
+
+
+Using hotshot data
+------------------
+
+.. module:: hotshot.stats
+ :synopsis: Statistical analysis for Hotshot
+
+
+.. versionadded:: 2.2
+
+This module loads hotshot profiling data into the standard :mod:`pstats` Stats
+objects.
+
+
+.. function:: load(filename)
+
+ Load hotshot data from *filename*. Returns an instance of the
+ :class:`pstats.Stats` class.
+
+
+.. seealso::
+
+ Module :mod:`profile`
+ The :mod:`profile` module's :class:`Stats` class
+
+
+.. _hotshot-example:
+
+Example Usage
+-------------
+
+Note that this example runs the python "benchmark" pystones. It can take some
+time to run, and will produce large output files. ::
+
+ >>> import hotshot, hotshot.stats, test.pystone
+ >>> prof = hotshot.Profile("stones.prof")
+ >>> benchtime, stones = prof.runcall(test.pystone.pystones)
+ >>> prof.close()
+ >>> stats = hotshot.stats.load("stones.prof")
+ >>> stats.strip_dirs()
+ >>> stats.sort_stats('time', 'calls')
+ >>> stats.print_stats(20)
+ 850004 function calls in 10.090 CPU seconds
+
+ Ordered by: internal time, call count
+
+ ncalls tottime percall cumtime percall filename:lineno(function)
+ 1 3.295 3.295 10.090 10.090 pystone.py:79(Proc0)
+ 150000 1.315 0.000 1.315 0.000 pystone.py:203(Proc7)
+ 50000 1.313 0.000 1.463 0.000 pystone.py:229(Func2)
+ .
+ .
+ .
+
--- /dev/null
+
+:mod:`htmllib` --- A parser for HTML documents
+==============================================
+
+.. module:: htmllib
+ :synopsis: A parser for HTML documents.
+
+
+.. index::
+ single: HTML
+ single: hypertext
+
+.. index::
+ module: sgmllib
+ module: formatter
+ single: SGMLParser (in module sgmllib)
+
+This module defines a class which can serve as a base for parsing text files
+formatted in the HyperText Mark-up Language (HTML). The class is not directly
+concerned with I/O --- it must be provided with input in string form via a
+method, and makes calls to methods of a "formatter" object in order to produce
+output. The :class:`HTMLParser` class is designed to be used as a base class
+for other classes in order to add functionality, and allows most of its methods
+to be extended or overridden. In turn, this class is derived from and extends
+the :class:`SGMLParser` class defined in module :mod:`sgmllib`. The
+:class:`HTMLParser` implementation supports the HTML 2.0 language as described
+in :rfc:`1866`. Two implementations of formatter objects are provided in the
+:mod:`formatter` module; refer to the documentation for that module for
+information on the formatter interface.
+
+The following is a summary of the interface defined by
+:class:`sgmllib.SGMLParser`:
+
+* The interface to feed data to an instance is through the :meth:`feed` method,
+ which takes a string argument. This can be called with as little or as much
+ text at a time as desired; ``p.feed(a); p.feed(b)`` has the same effect as
+ ``p.feed(a+b)``. When the data contains complete HTML markup constructs, these
+ are processed immediately; incomplete constructs are saved in a buffer. To
+ force processing of all unprocessed data, call the :meth:`close` method.
+
+ For example, to parse the entire contents of a file, use::
+
+ parser.feed(open('myfile.html').read())
+ parser.close()
+
+* The interface to define semantics for HTML tags is very simple: derive a class
+ and define methods called :meth:`start_tag`, :meth:`end_tag`, or :meth:`do_tag`.
+ The parser will call these at appropriate moments: :meth:`start_tag` or
+ :meth:`do_tag` is called when an opening tag of the form ``<tag ...>`` is
+ encountered; :meth:`end_tag` is called when a closing tag of the form ``<tag>``
+ is encountered. If an opening tag requires a corresponding closing tag, like
+ ``<H1>`` ... ``</H1>``, the class should define the :meth:`start_tag` method; if
+ a tag requires no closing tag, like ``<P>``, the class should define the
+ :meth:`do_tag` method.
+
+The module defines a parser class and an exception:
+
+
+.. class:: HTMLParser(formatter)
+
+ This is the basic HTML parser class. It supports all entity names required by
+ the XHTML 1.0 Recommendation (http://www.w3.org/TR/xhtml1). It also defines
+ handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements.
+
+
+.. exception:: HTMLParseError
+
+ Exception raised by the :class:`HTMLParser` class when it encounters an error
+ while parsing.
+
+ .. versionadded:: 2.4
+
+
+.. seealso::
+
+ Module :mod:`formatter`
+ Interface definition for transforming an abstract flow of formatting events into
+ specific output events on writer objects.
+
+ Module :mod:`HTMLParser`
+ Alternate HTML parser that offers a slightly lower-level view of the input, but
+ is designed to work with XHTML, and does not implement some of the SGML syntax
+ not used in "HTML as deployed" and which isn't legal for XHTML.
+
+ Module :mod:`htmlentitydefs`
+ Definition of replacement text for XHTML 1.0 entities.
+
+ Module :mod:`sgmllib`
+ Base class for :class:`HTMLParser`.
+
+
+.. _html-parser-objects:
+
+HTMLParser Objects
+------------------
+
+In addition to tag methods, the :class:`HTMLParser` class provides some
+additional methods and instance variables for use within tag methods.
+
+
+.. attribute:: HTMLParser.formatter
+
+ This is the formatter instance associated with the parser.
+
+
+.. attribute:: HTMLParser.nofill
+
+ Boolean flag which should be true when whitespace should not be collapsed, or
+ false when it should be. In general, this should only be true when character
+ data is to be treated as "preformatted" text, as within a ``<PRE>`` element.
+ The default value is false. This affects the operation of :meth:`handle_data`
+ and :meth:`save_end`.
+
+
+.. method:: HTMLParser.anchor_bgn(href, name, type)
+
+ This method is called at the start of an anchor region. The arguments
+ correspond to the attributes of the ``<A>`` tag with the same names. The
+ default implementation maintains a list of hyperlinks (defined by the ``HREF``
+ attribute for ``<A>`` tags) within the document. The list of hyperlinks is
+ available as the data attribute :attr:`anchorlist`.
+
+
+.. method:: HTMLParser.anchor_end()
+
+ This method is called at the end of an anchor region. The default
+ implementation adds a textual footnote marker using an index into the list of
+ hyperlinks created by :meth:`anchor_bgn`.
+
+
+.. method:: HTMLParser.handle_image(source, alt[, ismap[, align[, width[, height]]]])
+
+ This method is called to handle images. The default implementation simply
+ passes the *alt* value to the :meth:`handle_data` method.
+
+
+.. method:: HTMLParser.save_bgn()
+
+ Begins saving character data in a buffer instead of sending it to the formatter
+ object. Retrieve the stored data via :meth:`save_end`. Use of the
+ :meth:`save_bgn` / :meth:`save_end` pair may not be nested.
+
+
+.. method:: HTMLParser.save_end()
+
+ Ends buffering character data and returns all data saved since the preceding
+ call to :meth:`save_bgn`. If the :attr:`nofill` flag is false, whitespace is
+ collapsed to single spaces. A call to this method without a preceding call to
+ :meth:`save_bgn` will raise a :exc:`TypeError` exception.
+
+
+:mod:`htmlentitydefs` --- Definitions of HTML general entities
+==============================================================
+
+.. module:: htmlentitydefs
+ :synopsis: Definitions of HTML general entities.
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+This module defines three dictionaries, ``name2codepoint``, ``codepoint2name``,
+and ``entitydefs``. ``entitydefs`` is used by the :mod:`htmllib` module to
+provide the :attr:`entitydefs` member of the :class:`HTMLParser` class. The
+definition provided here contains all the entities defined by XHTML 1.0 that
+can be handled using simple textual substitution in the Latin-1 character set
+(ISO-8859-1).
+
+
+.. data:: entitydefs
+
+ A dictionary mapping XHTML 1.0 entity definitions to their replacement text in
+ ISO Latin-1.
+
+
+.. data:: name2codepoint
+
+ A dictionary that maps HTML entity names to the Unicode codepoints.
+
+ .. versionadded:: 2.3
+
+
+.. data:: codepoint2name
+
+ A dictionary that maps Unicode codepoints to HTML entity names.
+
+ .. versionadded:: 2.3
+
--- /dev/null
+
+:mod:`HTMLParser` --- Simple HTML and XHTML parser
+==================================================
+
+.. module:: HTMLParser
+ :synopsis: A simple parser that can handle HTML and XHTML.
+
+
+.. versionadded:: 2.2
+
+.. index::
+ single: HTML
+ single: XHTML
+
+This module defines a class :class:`HTMLParser` which serves as the basis for
+parsing text files formatted in HTML (HyperText Mark-up Language) and XHTML.
+Unlike the parser in :mod:`htmllib`, this parser is not based on the SGML parser
+in :mod:`sgmllib`.
+
+
+.. class:: HTMLParser()
+
+ The :class:`HTMLParser` class is instantiated without arguments.
+
+ An HTMLParser instance is fed HTML data and calls handler functions when tags
+ begin and end. The :class:`HTMLParser` class is meant to be overridden by the
+ user to provide a desired behavior.
+
+ Unlike the parser in :mod:`htmllib`, this parser does not check that end tags
+ match start tags or call the end-tag handler for elements which are closed
+ implicitly by closing an outer element.
+
+An exception is defined as well:
+
+
+.. exception:: HTMLParseError
+
+ Exception raised by the :class:`HTMLParser` class when it encounters an error
+ while parsing. This exception provides three attributes: :attr:`msg` is a brief
+ message explaining the error, :attr:`lineno` is the number of the line on which
+ the broken construct was detected, and :attr:`offset` is the number of
+ characters into the line at which the construct starts.
+
+:class:`HTMLParser` instances have the following methods:
+
+
+.. method:: HTMLParser.reset()
+
+ Reset the instance. Loses all unprocessed data. This is called implicitly at
+ instantiation time.
+
+
+.. method:: HTMLParser.feed(data)
+
+ Feed some text to the parser. It is processed insofar as it consists of
+ complete elements; incomplete data is buffered until more data is fed or
+ :meth:`close` is called.
+
+
+.. method:: HTMLParser.close()
+
+ Force processing of all buffered data as if it were followed by an end-of-file
+ mark. This method may be redefined by a derived class to define additional
+ processing at the end of the input, but the redefined version should always call
+ the :class:`HTMLParser` base class method :meth:`close`.
+
+
+.. method:: HTMLParser.getpos()
+
+ Return current line number and offset.
+
+
+.. method:: HTMLParser.get_starttag_text()
+
+ Return the text of the most recently opened start tag. This should not normally
+ be needed for structured processing, but may be useful in dealing with HTML "as
+ deployed" or for re-generating input with minimal changes (whitespace between
+ attributes can be preserved, etc.).
+
+
+.. method:: HTMLParser.handle_starttag(tag, attrs)
+
+ This method is called to handle the start of a tag. It is intended to be
+ overridden by a derived class; the base class implementation does nothing.
+
+ The *tag* argument is the name of the tag converted to lower case. The *attrs*
+ argument is a list of ``(name, value)`` pairs containing the attributes found
+ inside the tag's ``<>`` brackets. The *name* will be translated to lower case,
+ and quotes in the *value* have been removed, and character and entity references
+ have been replaced. For instance, for the tag ``<A
+ HREF="http://www.cwi.nl/">``, this method would be called as
+ ``handle_starttag('a', [('href', 'http://www.cwi.nl/')])``.
+
+ .. versionchanged:: 2.6
+ All entity references from htmlentitydefs are now replaced in the attribute
+ values.
+
+
+.. method:: HTMLParser.handle_startendtag(tag, attrs)
+
+ Similar to :meth:`handle_starttag`, but called when the parser encounters an
+ XHTML-style empty tag (``<a .../>``). This method may be overridden by
+ subclasses which require this particular lexical information; the default
+ implementation simple calls :meth:`handle_starttag` and :meth:`handle_endtag`.
+
+
+.. method:: HTMLParser.handle_endtag(tag)
+
+ This method is called to handle the end tag of an element. It is intended to be
+ overridden by a derived class; the base class implementation does nothing. The
+ *tag* argument is the name of the tag converted to lower case.
+
+
+.. method:: HTMLParser.handle_data(data)
+
+ This method is called to process arbitrary data. It is intended to be
+ overridden by a derived class; the base class implementation does nothing.
+
+
+.. method:: HTMLParser.handle_charref(name)
+
+ This method is called to process a character reference of the form ``&#ref;``.
+ It is intended to be overridden by a derived class; the base class
+ implementation does nothing.
+
+
+.. method:: HTMLParser.handle_entityref(name)
+
+ This method is called to process a general entity reference of the form
+ ``&name;`` where *name* is an general entity reference. It is intended to be
+ overridden by a derived class; the base class implementation does nothing.
+
+
+.. method:: HTMLParser.handle_comment(data)
+
+ This method is called when a comment is encountered. The *comment* argument is
+ a string containing the text between the ``--`` and ``--`` delimiters, but not
+ the delimiters themselves. For example, the comment ``<!--text-->`` will cause
+ this method to be called with the argument ``'text'``. It is intended to be
+ overridden by a derived class; the base class implementation does nothing.
+
+
+.. method:: HTMLParser.handle_decl(decl)
+
+ Method called when an SGML declaration is read by the parser. The *decl*
+ parameter will be the entire contents of the declaration inside the ``<!``...\
+ ``>`` markup. It is intended to be overridden by a derived class; the base
+ class implementation does nothing.
+
+
+.. method:: HTMLParser.handle_pi(data)
+
+ Method called when a processing instruction is encountered. The *data*
+ parameter will contain the entire processing instruction. For example, for the
+ processing instruction ``<?proc color='red'>``, this method would be called as
+ ``handle_pi("proc color='red'")``. It is intended to be overridden by a derived
+ class; the base class implementation does nothing.
+
+ .. note::
+
+ The :class:`HTMLParser` class uses the SGML syntactic rules for processing
+ instructions. An XHTML processing instruction using the trailing ``'?'`` will
+ cause the ``'?'`` to be included in *data*.
+
+
+.. _htmlparser-example:
+
+Example HTML Parser Application
+-------------------------------
+
+As a basic example, below is a very basic HTML parser that uses the
+:class:`HTMLParser` class to print out tags as they are encountered::
+
+ from HTMLParser import HTMLParser
+
+ class MyHTMLParser(HTMLParser):
+
+ def handle_starttag(self, tag, attrs):
+ print "Encountered the beginning of a %s tag" % tag
+
+ def handle_endtag(self, tag):
+ print "Encountered the end of a %s tag" % tag
+
--- /dev/null
+
+:mod:`httplib` --- HTTP protocol client
+=======================================
+
+.. module:: httplib
+ :synopsis: HTTP and HTTPS protocol client (requires sockets).
+
+
+.. index::
+ pair: HTTP; protocol
+ single: HTTP; httplib (standard module)
+
+.. index:: module: urllib
+
+This module defines classes which implement the client side of the HTTP and
+HTTPS protocols. It is normally not used directly --- the module :mod:`urllib`
+uses it to handle URLs that use HTTP and HTTPS.
+
+.. note::
+
+ HTTPS support is only available if the :mod:`socket` module was compiled with
+ SSL support.
+
+.. note::
+
+ The public interface for this module changed substantially in Python 2.0. The
+ :class:`HTTP` class is retained only for backward compatibility with 1.5.2. It
+ should not be used in new code. Refer to the online docstrings for usage.
+
+The module provides the following classes:
+
+
+.. class:: HTTPConnection(host[, port[, strict[, timeout]]])
+
+ An :class:`HTTPConnection` instance represents one transaction with an HTTP
+ server. It should be instantiated passing it a host and optional port number.
+ If no port number is passed, the port is extracted from the host string if it
+ has the form ``host:port``, else the default HTTP port (80) is used. When True,
+ the optional parameter *strict* causes ``BadStatusLine`` to be raised if the
+ status line can't be parsed as a valid HTTP/1.0 or 1.1 status line. If the
+ optional *timeout* parameter is given, connection attempts will timeout after
+ that many seconds (if it is not given or ``None``, the global default timeout
+ setting is used).
+
+ For example, the following calls all create instances that connect to the server
+ at the same host and port::
+
+ >>> h1 = httplib.HTTPConnection('www.cwi.nl')
+ >>> h2 = httplib.HTTPConnection('www.cwi.nl:80')
+ >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)
+ >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80, timeout=10)
+
+ .. versionadded:: 2.0
+
+ .. versionchanged:: 2.6
+ *timeout* was added.
+
+
+.. class:: HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout]]]]])
+
+ A subclass of :class:`HTTPConnection` that uses SSL for communication with
+ secure servers. Default port is ``443``. *key_file* is the name of a PEM
+ formatted file that contains your private key. *cert_file* is a PEM formatted
+ certificate chain file.
+
+ .. warning::
+
+ This does not do any certificate verification!
+
+ .. versionadded:: 2.0
+
+ .. versionchanged:: 2.6
+ *timeout* was added.
+
+
+.. class:: HTTPResponse(sock[, debuglevel=0][, strict=0])
+
+ Class whose instances are returned upon successful connection. Not instantiated
+ directly by user.
+
+ .. versionadded:: 2.0
+
+The following exceptions are raised as appropriate:
+
+
+.. exception:: HTTPException
+
+ The base class of the other exceptions in this module. It is a subclass of
+ :exc:`Exception`.
+
+ .. versionadded:: 2.0
+
+
+.. exception:: NotConnected
+
+ A subclass of :exc:`HTTPException`.
+
+ .. versionadded:: 2.0
+
+
+.. exception:: InvalidURL
+
+ A subclass of :exc:`HTTPException`, raised if a port is given and is either
+ non-numeric or empty.
+
+ .. versionadded:: 2.3
+
+
+.. exception:: UnknownProtocol
+
+ A subclass of :exc:`HTTPException`.
+
+ .. versionadded:: 2.0
+
+
+.. exception:: UnknownTransferEncoding
+
+ A subclass of :exc:`HTTPException`.
+
+ .. versionadded:: 2.0
+
+
+.. exception:: UnimplementedFileMode
+
+ A subclass of :exc:`HTTPException`.
+
+ .. versionadded:: 2.0
+
+
+.. exception:: IncompleteRead
+
+ A subclass of :exc:`HTTPException`.
+
+ .. versionadded:: 2.0
+
+
+.. exception:: ImproperConnectionState
+
+ A subclass of :exc:`HTTPException`.
+
+ .. versionadded:: 2.0
+
+
+.. exception:: CannotSendRequest
+
+ A subclass of :exc:`ImproperConnectionState`.
+
+ .. versionadded:: 2.0
+
+
+.. exception:: CannotSendHeader
+
+ A subclass of :exc:`ImproperConnectionState`.
+
+ .. versionadded:: 2.0
+
+
+.. exception:: ResponseNotReady
+
+ A subclass of :exc:`ImproperConnectionState`.
+
+ .. versionadded:: 2.0
+
+
+.. exception:: BadStatusLine
+
+ A subclass of :exc:`HTTPException`. Raised if a server responds with a HTTP
+ status code that we don't understand.
+
+ .. versionadded:: 2.0
+
+The constants defined in this module are:
+
+
+.. data:: HTTP_PORT
+
+ The default port for the HTTP protocol (always ``80``).
+
+
+.. data:: HTTPS_PORT
+
+ The default port for the HTTPS protocol (always ``443``).
+
+and also the following constants for integer status codes:
+
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| Constant | Value | Definition |
++==========================================+=========+=======================================================================+
+| :const:`CONTINUE` | ``100`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.1.1 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.1>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`SWITCHING_PROTOCOLS` | ``101`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.1.2 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.2>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`PROCESSING` | ``102`` | WEBDAV, `RFC 2518, Section 10.1 |
+| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_102>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`OK` | ``200`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.2.1 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`CREATED` | ``201`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.2.2 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`ACCEPTED` | ``202`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.2.3 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`NON_AUTHORITATIVE_INFORMATION` | ``203`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.2.4 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.4>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`NO_CONTENT` | ``204`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.2.5 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`RESET_CONTENT` | ``205`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.2.6 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.6>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`PARTIAL_CONTENT` | ``206`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.2.7 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.7>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`MULTI_STATUS` | ``207`` | WEBDAV `RFC 2518, Section 10.2 |
+| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_207>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`IM_USED` | ``226`` | Delta encoding in HTTP, |
+| | | :rfc:`3229`, Section 10.4.1 |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`MULTIPLE_CHOICES` | ``300`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.3.1 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.1>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`MOVED_PERMANENTLY` | ``301`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.3.2 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`FOUND` | ``302`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.3.3 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`SEE_OTHER` | ``303`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.3.4 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.4>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`NOT_MODIFIED` | ``304`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.3.5 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.5>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`USE_PROXY` | ``305`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.3.6 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.6>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`TEMPORARY_REDIRECT` | ``307`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.3.8 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.8>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`BAD_REQUEST` | ``400`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.1 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`UNAUTHORIZED` | ``401`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.2 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`PAYMENT_REQUIRED` | ``402`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.3 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.3>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`FORBIDDEN` | ``403`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.4 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`NOT_FOUND` | ``404`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.5 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`METHOD_NOT_ALLOWED` | ``405`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.6 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`NOT_ACCEPTABLE` | ``406`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.7 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`PROXY_AUTHENTICATION_REQUIRED` | ``407`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.8 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.8>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`REQUEST_TIMEOUT` | ``408`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.9 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.9>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`CONFLICT` | ``409`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.10 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`GONE` | ``410`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.11 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.11>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`LENGTH_REQUIRED` | ``411`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.12 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.12>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`PRECONDITION_FAILED` | ``412`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.13 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.13>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`REQUEST_ENTITY_TOO_LARGE` | ``413`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.14 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.14>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`REQUEST_URI_TOO_LONG` | ``414`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.15 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.15>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`UNSUPPORTED_MEDIA_TYPE` | ``415`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.16 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`REQUESTED_RANGE_NOT_SATISFIABLE` | ``416`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.17 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.17>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`EXPECTATION_FAILED` | ``417`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.4.18 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.18>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`UNPROCESSABLE_ENTITY` | ``422`` | WEBDAV, `RFC 2518, Section 10.3 |
+| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_422>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`LOCKED` | ``423`` | WEBDAV `RFC 2518, Section 10.4 |
+| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_423>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`FAILED_DEPENDENCY` | ``424`` | WEBDAV, `RFC 2518, Section 10.5 |
+| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_424>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`UPGRADE_REQUIRED` | ``426`` | HTTP Upgrade to TLS, |
+| | | :rfc:`2817`, Section 6 |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`INTERNAL_SERVER_ERROR` | ``500`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.5.1 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`NOT_IMPLEMENTED` | ``501`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.5.2 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`BAD_GATEWAY` | ``502`` | HTTP/1.1 `RFC 2616, Section |
+| | | 10.5.3 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.3>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`SERVICE_UNAVAILABLE` | ``503`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.5.4 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`GATEWAY_TIMEOUT` | ``504`` | HTTP/1.1 `RFC 2616, Section |
+| | | 10.5.5 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.5>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`HTTP_VERSION_NOT_SUPPORTED` | ``505`` | HTTP/1.1, `RFC 2616, Section |
+| | | 10.5.6 |
+| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.6>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`INSUFFICIENT_STORAGE` | ``507`` | WEBDAV, `RFC 2518, Section 10.6 |
+| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_507>`_ |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+| :const:`NOT_EXTENDED` | ``510`` | An HTTP Extension Framework, |
+| | | :rfc:`2774`, Section 7 |
++------------------------------------------+---------+-----------------------------------------------------------------------+
+
+
+.. data:: responses
+
+ This dictionary maps the HTTP 1.1 status codes to the W3C names.
+
+ Example: ``httplib.responses[httplib.NOT_FOUND]`` is ``'Not Found'``.
+
+ .. versionadded:: 2.5
+
+
+.. _httpconnection-objects:
+
+HTTPConnection Objects
+----------------------
+
+:class:`HTTPConnection` instances have the following methods:
+
+
+.. method:: HTTPConnection.request(method, url[, body[, headers]])
+
+ This will send a request to the server using the HTTP request method *method*
+ and the selector *url*. If the *body* argument is present, it should be a
+ string of data to send after the headers are finished. Alternatively, it may
+ be an open file object, in which case the contents of the file is sent; this
+ file object should support ``fileno()`` and ``read()`` methods. The header
+ Content-Length is automatically set to the correct value. The *headers*
+ argument should be a mapping of extra HTTP headers to send with the request.
+
+ .. versionchanged:: 2.6
+ *body* can be a file object.
+
+
+.. method:: HTTPConnection.getresponse()
+
+ Should be called after a request is sent to get the response from the server.
+ Returns an :class:`HTTPResponse` instance.
+
+ .. note::
+
+ Note that you must have read the whole response before you can send a new
+ request to the server.
+
+
+.. method:: HTTPConnection.set_debuglevel(level)
+
+ Set the debugging level (the amount of debugging output printed). The default
+ debug level is ``0``, meaning no debugging output is printed.
+
+
+.. method:: HTTPConnection.connect()
+
+ Connect to the server specified when the object was created.
+
+
+.. method:: HTTPConnection.close()
+
+ Close the connection to the server.
+
+As an alternative to using the :meth:`request` method described above, you can
+also send your request step by step, by using the four functions below.
+
+
+.. method:: HTTPConnection.putrequest(request, selector[, skip_host[, skip_accept_encoding]])
+
+ This should be the first call after the connection to the server has been made.
+ It sends a line to the server consisting of the *request* string, the *selector*
+ string, and the HTTP version (``HTTP/1.1``). To disable automatic sending of
+ ``Host:`` or ``Accept-Encoding:`` headers (for example to accept additional
+ content encodings), specify *skip_host* or *skip_accept_encoding* with non-False
+ values.
+
+ .. versionchanged:: 2.4
+ *skip_accept_encoding* argument added.
+
+
+.. method:: HTTPConnection.putheader(header, argument[, ...])
+
+ Send an :rfc:`822`\ -style header to the server. It sends a line to the server
+ consisting of the header, a colon and a space, and the first argument. If more
+ arguments are given, continuation lines are sent, each consisting of a tab and
+ an argument.
+
+
+.. method:: HTTPConnection.endheaders()
+
+ Send a blank line to the server, signalling the end of the headers.
+
+
+.. method:: HTTPConnection.send(data)
+
+ Send data to the server. This should be used directly only after the
+ :meth:`endheaders` method has been called and before :meth:`getresponse` is
+ called.
+
+
+.. _httpresponse-objects:
+
+HTTPResponse Objects
+--------------------
+
+:class:`HTTPResponse` instances have the following methods and attributes:
+
+
+.. method:: HTTPResponse.read([amt])
+
+ Reads and returns the response body, or up to the next *amt* bytes.
+
+
+.. method:: HTTPResponse.getheader(name[, default])
+
+ Get the contents of the header *name*, or *default* if there is no matching
+ header.
+
+
+.. method:: HTTPResponse.getheaders()
+
+ Return a list of (header, value) tuples.
+
+ .. versionadded:: 2.4
+
+
+.. attribute:: HTTPResponse.msg
+
+ A :class:`mimetools.Message` instance containing the response headers.
+
+
+.. attribute:: HTTPResponse.version
+
+ HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1.
+
+
+.. attribute:: HTTPResponse.status
+
+ Status code returned by server.
+
+
+.. attribute:: HTTPResponse.reason
+
+ Reason phrase returned by server.
+
+
+.. _httplib-examples:
+
+Examples
+--------
+
+Here is an example session that uses the ``GET`` method::
+
+ >>> import httplib
+ >>> conn = httplib.HTTPConnection("www.python.org")
+ >>> conn.request("GET", "/index.html")
+ >>> r1 = conn.getresponse()
+ >>> print r1.status, r1.reason
+ 200 OK
+ >>> data1 = r1.read()
+ >>> conn.request("GET", "/parrot.spam")
+ >>> r2 = conn.getresponse()
+ >>> print r2.status, r2.reason
+ 404 Not Found
+ >>> data2 = r2.read()
+ >>> conn.close()
+
+Here is an example session that shows how to ``POST`` requests::
+
+ >>> import httplib, urllib
+ >>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
+ >>> headers = {"Content-type": "application/x-www-form-urlencoded",
+ ... "Accept": "text/plain"}
+ >>> conn = httplib.HTTPConnection("musi-cal.mojam.com:80")
+ >>> conn.request("POST", "/cgi-bin/query", params, headers)
+ >>> response = conn.getresponse()
+ >>> print response.status, response.reason
+ 200 OK
+ >>> data = response.read()
+ >>> conn.close()
+
--- /dev/null
+
+.. _i18n:
+
+********************
+Internationalization
+********************
+
+The modules described in this chapter help you write software that is
+independent of language and locale by providing mechanisms for selecting a
+language to be used in program messages or by tailoring output to match local
+conventions.
+
+The list of modules described in this chapter is:
+
+
+.. toctree::
+
+ gettext.rst
+ locale.rst
--- /dev/null
+
+:mod:`ic` --- Access to the Mac OS X Internet Config
+====================================================
+
+.. module:: ic
+ :platform: Mac
+ :synopsis: Access to the Mac OS X Internet Config.
+
+
+This module provides access to various internet-related preferences set through
+:program:`System Preferences` or the :program:`Finder`.
+
+.. index:: module: icglue
+
+There is a low-level companion module :mod:`icglue` which provides the basic
+Internet Config access functionality. This low-level module is not documented,
+but the docstrings of the routines document the parameters and the routine names
+are the same as for the Pascal or C API to Internet Config, so the standard IC
+programmers' documentation can be used if this module is needed.
+
+The :mod:`ic` module defines the :exc:`error` exception and symbolic names for
+all error codes Internet Config can produce; see the source for details.
+
+
+.. exception:: error
+
+ Exception raised on errors in the :mod:`ic` module.
+
+The :mod:`ic` module defines the following class and function:
+
+
+.. class:: IC([signature[, ic]])
+
+ Create an Internet Config object. The signature is a 4-character creator code of
+ the current application (default ``'Pyth'``) which may influence some of ICs
+ settings. The optional *ic* argument is a low-level ``icglue.icinstance``
+ created beforehand, this may be useful if you want to get preferences from a
+ different config file, etc.
+
+
+.. function:: launchurl(url[, hint])
+ parseurl(data[, start[, end[, hint]]])
+ mapfile(file)
+ maptypecreator(type, creator[, filename])
+ settypecreator(file)
+
+ These functions are "shortcuts" to the methods of the same name, described
+ below.
+
+
+IC Objects
+----------
+
+:class:`IC` objects have a mapping interface, hence to obtain the mail address
+you simply get ``ic['MailAddress']``. Assignment also works, and changes the
+option in the configuration file.
+
+The module knows about various datatypes, and converts the internal IC
+representation to a "logical" Python data structure. Running the :mod:`ic`
+module standalone will run a test program that lists all keys and values in your
+IC database, this will have to serve as documentation.
+
+If the module does not know how to represent the data it returns an instance of
+the ``ICOpaqueData`` type, with the raw data in its :attr:`data` attribute.
+Objects of this type are also acceptable values for assignment.
+
+Besides the dictionary interface, :class:`IC` objects have the following
+methods:
+
+
+.. method:: IC.launchurl(url[, hint])
+
+ Parse the given URL, launch the correct application and pass it the URL. The
+ optional *hint* can be a scheme name such as ``'mailto:'``, in which case
+ incomplete URLs are completed with this scheme. If *hint* is not provided,
+ incomplete URLs are invalid.
+
+
+.. method:: IC.parseurl(data[, start[, end[, hint]]])
+
+ Find an URL somewhere in *data* and return start position, end position and the
+ URL. The optional *start* and *end* can be used to limit the search, so for
+ instance if a user clicks in a long text field you can pass the whole text field
+ and the click-position in *start* and this routine will return the whole URL in
+ which the user clicked. As above, *hint* is an optional scheme used to complete
+ incomplete URLs.
+
+
+.. method:: IC.mapfile(file)
+
+ Return the mapping entry for the given *file*, which can be passed as either a
+ filename or an :func:`FSSpec` result, and which need not exist.
+
+ The mapping entry is returned as a tuple ``(version, type, creator, postcreator,
+ flags, extension, appname, postappname, mimetype, entryname)``, where *version*
+ is the entry version number, *type* is the 4-character filetype, *creator* is
+ the 4-character creator type, *postcreator* is the 4-character creator code of
+ an optional application to post-process the file after downloading, *flags* are
+ various bits specifying whether to transfer in binary or ascii and such,
+ *extension* is the filename extension for this file type, *appname* is the
+ printable name of the application to which this file belongs, *postappname* is
+ the name of the postprocessing application, *mimetype* is the MIME type of this
+ file and *entryname* is the name of this entry.
+
+
+.. method:: IC.maptypecreator(type, creator[, filename])
+
+ Return the mapping entry for files with given 4-character *type* and *creator*
+ codes. The optional *filename* may be specified to further help finding the
+ correct entry (if the creator code is ``'????'``, for instance).
+
+ The mapping entry is returned in the same format as for *mapfile*.
+
+
+.. method:: IC.settypecreator(file)
+
+ Given an existing *file*, specified either as a filename or as an :func:`FSSpec`
+ result, set its creator and type correctly based on its extension. The finder
+ is told about the change, so the finder icon will be updated quickly.
--- /dev/null
+.. _idle:
+
+Idle
+====
+
+.. moduleauthor:: Guido van Rossum <guido@Python.org>
+
+
+.. % \declaremodule{standard}{idle}
+.. % \modulesynopsis{A Python Integrated Development Environment}
+
+.. index::
+ single: Idle
+ single: Python Editor
+ single: Integrated Development Environment
+
+Idle is the Python IDE built with the :mod:`Tkinter` GUI toolkit.
+
+IDLE has the following features:
+
+* coded in 100% pure Python, using the :mod:`Tkinter` GUI toolkit
+
+* cross-platform: works on Windows and Unix (on Mac OS, there are currently
+ problems with Tcl/Tk)
+
+* multi-window text editor with multiple undo, Python colorizing and many other
+ features, e.g. smart indent and call tips
+
+* Python shell window (a.k.a. interactive interpreter)
+
+* debugger (not complete, but you can set breakpoints, view and step)
+
+
+Menus
+-----
+
+
+File menu
+^^^^^^^^^
+
+New window
+ create a new editing window
+
+Open...
+ open an existing file
+
+Open module...
+ open an existing module (searches sys.path)
+
+Class browser
+ show classes and methods in current file
+
+Path browser
+ show sys.path directories, modules, classes and methods
+
+.. index::
+ single: Class browser
+ single: Path browser
+
+Save
+ save current window to the associated file (unsaved windows have a \* before and
+ after the window title)
+
+Save As...
+ save current window to new file, which becomes the associated file
+
+Save Copy As...
+ save current window to different file without changing the associated file
+
+Close
+ close current window (asks to save if unsaved)
+
+Exit
+ close all windows and quit IDLE (asks to save if unsaved)
+
+
+Edit menu
+^^^^^^^^^
+
+Undo
+ Undo last change to current window (max 1000 changes)
+
+Redo
+ Redo last undone change to current window
+
+Cut
+ Copy selection into system-wide clipboard; then delete selection
+
+Copy
+ Copy selection into system-wide clipboard
+
+Paste
+ Insert system-wide clipboard into window
+
+Select All
+ Select the entire contents of the edit buffer
+
+Find...
+ Open a search dialog box with many options
+
+Find again
+ Repeat last search
+
+Find selection
+ Search for the string in the selection
+
+Find in Files...
+ Open a search dialog box for searching files
+
+Replace...
+ Open a search-and-replace dialog box
+
+Go to line
+ Ask for a line number and show that line
+
+Indent region
+ Shift selected lines right 4 spaces
+
+Dedent region
+ Shift selected lines left 4 spaces
+
+Comment out region
+ Insert ## in front of selected lines
+
+Uncomment region
+ Remove leading # or ## from selected lines
+
+Tabify region
+ Turns *leading* stretches of spaces into tabs
+
+Untabify region
+ Turn *all* tabs into the right number of spaces
+
+Expand word
+ Expand the word you have typed to match another word in the same buffer; repeat
+ to get a different expansion
+
+Format Paragraph
+ Reformat the current blank-line-separated paragraph
+
+Import module
+ Import or reload the current module
+
+Run script
+ Execute the current file in the __main__ namespace
+
+.. index::
+ single: Import module
+ single: Run script
+
+
+Windows menu
+^^^^^^^^^^^^
+
+Zoom Height
+ toggles the window between normal size (24x80) and maximum height.
+
+The rest of this menu lists the names of all open windows; select one to bring
+it to the foreground (deiconifying it if necessary).
+
+
+Debug menu (in the Python Shell window only)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Go to file/line
+ look around the insert point for a filename and linenumber, open the file, and
+ show the line.
+
+Open stack viewer
+ show the stack traceback of the last exception
+
+Debugger toggle
+ Run commands in the shell under the debugger
+
+JIT Stack viewer toggle
+ Open stack viewer on traceback
+
+.. index::
+ single: stack viewer
+ single: debugger
+
+
+Basic editing and navigation
+----------------------------
+
+* :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right
+
+* Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around
+
+* :kbd:`Home`/:kbd:`End` go to begin/end of line
+
+* :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file
+
+* Some :program:`Emacs` bindings may also work, including :kbd:`C-B`,
+ :kbd:`C-P`, :kbd:`C-A`, :kbd:`C-E`, :kbd:`C-D`, :kbd:`C-L`
+
+
+Automatic indentation
+^^^^^^^^^^^^^^^^^^^^^
+
+After a block-opening statement, the next line is indented by 4 spaces (in the
+Python Shell window by one tab). After certain keywords (break, return etc.)
+the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up
+to 4 spaces if they are there. :kbd:`Tab` inserts 1-4 spaces (in the Python
+Shell window one tab). See also the indent/dedent region commands in the edit
+menu.
+
+
+Python Shell window
+^^^^^^^^^^^^^^^^^^^
+
+* :kbd:`C-C` interrupts executing command
+
+* :kbd:`C-D` sends end-of-file; closes window if typed at a ``>>>`` prompt
+
+* :kbd:`Alt-p` retrieves previous command matching what you have typed
+
+* :kbd:`Alt-n` retrieves next
+
+* :kbd:`Return` while on any previous command retrieves that command
+
+* :kbd:`Alt-/` (Expand word) is also useful here
+
+.. index:: single: indentation
+
+
+Syntax colors
+-------------
+
+The coloring is applied in a background "thread," so you may occasionally see
+uncolorized text. To change the color scheme, edit the ``[Colors]`` section in
+:file:`config.txt`.
+
+Python syntax colors:
+ Keywords
+ orange
+
+ Strings
+ green
+
+ Comments
+ red
+
+ Definitions
+ blue
+
+Shell colors:
+ Console output
+ brown
+
+ stdout
+ blue
+
+ stderr
+ dark green
+
+ stdin
+ black
+
+
+Command line usage
+^^^^^^^^^^^^^^^^^^
+
+::
+
+ idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ...
+
+ -c command run this command
+ -d enable debugger
+ -e edit mode; arguments are files to be edited
+ -s run $IDLESTARTUP or $PYTHONSTARTUP first
+ -t title set title of shell window
+
+If there are arguments:
+
+#. If :option:`-e` is used, arguments are files opened for editing and
+ ``sys.argv`` reflects the arguments passed to IDLE itself.
+
+#. Otherwise, if :option:`-c` is used, all arguments are placed in
+ ``sys.argv[1:...]``, with ``sys.argv[0]`` set to ``'-c'``.
+
+#. Otherwise, if neither :option:`-e` nor :option:`-c` is used, the first
+ argument is a script which is executed with the remaining arguments in
+ ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the script
+ name is '-', no script is executed but an interactive Python session is started;
+ the arguments are still available in ``sys.argv``.
+
+
--- /dev/null
+
+:mod:`imageop` --- Manipulate raw image data
+============================================
+
+.. module:: imageop
+ :synopsis: Manipulate raw image data.
+
+
+The :mod:`imageop` module contains some useful operations on images. It operates
+on images consisting of 8 or 32 bit pixels stored in Python strings. This is
+the same format as used by :func:`gl.lrectwrite` and the :mod:`imgfile` module.
+
+The module defines the following variables and functions:
+
+
+.. exception:: error
+
+ This exception is raised on all errors, such as unknown number of bits per
+ pixel, etc.
+
+
+.. function:: crop(image, psize, width, height, x0, y0, x1, y1)
+
+ Return the selected part of *image*, which should be *width* by *height* in size
+ and consist of pixels of *psize* bytes. *x0*, *y0*, *x1* and *y1* are like the
+ :func:`gl.lrectread` parameters, i.e. the boundary is included in the new image.
+ The new boundaries need not be inside the picture. Pixels that fall outside the
+ old image will have their value set to zero. If *x0* is bigger than *x1* the
+ new image is mirrored. The same holds for the y coordinates.
+
+
+.. function:: scale(image, psize, width, height, newwidth, newheight)
+
+ Return *image* scaled to size *newwidth* by *newheight*. No interpolation is
+ done, scaling is done by simple-minded pixel duplication or removal. Therefore,
+ computer-generated images or dithered images will not look nice after scaling.
+
+
+.. function:: tovideo(image, psize, width, height)
+
+ Run a vertical low-pass filter over an image. It does so by computing each
+ destination pixel as the average of two vertically-aligned source pixels. The
+ main use of this routine is to forestall excessive flicker if the image is
+ displayed on a video device that uses interlacing, hence the name.
+
+
+.. function:: grey2mono(image, width, height, threshold)
+
+ Convert a 8-bit deep greyscale image to a 1-bit deep image by thresholding all
+ the pixels. The resulting image is tightly packed and is probably only useful
+ as an argument to :func:`mono2grey`.
+
+
+.. function:: dither2mono(image, width, height)
+
+ Convert an 8-bit greyscale image to a 1-bit monochrome image using a
+ (simple-minded) dithering algorithm.
+
+
+.. function:: mono2grey(image, width, height, p0, p1)
+
+ Convert a 1-bit monochrome image to an 8 bit greyscale or color image. All
+ pixels that are zero-valued on input get value *p0* on output and all one-value
+ input pixels get value *p1* on output. To convert a monochrome black-and-white
+ image to greyscale pass the values ``0`` and ``255`` respectively.
+
+
+.. function:: grey2grey4(image, width, height)
+
+ Convert an 8-bit greyscale image to a 4-bit greyscale image without dithering.
+
+
+.. function:: grey2grey2(image, width, height)
+
+ Convert an 8-bit greyscale image to a 2-bit greyscale image without dithering.
+
+
+.. function:: dither2grey2(image, width, height)
+
+ Convert an 8-bit greyscale image to a 2-bit greyscale image with dithering. As
+ for :func:`dither2mono`, the dithering algorithm is currently very simple.
+
+
+.. function:: grey42grey(image, width, height)
+
+ Convert a 4-bit greyscale image to an 8-bit greyscale image.
+
+
+.. function:: grey22grey(image, width, height)
+
+ Convert a 2-bit greyscale image to an 8-bit greyscale image.
+
+
+.. data:: backward_compatible
+
+ If set to 0, the functions in this module use a non-backward compatible way
+ of representing multi-byte pixels on little-endian systems. The SGI for
+ which this module was originally written is a big-endian system, so setting
+ this variable will have no effect. However, the code wasn't originally
+ intended to run on anything else, so it made assumptions about byte order
+ which are not universal. Setting this variable to 0 will cause the byte
+ order to be reversed on little-endian systems, so that it then is the same as
+ on big-endian systems.
+
--- /dev/null
+
+:mod:`imaplib` --- IMAP4 protocol client
+========================================
+
+.. module:: imaplib
+ :synopsis: IMAP4 protocol client (requires sockets).
+.. moduleauthor:: Piers Lauder <piers@communitysolutions.com.au>
+.. sectionauthor:: Piers Lauder <piers@communitysolutions.com.au>
+
+
+.. index::
+ pair: IMAP4; protocol
+ pair: IMAP4_SSL; protocol
+ pair: IMAP4_stream; protocol
+
+.. % Based on HTML documentation by Piers Lauder
+.. % <piers@communitysolutions.com.au>;
+.. % converted by Fred L. Drake, Jr. <fdrake@acm.org>.
+.. % Revised by ESR, January 2000.
+.. % Changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002
+.. % Changes for IMAP4_stream by Piers Lauder
+.. % <piers@communitysolutions.com.au>, November 2002
+
+This module defines three classes, :class:`IMAP4`, :class:`IMAP4_SSL` and
+:class:`IMAP4_stream`, which encapsulate a connection to an IMAP4 server and
+implement a large subset of the IMAP4rev1 client protocol as defined in
+:rfc:`2060`. It is backward compatible with IMAP4 (:rfc:`1730`) servers, but
+note that the ``STATUS`` command is not supported in IMAP4.
+
+Three classes are provided by the :mod:`imaplib` module, :class:`IMAP4` is the
+base class:
+
+
+.. class:: IMAP4([host[, port]])
+
+ This class implements the actual IMAP4 protocol. The connection is created and
+ protocol version (IMAP4 or IMAP4rev1) is determined when the instance is
+ initialized. If *host* is not specified, ``''`` (the local host) is used. If
+ *port* is omitted, the standard IMAP4 port (143) is used.
+
+Three exceptions are defined as attributes of the :class:`IMAP4` class:
+
+
+.. exception:: IMAP4.error
+
+ Exception raised on any errors. The reason for the exception is passed to the
+ constructor as a string.
+
+
+.. exception:: IMAP4.abort
+
+ IMAP4 server errors cause this exception to be raised. This is a sub-class of
+ :exc:`IMAP4.error`. Note that closing the instance and instantiating a new one
+ will usually allow recovery from this exception.
+
+
+.. exception:: IMAP4.readonly
+
+ This exception is raised when a writable mailbox has its status changed by the
+ server. This is a sub-class of :exc:`IMAP4.error`. Some other client now has
+ write permission, and the mailbox will need to be re-opened to re-obtain write
+ permission.
+
+There's also a subclass for secure connections:
+
+
+.. class:: IMAP4_SSL([host[, port[, keyfile[, certfile]]]])
+
+ This is a subclass derived from :class:`IMAP4` that connects over an SSL
+ encrypted socket (to use this class you need a socket module that was compiled
+ with SSL support). If *host* is not specified, ``''`` (the local host) is used.
+ If *port* is omitted, the standard IMAP4-over-SSL port (993) is used. *keyfile*
+ and *certfile* are also optional - they can contain a PEM formatted private key
+ and certificate chain file for the SSL connection.
+
+The second subclass allows for connections created by a child process:
+
+
+.. class:: IMAP4_stream(command)
+
+ This is a subclass derived from :class:`IMAP4` that connects to the
+ ``stdin/stdout`` file descriptors created by passing *command* to
+ ``os.popen2()``.
+
+ .. versionadded:: 2.3
+
+The following utility functions are defined:
+
+
+.. function:: Internaldate2tuple(datestr)
+
+ Converts an IMAP4 INTERNALDATE string to Coordinated Universal Time. Returns a
+ :mod:`time` module tuple.
+
+
+.. function:: Int2AP(num)
+
+ Converts an integer into a string representation using characters from the set
+ [``A`` .. ``P``].
+
+
+.. function:: ParseFlags(flagstr)
+
+ Converts an IMAP4 ``FLAGS`` response to a tuple of individual flags.
+
+
+.. function:: Time2Internaldate(date_time)
+
+ Converts a :mod:`time` module tuple to an IMAP4 ``INTERNALDATE`` representation.
+ Returns a string in the form: ``"DD-Mmm-YYYY HH:MM:SS +HHMM"`` (including
+ double-quotes).
+
+Note that IMAP4 message numbers change as the mailbox changes; in particular,
+after an ``EXPUNGE`` command performs deletions the remaining messages are
+renumbered. So it is highly advisable to use UIDs instead, with the UID command.
+
+At the end of the module, there is a test section that contains a more extensive
+example of usage.
+
+
+.. seealso::
+
+ Documents describing the protocol, and sources and binaries for servers
+ implementing it, can all be found at the University of Washington's *IMAP
+ Information Center* (http://www.cac.washington.edu/imap/).
+
+
+.. _imap4-objects:
+
+IMAP4 Objects
+-------------
+
+All IMAP4rev1 commands are represented by methods of the same name, either
+upper-case or lower-case.
+
+All arguments to commands are converted to strings, except for ``AUTHENTICATE``,
+and the last argument to ``APPEND`` which is passed as an IMAP4 literal. If
+necessary (the string contains IMAP4 protocol-sensitive characters and isn't
+enclosed with either parentheses or double quotes) each string is quoted.
+However, the *password* argument to the ``LOGIN`` command is always quoted. If
+you want to avoid having an argument string quoted (eg: the *flags* argument to
+``STORE``) then enclose the string in parentheses (eg: ``r'(\Deleted)'``).
+
+Each command returns a tuple: ``(type, [data, ...])`` where *type* is usually
+``'OK'`` or ``'NO'``, and *data* is either the text from the command response,
+or mandated results from the command. Each *data* is either a string, or a
+tuple. If a tuple, then the first part is the header of the response, and the
+second part contains the data (ie: 'literal' value).
+
+The *message_set* options to commands below is a string specifying one or more
+messages to be acted upon. It may be a simple message number (``'1'``), a range
+of message numbers (``'2:4'``), or a group of non-contiguous ranges separated by
+commas (``'1:3,6:9'``). A range can contain an asterisk to indicate an infinite
+upper bound (``'3:*'``).
+
+An :class:`IMAP4` instance has the following methods:
+
+
+.. method:: IMAP4.append(mailbox, flags, date_time, message)
+
+ Append *message* to named mailbox.
+
+
+.. method:: IMAP4.authenticate(mechanism, authobject)
+
+ Authenticate command --- requires response processing.
+
+ *mechanism* specifies which authentication mechanism is to be used - it should
+ appear in the instance variable ``capabilities`` in the form ``AUTH=mechanism``.
+
+ *authobject* must be a callable object::
+
+ data = authobject(response)
+
+ It will be called to process server continuation responses. It should return
+ ``data`` that will be encoded and sent to server. It should return ``None`` if
+ the client abort response ``*`` should be sent instead.
+
+
+.. method:: IMAP4.check()
+
+ Checkpoint mailbox on server.
+
+
+.. method:: IMAP4.close()
+
+ Close currently selected mailbox. Deleted messages are removed from writable
+ mailbox. This is the recommended command before ``LOGOUT``.
+
+
+.. method:: IMAP4.copy(message_set, new_mailbox)
+
+ Copy *message_set* messages onto end of *new_mailbox*.
+
+
+.. method:: IMAP4.create(mailbox)
+
+ Create new mailbox named *mailbox*.
+
+
+.. method:: IMAP4.delete(mailbox)
+
+ Delete old mailbox named *mailbox*.
+
+
+.. method:: IMAP4.deleteacl(mailbox, who)
+
+ Delete the ACLs (remove any rights) set for who on mailbox.
+
+ .. versionadded:: 2.4
+
+
+.. method:: IMAP4.expunge()
+
+ Permanently remove deleted items from selected mailbox. Generates an ``EXPUNGE``
+ response for each deleted message. Returned data contains a list of ``EXPUNGE``
+ message numbers in order received.
+
+
+.. method:: IMAP4.fetch(message_set, message_parts)
+
+ Fetch (parts of) messages. *message_parts* should be a string of message part
+ names enclosed within parentheses, eg: ``"(UID BODY[TEXT])"``. Returned data
+ are tuples of message part envelope and data.
+
+
+.. method:: IMAP4.getacl(mailbox)
+
+ Get the ``ACL``\ s for *mailbox*. The method is non-standard, but is supported
+ by the ``Cyrus`` server.
+
+
+.. method:: IMAP4.getannotation(mailbox, entry, attribute)
+
+ Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is
+ non-standard, but is supported by the ``Cyrus`` server.
+
+ .. versionadded:: 2.5
+
+
+.. method:: IMAP4.getquota(root)
+
+ Get the ``quota`` *root*'s resource usage and limits. This method is part of the
+ IMAP4 QUOTA extension defined in rfc2087.
+
+ .. versionadded:: 2.3
+
+
+.. method:: IMAP4.getquotaroot(mailbox)
+
+ Get the list of ``quota`` ``roots`` for the named *mailbox*. This method is part
+ of the IMAP4 QUOTA extension defined in rfc2087.
+
+ .. versionadded:: 2.3
+
+
+.. method:: IMAP4.list([directory[, pattern]])
+
+ List mailbox names in *directory* matching *pattern*. *directory* defaults to
+ the top-level mail folder, and *pattern* defaults to match anything. Returned
+ data contains a list of ``LIST`` responses.
+
+
+.. method:: IMAP4.login(user, password)
+
+ Identify the client using a plaintext password. The *password* will be quoted.
+
+
+.. method:: IMAP4.login_cram_md5(user, password)
+
+ Force use of ``CRAM-MD5`` authentication when identifying the client to protect
+ the password. Will only work if the server ``CAPABILITY`` response includes the
+ phrase ``AUTH=CRAM-MD5``.
+
+ .. versionadded:: 2.3
+
+
+.. method:: IMAP4.logout()
+
+ Shutdown connection to server. Returns server ``BYE`` response.
+
+
+.. method:: IMAP4.lsub([directory[, pattern]])
+
+ List subscribed mailbox names in directory matching pattern. *directory*
+ defaults to the top level directory and *pattern* defaults to match any mailbox.
+ Returned data are tuples of message part envelope and data.
+
+
+.. method:: IMAP4.myrights(mailbox)
+
+ Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).
+
+ .. versionadded:: 2.4
+
+
+.. method:: IMAP4.namespace()
+
+ Returns IMAP namespaces as defined in RFC2342.
+
+ .. versionadded:: 2.3
+
+
+.. method:: IMAP4.noop()
+
+ Send ``NOOP`` to server.
+
+
+.. method:: IMAP4.open(host, port)
+
+ Opens socket to *port* at *host*. The connection objects established by this
+ method will be used in the ``read``, ``readline``, ``send``, and ``shutdown``
+ methods. You may override this method.
+
+
+.. method:: IMAP4.partial(message_num, message_part, start, length)
+
+ Fetch truncated part of a message. Returned data is a tuple of message part
+ envelope and data.
+
+
+.. method:: IMAP4.proxyauth(user)
+
+ Assume authentication as *user*. Allows an authorised administrator to proxy
+ into any user's mailbox.
+
+ .. versionadded:: 2.3
+
+
+.. method:: IMAP4.read(size)
+
+ Reads *size* bytes from the remote server. You may override this method.
+
+
+.. method:: IMAP4.readline()
+
+ Reads one line from the remote server. You may override this method.
+
+
+.. method:: IMAP4.recent()
+
+ Prompt server for an update. Returned data is ``None`` if no new messages, else
+ value of ``RECENT`` response.
+
+
+.. method:: IMAP4.rename(oldmailbox, newmailbox)
+
+ Rename mailbox named *oldmailbox* to *newmailbox*.
+
+
+.. method:: IMAP4.response(code)
+
+ Return data for response *code* if received, or ``None``. Returns the given
+ code, instead of the usual type.
+
+
+.. method:: IMAP4.search(charset, criterion[, ...])
+
+ Search mailbox for matching messages. *charset* may be ``None``, in which case
+ no ``CHARSET`` will be specified in the request to the server. The IMAP
+ protocol requires that at least one criterion be specified; an exception will be
+ raised when the server returns an error.
+
+ Example::
+
+ # M is a connected IMAP4 instance...
+ typ, msgnums = M.search(None, 'FROM', '"LDJ"')
+
+ # or:
+ typ, msgnums = M.search(None, '(FROM "LDJ")')
+
+
+.. method:: IMAP4.select([mailbox[, readonly]])
+
+ Select a mailbox. Returned data is the count of messages in *mailbox*
+ (``EXISTS`` response). The default *mailbox* is ``'INBOX'``. If the *readonly*
+ flag is set, modifications to the mailbox are not allowed.
+
+
+.. method:: IMAP4.send(data)
+
+ Sends ``data`` to the remote server. You may override this method.
+
+
+.. method:: IMAP4.setacl(mailbox, who, what)
+
+ Set an ``ACL`` for *mailbox*. The method is non-standard, but is supported by
+ the ``Cyrus`` server.
+
+
+.. method:: IMAP4.setannotation(mailbox, entry, attribute[, ...])
+
+ Set ``ANNOTATION``\ s for *mailbox*. The method is non-standard, but is
+ supported by the ``Cyrus`` server.
+
+ .. versionadded:: 2.5
+
+
+.. method:: IMAP4.setquota(root, limits)
+
+ Set the ``quota`` *root*'s resource *limits*. This method is part of the IMAP4
+ QUOTA extension defined in rfc2087.
+
+ .. versionadded:: 2.3
+
+
+.. method:: IMAP4.shutdown()
+
+ Close connection established in ``open``. You may override this method.
+
+
+.. method:: IMAP4.socket()
+
+ Returns socket instance used to connect to server.
+
+
+.. method:: IMAP4.sort(sort_criteria, charset, search_criterion[, ...])
+
+ The ``sort`` command is a variant of ``search`` with sorting semantics for the
+ results. Returned data contains a space separated list of matching message
+ numbers.
+
+ Sort has two arguments before the *search_criterion* argument(s); a
+ parenthesized list of *sort_criteria*, and the searching *charset*. Note that
+ unlike ``search``, the searching *charset* argument is mandatory. There is also
+ a ``uid sort`` command which corresponds to ``sort`` the way that ``uid search``
+ corresponds to ``search``. The ``sort`` command first searches the mailbox for
+ messages that match the given searching criteria using the charset argument for
+ the interpretation of strings in the searching criteria. It then returns the
+ numbers of matching messages.
+
+ This is an ``IMAP4rev1`` extension command.
+
+
+.. method:: IMAP4.status(mailbox, names)
+
+ Request named status conditions for *mailbox*.
+
+
+.. method:: IMAP4.store(message_set, command, flag_list)
+
+ Alters flag dispositions for messages in mailbox. *command* is specified by
+ section 6.4.6 of :rfc:`2060` as being one of "FLAGS", "+FLAGS", or "-FLAGS",
+ optionally with a suffix of ".SILENT".
+
+ For example, to set the delete flag on all messages::
+
+ typ, data = M.search(None, 'ALL')
+ for num in data[0].split():
+ M.store(num, '+FLAGS', '\\Deleted')
+ M.expunge()
+
+
+.. method:: IMAP4.subscribe(mailbox)
+
+ Subscribe to new mailbox.
+
+
+.. method:: IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])
+
+ The ``thread`` command is a variant of ``search`` with threading semantics for
+ the results. Returned data contains a space separated list of thread members.
+
+ Thread members consist of zero or more messages numbers, delimited by spaces,
+ indicating successive parent and child.
+
+ Thread has two arguments before the *search_criterion* argument(s); a
+ *threading_algorithm*, and the searching *charset*. Note that unlike
+ ``search``, the searching *charset* argument is mandatory. There is also a
+ ``uid thread`` command which corresponds to ``thread`` the way that ``uid
+ search`` corresponds to ``search``. The ``thread`` command first searches the
+ mailbox for messages that match the given searching criteria using the charset
+ argument for the interpretation of strings in the searching criteria. It then
+ returns the matching messages threaded according to the specified threading
+ algorithm.
+
+ This is an ``IMAP4rev1`` extension command.
+
+ .. versionadded:: 2.4
+
+
+.. method:: IMAP4.uid(command, arg[, ...])
+
+ Execute command args with messages identified by UID, rather than message
+ number. Returns response appropriate to command. At least one argument must be
+ supplied; if none are provided, the server will return an error and an exception
+ will be raised.
+
+
+.. method:: IMAP4.unsubscribe(mailbox)
+
+ Unsubscribe from old mailbox.
+
+
+.. method:: IMAP4.xatom(name[, arg[, ...]])
+
+ Allow simple extension commands notified by server in ``CAPABILITY`` response.
+
+Instances of :class:`IMAP4_SSL` have just one additional method:
+
+
+.. method:: IMAP4_SSL.ssl()
+
+ Returns SSLObject instance used for the secure connection with the server.
+
+The following attributes are defined on instances of :class:`IMAP4`:
+
+
+.. attribute:: IMAP4.PROTOCOL_VERSION
+
+ The most recent supported protocol in the ``CAPABILITY`` response from the
+ server.
+
+
+.. attribute:: IMAP4.debug
+
+ Integer value to control debugging output. The initialize value is taken from
+ the module variable ``Debug``. Values greater than three trace each command.
+
+
+.. _imap4-example:
+
+IMAP4 Example
+-------------
+
+Here is a minimal example (without error checking) that opens a mailbox and
+retrieves and prints all messages::
+
+ import getpass, imaplib
+
+ M = imaplib.IMAP4()
+ M.login(getpass.getuser(), getpass.getpass())
+ M.select()
+ typ, data = M.search(None, 'ALL')
+ for num in data[0].split():
+ typ, data = M.fetch(num, '(RFC822)')
+ print 'Message %s\n%s\n' % (num, data[0][1])
+ M.close()
+ M.logout()
+
--- /dev/null
+
+:mod:`imgfile` --- Support for SGI imglib files
+===============================================
+
+.. module:: imgfile
+ :platform: IRIX
+ :synopsis: Support for SGI imglib files.
+
+
+The :mod:`imgfile` module allows Python programs to access SGI imglib image
+files (also known as :file:`.rgb` files). The module is far from complete, but
+is provided anyway since the functionality that there is enough in some cases.
+Currently, colormap files are not supported.
+
+The module defines the following variables and functions:
+
+
+.. exception:: error
+
+ This exception is raised on all errors, such as unsupported file type, etc.
+
+
+.. function:: getsizes(file)
+
+ This function returns a tuple ``(x, y, z)`` where *x* and *y* are the size of
+ the image in pixels and *z* is the number of bytes per pixel. Only 3 byte RGB
+ pixels and 1 byte greyscale pixels are currently supported.
+
+
+.. function:: read(file)
+
+ This function reads and decodes the image on the specified file, and returns it
+ as a Python string. The string has either 1 byte greyscale pixels or 4 byte RGBA
+ pixels. The bottom left pixel is the first in the string. This format is
+ suitable to pass to :func:`gl.lrectwrite`, for instance.
+
+
+.. function:: readscaled(file, x, y, filter[, blur])
+
+ This function is identical to read but it returns an image that is scaled to the
+ given *x* and *y* sizes. If the *filter* and *blur* parameters are omitted
+ scaling is done by simply dropping or duplicating pixels, so the result will be
+ less than perfect, especially for computer-generated images.
+
+ Alternatively, you can specify a filter to use to smooth the image after
+ scaling. The filter forms supported are ``'impulse'``, ``'box'``,
+ ``'triangle'``, ``'quadratic'`` and ``'gaussian'``. If a filter is specified
+ *blur* is an optional parameter specifying the blurriness of the filter. It
+ defaults to ``1.0``.
+
+ :func:`readscaled` makes no attempt to keep the aspect ratio correct, so that is
+ the users' responsibility.
+
+
+.. function:: ttob(flag)
+
+ This function sets a global flag which defines whether the scan lines of the
+ image are read or written from bottom to top (flag is zero, compatible with SGI
+ GL) or from top to bottom(flag is one, compatible with X). The default is zero.
+
+
+.. function:: write(file, data, x, y, z)
+
+ This function writes the RGB or greyscale data in *data* to image file *file*.
+ *x* and *y* give the size of the image, *z* is 1 for 1 byte greyscale images or
+ 3 for RGB images (which are stored as 4 byte values of which only the lower
+ three bytes are used). These are the formats returned by :func:`gl.lrectread`.
+
--- /dev/null
+
+:mod:`imghdr` --- Determine the type of an image
+================================================
+
+.. module:: imghdr
+ :synopsis: Determine the type of image contained in a file or byte stream.
+
+
+The :mod:`imghdr` module determines the type of image contained in a file or
+byte stream.
+
+The :mod:`imghdr` module defines the following function:
+
+
+.. function:: what(filename[, h])
+
+ Tests the image data contained in the file named by *filename*, and returns a
+ string describing the image type. If optional *h* is provided, the *filename*
+ is ignored and *h* is assumed to contain the byte stream to test.
+
+The following image types are recognized, as listed below with the return value
+from :func:`what`:
+
++------------+-----------------------------------+
+| Value | Image format |
++============+===================================+
+| ``'rgb'`` | SGI ImgLib Files |
++------------+-----------------------------------+
+| ``'gif'`` | GIF 87a and 89a Files |
++------------+-----------------------------------+
+| ``'pbm'`` | Portable Bitmap Files |
++------------+-----------------------------------+
+| ``'pgm'`` | Portable Graymap Files |
++------------+-----------------------------------+
+| ``'ppm'`` | Portable Pixmap Files |
++------------+-----------------------------------+
+| ``'tiff'`` | TIFF Files |
++------------+-----------------------------------+
+| ``'rast'`` | Sun Raster Files |
++------------+-----------------------------------+
+| ``'xbm'`` | X Bitmap Files |
++------------+-----------------------------------+
+| ``'jpeg'`` | JPEG data in JFIF or Exif formats |
++------------+-----------------------------------+
+| ``'bmp'`` | BMP files |
++------------+-----------------------------------+
+| ``'png'`` | Portable Network Graphics |
++------------+-----------------------------------+
+
+.. versionadded:: 2.5
+ Exif detection.
+
+You can extend the list of file types :mod:`imghdr` can recognize by appending
+to this variable:
+
+
+.. data:: tests
+
+ A list of functions performing the individual tests. Each function takes two
+ arguments: the byte-stream and an open file-like object. When :func:`what` is
+ called with a byte-stream, the file-like object will be ``None``.
+
+ The test function should return a string describing the image type if the test
+ succeeded, or ``None`` if it failed.
+
+Example::
+
+ >>> import imghdr
+ >>> imghdr.what('/tmp/bass.gif')
+ 'gif'
+
--- /dev/null
+
+:mod:`imp` --- Access the :keyword:`import` internals
+=====================================================
+
+.. module:: imp
+ :synopsis: Access the implementation of the import statement.
+
+
+.. index:: statement: import
+
+This module provides an interface to the mechanisms used to implement the
+:keyword:`import` statement. It defines the following constants and functions:
+
+
+.. function:: get_magic()
+
+ .. index:: pair: file; byte-code
+
+ Return the magic string value used to recognize byte-compiled code files
+ (:file:`.pyc` files). (This value may be different for each Python version.)
+
+
+.. function:: get_suffixes()
+
+ Return a list of triples, each describing a particular type of module. Each
+ triple has the form ``(suffix, mode, type)``, where *suffix* is a string to be
+ appended to the module name to form the filename to search for, *mode* is the
+ mode string to pass to the built-in :func:`open` function to open the file (this
+ can be ``'r'`` for text files or ``'rb'`` for binary files), and *type* is the
+ file type, which has one of the values :const:`PY_SOURCE`, :const:`PY_COMPILED`,
+ or :const:`C_EXTENSION`, described below.
+
+
+.. function:: find_module(name[, path])
+
+ Try to find the module *name* on the search path *path*. If *path* is a list of
+ directory names, each directory is searched for files with any of the suffixes
+ returned by :func:`get_suffixes` above. Invalid names in the list are silently
+ ignored (but all list items must be strings). If *path* is omitted or ``None``,
+ the list of directory names given by ``sys.path`` is searched, but first it
+ searches a few special places: it tries to find a built-in module with the given
+ name (:const:`C_BUILTIN`), then a frozen module (:const:`PY_FROZEN`), and on
+ some systems some other places are looked in as well (on the Mac, it looks for a
+ resource (:const:`PY_RESOURCE`); on Windows, it looks in the registry which may
+ point to a specific file).
+
+ If search is successful, the return value is a triple ``(file, pathname,
+ description)`` where *file* is an open file object positioned at the beginning,
+ *pathname* is the pathname of the file found, and *description* is a triple as
+ contained in the list returned by :func:`get_suffixes` describing the kind of
+ module found. If the module does not live in a file, the returned *file* is
+ ``None``, *filename* is the empty string, and the *description* tuple contains
+ empty strings for its suffix and mode; the module type is as indicate in
+ parentheses above. If the search is unsuccessful, :exc:`ImportError` is raised.
+ Other exceptions indicate problems with the arguments or environment.
+
+ This function does not handle hierarchical module names (names containing dots).
+ In order to find *P*.*M*, that is, submodule *M* of package *P*, use
+ :func:`find_module` and :func:`load_module` to find and load package *P*, and
+ then use :func:`find_module` with the *path* argument set to ``P.__path__``.
+ When *P* itself has a dotted name, apply this recipe recursively.
+
+
+.. function:: load_module(name, file, filename, description)
+
+ .. index:: builtin: reload
+
+ Load a module that was previously found by :func:`find_module` (or by an
+ otherwise conducted search yielding compatible results). This function does
+ more than importing the module: if the module was already imported, it is
+ equivalent to a :func:`reload`! The *name* argument indicates the full module
+ name (including the package name, if this is a submodule of a package). The
+ *file* argument is an open file, and *filename* is the corresponding file name;
+ these can be ``None`` and ``''``, respectively, when the module is not being
+ loaded from a file. The *description* argument is a tuple, as would be returned
+ by :func:`get_suffixes`, describing what kind of module must be loaded.
+
+ If the load is successful, the return value is the module object; otherwise, an
+ exception (usually :exc:`ImportError`) is raised.
+
+ **Important:** the caller is responsible for closing the *file* argument, if it
+ was not ``None``, even when an exception is raised. This is best done using a
+ :keyword:`try` ... :keyword:`finally` statement.
+
+
+.. function:: new_module(name)
+
+ Return a new empty module object called *name*. This object is *not* inserted
+ in ``sys.modules``.
+
+
+.. function:: lock_held()
+
+ Return ``True`` if the import lock is currently held, else ``False``. On
+ platforms without threads, always return ``False``.
+
+ On platforms with threads, a thread executing an import holds an internal lock
+ until the import is complete. This lock blocks other threads from doing an
+ import until the original import completes, which in turn prevents other threads
+ from seeing incomplete module objects constructed by the original thread while
+ in the process of completing its import (and the imports, if any, triggered by
+ that).
+
+
+.. function:: acquire_lock()
+
+ Acquires the interpreter's import lock for the current thread. This lock should
+ be used by import hooks to ensure thread-safety when importing modules. On
+ platforms without threads, this function does nothing.
+
+ .. versionadded:: 2.3
+
+
+.. function:: release_lock()
+
+ Release the interpreter's import lock. On platforms without threads, this
+ function does nothing.
+
+ .. versionadded:: 2.3
+
+The following constants with integer values, defined in this module, are used to
+indicate the search result of :func:`find_module`.
+
+
+.. data:: PY_SOURCE
+
+ The module was found as a source file.
+
+
+.. data:: PY_COMPILED
+
+ The module was found as a compiled code object file.
+
+
+.. data:: C_EXTENSION
+
+ The module was found as dynamically loadable shared library.
+
+
+.. data:: PY_RESOURCE
+
+ The module was found as a Mac OS 9 resource. This value can only be returned on
+ a Mac OS 9 or earlier Macintosh.
+
+
+.. data:: PKG_DIRECTORY
+
+ The module was found as a package directory.
+
+
+.. data:: C_BUILTIN
+
+ The module was found as a built-in module.
+
+
+.. data:: PY_FROZEN
+
+ The module was found as a frozen module (see :func:`init_frozen`).
+
+The following constant and functions are obsolete; their functionality is
+available through :func:`find_module` or :func:`load_module`. They are kept
+around for backward compatibility:
+
+
+.. data:: SEARCH_ERROR
+
+ Unused.
+
+
+.. function:: init_builtin(name)
+
+ Initialize the built-in module called *name* and return its module object along
+ with storing it in ``sys.modules``. If the module was already initialized, it
+ will be initialized *again*. Re-initialization involves the copying of the
+ built-in module's ``__dict__`` from the cached module over the module's entry in
+ ``sys.modules``. If there is no built-in module called *name*, ``None`` is
+ returned.
+
+
+.. function:: init_frozen(name)
+
+ Initialize the frozen module called *name* and return its module object. If
+ the module was already initialized, it will be initialized *again*. If there
+ is no frozen module called *name*, ``None`` is returned. (Frozen modules are
+ modules written in Python whose compiled byte-code object is incorporated
+ into a custom-built Python interpreter by Python's :program:`freeze`
+ utility. See :file:`Tools/freeze/` for now.)
+
+
+.. function:: is_builtin(name)
+
+ Return ``1`` if there is a built-in module called *name* which can be
+ initialized again. Return ``-1`` if there is a built-in module called *name*
+ which cannot be initialized again (see :func:`init_builtin`). Return ``0`` if
+ there is no built-in module called *name*.
+
+
+.. function:: is_frozen(name)
+
+ Return ``True`` if there is a frozen module (see :func:`init_frozen`) called
+ *name*, or ``False`` if there is no such module.
+
+
+.. function:: load_compiled(name, pathname, [file])
+
+ .. index:: pair: file; byte-code
+
+ Load and initialize a module implemented as a byte-compiled code file and return
+ its module object. If the module was already initialized, it will be
+ initialized *again*. The *name* argument is used to create or access a module
+ object. The *pathname* argument points to the byte-compiled code file. The
+ *file* argument is the byte-compiled code file, open for reading in binary mode,
+ from the beginning. It must currently be a real file object, not a user-defined
+ class emulating a file.
+
+
+.. function:: load_dynamic(name, pathname[, file])
+
+ Load and initialize a module implemented as a dynamically loadable shared
+ library and return its module object. If the module was already initialized, it
+ will be initialized *again*. Re-initialization involves copying the ``__dict__``
+ attribute of the cached instance of the module over the value used in the module
+ cached in ``sys.modules``. The *pathname* argument must point to the shared
+ library. The *name* argument is used to construct the name of the
+ initialization function: an external C function called ``initname()`` in the
+ shared library is called. The optional *file* argument is ignored. (Note:
+ using shared libraries is highly system dependent, and not all systems support
+ it.)
+
+
+.. function:: load_source(name, pathname[, file])
+
+ Load and initialize a module implemented as a Python source file and return its
+ module object. If the module was already initialized, it will be initialized
+ *again*. The *name* argument is used to create or access a module object. The
+ *pathname* argument points to the source file. The *file* argument is the
+ source file, open for reading as text, from the beginning. It must currently be
+ a real file object, not a user-defined class emulating a file. Note that if a
+ properly matching byte-compiled file (with suffix :file:`.pyc` or :file:`.pyo`)
+ exists, it will be used instead of parsing the given source file.
+
+
+.. class:: NullImporter(path_string)
+
+ The :class:`NullImporter` type is a :pep:`302` import hook that handles
+ non-directory path strings by failing to find any modules. Calling this type
+ with an existing directory or empty string raises :exc:`ImportError`.
+ Otherwise, a :class:`NullImporter` instance is returned.
+
+ Python adds instances of this type to ``sys.path_importer_cache`` for any path
+ entries that are not directories and are not handled by any other path hooks on
+ ``sys.path_hooks``. Instances have only one method:
+
+
+ .. method:: NullImporter.find_module(fullname [, path])
+
+ This method always returns ``None``, indicating that the requested module could
+ not be found.
+
+ .. versionadded:: 2.5
+
+
+.. _examples-imp:
+
+Examples
+--------
+
+The following function emulates what was the standard import statement up to
+Python 1.4 (no hierarchical module names). (This *implementation* wouldn't work
+in that version, since :func:`find_module` has been extended and
+:func:`load_module` has been added in 1.4.) ::
+
+ import imp
+ import sys
+
+ def __import__(name, globals=None, locals=None, fromlist=None):
+ # Fast path: see if the module has already been imported.
+ try:
+ return sys.modules[name]
+ except KeyError:
+ pass
+
+ # If any of the following calls raises an exception,
+ # there's a problem we can't handle -- let the caller handle it.
+
+ fp, pathname, description = imp.find_module(name)
+
+ try:
+ return imp.load_module(name, fp, pathname, description)
+ finally:
+ # Since we may exit via an exception, close fp explicitly.
+ if fp:
+ fp.close()
+
+.. index::
+ builtin: reload
+ module: knee
+
+A more complete example that implements hierarchical module names and includes a
+:func:`reload` function can be found in the module :mod:`knee`. The :mod:`knee`
+module can be found in :file:`Demo/imputil/` in the Python source distribution.
+
--- /dev/null
+.. _library-index:
+
+###############################
+ The Python Standard Library
+###############################
+
+:Release: |version|
+:Date: |today|
+
+While the :ref:`reference-index` describes the exact syntax and
+semantics of the Python language, this library reference manual
+describes the standard library that is distributed with Python. It also
+describes some of the optional components that are commonly included
+in Python distributions.
+
+Python's standard library is very extensive, offering a wide range of
+facilities as indicated by the long table of contents listed below. The
+library contains built-in modules (written in C) that provide access to
+system functionality such as file I/O that would otherwise be
+inaccessible to Python programmers, as well as modules written in Python
+that provide standardized solutions for many problems that occur in
+everyday programming. Some of these modules are explicitly designed to
+encourage and enhance the portability of Python programs by abstracting
+away platform-specifics into platform-neutral APIs.
+
+The Python installers for the Windows and Mac platforms usually include
+the entire standard library and often also include many additional
+components. For Unix-like operating systems Python is normally provided
+as a collection of packages, so it may be necessary to use the packaging
+tools provided with the operating system to obtain some or all of the
+optional components.
+
+In addition to the standard library, there is a growing collection of
+over 2500 additional components available from the `Python Package Index
+<http://pypi.python.org/pypi>`_.
+
+
+.. toctree::
+ :maxdepth: 2
+
+ intro.rst
+ functions.rst
+ constants.rst
+ objects.rst
+ stdtypes.rst
+ exceptions.rst
+
+ strings.rst
+ datatypes.rst
+ numeric.rst
+ filesys.rst
+ persistence.rst
+ archiving.rst
+ fileformats.rst
+ crypto.rst
+ allos.rst
+ someos.rst
+ ipc.rst
+ netdata.rst
+ markup.rst
+ internet.rst
+ mm.rst
+ i18n.rst
+ frameworks.rst
+ tk.rst
+ development.rst
+ pdb.rst
+ profile.rst
+ hotshot.rst
+ timeit.rst
+ trace.rst
+ python.rst
+ custominterp.rst
+ restricted.rst
+ modules.rst
+ language.rst
+ compiler.rst
+ misc.rst
+ windows.rst
+ unix.rst
+ mac.rst
+ macosa.rst
+ sgi.rst
+ sun.rst
+ undoc.rst
--- /dev/null
+
+:mod:`inspect` --- Inspect live objects
+=======================================
+
+.. module:: inspect
+ :synopsis: Extract information and source code from live objects.
+.. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
+.. sectionauthor:: Ka-Ping Yee <ping@lfw.org>
+
+
+.. versionadded:: 2.1
+
+The :mod:`inspect` module provides several useful functions to help get
+information about live objects such as modules, classes, methods, functions,
+tracebacks, frame objects, and code objects. For example, it can help you
+examine the contents of a class, retrieve the source code of a method, extract
+and format the argument list for a function, or get all the information you need
+to display a detailed traceback.
+
+There are four main kinds of services provided by this module: type checking,
+getting source code, inspecting classes and functions, and examining the
+interpreter stack.
+
+
+.. _inspect-types:
+
+Types and members
+-----------------
+
+The :func:`getmembers` function retrieves the members of an object such as a
+class or module. The eleven functions whose names begin with "is" are mainly
+provided as convenient choices for the second argument to :func:`getmembers`.
+They also help you determine when you can expect to find the following special
+attributes:
+
++-----------+-----------------+---------------------------+-------+
+| Type | Attribute | Description | Notes |
++===========+=================+===========================+=======+
+| module | __doc__ | documentation string | |
++-----------+-----------------+---------------------------+-------+
+| | __file__ | filename (missing for | |
+| | | built-in modules) | |
++-----------+-----------------+---------------------------+-------+
+| class | __doc__ | documentation string | |
++-----------+-----------------+---------------------------+-------+
+| | __module__ | name of module in which | |
+| | | this class was defined | |
++-----------+-----------------+---------------------------+-------+
+| method | __doc__ | documentation string | |
++-----------+-----------------+---------------------------+-------+
+| | __name__ | name with which this | |
+| | | method was defined | |
++-----------+-----------------+---------------------------+-------+
+| | im_class | class object that asked | \(1) |
+| | | for this method | |
++-----------+-----------------+---------------------------+-------+
+| | im_func | function object | |
+| | | containing implementation | |
+| | | of method | |
++-----------+-----------------+---------------------------+-------+
+| | im_self | instance to which this | |
+| | | method is bound, or | |
+| | | ``None`` | |
++-----------+-----------------+---------------------------+-------+
+| function | __doc__ | documentation string | |
++-----------+-----------------+---------------------------+-------+
+| | __name__ | name with which this | |
+| | | function was defined | |
++-----------+-----------------+---------------------------+-------+
+| | func_code | code object containing | |
+| | | compiled function | |
+| | | bytecode | |
++-----------+-----------------+---------------------------+-------+
+| | func_defaults | tuple of any default | |
+| | | values for arguments | |
++-----------+-----------------+---------------------------+-------+
+| | func_doc | (same as __doc__) | |
++-----------+-----------------+---------------------------+-------+
+| | func_globals | global namespace in which | |
+| | | this function was defined | |
++-----------+-----------------+---------------------------+-------+
+| | func_name | (same as __name__) | |
++-----------+-----------------+---------------------------+-------+
+| traceback | tb_frame | frame object at this | |
+| | | level | |
++-----------+-----------------+---------------------------+-------+
+| | tb_lasti | index of last attempted | |
+| | | instruction in bytecode | |
++-----------+-----------------+---------------------------+-------+
+| | tb_lineno | current line number in | |
+| | | Python source code | |
++-----------+-----------------+---------------------------+-------+
+| | tb_next | next inner traceback | |
+| | | object (called by this | |
+| | | level) | |
++-----------+-----------------+---------------------------+-------+
+| frame | f_back | next outer frame object | |
+| | | (this frame's caller) | |
++-----------+-----------------+---------------------------+-------+
+| | f_builtins | built-in namespace seen | |
+| | | by this frame | |
++-----------+-----------------+---------------------------+-------+
+| | f_code | code object being | |
+| | | executed in this frame | |
++-----------+-----------------+---------------------------+-------+
+| | f_exc_traceback | traceback if raised in | |
+| | | this frame, or ``None`` | |
++-----------+-----------------+---------------------------+-------+
+| | f_exc_type | exception type if raised | |
+| | | in this frame, or | |
+| | | ``None`` | |
++-----------+-----------------+---------------------------+-------+
+| | f_exc_value | exception value if raised | |
+| | | in this frame, or | |
+| | | ``None`` | |
++-----------+-----------------+---------------------------+-------+
+| | f_globals | global namespace seen by | |
+| | | this frame | |
++-----------+-----------------+---------------------------+-------+
+| | f_lasti | index of last attempted | |
+| | | instruction in bytecode | |
++-----------+-----------------+---------------------------+-------+
+| | f_lineno | current line number in | |
+| | | Python source code | |
++-----------+-----------------+---------------------------+-------+
+| | f_locals | local namespace seen by | |
+| | | this frame | |
++-----------+-----------------+---------------------------+-------+
+| | f_restricted | 0 or 1 if frame is in | |
+| | | restricted execution mode | |
++-----------+-----------------+---------------------------+-------+
+| | f_trace | tracing function for this | |
+| | | frame, or ``None`` | |
++-----------+-----------------+---------------------------+-------+
+| code | co_argcount | number of arguments (not | |
+| | | including \* or \*\* | |
+| | | args) | |
++-----------+-----------------+---------------------------+-------+
+| | co_code | string of raw compiled | |
+| | | bytecode | |
++-----------+-----------------+---------------------------+-------+
+| | co_consts | tuple of constants used | |
+| | | in the bytecode | |
++-----------+-----------------+---------------------------+-------+
+| | co_filename | name of file in which | |
+| | | this code object was | |
+| | | created | |
++-----------+-----------------+---------------------------+-------+
+| | co_firstlineno | number of first line in | |
+| | | Python source code | |
++-----------+-----------------+---------------------------+-------+
+| | co_flags | bitmap: 1=optimized ``|`` | |
+| | | 2=newlocals ``|`` 4=\*arg | |
+| | | ``|`` 8=\*\*arg | |
++-----------+-----------------+---------------------------+-------+
+| | co_lnotab | encoded mapping of line | |
+| | | numbers to bytecode | |
+| | | indices | |
++-----------+-----------------+---------------------------+-------+
+| | co_name | name with which this code | |
+| | | object was defined | |
++-----------+-----------------+---------------------------+-------+
+| | co_names | tuple of names of local | |
+| | | variables | |
++-----------+-----------------+---------------------------+-------+
+| | co_nlocals | number of local variables | |
++-----------+-----------------+---------------------------+-------+
+| | co_stacksize | virtual machine stack | |
+| | | space required | |
++-----------+-----------------+---------------------------+-------+
+| | co_varnames | tuple of names of | |
+| | | arguments and local | |
+| | | variables | |
++-----------+-----------------+---------------------------+-------+
+| builtin | __doc__ | documentation string | |
++-----------+-----------------+---------------------------+-------+
+| | __name__ | original name of this | |
+| | | function or method | |
++-----------+-----------------+---------------------------+-------+
+| | __self__ | instance to which a | |
+| | | method is bound, or | |
+| | | ``None`` | |
++-----------+-----------------+---------------------------+-------+
+
+Note:
+
+(1)
+ .. versionchanged:: 2.2
+ :attr:`im_class` used to refer to the class that defined the method.
+
+
+.. function:: getmembers(object[, predicate])
+
+ Return all the members of an object in a list of (name, value) pairs sorted by
+ name. If the optional *predicate* argument is supplied, only members for which
+ the predicate returns a true value are included.
+
+
+.. function:: getmoduleinfo(path)
+
+ Return a tuple of values that describe how Python will interpret the file
+ identified by *path* if it is a module, or ``None`` if it would not be
+ identified as a module. The return tuple is ``(name, suffix, mode, mtype)``,
+ where *name* is the name of the module without the name of any enclosing
+ package, *suffix* is the trailing part of the file name (which may not be a
+ dot-delimited extension), *mode* is the :func:`open` mode that would be used
+ (``'r'`` or ``'rb'``), and *mtype* is an integer giving the type of the
+ module. *mtype* will have a value which can be compared to the constants
+ defined in the :mod:`imp` module; see the documentation for that module for
+ more information on module types.
+
+
+.. function:: getmodulename(path)
+
+ Return the name of the module named by the file *path*, without including the
+ names of enclosing packages. This uses the same algorithm as the interpreter
+ uses when searching for modules. If the name cannot be matched according to the
+ interpreter's rules, ``None`` is returned.
+
+
+.. function:: ismodule(object)
+
+ Return true if the object is a module.
+
+
+.. function:: isclass(object)
+
+ Return true if the object is a class.
+
+
+.. function:: ismethod(object)
+
+ Return true if the object is a method.
+
+
+.. function:: isfunction(object)
+
+ Return true if the object is a Python function or unnamed (lambda) function.
+
+
+.. function:: istraceback(object)
+
+ Return true if the object is a traceback.
+
+
+.. function:: isframe(object)
+
+ Return true if the object is a frame.
+
+
+.. function:: iscode(object)
+
+ Return true if the object is a code.
+
+
+.. function:: isbuiltin(object)
+
+ Return true if the object is a built-in function.
+
+
+.. function:: isroutine(object)
+
+ Return true if the object is a user-defined or built-in function or method.
+
+
+.. function:: ismethoddescriptor(object)
+
+ Return true if the object is a method descriptor, but not if ismethod() or
+ isclass() or isfunction() are true.
+
+ This is new as of Python 2.2, and, for example, is true of int.__add__. An
+ object passing this test has a __get__ attribute but not a __set__ attribute,
+ but beyond that the set of attributes varies. __name__ is usually sensible, and
+ __doc__ often is.
+
+ Methods implemented via descriptors that also pass one of the other tests return
+ false from the ismethoddescriptor() test, simply because the other tests promise
+ more -- you can, e.g., count on having the im_func attribute (etc) when an
+ object passes ismethod().
+
+
+.. function:: isdatadescriptor(object)
+
+ Return true if the object is a data descriptor.
+
+ Data descriptors have both a __get__ and a __set__ attribute. Examples are
+ properties (defined in Python), getsets, and members. The latter two are
+ defined in C and there are more specific tests available for those types, which
+ is robust across Python implementations. Typically, data descriptors will also
+ have __name__ and __doc__ attributes (properties, getsets, and members have both
+ of these attributes), but this is not guaranteed.
+
+ .. versionadded:: 2.3
+
+
+.. function:: isgetsetdescriptor(object)
+
+ Return true if the object is a getset descriptor.
+
+ getsets are attributes defined in extension modules via ``PyGetSetDef``
+ structures. For Python implementations without such types, this method will
+ always return ``False``.
+
+ .. versionadded:: 2.5
+
+
+.. function:: ismemberdescriptor(object)
+
+ Return true if the object is a member descriptor.
+
+ Member descriptors are attributes defined in extension modules via
+ ``PyMemberDef`` structures. For Python implementations without such types, this
+ method will always return ``False``.
+
+ .. versionadded:: 2.5
+
+
+.. _inspect-source:
+
+Retrieving source code
+----------------------
+
+
+.. function:: getdoc(object)
+
+ Get the documentation string for an object. All tabs are expanded to spaces. To
+ clean up docstrings that are indented to line up with blocks of code, any
+ whitespace than can be uniformly removed from the second line onwards is
+ removed.
+
+
+.. function:: getcomments(object)
+
+ Return in a single string any lines of comments immediately preceding the
+ object's source code (for a class, function, or method), or at the top of the
+ Python source file (if the object is a module).
+
+
+.. function:: getfile(object)
+
+ Return the name of the (text or binary) file in which an object was defined.
+ This will fail with a :exc:`TypeError` if the object is a built-in module,
+ class, or function.
+
+
+.. function:: getmodule(object)
+
+ Try to guess which module an object was defined in.
+
+
+.. function:: getsourcefile(object)
+
+ Return the name of the Python source file in which an object was defined. This
+ will fail with a :exc:`TypeError` if the object is a built-in module, class, or
+ function.
+
+
+.. function:: getsourcelines(object)
+
+ Return a list of source lines and starting line number for an object. The
+ argument may be a module, class, method, function, traceback, frame, or code
+ object. The source code is returned as a list of the lines corresponding to the
+ object and the line number indicates where in the original source file the first
+ line of code was found. An :exc:`IOError` is raised if the source code cannot
+ be retrieved.
+
+
+.. function:: getsource(object)
+
+ Return the text of the source code for an object. The argument may be a module,
+ class, method, function, traceback, frame, or code object. The source code is
+ returned as a single string. An :exc:`IOError` is raised if the source code
+ cannot be retrieved.
+
+
+.. _inspect-classes-functions:
+
+Classes and functions
+---------------------
+
+
+.. function:: getclasstree(classes[, unique])
+
+ Arrange the given list of classes into a hierarchy of nested lists. Where a
+ nested list appears, it contains classes derived from the class whose entry
+ immediately precedes the list. Each entry is a 2-tuple containing a class and a
+ tuple of its base classes. If the *unique* argument is true, exactly one entry
+ appears in the returned structure for each class in the given list. Otherwise,
+ classes using multiple inheritance and their descendants will appear multiple
+ times.
+
+
+.. function:: getargspec(func)
+
+ Get the names and default values of a function's arguments. A tuple of four
+ things is returned: ``(args, varargs, varkw, defaults)``. *args* is a list of
+ the argument names (it may contain nested lists). *varargs* and *varkw* are the
+ names of the ``*`` and ``**`` arguments or ``None``. *defaults* is a tuple of
+ default argument values or None if there are no default arguments; if this tuple
+ has *n* elements, they correspond to the last *n* elements listed in *args*.
+
+
+.. function:: getargvalues(frame)
+
+ Get information about arguments passed into a particular frame. A tuple of four
+ things is returned: ``(args, varargs, varkw, locals)``. *args* is a list of the
+ argument names (it may contain nested lists). *varargs* and *varkw* are the
+ names of the ``*`` and ``**`` arguments or ``None``. *locals* is the locals
+ dictionary of the given frame.
+
+
+.. function:: formatargspec(args[, varargs, varkw, defaults, formatarg, formatvarargs, formatvarkw, formatvalue, join])
+
+ Format a pretty argument spec from the four values returned by
+ :func:`getargspec`. The format\* arguments are the corresponding optional
+ formatting functions that are called to turn names and values into strings.
+
+
+.. function:: formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue, join])
+
+ Format a pretty argument spec from the four values returned by
+ :func:`getargvalues`. The format\* arguments are the corresponding optional
+ formatting functions that are called to turn names and values into strings.
+
+
+.. function:: getmro(cls)
+
+ Return a tuple of class cls's base classes, including cls, in method resolution
+ order. No class appears more than once in this tuple. Note that the method
+ resolution order depends on cls's type. Unless a very peculiar user-defined
+ metatype is in use, cls will be the first element of the tuple.
+
+
+.. _inspect-stack:
+
+The interpreter stack
+---------------------
+
+When the following functions return "frame records," each record is a tuple of
+six items: the frame object, the filename, the line number of the current line,
+the function name, a list of lines of context from the source code, and the
+index of the current line within that list.
+
+.. warning::
+
+ Keeping references to frame objects, as found in the first element of the frame
+ records these functions return, can cause your program to create reference
+ cycles. Once a reference cycle has been created, the lifespan of all objects
+ which can be accessed from the objects which form the cycle can become much
+ longer even if Python's optional cycle detector is enabled. If such cycles must
+ be created, it is important to ensure they are explicitly broken to avoid the
+ delayed destruction of objects and increased memory consumption which occurs.
+
+ Though the cycle detector will catch these, destruction of the frames (and local
+ variables) can be made deterministic by removing the cycle in a
+ :keyword:`finally` clause. This is also important if the cycle detector was
+ disabled when Python was compiled or using :func:`gc.disable`. For example::
+
+ def handle_stackframe_without_leak():
+ frame = inspect.currentframe()
+ try:
+ # do something with the frame
+ finally:
+ del frame
+
+The optional *context* argument supported by most of these functions specifies
+the number of lines of context to return, which are centered around the current
+line.
+
+
+.. function:: getframeinfo(frame[, context])
+
+ Get information about a frame or traceback object. A 5-tuple is returned, the
+ last five elements of the frame's frame record.
+
+
+.. function:: getouterframes(frame[, context])
+
+ Get a list of frame records for a frame and all outer frames. These frames
+ represent the calls that lead to the creation of *frame*. The first entry in the
+ returned list represents *frame*; the last entry represents the outermost call
+ on *frame*'s stack.
+
+
+.. function:: getinnerframes(traceback[, context])
+
+ Get a list of frame records for a traceback's frame and all inner frames. These
+ frames represent calls made as a consequence of *frame*. The first entry in the
+ list represents *traceback*; the last entry represents where the exception was
+ raised.
+
+
+.. function:: currentframe()
+
+ Return the frame object for the caller's stack frame.
+
+
+.. function:: stack([context])
+
+ Return a list of frame records for the caller's stack. The first entry in the
+ returned list represents the caller; the last entry represents the outermost
+ call on the stack.
+
+
+.. function:: trace([context])
+
+ Return a list of frame records for the stack between the current frame and the
+ frame in which an exception currently being handled was raised in. The first
+ entry in the list represents the caller; the last entry represents where the
+ exception was raised.
+
--- /dev/null
+
+.. _internet:
+
+******************************
+Internet Protocols and Support
+******************************
+
+.. index::
+ single: WWW
+ single: Internet
+ single: World Wide Web
+
+.. index:: module: socket
+
+The modules described in this chapter implement Internet protocols and support
+for related technology. They are all implemented in Python. Most of these
+modules require the presence of the system-dependent module :mod:`socket`, which
+is currently supported on most popular platforms. Here is an overview:
+
+
+.. toctree::
+
+ webbrowser.rst
+ cgi.rst
+ cgitb.rst
+ wsgiref.rst
+ urllib.rst
+ urllib2.rst
+ httplib.rst
+ ftplib.rst
+ poplib.rst
+ imaplib.rst
+ nntplib.rst
+ smtplib.rst
+ smtpd.rst
+ telnetlib.rst
+ uuid.rst
+ urlparse.rst
+ socketserver.rst
+ basehttpserver.rst
+ simplehttpserver.rst
+ cgihttpserver.rst
+ cookielib.rst
+ cookie.rst
+ xmlrpclib.rst
+ simplexmlrpcserver.rst
+ docxmlrpcserver.rst
--- /dev/null
+
+.. _library-intro:
+
+************
+Introduction
+************
+
+The "Python library" contains several different kinds of components.
+
+It contains data types that would normally be considered part of the "core" of a
+language, such as numbers and lists. For these types, the Python language core
+defines the form of literals and places some constraints on their semantics, but
+does not fully define the semantics. (On the other hand, the language core does
+define syntactic properties like the spelling and priorities of operators.)
+
+The library also contains built-in functions and exceptions --- objects that can
+be used by all Python code without the need of an :keyword:`import` statement.
+Some of these are defined by the core language, but many are not essential for
+the core semantics and are only described here.
+
+The bulk of the library, however, consists of a collection of modules. There are
+many ways to dissect this collection. Some modules are written in C and built
+in to the Python interpreter; others are written in Python and imported in
+source form. Some modules provide interfaces that are highly specific to
+Python, like printing a stack trace; some provide interfaces that are specific
+to particular operating systems, such as access to specific hardware; others
+provide interfaces that are specific to a particular application domain, like
+the World Wide Web. Some modules are available in all versions and ports of
+Python; others are only available when the underlying system supports or
+requires them; yet others are available only when a particular configuration
+option was chosen at the time when Python was compiled and installed.
+
+This manual is organized "from the inside out:" it first describes the built-in
+data types, then the built-in functions and exceptions, and finally the modules,
+grouped in chapters of related modules. The ordering of the chapters as well as
+the ordering of the modules within each chapter is roughly from most relevant to
+least important.
+
+This means that if you start reading this manual from the start, and skip to the
+next chapter when you get bored, you will get a reasonable overview of the
+available modules and application areas that are supported by the Python
+library. Of course, you don't *have* to read it like a novel --- you can also
+browse the table of contents (in front of the manual), or look for a specific
+function, module or term in the index (in the back). And finally, if you enjoy
+learning about random subjects, you choose a random page number (see module
+:mod:`random`) and read a section or two. Regardless of the order in which you
+read the sections of this manual, it helps to start with chapter :ref:`builtin`,
+as the remainder of the manual assumes familiarity with this material.
+
+Let the show begin!
+
--- /dev/null
+
+.. _ipc:
+
+*****************************************
+Interprocess Communication and Networking
+*****************************************
+
+The modules described in this chapter provide mechanisms for different processes
+to communicate.
+
+Some modules only work for two processes that are on the same machine, e.g.
+:mod:`signal` and :mod:`subprocess`. Other modules support networking protocols
+that two or more processes can used to communicate across machines.
+
+The list of modules described in this chapter is:
+
+
+.. toctree::
+
+ subprocess.rst
+ socket.rst
+ signal.rst
+ popen2.rst
+ asyncore.rst
+ asynchat.rst
--- /dev/null
+
+:mod:`itertools` --- Functions creating iterators for efficient looping
+=======================================================================
+
+.. module:: itertools
+ :synopsis: Functions creating iterators for efficient looping.
+.. moduleauthor:: Raymond Hettinger <python@rcn.com>
+.. sectionauthor:: Raymond Hettinger <python@rcn.com>
+
+
+.. versionadded:: 2.3
+
+This module implements a number of iterator building blocks inspired by
+constructs from the Haskell and SML programming languages. Each has been recast
+in a form suitable for Python.
+
+The module standardizes a core set of fast, memory efficient tools that are
+useful by themselves or in combination. Standardization helps avoid the
+readability and reliability problems which arise when many different individuals
+create their own slightly varying implementations, each with their own quirks
+and naming conventions.
+
+The tools are designed to combine readily with one another. This makes it easy
+to construct more specialized tools succinctly and efficiently in pure Python.
+
+For instance, SML provides a tabulation tool: ``tabulate(f)`` which produces a
+sequence ``f(0), f(1), ...``. This toolbox provides :func:`imap` and
+:func:`count` which can be combined to form ``imap(f, count())`` and produce an
+equivalent result.
+
+Likewise, the functional tools are designed to work well with the high-speed
+functions provided by the :mod:`operator` module.
+
+The module author welcomes suggestions for other basic building blocks to be
+added to future versions of the module.
+
+Whether cast in pure python form or compiled code, tools that use iterators are
+more memory efficient (and faster) than their list based counterparts. Adopting
+the principles of just-in-time manufacturing, they create data when and where
+needed instead of consuming memory with the computer equivalent of "inventory".
+
+The performance advantage of iterators becomes more acute as the number of
+elements increases -- at some point, lists grow large enough to severely impact
+memory cache performance and start running slowly.
+
+
+.. seealso::
+
+ The Standard ML Basis Library, `The Standard ML Basis Library
+ <http://www.standardml.org/Basis/>`_.
+
+ Haskell, A Purely Functional Language, `Definition of Haskell and the Standard
+ Libraries <http://www.haskell.org/definition/>`_.
+
+
+.. _itertools-functions:
+
+Itertool functions
+------------------
+
+The following module functions all construct and return iterators. Some provide
+streams of infinite length, so they should only be accessed by functions or
+loops that truncate the stream.
+
+
+.. function:: chain(*iterables)
+
+ Make an iterator that returns elements from the first iterable until it is
+ exhausted, then proceeds to the next iterable, until all of the iterables are
+ exhausted. Used for treating consecutive sequences as a single sequence.
+ Equivalent to::
+
+ def chain(*iterables):
+ for it in iterables:
+ for element in it:
+ yield element
+
+
+.. function:: count([n])
+
+ Make an iterator that returns consecutive integers starting with *n*. If not
+ specified *n* defaults to zero. Does not currently support python long
+ integers. Often used as an argument to :func:`imap` to generate consecutive
+ data points. Also, used with :func:`izip` to add sequence numbers. Equivalent
+ to::
+
+ def count(n=0):
+ while True:
+ yield n
+ n += 1
+
+ Note, :func:`count` does not check for overflow and will return negative numbers
+ after exceeding ``sys.maxint``. This behavior may change in the future.
+
+
+.. function:: cycle(iterable)
+
+ Make an iterator returning elements from the iterable and saving a copy of each.
+ When the iterable is exhausted, return elements from the saved copy. Repeats
+ indefinitely. Equivalent to::
+
+ def cycle(iterable):
+ saved = []
+ for element in iterable:
+ yield element
+ saved.append(element)
+ while saved:
+ for element in saved:
+ yield element
+
+ Note, this member of the toolkit may require significant auxiliary storage
+ (depending on the length of the iterable).
+
+
+.. function:: dropwhile(predicate, iterable)
+
+ Make an iterator that drops elements from the iterable as long as the predicate
+ is true; afterwards, returns every element. Note, the iterator does not produce
+ *any* output until the predicate first becomes false, so it may have a lengthy
+ start-up time. Equivalent to::
+
+ def dropwhile(predicate, iterable):
+ iterable = iter(iterable)
+ for x in iterable:
+ if not predicate(x):
+ yield x
+ break
+ for x in iterable:
+ yield x
+
+
+.. function:: groupby(iterable[, key])
+
+ Make an iterator that returns consecutive keys and groups from the *iterable*.
+ The *key* is a function computing a key value for each element. If not
+ specified or is ``None``, *key* defaults to an identity function and returns
+ the element unchanged. Generally, the iterable needs to already be sorted on
+ the same key function.
+
+ The operation of :func:`groupby` is similar to the ``uniq`` filter in Unix. It
+ generates a break or new group every time the value of the key function changes
+ (which is why it is usually necessary to have sorted the data using the same key
+ function). That behavior differs from SQL's GROUP BY which aggregates common
+ elements regardless of their input order.
+
+ The returned group is itself an iterator that shares the underlying iterable
+ with :func:`groupby`. Because the source is shared, when the :func:`groupby`
+ object is advanced, the previous group is no longer visible. So, if that data
+ is needed later, it should be stored as a list::
+
+ groups = []
+ uniquekeys = []
+ data = sorted(data, key=keyfunc)
+ for k, g in groupby(data, keyfunc):
+ groups.append(list(g)) # Store group iterator as a list
+ uniquekeys.append(k)
+
+ :func:`groupby` is equivalent to::
+
+ class groupby(object):
+ def __init__(self, iterable, key=None):
+ if key is None:
+ key = lambda x: x
+ self.keyfunc = key
+ self.it = iter(iterable)
+ self.tgtkey = self.currkey = self.currvalue = xrange(0)
+ def __iter__(self):
+ return self
+ def next(self):
+ while self.currkey == self.tgtkey:
+ self.currvalue = self.it.next() # Exit on StopIteration
+ self.currkey = self.keyfunc(self.currvalue)
+ self.tgtkey = self.currkey
+ return (self.currkey, self._grouper(self.tgtkey))
+ def _grouper(self, tgtkey):
+ while self.currkey == tgtkey:
+ yield self.currvalue
+ self.currvalue = self.it.next() # Exit on StopIteration
+ self.currkey = self.keyfunc(self.currvalue)
+
+ .. versionadded:: 2.4
+
+
+.. function:: ifilter(predicate, iterable)
+
+ Make an iterator that filters elements from iterable returning only those for
+ which the predicate is ``True``. If *predicate* is ``None``, return the items
+ that are true. Equivalent to::
+
+ def ifilter(predicate, iterable):
+ if predicate is None:
+ predicate = bool
+ for x in iterable:
+ if predicate(x):
+ yield x
+
+
+.. function:: ifilterfalse(predicate, iterable)
+
+ Make an iterator that filters elements from iterable returning only those for
+ which the predicate is ``False``. If *predicate* is ``None``, return the items
+ that are false. Equivalent to::
+
+ def ifilterfalse(predicate, iterable):
+ if predicate is None:
+ predicate = bool
+ for x in iterable:
+ if not predicate(x):
+ yield x
+
+
+.. function:: imap(function, *iterables)
+
+ Make an iterator that computes the function using arguments from each of the
+ iterables. If *function* is set to ``None``, then :func:`imap` returns the
+ arguments as a tuple. Like :func:`map` but stops when the shortest iterable is
+ exhausted instead of filling in ``None`` for shorter iterables. The reason for
+ the difference is that infinite iterator arguments are typically an error for
+ :func:`map` (because the output is fully evaluated) but represent a common and
+ useful way of supplying arguments to :func:`imap`. Equivalent to::
+
+ def imap(function, *iterables):
+ iterables = map(iter, iterables)
+ while True:
+ args = [i.next() for i in iterables]
+ if function is None:
+ yield tuple(args)
+ else:
+ yield function(*args)
+
+
+.. function:: islice(iterable, [start,] stop [, step])
+
+ Make an iterator that returns selected elements from the iterable. If *start* is
+ non-zero, then elements from the iterable are skipped until start is reached.
+ Afterward, elements are returned consecutively unless *step* is set higher than
+ one which results in items being skipped. If *stop* is ``None``, then iteration
+ continues until the iterator is exhausted, if at all; otherwise, it stops at the
+ specified position. Unlike regular slicing, :func:`islice` does not support
+ negative values for *start*, *stop*, or *step*. Can be used to extract related
+ fields from data where the internal structure has been flattened (for example, a
+ multi-line report may list a name field on every third line). Equivalent to::
+
+ def islice(iterable, *args):
+ s = slice(*args)
+ it = iter(xrange(s.start or 0, s.stop or sys.maxint, s.step or 1))
+ nexti = it.next()
+ for i, element in enumerate(iterable):
+ if i == nexti:
+ yield element
+ nexti = it.next()
+
+ If *start* is ``None``, then iteration starts at zero. If *step* is ``None``,
+ then the step defaults to one.
+
+ .. versionchanged:: 2.5
+ accept ``None`` values for default *start* and *step*.
+
+
+.. function:: izip(*iterables)
+
+ Make an iterator that aggregates elements from each of the iterables. Like
+ :func:`zip` except that it returns an iterator instead of a list. Used for
+ lock-step iteration over several iterables at a time. Equivalent to::
+
+ def izip(*iterables):
+ iterables = map(iter, iterables)
+ while iterables:
+ result = [it.next() for it in iterables]
+ yield tuple(result)
+
+ .. versionchanged:: 2.4
+ When no iterables are specified, returns a zero length iterator instead of
+ raising a :exc:`TypeError` exception.
+
+ Note, the left-to-right evaluation order of the iterables is guaranteed. This
+ makes possible an idiom for clustering a data series into n-length groups using
+ ``izip(*[iter(s)]*n)``. For data that doesn't fit n-length groups exactly, the
+ last tuple can be pre-padded with fill values using ``izip(*[chain(s,
+ [None]*(n-1))]*n)``.
+
+ Note, when :func:`izip` is used with unequal length inputs, subsequent
+ iteration over the longer iterables cannot reliably be continued after
+ :func:`izip` terminates. Potentially, up to one entry will be missing from
+ each of the left-over iterables. This occurs because a value is fetched from
+ each iterator in turn, but the process ends when one of the iterators
+ terminates. This leaves the last fetched values in limbo (they cannot be
+ returned in a final, incomplete tuple and they are cannot be pushed back into
+ the iterator for retrieval with ``it.next()``). In general, :func:`izip`
+ should only be used with unequal length inputs when you don't care about
+ trailing, unmatched values from the longer iterables.
+
+
+.. function:: izip_longest(*iterables[, fillvalue])
+
+ Make an iterator that aggregates elements from each of the iterables. If the
+ iterables are of uneven length, missing values are filled-in with *fillvalue*.
+ Iteration continues until the longest iterable is exhausted. Equivalent to::
+
+ def izip_longest(*args, **kwds):
+ fillvalue = kwds.get('fillvalue')
+ def sentinel(counter = ([fillvalue]*(len(args)-1)).pop):
+ yield counter() # yields the fillvalue, or raises IndexError
+ fillers = repeat(fillvalue)
+ iters = [chain(it, sentinel(), fillers) for it in args]
+ try:
+ for tup in izip(*iters):
+ yield tup
+ except IndexError:
+ pass
+
+ If one of the iterables is potentially infinite, then the :func:`izip_longest`
+ function should be wrapped with something that limits the number of calls (for
+ example :func:`islice` or :func:`takewhile`).
+
+ .. versionadded:: 2.6
+
+
+.. function:: repeat(object[, times])
+
+ Make an iterator that returns *object* over and over again. Runs indefinitely
+ unless the *times* argument is specified. Used as argument to :func:`imap` for
+ invariant parameters to the called function. Also used with :func:`izip` to
+ create an invariant part of a tuple record. Equivalent to::
+
+ def repeat(object, times=None):
+ if times is None:
+ while True:
+ yield object
+ else:
+ for i in xrange(times):
+ yield object
+
+
+.. function:: starmap(function, iterable)
+
+ Make an iterator that computes the function using arguments tuples obtained from
+ the iterable. Used instead of :func:`imap` when argument parameters are already
+ grouped in tuples from a single iterable (the data has been "pre-zipped"). The
+ difference between :func:`imap` and :func:`starmap` parallels the distinction
+ between ``function(a,b)`` and ``function(*c)``. Equivalent to::
+
+ def starmap(function, iterable):
+ iterable = iter(iterable)
+ while True:
+ yield function(*iterable.next())
+
+
+.. function:: takewhile(predicate, iterable)
+
+ Make an iterator that returns elements from the iterable as long as the
+ predicate is true. Equivalent to::
+
+ def takewhile(predicate, iterable):
+ for x in iterable:
+ if predicate(x):
+ yield x
+ else:
+ break
+
+
+.. function:: tee(iterable[, n=2])
+
+ Return *n* independent iterators from a single iterable. The case where ``n==2``
+ is equivalent to::
+
+ def tee(iterable):
+ def gen(next, data={}, cnt=[0]):
+ for i in count():
+ if i == cnt[0]:
+ item = data[i] = next()
+ cnt[0] += 1
+ else:
+ item = data.pop(i)
+ yield item
+ it = iter(iterable)
+ return (gen(it.next), gen(it.next))
+
+ Note, once :func:`tee` has made a split, the original *iterable* should not be
+ used anywhere else; otherwise, the *iterable* could get advanced without the tee
+ objects being informed.
+
+ Note, this member of the toolkit may require significant auxiliary storage
+ (depending on how much temporary data needs to be stored). In general, if one
+ iterator is going to use most or all of the data before the other iterator, it
+ is faster to use :func:`list` instead of :func:`tee`.
+
+ .. versionadded:: 2.4
+
+
+.. _itertools-example:
+
+Examples
+--------
+
+The following examples show common uses for each tool and demonstrate ways they
+can be combined. ::
+
+ >>> amounts = [120.15, 764.05, 823.14]
+ >>> for checknum, amount in izip(count(1200), amounts):
+ ... print 'Check %d is for $%.2f' % (checknum, amount)
+ ...
+ Check 1200 is for $120.15
+ Check 1201 is for $764.05
+ Check 1202 is for $823.14
+
+ >>> import operator
+ >>> for cube in imap(operator.pow, xrange(1,5), repeat(3)):
+ ... print cube
+ ...
+ 1
+ 8
+ 27
+ 64
+
+ >>> reportlines = ['EuroPython', 'Roster', '', 'alex', '', 'laura',
+ ... '', 'martin', '', 'walter', '', 'mark']
+ >>> for name in islice(reportlines, 3, None, 2):
+ ... print name.title()
+ ...
+ Alex
+ Laura
+ Martin
+ Walter
+ Mark
+
+ # Show a dictionary sorted and grouped by value
+ >>> from operator import itemgetter
+ >>> d = dict(a=1, b=2, c=1, d=2, e=1, f=2, g=3)
+ >>> di = sorted(d.iteritems(), key=itemgetter(1))
+ >>> for k, g in groupby(di, key=itemgetter(1)):
+ ... print k, map(itemgetter(0), g)
+ ...
+ 1 ['a', 'c', 'e']
+ 2 ['b', 'd', 'f']
+ 3 ['g']
+
+ # Find runs of consecutive numbers using groupby. The key to the solution
+ # is differencing with a range so that consecutive numbers all appear in
+ # same group.
+ >>> data = [ 1, 4,5,6, 10, 15,16,17,18, 22, 25,26,27,28]
+ >>> for k, g in groupby(enumerate(data), lambda (i,x):i-x):
+ ... print map(operator.itemgetter(1), g)
+ ...
+ [1]
+ [4, 5, 6]
+ [10]
+ [15, 16, 17, 18]
+ [22]
+ [25, 26, 27, 28]
+
+
+
+.. _itertools-recipes:
+
+Recipes
+-------
+
+This section shows recipes for creating an extended toolset using the existing
+itertools as building blocks.
+
+The extended tools offer the same high performance as the underlying toolset.
+The superior memory performance is kept by processing elements one at a time
+rather than bringing the whole iterable into memory all at once. Code volume is
+kept small by linking the tools together in a functional style which helps
+eliminate temporary variables. High speed is retained by preferring
+"vectorized" building blocks over the use of for-loops and generators which
+incur interpreter overhead. ::
+
+ def take(n, seq):
+ return list(islice(seq, n))
+
+ def enumerate(iterable):
+ return izip(count(), iterable)
+
+ def tabulate(function):
+ "Return function(0), function(1), ..."
+ return imap(function, count())
+
+ def iteritems(mapping):
+ return izip(mapping.iterkeys(), mapping.itervalues())
+
+ def nth(iterable, n):
+ "Returns the nth item or raise StopIteration"
+ return islice(iterable, n, None).next()
+
+ def all(seq, pred=None):
+ "Returns True if pred(x) is true for every element in the iterable"
+ for elem in ifilterfalse(pred, seq):
+ return False
+ return True
+
+ def any(seq, pred=None):
+ "Returns True if pred(x) is true for at least one element in the iterable"
+ for elem in ifilter(pred, seq):
+ return True
+ return False
+
+ def no(seq, pred=None):
+ "Returns True if pred(x) is false for every element in the iterable"
+ for elem in ifilter(pred, seq):
+ return False
+ return True
+
+ def quantify(seq, pred=None):
+ "Count how many times the predicate is true in the sequence"
+ return sum(imap(pred, seq))
+
+ def padnone(seq):
+ """Returns the sequence elements and then returns None indefinitely.
+
+ Useful for emulating the behavior of the built-in map() function.
+ """
+ return chain(seq, repeat(None))
+
+ def ncycles(seq, n):
+ "Returns the sequence elements n times"
+ return chain(*repeat(seq, n))
+
+ def dotproduct(vec1, vec2):
+ return sum(imap(operator.mul, vec1, vec2))
+
+ def flatten(listOfLists):
+ return list(chain(*listOfLists))
+
+ def repeatfunc(func, times=None, *args):
+ """Repeat calls to func with specified arguments.
+
+ Example: repeatfunc(random.random)
+ """
+ if times is None:
+ return starmap(func, repeat(args))
+ else:
+ return starmap(func, repeat(args, times))
+
+ def pairwise(iterable):
+ "s -> (s0,s1), (s1,s2), (s2, s3), ..."
+ a, b = tee(iterable)
+ try:
+ b.next()
+ except StopIteration:
+ pass
+ return izip(a, b)
+
+ def grouper(n, iterable, padvalue=None):
+ "grouper(3, 'abcdefg', 'x') --> ('a','b','c'), ('d','e','f'), ('g','x','x')"
+ return izip(*[chain(iterable, repeat(padvalue, n-1))]*n)
+
+
+
--- /dev/null
+
+:mod:`jpeg` --- Read and write JPEG files
+=========================================
+
+.. module:: jpeg
+ :platform: IRIX
+ :synopsis: Read and write image files in compressed JPEG format.
+
+
+.. index:: single: Independent JPEG Group
+
+The module :mod:`jpeg` provides access to the jpeg compressor and decompressor
+written by the Independent JPEG Group (IJG). JPEG is a standard for compressing
+pictures; it is defined in ISO 10918. For details on JPEG or the Independent
+JPEG Group software refer to the JPEG standard or the documentation provided
+with the software.
+
+.. index::
+ single: Python Imaging Library
+ single: PIL (the Python Imaging Library)
+ single: Lundh, Fredrik
+
+A portable interface to JPEG image files is available with the Python Imaging
+Library (PIL) by Fredrik Lundh. Information on PIL is available at
+http://www.pythonware.com/products/pil/.
+
+The :mod:`jpeg` module defines an exception and some functions.
+
+
+.. exception:: error
+
+ Exception raised by :func:`compress` and :func:`decompress` in case of errors.
+
+
+.. function:: compress(data, w, h, b)
+
+ .. index:: single: JFIF
+
+ Treat data as a pixmap of width *w* and height *h*, with *b* bytes per pixel.
+ The data is in SGI GL order, so the first pixel is in the lower-left corner.
+ This means that :func:`gl.lrectread` return data can immediately be passed to
+ :func:`compress`. Currently only 1 byte and 4 byte pixels are allowed, the
+ former being treated as greyscale and the latter as RGB color. :func:`compress`
+ returns a string that contains the compressed picture, in JFIF format.
+
+
+.. function:: decompress(data)
+
+ .. index:: single: JFIF
+
+ Data is a string containing a picture in JFIF format. It returns a tuple
+ ``(data, width, height, bytesperpixel)``. Again, the data is suitable to pass
+ to :func:`gl.lrectwrite`.
+
+
+.. function:: setoption(name, value)
+
+ Set various options. Subsequent :func:`compress` and :func:`decompress` calls
+ will use these options. The following options are available:
+
+ +-----------------+---------------------------------------------+
+ | Option | Effect |
+ +=================+=============================================+
+ | ``'forcegray'`` | Force output to be grayscale, even if input |
+ | | is RGB. |
+ +-----------------+---------------------------------------------+
+ | ``'quality'`` | Set the quality of the compressed image to |
+ | | a value between ``0`` and ``100`` (default |
+ | | is ``75``). This only affects compression. |
+ +-----------------+---------------------------------------------+
+ | ``'optimize'`` | Perform Huffman table optimization. Takes |
+ | | longer, but results in smaller compressed |
+ | | image. This only affects compression. |
+ +-----------------+---------------------------------------------+
+ | ``'smooth'`` | Perform inter-block smoothing on |
+ | | uncompressed image. Only useful for low- |
+ | | quality images. This only affects |
+ | | decompression. |
+ +-----------------+---------------------------------------------+
+
+ .. %
+ .. %
+ .. %
+ .. %
+
+
+.. seealso::
+
+ JPEG Still Image Data Compression Standard
+ The canonical reference for the JPEG image format, by Pennebaker and Mitchell.
+
+ `Information Technology - Digital Compression and Coding of Continuous-tone Still Images - Requirements and Guidelines <http://www.w3.org/Graphics/JPEG/itu-t81.pdf>`_
+ The ISO standard for JPEG is also published as ITU T.81. This is available
+ online in PDF form.
+
--- /dev/null
+
+:mod:`keyword` --- Testing for Python keywords
+==============================================
+
+.. module:: keyword
+ :synopsis: Test whether a string is a keyword in Python.
+
+
+This module allows a Python program to determine if a string is a keyword.
+
+
+.. function:: iskeyword(s)
+
+ Return true if *s* is a Python keyword.
+
+
+.. data:: kwlist
+
+ Sequence containing all the keywords defined for the interpreter. If any
+ keywords are defined to only be active when particular :mod:`__future__`
+ statements are in effect, these will be included as well.
+
--- /dev/null
+
+.. _language:
+
+************************
+Python Language Services
+************************
+
+Python provides a number of modules to assist in working with the Python
+language. These modules support tokenizing, parsing, syntax analysis, bytecode
+disassembly, and various other facilities.
+
+These modules include:
+
+
+.. toctree::
+
+ parser.rst
+ symbol.rst
+ token.rst
+ keyword.rst
+ tokenize.rst
+ tabnanny.rst
+ pyclbr.rst
+ py_compile.rst
+ compileall.rst
+ dis.rst
+ pickletools.rst
+ distutils.rst
--- /dev/null
+
+:mod:`linecache` --- Random access to text lines
+================================================
+
+.. module:: linecache
+ :synopsis: This module provides random access to individual lines from text files.
+.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+
+
+The :mod:`linecache` module allows one to get any line from any file, while
+attempting to optimize internally, using a cache, the common case where many
+lines are read from a single file. This is used by the :mod:`traceback` module
+to retrieve source lines for inclusion in the formatted traceback.
+
+The :mod:`linecache` module defines the following functions:
+
+
+.. function:: getline(filename, lineno[, module_globals])
+
+ Get line *lineno* from file named *filename*. This function will never throw an
+ exception --- it will return ``''`` on errors (the terminating newline character
+ will be included for lines that are found).
+
+ .. index:: triple: module; search; path
+
+ If a file named *filename* is not found, the function will look for it in the
+ module search path, ``sys.path``, after first checking for a :pep:`302`
+ ``__loader__`` in *module_globals*, in case the module was imported from a
+ zipfile or other non-filesystem import source.
+
+ .. versionadded:: 2.5
+ The *module_globals* parameter was added.
+
+
+.. function:: clearcache()
+
+ Clear the cache. Use this function if you no longer need lines from files
+ previously read using :func:`getline`.
+
+
+.. function:: checkcache([filename])
+
+ Check the cache for validity. Use this function if files in the cache may have
+ changed on disk, and you require the updated version. If *filename* is omitted,
+ it will check all the entries in the cache.
+
+Example::
+
+ >>> import linecache
+ >>> linecache.getline('/etc/passwd', 4)
+ 'sys:x:3:3:sys:/dev:/bin/sh\n'
+
--- /dev/null
+
+:mod:`locale` --- Internationalization services
+===============================================
+
+.. module:: locale
+ :synopsis: Internationalization services.
+.. moduleauthor:: Martin von Löwis <martin@v.loewis.de>
+.. sectionauthor:: Martin von Löwis <martin@v.loewis.de>
+
+
+The :mod:`locale` module opens access to the POSIX locale database and
+functionality. The POSIX locale mechanism allows programmers to deal with
+certain cultural issues in an application, without requiring the programmer to
+know all the specifics of each country where the software is executed.
+
+.. index:: module: _locale
+
+The :mod:`locale` module is implemented on top of the :mod:`_locale` module,
+which in turn uses an ANSI C locale implementation if available.
+
+The :mod:`locale` module defines the following exception and functions:
+
+
+.. exception:: Error
+
+ Exception raised when :func:`setlocale` fails.
+
+
+.. function:: setlocale(category[, locale])
+
+ If *locale* is specified, it may be a string, a tuple of the form ``(language
+ code, encoding)``, or ``None``. If it is a tuple, it is converted to a string
+ using the locale aliasing engine. If *locale* is given and not ``None``,
+ :func:`setlocale` modifies the locale setting for the *category*. The available
+ categories are listed in the data description below. The value is the name of a
+ locale. An empty string specifies the user's default settings. If the
+ modification of the locale fails, the exception :exc:`Error` is raised. If
+ successful, the new locale setting is returned.
+
+ If *locale* is omitted or ``None``, the current setting for *category* is
+ returned.
+
+ :func:`setlocale` is not thread safe on most systems. Applications typically
+ start with a call of ::
+
+ import locale
+ locale.setlocale(locale.LC_ALL, '')
+
+ This sets the locale for all categories to the user's default setting (typically
+ specified in the :envvar:`LANG` environment variable). If the locale is not
+ changed thereafter, using multithreading should not cause problems.
+
+ .. versionchanged:: 2.0
+ Added support for tuple values of the *locale* parameter.
+
+
+.. function:: localeconv()
+
+ Returns the database of the local conventions as a dictionary. This dictionary
+ has the following strings as keys:
+
+ +----------------------+-------------------------------------+--------------------------------+
+ | Category | Key | Meaning |
+ +======================+=====================================+================================+
+ | :const:`LC_NUMERIC` | ``'decimal_point'`` | Decimal point character. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'grouping'`` | Sequence of numbers specifying |
+ | | | which relative positions the |
+ | | | ``'thousands_sep'`` is |
+ | | | expected. If the sequence is |
+ | | | terminated with |
+ | | | :const:`CHAR_MAX`, no further |
+ | | | grouping is performed. If the |
+ | | | sequence terminates with a |
+ | | | ``0``, the last group size is |
+ | | | repeatedly used. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'thousands_sep'`` | Character used between groups. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | :const:`LC_MONETARY` | ``'int_curr_symbol'`` | International currency symbol. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'currency_symbol'`` | Local currency symbol. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'p_cs_precedes/n_cs_precedes'`` | Whether the currency symbol |
+ | | | precedes the value (for |
+ | | | positive resp. negative |
+ | | | values). |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'p_sep_by_space/n_sep_by_space'`` | Whether the currency symbol is |
+ | | | separated from the value by a |
+ | | | space (for positive resp. |
+ | | | negative values). |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'mon_decimal_point'`` | Decimal point used for |
+ | | | monetary values. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'frac_digits'`` | Number of fractional digits |
+ | | | used in local formatting of |
+ | | | monetary values. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'int_frac_digits'`` | Number of fractional digits |
+ | | | used in international |
+ | | | formatting of monetary values. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'mon_thousands_sep'`` | Group separator used for |
+ | | | monetary values. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'mon_grouping'`` | Equivalent to ``'grouping'``, |
+ | | | used for monetary values. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'positive_sign'`` | Symbol used to annotate a |
+ | | | positive monetary value. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'negative_sign'`` | Symbol used to annotate a |
+ | | | negative monetary value. |
+ +----------------------+-------------------------------------+--------------------------------+
+ | | ``'p_sign_posn/n_sign_posn'`` | The position of the sign (for |
+ | | | positive resp. negative |
+ | | | values), see below. |
+ +----------------------+-------------------------------------+--------------------------------+
+
+ All numeric values can be set to :const:`CHAR_MAX` to indicate that there is no
+ value specified in this locale.
+
+ The possible values for ``'p_sign_posn'`` and ``'n_sign_posn'`` are given below.
+
+ +--------------+-----------------------------------------+
+ | Value | Explanation |
+ +==============+=========================================+
+ | ``0`` | Currency and value are surrounded by |
+ | | parentheses. |
+ +--------------+-----------------------------------------+
+ | ``1`` | The sign should precede the value and |
+ | | currency symbol. |
+ +--------------+-----------------------------------------+
+ | ``2`` | The sign should follow the value and |
+ | | currency symbol. |
+ +--------------+-----------------------------------------+
+ | ``3`` | The sign should immediately precede the |
+ | | value. |
+ +--------------+-----------------------------------------+
+ | ``4`` | The sign should immediately follow the |
+ | | value. |
+ +--------------+-----------------------------------------+
+ | ``CHAR_MAX`` | Nothing is specified in this locale. |
+ +--------------+-----------------------------------------+
+
+
+.. function:: nl_langinfo(option)
+
+ Return some locale-specific information as a string. This function is not
+ available on all systems, and the set of possible options might also vary across
+ platforms. The possible argument values are numbers, for which symbolic
+ constants are available in the locale module.
+
+
+.. function:: getdefaultlocale([envvars])
+
+ Tries to determine the default locale settings and returns them as a tuple of
+ the form ``(language code, encoding)``.
+
+ According to POSIX, a program which has not called ``setlocale(LC_ALL, '')``
+ runs using the portable ``'C'`` locale. Calling ``setlocale(LC_ALL, '')`` lets
+ it use the default locale as defined by the :envvar:`LANG` variable. Since we
+ do not want to interfere with the current locale setting we thus emulate the
+ behavior in the way described above.
+
+ To maintain compatibility with other platforms, not only the :envvar:`LANG`
+ variable is tested, but a list of variables given as envvars parameter. The
+ first found to be defined will be used. *envvars* defaults to the search path
+ used in GNU gettext; it must always contain the variable name ``LANG``. The GNU
+ gettext search path contains ``'LANGUAGE'``, ``'LC_ALL'``, ``'LC_CTYPE'``, and
+ ``'LANG'``, in that order.
+
+ Except for the code ``'C'``, the language code corresponds to :rfc:`1766`.
+ *language code* and *encoding* may be ``None`` if their values cannot be
+ determined.
+
+ .. versionadded:: 2.0
+
+
+.. function:: getlocale([category])
+
+ Returns the current setting for the given locale category as sequence containing
+ *language code*, *encoding*. *category* may be one of the :const:`LC_\*` values
+ except :const:`LC_ALL`. It defaults to :const:`LC_CTYPE`.
+
+ Except for the code ``'C'``, the language code corresponds to :rfc:`1766`.
+ *language code* and *encoding* may be ``None`` if their values cannot be
+ determined.
+
+ .. versionadded:: 2.0
+
+
+.. function:: getpreferredencoding([do_setlocale])
+
+ Return the encoding used for text data, according to user preferences. User
+ preferences are expressed differently on different systems, and might not be
+ available programmatically on some systems, so this function only returns a
+ guess.
+
+ On some systems, it is necessary to invoke :func:`setlocale` to obtain the user
+ preferences, so this function is not thread-safe. If invoking setlocale is not
+ necessary or desired, *do_setlocale* should be set to ``False``.
+
+ .. versionadded:: 2.3
+
+
+.. function:: normalize(localename)
+
+ Returns a normalized locale code for the given locale name. The returned locale
+ code is formatted for use with :func:`setlocale`. If normalization fails, the
+ original name is returned unchanged.
+
+ If the given encoding is not known, the function defaults to the default
+ encoding for the locale code just like :func:`setlocale`.
+
+ .. versionadded:: 2.0
+
+
+.. function:: resetlocale([category])
+
+ Sets the locale for *category* to the default setting.
+
+ The default setting is determined by calling :func:`getdefaultlocale`.
+ *category* defaults to :const:`LC_ALL`.
+
+ .. versionadded:: 2.0
+
+
+.. function:: strcoll(string1, string2)
+
+ Compares two strings according to the current :const:`LC_COLLATE` setting. As
+ any other compare function, returns a negative, or a positive value, or ``0``,
+ depending on whether *string1* collates before or after *string2* or is equal to
+ it.
+
+
+.. function:: strxfrm(string)
+
+ .. index:: builtin: cmp
+
+ Transforms a string to one that can be used for the built-in function
+ :func:`cmp`, and still returns locale-aware results. This function can be used
+ when the same string is compared repeatedly, e.g. when collating a sequence of
+ strings.
+
+
+.. function:: format(format, val[, grouping[, monetary]])
+
+ Formats a number *val* according to the current :const:`LC_NUMERIC` setting.
+ The format follows the conventions of the ``%`` operator. For floating point
+ values, the decimal point is modified if appropriate. If *grouping* is true,
+ also takes the grouping into account.
+
+ If *monetary* is true, the conversion uses monetary thousands separator and
+ grouping strings.
+
+ Please note that this function will only work for exactly one %char specifier.
+ For whole format strings, use :func:`format_string`.
+
+ .. versionchanged:: 2.5
+ Added the *monetary* parameter.
+
+
+.. function:: format_string(format, val[, grouping])
+
+ Processes formatting specifiers as in ``format % val``, but takes the current
+ locale settings into account.
+
+ .. versionadded:: 2.5
+
+
+.. function:: currency(val[, symbol[, grouping[, international]]])
+
+ Formats a number *val* according to the current :const:`LC_MONETARY` settings.
+
+ The returned string includes the currency symbol if *symbol* is true, which is
+ the default. If *grouping* is true (which is not the default), grouping is done
+ with the value. If *international* is true (which is not the default), the
+ international currency symbol is used.
+
+ Note that this function will not work with the 'C' locale, so you have to set a
+ locale via :func:`setlocale` first.
+
+ .. versionadded:: 2.5
+
+
+.. function:: str(float)
+
+ Formats a floating point number using the same format as the built-in function
+ ``str(float)``, but takes the decimal point into account.
+
+
+.. function:: atof(string)
+
+ Converts a string to a floating point number, following the :const:`LC_NUMERIC`
+ settings.
+
+
+.. function:: atoi(string)
+
+ Converts a string to an integer, following the :const:`LC_NUMERIC` conventions.
+
+
+.. data:: LC_CTYPE
+
+ .. index:: module: string
+
+ Locale category for the character type functions. Depending on the settings of
+ this category, the functions of module :mod:`string` dealing with case change
+ their behaviour.
+
+
+.. data:: LC_COLLATE
+
+ Locale category for sorting strings. The functions :func:`strcoll` and
+ :func:`strxfrm` of the :mod:`locale` module are affected.
+
+
+.. data:: LC_TIME
+
+ Locale category for the formatting of time. The function :func:`time.strftime`
+ follows these conventions.
+
+
+.. data:: LC_MONETARY
+
+ Locale category for formatting of monetary values. The available options are
+ available from the :func:`localeconv` function.
+
+
+.. data:: LC_MESSAGES
+
+ Locale category for message display. Python currently does not support
+ application specific locale-aware messages. Messages displayed by the operating
+ system, like those returned by :func:`os.strerror` might be affected by this
+ category.
+
+
+.. data:: LC_NUMERIC
+
+ Locale category for formatting numbers. The functions :func:`format`,
+ :func:`atoi`, :func:`atof` and :func:`str` of the :mod:`locale` module are
+ affected by that category. All other numeric formatting operations are not
+ affected.
+
+
+.. data:: LC_ALL
+
+ Combination of all locale settings. If this flag is used when the locale is
+ changed, setting the locale for all categories is attempted. If that fails for
+ any category, no category is changed at all. When the locale is retrieved using
+ this flag, a string indicating the setting for all categories is returned. This
+ string can be later used to restore the settings.
+
+
+.. data:: CHAR_MAX
+
+ This is a symbolic constant used for different values returned by
+ :func:`localeconv`.
+
+The :func:`nl_langinfo` function accepts one of the following keys. Most
+descriptions are taken from the corresponding description in the GNU C library.
+
+
+.. data:: CODESET
+
+ Return a string with the name of the character encoding used in the selected
+ locale.
+
+
+.. data:: D_T_FMT
+
+ Return a string that can be used as a format string for strftime(3) to represent
+ time and date in a locale-specific way.
+
+
+.. data:: D_FMT
+
+ Return a string that can be used as a format string for strftime(3) to represent
+ a date in a locale-specific way.
+
+
+.. data:: T_FMT
+
+ Return a string that can be used as a format string for strftime(3) to represent
+ a time in a locale-specific way.
+
+
+.. data:: T_FMT_AMPM
+
+ The return value can be used as a format string for 'strftime' to represent time
+ in the am/pm format.
+
+
+.. data:: DAY_1 ... DAY_7
+
+ Return name of the n-th day of the week.
+
+ .. warning::
+
+ This follows the US convention of :const:`DAY_1` being Sunday, not the
+ international convention (ISO 8601) that Monday is the first day of the week.
+
+
+.. data:: ABDAY_1 ... ABDAY_7
+
+ Return abbreviated name of the n-th day of the week.
+
+
+.. data:: MON_1 ... MON_12
+
+ Return name of the n-th month.
+
+
+.. data:: ABMON_1 ... ABMON_12
+
+ Return abbreviated name of the n-th month.
+
+
+.. data:: RADIXCHAR
+
+ Return radix character (decimal dot, decimal comma, etc.)
+
+
+.. data:: THOUSEP
+
+ Return separator character for thousands (groups of three digits).
+
+
+.. data:: YESEXPR
+
+ Return a regular expression that can be used with the regex function to
+ recognize a positive response to a yes/no question.
+
+ .. warning::
+
+ The expression is in the syntax suitable for the :cfunc:`regex` function from
+ the C library, which might differ from the syntax used in :mod:`re`.
+
+
+.. data:: NOEXPR
+
+ Return a regular expression that can be used with the regex(3) function to
+ recognize a negative response to a yes/no question.
+
+
+.. data:: CRNCYSTR
+
+ Return the currency symbol, preceded by "-" if the symbol should appear before
+ the value, "+" if the symbol should appear after the value, or "." if the symbol
+ should replace the radix character.
+
+
+.. data:: ERA
+
+ The return value represents the era used in the current locale.
+
+ Most locales do not define this value. An example of a locale which does define
+ this value is the Japanese one. In Japan, the traditional representation of
+ dates includes the name of the era corresponding to the then-emperor's reign.
+
+ Normally it should not be necessary to use this value directly. Specifying the
+ ``E`` modifier in their format strings causes the :func:`strftime` function to
+ use this information. The format of the returned string is not specified, and
+ therefore you should not assume knowledge of it on different systems.
+
+
+.. data:: ERA_YEAR
+
+ The return value gives the year in the relevant era of the locale.
+
+
+.. data:: ERA_D_T_FMT
+
+ This return value can be used as a format string for :func:`strftime` to
+ represent dates and times in a locale-specific era-based way.
+
+
+.. data:: ERA_D_FMT
+
+ This return value can be used as a format string for :func:`strftime` to
+ represent time in a locale-specific era-based way.
+
+
+.. data:: ALT_DIGITS
+
+ The return value is a representation of up to 100 values used to represent the
+ values 0 to 99.
+
+Example::
+
+ >>> import locale
+ >>> loc = locale.getlocale(locale.LC_ALL) # get current locale
+ >>> locale.setlocale(locale.LC_ALL, 'de_DE') # use German locale; name might vary with platform
+ >>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut
+ >>> locale.setlocale(locale.LC_ALL, '') # use user's preferred locale
+ >>> locale.setlocale(locale.LC_ALL, 'C') # use default (C) locale
+ >>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale
+
+
+Background, details, hints, tips and caveats
+--------------------------------------------
+
+The C standard defines the locale as a program-wide property that may be
+relatively expensive to change. On top of that, some implementation are broken
+in such a way that frequent locale changes may cause core dumps. This makes the
+locale somewhat painful to use correctly.
+
+Initially, when a program is started, the locale is the ``C`` locale, no matter
+what the user's preferred locale is. The program must explicitly say that it
+wants the user's preferred locale settings by calling ``setlocale(LC_ALL, '')``.
+
+It is generally a bad idea to call :func:`setlocale` in some library routine,
+since as a side effect it affects the entire program. Saving and restoring it
+is almost as bad: it is expensive and affects other threads that happen to run
+before the settings have been restored.
+
+If, when coding a module for general use, you need a locale independent version
+of an operation that is affected by the locale (such as :func:`string.lower`, or
+certain formats used with :func:`time.strftime`), you will have to find a way to
+do it without using the standard library routine. Even better is convincing
+yourself that using locale settings is okay. Only as a last resort should you
+document that your module is not compatible with non-\ ``C`` locale settings.
+
+.. index:: module: string
+
+The case conversion functions in the :mod:`string` module are affected by the
+locale settings. When a call to the :func:`setlocale` function changes the
+:const:`LC_CTYPE` settings, the variables ``string.lowercase``,
+``string.uppercase`` and ``string.letters`` are recalculated. Note that code
+that uses these variable through ':keyword:`from` ... :keyword:`import` ...',
+e.g. ``from string import letters``, is not affected by subsequent
+:func:`setlocale` calls.
+
+The only way to perform numeric operations according to the locale is to use the
+special functions defined by this module: :func:`atof`, :func:`atoi`,
+:func:`format`, :func:`str`.
+
+
+.. _embedding-locale:
+
+For extension writers and programs that embed Python
+----------------------------------------------------
+
+Extension modules should never call :func:`setlocale`, except to find out what
+the current locale is. But since the return value can only be used portably to
+restore it, that is not very useful (except perhaps to find out whether or not
+the locale is ``C``).
+
+When Python code uses the :mod:`locale` module to change the locale, this also
+affects the embedding application. If the embedding application doesn't want
+this to happen, it should remove the :mod:`_locale` extension module (which does
+all the work) from the table of built-in modules in the :file:`config.c` file,
+and make sure that the :mod:`_locale` module is not accessible as a shared
+library.
+
+
+.. _locale-gettext:
+
+Access to message catalogs
+--------------------------
+
+The locale module exposes the C library's gettext interface on systems that
+provide this interface. It consists of the functions :func:`gettext`,
+:func:`dgettext`, :func:`dcgettext`, :func:`textdomain`, :func:`bindtextdomain`,
+and :func:`bind_textdomain_codeset`. These are similar to the same functions in
+the :mod:`gettext` module, but use the C library's binary format for message
+catalogs, and the C library's search algorithms for locating message catalogs.
+
+Python applications should normally find no need to invoke these functions, and
+should use :mod:`gettext` instead. A known exception to this rule are
+applications that link use additional C libraries which internally invoke
+:cfunc:`gettext` or :func:`dcgettext`. For these applications, it may be
+necessary to bind the text domain, so that the libraries can properly locate
+their message catalogs.
+
--- /dev/null
+:mod:`logging` --- Logging facility for Python
+==============================================
+
+.. module:: logging
+ :synopsis: Flexible error logging system for applications.
+
+
+.. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
+.. sectionauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
+
+
+.. % These apply to all modules, and may be given more than once:
+
+
+
+.. index:: pair: Errors; logging
+
+.. versionadded:: 2.3
+
+This module defines functions and classes which implement a flexible error
+logging system for applications.
+
+Logging is performed by calling methods on instances of the :class:`Logger`
+class (hereafter called :dfn:`loggers`). Each instance has a name, and they are
+conceptually arranged in a name space hierarchy using dots (periods) as
+separators. For example, a logger named "scan" is the parent of loggers
+"scan.text", "scan.html" and "scan.pdf". Logger names can be anything you want,
+and indicate the area of an application in which a logged message originates.
+
+Logged messages also have levels of importance associated with them. The default
+levels provided are :const:`DEBUG`, :const:`INFO`, :const:`WARNING`,
+:const:`ERROR` and :const:`CRITICAL`. As a convenience, you indicate the
+importance of a logged message by calling an appropriate method of
+:class:`Logger`. The methods are :meth:`debug`, :meth:`info`, :meth:`warning`,
+:meth:`error` and :meth:`critical`, which mirror the default levels. You are not
+constrained to use these levels: you can specify your own and use a more general
+:class:`Logger` method, :meth:`log`, which takes an explicit level argument.
+
+The numeric values of logging levels are given in the following table. These are
+primarily of interest if you want to define your own levels, and need them to
+have specific values relative to the predefined levels. If you define a level
+with the same numeric value, it overwrites the predefined value; the predefined
+name is lost.
+
++--------------+---------------+
+| Level | Numeric value |
++==============+===============+
+| ``CRITICAL`` | 50 |
++--------------+---------------+
+| ``ERROR`` | 40 |
++--------------+---------------+
+| ``WARNING`` | 30 |
++--------------+---------------+
+| ``INFO`` | 20 |
++--------------+---------------+
+| ``DEBUG`` | 10 |
++--------------+---------------+
+| ``NOTSET`` | 0 |
++--------------+---------------+
+
+Levels can also be associated with loggers, being set either by the developer or
+through loading a saved logging configuration. When a logging method is called
+on a logger, the logger compares its own level with the level associated with
+the method call. If the logger's level is higher than the method call's, no
+logging message is actually generated. This is the basic mechanism controlling
+the verbosity of logging output.
+
+Logging messages are encoded as instances of the :class:`LogRecord` class. When
+a logger decides to actually log an event, a :class:`LogRecord` instance is
+created from the logging message.
+
+Logging messages are subjected to a dispatch mechanism through the use of
+:dfn:`handlers`, which are instances of subclasses of the :class:`Handler`
+class. Handlers are responsible for ensuring that a logged message (in the form
+of a :class:`LogRecord`) ends up in a particular location (or set of locations)
+which is useful for the target audience for that message (such as end users,
+support desk staff, system administrators, developers). Handlers are passed
+:class:`LogRecord` instances intended for particular destinations. Each logger
+can have zero, one or more handlers associated with it (via the
+:meth:`addHandler` method of :class:`Logger`). In addition to any handlers
+directly associated with a logger, *all handlers associated with all ancestors
+of the logger* are called to dispatch the message.
+
+Just as for loggers, handlers can have levels associated with them. A handler's
+level acts as a filter in the same way as a logger's level does. If a handler
+decides to actually dispatch an event, the :meth:`emit` method is used to send
+the message to its destination. Most user-defined subclasses of :class:`Handler`
+will need to override this :meth:`emit`.
+
+In addition to the base :class:`Handler` class, many useful subclasses are
+provided:
+
+#. :class:`StreamHandler` instances send error messages to streams (file-like
+ objects).
+
+#. :class:`FileHandler` instances send error messages to disk files.
+
+#. :class:`BaseRotatingHandler` is the base class for handlers that rotate log
+ files at a certain point. It is not meant to be instantiated directly. Instead,
+ use :class:`RotatingFileHandler` or :class:`TimedRotatingFileHandler`.
+
+#. :class:`RotatingFileHandler` instances send error messages to disk files,
+ with support for maximum log file sizes and log file rotation.
+
+#. :class:`TimedRotatingFileHandler` instances send error messages to disk files
+ rotating the log file at certain timed intervals.
+
+#. :class:`SocketHandler` instances send error messages to TCP/IP sockets.
+
+#. :class:`DatagramHandler` instances send error messages to UDP sockets.
+
+#. :class:`SMTPHandler` instances send error messages to a designated email
+ address.
+
+#. :class:`SysLogHandler` instances send error messages to a Unix syslog daemon,
+ possibly on a remote machine.
+
+#. :class:`NTEventLogHandler` instances send error messages to a Windows
+ NT/2000/XP event log.
+
+#. :class:`MemoryHandler` instances send error messages to a buffer in memory,
+ which is flushed whenever specific criteria are met.
+
+#. :class:`HTTPHandler` instances send error messages to an HTTP server using
+ either ``GET`` or ``POST`` semantics.
+
+The :class:`StreamHandler` and :class:`FileHandler` classes are defined in the
+core logging package. The other handlers are defined in a sub- module,
+:mod:`logging.handlers`. (There is also another sub-module,
+:mod:`logging.config`, for configuration functionality.)
+
+Logged messages are formatted for presentation through instances of the
+:class:`Formatter` class. They are initialized with a format string suitable for
+use with the % operator and a dictionary.
+
+For formatting multiple messages in a batch, instances of
+:class:`BufferingFormatter` can be used. In addition to the format string (which
+is applied to each message in the batch), there is provision for header and
+trailer format strings.
+
+When filtering based on logger level and/or handler level is not enough,
+instances of :class:`Filter` can be added to both :class:`Logger` and
+:class:`Handler` instances (through their :meth:`addFilter` method). Before
+deciding to process a message further, both loggers and handlers consult all
+their filters for permission. If any filter returns a false value, the message
+is not processed further.
+
+The basic :class:`Filter` functionality allows filtering by specific logger
+name. If this feature is used, messages sent to the named logger and its
+children are allowed through the filter, and all others dropped.
+
+In addition to the classes described above, there are a number of module- level
+functions.
+
+
+.. function:: getLogger([name])
+
+ Return a logger with the specified name or, if no name is specified, return a
+ logger which is the root logger of the hierarchy. If specified, the name is
+ typically a dot-separated hierarchical name like *"a"*, *"a.b"* or *"a.b.c.d"*.
+ Choice of these names is entirely up to the developer who is using logging.
+
+ All calls to this function with a given name return the same logger instance.
+ This means that logger instances never need to be passed between different parts
+ of an application.
+
+
+.. function:: getLoggerClass()
+
+ Return either the standard :class:`Logger` class, or the last class passed to
+ :func:`setLoggerClass`. This function may be called from within a new class
+ definition, to ensure that installing a customised :class:`Logger` class will
+ not undo customisations already applied by other code. For example::
+
+ class MyLogger(logging.getLoggerClass()):
+ # ... override behaviour here
+
+
+.. function:: debug(msg[, *args[, **kwargs]])
+
+ Logs a message with level :const:`DEBUG` on the root logger. The *msg* is the
+ message format string, and the *args* are the arguments which are merged into
+ *msg* using the string formatting operator. (Note that this means that you can
+ use keywords in the format string, together with a single dictionary argument.)
+
+ There are two keyword arguments in *kwargs* which are inspected: *exc_info*
+ which, if it does not evaluate as false, causes exception information to be
+ added to the logging message. If an exception tuple (in the format returned by
+ :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info`
+ is called to get the exception information.
+
+ The other optional keyword argument is *extra* which can be used to pass a
+ dictionary which is used to populate the __dict__ of the LogRecord created for
+ the logging event with user-defined attributes. These custom attributes can then
+ be used as you like. For example, they could be incorporated into logged
+ messages. For example::
+
+ FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"
+ logging.basicConfig(format=FORMAT)
+ d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
+ logging.warning("Protocol problem: %s", "connection reset", extra=d)
+
+ would print something like ::
+
+ 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
+
+ The keys in the dictionary passed in *extra* should not clash with the keys used
+ by the logging system. (See the :class:`Formatter` documentation for more
+ information on which keys are used by the logging system.)
+
+ If you choose to use these attributes in logged messages, you need to exercise
+ some care. In the above example, for instance, the :class:`Formatter` has been
+ set up with a format string which expects 'clientip' and 'user' in the attribute
+ dictionary of the LogRecord. If these are missing, the message will not be
+ logged because a string formatting exception will occur. So in this case, you
+ always need to pass the *extra* dictionary with these keys.
+
+ While this might be annoying, this feature is intended for use in specialized
+ circumstances, such as multi-threaded servers where the same code executes in
+ many contexts, and interesting conditions which arise are dependent on this
+ context (such as remote client IP address and authenticated user name, in the
+ above example). In such circumstances, it is likely that specialized
+ :class:`Formatter`\ s would be used with particular :class:`Handler`\ s.
+
+ .. versionchanged:: 2.5
+ *extra* was added.
+
+
+.. function:: info(msg[, *args[, **kwargs]])
+
+ Logs a message with level :const:`INFO` on the root logger. The arguments are
+ interpreted as for :func:`debug`.
+
+
+.. function:: warning(msg[, *args[, **kwargs]])
+
+ Logs a message with level :const:`WARNING` on the root logger. The arguments are
+ interpreted as for :func:`debug`.
+
+
+.. function:: error(msg[, *args[, **kwargs]])
+
+ Logs a message with level :const:`ERROR` on the root logger. The arguments are
+ interpreted as for :func:`debug`.
+
+
+.. function:: critical(msg[, *args[, **kwargs]])
+
+ Logs a message with level :const:`CRITICAL` on the root logger. The arguments
+ are interpreted as for :func:`debug`.
+
+
+.. function:: exception(msg[, *args])
+
+ Logs a message with level :const:`ERROR` on the root logger. The arguments are
+ interpreted as for :func:`debug`. Exception info is added to the logging
+ message. This function should only be called from an exception handler.
+
+
+.. function:: log(level, msg[, *args[, **kwargs]])
+
+ Logs a message with level *level* on the root logger. The other arguments are
+ interpreted as for :func:`debug`.
+
+
+.. function:: disable(lvl)
+
+ Provides an overriding level *lvl* for all loggers which takes precedence over
+ the logger's own level. When the need arises to temporarily throttle logging
+ output down across the whole application, this function can be useful.
+
+
+.. function:: addLevelName(lvl, levelName)
+
+ Associates level *lvl* with text *levelName* in an internal dictionary, which is
+ used to map numeric levels to a textual representation, for example when a
+ :class:`Formatter` formats a message. This function can also be used to define
+ your own levels. The only constraints are that all levels used must be
+ registered using this function, levels should be positive integers and they
+ should increase in increasing order of severity.
+
+
+.. function:: getLevelName(lvl)
+
+ Returns the textual representation of logging level *lvl*. If the level is one
+ of the predefined levels :const:`CRITICAL`, :const:`ERROR`, :const:`WARNING`,
+ :const:`INFO` or :const:`DEBUG` then you get the corresponding string. If you
+ have associated levels with names using :func:`addLevelName` then the name you
+ have associated with *lvl* is returned. If a numeric value corresponding to one
+ of the defined levels is passed in, the corresponding string representation is
+ returned. Otherwise, the string "Level %s" % lvl is returned.
+
+
+.. function:: makeLogRecord(attrdict)
+
+ Creates and returns a new :class:`LogRecord` instance whose attributes are
+ defined by *attrdict*. This function is useful for taking a pickled
+ :class:`LogRecord` attribute dictionary, sent over a socket, and reconstituting
+ it as a :class:`LogRecord` instance at the receiving end.
+
+
+.. function:: basicConfig([**kwargs])
+
+ Does basic configuration for the logging system by creating a
+ :class:`StreamHandler` with a default :class:`Formatter` and adding it to the
+ root logger. The functions :func:`debug`, :func:`info`, :func:`warning`,
+ :func:`error` and :func:`critical` will call :func:`basicConfig` automatically
+ if no handlers are defined for the root logger.
+
+ .. versionchanged:: 2.4
+ Formerly, :func:`basicConfig` did not take any keyword arguments.
+
+ The following keyword arguments are supported.
+
+ +--------------+---------------------------------------------+
+ | Format | Description |
+ +==============+=============================================+
+ | ``filename`` | Specifies that a FileHandler be created, |
+ | | using the specified filename, rather than a |
+ | | StreamHandler. |
+ +--------------+---------------------------------------------+
+ | ``filemode`` | Specifies the mode to open the file, if |
+ | | filename is specified (if filemode is |
+ | | unspecified, it defaults to 'a'). |
+ +--------------+---------------------------------------------+
+ | ``format`` | Use the specified format string for the |
+ | | handler. |
+ +--------------+---------------------------------------------+
+ | ``datefmt`` | Use the specified date/time format. |
+ +--------------+---------------------------------------------+
+ | ``level`` | Set the root logger level to the specified |
+ | | level. |
+ +--------------+---------------------------------------------+
+ | ``stream`` | Use the specified stream to initialize the |
+ | | StreamHandler. Note that this argument is |
+ | | incompatible with 'filename' - if both are |
+ | | present, 'stream' is ignored. |
+ +--------------+---------------------------------------------+
+
+
+.. function:: shutdown()
+
+ Informs the logging system to perform an orderly shutdown by flushing and
+ closing all handlers.
+
+
+.. function:: setLoggerClass(klass)
+
+ Tells the logging system to use the class *klass* when instantiating a logger.
+ The class should define :meth:`__init__` such that only a name argument is
+ required, and the :meth:`__init__` should call :meth:`Logger.__init__`. This
+ function is typically called before any loggers are instantiated by applications
+ which need to use custom logger behavior.
+
+
+.. seealso::
+
+ :pep:`282` - A Logging System
+ The proposal which described this feature for inclusion in the Python standard
+ library.
+
+ `Original Python :mod:`logging` package <http://www.red-dove.com/python_logging.html>`_
+ This is the original source for the :mod:`logging` package. The version of the
+ package available from this site is suitable for use with Python 1.5.2, 2.1.x
+ and 2.2.x, which do not include the :mod:`logging` package in the standard
+ library.
+
+
+Logger Objects
+--------------
+
+Loggers have the following attributes and methods. Note that Loggers are never
+instantiated directly, but always through the module-level function
+``logging.getLogger(name)``.
+
+
+.. attribute:: Logger.propagate
+
+ If this evaluates to false, logging messages are not passed by this logger or by
+ child loggers to higher level (ancestor) loggers. The constructor sets this
+ attribute to 1.
+
+
+.. method:: Logger.setLevel(lvl)
+
+ Sets the threshold for this logger to *lvl*. Logging messages which are less
+ severe than *lvl* will be ignored. When a logger is created, the level is set to
+ :const:`NOTSET` (which causes all messages to be processed when the logger is
+ the root logger, or delegation to the parent when the logger is a non-root
+ logger). Note that the root logger is created with level :const:`WARNING`.
+
+ The term "delegation to the parent" means that if a logger has a level of
+ NOTSET, its chain of ancestor loggers is traversed until either an ancestor with
+ a level other than NOTSET is found, or the root is reached.
+
+ If an ancestor is found with a level other than NOTSET, then that ancestor's
+ level is treated as the effective level of the logger where the ancestor search
+ began, and is used to determine how a logging event is handled.
+
+ If the root is reached, and it has a level of NOTSET, then all messages will be
+ processed. Otherwise, the root's level will be used as the effective level.
+
+
+.. method:: Logger.isEnabledFor(lvl)
+
+ Indicates if a message of severity *lvl* would be processed by this logger.
+ This method checks first the module-level level set by
+ ``logging.disable(lvl)`` and then the logger's effective level as determined
+ by :meth:`getEffectiveLevel`.
+
+
+.. method:: Logger.getEffectiveLevel()
+
+ Indicates the effective level for this logger. If a value other than
+ :const:`NOTSET` has been set using :meth:`setLevel`, it is returned. Otherwise,
+ the hierarchy is traversed towards the root until a value other than
+ :const:`NOTSET` is found, and that value is returned.
+
+
+.. method:: Logger.debug(msg[, *args[, **kwargs]])
+
+ Logs a message with level :const:`DEBUG` on this logger. The *msg* is the
+ message format string, and the *args* are the arguments which are merged into
+ *msg* using the string formatting operator. (Note that this means that you can
+ use keywords in the format string, together with a single dictionary argument.)
+
+ There are two keyword arguments in *kwargs* which are inspected: *exc_info*
+ which, if it does not evaluate as false, causes exception information to be
+ added to the logging message. If an exception tuple (in the format returned by
+ :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info`
+ is called to get the exception information.
+
+ The other optional keyword argument is *extra* which can be used to pass a
+ dictionary which is used to populate the __dict__ of the LogRecord created for
+ the logging event with user-defined attributes. These custom attributes can then
+ be used as you like. For example, they could be incorporated into logged
+ messages. For example::
+
+ FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"
+ logging.basicConfig(format=FORMAT)
+ dict = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' }
+ logger = logging.getLogger("tcpserver")
+ logger.warning("Protocol problem: %s", "connection reset", extra=d)
+
+ would print something like ::
+
+ 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
+
+ The keys in the dictionary passed in *extra* should not clash with the keys used
+ by the logging system. (See the :class:`Formatter` documentation for more
+ information on which keys are used by the logging system.)
+
+ If you choose to use these attributes in logged messages, you need to exercise
+ some care. In the above example, for instance, the :class:`Formatter` has been
+ set up with a format string which expects 'clientip' and 'user' in the attribute
+ dictionary of the LogRecord. If these are missing, the message will not be
+ logged because a string formatting exception will occur. So in this case, you
+ always need to pass the *extra* dictionary with these keys.
+
+ While this might be annoying, this feature is intended for use in specialized
+ circumstances, such as multi-threaded servers where the same code executes in
+ many contexts, and interesting conditions which arise are dependent on this
+ context (such as remote client IP address and authenticated user name, in the
+ above example). In such circumstances, it is likely that specialized
+ :class:`Formatter`\ s would be used with particular :class:`Handler`\ s.
+
+ .. versionchanged:: 2.5
+ *extra* was added.
+
+
+.. method:: Logger.info(msg[, *args[, **kwargs]])
+
+ Logs a message with level :const:`INFO` on this logger. The arguments are
+ interpreted as for :meth:`debug`.
+
+
+.. method:: Logger.warning(msg[, *args[, **kwargs]])
+
+ Logs a message with level :const:`WARNING` on this logger. The arguments are
+ interpreted as for :meth:`debug`.
+
+
+.. method:: Logger.error(msg[, *args[, **kwargs]])
+
+ Logs a message with level :const:`ERROR` on this logger. The arguments are
+ interpreted as for :meth:`debug`.
+
+
+.. method:: Logger.critical(msg[, *args[, **kwargs]])
+
+ Logs a message with level :const:`CRITICAL` on this logger. The arguments are
+ interpreted as for :meth:`debug`.
+
+
+.. method:: Logger.log(lvl, msg[, *args[, **kwargs]])
+
+ Logs a message with integer level *lvl* on this logger. The other arguments are
+ interpreted as for :meth:`debug`.
+
+
+.. method:: Logger.exception(msg[, *args])
+
+ Logs a message with level :const:`ERROR` on this logger. The arguments are
+ interpreted as for :meth:`debug`. Exception info is added to the logging
+ message. This method should only be called from an exception handler.
+
+
+.. method:: Logger.addFilter(filt)
+
+ Adds the specified filter *filt* to this logger.
+
+
+.. method:: Logger.removeFilter(filt)
+
+ Removes the specified filter *filt* from this logger.
+
+
+.. method:: Logger.filter(record)
+
+ Applies this logger's filters to the record and returns a true value if the
+ record is to be processed.
+
+
+.. method:: Logger.addHandler(hdlr)
+
+ Adds the specified handler *hdlr* to this logger.
+
+
+.. method:: Logger.removeHandler(hdlr)
+
+ Removes the specified handler *hdlr* from this logger.
+
+
+.. method:: Logger.findCaller()
+
+ Finds the caller's source filename and line number. Returns the filename, line
+ number and function name as a 3-element tuple.
+
+ .. versionchanged:: 2.5
+ The function name was added. In earlier versions, the filename and line number
+ were returned as a 2-element tuple..
+
+
+.. method:: Logger.handle(record)
+
+ Handles a record by passing it to all handlers associated with this logger and
+ its ancestors (until a false value of *propagate* is found). This method is used
+ for unpickled records received from a socket, as well as those created locally.
+ Logger-level filtering is applied using :meth:`filter`.
+
+
+.. method:: Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info [, func, extra])
+
+ This is a factory method which can be overridden in subclasses to create
+ specialized :class:`LogRecord` instances.
+
+ .. versionchanged:: 2.5
+ *func* and *extra* were added.
+
+
+.. _minimal-example:
+
+Basic example
+-------------
+
+.. versionchanged:: 2.4
+ formerly :func:`basicConfig` did not take any keyword arguments.
+
+The :mod:`logging` package provides a lot of flexibility, and its configuration
+can appear daunting. This section demonstrates that simple use of the logging
+package is possible.
+
+The simplest example shows logging to the console::
+
+ import logging
+
+ logging.debug('A debug message')
+ logging.info('Some information')
+ logging.warning('A shot across the bows')
+
+If you run the above script, you'll see this::
+
+ WARNING:root:A shot across the bows
+
+Because no particular logger was specified, the system used the root logger. The
+debug and info messages didn't appear because by default, the root logger is
+configured to only handle messages with a severity of WARNING or above. The
+message format is also a configuration default, as is the output destination of
+the messages - ``sys.stderr``. The severity level, the message format and
+destination can be easily changed, as shown in the example below::
+
+ import logging
+
+ logging.basicConfig(level=logging.DEBUG,
+ format='%(asctime)s %(levelname)s %(message)s',
+ filename='/tmp/myapp.log',
+ filemode='w')
+ logging.debug('A debug message')
+ logging.info('Some information')
+ logging.warning('A shot across the bows')
+
+The :meth:`basicConfig` method is used to change the configuration defaults,
+which results in output (written to ``/tmp/myapp.log``) which should look
+something like the following::
+
+ 2004-07-02 13:00:08,743 DEBUG A debug message
+ 2004-07-02 13:00:08,743 INFO Some information
+ 2004-07-02 13:00:08,743 WARNING A shot across the bows
+
+This time, all messages with a severity of DEBUG or above were handled, and the
+format of the messages was also changed, and output went to the specified file
+rather than the console.
+
+Formatting uses standard Python string formatting - see section
+:ref:`string-formatting`. The format string takes the following common
+specifiers. For a complete list of specifiers, consult the :class:`Formatter`
+documentation.
+
++-------------------+-----------------------------------------------+
+| Format | Description |
++===================+===============================================+
+| ``%(name)s`` | Name of the logger (logging channel). |
++-------------------+-----------------------------------------------+
+| ``%(levelname)s`` | Text logging level for the message |
+| | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``, |
+| | ``'ERROR'``, ``'CRITICAL'``). |
++-------------------+-----------------------------------------------+
+| ``%(asctime)s`` | Human-readable time when the |
+| | :class:`LogRecord` was created. By default |
+| | this is of the form "2003-07-08 16:49:45,896" |
+| | (the numbers after the comma are millisecond |
+| | portion of the time). |
++-------------------+-----------------------------------------------+
+| ``%(message)s`` | The logged message. |
++-------------------+-----------------------------------------------+
+
+To change the date/time format, you can pass an additional keyword parameter,
+*datefmt*, as in the following::
+
+ import logging
+
+ logging.basicConfig(level=logging.DEBUG,
+ format='%(asctime)s %(levelname)-8s %(message)s',
+ datefmt='%a, %d %b %Y %H:%M:%S',
+ filename='/temp/myapp.log',
+ filemode='w')
+ logging.debug('A debug message')
+ logging.info('Some information')
+ logging.warning('A shot across the bows')
+
+which would result in output like ::
+
+ Fri, 02 Jul 2004 13:06:18 DEBUG A debug message
+ Fri, 02 Jul 2004 13:06:18 INFO Some information
+ Fri, 02 Jul 2004 13:06:18 WARNING A shot across the bows
+
+The date format string follows the requirements of :func:`strftime` - see the
+documentation for the :mod:`time` module.
+
+If, instead of sending logging output to the console or a file, you'd rather use
+a file-like object which you have created separately, you can pass it to
+:func:`basicConfig` using the *stream* keyword argument. Note that if both
+*stream* and *filename* keyword arguments are passed, the *stream* argument is
+ignored.
+
+Of course, you can put variable information in your output. To do this, simply
+have the message be a format string and pass in additional arguments containing
+the variable information, as in the following example::
+
+ import logging
+
+ logging.basicConfig(level=logging.DEBUG,
+ format='%(asctime)s %(levelname)-8s %(message)s',
+ datefmt='%a, %d %b %Y %H:%M:%S',
+ filename='/temp/myapp.log',
+ filemode='w')
+ logging.error('Pack my box with %d dozen %s', 5, 'liquor jugs')
+
+which would result in ::
+
+ Wed, 21 Jul 2004 15:35:16 ERROR Pack my box with 5 dozen liquor jugs
+
+
+.. _multiple-destinations:
+
+Logging to multiple destinations
+--------------------------------
+
+Let's say you want to log to console and file with different message formats and
+in differing circumstances. Say you want to log messages with levels of DEBUG
+and higher to file, and those messages at level INFO and higher to the console.
+Let's also assume that the file should contain timestamps, but the console
+messages should not. Here's how you can achieve this::
+
+ import logging
+
+ # set up logging to file - see previous section for more details
+ logging.basicConfig(level=logging.DEBUG,
+ format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',
+ datefmt='%m-%d %H:%M',
+ filename='/temp/myapp.log',
+ filemode='w')
+ # define a Handler which writes INFO messages or higher to the sys.stderr
+ console = logging.StreamHandler()
+ console.setLevel(logging.INFO)
+ # set a format which is simpler for console use
+ formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')
+ # tell the handler to use this format
+ console.setFormatter(formatter)
+ # add the handler to the root logger
+ logging.getLogger('').addHandler(console)
+
+ # Now, we can log to the root logger, or any other logger. First the root...
+ logging.info('Jackdaws love my big sphinx of quartz.')
+
+ # Now, define a couple of other loggers which might represent areas in your
+ # application:
+
+ logger1 = logging.getLogger('myapp.area1')
+ logger2 = logging.getLogger('myapp.area2')
+
+ logger1.debug('Quick zephyrs blow, vexing daft Jim.')
+ logger1.info('How quickly daft jumping zebras vex.')
+ logger2.warning('Jail zesty vixen who grabbed pay from quack.')
+ logger2.error('The five boxing wizards jump quickly.')
+
+When you run this, on the console you will see ::
+
+ root : INFO Jackdaws love my big sphinx of quartz.
+ myapp.area1 : INFO How quickly daft jumping zebras vex.
+ myapp.area2 : WARNING Jail zesty vixen who grabbed pay from quack.
+ myapp.area2 : ERROR The five boxing wizards jump quickly.
+
+and in the file you will see something like ::
+
+ 10-22 22:19 root INFO Jackdaws love my big sphinx of quartz.
+ 10-22 22:19 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.
+ 10-22 22:19 myapp.area1 INFO How quickly daft jumping zebras vex.
+ 10-22 22:19 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
+ 10-22 22:19 myapp.area2 ERROR The five boxing wizards jump quickly.
+
+As you can see, the DEBUG message only shows up in the file. The other messages
+are sent to both destinations.
+
+This example uses console and file handlers, but you can use any number and
+combination of handlers you choose.
+
+
+.. _network-logging:
+
+Sending and receiving logging events across a network
+-----------------------------------------------------
+
+Let's say you want to send logging events across a network, and handle them at
+the receiving end. A simple way of doing this is attaching a
+:class:`SocketHandler` instance to the root logger at the sending end::
+
+ import logging, logging.handlers
+
+ rootLogger = logging.getLogger('')
+ rootLogger.setLevel(logging.DEBUG)
+ socketHandler = logging.handlers.SocketHandler('localhost',
+ logging.handlers.DEFAULT_TCP_LOGGING_PORT)
+ # don't bother with a formatter, since a socket handler sends the event as
+ # an unformatted pickle
+ rootLogger.addHandler(socketHandler)
+
+ # Now, we can log to the root logger, or any other logger. First the root...
+ logging.info('Jackdaws love my big sphinx of quartz.')
+
+ # Now, define a couple of other loggers which might represent areas in your
+ # application:
+
+ logger1 = logging.getLogger('myapp.area1')
+ logger2 = logging.getLogger('myapp.area2')
+
+ logger1.debug('Quick zephyrs blow, vexing daft Jim.')
+ logger1.info('How quickly daft jumping zebras vex.')
+ logger2.warning('Jail zesty vixen who grabbed pay from quack.')
+ logger2.error('The five boxing wizards jump quickly.')
+
+At the receiving end, you can set up a receiver using the :mod:`SocketServer`
+module. Here is a basic working example::
+
+ import cPickle
+ import logging
+ import logging.handlers
+ import SocketServer
+ import struct
+
+
+ class LogRecordStreamHandler(SocketServer.StreamRequestHandler):
+ """Handler for a streaming logging request.
+
+ This basically logs the record using whatever logging policy is
+ configured locally.
+ """
+
+ def handle(self):
+ """
+ Handle multiple requests - each expected to be a 4-byte length,
+ followed by the LogRecord in pickle format. Logs the record
+ according to whatever policy is configured locally.
+ """
+ while 1:
+ chunk = self.connection.recv(4)
+ if len(chunk) < 4:
+ break
+ slen = struct.unpack(">L", chunk)[0]
+ chunk = self.connection.recv(slen)
+ while len(chunk) < slen:
+ chunk = chunk + self.connection.recv(slen - len(chunk))
+ obj = self.unPickle(chunk)
+ record = logging.makeLogRecord(obj)
+ self.handleLogRecord(record)
+
+ def unPickle(self, data):
+ return cPickle.loads(data)
+
+ def handleLogRecord(self, record):
+ # if a name is specified, we use the named logger rather than the one
+ # implied by the record.
+ if self.server.logname is not None:
+ name = self.server.logname
+ else:
+ name = record.name
+ logger = logging.getLogger(name)
+ # N.B. EVERY record gets logged. This is because Logger.handle
+ # is normally called AFTER logger-level filtering. If you want
+ # to do filtering, do it at the client end to save wasting
+ # cycles and network bandwidth!
+ logger.handle(record)
+
+ class LogRecordSocketReceiver(SocketServer.ThreadingTCPServer):
+ """simple TCP socket-based logging receiver suitable for testing.
+ """
+
+ allow_reuse_address = 1
+
+ def __init__(self, host='localhost',
+ port=logging.handlers.DEFAULT_TCP_LOGGING_PORT,
+ handler=LogRecordStreamHandler):
+ SocketServer.ThreadingTCPServer.__init__(self, (host, port), handler)
+ self.abort = 0
+ self.timeout = 1
+ self.logname = None
+
+ def serve_until_stopped(self):
+ import select
+ abort = 0
+ while not abort:
+ rd, wr, ex = select.select([self.socket.fileno()],
+ [], [],
+ self.timeout)
+ if rd:
+ self.handle_request()
+ abort = self.abort
+
+ def main():
+ logging.basicConfig(
+ format="%(relativeCreated)5d %(name)-15s %(levelname)-8s %(message)s")
+ tcpserver = LogRecordSocketReceiver()
+ print "About to start TCP server..."
+ tcpserver.serve_until_stopped()
+
+ if __name__ == "__main__":
+ main()
+
+First run the server, and then the client. On the client side, nothing is
+printed on the console; on the server side, you should see something like::
+
+ About to start TCP server...
+ 59 root INFO Jackdaws love my big sphinx of quartz.
+ 59 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.
+ 69 myapp.area1 INFO How quickly daft jumping zebras vex.
+ 69 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
+ 69 myapp.area2 ERROR The five boxing wizards jump quickly.
+
+
+Handler Objects
+---------------
+
+Handlers have the following attributes and methods. Note that :class:`Handler`
+is never instantiated directly; this class acts as a base for more useful
+subclasses. However, the :meth:`__init__` method in subclasses needs to call
+:meth:`Handler.__init__`.
+
+
+.. method:: Handler.__init__(level=NOTSET)
+
+ Initializes the :class:`Handler` instance by setting its level, setting the list
+ of filters to the empty list and creating a lock (using :meth:`createLock`) for
+ serializing access to an I/O mechanism.
+
+
+.. method:: Handler.createLock()
+
+ Initializes a thread lock which can be used to serialize access to underlying
+ I/O functionality which may not be threadsafe.
+
+
+.. method:: Handler.acquire()
+
+ Acquires the thread lock created with :meth:`createLock`.
+
+
+.. method:: Handler.release()
+
+ Releases the thread lock acquired with :meth:`acquire`.
+
+
+.. method:: Handler.setLevel(lvl)
+
+ Sets the threshold for this handler to *lvl*. Logging messages which are less
+ severe than *lvl* will be ignored. When a handler is created, the level is set
+ to :const:`NOTSET` (which causes all messages to be processed).
+
+
+.. method:: Handler.setFormatter(form)
+
+ Sets the :class:`Formatter` for this handler to *form*.
+
+
+.. method:: Handler.addFilter(filt)
+
+ Adds the specified filter *filt* to this handler.
+
+
+.. method:: Handler.removeFilter(filt)
+
+ Removes the specified filter *filt* from this handler.
+
+
+.. method:: Handler.filter(record)
+
+ Applies this handler's filters to the record and returns a true value if the
+ record is to be processed.
+
+
+.. method:: Handler.flush()
+
+ Ensure all logging output has been flushed. This version does nothing and is
+ intended to be implemented by subclasses.
+
+
+.. method:: Handler.close()
+
+ Tidy up any resources used by the handler. This version does nothing and is
+ intended to be implemented by subclasses.
+
+
+.. method:: Handler.handle(record)
+
+ Conditionally emits the specified logging record, depending on filters which may
+ have been added to the handler. Wraps the actual emission of the record with
+ acquisition/release of the I/O thread lock.
+
+
+.. method:: Handler.handleError(record)
+
+ This method should be called from handlers when an exception is encountered
+ during an :meth:`emit` call. By default it does nothing, which means that
+ exceptions get silently ignored. This is what is mostly wanted for a logging
+ system - most users will not care about errors in the logging system, they are
+ more interested in application errors. You could, however, replace this with a
+ custom handler if you wish. The specified record is the one which was being
+ processed when the exception occurred.
+
+
+.. method:: Handler.format(record)
+
+ Do formatting for a record - if a formatter is set, use it. Otherwise, use the
+ default formatter for the module.
+
+
+.. method:: Handler.emit(record)
+
+ Do whatever it takes to actually log the specified logging record. This version
+ is intended to be implemented by subclasses and so raises a
+ :exc:`NotImplementedError`.
+
+
+StreamHandler
+^^^^^^^^^^^^^
+
+The :class:`StreamHandler` class, located in the core :mod:`logging` package,
+sends logging output to streams such as *sys.stdout*, *sys.stderr* or any
+file-like object (or, more precisely, any object which supports :meth:`write`
+and :meth:`flush` methods).
+
+
+.. class:: StreamHandler([strm])
+
+ Returns a new instance of the :class:`StreamHandler` class. If *strm* is
+ specified, the instance will use it for logging output; otherwise, *sys.stderr*
+ will be used.
+
+
+.. method:: StreamHandler.emit(record)
+
+ If a formatter is specified, it is used to format the record. The record is then
+ written to the stream with a trailing newline. If exception information is
+ present, it is formatted using :func:`traceback.print_exception` and appended to
+ the stream.
+
+
+.. method:: StreamHandler.flush()
+
+ Flushes the stream by calling its :meth:`flush` method. Note that the
+ :meth:`close` method is inherited from :class:`Handler` and so does nothing, so
+ an explicit :meth:`flush` call may be needed at times.
+
+
+FileHandler
+^^^^^^^^^^^
+
+The :class:`FileHandler` class, located in the core :mod:`logging` package,
+sends logging output to a disk file. It inherits the output functionality from
+:class:`StreamHandler`.
+
+
+.. class:: FileHandler(filename[, mode[, encoding]])
+
+ Returns a new instance of the :class:`FileHandler` class. The specified file is
+ opened and used as the stream for logging. If *mode* is not specified,
+ :const:`'a'` is used. If *encoding* is not *None*, it is used to open the file
+ with that encoding. By default, the file grows indefinitely.
+
+
+.. method:: FileHandler.close()
+
+ Closes the file.
+
+
+.. method:: FileHandler.emit(record)
+
+ Outputs the record to the file.
+
+
+WatchedFileHandler
+^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 2.6
+
+The :class:`WatchedFileHandler` class, located in the :mod:`logging.handlers`
+module, is a :class:`FileHandler` which watches the file it is logging to. If
+the file changes, it is closed and reopened using the file name.
+
+A file change can happen because of usage of programs such as *newsyslog* and
+*logrotate* which perform log file rotation. This handler, intended for use
+under Unix/Linux, watches the file to see if it has changed since the last emit.
+(A file is deemed to have changed if its device or inode have changed.) If the
+file has changed, the old file stream is closed, and the file opened to get a
+new stream.
+
+This handler is not appropriate for use under Windows, because under Windows
+open log files cannot be moved or renamed - logging opens the files with
+exclusive locks - and so there is no need for such a handler. Furthermore,
+*ST_INO* is not supported under Windows; :func:`stat` always returns zero for
+this value.
+
+
+.. class:: WatchedFileHandler(filename[,mode[, encoding]])
+
+ Returns a new instance of the :class:`WatchedFileHandler` class. The specified
+ file is opened and used as the stream for logging. If *mode* is not specified,
+ :const:`'a'` is used. If *encoding* is not *None*, it is used to open the file
+ with that encoding. By default, the file grows indefinitely.
+
+
+.. method:: WatchedFileHandler.emit(record)
+
+ Outputs the record to the file, but first checks to see if the file has changed.
+ If it has, the existing stream is flushed and closed and the file opened again,
+ before outputting the record to the file.
+
+
+RotatingFileHandler
+^^^^^^^^^^^^^^^^^^^
+
+The :class:`RotatingFileHandler` class, located in the :mod:`logging.handlers`
+module, supports rotation of disk log files.
+
+
+.. class:: RotatingFileHandler(filename[, mode[, maxBytes[, backupCount]]])
+
+ Returns a new instance of the :class:`RotatingFileHandler` class. The specified
+ file is opened and used as the stream for logging. If *mode* is not specified,
+ ``'a'`` is used. By default, the file grows indefinitely.
+
+ You can use the *maxBytes* and *backupCount* values to allow the file to
+ :dfn:`rollover` at a predetermined size. When the size is about to be exceeded,
+ the file is closed and a new file is silently opened for output. Rollover occurs
+ whenever the current log file is nearly *maxBytes* in length; if *maxBytes* is
+ zero, rollover never occurs. If *backupCount* is non-zero, the system will save
+ old log files by appending the extensions ".1", ".2" etc., to the filename. For
+ example, with a *backupCount* of 5 and a base file name of :file:`app.log`, you
+ would get :file:`app.log`, :file:`app.log.1`, :file:`app.log.2`, up to
+ :file:`app.log.5`. The file being written to is always :file:`app.log`. When
+ this file is filled, it is closed and renamed to :file:`app.log.1`, and if files
+ :file:`app.log.1`, :file:`app.log.2`, etc. exist, then they are renamed to
+ :file:`app.log.2`, :file:`app.log.3` etc. respectively.
+
+
+.. method:: RotatingFileHandler.doRollover()
+
+ Does a rollover, as described above.
+
+
+.. method:: RotatingFileHandler.emit(record)
+
+ Outputs the record to the file, catering for rollover as described previously.
+
+
+TimedRotatingFileHandler
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :class:`TimedRotatingFileHandler` class, located in the
+:mod:`logging.handlers` module, supports rotation of disk log files at certain
+timed intervals.
+
+
+.. class:: TimedRotatingFileHandler(filename [,when [,interval [,backupCount]]])
+
+ Returns a new instance of the :class:`TimedRotatingFileHandler` class. The
+ specified file is opened and used as the stream for logging. On rotating it also
+ sets the filename suffix. Rotating happens based on the product of *when* and
+ *interval*.
+
+ You can use the *when* to specify the type of *interval*. The list of possible
+ values is, note that they are not case sensitive:
+
+ +----------+-----------------------+
+ | Value | Type of interval |
+ +==========+=======================+
+ | S | Seconds |
+ +----------+-----------------------+
+ | M | Minutes |
+ +----------+-----------------------+
+ | H | Hours |
+ +----------+-----------------------+
+ | D | Days |
+ +----------+-----------------------+
+ | W | Week day (0=Monday) |
+ +----------+-----------------------+
+ | midnight | Roll over at midnight |
+ +----------+-----------------------+
+
+ If *backupCount* is non-zero, the system will save old log files by appending
+ extensions to the filename. The extensions are date-and-time based, using the
+ strftime format ``%Y-%m-%d_%H-%M-%S`` or a leading portion thereof, depending on
+ the rollover interval. At most *backupCount* files will be kept, and if more
+ would be created when rollover occurs, the oldest one is deleted.
+
+
+.. method:: TimedRotatingFileHandler.doRollover()
+
+ Does a rollover, as described above.
+
+
+.. method:: TimedRotatingFileHandler.emit(record)
+
+ Outputs the record to the file, catering for rollover as described above.
+
+
+SocketHandler
+^^^^^^^^^^^^^
+
+The :class:`SocketHandler` class, located in the :mod:`logging.handlers` module,
+sends logging output to a network socket. The base class uses a TCP socket.
+
+
+.. class:: SocketHandler(host, port)
+
+ Returns a new instance of the :class:`SocketHandler` class intended to
+ communicate with a remote machine whose address is given by *host* and *port*.
+
+
+.. method:: SocketHandler.close()
+
+ Closes the socket.
+
+
+.. method:: SocketHandler.emit()
+
+ Pickles the record's attribute dictionary and writes it to the socket in binary
+ format. If there is an error with the socket, silently drops the packet. If the
+ connection was previously lost, re-establishes the connection. To unpickle the
+ record at the receiving end into a :class:`LogRecord`, use the
+ :func:`makeLogRecord` function.
+
+
+.. method:: SocketHandler.handleError()
+
+ Handles an error which has occurred during :meth:`emit`. The most likely cause
+ is a lost connection. Closes the socket so that we can retry on the next event.
+
+
+.. method:: SocketHandler.makeSocket()
+
+ This is a factory method which allows subclasses to define the precise type of
+ socket they want. The default implementation creates a TCP socket
+ (:const:`socket.SOCK_STREAM`).
+
+
+.. method:: SocketHandler.makePickle(record)
+
+ Pickles the record's attribute dictionary in binary format with a length prefix,
+ and returns it ready for transmission across the socket.
+
+
+.. method:: SocketHandler.send(packet)
+
+ Send a pickled string *packet* to the socket. This function allows for partial
+ sends which can happen when the network is busy.
+
+
+DatagramHandler
+^^^^^^^^^^^^^^^
+
+The :class:`DatagramHandler` class, located in the :mod:`logging.handlers`
+module, inherits from :class:`SocketHandler` to support sending logging messages
+over UDP sockets.
+
+
+.. class:: DatagramHandler(host, port)
+
+ Returns a new instance of the :class:`DatagramHandler` class intended to
+ communicate with a remote machine whose address is given by *host* and *port*.
+
+
+.. method:: DatagramHandler.emit()
+
+ Pickles the record's attribute dictionary and writes it to the socket in binary
+ format. If there is an error with the socket, silently drops the packet. To
+ unpickle the record at the receiving end into a :class:`LogRecord`, use the
+ :func:`makeLogRecord` function.
+
+
+.. method:: DatagramHandler.makeSocket()
+
+ The factory method of :class:`SocketHandler` is here overridden to create a UDP
+ socket (:const:`socket.SOCK_DGRAM`).
+
+
+.. method:: DatagramHandler.send(s)
+
+ Send a pickled string to a socket.
+
+
+SysLogHandler
+^^^^^^^^^^^^^
+
+The :class:`SysLogHandler` class, located in the :mod:`logging.handlers` module,
+supports sending logging messages to a remote or local Unix syslog.
+
+
+.. class:: SysLogHandler([address[, facility]])
+
+ Returns a new instance of the :class:`SysLogHandler` class intended to
+ communicate with a remote Unix machine whose address is given by *address* in
+ the form of a ``(host, port)`` tuple. If *address* is not specified,
+ ``('localhost', 514)`` is used. The address is used to open a UDP socket. An
+ alternative to providing a ``(host, port)`` tuple is providing an address as a
+ string, for example "/dev/log". In this case, a Unix domain socket is used to
+ send the message to the syslog. If *facility* is not specified,
+ :const:`LOG_USER` is used.
+
+
+.. method:: SysLogHandler.close()
+
+ Closes the socket to the remote host.
+
+
+.. method:: SysLogHandler.emit(record)
+
+ The record is formatted, and then sent to the syslog server. If exception
+ information is present, it is *not* sent to the server.
+
+
+.. method:: SysLogHandler.encodePriority(facility, priority)
+
+ Encodes the facility and priority into an integer. You can pass in strings or
+ integers - if strings are passed, internal mapping dictionaries are used to
+ convert them to integers.
+
+
+NTEventLogHandler
+^^^^^^^^^^^^^^^^^
+
+The :class:`NTEventLogHandler` class, located in the :mod:`logging.handlers`
+module, supports sending logging messages to a local Windows NT, Windows 2000 or
+Windows XP event log. Before you can use it, you need Mark Hammond's Win32
+extensions for Python installed.
+
+
+.. class:: NTEventLogHandler(appname[, dllname[, logtype]])
+
+ Returns a new instance of the :class:`NTEventLogHandler` class. The *appname* is
+ used to define the application name as it appears in the event log. An
+ appropriate registry entry is created using this name. The *dllname* should give
+ the fully qualified pathname of a .dll or .exe which contains message
+ definitions to hold in the log (if not specified, ``'win32service.pyd'`` is used
+ - this is installed with the Win32 extensions and contains some basic
+ placeholder message definitions. Note that use of these placeholders will make
+ your event logs big, as the entire message source is held in the log. If you
+ want slimmer logs, you have to pass in the name of your own .dll or .exe which
+ contains the message definitions you want to use in the event log). The
+ *logtype* is one of ``'Application'``, ``'System'`` or ``'Security'``, and
+ defaults to ``'Application'``.
+
+
+.. method:: NTEventLogHandler.close()
+
+ At this point, you can remove the application name from the registry as a source
+ of event log entries. However, if you do this, you will not be able to see the
+ events as you intended in the Event Log Viewer - it needs to be able to access
+ the registry to get the .dll name. The current version does not do this (in fact
+ it doesn't do anything).
+
+
+.. method:: NTEventLogHandler.emit(record)
+
+ Determines the message ID, event category and event type, and then logs the
+ message in the NT event log.
+
+
+.. method:: NTEventLogHandler.getEventCategory(record)
+
+ Returns the event category for the record. Override this if you want to specify
+ your own categories. This version returns 0.
+
+
+.. method:: NTEventLogHandler.getEventType(record)
+
+ Returns the event type for the record. Override this if you want to specify your
+ own types. This version does a mapping using the handler's typemap attribute,
+ which is set up in :meth:`__init__` to a dictionary which contains mappings for
+ :const:`DEBUG`, :const:`INFO`, :const:`WARNING`, :const:`ERROR` and
+ :const:`CRITICAL`. If you are using your own levels, you will either need to
+ override this method or place a suitable dictionary in the handler's *typemap*
+ attribute.
+
+
+.. method:: NTEventLogHandler.getMessageID(record)
+
+ Returns the message ID for the record. If you are using your own messages, you
+ could do this by having the *msg* passed to the logger being an ID rather than a
+ format string. Then, in here, you could use a dictionary lookup to get the
+ message ID. This version returns 1, which is the base message ID in
+ :file:`win32service.pyd`.
+
+
+SMTPHandler
+^^^^^^^^^^^
+
+The :class:`SMTPHandler` class, located in the :mod:`logging.handlers` module,
+supports sending logging messages to an email address via SMTP.
+
+
+.. class:: SMTPHandler(mailhost, fromaddr, toaddrs, subject[, credentials])
+
+ Returns a new instance of the :class:`SMTPHandler` class. The instance is
+ initialized with the from and to addresses and subject line of the email. The
+ *toaddrs* should be a list of strings. To specify a non-standard SMTP port, use
+ the (host, port) tuple format for the *mailhost* argument. If you use a string,
+ the standard SMTP port is used. If your SMTP server requires authentication, you
+ can specify a (username, password) tuple for the *credentials* argument.
+
+ .. versionchanged:: 2.6
+ *credentials* was added.
+
+
+.. method:: SMTPHandler.emit(record)
+
+ Formats the record and sends it to the specified addressees.
+
+
+.. method:: SMTPHandler.getSubject(record)
+
+ If you want to specify a subject line which is record-dependent, override this
+ method.
+
+
+MemoryHandler
+^^^^^^^^^^^^^
+
+The :class:`MemoryHandler` class, located in the :mod:`logging.handlers` module,
+supports buffering of logging records in memory, periodically flushing them to a
+:dfn:`target` handler. Flushing occurs whenever the buffer is full, or when an
+event of a certain severity or greater is seen.
+
+:class:`MemoryHandler` is a subclass of the more general
+:class:`BufferingHandler`, which is an abstract class. This buffers logging
+records in memory. Whenever each record is added to the buffer, a check is made
+by calling :meth:`shouldFlush` to see if the buffer should be flushed. If it
+should, then :meth:`flush` is expected to do the needful.
+
+
+.. class:: BufferingHandler(capacity)
+
+ Initializes the handler with a buffer of the specified capacity.
+
+
+.. method:: BufferingHandler.emit(record)
+
+ Appends the record to the buffer. If :meth:`shouldFlush` returns true, calls
+ :meth:`flush` to process the buffer.
+
+
+.. method:: BufferingHandler.flush()
+
+ You can override this to implement custom flushing behavior. This version just
+ zaps the buffer to empty.
+
+
+.. method:: BufferingHandler.shouldFlush(record)
+
+ Returns true if the buffer is up to capacity. This method can be overridden to
+ implement custom flushing strategies.
+
+
+.. class:: MemoryHandler(capacity[, flushLevel [, target]])
+
+ Returns a new instance of the :class:`MemoryHandler` class. The instance is
+ initialized with a buffer size of *capacity*. If *flushLevel* is not specified,
+ :const:`ERROR` is used. If no *target* is specified, the target will need to be
+ set using :meth:`setTarget` before this handler does anything useful.
+
+
+.. method:: MemoryHandler.close()
+
+ Calls :meth:`flush`, sets the target to :const:`None` and clears the buffer.
+
+
+.. method:: MemoryHandler.flush()
+
+ For a :class:`MemoryHandler`, flushing means just sending the buffered records
+ to the target, if there is one. Override if you want different behavior.
+
+
+.. method:: MemoryHandler.setTarget(target)
+
+ Sets the target handler for this handler.
+
+
+.. method:: MemoryHandler.shouldFlush(record)
+
+ Checks for buffer full or a record at the *flushLevel* or higher.
+
+
+HTTPHandler
+^^^^^^^^^^^
+
+The :class:`HTTPHandler` class, located in the :mod:`logging.handlers` module,
+supports sending logging messages to a Web server, using either ``GET`` or
+``POST`` semantics.
+
+
+.. class:: HTTPHandler(host, url[, method])
+
+ Returns a new instance of the :class:`HTTPHandler` class. The instance is
+ initialized with a host address, url and HTTP method. The *host* can be of the
+ form ``host:port``, should you need to use a specific port number. If no
+ *method* is specified, ``GET`` is used.
+
+
+.. method:: HTTPHandler.emit(record)
+
+ Sends the record to the Web server as an URL-encoded dictionary.
+
+
+Formatter Objects
+-----------------
+
+:class:`Formatter`\ s have the following attributes and methods. They are
+responsible for converting a :class:`LogRecord` to (usually) a string which can
+be interpreted by either a human or an external system. The base
+:class:`Formatter` allows a formatting string to be specified. If none is
+supplied, the default value of ``'%(message)s'`` is used.
+
+A Formatter can be initialized with a format string which makes use of knowledge
+of the :class:`LogRecord` attributes - such as the default value mentioned above
+making use of the fact that the user's message and arguments are pre-formatted
+into a :class:`LogRecord`'s *message* attribute. This format string contains
+standard python %-style mapping keys. See section :ref:`string-formatting`
+for more information on string formatting.
+
+Currently, the useful mapping keys in a :class:`LogRecord` are:
+
++-------------------------+-----------------------------------------------+
+| Format | Description |
++=========================+===============================================+
+| ``%(name)s`` | Name of the logger (logging channel). |
++-------------------------+-----------------------------------------------+
+| ``%(levelno)s`` | Numeric logging level for the message |
+| | (:const:`DEBUG`, :const:`INFO`, |
+| | :const:`WARNING`, :const:`ERROR`, |
+| | :const:`CRITICAL`). |
++-------------------------+-----------------------------------------------+
+| ``%(levelname)s`` | Text logging level for the message |
+| | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``, |
+| | ``'ERROR'``, ``'CRITICAL'``). |
++-------------------------+-----------------------------------------------+
+| ``%(pathname)s`` | Full pathname of the source file where the |
+| | logging call was issued (if available). |
++-------------------------+-----------------------------------------------+
+| ``%(filename)s`` | Filename portion of pathname. |
++-------------------------+-----------------------------------------------+
+| ``%(module)s`` | Module (name portion of filename). |
++-------------------------+-----------------------------------------------+
+| ``%(funcName)s`` | Name of function containing the logging call. |
++-------------------------+-----------------------------------------------+
+| ``%(lineno)d`` | Source line number where the logging call was |
+| | issued (if available). |
++-------------------------+-----------------------------------------------+
+| ``%(created)f`` | Time when the :class:`LogRecord` was created |
+| | (as returned by :func:`time.time`). |
++-------------------------+-----------------------------------------------+
+| ``%(relativeCreated)d`` | Time in milliseconds when the LogRecord was |
+| | created, relative to the time the logging |
+| | module was loaded. |
++-------------------------+-----------------------------------------------+
+| ``%(asctime)s`` | Human-readable time when the |
+| | :class:`LogRecord` was created. By default |
+| | this is of the form "2003-07-08 16:49:45,896" |
+| | (the numbers after the comma are millisecond |
+| | portion of the time). |
++-------------------------+-----------------------------------------------+
+| ``%(msecs)d`` | Millisecond portion of the time when the |
+| | :class:`LogRecord` was created. |
++-------------------------+-----------------------------------------------+
+| ``%(thread)d`` | Thread ID (if available). |
++-------------------------+-----------------------------------------------+
+| ``%(threadName)s`` | Thread name (if available). |
++-------------------------+-----------------------------------------------+
+| ``%(process)d`` | Process ID (if available). |
++-------------------------+-----------------------------------------------+
+| ``%(message)s`` | The logged message, computed as ``msg % |
+| | args``. |
++-------------------------+-----------------------------------------------+
+
+.. versionchanged:: 2.5
+ *funcName* was added.
+
+
+.. class:: Formatter([fmt[, datefmt]])
+
+ Returns a new instance of the :class:`Formatter` class. The instance is
+ initialized with a format string for the message as a whole, as well as a format
+ string for the date/time portion of a message. If no *fmt* is specified,
+ ``'%(message)s'`` is used. If no *datefmt* is specified, the ISO8601 date format
+ is used.
+
+
+.. method:: Formatter.format(record)
+
+ The record's attribute dictionary is used as the operand to a string formatting
+ operation. Returns the resulting string. Before formatting the dictionary, a
+ couple of preparatory steps are carried out. The *message* attribute of the
+ record is computed using *msg* % *args*. If the formatting string contains
+ ``'(asctime)'``, :meth:`formatTime` is called to format the event time. If there
+ is exception information, it is formatted using :meth:`formatException` and
+ appended to the message.
+
+
+.. method:: Formatter.formatTime(record[, datefmt])
+
+ This method should be called from :meth:`format` by a formatter which wants to
+ make use of a formatted time. This method can be overridden in formatters to
+ provide for any specific requirement, but the basic behavior is as follows: if
+ *datefmt* (a string) is specified, it is used with :func:`time.strftime` to
+ format the creation time of the record. Otherwise, the ISO8601 format is used.
+ The resulting string is returned.
+
+
+.. method:: Formatter.formatException(exc_info)
+
+ Formats the specified exception information (a standard exception tuple as
+ returned by :func:`sys.exc_info`) as a string. This default implementation just
+ uses :func:`traceback.print_exception`. The resulting string is returned.
+
+
+Filter Objects
+--------------
+
+:class:`Filter`\ s can be used by :class:`Handler`\ s and :class:`Logger`\ s for
+more sophisticated filtering than is provided by levels. The base filter class
+only allows events which are below a certain point in the logger hierarchy. For
+example, a filter initialized with "A.B" will allow events logged by loggers
+"A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB", "B.A.B" etc. If
+initialized with the empty string, all events are passed.
+
+
+.. class:: Filter([name])
+
+ Returns an instance of the :class:`Filter` class. If *name* is specified, it
+ names a logger which, together with its children, will have its events allowed
+ through the filter. If no name is specified, allows every event.
+
+
+.. method:: Filter.filter(record)
+
+ Is the specified record to be logged? Returns zero for no, nonzero for yes. If
+ deemed appropriate, the record may be modified in-place by this method.
+
+
+LogRecord Objects
+-----------------
+
+:class:`LogRecord` instances are created every time something is logged. They
+contain all the information pertinent to the event being logged. The main
+information passed in is in msg and args, which are combined using msg % args to
+create the message field of the record. The record also includes information
+such as when the record was created, the source line where the logging call was
+made, and any exception information to be logged.
+
+
+.. class:: LogRecord(name, lvl, pathname, lineno, msg, args, exc_info [, func])
+
+ Returns an instance of :class:`LogRecord` initialized with interesting
+ information. The *name* is the logger name; *lvl* is the numeric level;
+ *pathname* is the absolute pathname of the source file in which the logging
+ call was made; *lineno* is the line number in that file where the logging
+ call is found; *msg* is the user-supplied message (a format string); *args*
+ is the tuple which, together with *msg*, makes up the user message; and
+ *exc_info* is the exception tuple obtained by calling :func:`sys.exc_info`
+ (or :const:`None`, if no exception information is available). The *func* is
+ the name of the function from which the logging call was made. If not
+ specified, it defaults to ``None``.
+
+ .. versionchanged:: 2.5
+ *func* was added.
+
+
+.. method:: LogRecord.getMessage()
+
+ Returns the message for this :class:`LogRecord` instance after merging any
+ user-supplied arguments with the message.
+
+
+Thread Safety
+-------------
+
+The logging module is intended to be thread-safe without any special work
+needing to be done by its clients. It achieves this though using threading
+locks; there is one lock to serialize access to the module's shared data, and
+each handler also creates a lock to serialize access to its underlying I/O.
+
+
+Configuration
+-------------
+
+
+.. _logging-config-api:
+
+Configuration functions
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. %
+
+The following functions configure the logging module. They are located in the
+:mod:`logging.config` module. Their use is optional --- you can configure the
+logging module using these functions or by making calls to the main API (defined
+in :mod:`logging` itself) and defining handlers which are declared either in
+:mod:`logging` or :mod:`logging.handlers`.
+
+
+.. function:: fileConfig(fname[, defaults])
+
+ Reads the logging configuration from a ConfigParser-format file named *fname*.
+ This function can be called several times from an application, allowing an end
+ user the ability to select from various pre-canned configurations (if the
+ developer provides a mechanism to present the choices and load the chosen
+ configuration). Defaults to be passed to ConfigParser can be specified in the
+ *defaults* argument.
+
+
+.. function:: listen([port])
+
+ Starts up a socket server on the specified port, and listens for new
+ configurations. If no port is specified, the module's default
+ :const:`DEFAULT_LOGGING_CONFIG_PORT` is used. Logging configurations will be
+ sent as a file suitable for processing by :func:`fileConfig`. Returns a
+ :class:`Thread` instance on which you can call :meth:`start` to start the
+ server, and which you can :meth:`join` when appropriate. To stop the server,
+ call :func:`stopListening`. To send a configuration to the socket, read in the
+ configuration file and send it to the socket as a string of bytes preceded by a
+ four-byte length packed in binary using struct.\ ``pack('>L', n)``.
+
+
+.. function:: stopListening()
+
+ Stops the listening server which was created with a call to :func:`listen`. This
+ is typically called before calling :meth:`join` on the return value from
+ :func:`listen`.
+
+
+.. _logging-config-fileformat:
+
+Configuration file format
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. %
+
+The configuration file format understood by :func:`fileConfig` is based on
+ConfigParser functionality. The file must contain sections called ``[loggers]``,
+``[handlers]`` and ``[formatters]`` which identify by name the entities of each
+type which are defined in the file. For each such entity, there is a separate
+section which identified how that entity is configured. Thus, for a logger named
+``log01`` in the ``[loggers]`` section, the relevant configuration details are
+held in a section ``[logger_log01]``. Similarly, a handler called ``hand01`` in
+the ``[handlers]`` section will have its configuration held in a section called
+``[handler_hand01]``, while a formatter called ``form01`` in the
+``[formatters]`` section will have its configuration specified in a section
+called ``[formatter_form01]``. The root logger configuration must be specified
+in a section called ``[logger_root]``.
+
+Examples of these sections in the file are given below. ::
+
+ [loggers]
+ keys=root,log02,log03,log04,log05,log06,log07
+
+ [handlers]
+ keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09
+
+ [formatters]
+ keys=form01,form02,form03,form04,form05,form06,form07,form08,form09
+
+The root logger must specify a level and a list of handlers. An example of a
+root logger section is given below. ::
+
+ [logger_root]
+ level=NOTSET
+ handlers=hand01
+
+The ``level`` entry can be one of ``DEBUG, INFO, WARNING, ERROR, CRITICAL`` or
+``NOTSET``. For the root logger only, ``NOTSET`` means that all messages will be
+logged. Level values are :func:`eval`\ uated in the context of the ``logging``
+package's namespace.
+
+The ``handlers`` entry is a comma-separated list of handler names, which must
+appear in the ``[handlers]`` section. These names must appear in the
+``[handlers]`` section and have corresponding sections in the configuration
+file.
+
+For loggers other than the root logger, some additional information is required.
+This is illustrated by the following example. ::
+
+ [logger_parser]
+ level=DEBUG
+ handlers=hand01
+ propagate=1
+ qualname=compiler.parser
+
+The ``level`` and ``handlers`` entries are interpreted as for the root logger,
+except that if a non-root logger's level is specified as ``NOTSET``, the system
+consults loggers higher up the hierarchy to determine the effective level of the
+logger. The ``propagate`` entry is set to 1 to indicate that messages must
+propagate to handlers higher up the logger hierarchy from this logger, or 0 to
+indicate that messages are **not** propagated to handlers up the hierarchy. The
+``qualname`` entry is the hierarchical channel name of the logger, that is to
+say the name used by the application to get the logger.
+
+Sections which specify handler configuration are exemplified by the following.
+::
+
+ [handler_hand01]
+ class=StreamHandler
+ level=NOTSET
+ formatter=form01
+ args=(sys.stdout,)
+
+The ``class`` entry indicates the handler's class (as determined by :func:`eval`
+in the ``logging`` package's namespace). The ``level`` is interpreted as for
+loggers, and ``NOTSET`` is taken to mean "log everything".
+
+The ``formatter`` entry indicates the key name of the formatter for this
+handler. If blank, a default formatter (``logging._defaultFormatter``) is used.
+If a name is specified, it must appear in the ``[formatters]`` section and have
+a corresponding section in the configuration file.
+
+The ``args`` entry, when :func:`eval`\ uated in the context of the ``logging``
+package's namespace, is the list of arguments to the constructor for the handler
+class. Refer to the constructors for the relevant handlers, or to the examples
+below, to see how typical entries are constructed. ::
+
+ [handler_hand02]
+ class=FileHandler
+ level=DEBUG
+ formatter=form02
+ args=('python.log', 'w')
+
+ [handler_hand03]
+ class=handlers.SocketHandler
+ level=INFO
+ formatter=form03
+ args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)
+
+ [handler_hand04]
+ class=handlers.DatagramHandler
+ level=WARN
+ formatter=form04
+ args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)
+
+ [handler_hand05]
+ class=handlers.SysLogHandler
+ level=ERROR
+ formatter=form05
+ args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)
+
+ [handler_hand06]
+ class=handlers.NTEventLogHandler
+ level=CRITICAL
+ formatter=form06
+ args=('Python Application', '', 'Application')
+
+ [handler_hand07]
+ class=handlers.SMTPHandler
+ level=WARN
+ formatter=form07
+ args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')
+
+ [handler_hand08]
+ class=handlers.MemoryHandler
+ level=NOTSET
+ formatter=form08
+ target=
+ args=(10, ERROR)
+
+ [handler_hand09]
+ class=handlers.HTTPHandler
+ level=NOTSET
+ formatter=form09
+ args=('localhost:9022', '/log', 'GET')
+
+Sections which specify formatter configuration are typified by the following. ::
+
+ [formatter_form01]
+ format=F1 %(asctime)s %(levelname)s %(message)s
+ datefmt=
+ class=logging.Formatter
+
+The ``format`` entry is the overall format string, and the ``datefmt`` entry is
+the :func:`strftime`\ -compatible date/time format string. If empty, the package
+substitutes ISO8601 format date/times, which is almost equivalent to specifying
+the date format string "The ISO8601 format also specifies milliseconds, which
+are appended to the result of using the above format string, with a comma
+separator. An example time in ISO8601 format is ``2003-01-23 00:29:50,411``.
+
+.. % Y-%m-%d %H:%M:%S".
+
+The ``class`` entry is optional. It indicates the name of the formatter's class
+(as a dotted module and class name.) This option is useful for instantiating a
+:class:`Formatter` subclass. Subclasses of :class:`Formatter` can present
+exception tracebacks in an expanded or condensed format.
+
--- /dev/null
+.. _mac-specific-services:
+
+*************************
+MacOS X specific services
+*************************
+
+This chapter describes modules that are only available on the Mac OS X platform.
+
+See the chapters :ref:`mac-scripting` and :ref:`undoc-mac-modules` for more
+modules, and the HOWTO :ref:`using-on-mac` for a general introduction to
+Mac-specific Python programming.
+
+
+.. toctree::
+
+ ic.rst
+ macos.rst
+ macostools.rst
+ easydialogs.rst
+ framework.rst
+ autogil.rst
+ carbon.rst
+ colorpicker.rst
--- /dev/null
+
+:mod:`MacOS` --- Access to Mac OS interpreter features
+======================================================
+
+.. module:: MacOS
+ :platform: Mac
+ :synopsis: Access to Mac OS-specific interpreter features.
+
+
+This module provides access to MacOS specific functionality in the Python
+interpreter, such as how the interpreter eventloop functions and the like. Use
+with care.
+
+Note the capitalization of the module name; this is a historical artifact.
+
+
+.. data:: runtimemodel
+
+ Always ``'macho'``, from Python 2.4 on. In earlier versions of Python the value
+ could also be ``'ppc'`` for the classic Mac OS 8 runtime model or ``'carbon'``
+ for the Mac OS 9 runtime model.
+
+
+.. data:: linkmodel
+
+ The way the interpreter has been linked. As extension modules may be
+ incompatible between linking models, packages could use this information to give
+ more decent error messages. The value is one of ``'static'`` for a statically
+ linked Python, ``'framework'`` for Python in a Mac OS X framework, ``'shared'``
+ for Python in a standard Unix shared library. Older Pythons could also have the
+ value ``'cfm'`` for Mac OS 9-compatible Python.
+
+
+.. exception:: Error
+
+ .. index:: module: macerrors
+
+ This exception is raised on MacOS generated errors, either from functions in
+ this module or from other mac-specific modules like the toolbox interfaces. The
+ arguments are the integer error code (the :cdata:`OSErr` value) and a textual
+ description of the error code. Symbolic names for all known error codes are
+ defined in the standard module :mod:`macerrors`.
+
+
+.. function:: GetErrorString(errno)
+
+ Return the textual description of MacOS error code *errno*.
+
+
+.. function:: DebugStr(message [, object])
+
+ On Mac OS X the string is simply printed to stderr (on older Mac OS systems more
+ elaborate functionality was available), but it provides a convenient location to
+ attach a breakpoint in a low-level debugger like :program:`gdb`.
+
+
+.. function:: SysBeep()
+
+ Ring the bell.
+
+
+.. function:: GetTicks()
+
+ Get the number of clock ticks (1/60th of a second) since system boot.
+
+
+.. function:: GetCreatorAndType(file)
+
+ Return the file creator and file type as two four-character strings. The *file*
+ parameter can be a pathname or an ``FSSpec`` or ``FSRef`` object.
+
+
+.. function:: SetCreatorAndType(file, creator, type)
+
+ Set the file creator and file type. The *file* parameter can be a pathname or an
+ ``FSSpec`` or ``FSRef`` object. *creator* and *type* must be four character
+ strings.
+
+
+.. function:: openrf(name [, mode])
+
+ Open the resource fork of a file. Arguments are the same as for the built-in
+ function :func:`open`. The object returned has file-like semantics, but it is
+ not a Python file object, so there may be subtle differences.
+
+
+.. function:: WMAvailable()
+
+ Checks whether the current process has access to the window manager. The method
+ will return ``False`` if the window manager is not available, for instance when
+ running on Mac OS X Server or when logged in via ssh, or when the current
+ interpreter is not running from a fullblown application bundle. A script runs
+ from an application bundle either when it has been started with
+ :program:`pythonw` instead of :program:`python` or when running as an applet.
+
--- /dev/null
+
+.. _mac-scripting:
+
+*********************
+MacPython OSA Modules
+*********************
+
+This chapter describes the current implementation of the Open Scripting
+Architecure (OSA, also commonly referred to as AppleScript) for Python, allowing
+you to control scriptable applications from your Python program, and with a
+fairly pythonic interface. Development on this set of modules has stopped, and a
+replacement is expected for Python 2.5.
+
+For a description of the various components of AppleScript and OSA, and to get
+an understanding of the architecture and terminology, you should read Apple's
+documentation. The "Applescript Language Guide" explains the conceptual model
+and the terminology, and documents the standard suite. The "Open Scripting
+Architecture" document explains how to use OSA from an application programmers
+point of view. In the Apple Help Viewer these books are located in the Developer
+Documentation, Core Technologies section.
+
+As an example of scripting an application, the following piece of AppleScript
+will get the name of the frontmost :program:`Finder` window and print it::
+
+ tell application "Finder"
+ get name of window 1
+ end tell
+
+In Python, the following code fragment will do the same::
+
+ import Finder
+
+ f = Finder.Finder()
+ print f.get(f.window(1).name)
+
+As distributed the Python library includes packages that implement the standard
+suites, plus packages that interface to a small number of common applications.
+
+To send AppleEvents to an application you must first create the Python package
+interfacing to the terminology of the application (what :program:`Script Editor`
+calls the "Dictionary"). This can be done from within the :program:`PythonIDE`
+or by running the :file:`gensuitemodule.py` module as a standalone program from
+the command line.
+
+The generated output is a package with a number of modules, one for every suite
+used in the program plus an :mod:`__init__` module to glue it all together. The
+Python inheritance graph follows the AppleScript inheritance graph, so if a
+program's dictionary specifies that it includes support for the Standard Suite,
+but extends one or two verbs with extra arguments then the output suite will
+contain a module :mod:`Standard_Suite` that imports and re-exports everything
+from :mod:`StdSuites.Standard_Suite` but overrides the methods that have extra
+functionality. The output of :mod:`gensuitemodule` is pretty readable, and
+contains the documentation that was in the original AppleScript dictionary in
+Python docstrings, so reading it is a good source of documentation.
+
+The output package implements a main class with the same name as the package
+which contains all the AppleScript verbs as methods, with the direct object as
+the first argument and all optional parameters as keyword arguments. AppleScript
+classes are also implemented as Python classes, as are comparisons and all the
+other thingies.
+
+The main Python class implementing the verbs also allows access to the
+properties and elements declared in the AppleScript class "application". In the
+current release that is as far as the object orientation goes, so in the example
+above we need to use ``f.get(f.window(1).name)`` instead of the more Pythonic
+``f.window(1).name.get()``.
+
+If an AppleScript identifier is not a Python identifier the name is mangled
+according to a small number of rules:
+
+* spaces are replaced with underscores
+
+* other non-alphanumeric characters are replaced with ``_xx_`` where ``xx`` is
+ the hexadecimal character value
+
+* any Python reserved word gets an underscore appended
+
+Python also has support for creating scriptable applications in Python, but The
+following modules are relevant to MacPython AppleScript support:
+
+.. toctree::
+
+ gensuitemodule.rst
+ aetools.rst
+ aepack.rst
+ aetypes.rst
+ miniaeframe.rst
+
+
+In addition, support modules have been pre-generated for :mod:`Finder`,
+:mod:`Terminal`, :mod:`Explorer`, :mod:`Netscape`, :mod:`CodeWarrior`,
+:mod:`SystemEvents` and :mod:`StdSuites`.
--- /dev/null
+
+:mod:`macostools` --- Convenience routines for file manipulation
+================================================================
+
+.. module:: macostools
+ :platform: Mac
+ :synopsis: Convenience routines for file manipulation.
+
+
+This module contains some convenience routines for file-manipulation on the
+Macintosh. All file parameters can be specified as pathnames, :class:`FSRef` or
+:class:`FSSpec` objects. This module expects a filesystem which supports forked
+files, so it should not be used on UFS partitions.
+
+The :mod:`macostools` module defines the following functions:
+
+
+.. function:: copy(src, dst[, createpath[, copytimes]])
+
+ Copy file *src* to *dst*. If *createpath* is non-zero the folders leading to
+ *dst* are created if necessary. The method copies data and resource fork and
+ some finder information (creator, type, flags) and optionally the creation,
+ modification and backup times (default is to copy them). Custom icons, comments
+ and icon position are not copied.
+
+
+.. function:: copytree(src, dst)
+
+ Recursively copy a file tree from *src* to *dst*, creating folders as needed.
+ *src* and *dst* should be specified as pathnames.
+
+
+.. function:: mkalias(src, dst)
+
+ Create a finder alias *dst* pointing to *src*.
+
+
+.. function:: touched(dst)
+
+ Tell the finder that some bits of finder-information such as creator or type for
+ file *dst* has changed. The file can be specified by pathname or fsspec. This
+ call should tell the finder to redraw the files icon.
+
+ .. deprecated:: 2.6
+ The function is a no-op on OS X.
+
+
+.. data:: BUFSIZ
+
+ The buffer size for ``copy``, default 1 megabyte.
+
+Note that the process of creating finder aliases is not specified in the Apple
+documentation. Hence, aliases created with :func:`mkalias` could conceivably
+have incompatible behaviour in some cases.
+
+
+:mod:`findertools` --- The :program:`finder`'s Apple Events interface
+=====================================================================
+
+.. module:: findertools
+ :platform: Mac
+ :synopsis: Wrappers around the finder's Apple Events interface.
+
+
+.. index:: single: AppleEvents
+
+This module contains routines that give Python programs access to some
+functionality provided by the finder. They are implemented as wrappers around
+the AppleEvent interface to the finder.
+
+All file and folder parameters can be specified either as full pathnames, or as
+:class:`FSRef` or :class:`FSSpec` objects.
+
+The :mod:`findertools` module defines the following functions:
+
+
+.. function:: launch(file)
+
+ Tell the finder to launch *file*. What launching means depends on the file:
+ applications are started, folders are opened and documents are opened in the
+ correct application.
+
+
+.. function:: Print(file)
+
+ Tell the finder to print a file. The behaviour is identical to selecting the
+ file and using the print command in the finder's file menu.
+
+
+.. function:: copy(file, destdir)
+
+ Tell the finder to copy a file or folder *file* to folder *destdir*. The
+ function returns an :class:`Alias` object pointing to the new file.
+
+
+.. function:: move(file, destdir)
+
+ Tell the finder to move a file or folder *file* to folder *destdir*. The
+ function returns an :class:`Alias` object pointing to the new file.
+
+
+.. function:: sleep()
+
+ Tell the finder to put the Macintosh to sleep, if your machine supports it.
+
+
+.. function:: restart()
+
+ Tell the finder to perform an orderly restart of the machine.
+
+
+.. function:: shutdown()
+
+ Tell the finder to perform an orderly shutdown of the machine.
+
projects / python / commitdiff