Delete the LaTeX doc tree.
diff --git a/Doc/ACKS b/Doc/ACKS
deleted file mode 100644
index 3c2662d..0000000
--- a/Doc/ACKS
+++ /dev/null
@@ -1,202 +0,0 @@
-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.
-
-It is only with the input and contributions of the Python community
-that Python has such wonderful documentation -- Thank You!
-
-In the official sources, this file is encoded in ISO-8859-1 (Latin-1).
-
-
- -Fred
-
-
-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
-Keith Briggs
-Lee Busby
-Lorenzo M. Catucci
-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
-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
diff --git a/Doc/Makefile b/Doc/Makefile
deleted file mode 100644
index 3da9690..0000000
--- a/Doc/Makefile
+++ /dev/null
@@ -1,736 +0,0 @@
-# Makefile for Python documentation
-# ---------------------------------
-#
-# See also the README file.
-#
-# This is a bit of a mess. The documents are identified by short names:
-# api -- Python/C API Reference Manual
-# doc -- Documenting Python
-# ext -- Extending and Embedding the Python Interpreter
-# lib -- Library Reference Manual
-# mac -- Macintosh Library Modules
-# ref -- Python Reference Manual
-# tut -- Python Tutorial
-# inst -- Installing Python Modules
-# dist -- Distributing Python Modules
-#
-# The LaTeX sources for each of these documents are in subdirectories
-# with the three-letter designations above as the directory names.
-#
-# The main target creates HTML for each of the documents. You can
-# also do "make lib" (etc.) to create the HTML versions of individual
-# documents.
-#
-# The document classes and styles are in the texinputs/ directory.
-# These define a number of macros that are similar in name and intent
-# as macros in Texinfo (e.g. \code{...} and \emph{...}), as well as a
-# number of environments for formatting function and data definitions.
-# Documentation for the macros is included in "Documenting Python"; see
-# http://www.python.org/doc/current/doc/doc.html, or the sources for
-# this document in the doc/ directory.
-#
-# Everything is processed by LaTeX. See the file `README' for more
-# information on the tools needed for processing.
-#
-# There's a problem with generating the index which has been solved by
-# a sed command applied to the index file. The shell script fix_hack
-# does this (the Makefile takes care of calling it).
-#
-# Additional targets attempt to convert selected LaTeX sources to
-# various other formats. These are generally site specific because
-# the tools used are all but universal. These targets are:
-#
-# ps -- convert all documents from LaTeX to PostScript
-# pdf -- convert all documents from LaTeX to the
-# Portable Document Format
-#
-# See the README file for more information on these targets.
-#
-# The formatted output is located in subdirectories. For PDF and
-# PostScript, look in the paper-$(PAPER)/ directory. For HTML, look in
-# the html/ directory. If you want to fix the GNU info process, look
-# in the info/ directory; please send patches to docs@python.org.
-
-# This Makefile only includes information on how to perform builds; for
-# dependency information, see Makefile.deps.
-
-# Customization -- you *may* have to edit this
-
-# You could set this to a4:
-PAPER=letter
-
-# Ideally, you shouldn't need to edit beyond this point
-
-INFODIR= info
-TOOLSDIR= tools
-
-# This is the *documentation* release, and is used to construct the
-# file names of the downloadable tarballs. It is initialized by the
-# getversioninfo script to ensure that the right version number is
-# used; the script will also write commontex/patchlevel.tex if that
-# doesn't exist or needs to be changed. Documents which depend on the
-# version number should use \input{patchlevel} and include
-# commontex/patchlevel.tex in their dependencies.
-RELEASE=$(shell $(PYTHON) tools/getversioninfo)
-
-PYTHON= $(PWD)/../python
-DVIPS= dvips -N0 -t $(PAPER)
-
-# This is ugly! The issue here is that there are two different levels
-# in the directory tree at which we execute mkhowto, so we can't
-# define it just once using a relative path (at least not with the
-# current implementation and Makefile structure). We use the GNUish
-# $(shell) function here to work around that restriction by
-# identifying mkhowto and the commontex/ directory using absolute paths.
-#
-# If your doc build fails immediately, you may need to switch to GNU make.
-# (e.g. OpenBSD needs package gmake installed; use gmake instead of make)
-PWD=$(shell pwd)
-
-# (The trailing colon in the value is needed; TeX places its default
-# set of paths at the location of the empty string in the path list.)
-TEXINPUTS=$(PWD)/commontex:
-
-# The mkhowto script can be run from the checkout using the first
-# version of this variable definition, or from a preferred version
-# using the second version. The standard documentation is typically
-# built using the second flavor, where the preferred version is from
-# the Python CVS trunk.
-MKHOWTO= TEXINPUTS=$(TEXINPUTS) $(PYTHON) $(PWD)/tools/mkhowto
-
-MKDVI= $(MKHOWTO) --paper=$(PAPER) --dvi
-MKHTML= $(MKHOWTO) --html --about html/stdabout.dat \
- --iconserver ../icons --favicon ../icons/pyfav.png \
- --address $(PYTHONDOCS) --up-link ../index.html \
- --up-title "Python Documentation Index" \
- --global-module-index "../modindex.html" --dvips-safe
-MKISILOHTML=$(MKHOWTO) --html --about html/stdabout.dat \
- --iconserver ../icons \
- --l2h-init perl/isilo.perl --numeric --split 1 \
- --dvips-safe
-MKISILO= iSilo386 -U -y -rCR -d0
-MKPDF= $(MKHOWTO) --paper=$(PAPER) --pdf
-MKPS= $(MKHOWTO) --paper=$(PAPER) --ps
-
-BUILDINDEX=$(TOOLSDIR)/buildindex.py
-
-PYTHONDOCS="See <i><a href=\"about.html\">About this document...</a></i> for information on suggesting changes."
-HTMLBASE= file:`pwd`
-
-# The emacs binary used to build the info docs. GNU Emacs 21 is required.
-EMACS= emacs
-
-# The end of this should reflect the major/minor version numbers of
-# the release:
-WHATSNEW=whatsnew30
-
-# what's what
-MANDVIFILES= paper-$(PAPER)/api.dvi paper-$(PAPER)/ext.dvi \
- paper-$(PAPER)/lib.dvi paper-$(PAPER)/mac.dvi \
- paper-$(PAPER)/ref.dvi paper-$(PAPER)/tut.dvi
-HOWTODVIFILES= paper-$(PAPER)/doc.dvi paper-$(PAPER)/inst.dvi \
- paper-$(PAPER)/dist.dvi paper-$(PAPER)/$(WHATSNEW).dvi
-
-MANPDFFILES= paper-$(PAPER)/api.pdf paper-$(PAPER)/ext.pdf \
- paper-$(PAPER)/lib.pdf paper-$(PAPER)/mac.pdf \
- paper-$(PAPER)/ref.pdf paper-$(PAPER)/tut.pdf
-HOWTOPDFFILES= paper-$(PAPER)/doc.pdf paper-$(PAPER)/inst.pdf \
- paper-$(PAPER)/dist.pdf paper-$(PAPER)/$(WHATSNEW).pdf
-
-MANPSFILES= paper-$(PAPER)/api.ps paper-$(PAPER)/ext.ps \
- paper-$(PAPER)/lib.ps paper-$(PAPER)/mac.ps \
- paper-$(PAPER)/ref.ps paper-$(PAPER)/tut.ps
-HOWTOPSFILES= paper-$(PAPER)/doc.ps paper-$(PAPER)/inst.ps \
- paper-$(PAPER)/dist.ps paper-$(PAPER)/$(WHATSNEW).ps
-
-DVIFILES= $(MANDVIFILES) $(HOWTODVIFILES)
-PDFFILES= $(MANPDFFILES) $(HOWTOPDFFILES)
-PSFILES= $(MANPSFILES) $(HOWTOPSFILES)
-
-HTMLCSSFILES=html/api/api.css \
- html/doc/doc.css \
- html/ext/ext.css \
- html/lib/lib.css \
- html/mac/mac.css \
- html/ref/ref.css \
- html/tut/tut.css \
- html/inst/inst.css \
- html/dist/dist.css
-
-ISILOCSSFILES=isilo/api/api.css \
- isilo/doc/doc.css \
- isilo/ext/ext.css \
- isilo/lib/lib.css \
- isilo/mac/mac.css \
- isilo/ref/ref.css \
- isilo/tut/tut.css \
- isilo/inst/inst.css \
- isilo/dist/dist.css
-
-ALLCSSFILES=$(HTMLCSSFILES) $(ISILOCSSFILES)
-
-INDEXFILES=html/api/api.html \
- html/doc/doc.html \
- html/ext/ext.html \
- html/lib/lib.html \
- html/mac/mac.html \
- html/ref/ref.html \
- html/tut/tut.html \
- html/inst/inst.html \
- html/dist/dist.html \
- html/whatsnew/$(WHATSNEW).html
-
-ALLHTMLFILES=$(INDEXFILES) html/index.html html/modindex.html html/acks.html
-
-COMMONPERL= perl/manual.perl perl/python.perl perl/l2hinit.perl
-
-ANNOAPI=api/refcounts.dat tools/anno-api.py
-
-include Makefile.deps
-
-# These must be declared phony since there
-# are directories with matching names:
-.PHONY: api doc ext lib mac ref tut inst dist
-.PHONY: html info isilo
-
-
-# Main target
-default: html
-all: html dvi ps pdf isilo
-
-dvi: $(DVIFILES)
-pdf: $(PDFFILES)
-ps: $(PSFILES)
-
-world: ps pdf html distfiles
-
-
-# Rules to build PostScript and PDF formats
-.SUFFIXES: .dvi .ps
-
-.dvi.ps:
- $(DVIPS) -o $@ $<
-
-
-# Targets for each document:
-# Python/C API Reference Manual
-paper-$(PAPER)/api.dvi: $(ANNOAPIFILES)
- cd paper-$(PAPER) && $(MKDVI) api.tex
-
-paper-$(PAPER)/api.pdf: $(ANNOAPIFILES)
- cd paper-$(PAPER) && $(MKPDF) api.tex
-
-paper-$(PAPER)/api.tex: api/api.tex
- cp api/api.tex $@
-
-paper-$(PAPER)/abstract.tex: api/abstract.tex $(ANNOAPI)
- $(PYTHON) $(TOOLSDIR)/anno-api.py -o $@ api/abstract.tex
-
-paper-$(PAPER)/concrete.tex: api/concrete.tex $(ANNOAPI)
- $(PYTHON) $(TOOLSDIR)/anno-api.py -o $@ api/concrete.tex
-
-paper-$(PAPER)/exceptions.tex: api/exceptions.tex $(ANNOAPI)
- $(PYTHON) $(TOOLSDIR)/anno-api.py -o $@ api/exceptions.tex
-
-paper-$(PAPER)/init.tex: api/init.tex $(ANNOAPI)
- $(PYTHON) $(TOOLSDIR)/anno-api.py -o $@ api/init.tex
-
-paper-$(PAPER)/intro.tex: api/intro.tex
- cp api/intro.tex $@
-
-paper-$(PAPER)/memory.tex: api/memory.tex $(ANNOAPI)
- $(PYTHON) $(TOOLSDIR)/anno-api.py -o $@ api/memory.tex
-
-paper-$(PAPER)/newtypes.tex: api/newtypes.tex $(ANNOAPI)
- $(PYTHON) $(TOOLSDIR)/anno-api.py -o $@ api/newtypes.tex
-
-paper-$(PAPER)/refcounting.tex: api/refcounting.tex $(ANNOAPI)
- $(PYTHON) $(TOOLSDIR)/anno-api.py -o $@ api/refcounting.tex
-
-paper-$(PAPER)/utilities.tex: api/utilities.tex $(ANNOAPI)
- $(PYTHON) $(TOOLSDIR)/anno-api.py -o $@ api/utilities.tex
-
-paper-$(PAPER)/veryhigh.tex: api/veryhigh.tex $(ANNOAPI)
- $(PYTHON) $(TOOLSDIR)/anno-api.py -o $@ api/veryhigh.tex
-
-# Distributing Python Modules
-paper-$(PAPER)/dist.dvi: $(DISTFILES)
- cd paper-$(PAPER) && $(MKDVI) ../dist/dist.tex
-
-paper-$(PAPER)/dist.pdf: $(DISTFILES)
- cd paper-$(PAPER) && $(MKPDF) ../dist/dist.tex
-
-# Documenting Python
-paper-$(PAPER)/doc.dvi: $(DOCFILES)
- cd paper-$(PAPER) && $(MKDVI) ../doc/doc.tex
-
-paper-$(PAPER)/doc.pdf: $(DOCFILES)
- cd paper-$(PAPER) && $(MKPDF) ../doc/doc.tex
-
-# Extending and Embedding the Python Interpreter
-paper-$(PAPER)/ext.dvi: $(EXTFILES)
- cd paper-$(PAPER) && $(MKDVI) ../ext/ext.tex
-
-paper-$(PAPER)/ext.pdf: $(EXTFILES)
- cd paper-$(PAPER) && $(MKPDF) ../ext/ext.tex
-
-# Installing Python Modules
-paper-$(PAPER)/inst.dvi: $(INSTFILES)
- cd paper-$(PAPER) && $(MKDVI) ../inst/inst.tex
-
-paper-$(PAPER)/inst.pdf: $(INSTFILES)
- cd paper-$(PAPER) && $(MKPDF) ../inst/inst.tex
-
-# Python Library Reference
-paper-$(PAPER)/lib.dvi: $(LIBFILES)
- cd paper-$(PAPER) && $(MKDVI) ../lib/lib.tex
-
-paper-$(PAPER)/lib.pdf: $(LIBFILES)
- cd paper-$(PAPER) && $(MKPDF) ../lib/lib.tex
-
-# Macintosh Library Modules
-paper-$(PAPER)/mac.dvi: $(MACFILES)
- cd paper-$(PAPER) && $(MKDVI) ../mac/mac.tex
-
-paper-$(PAPER)/mac.pdf: $(MACFILES)
- cd paper-$(PAPER) && $(MKPDF) ../mac/mac.tex
-
-# Python Reference Manual
-paper-$(PAPER)/ref.dvi: $(REFFILES)
- cd paper-$(PAPER) && $(MKDVI) ../ref/ref.tex
-
-paper-$(PAPER)/ref.pdf: $(REFFILES)
- cd paper-$(PAPER) && $(MKPDF) ../ref/ref.tex
-
-# Python Tutorial
-paper-$(PAPER)/tut.dvi: $(TUTFILES)
- cd paper-$(PAPER) && $(MKDVI) ../tut/tut.tex
-
-paper-$(PAPER)/tut.pdf: $(TUTFILES)
- cd paper-$(PAPER) && $(MKPDF) ../tut/tut.tex
-
-# What's New in Python X.Y
-paper-$(PAPER)/$(WHATSNEW).dvi: whatsnew/$(WHATSNEW).tex
- cd paper-$(PAPER) && $(MKDVI) ../whatsnew/$(WHATSNEW).tex
-
-paper-$(PAPER)/$(WHATSNEW).pdf: whatsnew/$(WHATSNEW).tex
- cd paper-$(PAPER) && $(MKPDF) ../whatsnew/$(WHATSNEW).tex
-
-# The remaining part of the Makefile is concerned with various
-# conversions, as described above. See also the README file.
-
-info:
- cd $(INFODIR) && $(MAKE) EMACS=$(EMACS) WHATSNEW=$(WHATSNEW)
-
-# Targets to convert the manuals to HTML using Nikos Drakos' LaTeX to
-# HTML converter. For more info on this program, see
-# <URL:http://cbl.leeds.ac.uk/nikos/tex2html/doc/latex2html/latex2html.html>.
-
-# Note that LaTeX2HTML inserts references to an icons directory in
-# each page that it generates. I have placed a copy of this directory
-# in the distribution to simplify the process of creating a
-# self-contained HTML distribution; for this purpose I have also added
-# a (trivial) index.html. Change the definition of $ICONSERVER in
-# perl/l2hinit.perl to use a different location for the icons directory.
-
-# If you have the standard LaTeX2HTML icons installed, the versions shipped
-# with this documentation should be stored in a separate directory and used
-# instead. The standard set does *not* include all the icons used in the
-# Python documentation.
-
-$(ALLCSSFILES): html/style.css
- cp $< $@
-
-$(INDEXFILES): $(COMMONPERL) html/stdabout.dat tools/node2label.pl
-
-html/acks.html: ACKS $(TOOLSDIR)/support.py $(TOOLSDIR)/mkackshtml
- $(PYTHON) $(TOOLSDIR)/mkackshtml --address $(PYTHONDOCS) \
- --favicon icons/pyfav.png \
- --output html/acks.html <ACKS
-
-
-# html/index.html is dependent on $(INDEXFILES) since we want the date
-# on the front index to be updated whenever any of the child documents
-# are updated and boilerplate.tex uses \today as the date. The index
-# files are not used to actually generate content.
-
-BOILERPLATE=commontex/boilerplate.tex
-html/index.html: $(INDEXFILES)
-html/index.html: html/index.html.in $(BOILERPLATE) tools/rewrite.py
- $(PYTHON) tools/rewrite.py $(BOILERPLATE) \
- RELEASE=$(RELEASE) WHATSNEW=$(WHATSNEW) \
- <$< >$@
-
-html/modindex.html: $(TOOLSDIR)/support.py $(TOOLSDIR)/mkmodindex
-html/modindex.html: html/dist/dist.html
-html/modindex.html: html/lib/lib.html html/mac/mac.html
- cd html && \
- $(PYTHON) ../$(TOOLSDIR)/mkmodindex --columns 3 \
- --output modindex.html --address $(PYTHONDOCS) \
- --favicon icons/pyfav.png \
- dist/modindex.html \
- lib/modindex.html mac/modindex.html
-
-html: $(ALLHTMLFILES) $(HTMLCSSFILES)
-
-api: html/api/api.html html/api/api.css
-html/api/api.html: $(APIFILES) api/refcounts.dat
- $(MKHTML) --dir html/api api/api.tex
-
-doc: html/doc/doc.html html/doc/doc.css
-html/doc/doc.html: $(DOCFILES)
- $(MKHTML) --dir html/doc doc/doc.tex
-
-ext: html/ext/ext.html html/ext/ext.css
-html/ext/ext.html: $(EXTFILES)
- $(MKHTML) --dir html/ext ext/ext.tex
-
-lib: html/lib/lib.html html/lib/lib.css
-html/lib/lib.html: $(LIBFILES)
- $(MKHTML) --dir html/lib lib/lib.tex
-
-mac: html/mac/mac.html html/mac/mac.css
-html/mac/mac.html: $(MACFILES)
- $(MKHTML) --dir html/mac mac/mac.tex
-
-ref: html/ref/ref.html html/ref/ref.css
-html/ref/ref.html: $(REFFILES)
- $(MKHTML) --dir html/ref ref/ref.tex
-
-tut: html/tut/tut.html html/tut/tut.css
-html/tut/tut.html: $(TUTFILES)
- $(MKHTML) --dir html/tut --numeric --split 3 tut/tut.tex
-
-inst: html/inst/inst.html html/inst/inst.css
-html/inst/inst.html: $(INSTFILES) perl/distutils.perl
- $(MKHTML) --dir html/inst --split 4 inst/inst.tex
-
-dist: html/dist/dist.html html/dist/dist.css
-html/dist/dist.html: $(DISTFILES) perl/distutils.perl
- $(MKHTML) --dir html/dist --split 4 dist/dist.tex
-
-whatsnew: html/whatsnew/$(WHATSNEW).html
-html/whatsnew/$(WHATSNEW).html: whatsnew/$(WHATSNEW).tex
- $(MKHTML) --dir html/whatsnew --split 4 whatsnew/$(WHATSNEW).tex
-
-
-# The iSilo format is used by the iSilo document reader for PalmOS devices.
-
-ISILOINDEXFILES=isilo/api/api.html \
- isilo/doc/doc.html \
- isilo/ext/ext.html \
- isilo/lib/lib.html \
- isilo/mac/mac.html \
- isilo/ref/ref.html \
- isilo/tut/tut.html \
- isilo/inst/inst.html \
- isilo/dist/dist.html \
- isilo/whatsnew/$(WHATSNEW).html
-
-$(ISILOINDEXFILES): $(COMMONPERL) html/stdabout.dat perl/isilo.perl
-
-isilo: isilo/python-api.pdb \
- isilo/python-doc.pdb \
- isilo/python-ext.pdb \
- isilo/python-lib.pdb \
- isilo/python-mac.pdb \
- isilo/python-ref.pdb \
- isilo/python-tut.pdb \
- isilo/python-dist.pdb \
- isilo/python-inst.pdb \
- isilo/python-whatsnew.pdb
-
-isilo/python-api.pdb: isilo/api/api.html isilo/api/api.css
- $(MKISILO) "-iPython/C API Reference Manual" \
- isilo/api/api.html $@
-
-isilo/python-doc.pdb: isilo/doc/doc.html isilo/doc/doc.css
- $(MKISILO) "-iDocumenting Python" \
- isilo/doc/doc.html $@
-
-isilo/python-ext.pdb: isilo/ext/ext.html isilo/ext/ext.css
- $(MKISILO) "-iExtending & Embedding Python" \
- isilo/ext/ext.html $@
-
-isilo/python-lib.pdb: isilo/lib/lib.html isilo/lib/lib.css
- $(MKISILO) "-iPython Library Reference" \
- isilo/lib/lib.html $@
-
-isilo/python-mac.pdb: isilo/mac/mac.html isilo/mac/mac.css
- $(MKISILO) "-iPython/C API Reference Manual" \
- isilo/mac/mac.html $@
-
-isilo/python-ref.pdb: isilo/ref/ref.html isilo/ref/ref.css
- $(MKISILO) "-iPython Reference Manual" \
- isilo/ref/ref.html $@
-
-isilo/python-tut.pdb: isilo/tut/tut.html isilo/tut/tut.css
- $(MKISILO) "-iPython Tutorial" \
- isilo/tut/tut.html $@
-
-isilo/python-dist.pdb: isilo/dist/dist.html isilo/dist/dist.css
- $(MKISILO) "-iDistributing Python Modules" \
- isilo/dist/dist.html $@
-
-isilo/python-inst.pdb: isilo/inst/inst.html isilo/inst/inst.css
- $(MKISILO) "-iInstalling Python Modules" \
- isilo/inst/inst.html $@
-
-isilo/python-whatsnew.pdb: isilo/whatsnew/$(WHATSNEW).html isilo/whatsnew/$(WHATSNEW).css
- $(MKISILO) "-iWhat's New in Python X.Y" \
- isilo/whatsnew/$(WHATSNEW).html $@
-
-isilo/api/api.html: $(APIFILES) api/refcounts.dat
- $(MKISILOHTML) --dir isilo/api api/api.tex
-
-isilo/doc/doc.html: $(DOCFILES)
- $(MKISILOHTML) --dir isilo/doc doc/doc.tex
-
-isilo/ext/ext.html: $(EXTFILES)
- $(MKISILOHTML) --dir isilo/ext ext/ext.tex
-
-isilo/lib/lib.html: $(LIBFILES)
- $(MKISILOHTML) --dir isilo/lib lib/lib.tex
-
-isilo/mac/mac.html: $(MACFILES)
- $(MKISILOHTML) --dir isilo/mac mac/mac.tex
-
-isilo/ref/ref.html: $(REFFILES)
- $(MKISILOHTML) --dir isilo/ref ref/ref.tex
-
-isilo/tut/tut.html: $(TUTFILES)
- $(MKISILOHTML) --dir isilo/tut tut/tut.tex
-
-isilo/inst/inst.html: $(INSTFILES) perl/distutils.perl
- $(MKISILOHTML) --dir isilo/inst inst/inst.tex
-
-isilo/dist/dist.html: $(DISTFILES) perl/distutils.perl
- $(MKISILOHTML) --dir isilo/dist dist/dist.tex
-
-isilo/whatsnew/$(WHATSNEW).html: whatsnew/$(WHATSNEW).tex
- $(MKISILOHTML) --dir isilo/whatsnew whatsnew/$(WHATSNEW).tex
-
-# These are useful if you need to transport the iSilo-ready HTML to
-# another machine to perform the conversion:
-
-isilozip: isilo-html-$(RELEASE).zip
-
-isilo-html-$(RELEASE).zip: $(ISILOINDEXFILES)
- rm -f $@
- cd isilo && \
- zip -q -9 ../$@ */*.css */*.html */*.txt
-
-
-# webchecker needs an extra flag to process the huge index from the libref
-WEBCHECKER=$(PYTHON) ../Tools/webchecker/webchecker.py
-HTMLBASE= file:`pwd`/html
-
-webcheck: $(ALLHTMLFILES)
- $(WEBCHECKER) $(HTMLBASE)/api/
- $(WEBCHECKER) $(HTMLBASE)/doc/
- $(WEBCHECKER) $(HTMLBASE)/ext/
- $(WEBCHECKER) -m290000 $(HTMLBASE)/lib/
- $(WEBCHECKER) $(HTMLBASE)/mac/
- $(WEBCHECKER) $(HTMLBASE)/ref/
- $(WEBCHECKER) $(HTMLBASE)/tut/
- $(WEBCHECKER) $(HTMLBASE)/dist/
- $(WEBCHECKER) $(HTMLBASE)/inst/
- $(WEBCHECKER) $(HTMLBASE)/whatsnew/
-
-fastwebcheck: $(ALLHTMLFILES)
- $(WEBCHECKER) -x $(HTMLBASE)/api/
- $(WEBCHECKER) -x $(HTMLBASE)/doc/
- $(WEBCHECKER) -x $(HTMLBASE)/ext/
- $(WEBCHECKER) -x -m290000 $(HTMLBASE)/lib/
- $(WEBCHECKER) -x $(HTMLBASE)/mac/
- $(WEBCHECKER) -x $(HTMLBASE)/ref/
- $(WEBCHECKER) -x $(HTMLBASE)/tut/
- $(WEBCHECKER) -x $(HTMLBASE)/dist/
- $(WEBCHECKER) -x $(HTMLBASE)/inst/
- $(WEBCHECKER) -x $(HTMLBASE)/whatsnew/
-
-
-# Release packaging targets:
-
-paper-$(PAPER)/README: $(PSFILES) $(TOOLSDIR)/getpagecounts
- cd paper-$(PAPER) && ../$(TOOLSDIR)/getpagecounts -r $(RELEASE) >../$@
-
-info-$(RELEASE).tgz: info
- cd $(INFODIR) && tar cf - README python.dir python-*.info* \
- | gzip -9 >../$@
-
-info-$(RELEASE).tar.bz2: info
- cd $(INFODIR) && tar cf - README python.dir python-*.info* \
- | bzip2 -9 >../$@
-
-latex-$(RELEASE).tgz:
- $(PYTHON) $(TOOLSDIR)/mksourcepkg --gzip $(RELEASE)
-
-latex-$(RELEASE).tar.bz2:
- $(PYTHON) $(TOOLSDIR)/mksourcepkg --bzip2 $(RELEASE)
-
-latex-$(RELEASE).zip:
- rm -f $@
- $(PYTHON) $(TOOLSDIR)/mksourcepkg --zip $(RELEASE)
-
-pdf-$(PAPER)-$(RELEASE).tar: $(PDFFILES)
- rm -f $@
- mkdir Python-Docs-$(RELEASE)
- cp paper-$(PAPER)/*.pdf Python-Docs-$(RELEASE)
- tar cf $@ Python-Docs-$(RELEASE)
- rm -r Python-Docs-$(RELEASE)
-
-pdf-$(PAPER)-$(RELEASE).tgz: pdf-$(PAPER)-$(RELEASE).tar
- gzip -9 <$? >$@
-
-pdf-$(PAPER)-$(RELEASE).tar.bz2: pdf-$(PAPER)-$(RELEASE).tar
- bzip2 -9 <$? >$@
-
-pdf-$(PAPER)-$(RELEASE).zip: pdf
- rm -f $@
- mkdir Python-Docs-$(RELEASE)
- cp paper-$(PAPER)/*.pdf Python-Docs-$(RELEASE)
- zip -q -r -9 $@ Python-Docs-$(RELEASE)
- rm -r Python-Docs-$(RELEASE)
-
-postscript-$(PAPER)-$(RELEASE).tar: $(PSFILES) paper-$(PAPER)/README
- rm -f $@
- mkdir Python-Docs-$(RELEASE)
- cp paper-$(PAPER)/*.ps Python-Docs-$(RELEASE)
- cp paper-$(PAPER)/README Python-Docs-$(RELEASE)
- tar cf $@ Python-Docs-$(RELEASE)
- rm -r Python-Docs-$(RELEASE)
-
-postscript-$(PAPER)-$(RELEASE).tar.bz2: postscript-$(PAPER)-$(RELEASE).tar
- bzip2 -9 <$< >$@
-
-postscript-$(PAPER)-$(RELEASE).tgz: postscript-$(PAPER)-$(RELEASE).tar
- gzip -9 <$< >$@
-
-postscript-$(PAPER)-$(RELEASE).zip: $(PSFILES) paper-$(PAPER)/README
- rm -f $@
- mkdir Python-Docs-$(RELEASE)
- cp paper-$(PAPER)/*.ps Python-Docs-$(RELEASE)
- cp paper-$(PAPER)/README Python-Docs-$(RELEASE)
- zip -q -r -9 $@ Python-Docs-$(RELEASE)
- rm -r Python-Docs-$(RELEASE)
-
-HTMLPKGFILES=*.html */*.css */*.html */*.gif */*.png */*.txt
-
-html-$(RELEASE).tar: $(ALLHTMLFILES) $(HTMLCSSFILES)
- mkdir Python-Docs-$(RELEASE)
- -find html -name '*.gif' -size 0 | xargs rm -f
- cd html && tar cf ../temp.tar $(HTMLPKGFILES)
- cd Python-Docs-$(RELEASE) && tar xf ../temp.tar
- rm temp.tar
- tar cf html-$(RELEASE).tar Python-Docs-$(RELEASE)
- rm -r Python-Docs-$(RELEASE)
-
-html-$(RELEASE).tgz: html-$(RELEASE).tar
- gzip -9 <$? >$@
-
-html-$(RELEASE).tar.bz2: html-$(RELEASE).tar
- bzip2 -9 <$? >$@
-
-html-$(RELEASE).zip: $(ALLHTMLFILES) $(HTMLCSSFILES)
- rm -f $@
- mkdir Python-Docs-$(RELEASE)
- cd html && tar cf ../temp.tar $(HTMLPKGFILES)
- cd Python-Docs-$(RELEASE) && tar xf ../temp.tar
- rm temp.tar
- zip -q -r -9 $@ Python-Docs-$(RELEASE)
- rm -r Python-Docs-$(RELEASE)
-
-isilo-$(RELEASE).zip: isilo
- rm -f $@
- mkdir Python-Docs-$(RELEASE)
- cp isilo/python-*.pdb Python-Docs-$(RELEASE)
- zip -q -r -9 $@ Python-Docs-$(RELEASE)
- rm -r Python-Docs-$(RELEASE)
-
-
-# convenience targets:
-
-tarhtml: html-$(RELEASE).tgz
-tarinfo: info-$(RELEASE).tgz
-tarps: postscript-$(PAPER)-$(RELEASE).tgz
-tarpdf: pdf-$(PAPER)-$(RELEASE).tgz
-tarlatex: latex-$(RELEASE).tgz
-
-tarballs: tarpdf tarps tarhtml
-
-ziphtml: html-$(RELEASE).zip
-zipps: postscript-$(PAPER)-$(RELEASE).zip
-zippdf: pdf-$(PAPER)-$(RELEASE).zip
-ziplatex: latex-$(RELEASE).zip
-zipisilo: isilo-$(RELEASE).zip
-
-zips: zippdf zipps ziphtml
-
-bziphtml: html-$(RELEASE).tar.bz2
-bzipinfo: info-$(RELEASE).tar.bz2
-bzipps: postscript-$(PAPER)-$(RELEASE).tar.bz2
-bzippdf: pdf-$(PAPER)-$(RELEASE).tar.bz2
-bziplatex: latex-$(RELEASE).tar.bz2
-
-bzips: bzippdf bzipps bziphtml
-
-disthtml: bziphtml ziphtml
-distinfo: bzipinfo
-distps: bzipps zipps
-distpdf: bzippdf zippdf
-distlatex: bziplatex ziplatex
-
-# We use the "pkglist" target at the end of these to ensure the
-# package list is updated after building either of these; this seems a
-# reasonable compromise between only building it for distfiles or
-# having to build it manually. Doing it here allows the packages for
-# distribution to be built using either of
-# make distfiles && make PAPER=a4 paperdist
-# make paperdist && make PAPER=a4 distfiles
-# The small amount of additional work is a small price to pay for not
-# having to remember which order to do it in. ;)
-paperdist: distpdf distps pkglist
-edist: disthtml pkglist
-
-# The pkglist.html file is used as part of the download.html page on
-# python.org; it is not used as intermediate input here or as part of
-# the packages created.
-pkglist:
- $(TOOLSDIR)/mkpkglist >pkglist.html
-
-distfiles: paperdist edist
- $(TOOLSDIR)/mksourcepkg --bzip2 --zip $(RELEASE)
- $(TOOLSDIR)/mkpkglist >pkglist.html
-
-
-# Housekeeping targets
-
-# Remove temporary files; all except the following:
-# - sources: .tex, .bib, .sty, *.cls
-# - useful results: .dvi, .pdf, .ps, .texi, .info
-clean:
- rm -f html-$(RELEASE).tar
- cd $(INFODIR) && $(MAKE) clean
-
-# Remove temporaries as well as final products
-clobber:
- rm -f html-$(RELEASE).tar
- rm -f html-$(RELEASE).tgz info-$(RELEASE).tgz
- rm -f pdf-$(RELEASE).tgz postscript-$(RELEASE).tgz
- rm -f latex-$(RELEASE).tgz html-$(RELEASE).zip
- rm -f pdf-$(RELEASE).zip postscript-$(RELEASE).zip
- rm -f $(DVIFILES) $(PSFILES) $(PDFFILES)
- cd $(INFODIR) && $(MAKE) clobber
- rm -f paper-$(PAPER)/*.tex paper-$(PAPER)/*.ind paper-$(PAPER)/*.idx
- rm -f paper-$(PAPER)/*.l2h paper-$(PAPER)/*.how paper-$(PAPER)/README
- rm -rf html/index.html html/modindex.html html/acks.html
- rm -rf html/api/ html/doc/ html/ext/ html/lib/ html/mac/
- rm -rf html/ref/ html/tut/ html/inst/ html/dist/
- rm -rf html/whatsnew/
- rm -rf isilo/api/ isilo/doc/ isilo/ext/ isilo/lib/ isilo/mac/
- rm -rf isilo/ref/ isilo/tut/ isilo/inst/ isilo/dist/
- rm -rf isilo/whatsnew/
- rm -f isilo/python-*.pdb isilo-$(RELEASE).zip
-
-realclean distclean: clobber
diff --git a/Doc/Makefile.deps b/Doc/Makefile.deps
deleted file mode 100644
index 64b090b..0000000
--- a/Doc/Makefile.deps
+++ /dev/null
@@ -1,360 +0,0 @@
-# LaTeX source dependencies.
-
-COMMONSTYLES= texinputs/python.sty \
- texinputs/pypaper.sty
-
-INDEXSTYLES=texinputs/python.ist
-
-COMMONTEX=commontex/copyright.tex \
- commontex/license.tex \
- commontex/patchlevel.tex \
- commontex/boilerplate.tex
-
-MANSTYLES= texinputs/fncychap.sty \
- texinputs/manual.cls \
- $(COMMONSTYLES)
-
-HOWTOSTYLES= texinputs/howto.cls \
- $(COMMONSTYLES)
-
-
-APIFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
- api/api.tex \
- api/abstract.tex \
- api/concrete.tex \
- api/exceptions.tex \
- api/init.tex \
- api/intro.tex \
- api/memory.tex \
- api/newtypes.tex \
- api/refcounting.tex \
- api/utilities.tex \
- api/veryhigh.tex \
- commontex/typestruct.h \
- commontex/reportingbugs.tex
-
-# These files are generated from those listed above, and are used to
-# generate the typeset versions of the manuals. The list is defined
-# here to make it easier to ensure parallelism.
-ANNOAPIFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) api/refcounts.dat \
- paper-$(PAPER)/api.tex \
- paper-$(PAPER)/abstract.tex \
- paper-$(PAPER)/concrete.tex \
- paper-$(PAPER)/exceptions.tex \
- paper-$(PAPER)/init.tex \
- paper-$(PAPER)/intro.tex \
- paper-$(PAPER)/memory.tex \
- paper-$(PAPER)/newtypes.tex \
- paper-$(PAPER)/refcounting.tex \
- paper-$(PAPER)/utilities.tex \
- paper-$(PAPER)/veryhigh.tex \
- commontex/reportingbugs.tex
-
-DOCFILES= $(HOWTOSTYLES) \
- commontex/boilerplate.tex \
- texinputs/ltxmarkup.sty \
- doc/doc.tex
-
-EXTFILES= ext/ext.tex $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
- ext/extending.tex \
- ext/newtypes.tex \
- ext/building.tex \
- ext/windows.tex \
- ext/embedding.tex \
- ext/noddy.c \
- ext/noddy2.c \
- ext/noddy3.c \
- ext/noddy4.c \
- ext/run-func.c \
- commontex/typestruct.h \
- commontex/reportingbugs.tex
-
-TUTFILES= tut/tut.tex tut/glossary.tex $(MANSTYLES) $(COMMONTEX)
-
-# LaTeX source files for the Python Reference Manual
-REFFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
- ref/ref.tex \
- ref/ref1.tex \
- ref/ref2.tex \
- ref/ref3.tex \
- ref/ref4.tex \
- ref/ref5.tex \
- ref/ref6.tex \
- ref/ref7.tex \
- ref/ref8.tex
-
-# LaTeX source files for the Python Library Reference
-LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
- commontex/reportingbugs.tex \
- lib/lib.tex \
- lib/asttable.tex \
- lib/distutils.tex \
- lib/email.tex \
- lib/emailencoders.tex \
- lib/emailexc.tex \
- lib/emailgenerator.tex \
- lib/emailiter.tex \
- lib/emailmessage.tex \
- lib/emailparser.tex \
- lib/emailutil.tex \
- lib/libintro.tex \
- lib/libobjs.tex \
- lib/libstdtypes.tex \
- lib/libexcs.tex \
- lib/libconsts.tex \
- lib/libfuncs.tex \
- lib/libpython.tex \
- lib/libsys.tex \
- lib/libplatform.tex \
- lib/libfpectl.tex \
- lib/libgc.tex \
- lib/libweakref.tex \
- lib/libinspect.tex \
- lib/libpydoc.tex \
- lib/libdifflib.tex \
- lib/libdoctest.tex \
- lib/libunittest.tex \
- lib/libtest.tex \
- lib/libtypes.tex \
- lib/libtraceback.tex \
- lib/libpickle.tex \
- lib/libshelve.tex \
- lib/libcopy.tex \
- lib/libmarshal.tex \
- lib/libwarnings.tex \
- lib/libimp.tex \
- lib/libzipimport.tex \
- lib/librunpy.tex \
- lib/libpkgutil.tex \
- lib/libparser.tex \
- lib/libbltin.tex \
- lib/libmain.tex \
- lib/libfuture.tex \
- lib/libstrings.tex \
- lib/libstring.tex \
- lib/libtextwrap.tex \
- lib/libcodecs.tex \
- lib/libunicodedata.tex \
- lib/libstringprep.tex \
- lib/libstruct.tex \
- lib/libmisc.tex \
- lib/libmath.tex \
- lib/libdecimal.tex \
- lib/libarray.tex \
- lib/liballos.tex \
- lib/libos.tex \
- lib/libdatetime.tex \
- lib/tzinfo-examples.py \
- lib/libtime.tex \
- lib/libgetopt.tex \
- lib/liboptparse.tex \
- lib/caseless.py \
- lib/required_1.py \
- lib/required_2.py \
- lib/libtempfile.tex \
- lib/liberrno.tex \
- lib/libctypes.tex \
- lib/libsomeos.tex \
- lib/libsignal.tex \
- lib/libsocket.tex \
- lib/libselect.tex \
- lib/libthread.tex \
- lib/libdummythread.tex \
- lib/libunix.tex \
- lib/libposix.tex \
- lib/libposixpath.tex \
- lib/libpwd.tex \
- lib/libspwd.tex \
- lib/libgrp.tex \
- lib/libcrypt.tex \
- lib/libdbm.tex \
- lib/libgdbm.tex \
- lib/libtermios.tex \
- lib/libfcntl.tex \
- lib/libsyslog.tex \
- lib/liblogging.tex \
- lib/libpdb.tex \
- lib/libprofile.tex \
- lib/libhotshot.tex \
- lib/libtimeit.tex \
- lib/libtrace.tex \
- lib/libcgi.tex \
- lib/libcgitb.tex \
- lib/liburllib.tex \
- lib/liburllib2.tex \
- lib/libhttplib.tex \
- lib/libftplib.tex \
- lib/libnntplib.tex \
- lib/liburlparse.tex \
- lib/libhtmlparser.tex \
- lib/libhtmllib.tex \
- lib/libsgmllib.tex \
- lib/librfc822.tex \
- lib/libmimetools.tex \
- lib/libbinascii.tex \
- lib/libmm.tex \
- lib/libaudioop.tex \
- lib/libaifc.tex \
- lib/libossaudiodev.tex \
- lib/libcrypto.tex \
- lib/libhashlib.tex \
- lib/libhmac.tex \
- lib/libxdrlib.tex \
- lib/libimghdr.tex \
- lib/libformatter.tex \
- lib/liboperator.tex \
- lib/libresource.tex \
- lib/libstat.tex \
- lib/libstringio.tex \
- lib/libtoken.tex \
- lib/libkeyword.tex \
- lib/libundoc.tex \
- lib/libmailcap.tex \
- lib/libglob.tex \
- lib/libuser.tex \
- lib/libanydbm.tex \
- lib/libbsddb.tex \
- lib/libdumbdbm.tex \
- lib/libdbhash.tex \
- lib/librandom.tex \
- lib/libsite.tex \
- lib/libwhichdb.tex \
- lib/libbase64.tex \
- lib/libfnmatch.tex \
- lib/libquopri.tex \
- lib/libzlib.tex \
- lib/libsocksvr.tex \
- lib/libmailbox.tex \
- lib/libcommands.tex \
- lib/libcmath.tex \
- lib/libgzip.tex \
- lib/libbz2.tex \
- lib/libzipfile.tex \
- lib/libpprint.tex \
- lib/libcode.tex \
- lib/libre.tex \
- lib/libuserdict.tex \
- lib/libdis.tex \
- lib/libxmlrpclib.tex \
- lib/libsimplexmlrpc.tex \
- lib/libdocxmlrpc.tex \
- lib/libpyexpat.tex \
- lib/libfunctools.tex \
- lib/xmldom.tex \
- lib/xmldomminidom.tex \
- lib/xmldompulldom.tex \
- lib/xmlsax.tex \
- lib/xmlsaxhandler.tex \
- lib/xmlsaxutils.tex \
- lib/xmlsaxreader.tex \
- lib/libetree.tex \
- lib/libqueue.tex \
- lib/liblocale.tex \
- lib/libgettext.tex \
- lib/libbasehttp.tex \
- lib/libcookie.tex \
- lib/libcookielib.tex \
- lib/libcopyreg.tex \
- lib/libsymbol.tex \
- lib/libbinhex.tex \
- lib/libuu.tex \
- lib/libfileinput.tex \
- lib/libimaplib.tex \
- lib/libpoplib.tex \
- lib/libcalendar.tex \
- lib/libbisect.tex \
- lib/libcollections.tex \
- lib/libheapq.tex \
- lib/libmimetypes.tex \
- lib/libsmtplib.tex \
- lib/libsmtpd.tex \
- lib/libcmd.tex \
- lib/libmultifile.tex \
- lib/libthreading.tex \
- lib/libdummythreading.tex \
- lib/libwebbrowser.tex \
- lib/internet.tex \
- lib/netdata.tex \
- lib/markup.tex \
- lib/language.tex \
- lib/libpycompile.tex \
- lib/libcompileall.tex \
- lib/libshlex.tex \
- lib/libnetrc.tex \
- lib/librobotparser.tex \
- lib/libgetpass.tex \
- lib/libshutil.tex \
- lib/librepr.tex \
- lib/libmsilib.tex \
- lib/libmsvcrt.tex \
- lib/libwinreg.tex \
- lib/libwinsound.tex \
- lib/windows.tex \
- lib/libpyclbr.tex \
- lib/libtokenize.tex \
- lib/libtabnanny.tex \
- lib/libmhlib.tex \
- lib/libtelnetlib.tex \
- lib/libcolorsys.tex \
- lib/libfpformat.tex \
- lib/libcgihttp.tex \
- lib/libsimplehttp.tex \
- lib/liblinecache.tex \
- lib/libnew.tex \
- lib/libdircache.tex \
- lib/libfilecmp.tex \
- lib/libsunau.tex \
- lib/libwave.tex \
- lib/libchunk.tex \
- lib/libcodeop.tex \
- lib/libcurses.tex \
- lib/libcursespanel.tex \
- lib/libascii.tex \
- lib/libdl.tex \
- lib/libmutex.tex \
- lib/libnis.tex \
- lib/libpipes.tex \
- lib/libpty.tex \
- lib/libreadline.tex \
- lib/librlcompleter.tex \
- lib/libsched.tex \
- lib/libstatvfs.tex \
- lib/libtty.tex \
- lib/libasyncore.tex \
- lib/libasynchat.tex \
- lib/libatexit.tex \
- lib/libmmap.tex \
- lib/tkinter.tex \
- lib/libturtle.tex \
- lib/libtarfile.tex \
- lib/libcsv.tex \
- lib/libcfgparser.tex \
- lib/libsqlite3.tex
-
-# LaTeX source files for Macintosh Library Modules.
-MACFILES= $(HOWTOSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
- mac/mac.tex \
- mac/using.tex \
- mac/scripting.tex \
- mac/toolbox.tex \
- mac/undoc.tex \
- mac/libcolorpicker.tex \
- mac/libmac.tex \
- mac/libgensuitemodule.tex \
- mac/libaetools.tex \
- mac/libaepack.tex \
- mac/libaetypes.tex \
- mac/libmacos.tex \
- mac/libmacostools.tex \
- mac/libmacui.tex \
- mac/libmacic.tex \
- mac/libframework.tex \
- mac/libautogil.tex \
- mac/libminiae.tex \
- mac/libscrap.tex
-
-INSTFILES = $(HOWTOSTYLES) inst/inst.tex
-
-DISTFILES = $(HOWTOSTYLES) \
- dist/dist.tex \
- dist/sysconfig.tex
diff --git a/Doc/README b/Doc/README
deleted file mode 100644
index a426ba2..0000000
--- a/Doc/README
+++ /dev/null
@@ -1,246 +0,0 @@
-Python standard documentation -- in LaTeX
------------------------------------------
-
-This directory contains the LaTeX sources to the Python documentation
-and tools required to support the formatting process. The documents
-now require LaTeX2e; LaTeX 2.09 compatibility has been dropped.
-
-If you don't have LaTeX, or if you'd rather not format the
-documentation yourself, you can ftp a tar file containing HTML, PDF,
-or PostScript versions of all documents. Additional formats may be
-available. These should be in the same place where you fetched the
-main Python distribution (try <http://www.python.org/> or
-<ftp://ftp.python.org/pub/python/>).
-
-The following are the LaTeX source files:
-
- api/*.tex Python/C API Reference Manual
- doc/*.tex Documenting Python
- ext/*.tex Extending and Embedding the Python Interpreter
- lib/*.tex Python Library Reference
- mac/*.tex Macintosh Library Modules
- ref/*.tex Python Reference Manual
- tut/*.tex Python Tutorial
- inst/*.tex Installing Python Modules
- dist/*.tex Distributing Python Modules
-
-Most use the "manual" document class and "python" package, derived from
-the old "myformat.sty" style file. The Macintosh Library Modules
-document uses the "howto" document class instead. These contains many
-macro definitions useful in documenting Python, and set some style
-parameters.
-
-There's a Makefile to call LaTeX and the other utilities in the right
-order and the right number of times. By default, it will build the
-HTML version of the documentation, but DVI, PDF, and PostScript can
-also be made. To view the generated HTML, point your favorite browser
-at the top-level index (html/index.html) after running "make".
-
-The Makefile can also produce DVI files for each document made; to
-preview them, use xdvi. PostScript is produced by the same Makefile
-target that produces the DVI files. This uses the dvips tool.
-Printing depends on local conventions; at our site, we use lpr. For
-example:
-
- make paper-letter/lib.ps # create lib.dvi and lib.ps
- xdvi paper-letter/lib.dvi # preview lib.dvi
- lpr paper-letter/lib.ps # print on default printer
-
-
-What if I find a bug?
----------------------
-
-First, check that the bug is present in the development version of the
-documentation at <http://www.python.org/dev/doc/devel/>; we may
-have already fixed it.
-
-If we haven't, tell us about it. We'd like the documentation to be
-complete and accurate, but have limited time. If you discover any
-inconsistencies between the documentation and implementation, or just
-have suggestions as to how to improve the documentation, let is know!
-Specific bugs and patches should be reported using our bug & patch
-databases at:
-
- http://sourceforge.net/projects/python
-
-Other suggestions or questions should be sent to the Python
-Documentation Team:
-
- docs@python.org
-
-Thanks!
-
-
-What tools do I need?
----------------------
-
-You need to install Python; some of the scripts used to produce the
-documentation are written in Python. You don't need this
-documentation to install Python; instructions are included in the
-README file in the Python distribution.
-
-The simplest way to get the rest of the tools in the configuration we
-used is to install the teTeX TeX distribution, versions 0.9 or newer.
-More information is available on teTeX at <http://www.tug.org/tetex/>.
-This is a Unix-only TeX distribution at this time. This documentation
-release was tested with the 1.0.7 release, but there have been no
-substantial changes since late in the 0.9 series, which we used
-extensively for previous versions without any difficulty.
-
-If you don't want to get teTeX, here is what you'll need:
-
-To create DVI, PDF, or PostScript files:
-
- - LaTeX2e, 1995/12/01 or newer. Older versions are likely to
- choke.
-
- - makeindex. This is used to produce the indexes for the
- library reference and Python/C API reference.
-
-To create PDF files:
-
- - pdflatex. We used the one in the teTeX distribution (pdfTeX
- version 3.14159-13d (Web2C 7.3.1) at the time of this
- writing). Versions even a couple of patchlevels earlier are
- highly likely to fail due to syntax changes for some of the
- pdftex primitives.
-
-To create PostScript files:
-
- - dvips. Most TeX installations include this. If you don't
- have one, check CTAN (<ftp://ctan.tug.org/tex-archive/>).
-
-To create info files:
-
- Note that info support is currently being revised using new
- conversion tools by Michael Ernst <mernst@cs.washington.edu>.
-
- - makeinfo. This is available from any GNU mirror.
-
- - emacs or xemacs. Emacs is available from the same place as
- makeinfo, and xemacs is available from ftp.xemacs.org.
-
- - Perl. Find the software at
- <http://language.perl.com/info/software.html>.
-
- - HTML::Element. If you don't have this installed, you can get
- this from CPAN. Use the command:
-
- perl -e 'use CPAN; CPAN::install("HTML::Element");'
-
- You may need to be root to do this.
-
-To create HTML files:
-
- - Perl 5.6.0 or newer. Find the software at
- <http://language.perl.com/info/software.html>.
-
- - LaTeX2HTML 99.2b8 or newer. Older versions are not
- supported; each version changes enough that supporting
- multiple versions is not likely to work. Many older
- versions don't work with Perl 5.6 as well. This also screws
- up code fragments. ;-( Releases are available at:
- <http://www.latex2html.org/>.
-
-
-I got a make error: "make: don't know how to make commontex/patchlevel.tex."
-----------------------------------------------------------------------------
-
-Your version of make doesn't support the 'shell' function. You will need to
-use a version which does, e.g. GNU make.
-
-
-LaTeX (or pdfLaTeX) ran out of memory; how can I fix it?
---------------------------------------------------------
-
-This is known to be a problem at least on Mac OS X, but it has been
-observed on other systems in the past.
-
-On some systems, the default sizes of some of the memory pools
-allocated by TeX needs to be changed; this is a configuration setting
-for installations based on web2c (most if not all installations).
-This is usually set in a file named texmf/web2c/texmf.cnf (where the
-top-level texmf/ directory is part of the TeX installation). If you
-get a "buffer overflow" warning from LaTeX, open that configuration
-file and look for the "main_memory.pdflatex" setting. If there is not
-one, you can add a line with the setting. The value 1500000 seems to
-be sufficient for formatting the Python documetantion.
-
-
-What if Times fonts are not available?
---------------------------------------
-
-As distributed, the LaTeX documents use PostScript Times fonts. This
-is done since they are much better looking and produce smaller
-PostScript files. If, however, your TeX installation does not support
-them, they may be easily disabled. Edit the file
-texinputs/pypaper.sty and comment out the line that starts
-"\RequirePackage{times}" by inserting a "%" character at the beginning
-of the line. If you're formatting the docs for A4 paper instead of
-US-Letter paper, change paper-a4/pypaper.sty instead. An alternative
-is to install the right fonts and LaTeX style file.
-
-
-What if I want to use A4 paper?
--------------------------------
-
-Instead of building the PostScript by giving the command "make ps",
-give the command "make PAPER=a4 ps"; the output will be produced in
-the paper-a4/ subdirectory. (You can use "make PAPER=a4 pdf" if you'd
-rather have PDF output.)
-
-
-Making HTML files
------------------
-
-The LaTeX documents can be converted to HTML using Nikos Drakos'
-LaTeX2HTML converter. See the Makefile; after some twiddling, "make"
-should do the trick.
-
-
-What else is in here?
----------------------
-
-There is a new LaTeX document class called "howto". This is used for
-the new series of Python HOWTO documents which is being coordinated by
-Andrew Kuchling <akuchlin@mems-exchange.org>. The file
-templates/howto.tex is a commented example which may be used as a
-template. A Python script to "do the right thing" to format a howto
-document is included as tools/mkhowto. These documents can be
-formatted as HTML, PDF, PostScript, or ASCII files. Use "mkhowto
---help" for information on using the formatting tool.
-
-For authors of module documentation, there is a file
-templates/module.tex which may be used as a template for a module
-section. This may be used in conjunction with either the howto or
-manual document class. Create the documentation for a new module by
-copying the template to lib<mymodule>.tex and editing according to the
-instructions in the comments.
-
-Documentation on the authoring Python documentation, including
-information about both style and markup, is available in the
-"Documenting Python" manual.
-
-
-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 "commontex/license.tex" for information on usage and
-redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-----------------------------------------------------------------------
diff --git a/Doc/TODO b/Doc/TODO
deleted file mode 100644
index 8a467fe..0000000
--- a/Doc/TODO
+++ /dev/null
@@ -1,74 +0,0 @@
-PYTHON DOCUMENTATION TO-DO LIST -*- indented-text -*-
-===============================
-
-General
--------
-
-* Figure out HTMLHelp generation for the Windows world.
-
-
-Python/C API
-------------
-
-* The "Very High Level Interface" in the API document has been
- requested; I guess it wouldn't hurt to fill in a bit there. Request
- by Albert Hofkamp <a.hofkamp@wtb.tue.nl>. (Partly done.)
-
-* Describe implementing types in C, including use of the 'self'
- parameter to the method implementation function. (Missing material
- mentioned in the Extending & Embedding manual, section 1.1; problem
- reported by Clay Spence <cspence@sarnoff.com>.) Heavily impacts one
- chapter of the Python/C API manual.
-
-* Missing PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords(),
- Py_BuildValue(). Information requested by Greg Kochanski
- <gpk@bell-labs.com>. PyEval_EvalCode() has also been requested.
-
-Extending & Embedding
----------------------
-
-* More information is needed about building dynamically linked
- extensions in C++. Specifically, the extensions must be linked
- against the C++ libraries (and possibly runtime). Also noted by
- Albert Hofkamp <a.hofkamp@wtb.tue.nl>.
-
-Reference Manual
-----------------
-
-* Document the Extended Call Syntax in the language reference.
- [Jeremy Hylton]
-
-* Document new comparison support for recursive objects (lang. ref.?
- library ref.? (cmp() function). [Jeremy Hylton]
-
-Library Reference
------------------
-
-* Update the pickle documentation to describe all of the current
- behavior; only a subset is described. __reduce__, etc. Partial
- update submitted by Jim Kerr <jbkerr@sr.hp.com>.
-
-* Update the httplib documentation to match Greg Stein's HTTP/1.1
- support and new classes. (Greg, this is yours!)
-
-Tutorial
---------
-
-* Update tutorial to use string methods and talk about backward
- compatibility of same.
-
-
-NOT WORTH THE TROUBLE
----------------------
-
-* In the indexes, some subitem entries are separated from the item
- entries by column- or page-breaks. Reported by Lorenzo M. Catucci
- <lorenzo@argon.roma2.infn.it>. This one will be hard; probably not
- really worth the pain. (Only an issue at all when a header-letter
- and the first index entry get separated -- can change as soon as we
- change the index entries in the text.) Also only a problem in the
- print version.
-
-* Fix problem with howto documents getting the last module synopsis
- twice (in \localmoduletable) so we can get rid of the ugly 'uniq'
- hack in tools/mkhowto. (Probably not worth the trouble of fixing.)
diff --git a/Doc/api/abstract.tex b/Doc/api/abstract.tex
deleted file mode 100644
index c5b53d7..0000000
--- a/Doc/api/abstract.tex
+++ /dev/null
@@ -1,1037 +0,0 @@
-\chapter{Abstract Objects Layer \label{abstract}}
-
-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
-\cfunction{PyList_New()}, but whose items have not been set to some
-non-\code{NULL} value yet.
-
-\section{Object Protocol \label{object}}
-
-\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags}
- Print an object \var{o}, on file \var{fp}. Returns \code{-1} on
- error. The flags argument is used to enable certain printing
- options. The only option currently supported is
- \constant{Py_PRINT_RAW}; if given, the \function{str()} of the
- object is written instead of the \function{repr()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, const char *attr_name}
- Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
- \code{0} otherwise. This is equivalent to the Python expression
- \samp{hasattr(\var{o}, \var{attr_name})}. This function always
- succeeds.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o,
- const char *attr_name}
- Retrieve an attribute named \var{attr_name} from object \var{o}.
- Returns the attribute value on success, or \NULL{} on failure.
- This is the equivalent of the Python expression
- \samp{\var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name}
- Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
- \code{0} otherwise. This is equivalent to the Python expression
- \samp{hasattr(\var{o}, \var{attr_name})}. This function always
- succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o,
- PyObject *attr_name}
- Retrieve an attribute named \var{attr_name} from object \var{o}.
- Returns the attribute value on success, or \NULL{} on failure. This
- is the equivalent of the Python expression
- \samp{\var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o,
- const char *attr_name, PyObject *v}
- Set the value of the attribute named \var{attr_name}, for object
- \var{o}, to the value \var{v}. Returns \code{-1} on failure. This
- is the equivalent of the Python statement
- \samp{\var{o}.\var{attr_name} = \var{v}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o,
- PyObject *attr_name, PyObject *v}
- Set the value of the attribute named \var{attr_name}, for object
- \var{o}, to the value \var{v}. Returns \code{-1} on failure. This
- is the equivalent of the Python statement
- \samp{\var{o}.\var{attr_name} = \var{v}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, const char *attr_name}
- Delete attribute named \var{attr_name}, for object \var{o}. Returns
- \code{-1} on failure. This is the equivalent of the Python
- statement: \samp{del \var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name}
- Delete attribute named \var{attr_name}, for object \var{o}. Returns
- \code{-1} on failure. This is the equivalent of the Python
- statement \samp{del \var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_RichCompare}{PyObject *o1,
- PyObject *o2, int opid}
- Compare the values of \var{o1} and \var{o2} using the operation
- specified by \var{opid}, which must be one of
- \constant{Py_LT},
- \constant{Py_LE},
- \constant{Py_EQ},
- \constant{Py_NE},
- \constant{Py_GT}, or
- \constant{Py_GE}, corresponding to
- \code{<},
- \code{<=},
- \code{==},
- \code{!=},
- \code{>}, or
- \code{>=} respectively. This is the equivalent of the Python expression
- \samp{\var{o1} op \var{o2}}, where \code{op} is the operator
- corresponding to \var{opid}. Returns the value of the comparison on
- success, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_RichCompareBool}{PyObject *o1,
- PyObject *o2, int opid}
- Compare the values of \var{o1} and \var{o2} using the operation
- specified by \var{opid}, which must be one of
- \constant{Py_LT},
- \constant{Py_LE},
- \constant{Py_EQ},
- \constant{Py_NE},
- \constant{Py_GT}, or
- \constant{Py_GE}, corresponding to
- \code{<},
- \code{<=},
- \code{==},
- \code{!=},
- \code{>}, or
- \code{>=} respectively. Returns \code{-1} on error, \code{0} if the
- result is false, \code{1} otherwise. This is the equivalent of the
- Python expression \samp{\var{o1} op \var{o2}}, where
- \code{op} is the operator corresponding to \var{opid}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result}
- Compare the values of \var{o1} and \var{o2} using a routine provided
- by \var{o1}, if one exists, otherwise with a routine provided by
- \var{o2}. The result of the comparison is returned in
- \var{result}. Returns \code{-1} on failure. This is the equivalent
- of the Python statement\bifuncindex{cmp} \samp{\var{result} =
- cmp(\var{o1}, \var{o2})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2}
- Compare the values of \var{o1} and \var{o2} using a routine provided
- by \var{o1}, if one exists, otherwise with a routine provided by
- \var{o2}. Returns the result of the comparison on success. On
- error, the value returned is undefined; use
- \cfunction{PyErr_Occurred()} to detect an error. This is equivalent
- to the Python expression\bifuncindex{cmp} \samp{cmp(\var{o1},
- \var{o2})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o}
- Compute a string representation of object \var{o}. Returns the
- string representation on success, \NULL{} on failure. This is the
- equivalent of the Python expression \samp{repr(\var{o})}. Called by
- the \function{repr()}\bifuncindex{repr} built-in function and by
- reverse quotes.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o}
- Compute a string representation of object \var{o}. Returns the
- string representation on success, \NULL{} on failure. This is the
- equivalent of the Python expression \samp{str(\var{o})}. Called by
- the \function{str()}\bifuncindex{str} built-in function and by the
- \keyword{print} statement.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Unicode}{PyObject *o}
- Compute a Unicode string representation of object \var{o}. Returns
- the Unicode string representation on success, \NULL{} on failure.
- This is the equivalent of the Python expression
- \samp{unicode(\var{o})}. Called by the
- \function{unicode()}\bifuncindex{unicode} built-in function.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject *inst, PyObject *cls}
- Returns \code{1} if \var{inst} is an instance of the class \var{cls}
- or a subclass of \var{cls}, or \code{0} if not. On error, returns
- \code{-1} and sets an exception. If \var{cls} is a type object
- rather than a class object, \cfunction{PyObject_IsInstance()}
- returns \code{1} if \var{inst} is of type \var{cls}. If \var{cls}
- is a tuple, the check will be done against every entry in \var{cls}.
- The result will be \code{1} when at least one of the checks returns
- \code{1}, otherwise it will be \code{0}. If \var{inst} is not a class
- instance and \var{cls} is neither a type object, nor a class object,
- nor a tuple, \var{inst} must have a \member{__class__} attribute
- --- the class relationship of the value of that attribute with
- \var{cls} will be used to determine the result of this function.
- \versionadded{2.1}
- \versionchanged[Support for a tuple as the second argument added]{2.2}
-\end{cfuncdesc}
-
-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 \var{B} is a
-subclass of \var{A}, if \var{A} is \var{B},
-\cfunction{PyObject_IsSubclass()} returns true. If \var{A} and
-\var{B} are different objects, \var{B}'s \member{__bases__} attribute
-is searched in a depth-first fashion for \var{A} --- the presence of
-the \member{__bases__} attribute is considered sufficient for this
-determination.
-
-\begin{cfuncdesc}{int}{PyObject_IsSubclass}{PyObject *derived,
- PyObject *cls}
- Returns \code{1} if the class \var{derived} is identical to or
- derived from the class \var{cls}, otherwise returns \code{0}. In
- case of an error, returns \code{-1}. If \var{cls}
- is a tuple, the check will be done against every entry in \var{cls}.
- The result will be \code{1} when at least one of the checks returns
- \code{1}, otherwise it will be \code{0}. If either \var{derived} or
- \var{cls} is not an actual class object (or tuple), this function
- uses the generic algorithm described above.
- \versionadded{2.1}
- \versionchanged[Older versions of Python did not support a tuple
- as the second argument]{2.3}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
- Determine if the object \var{o} is callable. Return \code{1} if the
- object is callable and \code{0} otherwise. This function always
- succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Call}{PyObject *callable_object,
- PyObject *args,
- PyObject *kw}
- Call a callable Python object \var{callable_object}, with arguments
- given by the tuple \var{args}, and named arguments given by the
- dictionary \var{kw}. If no named arguments are needed, \var{kw} may
- be \NULL{}. \var{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 \samp{\var{callable_object}(*\var{args}, **\var{kw})}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object,
- PyObject *args}
- Call a callable Python object \var{callable_object}, with arguments
- given by the tuple \var{args}. If no arguments are needed, then
- \var{args} may be \NULL. Returns the result of the call on
- success, or \NULL{} on failure. This is the equivalent of the
- Python expression \samp{\var{callable_object}(*\var{args})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable,
- char *format, \moreargs}
- Call a callable Python object \var{callable}, with a variable
- number of C arguments. The C arguments are described using a
- \cfunction{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 \samp{\var{callable}(*\var{args})}.
- Note that if you only pass \ctype{PyObject *} args,
- \cfunction{PyObject_CallFunctionObjArgs} is a faster alternative.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o,
- char *method, char *format,
- \moreargs}
- Call the method named \var{method} of object \var{o} with a variable
- number of C arguments. The C arguments are described by a
- \cfunction{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 \samp{\var{o}.\var{method}(\var{args})}.
- Note that if you only pass \ctype{PyObject *} args,
- \cfunction{PyObject_CallMethodObjArgs} is a faster alternative.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallFunctionObjArgs}{PyObject *callable,
- \moreargs,
- \code{NULL}}
- Call a callable Python object \var{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}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallMethodObjArgs}{PyObject *o,
- PyObject *name,
- \moreargs,
- \code{NULL}}
- Calls a method of the object \var{o}, where the name of the method
- is given as a Python string object in \var{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}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{long}{PyObject_Hash}{PyObject *o}
- Compute and return the hash value of an object \var{o}. On failure,
- return \code{-1}. This is the equivalent of the Python expression
- \samp{hash(\var{o})}.\bifuncindex{hash}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
- Returns \code{1} if the object \var{o} is considered to be true, and
- \code{0} otherwise. This is equivalent to the Python expression
- \samp{not not \var{o}}. On failure, return \code{-1}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_Not}{PyObject *o}
- Returns \code{0} if the object \var{o} is considered to be true, and
- \code{1} otherwise. This is equivalent to the Python expression
- \samp{not \var{o}}. On failure, return \code{-1}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o}
- When \var{o} is non-\NULL, returns a type object corresponding to
- the object type of object \var{o}. On failure, raises
- \exception{SystemError} and returns \NULL. This is equivalent to
- the Python expression \code{type(\var{o})}.\bifuncindex{type}
- This function increments the reference count of the return value.
- There's really no reason to use this function instead of the
- common expression \code{\var{o}->ob_type}, which returns a pointer
- of type \ctype{PyTypeObject*}, except when the incremented reference
- count is needed.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_TypeCheck}{PyObject *o, PyTypeObject *type}
- Return true if the object \var{o} is of type \var{type} or a subtype
- of \var{type}. Both parameters must be non-\NULL.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PyObject_Length}{PyObject *o}
-\cfuncline{Py_ssize_t}{PyObject_Size}{PyObject *o}
- Return the length of object \var{o}. If the object \var{o} provides
- either the sequence and mapping protocols, the sequence length is
- returned. On error, \code{-1} is returned. This is the equivalent
- to the Python expression \samp{len(\var{o})}.\bifuncindex{len}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key}
- Return element of \var{o} corresponding to the object \var{key} or
- \NULL{} on failure. This is the equivalent of the Python expression
- \samp{\var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o,
- PyObject *key, PyObject *v}
- Map the object \var{key} to the value \var{v}. Returns \code{-1} on
- failure. This is the equivalent of the Python statement
- \samp{\var{o}[\var{key}] = \var{v}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key}
- Delete the mapping for \var{key} from \var{o}. Returns \code{-1} on
- failure. This is the equivalent of the Python statement \samp{del
- \var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \method{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 \code{-1} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Dir}{PyObject *o}
- This is equivalent to the Python expression \samp{dir(\var{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 \samp{dir()}, returning the names
- of the current locals; in this case, if no execution frame is active
- then \NULL{} is returned but \cfunction{PyErr_Occurred()} will
- return false.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_GetIter}{PyObject *o}
- This is equivalent to the Python expression \samp{iter(\var{o})}.
- It returns a new iterator for the object argument, or the object
- itself if the object is already an iterator. Raises
- \exception{TypeError} and returns \NULL{} if the object cannot be
- iterated.
-\end{cfuncdesc}
-
-
-\section{Number Protocol \label{number}}
-
-\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
- Returns \code{1} if the object \var{o} provides numeric protocols,
- and false otherwise. This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2}
- Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
- failure. This is the equivalent of the Python expression
- \samp{\var{o1} + \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2}
- Returns the result of subtracting \var{o2} from \var{o1}, or \NULL{}
- on failure. This is the equivalent of the Python expression
- \samp{\var{o1} - \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2}
- Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{}
- on failure. This is the equivalent of the Python expression
- \samp{\var{o1} * \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2}
- Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
- failure. This is the equivalent of the Python expression
- \samp{\var{o1} / \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_FloorDivide}{PyObject *o1, PyObject *o2}
- Return the floor of \var{o1} divided by \var{o2}, or \NULL{} on
- failure. This is equivalent to the ``classic'' division of
- integers.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_TrueDivide}{PyObject *o1, PyObject *o2}
- Return a reasonable approximation for the mathematical value of
- \var{o1} divided by \var{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}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2}
- Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{}
- on failure. This is the equivalent of the Python expression
- \samp{\var{o1} \%\ \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2}
- See the built-in function \function{divmod()}\bifuncindex{divmod}.
- Returns \NULL{} on failure. This is the equivalent of the Python
- expression \samp{divmod(\var{o1}, \var{o2})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1,
- PyObject *o2, PyObject *o3}
- See the built-in function \function{pow()}\bifuncindex{pow}.
- Returns \NULL{} on failure. This is the equivalent of the Python
- expression \samp{pow(\var{o1}, \var{o2}, \var{o3})}, where \var{o3}
- is optional. If \var{o3} is to be ignored, pass \cdata{Py_None} in
- its place (passing \NULL{} for \var{o3} would cause an illegal
- memory access).
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
- Returns the negation of \var{o} on success, or \NULL{} on failure.
- This is the equivalent of the Python expression \samp{-\var{o}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
- Returns \var{o} on success, or \NULL{} on failure. This is the
- equivalent of the Python expression \samp{+\var{o}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
- Returns the absolute value of \var{o}, or \NULL{} on failure. This
- is the equivalent of the Python expression \samp{abs(\var{o})}.
- \bifuncindex{abs}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
- Returns the bitwise negation of \var{o} on success, or \NULL{} on
- failure. This is the equivalent of the Python expression
- \samp{\~\var{o}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2}
- Returns the result of left shifting \var{o1} by \var{o2} on success,
- or \NULL{} on failure. This is the equivalent of the Python
- expression \samp{\var{o1} <\code{<} \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2}
- Returns the result of right shifting \var{o1} by \var{o2} on
- success, or \NULL{} on failure. This is the equivalent of the
- Python expression \samp{\var{o1} >\code{>} \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2}
- Returns the ``bitwise and'' of \var{o1} and \var{o2} on success and
- \NULL{} on failure. This is the equivalent of the Python expression
- \samp{\var{o1} \&\ \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2}
- Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on
- success, or \NULL{} on failure. This is the equivalent of the
- Python expression \samp{\var{o1} \textasciicircum{} \var{o2}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2}
- Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
- \NULL{} on failure. This is the equivalent of the Python expression
- \samp{\var{o1} | \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAdd}{PyObject *o1, PyObject *o2}
- Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
- failure. The operation is done \emph{in-place} when \var{o1}
- supports it. This is the equivalent of the Python statement
- \samp{\var{o1} += \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceSubtract}{PyObject *o1,
- PyObject *o2}
- Returns the result of subtracting \var{o2} from \var{o1}, or \NULL{}
- on failure. The operation is done \emph{in-place} when \var{o1}
- supports it. This is the equivalent of the Python statement
- \samp{\var{o1} -= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceMultiply}{PyObject *o1,
- PyObject *o2}
- Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{}
- on failure. The operation is done \emph{in-place} when \var{o1}
- supports it. This is the equivalent of the Python statement
- \samp{\var{o1} *= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceDivide}{PyObject *o1,
- PyObject *o2}
- Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
- failure. The operation is done \emph{in-place} when \var{o1}
- supports it. This is the equivalent of the Python statement
- \samp{\var{o1} /= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceFloorDivide}{PyObject *o1,
- PyObject *o2}
- Returns the mathematical floor of dividing \var{o1} by \var{o2}, or
- \NULL{} on failure. The operation is done \emph{in-place} when
- \var{o1} supports it. This is the equivalent of the Python
- statement \samp{\var{o1} //= \var{o2}}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceTrueDivide}{PyObject *o1,
- PyObject *o2}
- Return a reasonable approximation for the mathematical value of
- \var{o1} divided by \var{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 \emph{in-place} when
- \var{o1} supports it.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRemainder}{PyObject *o1,
- PyObject *o2}
- Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{}
- on failure. The operation is done \emph{in-place} when \var{o1}
- supports it. This is the equivalent of the Python statement
- \samp{\var{o1} \%= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlacePower}{PyObject *o1,
- PyObject *o2, PyObject *o3}
- See the built-in function \function{pow()}.\bifuncindex{pow}
- Returns \NULL{} on failure. The operation is done \emph{in-place}
- when \var{o1} supports it. This is the equivalent of the Python
- statement \samp{\var{o1} **= \var{o2}} when o3 is \cdata{Py_None},
- or an in-place variant of \samp{pow(\var{o1}, \var{o2}, \var{o3})}
- otherwise. If \var{o3} is to be ignored, pass \cdata{Py_None} in its
- place (passing \NULL{} for \var{o3} would cause an illegal memory
- access).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceLshift}{PyObject *o1,
- PyObject *o2}
- Returns the result of left shifting \var{o1} by \var{o2} on success,
- or \NULL{} on failure. The operation is done \emph{in-place} when
- \var{o1} supports it. This is the equivalent of the Python
- statement \samp{\var{o1} <\code{<=} \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRshift}{PyObject *o1,
- PyObject *o2}
- Returns the result of right shifting \var{o1} by \var{o2} on
- success, or \NULL{} on failure. The operation is done
- \emph{in-place} when \var{o1} supports it. This is the equivalent
- of the Python statement \samp{\var{o1} >>= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAnd}{PyObject *o1, PyObject *o2}
- Returns the ``bitwise and'' of \var{o1} and \var{o2} on success and
- \NULL{} on failure. The operation is done \emph{in-place} when
- \var{o1} supports it. This is the equivalent of the Python
- statement \samp{\var{o1} \&= \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceXor}{PyObject *o1, PyObject *o2}
- Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on
- success, or \NULL{} on failure. The operation is done
- \emph{in-place} when \var{o1} supports it. This is the equivalent
- of the Python statement \samp{\var{o1} \textasciicircum= \var{o2}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceOr}{PyObject *o1, PyObject *o2}
- Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
- \NULL{} on failure. The operation is done \emph{in-place} when
- \var{o1} supports it. This is the equivalent of the Python
- statement \samp{\var{o1} |= \var{o2}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
- Returns the \var{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 \samp{int(\var{o})}.\bifuncindex{int}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
- Returns the \var{o} converted to a long integer object on success,
- or \NULL{} on failure. This is the equivalent of the Python
- expression \samp{long(\var{o})}.\bifuncindex{long}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o}
- Returns the \var{o} converted to a float object on success, or
- \NULL{} on failure. This is the equivalent of the Python expression
- \samp{float(\var{o})}.\bifuncindex{float}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Index}{PyObject *o}
- Returns the \var{o} converted to a Python int or long on success or \NULL{}
- with a TypeError exception raised on failure.
- \versionadded{2.5}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PyNumber_AsSsize_t}{PyObject *o, PyObject *exc}
- Returns \var{o} converted to a Py_ssize_t value if \var{o}
- can be interpreted as an integer. If \var{o} can be converted to a Python
- int or long but the attempt to convert to a Py_ssize_t value
- would raise an \exception{OverflowError}, then the \var{exc} argument
- is the type of exception that will be raised (usually \exception{IndexError}
- or \exception{OverflowError}). If \var{exc} is \NULL{}, then the exception
- is cleared and the value is clipped to \var{PY_SSIZE_T_MIN}
- for a negative integer or \var{PY_SSIZE_T_MAX} for a positive integer.
- \versionadded{2.5}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyIndex_Check}{PyObject *o}
- Returns True if \var{o} is an index integer (has the nb_index slot of
- the tp_as_number structure filled in).
- \versionadded{2.5}
-\end{cfuncdesc}
-
-
-\section{Sequence Protocol \label{sequence}}
-
-\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
- Return \code{1} if the object provides sequence protocol, and
- \code{0} otherwise. This function always succeeds.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PySequence_Size}{PyObject *o}
- Returns the number of objects in sequence \var{o} on success, and
- \code{-1} on failure. For objects that do not provide sequence
- protocol, this is equivalent to the Python expression
- \samp{len(\var{o})}.\bifuncindex{len}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PySequence_Length}{PyObject *o}
- Alternate name for \cfunction{PySequence_Size()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2}
- Return the concatenation of \var{o1} and \var{o2} on success, and
- \NULL{} on failure. This is the equivalent of the Python
- expression \samp{\var{o1} + \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, Py_ssize_t count}
- Return the result of repeating sequence object \var{o} \var{count}
- times, or \NULL{} on failure. This is the equivalent of the Python
- expression \samp{\var{o} * \var{count}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceConcat}{PyObject *o1,
- PyObject *o2}
- Return the concatenation of \var{o1} and \var{o2} on success, and
- \NULL{} on failure. The operation is done \emph{in-place} when
- \var{o1} supports it. This is the equivalent of the Python
- expression \samp{\var{o1} += \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceRepeat}{PyObject *o, Py_ssize_t count}
- Return the result of repeating sequence object \var{o} \var{count}
- times, or \NULL{} on failure. The operation is done \emph{in-place}
- when \var{o} supports it. This is the equivalent of the Python
- expression \samp{\var{o} *= \var{count}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, Py_ssize_t i}
- Return the \var{i}th element of \var{o}, or \NULL{} on failure.
- This is the equivalent of the Python expression
- \samp{\var{o}[\var{i}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, Py_ssize_t i1, Py_ssize_t i2}
- Return the slice of sequence object \var{o} between \var{i1} and
- \var{i2}, or \NULL{} on failure. This is the equivalent of the
- Python expression \samp{\var{o}[\var{i1}:\var{i2}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, Py_ssize_t i, PyObject *v}
- Assign object \var{v} to the \var{i}th element of \var{o}. Returns
- \code{-1} on failure. This is the equivalent of the Python
- statement \samp{\var{o}[\var{i}] = \var{v}}. This function \emph{does not}
- steal a reference to \var{v}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, Py_ssize_t i}
- Delete the \var{i}th element of object \var{o}. Returns \code{-1}
- on failure. This is the equivalent of the Python statement
- \samp{del \var{o}[\var{i}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, Py_ssize_t i1,
- Py_ssize_t i2, PyObject *v}
- Assign the sequence object \var{v} to the slice in sequence object
- \var{o} from \var{i1} to \var{i2}. This is the equivalent of the
- Python statement \samp{\var{o}[\var{i1}:\var{i2}] = \var{v}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, Py_ssize_t i1, Py_ssize_t i2}
- Delete the slice in sequence object \var{o} from \var{i1} to
- \var{i2}. Returns \code{-1} on failure. This is the equivalent of
- the Python statement \samp{del \var{o}[\var{i1}:\var{i2}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PySequence_Count}{PyObject *o, PyObject *value}
- Return the number of occurrences of \var{value} in \var{o}, that is,
- return the number of keys for which \code{\var{o}[\var{key}] ==
- \var{value}}. On failure, return \code{-1}. This is equivalent to
- the Python expression \samp{\var{o}.count(\var{value})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_Contains}{PyObject *o, PyObject *value}
- Determine if \var{o} contains \var{value}. If an item in \var{o} is
- equal to \var{value}, return \code{1}, otherwise return \code{0}.
- On error, return \code{-1}. This is equivalent to the Python
- expression \samp{\var{value} in \var{o}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PySequence_Index}{PyObject *o, PyObject *value}
- Return the first index \var{i} for which \code{\var{o}[\var{i}] ==
- \var{value}}. On error, return \code{-1}. This is equivalent to
- the Python expression \samp{\var{o}.index(\var{value})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_List}{PyObject *o}
- Return a list object with the same contents as the arbitrary
- sequence \var{o}. The returned list is guaranteed to be new.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
- Return a tuple object with the same contents as the arbitrary
- sequence \var{o} or \NULL{} on failure. If \var{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 \samp{tuple(\var{o})}.
- \bifuncindex{tuple}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Fast}{PyObject *o, const char *m}
- Returns the sequence \var{o} as a tuple, unless it is already a
- tuple or list, in which case \var{o} is returned. Use
- \cfunction{PySequence_Fast_GET_ITEM()} to access the members of the
- result. Returns \NULL{} on failure. If the object is not a
- sequence, raises \exception{TypeError} with \var{m} as the message
- text.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, Py_ssize_t i}
- Return the \var{i}th element of \var{o}, assuming that \var{o} was
- returned by \cfunction{PySequence_Fast()}, \var{o} is not \NULL,
- and that \var{i} is within bounds.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject**}{PySequence_Fast_ITEMS}{PyObject *o}
- Return the underlying array of PyObject pointers. Assumes that
- \var{o} was returned by \cfunction{PySequence_Fast()} and
- \var{o} is not \NULL.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_ITEM}{PyObject *o, Py_ssize_t i}
- Return the \var{i}th element of \var{o} or \NULL{} on failure.
- Macro form of \cfunction{PySequence_GetItem()} but without checking
- that \cfunction{PySequence_Check(\var{o})} is true and without
- adjustment for negative indices.
- \versionadded{2.3}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PySequence_Fast_GET_SIZE}{PyObject *o}
- Returns the length of \var{o}, assuming that \var{o} was
- returned by \cfunction{PySequence_Fast()} and that \var{o} is
- not \NULL. The size can also be gotten by calling
- \cfunction{PySequence_Size()} on \var{o}, but
- \cfunction{PySequence_Fast_GET_SIZE()} is faster because it can
- assume \var{o} is a list or tuple.
-\end{cfuncdesc}
-
-
-\section{Mapping Protocol \label{mapping}}
-
-\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
- Return \code{1} if the object provides mapping protocol, and
- \code{0} otherwise. This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{Py_ssize_t}{PyMapping_Length}{PyObject *o}
- Returns the number of keys in object \var{o} on success, and
- \code{-1} on failure. For objects that do not provide mapping
- protocol, this is equivalent to the Python expression
- \samp{len(\var{o})}.\bifuncindex{len}
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key}
- Remove the mapping for object \var{key} from the object \var{o}.
- Return \code{-1} on failure. This is equivalent to the Python
- statement \samp{del \var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key}
- Remove the mapping for object \var{key} from the object \var{o}.
- Return \code{-1} on failure. This is equivalent to the Python
- statement \samp{del \var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key}
- On success, return \code{1} if the mapping object has the key
- \var{key} and \code{0} otherwise. This is equivalent to the Python
- expression \samp{\var{o}.has_key(\var{key})}. This function always
- succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key}
- Return \code{1} if the mapping object has the key \var{key} and
- \code{0} otherwise. This is equivalent to the Python expression
- \samp{\var{o}.has_key(\var{key})}. This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o}
- On success, return a list of the keys in object \var{o}. On
- failure, return \NULL. This is equivalent to the Python expression
- \samp{\var{o}.keys()}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o}
- On success, return a list of the values in object \var{o}. On
- failure, return \NULL. This is equivalent to the Python expression
- \samp{\var{o}.values()}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
- On success, return a list of the items in object \var{o}, where each
- item is a tuple containing a key-value pair. On failure, return
- \NULL. This is equivalent to the Python expression
- \samp{\var{o}.items()}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key}
- Return element of \var{o} corresponding to the object \var{key} or
- \NULL{} on failure. This is the equivalent of the Python expression
- \samp{\var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject *o, char *key,
- PyObject *v}
- Map the object \var{key} to the value \var{v} in object \var{o}.
- Returns \code{-1} on failure. This is the equivalent of the Python
- statement \samp{\var{o}[\var{key}] = \var{v}}.
-\end{cfuncdesc}
-
-
-\section{Iterator Protocol \label{iterator}}
-
-\versionadded{2.2}
-
-There are only a couple of functions specifically for working with
-iterators.
-
-\begin{cfuncdesc}{int}{PyIter_Check}{PyObject *o}
- Return true if the object \var{o} supports the iterator protocol.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyIter_Next}{PyObject *o}
- Return the next value from the iteration \var{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, \exception{TypeError} is
- raised, or if there is an error in retrieving the item, returns
- \NULL{} and passes along the exception.
-\end{cfuncdesc}
-
-To write a loop which iterates over an iterator, the C code should
-look something like this:
-
-\begin{verbatim}
-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 */
-}
-\end{verbatim}
-
-
-\section{Buffer Protocol \label{abstract-buffer}}
-
-\begin{cfuncdesc}{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 \var{obj} argument must support the single-segment
- character buffer interface. On success, returns \code{0}, sets
- \var{buffer} to the memory location and \var{buffer_len} to the buffer
- length. Returns \code{-1} and sets a \exception{TypeError} on error.
- \versionadded{1.6}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \var{obj} argument must support the
- single-segment readable buffer interface. On success, returns
- \code{0}, sets \var{buffer} to the memory location and \var{buffer_len}
- to the buffer length. Returns \code{-1} and sets a
- \exception{TypeError} on error.
- \versionadded{1.6}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_CheckReadBuffer}{PyObject *o}
- Returns \code{1} if \var{o} supports the single-segment readable
- buffer interface. Otherwise returns \code{0}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_AsWriteBuffer}{PyObject *obj,
- void **buffer,
- Py_ssize_t *buffer_len}
- Returns a pointer to a writeable memory location. The \var{obj}
- argument must support the single-segment, character buffer
- interface. On success, returns \code{0}, sets \var{buffer} to the
- memory location and \var{buffer_len} to the buffer length. Returns
- \code{-1} and sets a \exception{TypeError} on error.
- \versionadded{1.6}
-\end{cfuncdesc}
diff --git a/Doc/api/api.tex b/Doc/api/api.tex
deleted file mode 100644
index cf28f5b..0000000
--- a/Doc/api/api.tex
+++ /dev/null
@@ -1,60 +0,0 @@
-\documentclass{manual}
-
-\title{Python/C API Reference Manual}
-
-\input{boilerplate}
-
-\makeindex % tell \index to actually write the .idx file
-
-
-\begin{document}
-
-\maketitle
-
-\ifhtml
-\chapter*{Front Matter\label{front}}
-\fi
-
-\input{copyright}
-
-\begin{abstract}
-
-\noindent
-This manual documents the API used by C and \Cpp{} programmers who
-want to write extension modules or embed Python. It is a companion to
-\citetitle[../ext/ext.html]{Extending and Embedding the Python
-Interpreter}, 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 incomplete. I hope
-that it is nevertheless useful. I will continue to work on it, and
-release new versions from time to time, independent from Python source
-code releases.}
-
-\end{abstract}
-
-\tableofcontents
-
-
-\input{intro}
-\input{veryhigh}
-\input{refcounting}
-\input{exceptions}
-\input{utilities}
-\input{abstract}
-\input{concrete}
-\input{init}
-\input{memory}
-\input{newtypes}
-
-
-\appendix
-\chapter{Reporting Bugs}
-\input{reportingbugs}
-
-\chapter{History and License}
-\input{license}
-
-\input{api.ind} % Index -- must be last
-
-\end{document}
diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex
deleted file mode 100644
index ddb19d0..0000000
--- a/Doc/api/concrete.tex
+++ /dev/null
@@ -1,3326 +0,0 @@
-\chapter{Concrete Objects Layer \label{concrete}}
-
-
-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
-\cfunction{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.}
-
-
-\section{Fundamental Objects \label{fundamental}}
-
-This section describes Python type objects and the singleton object
-\code{None}.
-
-
-\subsection{Type Objects \label{typeObjects}}
-
-\obindex{type}
-\begin{ctypedesc}{PyTypeObject}
- The C structure of the objects used to describe built-in types.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyObject*}{PyType_Type}
- This is the type object for type objects; it is the same object as
- \code{type} and \code{types.TypeType} in the Python layer.
- \withsubitem{(in module types)}{\ttindex{TypeType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyType_Check}{PyObject *o}
- Return true if the object \var{o} is a type object, including
- instances of types derived from the standard type object. Return
- false in all other cases.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyType_CheckExact}{PyObject *o}
- Return true if the object \var{o} is a type object, but not a
- subtype of the standard type object. Return false in all other
- cases.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature}
- Return true if the type object \var{o} sets the feature
- \var{feature}. Type features are denoted by single bit flags.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyType_IS_GC}{PyObject *o}
- Return true if the type object includes support for the cycle
- detector; this tests the type flag \constant{Py_TPFLAGS_HAVE_GC}.
- \versionadded{2.0}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyType_IsSubtype}{PyTypeObject *a, PyTypeObject *b}
- Return true if \var{a} is a subtype of \var{b}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type,
- Py_ssize_t nitems}
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyType_GenericNew}{PyTypeObject *type,
- PyObject *args, PyObject *kwds}
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \code{0}
- on success, or return \code{-1} and sets an exception on error.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\subsection{The None Object \label{noneObject}}
-
-\obindex{None}
-Note that the \ctype{PyTypeObject} for \code{None} is not directly
-exposed in the Python/C API. Since \code{None} is a singleton,
-testing for object identity (using \samp{==} in C) is sufficient.
-There is no \cfunction{PyNone_Check()} function for the same reason.
-
-\begin{cvardesc}{PyObject*}{Py_None}
- The Python \code{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.
-\end{cvardesc}
-
-\begin{csimplemacrodesc}{Py_RETURN_NONE}
- Properly handle returning \cdata{Py_None} from within a C function.
- \versionadded{2.4}
-\end{csimplemacrodesc}
-
-
-\section{Numeric Objects \label{numericObjects}}
-
-\obindex{numeric}
-
-
-\subsection{Plain Integer Objects \label{intObjects}}
-
-\obindex{integer}
-\begin{ctypedesc}{PyIntObject}
- This subtype of \ctype{PyObject} represents a Python integer
- object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyInt_Type}
- This instance of \ctype{PyTypeObject} represents the Python plain
- integer type. This is the same object as \code{int} and
- \code{types.IntType}.
- \withsubitem{(in modules types)}{\ttindex{IntType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *o}
- Return true if \var{o} is of type \cdata{PyInt_Type} or a subtype
- of \cdata{PyInt_Type}.
- \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyInt_CheckExact}{PyObject *o}
- Return true if \var{o} is of type \cdata{PyInt_Type}, but not a
- subtype of \cdata{PyInt_Type}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyInt_FromString}{char *str, char **pend,
- int base}
- Return a new \ctype{PyIntObject} or \ctype{PyLongObject} based on the
- string value in \var{str}, which is interpreted according to the radix in
- \var{base}. If \var{pend} is non-\NULL{}, \code{*\var{pend}} will point to
- the first character in \var{str} which follows the representation of the
- number. If \var{base} is \code{0}, the radix will be determined based on
- the leading characters of \var{str}: if \var{str} starts with \code{'0x'}
- or \code{'0X'}, radix 16 will be used; if \var{str} starts with
- \code{'0'}, radix 8 will be used; otherwise radix 10 will be used. If
- \var{base} is not \code{0}, it must be between \code{2} and \code{36},
- inclusive. Leading spaces are ignored. If there are no digits,
- \exception{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
- Create a new integer object with a value of \var{ival}.
-
- The current implementation keeps an array of integer objects for all
- integers between \code{-5} and \code{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 \code{1}. I
- suspect the behaviour of Python in this case is undefined. :-)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyInt_FromSsize_t}{Py_ssize_t ival}
- Create a new integer object with a value of \var{ival}.
- If the value exceeds \code{LONG_MAX}, a long integer object is
- returned.
-
- \versionadded{2.5}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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, \code{-1} is returned, and the caller should check
- \code{PyErr_Occurred()} to find out whether there was an error, or
- whether the value just happened to be -1.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io}
- Return the value of the object \var{io}. No error checking is
- performed.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyInt_GetMax}{}
- Return the system's idea of the largest integer it can handle
- (\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system
- header files).
-\end{cfuncdesc}
-
-\subsection{Boolean Objects \label{boolObjects}}
-
-Booleans in Python are implemented as a subclass of integers. There
-are only two booleans, \constant{Py_False} and \constant{Py_True}. As
-such, the normal creation and deletion functions don't apply to
-booleans. The following macros are available, however.
-
-\begin{cfuncdesc}{int}{PyBool_Check}{PyObject *o}
- Return true if \var{o} is of type \cdata{PyBool_Type}.
- \versionadded{2.3}
-\end{cfuncdesc}
-
-\begin{cvardesc}{PyObject*}{Py_False}
- The Python \code{False} object. This object has no methods. It needs to
- be treated just like any other object with respect to reference counts.
-\end{cvardesc}
-
-\begin{cvardesc}{PyObject*}{Py_True}
- The Python \code{True} object. This object has no methods. It needs to
- be treated just like any other object with respect to reference counts.
-\end{cvardesc}
-
-\begin{csimplemacrodesc}{Py_RETURN_FALSE}
- Return \constant{Py_False} from a function, properly incrementing its
- reference count.
-\versionadded{2.4}
-\end{csimplemacrodesc}
-
-\begin{csimplemacrodesc}{Py_RETURN_TRUE}
- Return \constant{Py_True} from a function, properly incrementing its
- reference count.
-\versionadded{2.4}
-\end{csimplemacrodesc}
-
-\begin{cfuncdesc}{PyObject*}{PyBool_FromLong}{long v}
- Return a new reference to \constant{Py_True} or \constant{Py_False}
- depending on the truth value of \var{v}.
-\versionadded{2.3}
-\end{cfuncdesc}
-
-\subsection{Long Integer Objects \label{longObjects}}
-
-\obindex{long integer}
-\begin{ctypedesc}{PyLongObject}
- This subtype of \ctype{PyObject} represents a Python long integer
- object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyLong_Type}
- This instance of \ctype{PyTypeObject} represents the Python long
- integer type. This is the same object as \code{long} and
- \code{types.LongType}.
- \withsubitem{(in modules types)}{\ttindex{LongType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
- Return true if its argument is a \ctype{PyLongObject} or a subtype
- of \ctype{PyLongObject}.
- \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyLong_CheckExact}{PyObject *p}
- Return true if its argument is a \ctype{PyLongObject}, but not a
- subtype of \ctype{PyLongObject}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
- Return a new \ctype{PyLongObject} object from \var{v}, or \NULL{}
- on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
- Return a new \ctype{PyLongObject} object from a C \ctype{unsigned
- long}, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{PY_LONG_LONG v}
- Return a new \ctype{PyLongObject} object from a C \ctype{long long},
- or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
- Return a new \ctype{PyLongObject} object from the integer part of
- \var{v}, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
- int base}
- Return a new \ctype{PyLongObject} based on the string value in
- \var{str}, which is interpreted according to the radix in
- \var{base}. If \var{pend} is non-\NULL{}, \code{*\var{pend}} will
- point to the first character in \var{str} which follows the
- representation of the number. If \var{base} is \code{0}, the radix
- will be determined based on the leading characters of \var{str}: if
- \var{str} starts with \code{'0x'} or \code{'0X'}, radix 16 will be
- used; if \var{str} starts with \code{'0'}, radix 8 will be used;
- otherwise radix 10 will be used. If \var{base} is not \code{0}, it
- must be between \code{2} and \code{36}, inclusive. Leading spaces
- are ignored. If there are no digits, \exception{ValueError} will be
- raised.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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, \var{u}, points to the first character
- of the Unicode string, \var{length} gives the number of characters,
- and \var{base} is the radix for the conversion. The radix must be
- in the range [2, 36]; if it is out of range, \exception{ValueError}
- will be raised.
- \versionadded{1.6}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromVoidPtr}{void *p}
- Create a Python integer or long integer from the pointer \var{p}.
- The pointer value can be retrieved from the resulting value using
- \cfunction{PyLong_AsVoidPtr()}.
- \versionadded{1.5.2}
- \versionchanged[If the integer is larger than LONG_MAX,
- a positive long integer is returned]{2.5}
- \end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
- Return a C \ctype{long} representation of the contents of
- \var{pylong}. If \var{pylong} is greater than
- \constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError}
- is raised.
- \withsubitem{(built-in exception)}{\ttindex{OverflowError}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
- Return a C \ctype{unsigned long} representation of the contents of
- \var{pylong}. If \var{pylong} is greater than
- \constant{ULONG_MAX}\ttindex{ULONG_MAX}, an
- \exception{OverflowError} is raised.
- \withsubitem{(built-in exception)}{\ttindex{OverflowError}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PY_LONG_LONG}{PyLong_AsLongLong}{PyObject *pylong}
- Return a C \ctype{long long} from a Python long integer. If
- \var{pylong} cannot be represented as a \ctype{long long}, an
- \exception{OverflowError} will be raised.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyLong_AsUnsignedLongLong}{PyObject
- *pylong}
- Return a C \ctype{unsigned long long} from a Python long integer.
- If \var{pylong} cannot be represented as an \ctype{unsigned long
- long}, an \exception{OverflowError} will be raised if the value is
- positive, or a \exception{TypeError} will be raised if the value is
- negative.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLongMask}{PyObject *io}
- Return a C \ctype{unsigned long} from a Python long integer, without
- checking for overflow.
- \versionadded{2.3}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
- Return a C \ctype{double} representation of the contents of
- \var{pylong}. If \var{pylong} cannot be approximately represented
- as a \ctype{double}, an \exception{OverflowError} exception is
- raised and \code{-1.0} will be returned.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void*}{PyLong_AsVoidPtr}{PyObject *pylong}
- Convert a Python integer or long integer \var{pylong} to a C
- \ctype{void} pointer. If \var{pylong} cannot be converted, an
- \exception{OverflowError} will be raised. This is only assured to
- produce a usable \ctype{void} pointer for values created with
- \cfunction{PyLong_FromVoidPtr()}.
- \versionadded{1.5.2}
- \versionchanged[For values outside 0..LONG_MAX, both signed and
- unsigned integers are acccepted]{2.5}
-\end{cfuncdesc}
-
-
-\subsection{Floating Point Objects \label{floatObjects}}
-
-\obindex{floating point}
-\begin{ctypedesc}{PyFloatObject}
- This subtype of \ctype{PyObject} represents a Python floating point
- object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyFloat_Type}
- This instance of \ctype{PyTypeObject} represents the Python floating
- point type. This is the same object as \code{float} and
- \code{types.FloatType}.
- \withsubitem{(in modules types)}{\ttindex{FloatType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
- Return true if its argument is a \ctype{PyFloatObject} or a subtype
- of \ctype{PyFloatObject}.
- \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFloat_CheckExact}{PyObject *p}
- Return true if its argument is a \ctype{PyFloatObject}, but not a
- subtype of \ctype{PyFloatObject}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFloat_FromString}{PyObject *str}
- Create a \ctype{PyFloatObject} object based on the string value in
- \var{str}, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
- Create a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on
- failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
- Return a C \ctype{double} representation of the contents of
- \var{pyfloat}. If \var{pyfloat} is not a Python floating point
- object but has a \method{__float__} method, this method will first
- be called to convert \var{pyfloat} into a float.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
- Return a C \ctype{double} representation of the contents of
- \var{pyfloat}, but without error checking.
-\end{cfuncdesc}
-
-
-\subsection{Complex Number Objects \label{complexObjects}}
-
-\obindex{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.
-
-\subsubsection{Complex Numbers as C Structures}
-
-Note that the functions which accept these structures as parameters
-and return them as results do so \emph{by value} rather than
-dereferencing them through pointers. This is consistent throughout
-the API.
-
-\begin{ctypedesc}{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:
-
-\begin{verbatim}
-typedef struct {
- double real;
- double imag;
-} Py_complex;
-\end{verbatim}
-\end{ctypedesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex}
- Return the negation of the complex number \var{complex}, using the C
- \ctype{Py_complex} representation.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp}
- Return the exponentiation of \var{num} by \var{exp}, using the C
- \ctype{Py_complex} representation.
-\end{cfuncdesc}
-
-
-\subsubsection{Complex Numbers as Python Objects}
-
-\begin{ctypedesc}{PyComplexObject}
- This subtype of \ctype{PyObject} represents a Python complex number
- object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyComplex_Type}
- This instance of \ctype{PyTypeObject} represents the Python complex
- number type. It is the same object as \code{complex} and
- \code{types.ComplexType}.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
- Return true if its argument is a \ctype{PyComplexObject} or a
- subtype of \ctype{PyComplexObject}.
- \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyComplex_CheckExact}{PyObject *p}
- Return true if its argument is a \ctype{PyComplexObject}, but not a
- subtype of \ctype{PyComplexObject}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
- Create a new Python complex number object from a C
- \ctype{Py_complex} value.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
- Return a new \ctype{PyComplexObject} object from \var{real} and
- \var{imag}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
- Return the real part of \var{op} as a C \ctype{double}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
- Return the imaginary part of \var{op} as a C \ctype{double}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
- Return the \ctype{Py_complex} value of the complex number \var{op}.
- \versionchanged[If \var{op} is not a Python complex number object
- but has a \method{__complex__} method, this method
- will first be called to convert \var{op} to a Python
- complex number object]{2.6}
-\end{cfuncdesc}
-
-
-
-\section{Sequence Objects \label{sequenceObjects}}
-
-\obindex{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.
-
-
-\subsection{String Objects \label{stringObjects}}
-
-These functions raise \exception{TypeError} when expecting a string
-parameter and are called with a non-string parameter.
-
-\obindex{string}
-\begin{ctypedesc}{PyStringObject}
- This subtype of \ctype{PyObject} represents a Python string object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyString_Type}
- This instance of \ctype{PyTypeObject} represents the Python string
- type; it is the same object as \code{str} and \code{types.StringType}
- in the Python layer.
- \withsubitem{(in module types)}{\ttindex{StringType}}.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
- Return true if the object \var{o} is a string object or an instance
- of a subtype of the string type.
- \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_CheckExact}{PyObject *o}
- Return true if the object \var{o} is a string object, but not an
- instance of a subtype of the string type.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
- Return a new string object with a copy of the string \var{v} as value
- on success, and \NULL{} on failure. The parameter \var{v} must not be
- \NULL{}; it will not be checked.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
- Py_ssize_t len}
- Return a new string object with a copy of the string \var{v} as value
- and length \var{len} on success, and \NULL{} on failure. If \var{v} is
- \NULL{}, the contents of the string are uninitialized.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromFormat}{const char *format, ...}
- Take a C \cfunction{printf()}-style \var{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 \var{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.
-
- \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment}
- \lineiii{\%\%}{\emph{n/a}}{The literal \% character.}
- \lineiii{\%c}{int}{A single character, represented as an C int.}
- \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
- \lineiii{\%u}{unsigned int}{Exactly equivalent to \code{printf("\%u")}.}
- \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
- \lineiii{\%lu}{unsigned long}{Exactly equivalent to \code{printf("\%lu")}.}
- \lineiii{\%zd}{Py_ssize_t}{Exactly equivalent to \code{printf("\%zd")}.}
- \lineiii{\%zu}{size_t}{Exactly equivalent to \code{printf("\%zu")}.}
- \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
- \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
- \lineiii{\%s}{char*}{A null-terminated C character array.}
- \lineiii{\%p}{void*}{The hex representation of a C pointer.
- Mostly equivalent to \code{printf("\%p")} except that it is
- guaranteed to start with the literal \code{0x} regardless of
- what the platform's \code{printf} yields.}
- \end{tableiii}
-
- 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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromFormatV}{const char *format,
- va_list vargs}
- Identical to \function{PyString_FromFormat()} except that it takes
- exactly two arguments.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PyString_Size}{PyObject *string}
- Return the length of the string in string object \var{string}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PyString_GET_SIZE}{PyObject *string}
- Macro form of \cfunction{PyString_Size()} but without error
- checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
- Return a NUL-terminated representation of the contents of
- \var{string}. The pointer refers to the internal buffer of
- \var{string}, not a copy. The data must not be modified in any way,
- unless the string was just created using
- \code{PyString_FromStringAndSize(NULL, \var{size})}.
- It must not be deallocated. If \var{string} is a Unicode object,
- this function computes the default encoding of \var{string} and
- operates on that. If \var{string} is not a string object at all,
- \cfunction{PyString_AsString()} returns \NULL{} and raises
- \exception{TypeError}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string}
- Macro form of \cfunction{PyString_AsString()} but without error
- checking. Only string objects are supported; no Unicode objects
- should be passed.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj,
- char **buffer,
- Py_ssize_t *length}
- Return a NUL-terminated representation of the contents of the
- object \var{obj} through the output variables \var{buffer} and
- \var{length}.
-
- The function accepts both string and Unicode objects as input. For
- Unicode objects it returns the default encoded version of the
- object. If \var{length} is \NULL{}, the resulting buffer may not
- contain NUL characters; if it does, the function returns \code{-1}
- and a \exception{TypeError} is raised.
-
- The buffer refers to an internal string buffer of \var{obj}, not a
- copy. The data must not be modified in any way, unless the string
- was just created using \code{PyString_FromStringAndSize(NULL,
- \var{size})}. It must not be deallocated. If \var{string} is a
- Unicode object, this function computes the default encoding of
- \var{string} and operates on that. If \var{string} is not a string
- object at all, \cfunction{PyString_AsStringAndSize()} returns
- \code{-1} and raises \exception{TypeError}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
- PyObject *newpart}
- Create a new string object in \var{*string} containing the contents
- of \var{newpart} appended to \var{string}; the caller will own the
- new reference. The reference to the old value of \var{string} will
- be stolen. If the new string cannot be created, the old reference
- to \var{string} will still be discarded and the value of
- \var{*string} will be set to \NULL{}; the appropriate exception will
- be set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
- PyObject *newpart}
- Create a new string object in \var{*string} containing the contents
- of \var{newpart} appended to \var{string}. This version decrements
- the reference count of \var{newpart}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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, \var{*string}
- holds the resized string object and \code{0} is returned; the address in
- \var{*string} may differ from its input value. If the
- reallocation fails, the original string object at \var{*string} is
- deallocated, \var{*string} is set to \NULL{}, a memory exception is set,
- and \code{-1} is returned.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
- PyObject *args}
- Return a new string object from \var{format} and \var{args}.
- Analogous to \code{\var{format} \%\ \var{args}}. The \var{args}
- argument must be a tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string}
- Intern the argument \var{*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
- \var{*string}, it sets \var{*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
- \var{*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.)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v}
- A combination of \cfunction{PyString_FromString()} and
- \cfunction{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s,
- Py_ssize_t size,
- const char *encoding,
- const char *errors}
- Create an object by decoding \var{size} bytes of the encoded
- buffer \var{s} using the codec registered for
- \var{encoding}. \var{encoding} and \var{errors} have the same
- meaning as the parameters of the same name in the
- \function{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_AsDecodedObject}{PyObject *str,
- const char *encoding,
- const char *errors}
- Decode a string object by passing it to the codec registered for
- \var{encoding} and return the result as Python
- object. \var{encoding} and \var{errors} have the same meaning as the
- parameters of the same name in the string \method{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \var{encoding} and return a Python object.
- \var{encoding} and \var{errors} have the same meaning as the
- parameters of the same name in the string \method{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_AsEncodedObject}{PyObject *str,
- const char *encoding,
- const char *errors}
- Encode a string object using the codec registered for
- \var{encoding} and return the result as Python object.
- \var{encoding} and \var{errors} have the same meaning as the
- parameters of the same name in the string \method{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.
-\end{cfuncdesc}
-
-
-\subsection{Unicode Objects \label{unicodeObjects}}
-\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
-
-%--- Unicode Type -------------------------------------------------------
-
-These are the basic Unicode object types used for the Unicode
-implementation in Python:
-
-\begin{ctypedesc}{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).
-\end{ctypedesc}
-
-Note that UCS2 and UCS4 Python builds are not binary compatible.
-Please keep this in mind when writing extensions or interfaces.
-
-\begin{ctypedesc}{PyUnicodeObject}
- This subtype of \ctype{PyObject} represents a Python Unicode object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
- This instance of \ctype{PyTypeObject} represents the Python Unicode
- type. It is exposed to Python code as \code{unicode} and
- \code{types.UnicodeType}.
-\end{cvardesc}
-
-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:
-
-\begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
- Return true if the object \var{o} is a Unicode object or an
- instance of a Unicode subtype.
- \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_CheckExact}{PyObject *o}
- Return true if the object \var{o} is a Unicode object, but not an
- instance of a subtype.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GET_SIZE}{PyObject *o}
- Return the size of the object. \var{o} has to be a
- \ctype{PyUnicodeObject} (not checked).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GET_DATA_SIZE}{PyObject *o}
- Return the size of the object's internal buffer in bytes. \var{o}
- has to be a \ctype{PyUnicodeObject} (not checked).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o}
- Return a pointer to the internal \ctype{Py_UNICODE} buffer of the
- object. \var{o} has to be a \ctype{PyUnicodeObject} (not checked).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o}
- Return a pointer to the internal buffer of the object.
- \var{o} has to be a \ctype{PyUnicodeObject} (not checked).
-\end{cfuncdesc}
-
-% --- Unicode character properties ---------------------------------------
-
-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.
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch}
- Return 1 or 0 depending on whether \var{ch} is a whitespace
- character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch}
- Return 1 or 0 depending on whether \var{ch} is a lowercase character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch}
- Return 1 or 0 depending on whether \var{ch} is an uppercase
- character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch}
- Return 1 or 0 depending on whether \var{ch} is a titlecase character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch}
- Return 1 or 0 depending on whether \var{ch} is a linebreak character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch}
- Return 1 or 0 depending on whether \var{ch} is a decimal character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch}
- Return 1 or 0 depending on whether \var{ch} is a digit character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch}
- Return 1 or 0 depending on whether \var{ch} is a numeric character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch}
- Return 1 or 0 depending on whether \var{ch} is an alphabetic
- character.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch}
- Return 1 or 0 depending on whether \var{ch} is an alphanumeric
- character.
-\end{cfuncdesc}
-
-These APIs can be used for fast direct character conversions:
-
-\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch}
- Return the character \var{ch} converted to lower case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch}
- Return the character \var{ch} converted to upper case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch}
- Return the character \var{ch} converted to title case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch}
- Return the character \var{ch} converted to a decimal positive
- integer. Return \code{-1} if this is not possible. This macro
- does not raise exceptions.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch}
- Return the character \var{ch} converted to a single digit integer.
- Return \code{-1} if this is not possible. This macro does not raise
- exceptions.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch}
- Return the character \var{ch} converted to a double.
- Return \code{-1.0} if this is not possible. This macro does not raise
- exceptions.
-\end{cfuncdesc}
-
-% --- Plain Py_UNICODE ---------------------------------------------------
-
-To create Unicode objects and access their basic sequence properties,
-use these APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u,
- Py_ssize_t size}
- Create a Unicode Object from the Py_UNICODE buffer \var{u} of the
- given size. \var{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
- \var{u} is \NULL{}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromStringAndSize}{const char *u,
- Py_ssize_t size}
- Create a Unicode Object from the char buffer \var{u}.
- The bytes will be interpreted as being UTF-8 encoded.
- \var{u} may also 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 \var{u} is \NULL{}.
- \versionadded{3.0}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromString}{const char*u}
- Create a Unicode object from an UTF-8 encoded null-terminated
- char buffer \var{u}.
- \versionadded{3.0}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromFormat}{const char *format, ...}
- Take a C \cfunction{printf()}-style \var{format} string and a
- variable number of arguments, calculate the size of the resulting
- Python unicode 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 \var{format} string. The
- following format characters are allowed:
-
- % 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.
-
- \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment}
- \lineiii{\%\%}{\emph{n/a}}{The literal \% character.}
- \lineiii{\%c}{int}{A single character, represented as an C int.}
- \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
- \lineiii{\%u}{unsigned int}{Exactly equivalent to \code{printf("\%u")}.}
- \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
- \lineiii{\%lu}{unsigned long}{Exactly equivalent to \code{printf("\%lu")}.}
- \lineiii{\%zd}{Py_ssize_t}{Exactly equivalent to \code{printf("\%zd")}.}
- \lineiii{\%zu}{size_t}{Exactly equivalent to \code{printf("\%zu")}.}
- \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
- \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
- \lineiii{\%s}{char*}{A null-terminated C character array.}
- \lineiii{\%p}{void*}{The hex representation of a C pointer.
- Mostly equivalent to \code{printf("\%p")} except that it is
- guaranteed to start with the literal \code{0x} regardless of
- what the platform's \code{printf} yields.}
- \lineiii{\%U}{PyObject*}{A unicode object.}
- \lineiii{\%V}{PyObject*, char *}{A unicode object (which may be \NULL{})
- and a null-terminated C character array as a second parameter (which
- will be used, if the first parameter is \NULL{}).}
- \lineiii{\%S}{PyObject*}{The result of calling \function{PyObject_Unicode()}.}
- \lineiii{\%R}{PyObject*}{The result of calling \function{PyObject_Repr()}.}
- \end{tableiii}
-
- 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.
- \versionadded{3.0}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromFormatV}{const char *format,
- va_list vargs}
- Identical to \function{PyUnicode_FromFormat()} except that it takes
- exactly two arguments.
- \versionadded{3.0}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode}
- Return a read-only pointer to the Unicode object's internal
- \ctype{Py_UNICODE} buffer, \NULL{} if \var{unicode} is not a Unicode
- object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_GetSize}{PyObject *unicode}
- Return the length of the Unicode object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromEncodedObject}{PyObject *obj,
- const char *encoding,
- const char *errors}
- Coerce an encoded object \var{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
- \exception{TypeError} to be set.
-
- The API returns \NULL{} if there was an error. The caller is
- responsible for decref'ing the returned objects.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj}
- Shortcut for \code{PyUnicode_FromEncodedObject(obj, NULL, "strict")}
- which is used throughout the interpreter whenever coercion to
- Unicode is needed.
-\end{cfuncdesc}
-
-% --- wchar_t support for platforms which support it ---------------------
-
-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}.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_FromWideChar}{const wchar_t *w,
- Py_ssize_t size}
- Create a Unicode object from the \ctype{wchar_t} buffer \var{w} of
- the given size. Return \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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
- \var{w}. At most \var{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.
-\end{cfuncdesc}
-
-
-\subsubsection{Built-in Codecs \label{builtinCodecs}}
-
-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''
-(\exception{ValueError} is raised).
-
-The codecs all use a similar interface. Only deviation from the
-following generic ones are documented for simplicity.
-
-% --- Generic Codecs -----------------------------------------------------
-
-These are the generic codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s,
- Py_ssize_t size,
- const char *encoding,
- const char *errors}
- Create a Unicode object by decoding \var{size} bytes of the encoded
- string \var{s}. \var{encoding} and \var{errors} have the same
- meaning as the parameters of the same name in the
- \function{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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. \var{encoding} and \var{errors} have the
- same meaning as the parameters of the same name in the Unicode
- \method{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode,
- const char *encoding,
- const char *errors}
- Encode a Unicode object and return the result as Python string
- object. \var{encoding} and \var{errors} have the same meaning as the
- parameters of the same name in the Unicode \method{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.
-\end{cfuncdesc}
-
-% --- UTF-8 Codecs -------------------------------------------------------
-
-These are the UTF-8 codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s,
- Py_ssize_t size,
- const char *errors}
- Create a Unicode object by decoding \var{size} bytes of the UTF-8
- encoded string \var{s}. Return \NULL{} if an exception was raised
- by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8Stateful}{const char *s,
- Py_ssize_t size,
- const char *errors,
- Py_ssize_t *consumed}
- If \var{consumed} is \NULL{}, behave like \cfunction{PyUnicode_DecodeUTF8()}.
- If \var{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 \var{consumed}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-% --- UTF-16 Codecs ------------------------------------------------------ */
-
-These are the UTF-16 codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s,
- Py_ssize_t size,
- const char *errors,
- int *byteorder}
- Decode \var{length} bytes from a UTF-16 encoded buffer string and
- return the corresponding Unicode object. \var{errors} (if
- non-\NULL{}) defines the error handling. It defaults to ``strict''.
-
- If \var{byteorder} is non-\NULL{}, the decoder starts decoding using
- the given byte order:
-
-\begin{verbatim}
- *byteorder == -1: little endian
- *byteorder == 0: native order
- *byteorder == 1: big endian
-\end{verbatim}
-
- 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, \var{*byteorder}
- is set to the current byte order at the.
-
- If \var{byteorder} is \NULL{}, the codec starts in native order mode.
-
- Return \NULL{} if an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16Stateful}{const char *s,
- Py_ssize_t size,
- const char *errors,
- int *byteorder,
- Py_ssize_t *consumed}
- If \var{consumed} is \NULL{}, behave like
- \cfunction{PyUnicode_DecodeUTF16()}. If \var{consumed} is not \NULL{},
- \cfunction{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 \var{consumed}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \var{s}. If \var{byteorder} is not \code{0},
- output is written according to the following byte order:
-
-\begin{verbatim}
- byteorder == -1: little endian
- byteorder == 0: native byte order (writes a BOM mark)
- byteorder == 1: big endian
-\end{verbatim}
-
- If byteorder is \code{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 \var{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-% --- Unicode-Escape Codecs ----------------------------------------------
-
-These are the ``Unicode Escape'' codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s,
- Py_ssize_t size,
- const char *errors}
- Create a Unicode object by decoding \var{size} bytes of the
- Unicode-Escape encoded string \var{s}. Return \NULL{} if an
- exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-% --- Raw-Unicode-Escape Codecs ------------------------------------------
-
-These are the ``Raw Unicode Escape'' codec APIs:
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s,
- Py_ssize_t size,
- const char *errors}
- Create a Unicode object by decoding \var{size} bytes of the
- Raw-Unicode-Escape encoded string \var{s}. Return \NULL{} if an
- exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-% --- Latin-1 Codecs -----------------------------------------------------
-
-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.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s,
- Py_ssize_t size,
- const char *errors}
- Create a Unicode object by decoding \var{size} bytes of the Latin-1
- encoded string \var{s}. Return \NULL{} if an exception was raised
- by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-% --- ASCII Codecs -------------------------------------------------------
-
-These are the \ASCII{} codec APIs. Only 7-bit \ASCII{} data is
-accepted. All other codes generate errors.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s,
- Py_ssize_t size,
- const char *errors}
- Create a Unicode object by decoding \var{size} bytes of the
- \ASCII{} encoded string \var{s}. Return \NULL{} if an exception
- was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-% --- Character Map Codecs -----------------------------------------------
-
-These are the mapping codec APIs:
-
-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 \module{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.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s,
- Py_ssize_t size,
- PyObject *mapping,
- const char *errors}
- Create a Unicode object by decoding \var{size} bytes of the encoded
- string \var{s} using the given \var{mapping} object. Return
- \NULL{} if an exception was raised by the codec. If \var{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[Allowed unicode string as mapping argument]{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \var{mapping} object and return a Python string object.
- Return \NULL{} if an exception was raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode,
- PyObject *mapping}
- Encode a Unicode objects using the given \var{mapping} object and
- return the result as Python string object. Error handling is
- ``strict''. Return \NULL{} if an exception was raised by the
- codec.
-\end{cfuncdesc}
-
-The following codec API is special in that maps Unicode to Unicode.
-
-\begin{cfuncdesc}{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 \var{table} to it and return the
- resulting Unicode object. Return \NULL{} when an exception was
- raised by the codec.
-
- The \var{mapping} table must map Unicode ordinal integers to Unicode
- ordinal integers or None (causing deletion of the character).
-
- Mapping tables need only provide the \method{__getitem__()}
- interface; dictionaries and sequences work well. Unmapped character
- ordinals (ones which cause a \exception{LookupError}) are left
- untouched and are copied as-is.
-\end{cfuncdesc}
-
-% --- MBCS codecs for Windows --------------------------------------------
-
-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.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s,
- Py_ssize_t size,
- const char *errors}
- Create a Unicode object by decoding \var{size} bytes of the MBCS
- encoded string \var{s}. Return \NULL{} if an exception was
- raised by the codec.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCSStateful}{const char *s,
- int size,
- const char *errors,
- int *consumed}
- If \var{consumed} is \NULL{}, behave like
- \cfunction{PyUnicode_DecodeMBCS()}. If \var{consumed} is not \NULL{},
- \cfunction{PyUnicode_DecodeMBCSStateful()} will not decode trailing lead
- byte and the number of bytes that have been decoded will be stored in
- \var{consumed}.
- \versionadded{2.5}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-% --- Methods & Slots ----------------------------------------------------
-
-\subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}}
-
-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 \code{-1} if an exception occurs.
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left,
- PyObject *right}
- Concat two strings giving a new Unicode string.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \var{maxsplit} splits
- will be done. If negative, no limit is set. Separators are not
- included in the resulting list.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \var{keepend}
- is 0, the Line break characters are not included in the resulting
- strings.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \method{__getitem__()}
- interface; dictionaries and sequences work well. Unmapped character
- ordinals (ones which cause a \exception{LookupError}) are left
- untouched and are copied as-is.
-
- \var{errors} has the usual meaning for codecs. It may be \NULL{}
- which indicates to use the default error handling.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator,
- PyObject *seq}
- Join a sequence of strings using the given separator and return the
- resulting Unicode string.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_Tailmatch}{PyObject *str,
- PyObject *substr,
- Py_ssize_t start,
- Py_ssize_t end,
- int direction}
- Return 1 if \var{substr} matches \var{str}[\var{start}:\var{end}] at
- the given tail end (\var{direction} == -1 means to do a prefix
- match, \var{direction} == 1 a suffix match), 0 otherwise.
- Return \code{-1} if an error occurred.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PyUnicode_Find}{PyObject *str,
- PyObject *substr,
- Py_ssize_t start,
- Py_ssize_t end,
- int direction}
- Return the first position of \var{substr} in
- \var{str}[\var{start}:\var{end}] using the given \var{direction}
- (\var{direction} == 1 means to do a forward search,
- \var{direction} == -1 a backward search). The return value is the
- index of the first match; a value of \code{-1} indicates that no
- match was found, and \code{-2} indicates that an error occurred and
- an exception has been set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \var{substr} in
- \code{\var{str}[\var{start}:\var{end}]}. Return \code{-1} if an
- error occurred.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str,
- PyObject *substr,
- PyObject *replstr,
- Py_ssize_t maxcount}
- Replace at most \var{maxcount} occurrences of \var{substr} in
- \var{str} with \var{replstr} and return the resulting Unicode object.
- \var{maxcount} == -1 means replace all occurrences.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject *left, PyObject *right}
- Compare two strings and return -1, 0, 1 for less than, equal, and
- greater than, respectively.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_RichCompare}{PyObject *left,
- PyObject *right,
- int op}
-
- Rich compare two unicode strings and return one of the following:
- \begin{itemize}
- \item \code{NULL} in case an exception was raised
- \item \constant{Py_True} or \constant{Py_False} for successful comparisons
- \item \constant{Py_NotImplemented} in case the type combination is unknown
- \end{itemize}
-
- Note that \constant{Py_EQ} and \constant{Py_NE} comparisons can cause a
- \exception{UnicodeWarning} in case the conversion of the arguments to
- Unicode fails with a \exception{UnicodeDecodeError}.
-
- Possible values for \var{op} are
- \constant{Py_GT}, \constant{Py_GE}, \constant{Py_EQ},
- \constant{Py_NE}, \constant{Py_LT}, and \constant{Py_LE}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format,
- PyObject *args}
- Return a new string object from \var{format} and \var{args}; this
- is analogous to \code{\var{format} \%\ \var{args}}. The
- \var{args} argument must be a tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container,
- PyObject *element}
- Check whether \var{element} is contained in \var{container} and
- return true or false accordingly.
-
- \var{element} has to coerce to a one element Unicode
- string. \code{-1} is returned if there was an error.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyUnicode_InternInPlace}{PyObject **string}
- Intern the argument \var{*string} in place. The argument must be
- the address of a pointer variable pointing to a Python unicode string
- object. If there is an existing interned string that is the same as
- \var{*string}, it sets \var{*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
- \var{*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.)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyUnicode_InternFromString}{const char *v}
- A combination of \cfunction{PyUnicode_FromString()} and
- \cfunction{PyUnicode_InternInPlace()}, returning either a new unicode
- string object that has been interned, or a new (``owned'') reference to
- an earlier interned string object with the same value.
-\end{cfuncdesc}
-
-
-\subsection{Buffer Objects \label{bufferObjects}}
-\sectionauthor{Greg Stein}{gstein@lyra.org}
-
-\obindex{buffer}
-Python objects implemented in C can export a group of functions called
-the ``buffer\index{buffer interface} 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
-\method{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 \cfunction{PyArg_ParseTuple()} that operate
-against an object's buffer interface, returning data from the target
-object.
-
-More information on the buffer interface is provided in the section
-``Buffer Object Structures'' (section~\ref{buffer-structs}), under
-the description for \ctype{PyBufferProcs}\ttindex{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.
-
-\begin{ctypedesc}{PyBufferObject}
- This subtype of \ctype{PyObject} represents a buffer object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyBuffer_Type}
- The instance of \ctype{PyTypeObject} which represents the Python
- buffer type; it is the same object as \code{buffer} and
- \code{types.BufferType} in the Python layer.
- \withsubitem{(in module types)}{\ttindex{BufferType}}.
-\end{cvardesc}
-
-\begin{cvardesc}{int}{Py_END_OF_BUFFER}
- This constant may be passed as the \var{size} parameter to
- \cfunction{PyBuffer_FromObject()} or
- \cfunction{PyBuffer_FromReadWriteObject()}. It indicates that the
- new \ctype{PyBufferObject} should refer to \var{base} object from
- the specified \var{offset} to the end of its exported buffer. Using
- this enables the caller to avoid querying the \var{base} object for
- its length.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyBuffer_Check}{PyObject *p}
- Return true if the argument has type \cdata{PyBuffer_Type}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyBuffer_FromObject}{PyObject *base,
- Py_ssize_t offset, Py_ssize_t size}
- Return a new read-only buffer object. This raises
- \exception{TypeError} if \var{base} doesn't support the read-only
- buffer protocol or doesn't provide exactly one buffer segment, or it
- raises \exception{ValueError} if \var{offset} is less than zero. The
- buffer will hold a reference to the \var{base} object, and the
- buffer's contents will refer to the \var{base} object's buffer
- interface, starting as position \var{offset} and extending for
- \var{size} bytes. If \var{size} is \constant{Py_END_OF_BUFFER}, then
- the new buffer's contents extend to the length of the \var{base}
- object's exported buffer data.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \cfunction{PyBuffer_FromObject()}. If the
- \var{base} object does not export the writeable buffer protocol,
- then \exception{TypeError} is raised.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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
- \var{ptr}, is not deallocated while the returned buffer object
- exists. Raises \exception{ValueError} if \var{size} is less than
- zero. Note that \constant{Py_END_OF_BUFFER} may \emph{not} be
- passed for the \var{size} parameter; \exception{ValueError} will be
- raised in that case.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteMemory}{void *ptr, Py_ssize_t size}
- Similar to \cfunction{PyBuffer_FromMemory()}, but the returned
- buffer is writable.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyBuffer_New}{Py_ssize_t size}
- Return a new writable buffer object that maintains its own memory
- buffer of \var{size} bytes. \exception{ValueError} is returned if
- \var{size} is not zero or positive. Note that the memory buffer (as
- returned by \cfunction{PyObject_AsWriteBuffer()}) is not specifically
- aligned.
-\end{cfuncdesc}
-
-
-\subsection{Tuple Objects \label{tupleObjects}}
-
-\obindex{tuple}
-\begin{ctypedesc}{PyTupleObject}
- This subtype of \ctype{PyObject} represents a Python tuple object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyTuple_Type}
- This instance of \ctype{PyTypeObject} represents the Python tuple
- type; it is the same object as \code{tuple} and \code{types.TupleType}
- in the Python layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
- Return true if \var{p} is a tuple object or an instance of a subtype
- of the tuple type.
- \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTuple_CheckExact}{PyObject *p}
- Return true if \var{p} is a tuple object, but not an instance of a
- subtype of the tuple type.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_New}{Py_ssize_t len}
- Return a new tuple object of size \var{len}, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_Pack}{Py_ssize_t n, \moreargs}
- Return a new tuple object of size \var{n}, or \NULL{} on failure.
- The tuple values are initialized to the subsequent \var{n} C arguments
- pointing to Python objects. \samp{PyTuple_Pack(2, \var{a}, \var{b})}
- is equivalent to \samp{Py_BuildValue("(OO)", \var{a}, \var{b})}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p}
- Take a pointer to a tuple object, and return the size of that
- tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTuple_GET_SIZE}{PyObject *p}
- Return the size of the tuple \var{p}, which must be non-\NULL{} and
- point to a tuple; no error checking is performed.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, Py_ssize_t pos}
- Return the object at position \var{pos} in the tuple pointed to by
- \var{p}. If \var{pos} is out of bounds, return \NULL{} and sets an
- \exception{IndexError} exception.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, Py_ssize_t pos}
- Like \cfunction{PyTuple_GetItem()}, but does no checking of its
- arguments.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p,
- Py_ssize_t low, Py_ssize_t high}
- Take a slice of the tuple pointed to by \var{p} from \var{low} to
- \var{high} and return it as a new tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyObject *p,
- Py_ssize_t pos, PyObject *o}
- Insert a reference to object \var{o} at position \var{pos} of the
- tuple pointed to by \var{p}. Return \code{0} on success.
- \note{This function ``steals'' a reference to \var{o}.}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyObject *p,
- Py_ssize_t pos, PyObject *o}
- Like \cfunction{PyTuple_SetItem()}, but does no error checking, and
- should \emph{only} be used to fill in brand new tuples. \note{This
- function ``steals'' a reference to \var{o}.}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, Py_ssize_t newsize}
- Can be used to resize a tuple. \var{newsize} will be the new length
- of the tuple. Because tuples are \emph{supposed} to be immutable,
- this should only be used if there is only one reference to the
- object. Do \emph{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 \code{0} on success.
- Client code should never assume that the resulting value of
- \code{*\var{p}} will be the same as before calling this function.
- If the object referenced by \code{*\var{p}} is replaced, the
- original \code{*\var{p}} is destroyed. On failure, returns
- \code{-1} and sets \code{*\var{p}} to \NULL{}, and raises
- \exception{MemoryError} or
- \exception{SystemError}.
- \versionchanged[Removed unused third parameter, \var{last_is_sticky}]{2.2}
-\end{cfuncdesc}
-
-
-\subsection{List Objects \label{listObjects}}
-
-\obindex{list}
-\begin{ctypedesc}{PyListObject}
- This subtype of \ctype{PyObject} represents a Python list object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyList_Type}
- This instance of \ctype{PyTypeObject} represents the Python list
- type. This is the same object as \code{list} and \code{types.ListType}
- in the Python layer.\withsubitem{(in module types)}{\ttindex{ListType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
- Return true if \var{p} is a list object or an instance of a
- subtype of the list type.
- \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_CheckExact}{PyObject *p}
- Return true if \var{p} is a list object, but not an instance of a
- subtype of the list type.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_New}{Py_ssize_t len}
- Return a new list of length \var{len} on success, or \NULL{} on
- failure.
- \note{If \var{length} is greater than zero, the returned list object's
- items are set to \code{NULL}. Thus you cannot use abstract
- API functions such as \cfunction{PySequence_SetItem()}
- or expose the object to Python code before setting all items to a
- real object with \cfunction{PyList_SetItem()}.}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PyList_Size}{PyObject *list}
- Return the length of the list object in \var{list}; this is
- equivalent to \samp{len(\var{list})} on a list object.
- \bifuncindex{len}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PyList_GET_SIZE}{PyObject *list}
- Macro form of \cfunction{PyList_Size()} without error checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, Py_ssize_t index}
- Return the object at position \var{pos} in the list pointed to by
- \var{p}. The position must be positive, indexing from the end of the
- list is not supported. If \var{pos} is out of bounds, return \NULL{}
- and set an \exception{IndexError} exception.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, Py_ssize_t i}
- Macro form of \cfunction{PyList_GetItem()} without error checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, Py_ssize_t index,
- PyObject *item}
- Set the item at index \var{index} in list to \var{item}. Return
- \code{0} on success or \code{-1} on failure. \note{This function
- ``steals'' a reference to \var{item} and discards a reference to an
- item already in the list at the affected position.}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, Py_ssize_t i,
- PyObject *o}
- Macro form of \cfunction{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 \var{item}, and,
- unlike \cfunction{PyList_SetItem()}, does \emph{not} discard a
- reference to any item that it being replaced; any reference in
- \var{list} at position \var{i} will be leaked.}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, Py_ssize_t index,
- PyObject *item}
- Insert the item \var{item} into list \var{list} in front of index
- \var{index}. Return \code{0} if successful; return \code{-1} and
- set an exception if unsuccessful. Analogous to
- \code{\var{list}.insert(\var{index}, \var{item})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item}
- Append the object \var{item} at the end of list \var{list}.
- Return \code{0} if successful; return \code{-1} and set an
- exception if unsuccessful. Analogous to
- \code{\var{list}.append(\var{item})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
- Py_ssize_t low, Py_ssize_t high}
- Return a list of the objects in \var{list} containing the objects
- \emph{between} \var{low} and \var{high}. Return \NULL{} and set
- an exception if unsuccessful.
- Analogous to \code{\var{list}[\var{low}:\var{high}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
- Py_ssize_t low, Py_ssize_t high,
- PyObject *itemlist}
- Set the slice of \var{list} between \var{low} and \var{high} to the
- contents of \var{itemlist}. Analogous to
- \code{\var{list}[\var{low}:\var{high}] = \var{itemlist}}.
- The \var{itemlist} may be \NULL{}, indicating the assignment
- of an empty list (slice deletion).
- Return \code{0} on success, \code{-1} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list}
- Sort the items of \var{list} in place. Return \code{0} on
- success, \code{-1} on failure. This is equivalent to
- \samp{\var{list}.sort()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list}
- Reverse the items of \var{list} in place. Return \code{0} on
- success, \code{-1} on failure. This is the equivalent of
- \samp{\var{list}.reverse()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list}
- Return a new tuple object containing the contents of \var{list};
- equivalent to \samp{tuple(\var{list})}.\bifuncindex{tuple}
-\end{cfuncdesc}
-
-
-\section{Mapping Objects \label{mapObjects}}
-
-\obindex{mapping}
-
-
-\subsection{Dictionary Objects \label{dictObjects}}
-
-\obindex{dictionary}
-\begin{ctypedesc}{PyDictObject}
- This subtype of \ctype{PyObject} represents a Python dictionary
- object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyDict_Type}
- This instance of \ctype{PyTypeObject} represents the Python
- dictionary type. This is exposed to Python programs as
- \code{dict} and \code{types.DictType}.
- \withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
- Return true if \var{p} is a dict object or an instance of a
- subtype of the dict type.
- \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_CheckExact}{PyObject *p}
- Return true if \var{p} is a dict object, but not an instance of a
- subtype of the dict type.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
- Return a new empty dictionary, or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyDict_Clear}{PyObject *p}
- Empty an existing dictionary of all key-value pairs.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_Contains}{PyObject *p, PyObject *key}
- Determine if dictionary \var{p} contains \var{key}. If an item
- in \var{p} is matches \var{key}, return \code{1}, otherwise return
- \code{0}. On error, return \code{-1}. This is equivalent to the
- Python expression \samp{\var{key} in \var{p}}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p}
- Return a new dictionary that contains the same key-value pairs as
- \var{p}.
- \versionadded{1.6}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_SetItem}{PyObject *p, PyObject *key,
- PyObject *val}
- Insert \var{value} into the dictionary \var{p} with a key of
- \var{key}. \var{key} must be hashable; if it isn't,
- \exception{TypeError} will be raised.
- Return \code{0} on success or \code{-1} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p,
- const char *key,
- PyObject *val}
- Insert \var{value} into the dictionary \var{p} using \var{key} as a
- key. \var{key} should be a \ctype{char*}. The key object is created
- using \code{PyString_FromString(\var{key})}. Return \code{0} on
- success or \code{-1} on failure.
- \ttindex{PyString_FromString()}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_DelItem}{PyObject *p, PyObject *key}
- Remove the entry in dictionary \var{p} with key \var{key}.
- \var{key} must be hashable; if it isn't, \exception{TypeError} is
- raised. Return \code{0} on success or \code{-1} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyObject *p, char *key}
- Remove the entry in dictionary \var{p} which has a key specified by
- the string \var{key}. Return \code{0} on success or \code{-1} on
- failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_GetItem}{PyObject *p, PyObject *key}
- Return the object from dictionary \var{p} which has a key
- \var{key}. Return \NULL{} if the key \var{key} is not present, but
- \emph{without} setting an exception.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, const char *key}
- This is the same as \cfunction{PyDict_GetItem()}, but \var{key} is
- specified as a \ctype{char*}, rather than a \ctype{PyObject*}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyObject *p}
- Return a \ctype{PyListObject} containing all the items from the
- dictionary, as in the dictionary method \method{items()} (see the
- \citetitle[../lib/lib.html]{Python Library Reference}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyObject *p}
- Return a \ctype{PyListObject} containing all the keys from the
- dictionary, as in the dictionary method \method{keys()} (see the
- \citetitle[../lib/lib.html]{Python Library Reference}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyObject *p}
- Return a \ctype{PyListObject} containing all the values from the
- dictionary \var{p}, as in the dictionary method \method{values()}
- (see the \citetitle[../lib/lib.html]{Python Library Reference}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_ssize_t}{PyDict_Size}{PyObject *p}
- Return the number of items in the dictionary. This is equivalent
- to \samp{len(\var{p})} on a dictionary.\bifuncindex{len}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, Py_ssize_t *ppos,
- PyObject **pkey, PyObject **pvalue}
- Iterate over all key-value pairs in the dictionary \var{p}. The
- \ctype{int} referred to by \var{ppos} must be initialized to
- \code{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 \var{pkey} and \var{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. \var{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:
-
-\begin{verbatim}
-PyObject *key, *value;
-Py_ssize_t pos = 0;
-
-while (PyDict_Next(self->dict, &pos, &key, &value)) {
- /* do something interesting with the values... */
- ...
-}
-\end{verbatim}
-
- The dictionary \var{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:
-
-\begin{verbatim}
-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);
-}
-\end{verbatim}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_Merge}{PyObject *a, PyObject *b, int override}
- Iterate over mapping object \var{b} adding key-value pairs to dictionary
- \var{a}.
- \var{b} may be a dictionary, or any object supporting
- \function{PyMapping_Keys()} and \function{PyObject_GetItem()}.
- If \var{override} is true, existing pairs in \var{a} will
- be replaced if a matching key is found in \var{b}, otherwise pairs
- will only be added if there is not a matching key in \var{a}.
- Return \code{0} on success or \code{-1} if an exception was
- raised.
-\versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_Update}{PyObject *a, PyObject *b}
- This is the same as \code{PyDict_Merge(\var{a}, \var{b}, 1)} in C,
- or \code{\var{a}.update(\var{b})} in Python. Return \code{0} on
- success or \code{-1} if an exception was raised.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_MergeFromSeq2}{PyObject *a, PyObject *seq2,
- int override}
- Update or merge into dictionary \var{a}, from the key-value pairs in
- \var{seq2}. \var{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 \var{override} is true, else the
- first wins.
- Return \code{0} on success or \code{-1} if an exception
- was raised.
- Equivalent Python (except for the return value):
-
-\begin{verbatim}
-def PyDict_MergeFromSeq2(a, seq2, override):
- for key, value in seq2:
- if override or key not in a:
- a[key] = value
-\end{verbatim}
-
- \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\section{Other Objects \label{otherObjects}}
-
-\subsection{Class Objects \label{classObjects}}
-
-\obindex{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}).
-
-\begin{ctypedesc}{PyClassObject}
- The C structure of the objects used to describe built-in classes.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyObject*}{PyClass_Type}
- This is the type object for class objects; it is the same object as
- \code{types.ClassType} in the Python layer.
- \withsubitem{(in module types)}{\ttindex{ClassType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyClass_Check}{PyObject *o}
- Return true if the object \var{o} is a class object, including
- instances of types derived from the standard class object. Return
- false in all other cases.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyClass_IsSubclass}{PyObject *klass, PyObject *base}
- Return true if \var{klass} is a subclass of \var{base}. Return false in
- all other cases.
-\end{cfuncdesc}
-
-\subsection{File Objects \label{fileObjects}}
-
-\obindex{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.
-
-\begin{ctypedesc}{PyFileObject}
- This subtype of \ctype{PyObject} represents a Python file object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyFile_Type}
- This instance of \ctype{PyTypeObject} represents the Python file
- type. This is exposed to Python programs as \code{file} and
- \code{types.FileType}.
- \withsubitem{(in module types)}{\ttindex{FileType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
- Return true if its argument is a \ctype{PyFileObject} or a subtype
- of \ctype{PyFileObject}.
- \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFile_CheckExact}{PyObject *p}
- Return true if its argument is a \ctype{PyFileObject}, but not a
- subtype of \ctype{PyFileObject}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *filename, char *mode}
- On success, return a new file object that is opened on the file
- given by \var{filename}, with a file mode given by \var{mode}, where
- \var{mode} has the same semantics as the standard C routine
- \cfunction{fopen()}\ttindex{fopen()}. On failure, return \NULL{}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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, \var{fp}. The function \var{close} will be called
- when the file should be closed. Return \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyObject *p}
- Return the file object associated with \var{p} as a \ctype{FILE*}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n}
- Equivalent to \code{\var{p}.readline(\optional{\var{n}})}, this
- function reads one line from the object \var{p}. \var{p} may be a
- file object or any object with a \method{readline()} method. If
- \var{n} is \code{0}, exactly one line is read, regardless of the
- length of the line. If \var{n} is greater than \code{0}, no more
- than \var{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 \var{n} is less than \code{0},
- however, one line is read regardless of length, but
- \exception{EOFError} is raised if the end of the file is reached
- immediately.
- \withsubitem{(built-in exception)}{\ttindex{EOFError}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p}
- Return the name of the file specified by \var{p} as a string
- object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
- Available on systems with \cfunction{setvbuf()}\ttindex{setvbuf()}
- only. This should only be called immediately after file object
- creation.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFile_Encoding}{PyFileObject *p, char *enc}
- Set the file's encoding for Unicode output to \var{enc}. Return
- 1 on success and 0 on failure.
- \versionadded{2.3}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyObject *p, int newflag}
- This function exists for internal use by the interpreter. Set the
- \member{softspace} attribute of \var{p} to \var{newflag} and
- \withsubitem{(file attribute)}{\ttindex{softspace}}return the
- previous value. \var{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 \member{softspace} attribute can be set). This
- function clears any errors, and will return \code{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyObject *p,
- int flags}
- Write object \var{obj} to file object \var{p}. The only supported
- flag for \var{flags} is
- \constant{Py_PRINT_RAW}\ttindex{Py_PRINT_RAW}; if given, the
- \function{str()} of the object is written instead of the
- \function{repr()}. Return \code{0} on success or \code{-1} on
- failure; the appropriate exception will be set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFile_WriteString}{const char *s, PyObject *p}
- Write string \var{s} to file object \var{p}. Return \code{0} on
- success or \code{-1} on failure; the appropriate exception will be
- set.
-\end{cfuncdesc}
-
-
-\subsection{Instance Objects \label{instanceObjects}}
-
-\obindex{instance}
-There are very few functions specific to instance objects.
-
-\begin{cvardesc}{PyTypeObject}{PyInstance_Type}
- Type object for class instances.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj}
- Return true if \var{obj} is an instance.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyInstance_New}{PyObject *class,
- PyObject *arg,
- PyObject *kw}
- Create a new instance of a specific class. The parameters \var{arg}
- and \var{kw} are used as the positional and keyword parameters to
- the object's constructor.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyInstance_NewRaw}{PyObject *class,
- PyObject *dict}
- Create a new instance of a specific class without calling its
- constructor. \var{class} is the class of new object. The
- \var{dict} parameter will be used as the object's \member{__dict__};
- if \NULL{}, a new dictionary will be created for the instance.
-\end{cfuncdesc}
-
-
-\subsection{Function Objects \label{function-objects}}
-
-\obindex{function}
-There are a few functions specific to Python functions.
-
-\begin{ctypedesc}{PyFunctionObject}
- The C structure used for functions.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyFunction_Type}
- This is an instance of \ctype{PyTypeObject} and represents the
- Python function type. It is exposed to Python programmers as
- \code{types.FunctionType}.
- \withsubitem{(in module types)}{\ttindex{MethodType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyFunction_Check}{PyObject *o}
- Return true if \var{o} is a function object (has type
- \cdata{PyFunction_Type}). The parameter must not be \NULL{}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFunction_New}{PyObject *code,
- PyObject *globals}
- Return a new function object associated with the code object
- \var{code}. \var{globals} must be a dictionary with the global
- variables accessible to the function.
-
- The function's docstring, name and \var{__module__} are retrieved
- from the code object, the argument defaults and closure are set to
- \NULL{}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFunction_GetCode}{PyObject *op}
- Return the code object associated with the function object \var{op}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFunction_GetGlobals}{PyObject *op}
- Return the globals dictionary associated with the function object
- \var{op}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFunction_GetModule}{PyObject *op}
- Return the \var{__module__} attribute of the function object \var{op}.
- This is normally a string containing the module name, but can be set
- to any other object by Python code.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFunction_GetDefaults}{PyObject *op}
- Return the argument default values of the function object \var{op}.
- This can be a tuple of arguments or \NULL{}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFunction_SetDefaults}{PyObject *op,
- PyObject *defaults}
- Set the argument default values for the function object \var{op}.
- \var{defaults} must be \var{Py_None} or a tuple.
-
- Raises \exception{SystemError} and returns \code{-1} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFunction_GetClosure}{PyObject *op}
- Return the closure associated with the function object \var{op}.
- This can be \NULL{} or a tuple of cell objects.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFunction_SetClosure}{PyObject *op,
- PyObject *closure}
- Set the closure associated with the function object \var{op}.
- \var{closure} must be \var{Py_None} or a tuple of cell objects.
-
- Raises \exception{SystemError} and returns \code{-1} on failure.
-\end{cfuncdesc}
-
-
-\subsection{Method Objects \label{method-objects}}
-
-\obindex{method}
-There are some useful functions that are useful for working with
-method objects.
-
-\begin{cvardesc}{PyTypeObject}{PyMethod_Type}
- This instance of \ctype{PyTypeObject} represents the Python method
- type. This is exposed to Python programs as \code{types.MethodType}.
- \withsubitem{(in module types)}{\ttindex{MethodType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyMethod_Check}{PyObject *o}
- Return true if \var{o} is a method object (has type
- \cdata{PyMethod_Type}). The parameter must not be \NULL{}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func,
- PyObject *self, PyObject *class}
- Return a new method object, with \var{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, \var{self}
- should be the instance and \var{class} should be the class of
- \var{self}, otherwise \var{self} should be \NULL{} and \var{class}
- should be the class which provides the unbound method..
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMethod_Class}{PyObject *meth}
- Return the class object from which the method \var{meth} was
- created; if this was created from an instance, it will be the class
- of the instance.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMethod_GET_CLASS}{PyObject *meth}
- Macro version of \cfunction{PyMethod_Class()} which avoids error
- checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMethod_Function}{PyObject *meth}
- Return the function object associated with the method \var{meth}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMethod_GET_FUNCTION}{PyObject *meth}
- Macro version of \cfunction{PyMethod_Function()} which avoids error
- checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMethod_Self}{PyObject *meth}
- Return the instance associated with the method \var{meth} if it is
- bound, otherwise return \NULL{}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMethod_GET_SELF}{PyObject *meth}
- Macro version of \cfunction{PyMethod_Self()} which avoids error
- checking.
-\end{cfuncdesc}
-
-
-\subsection{Module Objects \label{moduleObjects}}
-
-\obindex{module}
-There are only a few functions special to module objects.
-
-\begin{cvardesc}{PyTypeObject}{PyModule_Type}
- This instance of \ctype{PyTypeObject} represents the Python module
- type. This is exposed to Python programs as
- \code{types.ModuleType}.
- \withsubitem{(in module types)}{\ttindex{ModuleType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p}
- Return true if \var{p} is a module object, or a subtype of a module
- object.
- \versionchanged[Allowed subtypes to be accepted]{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyModule_CheckExact}{PyObject *p}
- Return true if \var{p} is a module object, but not a subtype of
- \cdata{PyModule_Type}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyModule_New}{const char *name}
- Return a new module object with the \member{__name__} attribute set
- to \var{name}. Only the module's \member{__doc__} and
- \member{__name__} attributes are filled in; the caller is
- responsible for providing a \member{__file__} attribute.
- \withsubitem{(module attribute)}{
- \ttindex{__name__}\ttindex{__doc__}\ttindex{__file__}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyModule_GetDict}{PyObject *module}
- Return the dictionary object that implements \var{module}'s
- namespace; this object is the same as the \member{__dict__}
- attribute of the module object. This function never fails.
- \withsubitem{(module attribute)}{\ttindex{__dict__}}
- It is recommended extensions use other \cfunction{PyModule_*()}
- and \cfunction{PyObject_*()} functions rather than directly
- manipulate a module's \member{__dict__}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{PyModule_GetName}{PyObject *module}
- Return \var{module}'s \member{__name__} value. If the module does
- not provide one, or if it is not a string, \exception{SystemError}
- is raised and \NULL{} is returned.
- \withsubitem{(module attribute)}{\ttindex{__name__}}
- \withsubitem{(built-in exception)}{\ttindex{SystemError}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{PyModule_GetFilename}{PyObject *module}
- Return the name of the file from which \var{module} was loaded using
- \var{module}'s \member{__file__} attribute. If this is not defined,
- or if it is not a string, raise \exception{SystemError} and return
- \NULL{}.
- \withsubitem{(module attribute)}{\ttindex{__file__}}
- \withsubitem{(built-in exception)}{\ttindex{SystemError}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyModule_AddObject}{PyObject *module,
- const char *name, PyObject *value}
- Add an object to \var{module} as \var{name}. This is a convenience
- function which can be used from the module's initialization
- function. This steals a reference to \var{value}. Return
- \code{-1} on error, \code{0} on success.
- \versionadded{2.0}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module,
- const char *name, long value}
- Add an integer constant to \var{module} as \var{name}. This
- convenience function can be used from the module's initialization
- function. Return \code{-1} on error, \code{0} on success.
- \versionadded{2.0}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module,
- const char *name, const char *value}
- Add a string constant to \var{module} as \var{name}. This
- convenience function can be used from the module's initialization
- function. The string \var{value} must be null-terminated. Return
- \code{-1} on error, \code{0} on success.
- \versionadded{2.0}
-\end{cfuncdesc}
-
-
-\subsection{Iterator Objects \label{iterator-objects}}
-
-Python provides two general-purpose iterator objects. The first, a
-sequence iterator, works with an arbitrary sequence supporting the
-\method{__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.
-
-\begin{cvardesc}{PyTypeObject}{PySeqIter_Type}
- Type object for iterator objects returned by
- \cfunction{PySeqIter_New()} and the one-argument form of the
- \function{iter()} built-in function for built-in sequence types.
- \versionadded{2.2}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PySeqIter_Check}{op}
- Return true if the type of \var{op} is \cdata{PySeqIter_Type}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySeqIter_New}{PyObject *seq}
- Return an iterator that works with a general sequence object,
- \var{seq}. The iteration ends when the sequence raises
- \exception{IndexError} for the subscripting operation.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cvardesc}{PyTypeObject}{PyCallIter_Type}
- Type object for iterator objects returned by
- \cfunction{PyCallIter_New()} and the two-argument form of the
- \function{iter()} built-in function.
- \versionadded{2.2}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyCallIter_Check}{op}
- Return true if the type of \var{op} is \cdata{PyCallIter_Type}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyCallIter_New}{PyObject *callable,
- PyObject *sentinel}
- Return a new iterator. The first parameter, \var{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
- \var{callable} returns a value equal to \var{sentinel}, the
- iteration will be terminated.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\subsection{Descriptor Objects \label{descriptor-objects}}
-
-``Descriptors'' are objects that describe some attribute of an object.
-They are found in the dictionary of type objects.
-
-\begin{cvardesc}{PyTypeObject}{PyProperty_Type}
- The type object for the built-in descriptor types.
- \versionadded{2.2}
-\end{cvardesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDescr_NewGetSet}{PyTypeObject *type,
- struct PyGetSetDef *getset}
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDescr_NewMember}{PyTypeObject *type,
- struct PyMemberDef *meth}
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDescr_NewMethod}{PyTypeObject *type,
- struct PyMethodDef *meth}
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDescr_NewWrapper}{PyTypeObject *type,
- struct wrapperbase *wrapper,
- void *wrapped}
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDescr_NewClassMethod}{PyTypeObject *type,
- PyMethodDef *method}
- \versionadded{2.3}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDescr_IsData}{PyObject *descr}
- Return true if the descriptor objects \var{descr} describes a data
- attribute, or false if it describes a method. \var{descr} must be a
- descriptor object; there is no error checking.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyWrapper_New}{PyObject *, PyObject *}
- \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\subsection{Slice Objects \label{slice-objects}}
-
-\begin{cvardesc}{PyTypeObject}{PySlice_Type}
- The type object for slice objects. This is the same as
- \code{slice} and \code{types.SliceType}.
- \withsubitem{(in module types)}{\ttindex{SliceType}}
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob}
- Return true if \var{ob} is a slice object; \var{ob} must not be
- \NULL{}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySlice_New}{PyObject *start, PyObject *stop,
- PyObject *step}
- Return a new slice object with the given values. The \var{start},
- \var{stop}, and \var{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 \code{None} will be used for the
- corresponding attribute. Return \NULL{} if the new object could
- not be allocated.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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
-\var{slice}, assuming a sequence of length \var{length}. Treats
-indices greater than \var{length} as errors.
-
-Returns 0 on success and -1 on error with no exception set (unless one
-of the indices was not \constant{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 \cfunction{PySlice_GetIndicesEx},
-suitably renamed, in the source of your extension.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \cfunction{PySlice_GetIndices}. Retrieve the
-start, stop, and step indices from the slice object \var{slice}
-assuming a sequence of length \var{length}, and store the length of
-the slice in \var{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}
-\end{cfuncdesc}
-
-
-\subsection{Weak Reference Objects \label{weakref-objects}}
-
-Python supports \emph{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.
-
-\begin{cfuncdesc}{int}{PyWeakref_Check}{ob}
- Return true if \var{ob} is either a reference or proxy object.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyWeakref_CheckRef}{ob}
- Return true if \var{ob} is a reference object.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyWeakref_CheckProxy}{ob}
- Return true if \var{ob} is a proxy object.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyWeakref_NewRef}{PyObject *ob,
- PyObject *callback}
- Return a weak reference object for the object \var{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, \var{callback}, can be a callable object that receives
- notification when \var{ob} is garbage collected; it should accept a
- single parameter, which will be the weak reference object itself.
- \var{callback} may also be \code{None} or \NULL{}. If \var{ob}
- is not a weakly-referencable object, or if \var{callback} is not
- callable, \code{None}, or \NULL{}, this will return \NULL{} and
- raise \exception{TypeError}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyWeakref_NewProxy}{PyObject *ob,
- PyObject *callback}
- Return a weak reference proxy object for the object \var{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, \var{callback}, can be a callable object that receives
- notification when \var{ob} is garbage collected; it should accept a
- single parameter, which will be the weak reference object itself.
- \var{callback} may also be \code{None} or \NULL{}. If \var{ob} is not
- a weakly-referencable object, or if \var{callback} is not callable,
- \code{None}, or \NULL{}, this will return \NULL{} and raise
- \exception{TypeError}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyWeakref_GetObject}{PyObject *ref}
- Return the referenced object from a weak reference, \var{ref}. If
- the referent is no longer live, returns \code{None}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyWeakref_GET_OBJECT}{PyObject *ref}
- Similar to \cfunction{PyWeakref_GetObject()}, but implemented as a
- macro that does no error checking.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-
-\subsection{CObjects \label{cObjects}}
-
-\obindex{CObject}
-Refer to \emph{Extending and Embedding the Python Interpreter},
-section~1.12, ``Providing a C API for an Extension Module,'' for more
-information on using these objects.
-
-
-\begin{ctypedesc}{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.
-\end{ctypedesc}
-
-\begin{cfuncdesc}{int}{PyCObject_Check}{PyObject *p}
- Return true if its argument is a \ctype{PyCObject}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj,
- void (*destr)(void *)}
- Create a \ctype{PyCObject} from the \code{void *}\var{cobj}. The
- \var{destr} function will be called when the object is reclaimed,
- unless it is \NULL{}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtrAndDesc}{void* cobj,
- void* desc, void (*destr)(void *, void *)}
- Create a \ctype{PyCObject} from the \ctype{void *}\var{cobj}. The
- \var{destr} function will be called when the object is reclaimed.
- The \var{desc} argument can be used to pass extra callback data for
- the destructor function.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void*}{PyCObject_AsVoidPtr}{PyObject* self}
- Return the object \ctype{void *} that the \ctype{PyCObject}
- \var{self} was created with.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void*}{PyCObject_GetDesc}{PyObject* self}
- Return the description \ctype{void *} that the \ctype{PyCObject}
- \var{self} was created with.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyCObject_SetVoidPtr}{PyObject* self, void* cobj}
- Set the void pointer inside \var{self} to \var{cobj}.
- The \ctype{PyCObject} must not have an associated destructor.
- Return true on success, false on failure.
-\end{cfuncdesc}
-
-
-\subsection{Cell Objects \label{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.
-
-\begin{ctypedesc}{PyCellObject}
- The C structure used for cell objects.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyCell_Type}
- The type object corresponding to cell objects.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyCell_Check}{ob}
- Return true if \var{ob} is a cell object; \var{ob} must not be
- \NULL{}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyCell_New}{PyObject *ob}
- Create and return a new cell object containing the value \var{ob}.
- The parameter may be \NULL{}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyCell_Get}{PyObject *cell}
- Return the contents of the cell \var{cell}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyCell_GET}{PyObject *cell}
- Return the contents of the cell \var{cell}, but without checking
- that \var{cell} is non-\NULL{} and a cell object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyCell_Set}{PyObject *cell, PyObject *value}
- Set the contents of the cell object \var{cell} to \var{value}. This
- releases the reference to any current content of the cell.
- \var{value} may be \NULL{}. \var{cell} must be non-\NULL{}; if it is
- not a cell object, \code{-1} will be returned. On success, \code{0}
- will be returned.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyCell_SET}{PyObject *cell, PyObject *value}
- Sets the value of the cell object \var{cell} to \var{value}. No
- reference counts are adjusted, and no checks are made for safety;
- \var{cell} must be non-\NULL{} and must be a cell object.
-\end{cfuncdesc}
-
-
-\subsection{Generator Objects \label{gen-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 \cfunction{PyGen_New}.
-
-\begin{ctypedesc}{PyGenObject}
- The C structure used for generator objects.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyGen_Type}
- The type object corresponding to generator objects
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyGen_Check}{ob}
- Return true if \var{ob} is a generator object; \var{ob} must not be
- \NULL{}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyGen_CheckExact}{ob}
- Return true if \var{ob}'s type is \var{PyGen_Type}
- is a generator object; \var{ob} must not be
- \NULL{}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyGen_New}{PyFrameObject *frame}
- Create and return a new generator object based on the \var{frame} object.
- A reference to \var{frame} is stolen by this function.
- The parameter must not be \NULL{}.
-\end{cfuncdesc}
-
-
-\subsection{DateTime Objects \label{datetime-objects}}
-
-Various date and time objects are supplied by the \module{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
-\cfunction{PyDateTime_IMPORT} must be invoked. The macro puts a
-pointer to a C structure into a static variable,
-\code{PyDateTimeAPI}, that is used by the following macros.
-
-Type-check macros:
-
-\begin{cfuncdesc}{int}{PyDate_Check}{PyObject *ob}
- Return true if \var{ob} is of type \cdata{PyDateTime_DateType} or
- a subtype of \cdata{PyDateTime_DateType}. \var{ob} must not be
- \NULL{}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDate_CheckExact}{PyObject *ob}
- Return true if \var{ob} is of type \cdata{PyDateTime_DateType}.
- \var{ob} must not be \NULL{}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDateTime_Check}{PyObject *ob}
- Return true if \var{ob} is of type \cdata{PyDateTime_DateTimeType} or
- a subtype of \cdata{PyDateTime_DateTimeType}. \var{ob} must not be
- \NULL{}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDateTime_CheckExact}{PyObject *ob}
- Return true if \var{ob} is of type \cdata{PyDateTime_DateTimeType}.
- \var{ob} must not be \NULL{}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTime_Check}{PyObject *ob}
- Return true if \var{ob} is of type \cdata{PyDateTime_TimeType} or
- a subtype of \cdata{PyDateTime_TimeType}. \var{ob} must not be
- \NULL{}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTime_CheckExact}{PyObject *ob}
- Return true if \var{ob} is of type \cdata{PyDateTime_TimeType}.
- \var{ob} must not be \NULL{}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDelta_Check}{PyObject *ob}
- Return true if \var{ob} is of type \cdata{PyDateTime_DeltaType} or
- a subtype of \cdata{PyDateTime_DeltaType}. \var{ob} must not be
- \NULL{}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDelta_CheckExact}{PyObject *ob}
- Return true if \var{ob} is of type \cdata{PyDateTime_DeltaType}.
- \var{ob} must not be \NULL{}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTZInfo_Check}{PyObject *ob}
- Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType} or
- a subtype of \cdata{PyDateTime_TZInfoType}. \var{ob} must not be
- \NULL{}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTZInfo_CheckExact}{PyObject *ob}
- Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType}.
- \var{ob} must not be \NULL{}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-Macros to create objects:
-
-\begin{cfuncdesc}{PyObject*}{PyDate_FromDate}{int year, int month, int day}
- Return a \code{datetime.date} object with the specified year, month
- and day.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDateTime_FromDateAndTime}{int year, int month,
- int day, int hour, int minute, int second, int usecond}
- Return a \code{datetime.datetime} object with the specified year, month,
- day, hour, minute, second and microsecond.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTime_FromTime}{int hour, int minute,
- int second, int usecond}
- Return a \code{datetime.time} object with the specified hour, minute,
- second and microsecond.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDelta_FromDSU}{int days, int seconds,
- int useconds}
- Return a \code{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 \code{datetime.timedelta} objects.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-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:
-
-\begin{cfuncdesc}{int}{PyDateTime_GET_YEAR}{PyDateTime_Date *o}
- Return the year, as a positive int.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDateTime_GET_MONTH}{PyDateTime_Date *o}
- Return the month, as an int from 1 through 12.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDateTime_GET_DAY}{PyDateTime_Date *o}
- Return the day, as an int from 1 through 31.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-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:
-
-\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_HOUR}{PyDateTime_DateTime *o}
- Return the hour, as an int from 0 through 23.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_MINUTE}{PyDateTime_DateTime *o}
- Return the minute, as an int from 0 through 59.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_SECOND}{PyDateTime_DateTime *o}
- Return the second, as an int from 0 through 59.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDateTime_DATE_GET_MICROSECOND}{PyDateTime_DateTime *o}
- Return the microsecond, as an int from 0 through 999999.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-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:
-
-\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_HOUR}{PyDateTime_Time *o}
- Return the hour, as an int from 0 through 23.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_MINUTE}{PyDateTime_Time *o}
- Return the minute, as an int from 0 through 59.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_SECOND}{PyDateTime_Time *o}
- Return the second, as an int from 0 through 59.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDateTime_TIME_GET_MICROSECOND}{PyDateTime_Time *o}
- Return the microsecond, as an int from 0 through 999999.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-Macros for the convenience of modules implementing the DB API:
-
-\begin{cfuncdesc}{PyObject*}{PyDateTime_FromTimestamp}{PyObject *args}
- Create and return a new \code{datetime.datetime} object given an argument
- tuple suitable for passing to \code{datetime.datetime.fromtimestamp()}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDate_FromTimestamp}{PyObject *args}
- Create and return a new \code{datetime.date} object given an argument
- tuple suitable for passing to \code{datetime.date.fromtimestamp()}.
- \versionadded{2.4}
-\end{cfuncdesc}
-
-
-\subsection{Set Objects \label{setObjects}}
-\sectionauthor{Raymond D. Hettinger}{python@rcn.com}
-
-\obindex{set}
-\obindex{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
-\cfunction{PyObject_CallMethod()}, \cfunction{PyObject_RichCompareBool()},
-\cfunction{PyObject_Hash()}, \cfunction{PyObject_Repr()},
-\cfunction{PyObject_IsTrue()}, \cfunction{PyObject_Print()}, and
-\cfunction{PyObject_GetIter()})
-or the abstract number protocol (including
-\cfunction{PyNumber_And()}, \cfunction{PyNumber_Subtract()},
-\cfunction{PyNumber_Or()}, \cfunction{PyNumber_Xor()},
-\cfunction{PyNumber_InPlaceAnd()}, \cfunction{PyNumber_InPlaceSubtract()},
-\cfunction{PyNumber_InPlaceOr()}, and \cfunction{PyNumber_InPlaceXor()}).
-
-\begin{ctypedesc}{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.
-
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PySet_Type}
- This is an instance of \ctype{PyTypeObject} representing the Python
- \class{set} type.
-\end{cvardesc}
-
-\begin{cvardesc}{PyTypeObject}{PyFrozenSet_Type}
- This is an instance of \ctype{PyTypeObject} representing the Python
- \class{frozenset} type.
-\end{cvardesc}
-
-
-The following type check macros work on pointers to any Python object.
-Likewise, the constructor functions work with any iterable Python object.
-
-\begin{cfuncdesc}{int}{PyAnySet_Check}{PyObject *p}
- Return true if \var{p} is a \class{set} object, a \class{frozenset}
- object, or an instance of a subtype.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyAnySet_CheckExact}{PyObject *p}
- Return true if \var{p} is a \class{set} object or a \class{frozenset}
- object but not an instance of a subtype.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFrozenSet_CheckExact}{PyObject *p}
- Return true if \var{p} is a \class{frozenset} object
- but not an instance of a subtype.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySet_New}{PyObject *iterable}
- Return a new \class{set} containing objects returned by the
- \var{iterable}. The \var{iterable} may be \NULL{} to create a
- new empty set. Return the new set on success or \NULL{} on
- failure. Raise \exception{TypeError} if \var{iterable} is
- not actually iterable. The constructor is also useful for
- copying a set (\code{c=set(s)}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFrozenSet_New}{PyObject *iterable}
- Return a new \class{frozenset} containing objects returned by the
- \var{iterable}. The \var{iterable} may be \NULL{} to create a
- new empty frozenset. Return the new set on success or \NULL{} on
- failure. Raise \exception{TypeError} if \var{iterable} is
- not actually iterable.
-\end{cfuncdesc}
-
-
-The following functions and macros are available for instances of
-\class{set} or \class{frozenset} or instances of their subtypes.
-
-\begin{cfuncdesc}{int}{PySet_Size}{PyObject *anyset}
- Return the length of a \class{set} or \class{frozenset} object.
- Equivalent to \samp{len(\var{anyset})}. Raises a
- \exception{PyExc_SystemError} if \var{anyset} is not a \class{set},
- \class{frozenset}, or an instance of a subtype.
- \bifuncindex{len}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySet_GET_SIZE}{PyObject *anyset}
- Macro form of \cfunction{PySet_Size()} without error checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \method{__contains__()} method, this
- function does not automatically convert unhashable sets into temporary
- frozensets. Raise a \exception{TypeError} if the \var{key} is unhashable.
- Raise \exception{PyExc_SystemError} if \var{anyset} is not a \class{set},
- \class{frozenset}, or an instance of a subtype.
-\end{cfuncdesc}
-
-The following functions are available for instances of \class{set} or
-its subtypes but not for instances of \class{frozenset} or its subtypes.
-
-\begin{cfuncdesc}{int}{PySet_Add}{PyObject *set, PyObject *key}
- Add \var{key} to a \class{set} instance. Does not apply to
- \class{frozenset} instances. Return 0 on success or -1 on failure.
- Raise a \exception{TypeError} if the \var{key} is unhashable.
- Raise a \exception{MemoryError} if there is no room to grow.
- Raise a \exception{SystemError} if \var{set} is an not an instance
- of \class{set} or its subtype.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \exception{KeyError}
- for missing keys. Raise a \exception{TypeError} if the \var{key} is
- unhashable. Unlike the Python \method{discard()} method, this function
- does not automatically convert unhashable sets into temporary frozensets.
- Raise \exception{PyExc_SystemError} if \var{set} is an not an instance
- of \class{set} or its subtype.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySet_Pop}{PyObject *set}
- Return a new reference to an arbitrary object in the \var{set},
- and removes the object from the \var{set}. Return \NULL{} on
- failure. Raise \exception{KeyError} if the set is empty.
- Raise a \exception{SystemError} if \var{set} is an not an instance
- of \class{set} or its subtype.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySet_Clear}{PyObject *set}
- Empty an existing set of all elements.
-\end{cfuncdesc}
diff --git a/Doc/api/exceptions.tex b/Doc/api/exceptions.tex
deleted file mode 100644
index 8676963..0000000
--- a/Doc/api/exceptions.tex
+++ /dev/null
@@ -1,428 +0,0 @@
-\chapter{Exception Handling \label{exceptionHandling}}
-
-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 \code{-1} if they
-return an integer (exception: the \cfunction{PyArg_*()} functions
-return \code{1} for success and \code{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
-\emph{not} continue normally if it is not prepared to handle the
-error. If returning due to an error, it is important to indicate to
-the caller that an error has been set. If the error is not handled or
-carefully propagated, additional calls into the Python/C API may not
-behave as intended and may fail in mysterious ways.
-
-The error indicator consists of three Python objects corresponding to
-the result of \code{sys.exc_info()}. API functions exist to interact
-with the error indicator in various ways. There is a separate
-error indicator for each thread.
-
-% XXX Order of these should be more thoughtful.
-% Either alphabetical or some kind of structure.
-
-\begin{cfuncdesc}{void}{PyErr_Print}{}
- Print a standard traceback to \code{sys.stderr} and clear the error
- indicator. Call this function only when the error indicator is
- set. (Otherwise it will cause a fatal error!)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{}
- Test whether the error indicator is set. If set, return the
- exception \emph{type} (the first argument to the last call to one of
- the \cfunction{PyErr_Set*()} functions or to
- \cfunction{PyErr_Restore()}). If not set, return \NULL. You do
- not own a reference to the return value, so you do not need to
- \cfunction{Py_DECREF()} it. \note{Do not compare the return value
- to a specific exception; use \cfunction{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.)}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
- Equivalent to \samp{PyErr_GivenExceptionMatches(PyErr_Occurred(),
- \var{exc})}. This should only be called when an exception is
- actually set; a memory access violation will occur if no exception
- has been raised.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc}
- Return true if the \var{given} exception matches the exception in
- \var{exc}. If \var{exc} is a class object, this also returns true
- when \var{given} is an instance of a subclass. If \var{exc} is a
- tuple, all exceptions in the tuple (and recursively in subtuples)
- are searched for a match. If \var{given} is \NULL, a memory access
- violation will occur.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb}
- Under certain circumstances, the values returned by
- \cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning
- that \code{*\var{exc}} is a class object but \code{*\var{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_Clear}{}
- Clear the error indicator. If the error indicator is not set, there
- is no effect.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \cfunction{PyErr_Fetch()} to save the current
- exception state.}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value}
- This function is similar to \cfunction{PyErr_SetString()} but lets
- you specify an arbitrary Python object for the ``value'' of the
- exception.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception,
- const char *format, \moreargs}
- This function sets the error indicator and returns \NULL.
- \var{exception} should be a Python exception (class, not
- an instance). \var{format} should be a string, containing format
- codes, similar to \cfunction{printf()}. The \code{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.
-
- \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment}
- \lineiii{\%\%}{\emph{n/a}}{The literal \% character.}
- \lineiii{\%c}{int}{A single character, represented as an C int.}
- \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
- \lineiii{\%u}{unsigned int}{Exactly equivalent to \code{printf("\%u")}.}
- \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
- \lineiii{\%lu}{unsigned long}{Exactly equivalent to \code{printf("\%lu")}.}
- \lineiii{\%zd}{Py_ssize_t}{Exactly equivalent to \code{printf("\%zd")}.}
- \lineiii{\%zu}{size_t}{Exactly equivalent to \code{printf("\%zu")}.}
- \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
- \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
- \lineiii{\%s}{char*}{A null-terminated C character array.}
- \lineiii{\%p}{void*}{The hex representation of a C pointer.
- Mostly equivalent to \code{printf("\%p")} except that it is
- guaranteed to start with the literal \code{0x} regardless of
- what the platform's \code{printf} yields.}
- \end{tableiii}
-
- 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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
- This is a shorthand for \samp{PyErr_SetObject(\var{type},
- Py_None)}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_BadArgument}{}
- This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
- \var{message})}, where \var{message} indicates that a built-in
- operation was invoked with an illegal argument. It is mostly for
- internal use.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{}
- This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it
- returns \NULL{} so an object allocation function can write
- \samp{return PyErr_NoMemory();} when it runs out of memory.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrno}{PyObject *type}
- 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
- \cfunction{strerror()}\ttindex{strerror()}), and then calls
- \samp{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX, when
- the \cdata{errno} value is \constant{EINTR}, indicating an
- interrupted system call, this calls
- \cfunction{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
- \samp{return PyErr_SetFromErrno(\var{type});} when the system call
- returns an error.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type,
- const char *filename}
- Similar to \cfunction{PyErr_SetFromErrno()}, with the additional
- behavior that if \var{filename} is not \NULL, it is passed to the
- constructor of \var{type} as a third parameter. In the case of
- exceptions such as \exception{IOError} and \exception{OSError}, this
- is used to define the \member{filename} attribute of the exception
- instance.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_SetFromWindowsErr}{int ierr}
- This is a convenience function to raise \exception{WindowsError}.
- If called with \var{ierr} of \cdata{0}, the error code returned by a
- call to \cfunction{GetLastError()} is used instead. It calls the
- Win32 function \cfunction{FormatMessage()} to retrieve the Windows
- description of error code given by \var{ierr} or
- \cfunction{GetLastError()}, then it constructs a tuple object whose
- first item is the \var{ierr} value and whose second item is the
- corresponding error message (gotten from
- \cfunction{FormatMessage()}), and then calls
- \samp{PyErr_SetObject(\var{PyExc_WindowsError}, \var{object})}.
- This function always returns \NULL.
- Availability: Windows.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErr}{PyObject *type,
- int ierr}
- Similar to \cfunction{PyErr_SetFromWindowsErr()}, with an additional
- parameter specifying the exception type to be raised.
- Availability: Windows.
- \versionadded{2.3}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_SetFromWindowsErrWithFilename}{int ierr,
- const char *filename}
- Similar to \cfunction{PyErr_SetFromWindowsErr()}, with the
- additional behavior that if \var{filename} is not \NULL, it is
- passed to the constructor of \exception{WindowsError} as a third
- parameter.
- Availability: Windows.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErrWithFilename}
- {PyObject *type, int ierr, char *filename}
- Similar to \cfunction{PyErr_SetFromWindowsErrWithFilename()}, with
- an additional parameter specifying the exception type to be raised.
- Availability: Windows.
- \versionadded{2.3}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
- This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
- \var{message})}, where \var{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_WarnEx}{PyObject *category, char *message, int stacklevel}
- Issue a warning message. The \var{category} argument is a warning
- category (see below) or \NULL; the \var{message} argument is a
- message string. \var{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 \var{stacklevel}
- of 1 is the function calling \cfunction{PyErr_WarnEx()}, 2 is
- the function above that, and so forth.
-
- This function normally prints a warning message to \var{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 \module{warnings} module to do the heavy
- lifting). The return value is \code{0} if no exception is raised,
- or \code{-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, \cfunction{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 \samp{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
- \module{warnings} module and the \programopt{-W} option in the
- command line documentation. There is no C API for warning control.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \function{warnings.warn_explicit()}, see there for more
- information. The \var{module} and \var{registry} arguments may be
- set to \NULL{} to get the default effect described there.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
- 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
- \module{signal}\refbimodindex{signal} module is supported, this can
- invoke a signal handler written in Python. In all cases, the
- default effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the
- \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
- \exception{KeyboardInterrupt} exception. If an exception is raised
- the error indicator is set and the function returns \code{-1};
- otherwise the function returns \code{0}. The error indicator may or
- may not be cleared if it was previously set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
- This function simulates the effect of a
- \constant{SIGINT}\ttindex{SIGINT} signal arriving --- the next time
- \cfunction{PyErr_CheckSignals()} is called,
- \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
- \exception{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
- PyObject *base,
- PyObject *dict}
- This utility function creates and returns a new exception object.
- The \var{name} argument must be the name of the new exception, a C
- string of the form \code{module.class}. The \var{base} and
- \var{dict} arguments are normally \NULL. This creates a class
- object derived from \exception{Exception} (accessible in C as
- \cdata{PyExc_Exception}).
-
- The \member{__module__} attribute of the new class is set to the
- first part (up to the last dot) of the \var{name} argument, and the
- class name is set to the last part (after the last dot). The
- \var{base} argument can be used to specify alternate base classes;
- it can either be only one class or a tuple of classes.
- The \var{dict} argument can be used to specify a dictionary of class
- variables and methods.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_WriteUnraisable}{PyObject *obj}
- This utility function prints a warning message to \code{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 \method{__del__()} method.
-
- The function is called with a single argument \var{obj} that
- identifies the context in which the unraisable exception occurred.
- The repr of \var{obj} will be printed in the warning message.
-\end{cfuncdesc}
-
-\section{Standard Exceptions \label{standardExceptions}}
-
-All standard Python exceptions are available as global variables whose
-names are \samp{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:
-
-\begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes}
- \lineiii{PyExc_BaseException\ttindex{PyExc_BaseException}}{\exception{BaseException}}{(1), (4)}
- \lineiii{PyExc_Exception\ttindex{PyExc_Exception}}{\exception{Exception}}{(1)}
- \lineiii{PyExc_ArithmeticError\ttindex{PyExc_ArithmeticError}}{\exception{ArithmeticError}}{(1)}
- \lineiii{PyExc_LookupError\ttindex{PyExc_LookupError}}{\exception{LookupError}}{(1)}
- \lineiii{PyExc_AssertionError\ttindex{PyExc_AssertionError}}{\exception{AssertionError}}{}
- \lineiii{PyExc_AttributeError\ttindex{PyExc_AttributeError}}{\exception{AttributeError}}{}
- \lineiii{PyExc_EOFError\ttindex{PyExc_EOFError}}{\exception{EOFError}}{}
- \lineiii{PyExc_EnvironmentError\ttindex{PyExc_EnvironmentError}}{\exception{EnvironmentError}}{(1)}
- \lineiii{PyExc_FloatingPointError\ttindex{PyExc_FloatingPointError}}{\exception{FloatingPointError}}{}
- \lineiii{PyExc_IOError\ttindex{PyExc_IOError}}{\exception{IOError}}{}
- \lineiii{PyExc_ImportError\ttindex{PyExc_ImportError}}{\exception{ImportError}}{}
- \lineiii{PyExc_IndexError\ttindex{PyExc_IndexError}}{\exception{IndexError}}{}
- \lineiii{PyExc_KeyError\ttindex{PyExc_KeyError}}{\exception{KeyError}}{}
- \lineiii{PyExc_KeyboardInterrupt\ttindex{PyExc_KeyboardInterrupt}}{\exception{KeyboardInterrupt}}{}
- \lineiii{PyExc_MemoryError\ttindex{PyExc_MemoryError}}{\exception{MemoryError}}{}
- \lineiii{PyExc_NameError\ttindex{PyExc_NameError}}{\exception{NameError}}{}
- \lineiii{PyExc_NotImplementedError\ttindex{PyExc_NotImplementedError}}{\exception{NotImplementedError}}{}
- \lineiii{PyExc_OSError\ttindex{PyExc_OSError}}{\exception{OSError}}{}
- \lineiii{PyExc_OverflowError\ttindex{PyExc_OverflowError}}{\exception{OverflowError}}{}
- \lineiii{PyExc_ReferenceError\ttindex{PyExc_ReferenceError}}{\exception{ReferenceError}}{(2)}
- \lineiii{PyExc_RuntimeError\ttindex{PyExc_RuntimeError}}{\exception{RuntimeError}}{}
- \lineiii{PyExc_SyntaxError\ttindex{PyExc_SyntaxError}}{\exception{SyntaxError}}{}
- \lineiii{PyExc_SystemError\ttindex{PyExc_SystemError}}{\exception{SystemError}}{}
- \lineiii{PyExc_SystemExit\ttindex{PyExc_SystemExit}}{\exception{SystemExit}}{}
- \lineiii{PyExc_TypeError\ttindex{PyExc_TypeError}}{\exception{TypeError}}{}
- \lineiii{PyExc_ValueError\ttindex{PyExc_ValueError}}{\exception{ValueError}}{}
- \lineiii{PyExc_WindowsError\ttindex{PyExc_WindowsError}}{\exception{WindowsError}}{(3)}
- \lineiii{PyExc_ZeroDivisionError\ttindex{PyExc_ZeroDivisionError}}{\exception{ZeroDivisionError}}{}
-\end{tableiii}
-
-\noindent
-Notes:
-\begin{description}
-\item[(1)]
- This is a base class for other standard exceptions.
-
-\item[(2)]
- This is the same as \exception{weakref.ReferenceError}.
-
-\item[(3)]
- Only defined on Windows; protect code that uses this by testing that
- the preprocessor macro \code{MS_WINDOWS} is defined.
-
-\item[(4)]
- \versionadded{2.5}
-\end{description}
-
-
-\section{Deprecation of String Exceptions}
-
-All exceptions built into Python or provided in the standard library
-are derived from \exception{BaseException}.
-\withsubitem{(built-in exception)}{\ttindex{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.
diff --git a/Doc/api/init.tex b/Doc/api/init.tex
deleted file mode 100644
index 76fcf61..0000000
--- a/Doc/api/init.tex
+++ /dev/null
@@ -1,884 +0,0 @@
-\chapter{Initialization, Finalization, and Threads
- \label{initialization}}
-
-\begin{cfuncdesc}{void}{Py_Initialize}{}
- 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
- \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()},
- \cfunction{PyEval_InitThreads()}\ttindex{PyEval_InitThreads()},
- \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()},
- and \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()}.
- This initializes the table of loaded modules (\code{sys.modules}),
- and\withsubitem{(in module sys)}{\ttindex{modules}\ttindex{path}}
- creates the fundamental modules
- \module{__builtin__}\refbimodindex{__builtin__},
- \module{__main__}\refbimodindex{__main__} and
- \module{sys}\refbimodindex{sys}. It also initializes the module
- search\indexiii{module}{search}{path} path (\code{sys.path}).
- It does not set \code{sys.argv}; use
- \cfunction{PySys_SetArgv()}\ttindex{PySys_SetArgv()} for that. This
- is a no-op when called for a second time (without calling
- \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} first). There is
- no return value; it is a fatal error if the initialization fails.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_InitializeEx}{int initsigs}
- This function works like \cfunction{Py_Initialize()} if
- \var{initsigs} is 1. If \var{initsigs} is 0, it skips
- initialization registration of signal handlers, which
- might be useful when Python is embedded. \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_IsInitialized}{}
- Return true (nonzero) when the Python interpreter has been
- initialized, false (zero) if not. After \cfunction{Py_Finalize()}
- is called, this returns false until \cfunction{Py_Initialize()} is
- called again.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_Finalize}{}
- Undo all initializations made by \cfunction{Py_Initialize()} and
- subsequent use of Python/C API functions, and destroy all
- sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that
- were created and not yet destroyed since the last call to
- \cfunction{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 \cfunction{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.
-
- \strong{Bugs and caveats:} The destruction of modules and objects in
- modules is done in random order; this may cause destructors
- (\method{__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 \cfunction{Py_Initialize()} and
- \cfunction{Py_Finalize()} more than once.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState*}{Py_NewInterpreter}{}
- 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
- \module{__builtin__}\refbimodindex{__builtin__},
- \module{__main__}\refbimodindex{__main__} and
- \module{sys}\refbimodindex{sys}. The table of loaded modules
- (\code{sys.modules}) and the module search path (\code{sys.path})
- are also separate. The new environment has no \code{sys.argv}
- variable. It has new standard I/O stream file objects
- \code{sys.stdin}, \code{sys.stdout} and \code{sys.stderr} (however
- these refer to the same underlying \ctype{FILE} structures in the C
- library).
- \withsubitem{(in module sys)}{
- \ttindex{stdout}\ttindex{stderr}\ttindex{stdin}}
-
- 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.)
-
- 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 \code{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
- \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and
- \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}; in that case,
- the extension's \code{init\var{module}} function \emph{is} called
- again.
-
- \strong{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 \withsubitem{(in module os)}{\ttindex{close()}}
- \function{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
- \cfunction{PyGILState_*} APIs (and this is inherent in the way the
- \cfunction{PyGILState_*} functions work). Simple things may work,
- but confusing behavior will always be near.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
- 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.) \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} will
- destroy all sub-interpreters that haven't been explicitly destroyed
- at that point.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
- This function should be called before
- \cfunction{Py_Initialize()}\ttindex{Py_Initialize()} is called
- for the first time, if it is called at all. It tells the
- interpreter the value of the \code{argv[0]} argument to the
- \cfunction{main()}\ttindex{main()} function of the program. This is
- used by \cfunction{Py_GetPath()}\ttindex{Py_GetPath()} and some
- other functions below to find the Python run-time libraries relative
- to the interpreter executable. The default value is
- \code{'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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetProgramName}{}
- Return the program name set with
- \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, or the
- default. The returned string points into static storage; the caller
- should not modify its value.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetPrefix}{}
- Return the \emph{prefix} for installed platform-independent files.
- This is derived through a number of complicated rules from the
- program name set with \cfunction{Py_SetProgramName()} and some
- environment variables; for example, if the program name is
- \code{'/usr/local/bin/python'}, the prefix is \code{'/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
- \longprogramopt{prefix} argument to the \program{configure} script
- at build time. The value is available to Python code as
- \code{sys.prefix}. It is only useful on \UNIX{}. See also the next
- function.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetExecPrefix}{}
- Return the \emph{exec-prefix} for installed
- platform-\emph{de}pendent files. This is derived through a number
- of complicated rules from the program name set with
- \cfunction{Py_SetProgramName()} and some environment variables; for
- example, if the program name is \code{'/usr/local/bin/python'}, the
- exec-prefix is \code{'/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 \longprogramopt{exec-prefix} argument to the
- \program{configure} script at build time. The value is available
- to Python code as \code{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{}
- 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
- \cfunction{Py_SetProgramName()}\ttindex{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
- \code{sys.executable}.
- \withsubitem{(in module sys)}{\ttindex{executable}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetPath}{}
- \indexiii{module}{search}{path}
- Return the default module search path; this is computed from the
- program name (set by \cfunction{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 \character{:} on \UNIX{} and Mac OS X,
- \character{;} 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
- \code{sys.path}\withsubitem{(in module sys)}{\ttindex{path}}, which
- may be modified to change the future search path for loaded
- modules.
-
- % XXX should give the exact rules
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetVersion}{}
- Return the version of this Python interpreter. This is a string
- that looks something like
-
-\begin{verbatim}
-"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
-\end{verbatim}
-
- 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 \code{sys.version}.
- \withsubitem{(in module sys)}{\ttindex{version}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetPlatform}{}
- 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 \code{'sunos5'}. On Mac OS X, it is \code{'darwin'}. On Windows,
- it is \code{'win'}. The returned string points into static storage;
- the caller should not modify its value. The value is available to
- Python code as \code{sys.platform}.
- \withsubitem{(in module sys)}{\ttindex{platform}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetCopyright}{}
- Return the official copyright string for the current Python version,
- for example
-
- \code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'}
-
- The returned string points into static storage; the caller should
- not modify its value. The value is available to Python code as
- \code{sys.copyright}.
- \withsubitem{(in module sys)}{\ttindex{copyright}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetCompiler}{}
- Return an indication of the compiler used to build the current
- Python version, in square brackets, for example:
-
-\begin{verbatim}
-"[GCC 2.7.2.2]"
-\end{verbatim}
-
- 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 \code{sys.version}.
- \withsubitem{(in module sys)}{\ttindex{version}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetBuildInfo}{}
- Return information about the sequence number and build date and time
- of the current Python interpreter instance, for example
-
-\begin{verbatim}
-"#67, Aug 1 1997, 22:34:28"
-\end{verbatim}
-
- 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 \code{sys.version}.
- \withsubitem{(in module sys)}{\ttindex{version}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PySys_SetArgv}{int argc, char **argv}
- Set \code{sys.argv} based on \var{argc} and \var{argv}. These
- parameters are similar to those passed to the program's
- \cfunction{main()}\ttindex{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 \var{argv} can
- be an empty string. If this function fails to initialize
- \code{sys.argv}, a fatal condition is signalled using
- \cfunction{Py_FatalError()}\ttindex{Py_FatalError()}.
- \withsubitem{(in module sys)}{\ttindex{argv}}
- % XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
- % check w/ Guido.
-\end{cfuncdesc}
-
-% XXX Other PySys thingies (doesn't really belong in this chapter)
-
-\section{Thread State and the Global Interpreter Lock
- \label{threads}}
-
-\index{global interpreter lock}
-\index{interpreter lock}
-\index{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.
-
-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
-\withsubitem{(in module sys)}{\ttindex{setcheckinterval()}}
-\function{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.
-
-The Python interpreter needs to keep some bookkeeping information
-separate per thread --- for this it uses a data structure called
-\ctype{PyThreadState}\ttindex{PyThreadState}. There's one global
-variable, however: the pointer to the current
-\ctype{PyThreadState}\ttindex{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:
-
-\begin{verbatim}
-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.
-\end{verbatim}
-
-This is so common that a pair of macros exists to simplify it:
-
-\begin{verbatim}
-Py_BEGIN_ALLOW_THREADS
-...Do some blocking I/O operation...
-Py_END_ALLOW_THREADS
-\end{verbatim}
-
-The
-\csimplemacro{Py_BEGIN_ALLOW_THREADS}\ttindex{Py_BEGIN_ALLOW_THREADS}
-macro opens a new block and declares a hidden local variable; the
-\csimplemacro{Py_END_ALLOW_THREADS}\ttindex{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:
-
-\begin{verbatim}
- PyThreadState *_save;
-
- _save = PyEval_SaveThread();
- ...Do some blocking I/O operation...
- PyEval_RestoreThread(_save);
-\end{verbatim}
-
-Using even lower level primitives, we can get roughly the same effect
-as follows:
-
-\begin{verbatim}
- PyThreadState *_save;
-
- _save = PyThreadState_Swap(NULL);
- PyEval_ReleaseLock();
- ...Do some blocking I/O operation...
- PyEval_AcquireLock();
- PyThreadState_Swap(_save);
-\end{verbatim}
-
-There are some subtle differences; in particular,
-\cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()} saves
-and restores the value of the global variable
-\cdata{errno}\ttindex{errno}, since the lock manipulation does not
-guarantee that \cdata{errno} is left alone. Also, when thread support
-is disabled,
-\cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and
-\cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this
-case, \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} and
-\cfunction{PyEval_AcquireLock()}\ttindex{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
-\cfunction{PyGILState_*()} functions to do all of the above
-automatically. The typical idiom for calling into Python from a C
-thread is now:
-
-\begin{verbatim}
- 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);
-\end{verbatim}
-
-Note that the \cfunction{PyGILState_*()} functions assume there is
-only one global interpreter (created automatically by
-\cfunction{Py_Initialize()}). Python still supports the creation of
-additional interpreters (using \cfunction{Py_NewInterpreter()}), but
-mixing multiple interpreters and the \cfunction{PyGILState_*()} API is
-unsupported.
-
-\begin{ctypedesc}{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.
-\end{ctypedesc}
-
-\begin{ctypedesc}{PyThreadState}
- This data structure represents the state of a single thread. The
- only public data member is \ctype{PyInterpreterState
- *}\member{interp}, which points to this thread's interpreter state.
-\end{ctypedesc}
-
-\begin{cfuncdesc}{void}{PyEval_InitThreads}{}
- 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
- \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} or
- \code{PyEval_ReleaseThread(\var{tstate})}\ttindex{PyEval_ReleaseThread()}.
- It is not needed before calling
- \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} or
- \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}.
-
- This is a no-op when called for a second time. It is safe to call
- this function before calling
- \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
-
- 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
- \module{thread}\refbimodindex{thread} module creates a new thread,
- knowing that either it has the lock or the lock hasn't been created
- yet, it calls \cfunction{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 \strong{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyEval_ThreadsInitialized}{}
- Returns a non-zero value if \cfunction{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}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
- Acquire the global interpreter lock and set the current thread
- state to \var{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \var{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \var{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.)
-\end{cfuncdesc}
-
-The following macros are normally used without a trailing semicolon;
-look for example usage in the Python source distribution.
-
-\begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS}
- This macro expands to
- \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
- Note that it contains an opening brace; it must be matched with a
- following \csimplemacro{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.
-\end{csimplemacrodesc}
-
-\begin{csimplemacrodesc}{Py_END_ALLOW_THREADS}
- This macro expands to \samp{PyEval_RestoreThread(_save); \}}.
- Note that it contains a closing brace; it must be matched with an
- earlier \csimplemacro{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.
-\end{csimplemacrodesc}
-
-\begin{csimplemacrodesc}{Py_BLOCK_THREADS}
- This macro expands to \samp{PyEval_RestoreThread(_save);}: it is
- equivalent to \csimplemacro{Py_END_ALLOW_THREADS} without the
- closing brace. It is a no-op when thread support is disabled at
- compile time.
-\end{csimplemacrodesc}
-
-\begin{csimplemacrodesc}{Py_UNBLOCK_THREADS}
- This macro expands to \samp{_save = PyEval_SaveThread();}: it is
- equivalent to \csimplemacro{Py_BEGIN_ALLOW_THREADS} without the
- opening brace and variable declaration. It is a no-op when thread
- support is disabled at compile time.
-\end{csimplemacrodesc}
-
-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.
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
- Reset all information in an interpreter state object. The
- interpreter lock must be held.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \cfunction{PyInterpreterState_Clear()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
- Reset all information in a thread state object. The interpreter lock
- must be held.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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
- \cfunction{PyThreadState_Clear()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Swap}{PyThreadState *tstate}
- Swap the current thread state with the thread state given by the
- argument \var{tstate}, which may be \NULL. The interpreter lock
- must be held.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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[Previously this could only be called when a current
- thread is active, and \NULL{} meant that an exception was raised]{2.3}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyThreadState_SetAsyncExc}{long id, PyObject *exc}
- Asynchronously raise an exception in a thread.
- The \var{id} argument is the thread id of the target thread;
- \var{exc} is the exception object to be raised.
- This function does not steal any references to \var{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 \var{exc} is
- \constant{NULL}, the pending exception (if any) for the thread is cleared.
- This raises no exceptions.
- \versionadded{2.3}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \cfunction{PyGILState_Release()}.
-In general, other thread-related APIs may be used between
-\cfunction{PyGILState_Ensure()} and \cfunction{PyGILState_Release()}
-calls as long as the thread state is restored to its previous state
-before the Release(). For example, normal usage of the
-\csimplemacro{Py_BEGIN_ALLOW_THREADS} and
-\csimplemacro{Py_END_ALLOW_THREADS} macros is acceptable.
-
-The return value is an opaque "handle" to the thread state when
-\cfunction{PyGILState_Acquire()} was called, and must be passed to
-\cfunction{PyGILState_Release()} to ensure Python is left in the same
-state. Even though recursive calls are allowed, these handles
-\emph{cannot} be shared - each unique call to
-\cfunction{PyGILState_Ensure} must save the handle for its call to
-\cfunction{PyGILState_Release}.
-
-When the function returns, the current thread will hold the GIL.
-Failure is a fatal error.
- \versionadded{2.3}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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
-\cfunction{PyGILState_Ensure} call (but generally this state will be
-unknown to the caller, hence the use of the GILState API.)
-
-Every call to \cfunction{PyGILState_Ensure()} must be matched by a call to
-\cfunction{PyGILState_Release()} on the same thread.
- \versionadded{2.3}
-\end{cfuncdesc}
-
-
-\section{Profiling and Tracing \label{profiling}}
-
-\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.
-
-\begin{ctypedesc}[Py_tracefunc]{int (*Py_tracefunc)(PyObject *obj,
- PyFrameObject *frame, int what,
- PyObject *arg)}
- The type of the trace function registered using
- \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}.
- The first parameter is the object passed to the registration
- function as \var{obj}, \var{frame} is the frame object to which the
- event pertains, \var{what} is one of the constants
- \constant{PyTrace_CALL}, \constant{PyTrace_EXCEPTION},
- \constant{PyTrace_LINE}, \constant{PyTrace_RETURN},
- \constant{PyTrace_C_CALL}, \constant{PyTrace_C_EXCEPTION},
- or \constant{PyTrace_C_RETURN}, and \var{arg}
- depends on the value of \var{what}:
-
- \begin{tableii}{l|l}{constant}{Value of \var{what}}{Meaning of \var{arg}}
- \lineii{PyTrace_CALL}{Always \NULL.}
- \lineii{PyTrace_EXCEPTION}{Exception information as returned by
- \function{sys.exc_info()}.}
- \lineii{PyTrace_LINE}{Always \NULL.}
- \lineii{PyTrace_RETURN}{Value being returned to the caller.}
- \lineii{PyTrace_C_CALL}{Name of function being called.}
- \lineii{PyTrace_C_EXCEPTION}{Always \NULL.}
- \lineii{PyTrace_C_RETURN}{Always \NULL.}
- \end{tableii}
-\end{ctypedesc}
-
-\begin{cvardesc}{int}{PyTrace_CALL}
- The value of the \var{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.
-\end{cvardesc}
-
-\begin{cvardesc}{int}{PyTrace_EXCEPTION}
- The value of the \var{what} parameter to a \ctype{Py_tracefunc}
- function when an exception has been raised. The callback function
- is called with this value for \var{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.
-\end{cvardesc}
-
-\begin{cvardesc}{int}{PyTrace_LINE}
- The value passed as the \var{what} parameter to a trace function
- (but not a profiling function) when a line-number event is being
- reported.
-\end{cvardesc}
-
-\begin{cvardesc}{int}{PyTrace_RETURN}
- The value for the \var{what} parameter to \ctype{Py_tracefunc}
- functions when a call is returning without propagating an exception.
-\end{cvardesc}
-
-\begin{cvardesc}{int}{PyTrace_C_CALL}
- The value for the \var{what} parameter to \ctype{Py_tracefunc}
- functions when a C function is about to be called.
-\end{cvardesc}
-
-\begin{cvardesc}{int}{PyTrace_C_EXCEPTION}
- The value for the \var{what} parameter to \ctype{Py_tracefunc}
- functions when a C function has thrown an exception.
-\end{cvardesc}
-
-\begin{cvardesc}{int}{PyTrace_C_RETURN}
- The value for the \var{what} parameter to \ctype{Py_tracefunc}
- functions when a C function has returned.
-\end{cvardesc}
-
-\begin{cfuncdesc}{void}{PyEval_SetProfile}{Py_tracefunc func, PyObject *obj}
- Set the profiler function to \var{func}. The \var{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 \var{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj}
- Set the tracing function to \var{func}. This is similar to
- \cfunction{PyEval_SetProfile()}, except the tracing function does
- receive line-number events.
-\end{cfuncdesc}
-
-
-\section{Advanced Debugger Support \label{advanced-debugging}}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-These functions are only intended to be used by advanced debugging
-tools.
-
-\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Head}{}
- Return the interpreter state object at the head of the list of all
- such objects.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Next}{PyInterpreterState *interp}
- Return the next interpreter state object after \var{interp} from the
- list of all such objects.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState *}{PyInterpreterState_ThreadHead}{PyInterpreterState *interp}
- Return the a pointer to the first \ctype{PyThreadState} object in
- the list of threads associated with the interpreter \var{interp}.
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Next}{PyThreadState *tstate}
- Return the next thread state object after \var{tstate} from the list
- of all such objects belonging to the same \ctype{PyInterpreterState}
- object.
- \versionadded{2.2}
-\end{cfuncdesc}
diff --git a/Doc/api/intro.tex b/Doc/api/intro.tex
deleted file mode 100644
index a945180..0000000
--- a/Doc/api/intro.tex
+++ /dev/null
@@ -1,624 +0,0 @@
-\chapter{Introduction \label{intro}}
-
-
-The Application Programmer's Interface to Python gives C and
-\Cpp{} programmers access to the Python interpreter at a variety of
-levels. The API is equally usable from \Cpp, 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 \emph{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.
-
-
-\section{Include Files \label{includes}}
-
-All function, type and macro definitions needed to use the Python/C
-API are included in your code by the following line:
-
-\begin{verbatim}
-#include "Python.h"
-\end{verbatim}
-
-This implies inclusion of the following standard headers:
-\code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>},
-\code{<limits.h>}, and \code{<stdlib.h>} (if available).
-
-\begin{notice}[warning]
- Since Python may define some pre-processor definitions which affect
- the standard headers on some systems, you \emph{must} include
- \file{Python.h} before any standard headers are included.
-\end{notice}
-
-All user visible names defined by Python.h (except those defined by
-the included standard headers) have one of the prefixes \samp{Py} or
-\samp{_Py}. Names beginning with \samp{_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.
-
-\strong{Important:} user code should never define names that begin
-with \samp{Py} or \samp{_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{\envvar{prefix}/include/python\var{version}/} and
-\file{\envvar{exec_prefix}/include/python\var{version}/}, where
-\envvar{prefix} and \envvar{exec_prefix} are defined by the
-corresponding parameters to Python's \program{configure} script and
-\var{version} is \code{sys.version[:3]}. On Windows, the headers are
-installed in \file{\envvar{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 \emph{not} place the parent
-directories on the search path and then use
-\samp{\#include <python\shortversion/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}.
-
-\Cpp{} users should note that though the API is defined entirely using
-C, the header files do properly declare the entry points to be
-\code{extern "C"}, so there is no need to do anything special to use
-the API from \Cpp.
-
-
-\section{Objects, Types and Reference Counts \label{objects}}
-
-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\obindex{type};
-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 the \citetitle[../ref/ref.html]{Python
-Reference Manual}). For each of the well-known types there is a macro
-to check whether an object is of that type; for instance,
-\samp{PyList_Check(\var{a})} is true if (and only if) the object
-pointed to by \var{a} is a Python list.
-
-
-\subsection{Reference Counts \label{refcounts}}
-
-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.'')
-
-Reference counts are always manipulated explicitly. The normal way is
-to use the macro \cfunction{Py_INCREF()}\ttindex{Py_INCREF()} to
-increment an object's reference count by one, and
-\cfunction{Py_DECREF()}\ttindex{Py_DECREF()} to decrement it by
-one. The \cfunction{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 \code{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 \cfunction{Py_DECREF()},
-so almost any operation is potentially dangerous.
-
-A safe approach is to always use the generic operations (functions
-whose name begins with \samp{PyObject_}, \samp{PyNumber_},
-\samp{PySequence_} or \samp{PyMapping_}). These operations always
-increment the reference count of the object they return. This leaves
-the caller with the responsibility to call
-\cfunction{Py_DECREF()} when they are done with the result; this soon
-becomes second nature.
-
-
-\subsubsection{Reference Count Details \label{refcountDetails}}
-
-The reference count behavior of functions in the Python/C API is best
-explained in terms of \emph{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 \cfunction{Py_DECREF()} or
-\cfunction{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 \emph{new} reference. When no ownership
-is transferred, the caller is said to \emph{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 \emph{steals} a
-reference to the object, or it does not. \emph{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.
-
-Few functions steal references; the two notable exceptions are
-\cfunction{PyList_SetItem()}\ttindex{PyList_SetItem()} and
-\cfunction{PyTuple_SetItem()}\ttindex{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 \code{(1,
-2, "three")} could look like this (forgetting about error handling for
-the moment; a better way to code this is shown below):
-
-\begin{verbatim}
-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"));
-\end{verbatim}
-
-Here, \cfunction{PyInt_FromLong()} returns a new reference which is
-immediately stolen by \cfunction{PyTuple_SetItem()}. When you want to
-keep using an object although the reference to it will be stolen,
-use \cfunction{Py_INCREF()} to grab another reference before calling the
-reference-stealing function.
-
-Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to
-set tuple items; \cfunction{PySequence_SetItem()} and
-\cfunction{PyObject_SetItem()} refuse to do this since tuples are an
-immutable data type. You should only use
-\cfunction{PyTuple_SetItem()} for tuples that you are creating
-yourself.
-
-Equivalent code for populating a list can be written using
-\cfunction{PyList_New()} and \cfunction{PyList_SetItem()}.
-
-However, in practice, you will rarely use these ways of
-creating and populating a tuple or list. There's a generic function,
-\cfunction{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):
-
-\begin{verbatim}
-PyObject *tuple, *list;
-
-tuple = Py_BuildValue("(iis)", 1, 2, "three");
-list = Py_BuildValue("[iis]", 1, 2, "three");
-\end{verbatim}
-
-It is much more common to use \cfunction{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:
-
-\begin{verbatim}
-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;
-}
-\end{verbatim}
-\ttindex{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 \cfunction{PyObject_GetItem()} and
-\cfunction{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 --- \emph{the
-plumage} (the type of the object passed as an
-argument to the function) \emph{doesn't enter into it!} Thus, if you
-extract an item from a list using \cfunction{PyList_GetItem()}, you
-don't own the reference --- but if you obtain the same item from the
-same list using \cfunction{PySequence_GetItem()} (which happens to
-take exactly the same arguments), you do own a reference to the
-returned object.
-
-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
-\cfunction{PyList_GetItem()}\ttindex{PyList_GetItem()}, and once using
-\cfunction{PySequence_GetItem()}\ttindex{PySequence_GetItem()}.
-
-\begin{verbatim}
-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;
-}
-\end{verbatim}
-\ttindex{sum_list()}
-
-\begin{verbatim}
-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;
-}
-\end{verbatim}
-\ttindex{sum_sequence()}
-
-
-\subsection{Types \label{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.
-
-
-\section{Exceptions \label{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.
-
-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 \code{-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
-\cfunction{PyErr_Occurred()}\ttindex{PyErr_Occurred()}.
-
-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 \cfunction{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:
-\cfunction{PyErr_SetString()}\ttindex{PyErr_SetString()} is the most
-common (though not the most general) function to set the exception
-state, and \cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} clears the
-exception state.
-
-The full exception state consists of three objects (all of which can
-be \NULL): the exception type, the corresponding exception
-value, and the traceback. These have the same meanings as the Python
-result of \code{sys.exc_info()}; however, they are not the same: the Python
-objects represent the last exception being handled by a Python
-\keyword{try} \ldots\ \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 \code{sys.exc_info()}
-and friends.
-
-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
-\withsubitem{(in module sys)}{\ttindex{exc_info()}}
-\function{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 \emph{not} set another exception ---
-that would overwrite the exception that was just raised, and lose
-important information about the exact cause of the error.
-
-A simple example of detecting exceptions and passing them on is shown
-in the \cfunction{sum_sequence()}\ttindex{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:
-
-\begin{verbatim}
-def incr_item(dict, key):
- try:
- item = dict[key]
- except KeyError:
- item = 0
- dict[key] = item + 1
-\end{verbatim}
-\ttindex{incr_item()}
-
-Here is the corresponding C code, in all its glory:
-
-\begin{verbatim}
-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 */
-}
-\end{verbatim}
-\ttindex{incr_item()}
-
-This example represents an endorsed use of the \keyword{goto} statement
-in C! It illustrates the use of
-\cfunction{PyErr_ExceptionMatches()}\ttindex{PyErr_ExceptionMatches()} and
-\cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} to
-handle specific exceptions, and the use of
-\cfunction{Py_XDECREF()}\ttindex{Py_XDECREF()} to
-dispose of owned references that may be \NULL{} (note the
-\character{X} in the name; \cfunction{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
-\code{-1} (failure) and only set to success after the final call made
-is successful.
-
-
-\section{Embedding Python \label{embedding}}
-
-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.
-
-The basic initialization function is
-\cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
-This initializes the table of loaded modules, and creates the
-fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
-\module{__main__}\refbimodindex{__main__}, \module{sys}\refbimodindex{sys},
-and \module{exceptions}.\refbimodindex{exceptions} It also initializes
-the module search path (\code{sys.path}).%
-\indexiii{module}{search}{path}
-\withsubitem{(in module sys)}{\ttindex{path}}
-
-\cfunction{Py_Initialize()} does not set the ``script argument list''
-(\code{sys.argv}). If this variable is needed by Python code that
-will be executed later, it must be set explicitly with a call to
-\code{PySys_SetArgv(\var{argc},
-\var{argv})}\ttindex{PySys_SetArgv()} subsequent to the call to
-\cfunction{Py_Initialize()}.
-
-On most systems (in particular, on \UNIX{} and Windows, although the
-details are slightly different),
-\cfunction{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\shortversion} 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\shortversion}. (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}.
-
-The embedding application can steer the search by calling
-\code{Py_SetProgramName(\var{file})}\ttindex{Py_SetProgramName()} \emph{before} calling
-\cfunction{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
-\cfunction{Py_GetPath()}\ttindex{Py_GetPath()},
-\cfunction{Py_GetPrefix()}\ttindex{Py_GetPrefix()},
-\cfunction{Py_GetExecPrefix()}\ttindex{Py_GetExecPrefix()}, and
-\cfunction{Py_GetProgramFullPath()}\ttindex{Py_GetProgramFullPath()} (all
-defined in \file{Modules/getpath.c}).
-
-Sometimes, it is desirable to ``uninitialize'' Python. For instance,
-the application may want to start over (make another call to
-\cfunction{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 \cfunction{Py_Finalize()}. The function
-\cfunction{Py_IsInitialized()}\ttindex{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 \cfunction{Py_Finalize} does \emph{not} free all memory
-allocated by the Python interpreter, e.g. memory allocated by extension
-modules currently cannot be released.
-
-
-\section{Debugging Builds \label{debugging}}
-
-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 \csimplemacro{Py_DEBUG} macro
-defined produces what is generally meant by "a debug build" of Python.
-\csimplemacro{Py_DEBUG} is enabled in the \UNIX{} build by adding
-\longprogramopt{with-pydebug} to the \file{configure} command. It is also
-implied by the presence of the not-Python-specific
-\csimplemacro{_DEBUG} macro. When \csimplemacro{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:
-
-\begin{itemize}
- \item Extra checks are added to the object allocator.
- \item Extra checks are added to the parser and compiler.
- \item Downcasts from wide types to narrow types are checked for
- loss of information.
- \item A number of assertions are added to the dictionary and set
- implementations. In addition, the set object acquires a
- \method{test_c_api} method.
- \item Sanity checks of the input arguments are added to frame
- creation.
- \item The storage for long ints is initialized with a known
- invalid pattern to catch reference to uninitialized
- digits.
- \item Low-level tracing and extra exception checking are added
- to the runtime virtual machine.
- \item Extra checks are added to the memory arena implementation.
- \item Extra debugging is added to the thread module.
-\end{itemize}
-
-There may be additional checks not mentioned here.
-
-Defining \csimplemacro{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 \csimplemacro{Py_DEBUG}.
-
-Please refer to \file{Misc/SpecialBuilds.txt} in the Python source
-distribution for more detailed information.
diff --git a/Doc/api/memory.tex b/Doc/api/memory.tex
deleted file mode 100644
index 18abe98..0000000
--- a/Doc/api/memory.tex
+++ /dev/null
@@ -1,204 +0,0 @@
-\chapter{Memory Management \label{memory}}
-\sectionauthor{Vladimir Marangozov}{Vladimir.Marangozov@inrialpes.fr}
-
-
-\section{Overview \label{memoryOverview}}
-
-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 \emph{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.
-
-To avoid memory corruption, extension writers should never try to
-operate on Python objects with the functions exported by the C
-library: \cfunction{malloc()}\ttindex{malloc()},
-\cfunction{calloc()}\ttindex{calloc()},
-\cfunction{realloc()}\ttindex{realloc()} and
-\cfunction{free()}\ttindex{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:
-
-\begin{verbatim}
- 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;
-\end{verbatim}
-
-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 \emph{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.
-
-
-\section{Memory Interface \label{memoryInterface}}
-
-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:
-
-
-\begin{cfuncdesc}{void*}{PyMem_Malloc}{size_t n}
- Allocates \var{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 \cfunction{PyMem_Malloc(1)} had been called instead.
- The memory will not have been initialized in any way.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void*}{PyMem_Realloc}{void *p, size_t n}
- Resizes the memory block pointed to by \var{p} to \var{n} bytes.
- The contents will be unchanged to the minimum of the old and the new
- sizes. If \var{p} is \NULL, the call is equivalent to
- \cfunction{PyMem_Malloc(\var{n})}; else if \var{n} is equal to zero, the
- memory block is resized but is not freed, and the returned pointer
- is non-\NULL. Unless \var{p} is \NULL, it must have been
- returned by a previous call to \cfunction{PyMem_Malloc()} or
- \cfunction{PyMem_Realloc()}. If the request fails,
- \cfunction{PyMem_Realloc()} returns \NULL{} and \var{p} remains a
- valid pointer to the previous memory area.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyMem_Free}{void *p}
- Frees the memory block pointed to by \var{p}, which must have been
- returned by a previous call to \cfunction{PyMem_Malloc()} or
- \cfunction{PyMem_Realloc()}. Otherwise, or if
- \cfunction{PyMem_Free(p)} has been called before, undefined
- behavior occurs. If \var{p} is \NULL, no operation is performed.
-\end{cfuncdesc}
-
-The following type-oriented macros are provided for convenience. Note
-that \var{TYPE} refers to any C type.
-
-\begin{cfuncdesc}{\var{TYPE}*}{PyMem_New}{TYPE, size_t n}
- Same as \cfunction{PyMem_Malloc()}, but allocates \code{(\var{n} *
- sizeof(\var{TYPE}))} bytes of memory. Returns a pointer cast to
- \ctype{\var{TYPE}*}. The memory will not have been initialized in
- any way.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{\var{TYPE}*}{PyMem_Resize}{void *p, TYPE, size_t n}
- Same as \cfunction{PyMem_Realloc()}, but the memory block is resized
- to \code{(\var{n} * sizeof(\var{TYPE}))} bytes. Returns a pointer
- cast to \ctype{\var{TYPE}*}. On return, \var{p} will be a pointer to
- the new memory area, or \NULL{} in the event of failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyMem_Del}{void *p}
- Same as \cfunction{PyMem_Free()}.
-\end{cfuncdesc}
-
-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.
-
-\cfunction{PyMem_MALLOC()}, \cfunction{PyMem_REALLOC()}, \cfunction{PyMem_FREE()}.
-
-\cfunction{PyMem_NEW()}, \cfunction{PyMem_RESIZE()}, \cfunction{PyMem_DEL()}.
-
-
-\section{Examples \label{memoryExamples}}
-
-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:
-
-\begin{verbatim}
- 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;
-\end{verbatim}
-
-The same code using the type-oriented function set:
-
-\begin{verbatim}
- 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;
-\end{verbatim}
-
-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 \emph{fatal} because it mixes two different
-allocators operating on different heaps.
-
-\begin{verbatim}
-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() */
-\end{verbatim}
-
-In addition to the functions aimed at handling raw memory blocks from
-the Python heap, objects in Python are allocated and released with
-\cfunction{PyObject_New()}, \cfunction{PyObject_NewVar()} and
-\cfunction{PyObject_Del()}.
-
-These will be explained in the next chapter on defining and
-implementing new object types in C.
diff --git a/Doc/api/newtypes.tex b/Doc/api/newtypes.tex
deleted file mode 100644
index 77ad7a5..0000000
--- a/Doc/api/newtypes.tex
+++ /dev/null
@@ -1,1780 +0,0 @@
-\chapter{Object Implementation Support \label{newTypes}}
-
-
-This chapter describes the functions, types, and macros used when
-defining new object types.
-
-
-\section{Allocating Objects on the Heap
- \label{allocating-objects}}
-
-\begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyVarObject*}{_PyObject_NewVar}{PyTypeObject *type, Py_ssize_t size}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Init}{PyObject *op,
- PyTypeObject *type}
- Initialize a newly-allocated object \var{op} with its type and
- initial reference. Returns the initialized object. If \var{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyVarObject*}{PyObject_InitVar}{PyVarObject *op,
- PyTypeObject *type, Py_ssize_t size}
- This does everything \cfunction{PyObject_Init()} does, and also
- initializes the length information for a variable-size object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{\var{TYPE}*}{PyObject_New}{TYPE, PyTypeObject *type}
- Allocate a new Python object using the C structure type \var{TYPE}
- and the Python type object \var{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 \member{tp_basicsize} field of the
- type object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NewVar}{TYPE, PyTypeObject *type,
- Py_ssize_t size}
- Allocate a new Python object using the C structure type \var{TYPE}
- and the Python type object \var{type}. Fields not defined by the
- Python object header are not initialized. The allocated memory
- allows for the \var{TYPE} structure plus \var{size} fields of the
- size given by the \member{tp_itemsize} field of \var{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyObject_Del}{PyObject *op}
- Releases memory allocated to an object using
- \cfunction{PyObject_New()} or \cfunction{PyObject_NewVar()}. This
- is normally called from the \member{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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[Older versions of Python did not support \NULL{} as
- the value for the \var{methods} argument]{2.3}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \var{doc} is non-\NULL, it will
- be used to define the docstring for the module.
-
- \versionchanged[Older versions of Python did not support \NULL{} as
- the value for the \var{methods} argument]{2.3}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \var{doc} is non-\NULL, it will
- be used to define the docstring for the module. If \var{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 \var{apiver}, the only value which should
- be passed is defined by the constant \constant{PYTHON_API_VERSION}.
-
- \note{Most uses of this function should probably be using
- the \cfunction{Py_InitModule3()} instead; only use this if you are
- sure you need it.}
-
- \versionchanged[Older versions of Python did not support \NULL{} as
- the value for the \var{methods} argument]{2.3}
-\end{cfuncdesc}
-
-\begin{cvardesc}{PyObject}{_Py_NoneStruct}
- Object which is visible in Python as \code{None}. This should only
- be accessed using the \code{Py_None} macro, which evaluates to a
- pointer to this object.
-\end{cvardesc}
-
-
-\section{Common Object Structures \label{common-structs}}
-
-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.
-
-\begin{ctypedesc}{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 \code{PyObject_HEAD} macro.
-\end{ctypedesc}
-
-\begin{ctypedesc}{PyVarObject}
- This is an extension of \ctype{PyObject} that adds the
- \member{ob_size} field. This is only used for objects that have
- some notion of \emph{length}. This type does not often appear in
- the Python/C API. It corresponds to the fields defined by the
- expansion of the \code{PyObject_VAR_HEAD} macro.
-\end{ctypedesc}
-
-These macros are used in the definition of \ctype{PyObject} and
-\ctype{PyVarObject}:
-
-\begin{csimplemacrodesc}{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
- \csimplemacro{Py_TRACE_REFS}. By default, that macro is not
- defined, and \csimplemacro{PyObject_HEAD} expands to:
- \begin{verbatim}
- Py_ssize_t ob_refcnt;
- PyTypeObject *ob_type;
- \end{verbatim}
- When \csimplemacro{Py_TRACE_REFS} is defined, it expands to:
- \begin{verbatim}
- PyObject *_ob_next, *_ob_prev;
- Py_ssize_t ob_refcnt;
- PyTypeObject *ob_type;
- \end{verbatim}
-\end{csimplemacrodesc}
-
-\begin{csimplemacrodesc}{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:
- \begin{verbatim}
- PyObject_HEAD
- Py_ssize_t ob_size;
- \end{verbatim}
- Note that \csimplemacro{PyObject_HEAD} is part of the expansion, and
- that its own expansion varies depending on the definition of
- \csimplemacro{Py_TRACE_REFS}.
-\end{csimplemacrodesc}
-
-PyObject_HEAD_INIT
-
-\begin{ctypedesc}{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.
-\end{ctypedesc}
-
-\begin{ctypedesc}{PyMethodDef}
- Structure used to describe a method of an extension type. This
- structure has four fields:
-
- \begin{tableiii}{l|l|l}{member}{Field}{C Type}{Meaning}
- \lineiii{ml_name}{char *}{name of the method}
- \lineiii{ml_meth}{PyCFunction}{pointer to the C implementation}
- \lineiii{ml_flags}{int}{flag bits indicating how the call should be
- constructed}
- \lineiii{ml_doc}{char *}{points to the contents of the docstring}
- \end{tableiii}
-\end{ctypedesc}
-
-The \member{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 \var{self} object.
-
-The \member{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 \constant{METH_VARARGS} and \constant{METH_KEYWORDS} can be
-combined (but note that \constant{METH_KEYWORDS} alone is equivalent
-to \code{\constant{METH_VARARGS} | \constant{METH_KEYWORDS}}).
-Any of the calling convention flags can be combined with a
-binding flag.
-
-\begin{datadesc}{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 \var{self} object for
- methods; for module functions, it has the value given to
- \cfunction{Py_InitModule4()} (or \NULL{} if
- \cfunction{Py_InitModule()} was used). The second parameter
- (often called \var{args}) is a tuple object representing all
- arguments. This parameter is typically processed using
- \cfunction{PyArg_ParseTuple()} or \cfunction{PyArg_UnpackTuple}.
-\end{datadesc}
-
-\begin{datadesc}{METH_KEYWORDS}
- Methods with these flags must be of type
- \ctype{PyCFunctionWithKeywords}. The function expects three
- parameters: \var{self}, \var{args}, and a dictionary of all the
- keyword arguments. The flag is typically combined with
- \constant{METH_VARARGS}, and the parameters are typically processed
- using \cfunction{PyArg_ParseTupleAndKeywords()}.
-\end{datadesc}
-
-\begin{datadesc}{METH_NOARGS}
- Methods without parameters don't need to check whether arguments are
- given if they are listed with the \constant{METH_NOARGS} flag. They
- need to be of type \ctype{PyCFunction}. When used with object
- methods, the first parameter is typically named \code{self} and will
- hold a reference to the object instance. In all cases the second
- parameter will be \NULL.
-\end{datadesc}
-
-\begin{datadesc}{METH_O}
- Methods with a single object argument can be listed with the
- \constant{METH_O} flag, instead of invoking
- \cfunction{PyArg_ParseTuple()} with a \code{"O"} argument. They have
- the type \ctype{PyCFunction}, with the \var{self} parameter, and a
- \ctype{PyObject*} parameter representing the single argument.
-\end{datadesc}
-
-\begin{datadesc}{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.
-\end{datadesc}
-
-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.
-
-\begin{datadesc}{METH_CLASS}
- The method will be passed the type object as the first parameter
- rather than an instance of the type. This is used to create
- \emph{class methods}, similar to what is created when using the
- \function{classmethod()}\bifuncindex{classmethod} built-in
- function.
- \versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{METH_STATIC}
- The method will be passed \NULL{} as the first parameter rather than
- an instance of the type. This is used to create \emph{static
- methods}, similar to what is created when using the
- \function{staticmethod()}\bifuncindex{staticmethod} built-in
- function.
- \versionadded{2.3}
-\end{datadesc}
-
-One other constant controls whether a method is loaded in place of
-another definition with the same method name.
-
-\begin{datadesc}{METH_COEXIST}
- The method will be loaded in place of existing definitions. Without
- \var{METH_COEXIST}, the default is to skip repeated definitions. Since
- slot wrappers are loaded before the method table, the existence of a
- \var{sq_contains} slot, for example, would generate a wrapped method
- named \method{__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}
-\end{datadesc}
-
-\begin{cfuncdesc}{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
- \member{tp_getattro} or \member{tp_getattr} handler that does not
- use the \cfunction{PyObject_GenericGetAttr()} function.
-\end{cfuncdesc}
-
-
-\section{Type Objects \label{type-structs}}
-
-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 \cfunction{PyObject_*()} or \cfunction{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:
-
-\verbatiminput{typestruct.h}
-
-The type object structure extends the \ctype{PyVarObject} structure.
-The \member{ob_size} field is used for dynamic types (created
-by \function{type_new()}, usually called from a class statement).
-Note that \cdata{PyType_Type} (the metatype) initializes
-\member{tp_itemsize}, which means that its instances (i.e. type
-objects) \emph{must} have the \member{ob_size} field.
-
-\begin{cmemberdesc}{PyObject}{PyObject*}{_ob_next}
-\cmemberline{PyObject}{PyObject*}{_ob_prev}
- These fields are only present when the macro \code{Py_TRACE_REFS} is
- defined. Their initialization to \NULL{} is taken care of by the
- \code{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 \emph{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.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyObject}{Py_ssize_t}{ob_refcnt}
- This is the type object's reference count, initialized to \code{1}
- by the \code{PyObject_HEAD_INIT} macro. Note that for statically
- allocated type objects, the type's instances (objects whose
- \member{ob_type} points back to the type) do \emph{not} count as
- references. But for dynamically allocated type objects, the
- instances \emph{do} count as references.
-
- This field is not inherited by subtypes.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyObject}{PyTypeObject*}{ob_type}
- This is the type's type, in other words its metatype. It is
- initialized by the argument to the \code{PyObject_HEAD_INIT} macro,
- and its value should normally be \code{\&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
- \code{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:
-
-\begin{verbatim}
-Foo_Type.ob_type = &PyType_Type;
-\end{verbatim}
-
- This should be done before any instances of the type are created.
- \cfunction{PyType_Ready()} checks if \member{ob_type} is \NULL, and
- if so, initializes it: in Python 2.2, it is set to
- \code{\&PyType_Type}; in Python 2.2.1 and later it is
- initialized to the \member{ob_type} field of the base class.
- \cfunction{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.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyVarObject}{Py_ssize_t}{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.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{char*}{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 \module{M} in subpackage \module{Q} in package \module{P}
- should have the \member{tp_name} initializer \code{"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 \code{'__module__'}.
-
- For statically allocated type objects, the tp_name field should
- contain a dot. Everything before the last dot is made accessible as
- the \member{__module__} attribute, and everything after the last dot
- is made accessible as the \member{__name__} attribute.
-
- If no dot is present, the entire \member{tp_name} field is made
- accessible as the \member{__name__} attribute, and the
- \member{__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.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{Py_ssize_t}{tp_basicsize}
-\cmemberline{PyTypeObject}{Py_ssize_t}{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 \member{tp_itemsize} field, types with variable-length
- instances have a non-zero \member{tp_itemsize} field. For a type
- with fixed-length instances, all instances have the same size,
- given in \member{tp_basicsize}.
-
- For a type with variable-length instances, the instances must have
- an \member{ob_size} field, and the instance size is
- \member{tp_basicsize} plus N times \member{tp_itemsize}, where N is
- the ``length'' of the object. The value of N is typically stored in
- the instance's \member{ob_size} field. There are exceptions: for
- example, long ints use a negative \member{ob_size} to indicate a
- negative number, and N is \code{abs(\member{ob_size})} there. Also,
- the presence of an \member{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 \member{ob_size} field).
-
- The basic size includes the fields in the instance declared by the
- macro \csimplemacro{PyObject_HEAD} or
- \csimplemacro{PyObject_VAR_HEAD} (whichever is used to declare the
- instance struct) and this in turn includes the \member{_ob_prev} and
- \member{_ob_next} fields if they are present. This means that the
- only correct way to get an initializer for the \member{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 \member{tp_basicsize}).
-
- These fields are inherited separately by subtypes. If the base type
- has a non-zero \member{tp_itemsize}, it is generally not safe to set
- \member{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
- \member{tp_basicsize}. Example: suppose a type implements an array
- of \code{double}. \member{tp_itemsize} is \code{sizeof(double)}.
- It is the programmer's responsibility that \member{tp_basicsize} is
- a multiple of \code{sizeof(double)} (assuming this is the alignment
- requirement for \code{double}).
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{destructor}{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 \code{None} and
- \code{Ellipsis}).
-
- The destructor function is called by the \cfunction{Py_DECREF()} and
- \cfunction{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 \member{tp_free} function. If the
- type is not subtypable (doesn't have the
- \constant{Py_TPFLAGS_BASETYPE} flag bit set), it is permissible to
- call the object deallocator directly instead of via
- \member{tp_free}. The object deallocator should be the one used to
- allocate the instance; this is normally \cfunction{PyObject_Del()}
- if the instance was allocated using \cfunction{PyObject_New()} or
- \cfunction{PyObject_VarNew()}, or \cfunction{PyObject_GC_Del()} if
- the instance was allocated using \cfunction{PyObject_GC_New()} or
- \cfunction{PyObject_GC_VarNew()}.
-
- This field is inherited by subtypes.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{printfunc}{tp_print}
- An optional pointer to the instance print function.
-
- The print function is only called when the instance is printed to a
- \emph{real} file; when it is printed to a pseudo-file (like a
- \class{StringIO} instance), the instance's \member{tp_repr} or
- \member{tp_str} function is called to convert it to a string. These
- are also called when the type's \member{tp_print} field is \NULL. A
- type should never implement \member{tp_print} in a way that produces
- different output than \member{tp_repr} or \member{tp_str} would.
-
- The print function is called with the same signature as
- \cfunction{PyObject_Print()}: \code{int tp_print(PyObject *self, FILE
- *file, int flags)}. The \var{self} argument is the instance to be
- printed. The \var{file} argument is the stdio file to which it is
- to be printed. The \var{flags} argument is composed of flag bits.
- The only flag bit currently defined is \constant{Py_PRINT_RAW}.
- When the \constant{Py_PRINT_RAW} flag bit is set, the instance
- should be printed the same way as \member{tp_str} would format it;
- when the \constant{Py_PRINT_RAW} flag bit is clear, the instance
- should be printed the same was as \member{tp_repr} would format it.
- It should return \code{-1} and set an exception condition when an
- error occurred during the comparison.
-
- It is possible that the \member{tp_print} field will be deprecated.
- In any case, it is recommended not to define \member{tp_print}, but
- instead to rely on \member{tp_repr} and \member{tp_str} for
- printing.
-
- This field is inherited by subtypes.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{getattrfunc}{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 \member{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
- \cfunction{PyObject_GetAttrString()}.
-
- This field is inherited by subtypes together with
- \member{tp_getattro}: a subtype inherits both \member{tp_getattr}
- and \member{tp_getattro} from its base type when the subtype's
- \member{tp_getattr} and \member{tp_getattro} are both \NULL.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{setattrfunc}{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 \member{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
- \cfunction{PyObject_SetAttrString()}.
-
- This field is inherited by subtypes together with
- \member{tp_setattro}: a subtype inherits both \member{tp_setattr}
- and \member{tp_setattro} from its base type when the subtype's
- \member{tp_setattr} and \member{tp_setattro} are both \NULL.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{cmpfunc}{tp_compare}
- An optional pointer to the three-way comparison function.
-
- The signature is the same as for \cfunction{PyObject_Compare()}.
- The function should return \code{1} if \var{self} greater than
- \var{other}, \code{0} if \var{self} is equal to \var{other}, and
- \code{-1} if \var{self} less than \var{other}. It should return
- \code{-1} and set an exception condition when an error occurred
- during the comparison.
-
- This field is inherited by subtypes together with
- \member{tp_richcompare} and \member{tp_hash}: a subtypes inherits
- all three of \member{tp_compare}, \member{tp_richcompare}, and
- \member{tp_hash} when the subtype's \member{tp_compare},
- \member{tp_richcompare}, and \member{tp_hash} are all \NULL.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{reprfunc}{tp_repr}
- An optional pointer to a function that implements the built-in
- function \function{repr()}.\bifuncindex{repr}
-
- The signature is the same as for \cfunction{PyObject_Repr()}; it
- must return a string or a Unicode object. Ideally, this function
- should return a string that, when passed to \function{eval()}, given
- a suitable environment, returns an object with the same value. If
- this is not feasible, it should return a string starting with
- \character{\textless} and ending with \character{\textgreater} 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 \samp{<\%s object
- at \%p>} is returned, where \code{\%s} is replaced by the type name,
- and \code{\%p} by the object's memory address.
-
- This field is inherited by subtypes.
-\end{cmemberdesc}
-
-PyNumberMethods *tp_as_number;
-
- XXX
-
-PySequenceMethods *tp_as_sequence;
-
- XXX
-
-PyMappingMethods *tp_as_mapping;
-
- XXX
-
-\begin{cmemberdesc}{PyTypeObject}{hashfunc}{tp_hash}
- An optional pointer to a function that implements the built-in
- function \function{hash()}.\bifuncindex{hash}
-
- The signature is the same as for \cfunction{PyObject_Hash()}; it
- must return a C long. The value \code{-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
- \code{-1}.
-
- When this field is not set, two possibilities exist: if the
- \member{tp_compare} and \member{tp_richcompare} fields are both
- \NULL, a default hash value based on the object's address is
- returned; otherwise, a \exception{TypeError} is raised.
-
- This field is inherited by subtypes together with
- \member{tp_richcompare} and \member{tp_compare}: a subtypes inherits
- all three of \member{tp_compare}, \member{tp_richcompare}, and
- \member{tp_hash}, when the subtype's \member{tp_compare},
- \member{tp_richcompare} and \member{tp_hash} are all \NULL.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{ternaryfunc}{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 \cfunction{PyObject_Call()}.
-
- This field is inherited by subtypes.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{reprfunc}{tp_str}
- An optional pointer to a function that implements the built-in
- operation \function{str()}. (Note that \class{str} is a type now,
- and \function{str()} calls the constructor for that type. This
- constructor calls \cfunction{PyObject_Str()} to do the actual work,
- and \cfunction{PyObject_Str()} will call this handler.)
-
- The signature is the same as for \cfunction{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, \cfunction{PyObject_Repr()} is called to
- return a string representation.
-
- This field is inherited by subtypes.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{getattrofunc}{tp_getattro}
- An optional pointer to the get-attribute function.
-
- The signature is the same as for \cfunction{PyObject_GetAttr()}. It
- is usually convenient to set this field to
- \cfunction{PyObject_GenericGetAttr()}, which implements the normal
- way of looking for object attributes.
-
- This field is inherited by subtypes together with
- \member{tp_getattr}: a subtype inherits both \member{tp_getattr} and
- \member{tp_getattro} from its base type when the subtype's
- \member{tp_getattr} and \member{tp_getattro} are both \NULL.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{setattrofunc}{tp_setattro}
- An optional pointer to the set-attribute function.
-
- The signature is the same as for \cfunction{PyObject_SetAttr()}. It
- is usually convenient to set this field to
- \cfunction{PyObject_GenericSetAttr()}, which implements the normal
- way of setting object attributes.
-
- This field is inherited by subtypes together with
- \member{tp_setattr}: a subtype inherits both \member{tp_setattr} and
- \member{tp_setattro} from its base type when the subtype's
- \member{tp_setattr} and \member{tp_setattro} are both \NULL.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{PyBufferProcs*}{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 ``Buffer Object Structures'' (section
- \ref{buffer-structs}).
-
- The \member{tp_as_buffer} field is not inherited, but the contained
- fields are inherited individually.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{long}{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 \member{tp_as_number},
- \member{tp_as_sequence}, \member{tp_as_mapping}, and
- \member{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 \constant{Py_TPFLAGS_HAVE_GC} flag bit is inherited
- together with the \member{tp_traverse} and \member{tp_clear} fields,
- i.e. if the \constant{Py_TPFLAGS_HAVE_GC} flag bit is clear in the
- subtype and the \member{tp_traverse} and \member{tp_clear} fields in
- the subtype exist (as indicated by the
- \constant{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 \code{|} operator to form the value of the
- \member{tp_flags} field. The macro \cfunction{PyType_HasFeature()}
- takes a type and a flags value, \var{tp} and \var{f}, and checks
- whether \code{\var{tp}->tp_flags \& \var{f}} is non-zero.
-
- \begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER}
- If this bit is set, the \ctype{PyBufferProcs} struct referenced by
- \member{tp_as_buffer} has the \member{bf_getcharbuffer} field.
- \end{datadesc}
-
- \begin{datadesc}{Py_TPFLAGS_HAVE_SEQUENCE_IN}
- If this bit is set, the \ctype{PySequenceMethods} struct
- referenced by \member{tp_as_sequence} has the \member{sq_contains}
- field.
- \end{datadesc}
-
- \begin{datadesc}{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.
- \end{datadesc}
-
- \begin{datadesc}{Py_TPFLAGS_HAVE_INPLACEOPS}
- If this bit is set, the \ctype{PySequenceMethods} struct
- referenced by \member{tp_as_sequence} and the
- \ctype{PyNumberMethods} structure referenced by
- \member{tp_as_number} contain the fields for in-place operators.
- In particular, this means that the \ctype{PyNumberMethods}
- structure has the fields \member{nb_inplace_add},
- \member{nb_inplace_subtract}, \member{nb_inplace_multiply},
- \member{nb_inplace_divide}, \member{nb_inplace_remainder},
- \member{nb_inplace_power}, \member{nb_inplace_lshift},
- \member{nb_inplace_rshift}, \member{nb_inplace_and},
- \member{nb_inplace_xor}, and \member{nb_inplace_or}; and the
- \ctype{PySequenceMethods} struct has the fields
- \member{sq_inplace_concat} and \member{sq_inplace_repeat}.
- \end{datadesc}
-
- \begin{datadesc}{Py_TPFLAGS_CHECKTYPES}
- If this bit is set, the binary and ternary operations in the
- \ctype{PyNumberMethods} structure referenced by
- \member{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 \member{nb_add},
- \member{nb_subtract}, \member{nb_multiply}, \member{nb_divide},
- \member{nb_remainder}, \member{nb_divmod}, \member{nb_power},
- \member{nb_lshift}, \member{nb_rshift}, \member{nb_and},
- \member{nb_xor}, and \member{nb_or}.
- \end{datadesc}
-
- \begin{datadesc}{Py_TPFLAGS_HAVE_RICHCOMPARE}
- If this bit is set, the type object has the
- \member{tp_richcompare} field, as well as the \member{tp_traverse}
- and the \member{tp_clear} fields.
- \end{datadesc}
-
- \begin{datadesc}{Py_TPFLAGS_HAVE_WEAKREFS}
- If this bit is set, the \member{tp_weaklistoffset} field is
- defined. Instances of a type are weakly referenceable if the
- type's \member{tp_weaklistoffset} field has a value greater than
- zero.
- \end{datadesc}
-
- \begin{datadesc}{Py_TPFLAGS_HAVE_ITER}
- If this bit is set, the type object has the \member{tp_iter} and
- \member{tp_iternext} fields.
- \end{datadesc}
-
- \begin{datadesc}{Py_TPFLAGS_HAVE_CLASS}
- If this bit is set, the type object has several new fields defined
- starting in Python 2.2: \member{tp_methods}, \member{tp_members},
- \member{tp_getset}, \member{tp_base}, \member{tp_dict},
- \member{tp_descr_get}, \member{tp_descr_set},
- \member{tp_dictoffset}, \member{tp_init}, \member{tp_alloc},
- \member{tp_new}, \member{tp_free}, \member{tp_is_gc},
- \member{tp_bases}, \member{tp_mro}, \member{tp_cache},
- \member{tp_subclasses}, and \member{tp_weaklist}.
- \end{datadesc}
-
- \begin{datadesc}{Py_TPFLAGS_HEAPTYPE}
- This bit is set when the type object itself is allocated on the
- heap. In this case, the \member{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).
- \end{datadesc}
-
- \begin{datadesc}{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).
- \end{datadesc}
-
- \begin{datadesc}{Py_TPFLAGS_READY}
- This bit is set when the type object has been fully initialized by
- \cfunction{PyType_Ready()}.
- \end{datadesc}
-
- \begin{datadesc}{Py_TPFLAGS_READYING}
- This bit is set while \cfunction{PyType_Ready()} is in the process
- of initializing the type object.
- \end{datadesc}
-
- \begin{datadesc}{Py_TPFLAGS_HAVE_GC}
- This bit is set when the object supports garbage collection. If
- this bit is set, instances must be created using
- \cfunction{PyObject_GC_New()} and destroyed using
- \cfunction{PyObject_GC_Del()}. More information in section XXX
- about garbage collection. This bit also implies that the
- GC-related fields \member{tp_traverse} and \member{tp_clear} are
- present in the type object; but those fields also exist when
- \constant{Py_TPFLAGS_HAVE_GC} is clear but
- \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} is set.
- \end{datadesc}
-
- \begin{datadesc}{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:
- \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER},
- \constant{Py_TPFLAGS_HAVE_SEQUENCE_IN},
- \constant{Py_TPFLAGS_HAVE_INPLACEOPS},
- \constant{Py_TPFLAGS_HAVE_RICHCOMPARE},
- \constant{Py_TPFLAGS_HAVE_WEAKREFS},
- \constant{Py_TPFLAGS_HAVE_ITER}, and
- \constant{Py_TPFLAGS_HAVE_CLASS}.
- \end{datadesc}
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{char*}{tp_doc}
- An optional pointer to a NUL-terminated C string giving the
- docstring for this type object. This is exposed as the
- \member{__doc__} attribute on the type and instances of the type.
-
- This field is \emph{not} inherited by subtypes.
-\end{cmemberdesc}
-
-The following three fields only exist if the
-\constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit is set.
-
-\begin{cmemberdesc}{PyTypeObject}{traverseproc}{tp_traverse}
- An optional pointer to a traversal function for the garbage
- collector. This is only used if the \constant{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 \member{tp_traverse} pointer is used by the garbage collector
- to detect reference cycles. A typical implementation of a
- \member{tp_traverse} function simply calls \cfunction{Py_VISIT()} on
- each of the instance's members that are Python objects. For exampe, this
- is function \cfunction{local_traverse} from the \module{thread} extension
- module:
-
- \begin{verbatim}
- static int
- local_traverse(localobject *self, visitproc visit, void *arg)
- {
- Py_VISIT(self->args);
- Py_VISIT(self->kw);
- Py_VISIT(self->dict);
- return 0;
- }
- \end{verbatim}
-
- Note that \cfunction{Py_VISIT()} is called only on those members that can
- participate in reference cycles. Although there is also a
- \samp{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
- \module{gc} module's \function{get_referents()} function will include it.
-
- Note that \cfunction{Py_VISIT()} requires the \var{visit} and \var{arg}
- parameters to \cfunction{local_traverse} to have these specific names;
- don't name them just anything.
-
- This field is inherited by subtypes together with \member{tp_clear}
- and the \constant{Py_TPFLAGS_HAVE_GC} flag bit: the flag bit,
- \member{tp_traverse}, and \member{tp_clear} are all inherited from
- the base type if they are all zero in the subtype \emph{and} the
- subtype has the \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit set.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{inquiry}{tp_clear}
- An optional pointer to a clear function for the garbage collector.
- This is only used if the \constant{Py_TPFLAGS_HAVE_GC} flag bit is
- set.
-
- The \member{tp_clear} member function is used to break reference
- cycles in cyclic garbage detected by the garbage collector. Taken
- together, all \member{tp_clear} functions in the system must combine to
- break all reference cycles. This is subtle, and if in any doubt supply a
- \member{tp_clear} function. For example, the tuple type does not
- implement a \member{tp_clear} function, because it's possible to prove
- that no reference cycle can be composed entirely of tuples. Therefore
- the \member{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 \member{tp_clear}.
-
- Implementations of \member{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:
-
- \begin{verbatim}
- static int
- local_clear(localobject *self)
- {
- Py_CLEAR(self->key);
- Py_CLEAR(self->args);
- Py_CLEAR(self->kw);
- Py_CLEAR(self->dict);
- return 0;
- }
- \end{verbatim}
-
- The \cfunction{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 \var{self} again, it's
- important that the pointer to the contained object be \NULL{} at that
- time, so that \var{self} knows the contained object can no longer be
- used. The \cfunction{Py_CLEAR()} macro performs the operations in a
- safe order.
-
- Because the goal of \member{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 \member{tp_dealloc} function to
- invoke \member{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 \member{tp_traverse}
- and the \constant{Py_TPFLAGS_HAVE_GC} flag bit: the flag bit,
- \member{tp_traverse}, and \member{tp_clear} are all inherited from
- the base type if they are all zero in the subtype \emph{and} the
- subtype has the \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit set.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{richcmpfunc}{tp_richcompare}
- An optional pointer to the rich comparison function.
-
- The signature is the same as for \cfunction{PyObject_RichCompare()}.
- The function should return the result of the comparison (usually
- \code{Py_True} or \code{Py_False}). If the comparison is undefined,
- it must return \code{Py_NotImplemented}, if another error occurred
- it must return \code{NULL} and set an exception condition.
-
- This field is inherited by subtypes together with
- \member{tp_compare} and \member{tp_hash}: a subtype inherits all
- three of \member{tp_compare}, \member{tp_richcompare}, and
- \member{tp_hash}, when the subtype's \member{tp_compare},
- \member{tp_richcompare}, and \member{tp_hash} are all \NULL.
-
- The following constants are defined to be used as the third argument
- for \member{tp_richcompare} and for \cfunction{PyObject_RichCompare()}:
-
- \begin{tableii}{l|c}{constant}{Constant}{Comparison}
- \lineii{Py_LT}{\code{<}}
- \lineii{Py_LE}{\code{<=}}
- \lineii{Py_EQ}{\code{==}}
- \lineii{Py_NE}{\code{!=}}
- \lineii{Py_GT}{\code{>}}
- \lineii{Py_GE}{\code{>=}}
- \end{tableii}
-\end{cmemberdesc}
-
-The next field only exists if the \constant{Py_TPFLAGS_HAVE_WEAKREFS}
-flag bit is set.
-
-\begin{cmemberdesc}{PyTypeObject}{long}{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
- \cfunction{PyObject_ClearWeakRefs()} and the
- \cfunction{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 \member{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 \member{tp_weaklistoffset}, this
- should not be a problem.
-
- When a type defined by a class statement has no \member{__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
- \member{tp_weaklistoffset} of that slot's offset.
-
- When a type's \member{__slots__} declaration contains a slot named
- \member{__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 \member{tp_weaklistoffset}.
-
- When a type's \member{__slots__} declaration does not contain a slot
- named \member{__weakref__}, the type inherits its
- \member{tp_weaklistoffset} from its base type.
-\end{cmemberdesc}
-
-The next two fields only exist if the
-\constant{Py_TPFLAGS_HAVE_CLASS} flag bit is set.
-
-\begin{cmemberdesc}{PyTypeObject}{getiterfunc}{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 \method{__iter__()} method).
-
- This function has the same signature as
- \cfunction{PyObject_GetIter()}.
-
- This field is inherited by subtypes.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{iternextfunc}{tp_iternext}
- An optional pointer to a function that returns the next item in an
- iterator, or raises \exception{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 \method{__next__()} method).
-
- Iterator types should also define the \member{tp_iter} function, and
- that function should return the iterator instance itself (not a new
- iterator instance).
-
- This function has the same signature as \cfunction{PyIter_Next()}.
-
- This field is inherited by subtypes.
-\end{cmemberdesc}
-
-The next fields, up to and including \member{tp_weaklist}, only exist
-if the \constant{Py_TPFLAGS_HAVE_CLASS} flag bit is set.
-
-\begin{cmemberdesc}{PyTypeObject}{struct PyMethodDef*}{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 \member{tp_dict} below) containing a method
- descriptor.
-
- This field is not inherited by subtypes (methods are
- inherited through a different mechanism).
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{struct PyMemberDef*}{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 \member{tp_dict} below) containing a member
- descriptor.
-
- This field is not inherited by subtypes (members are inherited
- through a different mechanism).
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{struct PyGetSetDef*}{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 \member{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):
-
-\begin{verbatim}
-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;
-\end{verbatim}
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{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 \code{\&PyBaseObject_Type} (which to Python programmers is known
- as the type \class{object}).
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_dict}
- The type's dictionary is stored here by \cfunction{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
- \cfunction{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 \method{__add__()}).
-
- This field is not inherited by subtypes (though the attributes
- defined in here are inherited through a different mechanism).
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{descrgetfunc}{tp_descr_get}
- An optional pointer to a "descriptor get" function.
-
-
- The function signature is
-
-\begin{verbatim}
-PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
-\end{verbatim}
-
- XXX blah, blah.
-
- This field is inherited by subtypes.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{descrsetfunc}{tp_descr_set}
- An optional pointer to a "descriptor set" function.
-
- The function signature is
-
-\begin{verbatim}
-int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
-\end{verbatim}
-
- This field is inherited by subtypes.
-
- XXX blah, blah.
-
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{long}{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 \cfunction{PyObject_GenericGetAttr()}.
-
- Do not confuse this field with \member{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 \emph{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 \member{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, \member{tp_dictoffset} should be set to
- \code{-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 \member{tp_dictoffset} as follows:
-
-\begin{verbatim}
-dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
-if dictoffset is not aligned on sizeof(void*):
- round up to sizeof(void*)
-\end{verbatim}
-
- where \member{tp_basicsize}, \member{tp_itemsize} and
- \member{tp_dictoffset} are taken from the type object, and
- \member{ob_size} is taken from the instance. The absolute value is
- taken because long ints use the sign of \member{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
- \cfunction{_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
- \member{tp_dictoffset}, this should not be a problem.
-
- When a type defined by a class statement has no \member{__slots__}
- declaration, and none of its base types has an instance variable
- dictionary, a dictionary slot is added to the instance layout and
- the \member{tp_dictoffset} is set to that slot's offset.
-
- When a type defined by a class statement has a \member{__slots__}
- declaration, the type inherits its \member{tp_dictoffset} from its
- base type.
-
- (Adding a slot named \member{__dict__} to the \member{__slots__}
- declaration does not have the expected effect, it just causes
- confusion. Maybe this should be added as a feature just like
- \member{__weakref__} though.)
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{initproc}{tp_init}
- An optional pointer to an instance initialization function.
-
- This function corresponds to the \method{__init__()} method of
- classes. Like \method{__init__()}, it is possible to create an
- instance without calling \method{__init__()}, and it is possible to
- reinitialize an instance by calling its \method{__init__()} method
- again.
-
- The function signature is
-
-\begin{verbatim}
-int tp_init(PyObject *self, PyObject *args, PyObject *kwds)
-\end{verbatim}
-
- The self argument is the instance to be initialized; the \var{args}
- and \var{kwds} arguments represent positional and keyword arguments
- of the call to \method{__init__()}.
-
- The \member{tp_init} function, if not \NULL, is called when an
- instance is created normally by calling its type, after the type's
- \member{tp_new} function has returned an instance of the type. If
- the \member{tp_new} function returns an instance of some other type
- that is not a subtype of the original type, no \member{tp_init}
- function is called; if \member{tp_new} returns an instance of a
- subtype of the original type, the subtype's \member{tp_init} is
- called. (VERSION NOTE: described here is what is implemented in
- Python 2.2.1 and later. In Python 2.2, the \member{tp_init} of the
- type of the object returned by \member{tp_new} was always called, if
- not \NULL.)
-
- This field is inherited by subtypes.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{allocfunc}{tp_alloc}
- An optional pointer to an instance allocation function.
-
- The function signature is
-
-\begin{verbatim}
-PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems)
-\end{verbatim}
-
- 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 \member{ob_refcnt} set to \code{1}
- and \member{ob_type} set to the type argument. If the type's
- \member{tp_itemsize} is non-zero, the object's \member{ob_size} field
- should be initialized to \var{nitems} and the length of the
- allocated memory block should be \code{tp_basicsize +
- \var{nitems}*tp_itemsize}, rounded up to a multiple of
- \code{sizeof(void*)}; otherwise, \var{nitems} is not used and the
- length of the block should be \member{tp_basicsize}.
-
- Do not use this function to do any other instance initialization,
- not even to allocate additional memory; that should be done by
- \member{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 \cfunction{PyType_GenericAlloc}, to
- force a standard heap allocation strategy. That is also the
- recommended value for statically defined types.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{newfunc}{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
-
-\begin{verbatim}
-PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)
-\end{verbatim}
-
- The subtype argument is the type of the object being created; the
- \var{args} and \var{kwds} arguments represent positional and keyword
- arguments of the call to the type. Note that subtype doesn't have
- to equal the type whose \member{tp_new} function is called; it may
- be a subtype of that type (but not an unrelated type).
-
- The \member{tp_new} function should call
- \code{\var{subtype}->tp_alloc(\var{subtype}, \var{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
- \member{tp_init} handler. A good rule of thumb is that for
- immutable types, all initialization should take place in
- \member{tp_new}, while for mutable types, most initialization should
- be deferred to \member{tp_init}.
-
- This field is inherited by subtypes, except it is not inherited by
- static types whose \member{tp_base} is \NULL{} or
- \code{\&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.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{destructor}{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}:
-
-\begin{verbatim}
-void tp_free(PyObject *)
-\end{verbatim}
-
- In Python 2.3 and beyond, its signature is \ctype{freefunc}:
-
-\begin{verbatim}
-void tp_free(void *)
-\end{verbatim}
-
- The only initializer that is compatible with both versions is
- \code{_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
- \cfunction{PyType_GenericAlloc()} and the value of the
- \constant{Py_TPFLAGS_HAVE_GC} flag bit.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{inquiry}{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 \member{tp_flags} field, and check the
- \constant{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 \code{1} for a
- collectible instance, and \code{0} for a non-collectible instance.
- The signature is
-
-\begin{verbatim}
-int tp_is_gc(PyObject *self)
-\end{verbatim}
-
- (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.)
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{PyObject*}{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.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{PyObject*}{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
- \cfunction{PyType_Ready()}.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_cache}
- Unused. Not inherited. Internal use only.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_subclasses}
- List of weak references to subclasses. Not inherited. Internal
- use only.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_weaklist}
- Weak reference list head, for weak references to this type
- object. Not inherited. Internal use only.
-\end{cmemberdesc}
-
-The remaining fields are only defined if the feature test macro
-\constant{COUNT_ALLOCS} is defined, and are for internal use only.
-They are documented here for completeness. None of these fields are
-inherited by subtypes.
-
-\begin{cmemberdesc}{PyTypeObject}{Py_ssize_t}{tp_allocs}
- Number of allocations.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{Py_ssize_t}{tp_frees}
- Number of frees.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{Py_ssize_t}{tp_maxalloc}
- Maximum simultaneously allocated objects.
-\end{cmemberdesc}
-
-\begin{cmemberdesc}{PyTypeObject}{PyTypeObject*}{tp_next}
- Pointer to the next type object with a non-zero \member{tp_allocs}
- field.
-\end{cmemberdesc}
-
-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 \Cpp{} 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.
-
-\section{Mapping Object Structures \label{mapping-structs}}
-
-\begin{ctypedesc}{PyMappingMethods}
- Structure used to hold pointers to the functions used to implement
- the mapping protocol for an extension type.
-\end{ctypedesc}
-
-
-\section{Number Object Structures \label{number-structs}}
-
-\begin{ctypedesc}{PyNumberMethods}
- Structure used to hold pointers to the functions an extension type
- uses to implement the number protocol.
-\end{ctypedesc}
-
-
-\section{Sequence Object Structures \label{sequence-structs}}
-
-\begin{ctypedesc}{PySequenceMethods}
- Structure used to hold pointers to the functions which an object
- uses to implement the sequence protocol.
-\end{ctypedesc}
-
-
-\section{Buffer Object Structures \label{buffer-structs}}
-\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
-\member{tp_as_buffer} member in the \ctype{PyTypeObject} structure
-should be \NULL. Otherwise, the \member{tp_as_buffer} will point to
-a \ctype{PyBufferProcs} structure.
-
-\note{It is very important that your \ctype{PyTypeObject} structure
-uses \constant{Py_TPFLAGS_DEFAULT} for the value of the
-\member{tp_flags} member rather than \code{0}. This tells the Python
-runtime that your \ctype{PyBufferProcs} structure contains the
-\member{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.}
-
-\begin{ctypedesc}{PyBufferProcs}
- Structure used to hold the function pointers which define an
- implementation of the buffer protocol.
-
- The first slot is \member{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 \member{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 \member{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.
-
- The last slot is \member{bf_getcharbuffer}, of type
- \ctype{getcharbufferproc}. This slot will only be present if the
- \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the
- \member{tp_flags} field of the object's \ctype{PyTypeObject}.
- Before using this slot, the caller should test whether it is present
- by using the
- \cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()}
- function. If the flag is present, \member{bf_getcharbuffer} may be
- \NULL,
- indicating that the object's
- contents cannot be used as \emph{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
- \member{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
- \var{N} does not mean there are \var{N} characters present.}
-\end{ctypedesc}
-
-\begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER}
- Flag bit set in the type structure to indicate that the
- \member{bf_getcharbuffer} slot is known. This being set does not
- indicate that the object supports the buffer interface or that the
- \member{bf_getcharbuffer} slot is non-\NULL.
-\end{datadesc}
-
-\begin{ctypedesc}[getreadbufferproc]{Py_ssize_t (*readbufferproc)
- (PyObject *self, Py_ssize_t segment, void **ptrptr)}
- Return a pointer to a readable segment of the buffer in
- \code{*\var{ptrptr}}. This function
- is allowed to raise an exception, in which case it must return
- \code{-1}. The \var{segment} which is specified must be zero or
- positive, and strictly less than the number of segments returned by
- the \member{bf_getsegcount} slot function. On success, it returns
- the length of the segment, and sets \code{*\var{ptrptr}} to a
- pointer to that memory.
-\end{ctypedesc}
-
-\begin{ctypedesc}[getwritebufferproc]{Py_ssize_t (*writebufferproc)
- (PyObject *self, Py_ssize_t segment, void **ptrptr)}
- Return a pointer to a writable memory buffer in
- \code{*\var{ptrptr}}, and the length of that segment as the function
- return value. The memory buffer must correspond to buffer segment
- \var{segment}. Must return \code{-1} and set an exception on
- error. \exception{TypeError} should be raised if the object only
- supports read-only buffers, and \exception{SystemError} should be
- raised when \var{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.
-\end{ctypedesc}
-
-\begin{ctypedesc}[getsegcountproc]{Py_ssize_t (*segcountproc)
- (PyObject *self, Py_ssize_t *lenp)}
- Return the number of memory segments which comprise the buffer. If
- \var{lenp} is not \NULL, the implementation must report the sum of
- the sizes (in bytes) of all segments in \code{*\var{lenp}}.
- The function cannot fail.
-\end{ctypedesc}
-
-\begin{ctypedesc}[getcharbufferproc]{Py_ssize_t (*charbufferproc)
- (PyObject *self, Py_ssize_t segment, const char **ptrptr)}
- Return the size of the segment \var{segment} that \var{ptrptr}
- is set to. \code{*\var{ptrptr}} is set to the memory buffer.
- Returns \code{-1} on error.
-\end{ctypedesc}
-
-
-\section{Supporting the Iterator Protocol
- \label{supporting-iteration}}
-
-
-\section{Supporting Cyclic Garbage Collection
- \label{supporting-cycle-detection}}
-
-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
-``\ulink{Supporting the Cycle
-Collector}{../ext/example-cycle-support.html}'' in
-\citetitle[../ext/ext.html]{Extending and Embedding the Python
-Interpreter}.
-
-To create a container type, the \member{tp_flags} field of the type
-object must include the \constant{Py_TPFLAGS_HAVE_GC} and provide an
-implementation of the \member{tp_traverse} handler. If instances of the
-type are mutable, a \member{tp_clear} implementation must also be
-provided.
-
-\begin{datadesc}{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.
-\end{datadesc}
-
-Constructors for container types must conform to two rules:
-
-\begin{enumerate}
-\item The memory for the object must be allocated using
- \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_VarNew()}.
-
-\item Once all the fields which may contain references to other
- containers are initialized, it must call
- \cfunction{PyObject_GC_Track()}.
-\end{enumerate}
-
-\begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_New}{TYPE, PyTypeObject *type}
- Analogous to \cfunction{PyObject_New()} but for container objects with
- the \constant{Py_TPFLAGS_HAVE_GC} flag set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_NewVar}{TYPE, PyTypeObject *type,
- Py_ssize_t size}
- Analogous to \cfunction{PyObject_NewVar()} but for container objects
- with the \constant{Py_TPFLAGS_HAVE_GC} flag set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyVarObject *}{PyObject_GC_Resize}{PyVarObject *op, Py_ssize_t}
- Resize an object allocated by \cfunction{PyObject_NewVar()}. Returns
- the resized object or \NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyObject_GC_Track}{PyObject *op}
- Adds the object \var{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 \member{tp_traverse} handler become valid,
- usually near the end of the constructor.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{_PyObject_GC_TRACK}{PyObject *op}
- A macro version of \cfunction{PyObject_GC_Track()}. It should not be
- used for extension modules.
-\end{cfuncdesc}
-
-Similarly, the deallocator for the object must conform to a similar
-pair of rules:
-
-\begin{enumerate}
-\item Before fields which refer to other containers are invalidated,
- \cfunction{PyObject_GC_UnTrack()} must be called.
-
-\item The object's memory must be deallocated using
- \cfunction{PyObject_GC_Del()}.
-\end{enumerate}
-
-\begin{cfuncdesc}{void}{PyObject_GC_Del}{void *op}
- Releases memory allocated to an object using
- \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_NewVar()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyObject_GC_UnTrack}{void *op}
- Remove the object \var{op} from the set of container objects tracked
- by the collector. Note that \cfunction{PyObject_GC_Track()} can be
- called again on this object to add it back to the set of tracked
- objects. The deallocator (\member{tp_dealloc} handler) should call
- this for the object before any of the fields used by the
- \member{tp_traverse} handler become invalid.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{_PyObject_GC_UNTRACK}{PyObject *op}
- A macro version of \cfunction{PyObject_GC_UnTrack()}. It should not be
- used for extension modules.
-\end{cfuncdesc}
-
-The \member{tp_traverse} handler accepts a function parameter of this
-type:
-
-\begin{ctypedesc}[visitproc]{int (*visitproc)(PyObject *object, void *arg)}
- Type of the visitor function passed to the \member{tp_traverse}
- handler. The function should be called with an object to traverse
- as \var{object} and the third parameter to the \member{tp_traverse}
- handler as \var{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.
-\end{ctypedesc}
-
-The \member{tp_traverse} handler must have the following type:
-
-\begin{ctypedesc}[traverseproc]{int (*traverseproc)(PyObject *self,
- visitproc visit, void *arg)}
- Traversal function for a container object. Implementations must
- call the \var{visit} function for each object directly contained by
- \var{self}, with the parameters to \var{visit} being the contained
- object and the \var{arg} value passed to the handler. The \var{visit}
- function must not be called with a \NULL{} object argument. If
- \var{visit} returns a non-zero value
- that value should be returned immediately.
-\end{ctypedesc}
-
-To simplify writing \member{tp_traverse} handlers, a
-\cfunction{Py_VISIT()} macro is provided. In order to use this macro,
-the \member{tp_traverse} implementation must name its arguments
-exactly \var{visit} and \var{arg}:
-
-\begin{cfuncdesc}{void}{Py_VISIT}{PyObject *o}
- Call the \var{visit} callback, with arguments \var{o} and \var{arg}.
- If \var{visit} returns a non-zero value, then return it. Using this
- macro, \member{tp_traverse} handlers look like:
-
-\begin{verbatim}
-static int
-my_traverse(Noddy *self, visitproc visit, void *arg)
-{
- Py_VISIT(self->foo);
- Py_VISIT(self->bar);
- return 0;
-}
-\end{verbatim}
-
-\versionadded{2.4}
-\end{cfuncdesc}
-
-
-The \member{tp_clear} handler must be of the \ctype{inquiry} type, or
-\NULL{} if the object is immutable.
-
-\begin{ctypedesc}[inquiry]{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
- \cfunction{Py_DECREF()} on a reference). The collector will call
- this method if it detects that this object is involved in a
- reference cycle.
-\end{ctypedesc}
diff --git a/Doc/api/refcounting.tex b/Doc/api/refcounting.tex
deleted file mode 100644
index 077543b..0000000
--- a/Doc/api/refcounting.tex
+++ /dev/null
@@ -1,69 +0,0 @@
-\chapter{Reference Counting \label{countingRefs}}
-
-
-The macros in this section are used for managing reference counts
-of Python objects.
-
-
-\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
- Increment the reference count for object \var{o}. The object must
- not be \NULL; if you aren't sure that it isn't \NULL, use
- \cfunction{Py_XINCREF()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
- Increment the reference count for object \var{o}. The object may be
- \NULL, in which case the macro has no effect.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
- Decrement the reference count for object \var{o}. The object must
- not be \NULL; if you aren't sure that it isn't \NULL, use
- \cfunction{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 \method{__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
- \cfunction{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
- \cfunction{Py_DECREF()} for the temporary variable.}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
- Decrement the reference count for object \var{o}. The object may be
- \NULL, in which case the macro has no effect; otherwise the effect
- is the same as for \cfunction{Py_DECREF()}, and the same warning
- applies.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_CLEAR}{PyObject *o}
- Decrement the reference count for object \var{o}. The object may be
- \NULL, in which case the macro has no effect; otherwise the effect
- is the same as for \cfunction{Py_DECREF()}, except that the argument
- is also set to \NULL. The warning for \cfunction{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}
-\end{cfuncdesc}
-
-
-The following functions are for runtime dynamic embedding of Python:
-\cfunction{Py_IncRef(PyObject *o)}, \cfunction{Py_DecRef(PyObject *o)}.
-They are simply exported function versions of \cfunction{Py_XINCREF()} and
-\cfunction{Py_XDECREF()}, respectively.
-
-The following functions or macros are only for use within the
-interpreter core: \cfunction{_Py_Dealloc()},
-\cfunction{_Py_ForgetReference()}, \cfunction{_Py_NewReference()}, as
-well as the global variable \cdata{_Py_RefTotal}.
diff --git a/Doc/api/refcounts.dat b/Doc/api/refcounts.dat
deleted file mode 100644
index 54197c8..0000000
--- a/Doc/api/refcounts.dat
+++ /dev/null
@@ -1,1751 +0,0 @@
-# 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:
-
-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_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::
diff --git a/Doc/api/utilities.tex b/Doc/api/utilities.tex
deleted file mode 100644
index 037c087..0000000
--- a/Doc/api/utilities.tex
+++ /dev/null
@@ -1,1041 +0,0 @@
-\chapter{Utilities \label{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.
-
-
-\section{Operating System Utilities \label{os}}
-
-\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, const char *filename}
- Return true (nonzero) if the standard I/O file \var{fp} with name
- \var{filename} is deemed interactive. This is the case for files
- for which \samp{isatty(fileno(\var{fp}))} is true. If the global
- flag \cdata{Py_InteractiveFlag} is true, this function also returns
- true if the \var{filename} pointer is \NULL{} or if the name is
- equal to one of the strings \code{'<stdin>'} or \code{'???'}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
- Return the time of last modification of the file \var{filename}.
- The result is encoded in the same way as the timestamp returned by
- the standard C library function \cfunction{time()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyOS_CheckStack}{}
- Return true when the interpreter runs out of stack space. This is a
- reliable check, but is only available when \constant{USE_STACKCHECK}
- is defined (currently on Windows using the Microsoft Visual \Cpp{}
- compiler). \constant{USE_STACKCHECK} will be
- defined automatically; you should never change the definition in
- your own code.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_getsig}{int i}
- Return the current signal handler for signal \var{i}. This is a
- thin wrapper around either \cfunction{sigaction()} or
- \cfunction{signal()}. Do not call those functions directly!
- \ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void
- (*)(int)}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_setsig}{int i, PyOS_sighandler_t h}
- Set the signal handler for signal \var{i} to be \var{h}; return the
- old signal handler. This is a thin wrapper around either
- \cfunction{sigaction()} or \cfunction{signal()}. Do not call those
- functions directly! \ctype{PyOS_sighandler_t} is a typedef alias
- for \ctype{void (*)(int)}.
-\end{cfuncdesc}
-
-
-\section{Process Control \label{processControl}}
-
-\begin{cfuncdesc}{void}{Py_FatalError}{const char *message}
- 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
- \cfunction{abort()}\ttindex{abort()} is called which will attempt to
- produce a \file{core} file.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_Exit}{int status}
- Exit the current process. This calls
- \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and then calls the
- standard C library function
- \code{exit(\var{status})}\ttindex{exit()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
- Register a cleanup function to be called by
- \cfunction{Py_Finalize()}\ttindex{Py_Finalize()}. The cleanup
- function will be called with no arguments and should return no
- value. At most 32 \index{cleanup functions}cleanup functions can be
- registered. When the registration is successful,
- \cfunction{Py_AtExit()} returns \code{0}; on failure, it returns
- \code{-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 \var{func}.
-\end{cfuncdesc}
-
-
-\section{Importing Modules \label{importing}}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{const char *name}
- This is a simplified interface to
- \cfunction{PyImport_ImportModuleEx()} below, leaving the
- \var{globals} and \var{locals} arguments set to \NULL. When the
- \var{name} argument contains a dot (when it specifies a submodule of
- a package), the \var{fromlist} argument is set to the list
- \code{['*']} 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
- \var{name} in fact specifies a subpackage instead of a submodule:
- the submodules specified in the package's \code{__all__} variable
- are \index{package variable!\code{__all__}}
- \withsubitem{(package variable)}{\ttindex{__all__}}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 \code{sys.modules} to find out. Starting
- with Python 2.4, a failing import of a module no longer leaves the
- module in \code{sys.modules}.
- \versionchanged[failing imports remove incomplete module objects]{2.4}
- \withsubitem{(in module sys)}{\ttindex{modules}}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name,
- PyObject *globals, PyObject *locals, PyObject *fromlist}
- Import a module. This is best described by referring to the
- built-in Python function
- \function{__import__()}\bifuncindex{__import__}, as the standard
- \function{__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
- \function{__import__()}, the return value when a submodule of a
- package was requested is normally the top-level package, unless a
- non-empty \var{fromlist} was given.
- \versionchanged[failing imports remove incomplete module objects]{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_Import}{PyObject *name}
- This is a higher-level interface that calls the current ``import
- hook function''. It invokes the \function{__import__()} function
- from the \code{__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 \module{rexec}\refstmodindex{rexec}
- or \module{ihooks}\refstmodindex{ihooks}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_ReloadModule}{PyObject *m}
- Reload a module. Return a new reference to the reloaded module, or \NULL{}
- with an exception set on failure (the module still exists in this
- case).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_AddModule}{const char *name}
- Return the module object corresponding to a module name. The
- \var{name} argument may be of the form \code{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 \cfunction{PyImport_ImportModule()} or one of its variants to
- import a module. Package structures implied by a dotted name for
- \var{name} are not created if not already present.}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_ExecCodeModule}{char *name, PyObject *co}
- Given a module name (possibly of the form \code{package.module}) and
- a code object read from a Python bytecode file or obtained from the
- built-in function \function{compile()}\bifuncindex{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,
- \var{name} is removed from \code{sys.modules} in error cases, and even
- if \var{name} was already in \code{sys.modules} on entry to
- \cfunction{PyImport_ExecCodeModule()}. Leaving incompletely initialized
- modules in \code{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
- \cfunction{PyImport_ReloadModule()} for the intended way to reload a
- module.
-
- If \var{name} points to a dotted name of the
- form \code{package.module}, any package structures not already
- created will still not be created.
-
- \versionchanged[\var{name} is removed from \code{sys.modules} in error cases]{2.4}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_GetModuleDict}{}
- Return the dictionary used for the module administration
- (a.k.a.\ \code{sys.modules}). Note that this is a per-interpreter
- variable.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{_PyImport_Init}{}
- Initialize the import mechanism. For internal use only.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyImport_Cleanup}{}
- Empty the module table. For internal use only.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{_PyImport_Fini}{}
- Finalize the import mechanism. For internal use only.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *}
- For internal use only.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *}
- For internal use only.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name}
- Load a frozen module named \var{name}. Return \code{1} for success,
- \code{0} if the module is not found, and \code{-1} with an exception
- set if the initialization failed. To access the imported module on
- a successful load, use \cfunction{PyImport_ImportModule()}. (Note
- the misnomer --- this function would reload the module if it was
- already imported.)
-\end{cfuncdesc}
-
-\begin{ctypedesc}[_frozen]{struct _frozen}
- This is the structure type definition for frozen module descriptors,
- as generated by the \program{freeze}\index{freeze utility} utility
- (see \file{Tools/freeze/} in the Python source distribution). Its
- definition, found in \file{Include/import.h}, is:
-
-\begin{verbatim}
-struct _frozen {
- char *name;
- unsigned char *code;
- int size;
-};
-\end{verbatim}
-\end{ctypedesc}
-
-\begin{cvardesc}{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.
-\end{cvardesc}
-
-\begin{cfuncdesc}{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
- \cfunction{PyImport_ExtendInittab()}, returning \code{-1} if the
- table could not be extended. The new module can be imported by the
- name \var{name}, and uses the function \var{initfunc} as the
- initialization function called on the first attempted import. This
- should be called before \cfunction{Py_Initialize()}.
-\end{cfuncdesc}
-
-\begin{ctypedesc}[_inittab]{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 \cfunction{PyImport_ExtendInittab()} to provide additional
- built-in modules. The structure is defined in
- \file{Include/import.h} as:
-
-\begin{verbatim}
-struct _inittab {
- char *name;
- void (*initfunc)(void);
-};
-\end{verbatim}
-\end{ctypedesc}
-
-\begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab}
- Add a collection of modules to the table of built-in modules. The
- \var{newtab} array must end with a sentinel entry which contains
- \NULL{} for the \member{name} field; failure to provide the sentinel
- value can result in a memory fault. Returns \code{0} on success or
- \code{-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
- \cfunction{Py_Initialize()}.
-\end{cfuncdesc}
-
-
-\section{Data marshalling support \label{marshalling-utils}}
-
-These routines allow C code to work with serialized objects using the
-same data format as the \module{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. \var{Py_MARSHAL_VERSION}
-indicates the current file format (currently 1).
-
-\begin{cfuncdesc}{void}{PyMarshal_WriteLongToFile}{long value, FILE *file, int version}
- Marshal a \ctype{long} integer, \var{value}, to \var{file}. This
- will only write the least-significant 32 bits of \var{value};
- regardless of the size of the native \ctype{long} type.
-
- \versionchanged[\var{version} indicates the file format]{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyMarshal_WriteObjectToFile}{PyObject *value,
- FILE *file, int version}
- Marshal a Python object, \var{value}, to \var{file}.
-
- \versionchanged[\var{version} indicates the file format]{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMarshal_WriteObjectToString}{PyObject *value, int version}
- Return a string object containing the marshalled representation of
- \var{value}.
-
- \versionchanged[\var{version} indicates the file format]{2.4}
-\end{cfuncdesc}
-
-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?
-
-\begin{cfuncdesc}{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}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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
- (\exception{EOFError} or \exception{TypeError}) and returns \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMarshal_ReadLastObjectFromFile}{FILE *file}
- Return a Python object from the data stream in a \ctype{FILE*}
- opened for reading. Unlike
- \cfunction{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 (\exception{EOFError} or
- \exception{TypeError}) and returns \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMarshal_ReadObjectFromString}{char *string,
- Py_ssize_t len}
- Return a Python object from the data stream in a character buffer
- containing \var{len} bytes pointed to by \var{string}. On error,
- sets the appropriate exception (\exception{EOFError} or
- \exception{TypeError}) and returns \NULL.
-\end{cfuncdesc}
-
-
-\section{Parsing arguments and building values
- \label{arg-parsing}}
-
-These functions are useful when creating your own extensions functions
-and methods. Additional information and examples are available in
-\citetitle[../ext/ext.html]{Extending and Embedding the Python
-Interpreter}.
-
-The first three of these functions described,
-\cfunction{PyArg_ParseTuple()},
-\cfunction{PyArg_ParseTupleAndKeywords()}, and
-\cfunction{PyArg_Parse()}, all use \emph{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.
-
-\begin{description}
- \item[\samp{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 \exception{TypeError} exception is raised.
- Unicode objects are converted to C strings using the default
- encoding. If this conversion fails, a \exception{UnicodeError} is
- raised.
-
- \item[\samp{s\#} (string, Unicode or any read buffer compatible object)
- {[const char *, int]}]
- This variant on \samp{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.
-
- \item[\samp{y} (bytes object)
- {[const char *]}]
- This variant on \samp{s} convert a Python bytes object to a C pointer to a
- character string. The bytes object must not contain embedded NUL bytes;
- if it does, a \exception{TypeError} exception is raised.
-
- \item[\samp{y\#} (bytes object)
- {[const char *, int]}]
- This variant on \samp{s\#} stores into two C variables, the first one
- a pointer to a character string, the second one its length. This only
- accepts bytes objects.
-
- \item[\samp{z} (string or \code{None}) {[const char *]}]
- Like \samp{s}, but the Python object may also be \code{None}, in
- which case the C pointer is set to \NULL.
-
- \item[\samp{z\#} (string or \code{None} or any read buffer
- compatible object) {[const char *, int]}]
- This is to \samp{s\#} as \samp{z} is to \samp{s}.
-
- \item[\samp{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 \samp{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.
-
- \item[\samp{u\#} (Unicode object) {[Py_UNICODE *, int]}]
- This variant on \samp{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.
-
- \item[\samp{es} (string, Unicode object or character buffer
- compatible object) {[const char *encoding, char **buffer]}]
- This variant on \samp{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.
-
- \cfunction{PyArg_ParseTuple()} will allocate a buffer of the needed
- size, copy the encoded data into this buffer and adjust
- \var{*buffer} to reference the newly allocated storage. The caller
- is responsible for calling \cfunction{PyMem_Free()} to free the
- allocated buffer after use.
-
- \item[\samp{et} (string, Unicode object or character buffer
- compatible object) {[const char *encoding, char **buffer]}]
- Same as \samp{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.
-
- \item[\samp{es\#} (string, Unicode object or character buffer compatible
- object) {[const char *encoding, char **buffer, int *buffer_length]}]
- This variant on \samp{s\#} is used for encoding Unicode and objects
- convertible to Unicode into a character buffer. Unlike the
- \samp{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 \var{*buffer} points a \NULL{} pointer, the function will
- allocate a buffer of the needed size, copy the encoded data into
- this buffer and set \var{*buffer} to reference the newly allocated
- storage. The caller is responsible for calling
- \cfunction{PyMem_Free()} to free the allocated buffer after usage.
-
- If \var{*buffer} points to a non-\NULL{} pointer (an already
- allocated buffer), \cfunction{PyArg_ParseTuple()} will use this
- location as the buffer and interpret the initial value of
- \var{*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 \exception{ValueError} will be set.
-
- In both cases, \var{*buffer_length} is set to the length of the
- encoded data without the trailing NUL byte.
-
- \item[\samp{et\#} (string, Unicode object or character buffer compatible
- object) {[const char *encoding, char **buffer]}]
- Same as \samp{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.
-
- \item[\samp{b} (integer) {[char]}]
- Convert a Python integer to a tiny int, stored in a C \ctype{char}.
-
- \item[\samp{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}
-
- \item[\samp{h} (integer) {[short int]}]
- Convert a Python integer to a C \ctype{short int}.
-
- \item[\samp{H} (integer) {[unsigned short int]}]
- Convert a Python integer to a C \ctype{unsigned short int}, without
- overflow checking. \versionadded{2.3}
-
- \item[\samp{i} (integer) {[int]}]
- Convert a Python integer to a plain C \ctype{int}.
-
- \item[\samp{I} (integer) {[unsigned int]}]
- Convert a Python integer to a C \ctype{unsigned int}, without
- overflow checking. \versionadded{2.3}
-
- \item[\samp{l} (integer) {[long int]}]
- Convert a Python integer to a C \ctype{long int}.
-
- \item[\samp{k} (integer) {[unsigned long]}]
- Convert a Python integer or long integer to a C \ctype{unsigned long} without
- overflow checking. \versionadded{2.3}
-
- \item[\samp{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).
-
- \item[\samp{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}
-
- \item[\samp{n} (integer) {[Py_ssize_t]}]
- Convert a Python integer or long integer to a C \ctype{Py_ssize_t}.
- \versionadded{2.5}
-
- \item[\samp{c} (string of length 1) {[char]}]
- Convert a Python character, represented as a string of length 1, to
- a C \ctype{char}.
-
- \item[\samp{f} (float) {[float]}]
- Convert a Python floating point number to a C \ctype{float}.
-
- \item[\samp{d} (float) {[double]}]
- Convert a Python floating point number to a C \ctype{double}.
-
- \item[\samp{D} (complex) {[Py_complex]}]
- Convert a Python complex number to a C \ctype{Py_complex} structure.
-
- \item[\samp{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.
-
- \item[\samp{O!} (object) {[\var{typeobject}, PyObject *]}]
- Store a Python object in a C object pointer. This is similar to
- \samp{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,
- \exception{TypeError} is raised.
-
- \item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
- Convert a Python object to a C variable through a \var{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 \var{converter} function in turn is called
- as follows:
-
- \var{status}\code{ = }\var{converter}\code{(}\var{object},
- \var{address}\code{);}
-
- where \var{object} is the Python object to be converted and
- \var{address} is the \ctype{void*} argument that was passed to the
- \cfunction{PyArg_Parse*()} function. The returned \var{status}
- should be \code{1} for a successful conversion and \code{0} if the
- conversion has failed. When the conversion fails, the
- \var{converter} function should raise an exception.
-
- \item[\samp{S} (string) {[PyStringObject *]}]
- Like \samp{O} but requires that the Python object is a string
- object. Raises \exception{TypeError} if the object is not a string
- object. The C variable may also be declared as \ctype{PyObject*}.
-
- \item[\samp{U} (Unicode string) {[PyUnicodeObject *]}]
- Like \samp{O} but requires that the Python object is a Unicode
- object. Raises \exception{TypeError} if the object is not a Unicode
- object. The C variable may also be declared as \ctype{PyObject*}.
-
- \item[\samp{t\#} (read-only character buffer) {[char *, int]}]
- Like \samp{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; \exception{TypeError} is raised for all others.
-
- \item[\samp{w} (read-write character buffer) {[char *]}]
- Similar to \samp{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 \samp{w\#} instead. Only
- single-segment buffer objects are accepted; \exception{TypeError} is
- raised for all others.
-
- \item[\samp{w\#} (read-write character buffer) {[char *, int]}]
- Like \samp{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; \exception{TypeError} is raised for all others.
-
- \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
- The object must be a Python sequence whose length is the number of
- format units in \var{items}. The C arguments must correspond to the
- individual format units in \var{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
- \exception{TypeError} to be raised here may now proceed without an
- exception. This is not expected to be a problem for existing code.}
-\end{description}
-
-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:
-
-\begin{description}
- \item[\samp{|}]
- 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, \cfunction{PyArg_ParseTuple()} does not
- touch the contents of the corresponding C variable(s).
-
- \item[\samp{:}]
- 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 \cfunction{PyArg_ParseTuple()}
- raises).
-
- \item[\samp{;}]
- The list of format units ends here; the string after the semicolon
- is used as the error message \emph{instead} of the default error
- message. Clearly, \samp{:} and \samp{;} mutually exclude each
- other.
-\end{description}
-
-Note that any Python object references which are provided to the
-caller are \emph{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 \var{arg} object must match the
-format and the format must be exhausted. On success, the
-\cfunction{PyArg_Parse*()} functions return true, otherwise they
-return false and raise an appropriate exception.
-
-\begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, const char *format,
- \moreargs}
- 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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyArg_VaParse}{PyObject *args, const char *format,
- va_list vargs}
- Identical to \cfunction{PyArg_ParseTuple()}, except that it accepts a
- va_list rather than a variable number of arguments.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args,
- PyObject *kw, const char *format, char *keywords[],
- \moreargs}
- 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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyArg_VaParseTupleAndKeywords}{PyObject *args,
- PyObject *kw, const char *format, char *keywords[],
- va_list vargs}
- Identical to \cfunction{PyArg_ParseTupleAndKeywords()}, except that it
- accepts a va_list rather than a variable number of arguments.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, const char *format,
- \moreargs}
- Function used to deconstruct the argument lists of ``old-style''
- functions --- these are functions which use the
- \constant{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyArg_UnpackTuple}{PyObject *args, const char *name,
- Py_ssize_t min, Py_ssize_t max, \moreargs}
- 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
- \constant{METH_VARARGS} in function or method tables. The tuple
- containing the actual parameters should be passed as \var{args}; it
- must actually be a tuple. The length of the tuple must be at least
- \var{min} and no more than \var{max}; \var{min} and \var{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 \var{args}; they will contain
- borrowed references. The variables which correspond to optional
- parameters not given by \var{args} will not be filled in; these
- should be initialized by the caller.
- This function returns true on success and false if \var{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 \module{_weakref} helper module for weak references:
-
-\begin{verbatim}
-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;
-}
-\end{verbatim}
-
- The call to \cfunction{PyArg_UnpackTuple()} in this example is
- entirely equivalent to this call to \cfunction{PyArg_ParseTuple()}:
-
-\begin{verbatim}
-PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
-\end{verbatim}
-
- \versionadded{2.2}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{Py_BuildValue}{const char *format,
- \moreargs}
- Create a new value based on a format string similar to those
- accepted by the \cfunction{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.
-
- \cfunction{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 \code{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 \samp{s} and \samp{s\#} formats, the required
- data is copied. Buffers provided by the caller are never referenced
- by the objects created by \cfunction{Py_BuildValue()}. In other
- words, if your code invokes \cfunction{malloc()} and passes the
- allocated memory to \cfunction{Py_BuildValue()}, your code is
- responsible for calling \cfunction{free()} for that memory once
- \cfunction{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 \samp{s\#}). This can
- be used to make long format strings a tad more readable.
-
- \begin{description}
- \item[\samp{s} (string) {[char *]}]
- Convert a null-terminated C string to a Python object. If the C
- string pointer is \NULL, \code{None} is used.
-
- \item[\samp{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 \code{None} is
- returned.
-
- \item[\samp{z} (string or \code{None}) {[char *]}]
- Same as \samp{s}.
-
- \item[\samp{z\#} (string or \code{None}) {[char *, int]}]
- Same as \samp{s\#}.
-
- \item[\samp{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, \code{None} is returned.
-
- \item[\samp{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 \code{None} is returned.
-
- \item[\samp{U} (string) {[char *]}]
- Convert a null-terminated C string to a Python unicode object.
- If the C string pointer is \NULL, \code{None} is used.
-
- \item[\samp{U\#} (string) {[char *, int]}]
- Convert a C string and its length to a Python unicode object.
- If the C string pointer is \NULL, the length is ignored and \code{None}
- is returned.
-
- \item[\samp{i} (integer) {[int]}]
- Convert a plain C \ctype{int} to a Python integer object.
-
- \item[\samp{b} (integer) {[char]}]
- Convert a plain C \ctype{char} to a Python integer object.
-
- \item[\samp{h} (integer) {[short int]}]
- Convert a plain C \ctype{short int} to a Python integer object.
-
- \item[\samp{l} (integer) {[long int]}]
- Convert a C \ctype{long int} to a Python integer object.
-
- \item[\samp{B} (integer) {[unsigned char]}]
- Convert a C \ctype{unsigned char} to a Python integer object.
-
- \item[\samp{H} (integer) {[unsigned short int]}]
- Convert a C \ctype{unsigned short int} to a Python integer object.
-
- \item[\samp{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 \code{sys.maxint}.
-
- \item[\samp{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 \code{sys.maxint}.
-
- \item[\samp{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}.
-
- \item[\samp{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}.
-
- \item[\samp{n} (int) {[Py_ssize_t]}]
- Convert a C \ctype{Py_ssize_t} to a Python integer or long integer.
- \versionadded{2.5}
-
- \item[\samp{c} (string of length 1) {[char]}]
- Convert a C \ctype{int} representing a character to a Python
- string of length 1.
-
- \item[\samp{d} (float) {[double]}]
- Convert a C \ctype{double} to a Python floating point number.
-
- \item[\samp{f} (float) {[float]}]
- Same as \samp{d}.
-
- \item[\samp{D} (complex) {[Py_complex *]}]
- Convert a C \ctype{Py_complex} structure to a Python complex
- number.
-
- \item[\samp{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, \cfunction{Py_BuildValue()} will return \NULL{} but
- won't raise an exception. If no exception has been raised yet,
- \exception{SystemError} is set.
-
- \item[\samp{S} (object) {[PyObject *]}]
- Same as \samp{O}.
-
- \item[\samp{N} (object) {[PyObject *]}]
- Same as \samp{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.
-
- \item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
- Convert \var{anything} to a Python object through a
- \var{converter} function. The function is called with
- \var{anything} (which should be compatible with \ctype{void *}) as
- its argument and should return a ``new'' Python object, or \NULL{}
- if an error occurred.
-
- \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
- Convert a sequence of C values to a Python tuple with the same
- number of items.
-
- \item[\samp{[\var{items}]} (list) {[\var{matching-items}]}]
- Convert a sequence of C values to a Python list with the same
- number of items.
-
- \item[\samp{\{\var{items}\}} (dictionary) {[\var{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.
-
- \end{description}
-
- If there is an error in the format string, the
- \exception{SystemError} exception is set and \NULL{} returned.
-\end{cfuncdesc}
-
-\section{String conversion and formatting \label{string-formatting}}
-
-Functions for number conversion and formatted string output.
-
-\begin{cfuncdesc}{int}{PyOS_snprintf}{char *str, size_t size,
- const char *format, \moreargs}
-Output not more than \var{size} bytes to \var{str} according to the format
-string \var{format} and the extra arguments. See the \UNIX{} man
-page \manpage{snprintf}{2}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyOS_vsnprintf}{char *str, size_t size,
- const char *format, va_list va}
-Output not more than \var{size} bytes to \var{str} according to the format
-string \var{format} and the variable argument list \var{va}. \UNIX{}
-man page \manpage{vsnprintf}{2}.
-\end{cfuncdesc}
-
-\cfunction{PyOS_snprintf} and \cfunction{PyOS_vsnprintf} wrap the
-Standard C library functions \cfunction{snprintf()} and
-\cfunction{vsnprintf()}. Their purpose is to guarantee consistent
-behavior in corner cases, which the Standard C functions do not.
-
-The wrappers ensure that \var{str}[\var{size}-1] is always
-\character{\textbackslash0} upon return. They never write more than
-\var{size} bytes (including the trailing \character{\textbackslash0})
-into str. Both functions require that \code{\var{str} != NULL},
-\code{\var{size} > 0} and \code{\var{format} != NULL}.
-
-If the platform doesn't have \cfunction{vsnprintf()} and the buffer
-size needed to avoid truncation exceeds \var{size} by more than 512
-bytes, Python aborts with a \var{Py_FatalError}.
-
-The return value (\var{rv}) for these functions should be interpreted
-as follows:
-
-\begin{itemize}
-
-\item When \code{0 <= \var{rv} < \var{size}}, the output conversion
- was successful and \var{rv} characters were written to \var{str}
- (excluding the trailing \character{\textbackslash0} byte at
- \var{str}[\var{rv}]).
-
-\item When \code{\var{rv} >= \var{size}}, the output conversion was
- truncated and a buffer with \code{\var{rv} + 1} bytes would have
- been needed to succeed. \var{str}[\var{size}-1] is
- \character{\textbackslash0} in this case.
-
-\item When \code{\var{rv} < 0}, ``something bad happened.''
- \var{str}[\var{size}-1] is \character{\textbackslash0} in this case
- too, but the rest of \var{str} is undefined. The exact cause of the
- error depends on the underlying platform.
-
-\end{itemize}
-
-The following functions provide locale-independent string to number
-conversions.
-
-\begin{cfuncdesc}{double}{PyOS_ascii_strtod}{const char *nptr, char **endptr}
-Convert a string to a \ctype{double}. This function behaves like the
-Standard C function \cfunction{strtod()} does in the C locale. It does
-this without changing the current locale, since that would not be
-thread-safe.
-
-\cfunction{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.
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char *}{PyOS_ascii_formatd}{char *buffer, size_t buf_len,
- const char *format, double d}
-Convert a \ctype{double} to a string using the \character{.} as the
-decimal separator. \var{format} is a \cfunction{printf()}-style format
-string specifying the number format. Allowed conversion characters are
-\character{e}, \character{E}, \character{f}, \character{F},
-\character{g} and \character{G}.
-
-The return value is a pointer to \var{buffer} with the converted
-string or NULL if the conversion failed. \versionadded{2.4}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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.
-\end{cfuncdesc}
diff --git a/Doc/api/veryhigh.tex b/Doc/api/veryhigh.tex
deleted file mode 100644
index 5c79b44..0000000
--- a/Doc/api/veryhigh.tex
+++ /dev/null
@@ -1,287 +0,0 @@
-\chapter{The Very High Level Layer \label{veryhigh}}
-
-
-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 \constant{Py_eval_input},
-\constant{Py_file_input}, and \constant{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.
-
-
-\begin{cfuncdesc}{int}{Py_Main}{int argc, char **argv}
- The main program for the standard interpreter. This is made
- available for programs which embed Python. The \var{argc} and
- \var{argv} parameters should be prepared exactly as those which are
- passed to a C program's \cfunction{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
- \function{sys.exit()} function, \code{1} if the interpreter exits
- due to an exception, or \code{2} if the parameter list does not
- represent a valid Python command line.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, const char *filename}
- This is a simplified interface to \cfunction{PyRun_AnyFileExFlags()}
- below, leaving \var{closeit} set to \code{0} and \var{flags} set to \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_AnyFileFlags}{FILE *fp, const char *filename,
- PyCompilerFlags *flags}
- This is a simplified interface to \cfunction{PyRun_AnyFileExFlags()}
- below, leaving the \var{closeit} argument set to \code{0}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_AnyFileEx}{FILE *fp, const char *filename,
- int closeit}
- This is a simplified interface to \cfunction{PyRun_AnyFileExFlags()}
- below, leaving the \var{flags} argument set to \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_AnyFileExFlags}{FILE *fp, const char *filename,
- int closeit,
- PyCompilerFlags *flags}
- If \var{fp} refers to a file associated with an interactive device
- (console or terminal input or \UNIX{} pseudo-terminal), return the
- value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the
- result of \cfunction{PyRun_SimpleFile()}. If \var{filename} is
- \NULL, this function uses \code{"???"} as the filename.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_SimpleString}{const char *command}
- This is a simplified interface to \cfunction{PyRun_SimpleStringFlags()}
- below, leaving the \var{PyCompilerFlags*} argument set to NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_SimpleStringFlags}{const char *command,
- PyCompilerFlags *flags}
- Executes the Python source code from \var{command} in the
- \module{__main__} module according to the \var{flags} argument.
- If \module{__main__} does not already exist, it is created. Returns
- \code{0} on success or \code{-1} if an exception was raised. If there
- was an error, there is no way to get the exception information.
- For the meaning of \var{flags}, see below.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, const char *filename}
- This is a simplified interface to \cfunction{PyRun_SimpleFileExFlags()}
- below, leaving \var{closeit} set to \code{0} and \var{flags} set to
- \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_SimpleFileFlags}{FILE *fp, const char *filename,
- PyCompilerFlags *flags}
- This is a simplified interface to \cfunction{PyRun_SimpleFileExFlags()}
- below, leaving \var{closeit} set to \code{0}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_SimpleFileEx}{FILE *fp, const char *filename,
- int closeit}
- This is a simplified interface to \cfunction{PyRun_SimpleFileExFlags()}
- below, leaving \var{flags} set to \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_SimpleFileExFlags}{FILE *fp, const char *filename,
- int closeit,
- PyCompilerFlags *flags}
- Similar to \cfunction{PyRun_SimpleStringFlags()}, but the Python source
- code is read from \var{fp} instead of an in-memory string.
- \var{filename} should be the name of the file. If \var{closeit} is
- true, the file is closed before PyRun_SimpleFileExFlags returns.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, const char *filename}
- This is a simplified interface to \cfunction{PyRun_InteractiveOneFlags()}
- below, leaving \var{flags} set to \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \var{flags} argument. If
- \var{filename} is \NULL, \code{"???"} is used instead. The user will
- be prompted using \code{sys.ps1} and \code{sys.ps2}. Returns \code{0}
- when the input was executed successfully, \code{-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.)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, const char *filename}
- This is a simplified interface to \cfunction{PyRun_InteractiveLoopFlags()}
- below, leaving \var{flags} set to \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{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 \var{filename} is
- \NULL, \code{"???"} is used instead. The user will be prompted
- using \code{sys.ps1} and \code{sys.ps2}. Returns \code{0} at \EOF.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{const char *str,
- int start}
- This is a simplified interface to
- \cfunction{PyParser_SimpleParseStringFlagsFilename()} below, leaving
- \var{filename} set to \NULL{} and \var{flags} set to \code{0}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseStringFlags}{
- const char *str, int start, int flags}
- This is a simplified interface to
- \cfunction{PyParser_SimpleParseStringFlagsFilename()} below, leaving
- \var{filename} set to \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseStringFlagsFilename}{
- const char *str, const char *filename,
- int start, int flags}
- Parse Python source code from \var{str} using the start token
- \var{start} according to the \var{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
- const char *filename, int start}
- This is a simplified interface to \cfunction{PyParser_SimpleParseFileFlags()}
- below, leaving \var{flags} set to \code{0}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFileFlags}{FILE *fp,
- const char *filename, int start, int flags}
- Similar to \cfunction{PyParser_SimpleParseStringFlagsFilename()}, but
- the Python source code is read from \var{fp} instead of an in-memory
- string.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyRun_String}{const char *str, int start,
- PyObject *globals,
- PyObject *locals}
- This is a simplified interface to \cfunction{PyRun_StringFlags()} below,
- leaving \var{flags} set to \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyRun_StringFlags}{const char *str, int start,
- PyObject *globals,
- PyObject *locals,
- PyCompilerFlags *flags}
- Execute Python source code from \var{str} in the context specified
- by the dictionaries \var{globals} and \var{locals} with the compiler
- flags specified by \var{flags}. The parameter \var{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.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, const char *filename,
- int start, PyObject *globals,
- PyObject *locals}
- This is a simplified interface to \cfunction{PyRun_FileExFlags()} below,
- leaving \var{closeit} set to \code{0} and \var{flags} set to \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyRun_FileEx}{FILE *fp, const char *filename,
- int start, PyObject *globals,
- PyObject *locals, int closeit}
- This is a simplified interface to \cfunction{PyRun_FileExFlags()} below,
- leaving \var{flags} set to \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyRun_FileFlags}{FILE *fp, const char *filename,
- int start, PyObject *globals,
- PyObject *locals,
- PyCompilerFlags *flags}
- This is a simplified interface to \cfunction{PyRun_FileExFlags()} below,
- leaving \var{closeit} set to \code{0}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyRun_FileExFlags}{FILE *fp, const char *filename,
- int start, PyObject *globals,
- PyObject *locals, int closeit,
- PyCompilerFlags *flags}
- Similar to \cfunction{PyRun_StringFlags()}, but the Python source code is
- read from \var{fp} instead of an in-memory string.
- \var{filename} should be the name of the file.
- If \var{closeit} is true, the file is closed before
- \cfunction{PyRun_FileExFlags()} returns.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{Py_CompileString}{const char *str,
- const char *filename,
- int start}
- This is a simplified interface to \cfunction{Py_CompileStringFlags()} below,
- leaving \var{flags} set to \NULL.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{Py_CompileStringFlags}{const char *str,
- const char *filename,
- int start,
- PyCompilerFlags *flags}
- Parse and compile the Python source code in \var{str}, returning the
- resulting code object. The start token is given by \var{start};
- this can be used to constrain the code which can be compiled and should
- be \constant{Py_eval_input}, \constant{Py_file_input}, or
- \constant{Py_single_input}. The filename specified by
- \var{filename} is used to construct the code object and may appear
- in tracebacks or \exception{SyntaxError} exception messages. This
- returns \NULL{} if the code cannot be parsed or compiled.
-\end{cfuncdesc}
-
-\begin{cvardesc}{int}{Py_eval_input}
- The start symbol from the Python grammar for isolated expressions;
- for use with
- \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.
-\end{cvardesc}
-
-\begin{cvardesc}{int}{Py_file_input}
- The start symbol from the Python grammar for sequences of statements
- as read from a file or other source; for use with
- \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. This is
- the symbol to use when compiling arbitrarily long Python source code.
-\end{cvardesc}
-
-\begin{cvardesc}{int}{Py_single_input}
- The start symbol from the Python grammar for a single statement; for
- use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.
- This is the symbol used for the interactive interpreter loop.
-\end{cvardesc}
-
-\begin{ctypedesc}[PyCompilerFlags]{struct PyCompilerFlags}
- This is the structure used to hold compiler flags. In cases where
- code is only being compiled, it is passed as \code{int flags}, and in
- cases where code is being executed, it is passed as
- \code{PyCompilerFlags *flags}. In this case, \code{from __future__
- import} can modify \var{flags}.
-
- Whenever \code{PyCompilerFlags *flags} is \NULL, \member{cf_flags}
- is treated as equal to \code{0}, and any modification due to
- \code{from __future__ import} is discarded.
-\begin{verbatim}
-struct PyCompilerFlags {
- int cf_flags;
-}
-\end{verbatim}
-\end{ctypedesc}
-
-\begin{cvardesc}{int}{CO_FUTURE_DIVISION}
- This bit can be set in \var{flags} to cause division operator \code{/}
- to be interpreted as ``true division'' according to \pep{238}.
-\end{cvardesc}
diff --git a/Doc/commontex/boilerplate.tex b/Doc/commontex/boilerplate.tex
deleted file mode 100644
index b4c9f48..0000000
--- a/Doc/commontex/boilerplate.tex
+++ /dev/null
@@ -1,9 +0,0 @@
-\author{Guido van Rossum\\
- Fred L. Drake, Jr., editor}
-\authoraddress{
- \strong{Python Software Foundation}\\
- Email: \email{docs@python.org}
-}
-
-\date{\today} % XXX update before final release!
-\input{patchlevel} % include Python version information
diff --git a/Doc/commontex/copyright.tex b/Doc/commontex/copyright.tex
deleted file mode 100644
index ce70d0c..0000000
--- a/Doc/commontex/copyright.tex
+++ /dev/null
@@ -1,14 +0,0 @@
-Copyright \copyright{} 2001-2007 Python Software Foundation.
-All rights reserved.
-
-Copyright \copyright{} 2000 BeOpen.com.
-All rights reserved.
-
-Copyright \copyright{} 1995-2000 Corporation for National Research Initiatives.
-All rights reserved.
-
-Copyright \copyright{} 1991-1995 Stichting Mathematisch Centrum.
-All rights reserved.
-
-See the end of this document for complete license and permissions
-information.
diff --git a/Doc/commontex/license.tex b/Doc/commontex/license.tex
deleted file mode 100644
index fe6485c..0000000
--- a/Doc/commontex/license.tex
+++ /dev/null
@@ -1,674 +0,0 @@
-\section{History of the software}
-
-Python was created in the early 1990s by Guido van Rossum at Stichting
-Mathematisch Centrum (CWI, see \url{http://www.cwi.nl/}) in the Netherlands
-as a successor of a language called ABC. Guido remains Python's
-principal author, although it includes many contributions from others.
-
-In 1995, Guido continued his work on Python at the Corporation for
-National Research Initiatives (CNRI, see \url{http://www.cnri.reston.va.us/})
-in Reston, Virginia where he released several versions of the
-software.
-
-In May 2000, Guido and the Python core development team moved to
-BeOpen.com to form the BeOpen PythonLabs team. In October of the same
-year, the PythonLabs team moved to Digital Creations (now Zope
-Corporation; see \url{http://www.zope.com/}). In 2001, the Python
-Software Foundation (PSF, see \url{http://www.python.org/psf/}) was
-formed, a non-profit organization created specifically to own
-Python-related Intellectual Property. Zope Corporation is a
-sponsoring member of the PSF.
-
-All Python releases are Open Source (see
-\url{http://www.opensource.org/} for the Open Source Definition).
-Historically, most, but not all, Python releases have also been
-GPL-compatible; the table below summarizes the various releases.
-
-\begin{tablev}{c|c|c|c|c}{textrm}%
- {Release}{Derived from}{Year}{Owner}{GPL compatible?}
- \linev{0.9.0 thru 1.2}{n/a}{1991-1995}{CWI}{yes}
- \linev{1.3 thru 1.5.2}{1.2}{1995-1999}{CNRI}{yes}
- \linev{1.6}{1.5.2}{2000}{CNRI}{no}
- \linev{2.0}{1.6}{2000}{BeOpen.com}{no}
- \linev{1.6.1}{1.6}{2001}{CNRI}{no}
- \linev{2.1}{2.0+1.6.1}{2001}{PSF}{no}
- \linev{2.0.1}{2.0+1.6.1}{2001}{PSF}{yes}
- \linev{2.1.1}{2.1+2.0.1}{2001}{PSF}{yes}
- \linev{2.2}{2.1.1}{2001}{PSF}{yes}
- \linev{2.1.2}{2.1.1}{2002}{PSF}{yes}
- \linev{2.1.3}{2.1.2}{2002}{PSF}{yes}
- \linev{2.2.1}{2.2}{2002}{PSF}{yes}
- \linev{2.2.2}{2.2.1}{2002}{PSF}{yes}
- \linev{2.2.3}{2.2.2}{2002-2003}{PSF}{yes}
- \linev{2.3}{2.2.2}{2002-2003}{PSF}{yes}
- \linev{2.3.1}{2.3}{2002-2003}{PSF}{yes}
- \linev{2.3.2}{2.3.1}{2003}{PSF}{yes}
- \linev{2.3.3}{2.3.2}{2003}{PSF}{yes}
- \linev{2.3.4}{2.3.3}{2004}{PSF}{yes}
- \linev{2.3.5}{2.3.4}{2005}{PSF}{yes}
- \linev{2.4}{2.3}{2004}{PSF}{yes}
- \linev{2.4.1}{2.4}{2005}{PSF}{yes}
- \linev{2.4.2}{2.4.1}{2005}{PSF}{yes}
- \linev{2.4.3}{2.4.2}{2006}{PSF}{yes}
- \linev{2.4.4}{2.4.3}{2006}{PSF}{yes}
- \linev{2.5}{2.4}{2006}{PSF}{yes}
- \linev{2.5.1}{2.5}{2007}{PSF}{yes}
-\end{tablev}
-
-\note{GPL-compatible doesn't mean that we're distributing
-Python under the GPL. All Python licenses, unlike the GPL, let you
-distribute a modified version without making your changes open source.
-The GPL-compatible licenses make it possible to combine Python with
-other software that is released under the GPL; the others don't.}
-
-Thanks to the many outside volunteers who have worked under Guido's
-direction to make these releases possible.
-
-
-\section{Terms and conditions for accessing or otherwise using Python}
-
-\centerline{\strong{PSF LICENSE AGREEMENT FOR PYTHON \version}}
-
-\begin{enumerate}
-\item
-This LICENSE AGREEMENT is between the Python Software Foundation
-(``PSF''), and the Individual or Organization (``Licensee'') accessing
-and otherwise using Python \version{} software in source or binary
-form and its associated documentation.
-
-\item
-Subject to the terms and conditions of this License Agreement, PSF
-hereby grants Licensee a nonexclusive, royalty-free, world-wide
-license to reproduce, analyze, test, perform and/or display publicly,
-prepare derivative works, distribute, and otherwise use Python
-\version{} alone or in any derivative version, provided, however, that
-PSF's License Agreement and PSF's notice of copyright, i.e.,
-``Copyright \copyright{} 2001-2007 Python Software Foundation; All
-Rights Reserved'' are retained in Python \version{} alone or in any
-derivative version prepared by Licensee.
-
-\item
-In the event Licensee prepares a derivative work that is based on
-or incorporates Python \version{} or any part thereof, and wants to
-make the derivative work available to others as provided herein, then
-Licensee hereby agrees to include in any such work a brief summary of
-the changes made to Python \version.
-
-\item
-PSF is making Python \version{} available to Licensee on an ``AS IS''
-basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
-IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
-DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
-FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON \version{} WILL
-NOT INFRINGE ANY THIRD PARTY RIGHTS.
-
-\item
-PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
-\version{} FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR
-LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON
-\version, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE
-POSSIBILITY THEREOF.
-
-\item
-This License Agreement will automatically terminate upon a material
-breach of its terms and conditions.
-
-\item
-Nothing in this License Agreement shall be deemed to create any
-relationship of agency, partnership, or joint venture between PSF and
-Licensee. This License Agreement does not grant permission to use PSF
-trademarks or trade name in a trademark sense to endorse or promote
-products or services of Licensee, or any third party.
-
-\item
-By copying, installing or otherwise using Python \version, Licensee
-agrees to be bound by the terms and conditions of this License
-Agreement.
-\end{enumerate}
-
-
-\centerline{\strong{BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0}}
-
-\centerline{\strong{BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1}}
-
-\begin{enumerate}
-\item
-This LICENSE AGREEMENT is between BeOpen.com (``BeOpen''), having an
-office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the
-Individual or Organization (``Licensee'') accessing and otherwise
-using this software in source or binary form and its associated
-documentation (``the Software'').
-
-\item
-Subject to the terms and conditions of this BeOpen Python License
-Agreement, BeOpen hereby grants Licensee a non-exclusive,
-royalty-free, world-wide license to reproduce, analyze, test, perform
-and/or display publicly, prepare derivative works, distribute, and
-otherwise use the Software alone or in any derivative version,
-provided, however, that the BeOpen Python License is retained in the
-Software, alone or in any derivative version prepared by Licensee.
-
-\item
-BeOpen is making the Software available to Licensee on an ``AS IS''
-basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
-IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND
-DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
-FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT
-INFRINGE ANY THIRD PARTY RIGHTS.
-
-\item
-BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE
-SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS
-AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY
-DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
-
-\item
-This License Agreement will automatically terminate upon a material
-breach of its terms and conditions.
-
-\item
-This License Agreement shall be governed by and interpreted in all
-respects by the law of the State of California, excluding conflict of
-law provisions. Nothing in this License Agreement shall be deemed to
-create any relationship of agency, partnership, or joint venture
-between BeOpen and Licensee. This License Agreement does not grant
-permission to use BeOpen trademarks or trade names in a trademark
-sense to endorse or promote products or services of Licensee, or any
-third party. As an exception, the ``BeOpen Python'' logos available
-at http://www.pythonlabs.com/logos.html may be used according to the
-permissions granted on that web page.
-
-\item
-By copying, installing or otherwise using the software, Licensee
-agrees to be bound by the terms and conditions of this License
-Agreement.
-\end{enumerate}
-
-
-\centerline{\strong{CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1}}
-
-\begin{enumerate}
-\item
-This LICENSE AGREEMENT is between the Corporation for National
-Research Initiatives, having an office at 1895 Preston White Drive,
-Reston, VA 20191 (``CNRI''), and the Individual or Organization
-(``Licensee'') accessing and otherwise using Python 1.6.1 software in
-source or binary form and its associated documentation.
-
-\item
-Subject to the terms and conditions of this License Agreement, CNRI
-hereby grants Licensee a nonexclusive, royalty-free, world-wide
-license to reproduce, analyze, test, perform and/or display publicly,
-prepare derivative works, distribute, and otherwise use Python 1.6.1
-alone or in any derivative version, provided, however, that CNRI's
-License Agreement and CNRI's notice of copyright, i.e., ``Copyright
-\copyright{} 1995-2001 Corporation for National Research Initiatives;
-All Rights Reserved'' are retained in Python 1.6.1 alone or in any
-derivative version prepared by Licensee. Alternately, in lieu of
-CNRI's License Agreement, Licensee may substitute the following text
-(omitting the quotes): ``Python 1.6.1 is made available subject to the
-terms and conditions in CNRI's License Agreement. This Agreement
-together with Python 1.6.1 may be located on the Internet using the
-following unique, persistent identifier (known as a handle):
-1895.22/1013. This Agreement may also be obtained from a proxy server
-on the Internet using the following URL:
-\url{http://hdl.handle.net/1895.22/1013}.''
-
-\item
-In the event Licensee prepares a derivative work that is based on
-or incorporates Python 1.6.1 or any part thereof, and wants to make
-the derivative work available to others as provided herein, then
-Licensee hereby agrees to include in any such work a brief summary of
-the changes made to Python 1.6.1.
-
-\item
-CNRI is making Python 1.6.1 available to Licensee on an ``AS IS''
-basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
-IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND
-DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
-FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT
-INFRINGE ANY THIRD PARTY RIGHTS.
-
-\item
-CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
-1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
-A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1,
-OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
-
-\item
-This License Agreement will automatically terminate upon a material
-breach of its terms and conditions.
-
-\item
-This License Agreement shall be governed by the federal
-intellectual property law of the United States, including without
-limitation the federal copyright law, and, to the extent such
-U.S. federal law does not apply, by the law of the Commonwealth of
-Virginia, excluding Virginia's conflict of law provisions.
-Notwithstanding the foregoing, with regard to derivative works based
-on Python 1.6.1 that incorporate non-separable material that was
-previously distributed under the GNU General Public License (GPL), the
-law of the Commonwealth of Virginia shall govern this License
-Agreement only as to issues arising under or with respect to
-Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this
-License Agreement shall be deemed to create any relationship of
-agency, partnership, or joint venture between CNRI and Licensee. This
-License Agreement does not grant permission to use CNRI trademarks or
-trade name in a trademark sense to endorse or promote products or
-services of Licensee, or any third party.
-
-\item
-By clicking on the ``ACCEPT'' button where indicated, or by copying,
-installing or otherwise using Python 1.6.1, Licensee agrees to be
-bound by the terms and conditions of this License Agreement.
-\end{enumerate}
-
-\centerline{ACCEPT}
-
-
-
-\centerline{\strong{CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2}}
-
-Copyright \copyright{} 1991 - 1995, Stichting Mathematisch Centrum
-Amsterdam, The Netherlands. All rights reserved.
-
-Permission to use, copy, modify, and distribute this software and its
-documentation for any purpose and without fee is hereby granted,
-provided that the above copyright notice appear in all copies and that
-both that copyright notice and this permission notice appear in
-supporting documentation, and that the name of Stichting Mathematisch
-Centrum or CWI not be used in advertising or publicity pertaining to
-distribution of the software without specific, written prior
-permission.
-
-STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
-THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
-FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
-FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
-OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-
-
-\section{Licenses and Acknowledgements for Incorporated Software}
-
-This section is an incomplete, but growing list of licenses and
-acknowledgements for third-party software incorporated in the
-Python distribution.
-
-
-\subsection{Mersenne Twister}
-
-The \module{_random} module includes code based on a download from
-\url{http://www.math.keio.ac.jp/~matumoto/MT2002/emt19937ar.html}.
-The following are the verbatim comments from the original code:
-
-\begin{verbatim}
-A C-program for MT19937, with initialization improved 2002/1/26.
-Coded by Takuji Nishimura and Makoto Matsumoto.
-
-Before using, initialize the state by using init_genrand(seed)
-or init_by_array(init_key, key_length).
-
-Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions
-are met:
-
- 1. Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
-
- 2. Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in the
- documentation and/or other materials provided with the distribution.
-
- 3. The names of its contributors may not be used to endorse or promote
- products derived from this software without specific prior written
- permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
-CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
-EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
-PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
-LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
-NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-
-Any feedback is very welcome.
-http://www.math.keio.ac.jp/matumoto/emt.html
-email: matumoto@math.keio.ac.jp
-\end{verbatim}
-
-
-
-\subsection{Sockets}
-
-The \module{socket} module uses the functions, \function{getaddrinfo},
-and \function{getnameinfo}, which are coded in separate source files
-from the WIDE Project, \url{http://www.wide.ad.jp/about/index.html}.
-
-\begin{verbatim}
-Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions
-are met:
-1. Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
-2. Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in the
- documentation and/or other materials provided with the distribution.
-3. Neither the name of the project nor the names of its contributors
- may be used to endorse or promote products derived from this software
- without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
-GAI_ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
-FOR GAI_ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-HOWEVER CAUSED AND ON GAI_ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN GAI_ANY WAY
-OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-SUCH DAMAGE.
-\end{verbatim}
-
-
-
-\subsection{Floating point exception control}
-
-The source for the \module{fpectl} module includes the following notice:
-
-\begin{verbatim}
- ---------------------------------------------------------------------
- / Copyright (c) 1996. \
- | The Regents of the University of California. |
- | All rights reserved. |
- | |
- | Permission to use, copy, modify, and distribute this software for |
- | any purpose without fee is hereby granted, provided that this en- |
- | tire notice is included in all copies of any software which is or |
- | includes a copy or modification of this software and in all |
- | copies of the supporting documentation for such software. |
- | |
- | This work was produced at the University of California, Lawrence |
- | Livermore National Laboratory under contract no. W-7405-ENG-48 |
- | between the U.S. Department of Energy and The Regents of the |
- | University of California for the operation of UC LLNL. |
- | |
- | DISCLAIMER |
- | |
- | This software was prepared as an account of work sponsored by an |
- | agency of the United States Government. Neither the United States |
- | Government nor the University of California nor any of their em- |
- | ployees, makes any warranty, express or implied, or assumes any |
- | liability or responsibility for the accuracy, completeness, or |
- | usefulness of any information, apparatus, product, or process |
- | disclosed, or represents that its use would not infringe |
- | privately-owned rights. Reference herein to any specific commer- |
- | cial products, process, or service by trade name, trademark, |
- | manufacturer, or otherwise, does not necessarily constitute or |
- | imply its endorsement, recommendation, or favoring by the United |
- | States Government or the University of California. The views and |
- | opinions of authors expressed herein do not necessarily state or |
- | reflect those of the United States Government or the University |
- | of California, and shall not be used for advertising or product |
- \ endorsement purposes. /
- ---------------------------------------------------------------------
-\end{verbatim}
-
-
-
-\subsection{MD5 message digest algorithm}
-
-The source code for the \module{md5} module contains the following notice:
-
-\begin{verbatim}
- Copyright (C) 1999, 2002 Aladdin Enterprises. All rights reserved.
-
- This software is provided 'as-is', without any express or implied
- warranty. In no event will the authors be held liable for any damages
- arising from the use of this software.
-
- Permission is granted to anyone to use this software for any purpose,
- including commercial applications, and to alter it and redistribute it
- freely, subject to the following restrictions:
-
- 1. The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
- 2. Altered source versions must be plainly marked as such, and must not be
- misrepresented as being the original software.
- 3. This notice may not be removed or altered from any source distribution.
-
- L. Peter Deutsch
- ghost@aladdin.com
-
- Independent implementation of MD5 (RFC 1321).
-
- This code implements the MD5 Algorithm defined in RFC 1321, whose
- text is available at
- http://www.ietf.org/rfc/rfc1321.txt
- The code is derived from the text of the RFC, including the test suite
- (section A.5) but excluding the rest of Appendix A. It does not include
- any code or documentation that is identified in the RFC as being
- copyrighted.
-
- The original and principal author of md5.h is L. Peter Deutsch
- <ghost@aladdin.com>. Other authors are noted in the change history
- that follows (in reverse chronological order):
-
- 2002-04-13 lpd Removed support for non-ANSI compilers; removed
- references to Ghostscript; clarified derivation from RFC 1321;
- now handles byte order either statically or dynamically.
- 1999-11-04 lpd Edited comments slightly for automatic TOC extraction.
- 1999-10-18 lpd Fixed typo in header comment (ansi2knr rather than md5);
- added conditionalization for C++ compilation from Martin
- Purschke <purschke@bnl.gov>.
- 1999-05-03 lpd Original version.
-\end{verbatim}
-
-
-
-\subsection{Asynchronous socket services}
-
-The \module{asynchat} and \module{asyncore} modules contain the
-following notice:
-
-\begin{verbatim}
- Copyright 1996 by Sam Rushing
-
- All Rights Reserved
-
- Permission to use, copy, modify, and distribute this software and
- its documentation for any purpose and without fee is hereby
- granted, provided that the above copyright notice appear in all
- copies and that both that copyright notice and this permission
- notice appear in supporting documentation, and that the name of Sam
- Rushing not be used in advertising or publicity pertaining to
- distribution of the software without specific, written prior
- permission.
-
- SAM RUSHING DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
- INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
- NO EVENT SHALL SAM RUSHING BE LIABLE FOR ANY SPECIAL, INDIRECT OR
- CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
- OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
- CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-\end{verbatim}
-
-
-\subsection{Cookie management}
-
-The \module{Cookie} module contains the following notice:
-
-\begin{verbatim}
- Copyright 2000 by Timothy O'Malley <timo@alum.mit.edu>
-
- All Rights Reserved
-
- Permission to use, copy, modify, and distribute this software
- and its documentation for any purpose and without fee is hereby
- granted, provided that the above copyright notice appear in all
- copies and that both that copyright notice and this permission
- notice appear in supporting documentation, and that the name of
- Timothy O'Malley not be used in advertising or publicity
- pertaining to distribution of the software without specific, written
- prior permission.
-
- Timothy O'Malley DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
- SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS, IN NO EVENT SHALL Timothy O'Malley BE LIABLE FOR
- ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
- WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
- WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
- ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-\end{verbatim}
-
-
-
-\subsection{Profiling}
-
-The \module{profile} and \module{pstats} modules contain
-the following notice:
-
-\begin{verbatim}
- Copyright 1994, by InfoSeek Corporation, all rights reserved.
- Written by James Roskind
-
- Permission to use, copy, modify, and distribute this Python software
- and its associated documentation for any purpose (subject to the
- restriction in the following sentence) without fee is hereby granted,
- provided that the above copyright notice appears in all copies, and
- that both that copyright notice and this permission notice appear in
- supporting documentation, and that the name of InfoSeek not be used in
- advertising or publicity pertaining to distribution of the software
- without specific, written prior permission. This permission is
- explicitly restricted to the copying and modification of the software
- to remain in Python, compiled Python, or other languages (such as C)
- wherein the modified or derived code is exclusively imported into a
- Python module.
-
- INFOSEEK CORPORATION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
- SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
- FITNESS. IN NO EVENT SHALL INFOSEEK CORPORATION BE LIABLE FOR ANY
- SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
- RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
- CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
- CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-\end{verbatim}
-
-
-
-\subsection{Execution tracing}
-
-The \module{trace} module contains the following notice:
-
-\begin{verbatim}
- portions copyright 2001, Autonomous Zones Industries, Inc., all rights...
- err... reserved and offered to the public under the terms of the
- Python 2.2 license.
- Author: Zooko O'Whielacronx
- http://zooko.com/
- mailto:zooko@zooko.com
-
- Copyright 2000, Mojam Media, Inc., all rights reserved.
- Author: Skip Montanaro
-
- Copyright 1999, Bioreason, Inc., all rights reserved.
- Author: Andrew Dalke
-
- Copyright 1995-1997, Automatrix, Inc., all rights reserved.
- Author: Skip Montanaro
-
- Copyright 1991-1995, Stichting Mathematisch Centrum, all rights reserved.
-
-
- Permission to use, copy, modify, and distribute this Python software and
- its associated documentation for any purpose without fee is hereby
- granted, provided that the above copyright notice appears in all copies,
- and that both that copyright notice and this permission notice appear in
- supporting documentation, and that the name of neither Automatrix,
- Bioreason or Mojam Media be used in advertising or publicity pertaining to
- distribution of the software without specific, written prior permission.
-\end{verbatim}
-
-
-
-\subsection{UUencode and UUdecode functions}
-
-The \module{uu} module contains the following notice:
-
-\begin{verbatim}
- Copyright 1994 by Lance Ellinghouse
- Cathedral City, California Republic, United States of America.
- All Rights Reserved
- Permission to use, copy, modify, and distribute this software and its
- documentation for any purpose and without fee is hereby granted,
- provided that the above copyright notice appear in all copies and that
- both that copyright notice and this permission notice appear in
- supporting documentation, and that the name of Lance Ellinghouse
- not be used in advertising or publicity pertaining to distribution
- of the software without specific, written prior permission.
- LANCE ELLINGHOUSE DISCLAIMS ALL WARRANTIES WITH REGARD TO
- THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
- FITNESS, IN NO EVENT SHALL LANCE ELLINGHOUSE CENTRUM BE LIABLE
- FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
- WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
- ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
- OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-
- Modified by Jack Jansen, CWI, July 1995:
- - Use binascii module to do the actual line-by-line conversion
- between ascii and binary. This results in a 1000-fold speedup. The C
- version is still 5 times faster, though.
- - Arguments more compliant with python standard
-\end{verbatim}
-
-
-
-\subsection{XML Remote Procedure Calls}
-
-The \module{xmlrpclib} module contains the following notice:
-
-\begin{verbatim}
- The XML-RPC client interface is
-
- Copyright (c) 1999-2002 by Secret Labs AB
- Copyright (c) 1999-2002 by Fredrik Lundh
-
- By obtaining, using, and/or copying this software and/or its
- associated documentation, you agree that you have read, understood,
- and will comply with the following terms and conditions:
-
- Permission to use, copy, modify, and distribute this software and
- its associated documentation for any purpose and without fee is
- hereby granted, provided that the above copyright notice appears in
- all copies, and that both that copyright notice and this permission
- notice appear in supporting documentation, and that the name of
- Secret Labs AB or the author not be used in advertising or publicity
- pertaining to distribution of the software without specific, written
- prior permission.
-
- SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
- TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT-
- ABILITY AND FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR
- BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
- DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
- WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
- ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
- OF THIS SOFTWARE.
-\end{verbatim}
diff --git a/Doc/commontex/reportingbugs.tex b/Doc/commontex/reportingbugs.tex
deleted file mode 100644
index 68f2ebf..0000000
--- a/Doc/commontex/reportingbugs.tex
+++ /dev/null
@@ -1,61 +0,0 @@
-\label{reporting-bugs}
-
-Python is a mature programming language which has established a
-reputation for stability. In order to maintain this reputation, the
-developers would like to know of any deficiencies you find in Python
-or its documentation.
-
-Before submitting a report, you will be required to log into SourceForge;
-this will make it possible for the developers to contact you
-for additional information if needed. It is not possible to submit a
-bug report anonymously.
-
-All bug reports should be submitted via the Python Bug Tracker on
-SourceForge (\url{http://sourceforge.net/bugs/?group_id=5470}). 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 left side of the page.
-
-If the problem you're reporting is not already in the bug tracker, go
-back to the Python Bug Tracker
-(\url{http://sourceforge.net/bugs/?group_id=5470}). Select the
-``Submit a Bug'' link at the top of the page to open the bug reporting
-form.
-
-The submission form has a number of fields. The only fields that are
-required are the ``Summary'' and ``Details'' fields. For the summary,
-enter a \emph{very} short description of the problem; less than ten
-words is good. In the Details field, describe the problem in detail,
-including what you expected to happen and what did happen. Be sure to
-include the version of Python you used, whether any extension modules
-were involved, and what hardware and software platform you were using
-(including version information as appropriate).
-
-The only other field that you may want to set is the ``Category''
-field, which allows you to place the bug report into a broad category
-(such as ``Documentation'' or ``Library'').
-
-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.
-
-
-\begin{seealso}
- \seetitle[http://www-mice.cs.ucl.ac.uk/multimedia/software/documentation/ReportingBugs.html]{How
- to Report Bugs Effectively}{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.}
-
- \seetitle[http://www.mozilla.org/quality/bug-writing-guidelines.html]{Bug
- Writing Guidelines}{Information about writing a good bug
- report. Some of this is specific to the Mozilla project, but
- describes general good practices.}
-\end{seealso}
diff --git a/Doc/commontex/typestruct.h b/Doc/commontex/typestruct.h
deleted file mode 100644
index 0afe375..0000000
--- a/Doc/commontex/typestruct.h
+++ /dev/null
@@ -1,76 +0,0 @@
-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;
diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex
deleted file mode 100644
index a33227f..0000000
--- a/Doc/dist/dist.tex
+++ /dev/null
@@ -1,3811 +0,0 @@
-\documentclass{manual}
-\usepackage{distutils}
-
-% $Id$
-
-% TODO
-% Document extension.read_setup_file
-% Document build_clib command
-%
-
-\title{Distributing Python Modules}
-
-\input{boilerplate}
-
-\author{Greg Ward\\
- Anthony Baxter}
-\authoraddress{
- \strong{Python Software Foundation}\\
- Email: \email{distutils-sig@python.org}
-}
-
-\makeindex
-\makemodindex
-
-\begin{document}
-
-\maketitle
-
-\input{copyright}
-
-\begin{abstract}
- \noindent
- 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.
-\end{abstract}
-
-% The ugly "%begin{latexonly}" pseudo-environment suppresses the table
-% of contents for HTML generation.
-%
-%begin{latexonly}
-\tableofcontents
-%end{latexonly}
-
-
-\chapter{An Introduction to Distutils}
-\label{intro}
-
-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 \citetitle[../inst/inst.html]{Installing Python
-Modules} manual.
-
-
-\section{Concepts \& Terminology}
-\label{concepts}
-
-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:
-\begin{itemize}
-\item write a setup script (\file{setup.py} by convention)
-\item (optional) write a setup configuration file
-\item create a source distribution
-\item (optional) create one or more built (binary) distributions
-\end{itemize}
-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
-\emph{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.
-
-
-\section{A Simple Example}
-\label{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 \module{foo},
-contained in a file \file{foo.py}, then your setup script can be as
-simple as this:
-
-\begin{verbatim}
-from distutils.core import setup
-setup(name='foo',
- version='1.0',
- py_modules=['foo'],
- )
-\end{verbatim}
-
-Some observations:
-\begin{itemize}
-\item most information that you supply to the Distutils is supplied as
- keyword arguments to the \function{setup()} function
-\item 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)
-\item modules are specified by module name, not filename (the same will
- hold true for packages and extensions)
-\item 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)
-\end{itemize}
-
-To create a source distribution for this module, you would create a
-setup script, \file{setup.py}, containing the above code, and run:
-
-\begin{verbatim}
-python setup.py sdist
-\end{verbatim}
-
-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 \module{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
-
-\begin{verbatim}
-python setup.py install
-\end{verbatim}
-
-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 \emph{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:
-
-\begin{verbatim}
-python setup.py bdist_wininst
-\end{verbatim}
-
-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}:
-
-\begin{verbatim}
-python setup.py bdist_rpm
-\end{verbatim}
-
-(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
-
-\begin{verbatim}
-python setup.py bdist --help-formats
-\end{verbatim}
-
-
-\section{General Python terminology}
-\label{python-terms}
-
-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:
-\begin{description}
-\item[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.
-
-\item[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.''
-
-\item[extension module] a module written in the low-level language of
- the Python implementation: C/\Cpp{} 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/\Cpp{} extensions for Python.)
-
-\item[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}.
-
-\item[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 \code{sys.path}
- contributes modules to the root package.
-\end{description}
-
-
-\section{Distutils-specific terminology}
-\label{distutils-term}
-
-The following terms apply more specifically to the domain of
-distributing Python modules using the Distutils:
-\begin{description}
-\item[module distribution] a collection of Python modules distributed
- together as a single downloadable resource and meant to be installed
- \emph{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 \emph{package}, except that term
- is already taken in the Python context: a single module distribution
- may contain zero, one, or many Python packages.)
-
-\item[pure module distribution] a module distribution that contains only
- pure Python modules and packages. Sometimes referred to as a ``pure
- distribution.''
-
-\item[non-pure module distribution] a module distribution that contains
- at least one extension module. Sometimes referred to as a ``non-pure
- distribution.''
-
-\item[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.
-\end{description}
-
-
-\chapter{Writing the Setup Script}
-\label{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{simple-example} above,
-the setup script consists mainly of a call to \function{setup()}, and
-most information supplied to the Distutils by the module developer is
-supplied as keyword arguments to \function{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.)
-
-\begin{verbatim}
-#!/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'],
- )
-\end{verbatim}
-
-There are only two differences between this and the trivial one-file
-distribution presented in section~\ref{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 \emph{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
-\function{glob.glob()} or \function{os.listdir()} to specify files, you
-should be careful to write portable code instead of hardcoding path
-separators:
-
-\begin{verbatim}
- glob.glob(os.path.join('mydir', 'subdir', '*.html'))
- os.listdir(os.path.join('mydir', 'subdir'))
-\end{verbatim}
-
-
-\section{Listing whole packages}
-\label{listing-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 \module{distutils} is found in the directory
-\file{distutils} relative to the distribution root. Thus, when you say
-\code{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 \module{foo} package are in \file{lib/foo},
-and so forth. Then you would put
-
-\begin{verbatim}
-package_dir = {'': 'lib'}
-\end{verbatim}
-
-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 \code{packages = ['foo']}, you are promising that the file
-\file{lib/foo/\_\_init\_\_.py} exists.
-
-Another possible convention is to put the \module{foo} package right in
-\file{lib}, the \module{foo.bar} package in \file{lib/bar}, etc. This
-would be written in the setup script as
-
-\begin{verbatim}
-package_dir = {'foo': 'lib'}
-\end{verbatim}
-
-A \code{\var{package}: \var{dir}} entry in the \option{package\_dir}
-dictionary implicitly applies to all packages below \var{package}, so
-the \module{foo.bar} case is automatically handled here. In this
-example, having \code{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 \emph{not} recursively
-scan your source tree looking for any directory with an
-\file{\_\_init\_\_.py} file.)
-
-
-\section{Listing individual modules}
-\label{listing-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{simple-example}; here is a
-slightly more involved example:
-
-\begin{verbatim}
-py_modules = ['mod1', 'pkg.mod2']
-\end{verbatim}
-
-This describes two modules, one of them in the ``root'' package, the
-other in the \module{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.
-
-
-\section{Describing extension modules}
-\label{describing-extensions}
-
-% XXX read over this section
-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.).
-
-All of this is done through another keyword argument to
-\function{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 \module{foo} and implemented by \file{foo.c}. If no
-additional instructions to the compiler/linker are needed, describing
-this extension is quite simple:
-
-\begin{verbatim}
-Extension('foo', ['foo.c'])
-\end{verbatim}
-
-The \class{Extension} class can be imported from
-\module{distutils.core} along with \function{setup()}. Thus, the setup
-script for a module distribution that contains only this one extension
-and nothing else might be:
-
-\begin{verbatim}
-from distutils.core import setup, Extension
-setup(name='foo',
- version='1.0',
- ext_modules=[Extension('foo', ['foo.c'])],
- )
-\end{verbatim}
-
-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.
-
-
-\subsection{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,
-
-\begin{verbatim}
-Extension('foo', ['src/foo1.c', 'src/foo2.c'])
-\end{verbatim}
-
-describes an extension that lives in the root package, while
-
-\begin{verbatim}
-Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
-\end{verbatim}
-
-describes the same extension in the \module{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 \function{setup()}. For example,
-
-\begin{verbatim}
-setup(...
- ext_package='pkg',
- ext_modules=[Extension('foo', ['foo.c']),
- Extension('subpkg.bar', ['bar.c'])],
- )
-\end{verbatim}
-
-will compile \file{foo.c} to the extension \module{pkg.foo}, and
-\file{bar.c} to \module{pkg.subpkg.bar}.
-
-
-\subsection{Extension source files}
-
-The second argument to the \class{Extension} constructor is a list of
-source files. Since the Distutils currently only support C, \Cpp, and
-Objective-C extensions, these are normally C/\Cpp/Objective-C source
-files. (Be sure to use appropriate extensions to distinguish \Cpp\
-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/\Cpp{} file into your extension.
-
-\XXX{SWIG support is rough around the edges and largely untested!}
-
-This warning notwithstanding, options to SWIG can be currently passed
-like this:
-
-\begin{verbatim}
-setup(...
- ext_modules=[Extension('_foo', ['foo.i'],
- swig_opts=['-modern', '-I../include'])],
- py_modules=['foo'],
- )
-\end{verbatim}
-
-Or on the commandline like this:
-
-\begin{verbatim}
-> python setup.py build_ext --swig-opts="-modern -I../include"
-\end{verbatim}
-
-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 \Cpp. These will be compiled to binary resource
-(\file{.res}) files and linked into the executable.
-
-
-\subsection{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: \code{include\_dirs}, \code{define\_macros}, and
-\code{undef\_macros}.
-
-For example, if your extension requires header files in the
-\file{include} directory under your distribution root, use the
-\code{include\_dirs} option:
-
-\begin{verbatim}
-Extension('foo', ['foo.c'], include_dirs=['include'])
-\end{verbatim}
-
-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
-
-\begin{verbatim}
-Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
-\end{verbatim}
-
-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
-\begin{verbatim}
-#include <X11/Xlib.h>
-\end{verbatim}
-
-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
-\begin{verbatim}
-#include <Numerical/arrayobject.h>
-\end{verbatim}
-If you must put the \file{Numerical} include directory right into your
-header search path, though, you can find that directory using the
-Distutils \refmodule{distutils.sysconfig} module:
-
-\begin{verbatim}
-from distutils.sysconfig import get_python_inc
-incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
-setup(...,
- Extension(..., include_dirs=[incdir]),
- )
-\end{verbatim}
-
-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
-\code{define\_macros} and \code{undef\_macros} options.
-\code{define\_macros} takes a list of \code{(name, value)} tuples, where
-\code{name} is the name of the macro to define (a string) and
-\code{value} is its value: either a string or \code{None}. (Defining a
-macro \code{FOO} to \code{None} is the equivalent of a bare
-\code{\#define FOO} in your C source: with most compilers, this sets
-\code{FOO} to the string \code{1}.) \code{undef\_macros} is just
-a list of macros to undefine.
-
-For example:
-
-\begin{verbatim}
-Extension(...,
- define_macros=[('NDEBUG', '1'),
- ('HAVE_STRFTIME', None)],
- undef_macros=['HAVE_FOO', 'HAVE_BAR'])
-\end{verbatim}
-
-is the equivalent of having this at the top of every C source file:
-
-\begin{verbatim}
-#define NDEBUG 1
-#define HAVE_STRFTIME
-#undef HAVE_FOO
-#undef HAVE_BAR
-\end{verbatim}
-
-
-\subsection{Library options}
-
-You can also specify the libraries to link against when building your
-extension, and the directories to search for those libraries. The
-\code{libraries} option is a list of libraries to link against,
-\code{library\_dirs} is a list of directories to search for libraries at
-link-time, and \code{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
-
-\begin{verbatim}
-Extension(...,
- libraries=['gdbm', 'readline'])
-\end{verbatim}
-
-If you need to link with libraries in a non-standard location, you'll
-have to include the location in \code{library\_dirs}:
-
-\begin{verbatim}
-Extension(...,
- library_dirs=['/usr/X11R6/lib'],
- libraries=['X11', 'Xt'])
-\end{verbatim}
-
-(Again, this sort of non-portable construct should be avoided if you
-intend to distribute your code.)
-
-\XXX{Should mention clib libraries here or somewhere else!}
-
-\subsection{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 \code{initmodule}
-to the list of exported symbols.
-
-\section{Relationships between Distributions and Packages}
-
-A distribution may relate to packages in three specific ways:
-
-\begin{enumerate}
- \item It can require packages or modules.
-
- \item It can provide packages or modules.
-
- \item It can obsolete packages or modules.
-\end{enumerate}
-
-These relationships can be specified using keyword arguments to the
-\function{distutils.core.setup()} function.
-
-Dependencies on other Python modules and packages can be specified by
-supplying the \var{requires} keyword argument to \function{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 \code{'mymodule'} and \code{'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:
-
-\begin{verbatim}
-< > ==
-<= >= !=
-\end{verbatim}
-
-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:
-
-\begin{tableii}{l|l}{code}{Requires Expression}{Explanation}
- \lineii{==1.0} {Only version \code{1.0} is compatible}
- \lineii{>1.0, !=1.5.1, <2.0} {Any version after \code{1.0} and before
- \code{2.0} is compatible, except
- \code{1.5.1}}
-\end{tableii}
-
-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 \var{provides} keyword argument to \function{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:
-
-\begin{tableii}{l|l}{code}{Provides Expression}{Explanation}
- \lineii{mypkg} {Provide \code{mypkg}, using the distribution version}
- \lineii{mypkg (1.1)} {Provide \code{mypkg} version 1.1, regardless of the
- distribution version}
-\end{tableii}
-
-A package can declare that it obsoletes other packages using the
-\var{obsoletes} keyword argument. The value for this is similar to
-that of the \var{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.
-
-
-\section{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 \code{\#!} 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 \longprogramopt{executable} (or
-\programopt{-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:
-
-\begin{verbatim}
-setup(...
- scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
- )
-\end{verbatim}
-
-
-\section{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 \code{package_data}
-keyword argument to the \function{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
-\code{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:
-
-\begin{verbatim}
-setup.py
-src/
- mypkg/
- __init__.py
- module.py
- data/
- tables.dat
- spoons.dat
- forks.dat
-\end{verbatim}
-
-The corresponding call to \function{setup()} might be:
-
-\begin{verbatim}
-setup(...,
- packages=['mypkg'],
- package_dir={'mypkg': 'src/mypkg'},
- package_data={'mypkg': ['data/*.dat']},
- )
-\end{verbatim}
-
-
-\versionadded{2.4}
-
-
-\section{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 (\var{directory},
-\var{files}) pairs in the following way:
-
-\begin{verbatim}
-setup(...
- data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
- ('config', ['cfg/data.cfg']),
- ('/etc/init.d', ['init-script'])]
- )
-\end{verbatim}
-
-Note that you can specify the directory names where the data files
-will be installed, but you cannot rename the data files themselves.
-
-Each (\var{directory}, \var{files}) pair in the sequence specifies the
-installation directory and the files to install there. If
-\var{directory} is a relative path, it is interpreted relative to the
-installation prefix (Python's \code{sys.prefix} for pure-Python
-packages, \code{sys.exec_prefix} for packages that contain extension
-modules). Each file name in \var{files} is interpreted relative to
-the \file{setup.py} script at the top of the package source
-distribution. No directory information from \var{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.
-
-\section{Additional meta-data}
-\label{meta-data}
-
-The setup script may include additional meta-data beyond the name and
-version. This information includes:
-
-\begin{tableiv}{l|l|l|c}{code}%
- {Meta-Data}{Description}{Value}{Notes}
- \lineiv{name}{name of the package}
- {short string}{(1)}
- \lineiv{version}{version of this release}
- {short string}{(1)(2)}
- \lineiv{author}{package author's name}
- {short string}{(3)}
- \lineiv{author_email}{email address of the package author}
- {email address}{(3)}
- \lineiv{maintainer}{package maintainer's name}
- {short string}{(3)}
- \lineiv{maintainer_email}{email address of the package maintainer}
- {email address}{(3)}
- \lineiv{url}{home page for the package}
- {URL}{(1)}
- \lineiv{description}{short, summary description of the package}
- {short string}{}
- \lineiv{long_description}{longer description of the package}
- {long string}{}
- \lineiv{download_url}{location where the package may be downloaded}
- {URL}{(4)}
- \lineiv{classifiers}{a list of classifiers}
- {list of strings}{(4)}
-\end{tableiv}
-
-\noindent Notes:
-\begin{description}
-\item[(1)] These fields are required.
-\item[(2)] It is recommended that versions take the form
- \emph{major.minor\optional{.patch\optional{.sub}}}.
-\item[(3)] Either the author or the maintainer must be identified.
-\item[(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 \ulink{PyPI website}{http://www.python.org/pypi}.
-
-\item['short string'] A single line of text, not more than 200 characters.
-\item['long string'] Multiple lines of plain text in reStructuredText
- format (see \url{http://docutils.sf.net/}).
-\item['list of strings'] See below.
-\end{description}
-
-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
-\emph{major.minor\optional{.patch}\optional{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:
-
-\begin{description}
-\item[0.1.0] the first, experimental release of a package
-\item[1.0.1a2] the second alpha release of the first patch version of 1.0
-\end{description}
-
-\option{classifiers} are specified in a python list:
-
-\begin{verbatim}
-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',
- ],
- )
-\end{verbatim}
-
-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 \function{setup()} call.
-
-\begin{verbatim}
-# 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
-\end{verbatim}
-
-
-\section{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.
-
-\chapter{Writing the Setup Configuration File}
-\label{setup-config}
-
-Often, it's not possible to write down everything needed to build a
-distribution \emph{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.
-
-% (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.)
-
-The setup configuration file is a useful middle-ground between the setup
-script---which, ideally, would be opaque to installers\footnote{This
- ideal probably won't be achieved until auto-configuration is fully
- supported by the Distutils.}---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:
-\begin{itemize}
-\item installers can override some of what you put in \file{setup.py} by
- editing \file{setup.cfg}
-\item you can provide non-standard defaults for options that are not
- easily set in \file{setup.py}
-\item installers can override anything in \file{setup.cfg} using the
- command-line options to \file{setup.py}
-\end{itemize}
-
-The basic syntax of the configuration file is simple:
-
-\begin{verbatim}
-[command]
-option=value
-...
-\end{verbatim}
-
-where \var{command} is one of the Distutils commands (e.g.
-\command{build\_py}, \command{install}), and \var{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{\#} 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 \longprogramopt{help} option, e.g.
-
-\begin{verbatim}
-> 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
-[...]
-\end{verbatim}
-
-Note that an option spelled \longprogramopt{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 \module{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
-\module{pkg.mod1} and \module{pkg.mod2}. You can always use the
-\longprogramopt{inplace} option on the command-line to ensure this:
-
-\begin{verbatim}
-python setup.py build_ext --inplace
-\end{verbatim}
-
-But this requires that you always specify the \command{build\_ext}
-command explicitly, and remember to provide \longprogramopt{inplace}.
-An easier way is to ``set and forget'' this option, by encoding it in
-\file{setup.cfg}, the configuration file for this distribution:
-
-\begin{verbatim}
-[build_ext]
-inplace=1
-\end{verbatim}
-
-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}:
-
-\begin{verbatim}
-[bdist_rpm]
-release = 1
-packager = Greg Ward <gward@python.net>
-doc_files = CHANGES.txt
- README.txt
- USAGE.txt
- doc/
- examples/
-\end{verbatim}
-
-Note that the \option{doc\_files} option is simply a
-whitespace-separated string split across multiple lines for readability.
-
-
-\begin{seealso}
- \seetitle[../inst/config-syntax.html]{Installing Python
- Modules}{More information on the configuration files is
- available in the manual for system administrators.}
-\end{seealso}
-
-
-\chapter{Creating a Source Distribution}
-\label{source-dist}
-
-As shown in section~\ref{simple-example}, you use the
-\command{sdist} command to create a source distribution. In the
-simplest case,
-
-\begin{verbatim}
-python setup.py sdist
-\end{verbatim}
-
-(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
-\longprogramopt{formats} option, for example:
-
-\begin{verbatim}
-python setup.py sdist --formats=gztar,zip
-\end{verbatim}
-
-to create a gzipped tarball and a zip file. The available formats are:
-
-\begin{tableiii}{l|l|c}{code}%
- {Format}{Description}{Notes}
- \lineiii{zip}{zip file (\file{.zip})}{(1),(3)}
- \lineiii{gztar}{gzip'ed tar file (\file{.tar.gz})}{(2),(4)}
- \lineiii{bztar}{bzip2'ed tar file (\file{.tar.bz2})}{(4)}
- \lineiii{ztar}{compressed tar file (\file{.tar.Z})}{(4)}
- \lineiii{tar}{tar file (\file{.tar})}{(4)}
-\end{tableiii}
-
-\noindent Notes:
-\begin{description}
-\item[(1)] default on Windows
-\item[(2)] default on \UNIX
-\item[(3)] requires either external \program{zip} utility or
- \module{zipfile} module (part of the standard Python library since
- Python~1.6)
-\item[(4)] requires external utilities: \program{tar} and possibly one
- of \program{gzip}, \program{bzip2}, or \program{compress}
-\end{description}
-
-
-
-\section{Specifying the files to distribute}
-\label{manifest}
-
-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:
-\begin{itemize}
-\item all Python source files implied by the \option{py\_modules} and
- \option{packages} options
-\item all C source files mentioned in the \option{ext\_modules} or
- \option{libraries} options (\XXX{getting C library sources currently
- broken---no \method{get_source_files()} method in \file{build_clib.py}!})
-\item scripts identified by the \option{scripts} option
-\item 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)
-\item \file{README.txt} (or \file{README}), \file{setup.py} (or whatever
- you called your setup script), and \file{setup.cfg}
-\end{itemize}
-
-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 \emph{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:
-
-\begin{verbatim}
-include *.txt
-recursive-include examples *.txt *.py
-prune examples/sample?/build
-\end{verbatim}
-
-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 \emph{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 \longprogramopt{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:
-\begin{itemize}
-\item all files in the Distutils ``build'' tree (default \file{build/})
-\item all files in directories named \file{RCS}, \file{CVS} or \file{.svn}
-\end{itemize}
-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
-\longprogramopt{no-defaults} option, and you can disable the standard
-exclude set with \longprogramopt{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:
-\begin{enumerate}
-\item 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})
-\item include \file{README.txt}, \file{setup.py}, and \file{setup.cfg}
- (standard files)
-\item include \file{test/test*.py} (standard files)
-\item include \file{*.txt} in the distribution root (this will find
- \file{README.txt} a second time, but such redundancies are weeded out
- later)
-\item include anything matching \file{*.txt} or \file{*.py} in the
- sub-tree under \file{examples},
-\item 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
- \code{prune} command in the manifest template comes after the
- \code{recursive-include} command
-\item exclude the entire \file{build} tree, and any \file{RCS},
- \file{CVS} and \file{.svn} directories
-\end{enumerate}
-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.
-
-
-\section{Manifest-related options}
-\label{manifest-options}
-
-The normal course of operations for the \command{sdist} command is as
-follows:
-\begin{itemize}
-\item if the manifest file, \file{MANIFEST} doesn't exist, read
- \file{MANIFEST.in} and create the manifest
-\item if neither \file{MANIFEST} nor \file{MANIFEST.in} exist, create a
- manifest with just the default file set
-\item 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}
-\item use the list of files now in \file{MANIFEST} (either just
- generated or read in) to create the source distribution archive(s)
-\end{itemize}
-There are a couple of options that modify this behaviour. First, use
-the \longprogramopt{no-defaults} and \longprogramopt{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:
-
-\begin{verbatim}
-python setup.py sdist --force-manifest
-\end{verbatim}
-
-Or, you might just want to (re)generate the manifest, but not create a
-source distribution:
-
-\begin{verbatim}
-python setup.py sdist --manifest-only
-\end{verbatim}
-
-\longprogramopt{manifest-only} implies \longprogramopt{force-manifest}.
-\programopt{-o} is a shortcut for \longprogramopt{manifest-only}, and
-\programopt{-f} for \longprogramopt{force-manifest}.
-
-
-\chapter{Creating Built Distributions}
-\label{built-dist}
-
-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 \emph{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:
-
-\begin{verbatim}
-python setup.py bdist
-\end{verbatim}
-
-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.\filevar{plat}.tar.gz}; unpacking this tarball
-from the right place installs the Distutils just as though you had
-downloaded the source distribution and run \code{python setup.py
- install}. (The ``right place'' is either the root of the filesystem or
-Python's \filevar{prefix} directory, depending on the options given to
-the \command{bdist\_dumb} command; the default is to make dumb
-distributions relative to \filevar{prefix}.)
-
-Obviously, for pure Python distributions, this isn't any simpler than
-just running \code{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 \longprogramopt{formats} option,
-similar to the \command{sdist} command, which you can use to select the
-types of built distribution to generate: for example,
-
-\begin{verbatim}
-python setup.py bdist --format=zip
-\end{verbatim}
-
-would, when run on a \UNIX{} system, create
-\file{Distutils-1.0.\filevar{plat}.zip}---again, this archive would be
-unpacked from the root directory to install the Distutils.
-
-The available formats for built distributions are:
-
-\begin{tableiii}{l|l|c}{code}%
- {Format}{Description}{Notes}
- \lineiii{gztar}{gzipped tar file (\file{.tar.gz})}{(1),(3)}
- \lineiii{ztar}{compressed tar file (\file{.tar.Z})}{(3)}
- \lineiii{tar}{tar file (\file{.tar})}{(3)}
- \lineiii{zip}{zip file (\file{.zip})}{(4)}
- \lineiii{rpm}{RPM}{(5)}
- \lineiii{pkgtool}{Solaris \program{pkgtool}}{}
- \lineiii{sdux}{HP-UX \program{swinstall}}{}
- \lineiii{rpm}{RPM}{(5)}
-% \lineiii{srpm}{source RPM}{(5) \XXX{to do!}}
- \lineiii{wininst}{self-extracting ZIP file for Windows}{(2),(4)}
-\end{tableiii}
-
-\noindent Notes:
-\begin{description}
-\item[(1)] default on \UNIX
-\item[(2)] default on Windows \XXX{to-do!}
-\item[(3)] requires external utilities: \program{tar} and possibly one
- of \program{gzip}, \program{bzip2}, or \program{compress}
-\item[(4)] requires either external \program{zip} utility or
- \module{zipfile} module (part of the standard Python library since
- Python~1.6)
-\item[(5)] requires external \program{rpm} utility, version 3.0.4 or
- better (use \code{rpm --version} to find out which version you have)
-\end{description}
-
-You don't have to use the \command{bdist} command with the
-\longprogramopt{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 (\code{tar}, \code{ztar}, \code{gztar}, and
-\code{zip}), and \command{bdist\_rpm} generates both binary and source
-RPMs. The \command{bdist} sub-commands, and the formats generated by
-each, are:
-
-\begin{tableii}{l|l}{command}%
- {Command}{Formats}
- \lineii{bdist\_dumb}{tar, ztar, gztar, zip}
- \lineii{bdist\_rpm}{rpm, srpm}
- \lineii{bdist\_wininst}{wininst}
-\end{tableii}
-
-The following sections give details on the individual \command{bdist\_*}
-commands.
-
-
-\section{Creating dumb built distributions}
-\label{creating-dumb}
-
-\XXX{Need to document absolute vs. prefix-relative packages here, but
- first I have to implement it!}
-
-
-\section{Creating RPM packages}
-\label{creating-rpms}
-
-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:
-
-\begin{verbatim}
-python setup.py bdist_rpm
-\end{verbatim}
-
-or the \command{bdist} command with the \longprogramopt{format} option:
-
-\begin{verbatim}
-python setup.py bdist --formats=rpm
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-python setup.py bdist_rpm --packager="John Doe <jdoe@example.org>" \
- bdist_wininst --target_version="2.0"
-\end{verbatim}
-
-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:
-
-\begin{tableii}{l|l}{textrm}%
- {RPM \file{.spec} file option or section}{Distutils setup script option}
- \lineii{Name}{\option{name}}
- \lineii{Summary (in preamble)}{\option{description}}
- \lineii{Version}{\option{version}}
- \lineii{Vendor}{\option{author} and \option{author\_email}, or \\&
- \option{maintainer} and \option{maintainer\_email}}
- \lineii{Copyright}{\option{licence}}
- \lineii{Url}{\option{url}}
- \lineii{\%description (section)}{\option{long\_description}}
-\end{tableii}
-
-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:
-
-\begin{tableiii}{l|l|l}{textrm}%
- {RPM \file{.spec} file option or section}%
- {\command{bdist\_rpm} option}%
- {default value}
- \lineiii{Release}{\option{release}}{``1''}
- \lineiii{Group}{\option{group}}{``Development/Libraries''}
- \lineiii{Vendor}{\option{vendor}}{(see above)}
- \lineiii{Packager}{\option{packager}}{(none)}
- \lineiii{Provides}{\option{provides}}{(none)}
- \lineiii{Requires}{\option{requires}}{(none)}
- \lineiii{Conflicts}{\option{conflicts}}{(none)}
- \lineiii{Obsoletes}{\option{obsoletes}}{(none)}
- \lineiii{Distribution}{\option{distribution\_name}}{(none)}
- \lineiii{BuildRequires}{\option{build\_requires}}{(none)}
- \lineiii{Icon}{\option{icon}}{(none)}
-\end{tableiii}
-
-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{\textasciitilde/.pydistutils.cfg}).
-
-There are three steps to building a binary RPM package, all of which are
-handled automatically by the Distutils:
-
-\begin{enumerate}
-\item 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)
-\item create the source RPM
-\item create the ``binary'' RPM (which may or may not contain binary
- code, depending on whether your module distribution contains Python
- extensions)
-\end{enumerate}
-
-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
-\longprogramopt{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 \longprogramopt{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.)
-
-
-\section{Creating Windows Installers}
-\label{creating-wininst}
-
-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:
-
-\begin{verbatim}
-python setup.py bdist_wininst
-\end{verbatim}
-
-or the \command{bdist} command with the \longprogramopt{formats} option:
-
-\begin{verbatim}
-python setup.py bdist --formats=wininst
-\end{verbatim}
-
-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
-\longprogramopt{no-target-compile} and/or the
-\longprogramopt{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 \longprogramopt{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 \longprogramopt{title} option.
-
-The installer file will be written to the ``distribution directory''
---- normally \file{dist/}, but customizable with the
-\longprogramopt{dist-dir} option.
-
-\subsection{The Postinstallation script}
-\label{postinstallation-script}
-
-Starting with Python 2.3, a postinstallation script can be specified
-which the \longprogramopt{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 \code{argv[1]} set to
-\programopt{-install}, and again at uninstallation time before the
-files are removed with \code{argv[1]} set to \programopt{-remove}.
-
-The installation script runs embedded in the windows installer, every
-output (\code{sys.stdout}, \code{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.
-
-\begin{funcdesc}{directory_created}{path}
-\funcline{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
- \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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. \var{csidl_string} must be one of the following
- strings:
-
-\begin{verbatim}
-"CSIDL_APPDATA"
-
-"CSIDL_COMMON_STARTMENU"
-"CSIDL_STARTMENU"
-
-"CSIDL_COMMON_DESKTOPDIRECTORY"
-"CSIDL_DESKTOPDIRECTORY"
-
-"CSIDL_COMMON_STARTUP"
-"CSIDL_STARTUP"
-
-"CSIDL_COMMON_PROGRAMS"
-"CSIDL_PROGRAMS"
-
-"CSIDL_FONTS"
-\end{verbatim}
-
- If the folder cannot be retrieved, \exception{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
- \cfunction{SHGetSpecialFolderPath()} function.
-\end{funcdesc}
-
-\begin{funcdesc}{create_shortcut}{target, description,
- filename\optional{,
- arguments\optional{,
- workdir\optional{,
- iconpath\optional{, iconindex}}}}}
- This function creates a shortcut.
- \var{target} is the path to the program to be started by the shortcut.
- \var{description} is the description of the shortcut.
- \var{filename} is the title of the shortcut that the user will see.
- \var{arguments} specifies the command line arguments, if any.
- \var{workdir} is the working directory for the program.
- \var{iconpath} is the file containing the icon for the shortcut,
- and \var{iconindex} is the index of the icon in the file
- \var{iconpath}. Again, for details consult the Microsoft
- documentation for the \class{IShellLink} interface.
-\end{funcdesc}
-
-\chapter{Registering with the Package Index}
-\label{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:
-
-\begin{verbatim}
-python setup.py register
-\end{verbatim}
-
-Distutils will respond with the following prompt:
-
-\begin{verbatim}
-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]:
-\end{verbatim}
-
-\noindent 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.
-
-\section{The .pypirc file}
-\label{pypirc}
-
-The format of the \file{.pypirc} file is formated as follows:
-
-\begin{verbatim}
-[server-login]
-repository: <repository-url>
-username: <username>
-password: <password>
-\end{verbatim}
-
-\var{repository} can be ommitted and defaults to
-\code{http://www.python.org/pypi}.
-
-\chapter{Uploading Packages to the Package Index}
-\label{package-upload}
-
-\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
-
-\begin{verbatim}
-python setup.py sdist bdist_wininst upload
-\end{verbatim}
-
-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 \longprogramopt{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 \longprogramopt{identity=\var{name}} option.
-
-Other \command{upload} options include
-\longprogramopt{repository=\var{url}} (which lets you override the
-repository setting from \file{\$HOME/.pypirc}), and
-\longprogramopt{show-response} (which displays the full response text
-from the PyPI server for help in debugging upload problems).
-
-\chapter{Examples}
-\label{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.
-
-\begin{seealso}
- \seelink{http://www.python.org/cgi-bin/moinmoin/DistutilsCookbook}
- {Distutils Cookbook}
- {Collection of recipes showing how to achieve more control
- over distutils.}
-\end{seealso}
-
-
-\section{Pure Python distribution (by module)}
-\label{pure-mod}
-
-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:
-\begin{verbatim}
-<root>/
- setup.py
- foo.py
-\end{verbatim}
-(In all diagrams in this section, \var{\textless root\textgreater}
-will refer to the distribution root directory.) A minimal setup script
-to describe this situation would be:
-\begin{verbatim}
-from distutils.core import setup
-setup(name='foo',
- version='1.0',
- py_modules=['foo'],
- )
-\end{verbatim}
-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 \module{foo} and
-\module{bar}, your setup might look like this:
-\begin{verbatim}
-<root>/
- setup.py
- foo.py
- bar.py
-\end{verbatim}
-and the setup script might be
-\begin{verbatim}
-from distutils.core import setup
-setup(name='foobar',
- version='1.0',
- py_modules=['foo', 'bar'],
- )
-\end{verbatim}
-
-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.
-
-
-\section{Pure Python distribution (by package)}
-\label{pure-pkg}
-
-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
-\begin{verbatim}
-from distutils.core import setup
-setup(name='foobar',
- version='1.0',
- packages=[''],
- )
-\end{verbatim}
-(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.:
-\begin{verbatim}
-<root>/
- setup.py
- src/ foo.py
- bar.py
-\end{verbatim}
-then you would still specify the root package, but you have to tell the
-Distutils where source files in the root package live:
-\begin{verbatim}
-from distutils.core import setup
-setup(name='foobar',
- version='1.0',
- package_dir={'': 'src'},
- packages=[''],
- )
-\end{verbatim}
-
-More typically, though, you will want to distribute multiple modules in
-the same package (or in sub-packages). For example, if the \module{foo}
-and \module{bar} modules belong in package \module{foobar}, one way to
-layout your source tree is
-\begin{verbatim}
-<root>/
- setup.py
- foobar/
- __init__.py
- foo.py
- bar.py
-\end{verbatim}
-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:
-\begin{verbatim}
-from distutils.core import setup
-setup(name='foobar',
- version='1.0',
- packages=['foobar'],
- )
-\end{verbatim}
-
-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
-\module{foobar} package:
-\begin{verbatim}
-<root>/
- setup.py
- src/
- __init__.py
- foo.py
- bar.py
-\end{verbatim}
-an appropriate setup script would be
-\begin{verbatim}
-from distutils.core import setup
-setup(name='foobar',
- version='1.0',
- package_dir={'foobar': 'src'},
- packages=['foobar'],
- )
-\end{verbatim}
-
-Or, you might put modules from your main package right in the
-distribution root:
-\begin{verbatim}
-<root>/
- setup.py
- __init__.py
- foo.py
- bar.py
-\end{verbatim}
-in which case your setup script would be
-\begin{verbatim}
-from distutils.core import setup
-setup(name='foobar',
- version='1.0',
- package_dir={'foobar': ''},
- packages=['foobar'],
- )
-\end{verbatim}
-(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 \emph{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:
-\begin{verbatim}
-<root>/
- setup.py
- foobar/
- __init__.py
- foo.py
- bar.py
- subfoo/
- __init__.py
- blah.py
-\end{verbatim}
-then the corresponding setup script would be
-\begin{verbatim}
-from distutils.core import setup
-setup(name='foobar',
- version='1.0',
- packages=['foobar', 'foobar.subfoo'],
- )
-\end{verbatim}
-(Again, the empty string in \option{package\_dir} stands for the current
-directory.)
-
-
-\section{Single extension module}
-\label{single-ext}
-
-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:
-\begin{verbatim}
-<root>/
- setup.py
- foo.c
-\end{verbatim}
-If the \module{foo} extension belongs in the root package, the setup
-script for this could be
-\begin{verbatim}
-from distutils.core import setup
-from distutils.extension import Extension
-setup(name='foobar',
- version='1.0',
- ext_modules=[Extension('foo', ['foo.c'])],
- )
-\end{verbatim}
-
-If the extension actually belongs in a package, say \module{foopkg},
-then
-
-With exactly the same source tree layout, this extension can be put in
-the \module{foopkg} package simply by changing the name of the
-extension:
-\begin{verbatim}
-from distutils.core import setup
-from distutils.extension import Extension
-setup(name='foobar',
- version='1.0',
- ext_modules=[Extension('foopkg.foo', ['foo.c'])],
- )
-\end{verbatim}
-
-
-%\section{Multiple extension modules}
-%\label{multiple-ext}
-
-
-%\section{Putting it all together}
-
-
-\chapter{Extending Distutils \label{extending}}
-
-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 \refmodule{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?}
-
-\section{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 \function{distutils.core.setup()} function use them:
-
-\begin{verbatim}
-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},
- ...)
-\end{verbatim}
-
-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
-\longprogramopt{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
-\code{[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 \module{distutils.command} package. When
-\file{setup.py} is run with the option
-\longprogramopt{command-packages} \programopt{distcmds,buildcmds},
-however, the packages \module{distutils.command}, \module{distcmds},
-and \module{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}.
-
-\section{Adding new distribution types}
-
-Commands that create distributions (files in the \file{dist/}
-directory) need to add \code{(\var{command}, \var{filename})} pairs to
-\code{self.distribution.dist_files} so that \command{upload} can
-upload it to PyPI. The \var{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.
-
-\chapter{Command Reference}
-\label{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}
-
-
-\section{Installing modules: the \protect\command{install} command family}
-\label{install-cmd}
-
-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}
-
-\subsection{\protect\command{install\_data}}
-\label{install-data-cmd}
-This command installs all data files provided with the distribution.
-
-\subsection{\protect\command{install\_scripts}}
-\label{install-scripts-cmd}
-This command installs all (Python) scripts in the distribution.
-
-
-%\subsection{Cleaning up: the \protect\command{clean} command}
-%\label{clean-cmd}
-
-
-\section{Creating a source distribution: the
- \protect\command{sdist} command}
-\label{sdist-cmd}
-
-
-\XXX{fragment moved down from above: needs context!}
-
-The manifest template commands are:
-
-\begin{tableii}{ll}{command}{Command}{Description}
- \lineii{include \var{pat1} \var{pat2} ... }
- {include all files matching any of the listed patterns}
- \lineii{exclude \var{pat1} \var{pat2} ... }
- {exclude all files matching any of the listed patterns}
- \lineii{recursive-include \var{dir} \var{pat1} \var{pat2} ... }
- {include all files under \var{dir} matching any of the listed patterns}
- \lineii{recursive-exclude \var{dir} \var{pat1} \var{pat2} ...}
- {exclude all files under \var{dir} matching any of the listed patterns}
- \lineii{global-include \var{pat1} \var{pat2} ...}
- {include all files anywhere in the source tree matching\\&
- any of the listed patterns}
- \lineii{global-exclude \var{pat1} \var{pat2} ...}
- {exclude all files anywhere in the source tree matching\\&
- any of the listed patterns}
- \lineii{prune \var{dir}}{exclude all files under \var{dir}}
- \lineii{graft \var{dir}}{include all files under \var{dir}}
-\end{tableii}
-
-The patterns here are \UNIX-style ``glob'' patterns: \code{*} matches any
-sequence of regular filename characters, \code{?} matches any single
-regular filename character, and \code{[\var{range}]} matches any of the
-characters in \var{range} (e.g., \code{a-z}, \code{a-zA-Z},
-\code{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.
-
-\XXX{Windows support not there yet}
-
-
-%\section{Creating a built distribution: the
-% \protect\command{bdist} command family}
-%\label{bdist-cmds}
-
-
-%\subsection{\protect\command{bdist}}
-
-%\subsection{\protect\command{bdist\_dumb}}
-
-%\subsection{\protect\command{bdist\_rpm}}
-
-%\subsection{\protect\command{bdist\_wininst}}
-
-
-\chapter{API Reference \label{api-reference}}
-
-\section{\module{distutils.core} --- Core Distutils functionality}
-
-\declaremodule{standard}{distutils.core}
-\modulesynopsis{The core Distutils functionality}
-
-The \module{distutils.core} module is the only module that needs to be
-installed to use the Distutils. It provides the \function{setup()} (which
-is called from the setup script). Indirectly provides the
-\class{distutils.dist.Distribution} and \class{distutils.cmd.Command} class.
-
-\begin{funcdesc}{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.
-
-\begin{tableiii}{c|l|l}{argument name}{argument name}{value}{type}
-\lineiii{name}{The name of the package}{a string}
-\lineiii{version}{The version number of the package}{See \refmodule{distutils.version}}
-\lineiii{description}{A single line describing the package}{a string}
-\lineiii{long_description}{Longer description of the package}{a string}
-\lineiii{author}{The name of the package author}{a string}
-\lineiii{author_email}{The email address of the package author}{a string}
-\lineiii{maintainer}{The name of the current maintainer, if different from the author}{a string}
-\lineiii{maintainer_email}{The email address of the current maintainer, if different from the author}{}
-\lineiii{url}{A URL for the package (homepage)}{a URL}
-\lineiii{download_url}{A URL to download the package}{a URL}
-\lineiii{packages}{A list of Python packages that distutils will manipulate}{a list of strings}
-\lineiii{py_modules}{A list of Python modules that distutils will manipulate}{a list of strings}
-\lineiii{scripts}{A list of standalone script files to be built and installed}{a list of strings}
-\lineiii{ext_modules}{A list of Python extensions to be built}{A list of
-instances of \class{distutils.core.Extension}}
-\lineiii{classifiers}{A list of categories for the package}{The list of available categorizations is at \url{http://cheeseshop.python.org/pypi?:action=list_classifiers}.}
-\lineiii{distclass}{the \class{Distribution} class to use}{A subclass of \class{distutils.core.Distribution}}
-% What on earth is the use case for script_name?
-\lineiii{script_name}{The name of the setup.py script - defaults to \code{sys.argv[0]}}{a string}
-\lineiii{script_args}{Arguments to supply to the setup script}{a list of strings}
-\lineiii{options}{default options for the setup script}{a string}
-\lineiii{license}{The license for the package}{}
-\lineiii{keywords}{Descriptive meta-data. See \pep{314}}{}
-\lineiii{platforms}{}{}
-\lineiii{cmdclass}{A mapping of command names to \class{Command} subclasses}{a dictionary}
-\end{tableiii}
-
-\end{funcdesc}
-
-\begin{funcdesc}{run_setup}{script_name\optional{, script_args=\code{None}, stop_after=\code{'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 \var{script} to \function{setup()}), or
-the contents of the config files or command-line.
-
-\var{script_name} is a file that will be read and run with \function{exec()}
-\code{sys.argv[0]} will be replaced with \var{script} for the duration of the
-call. \var{script_args} is a list of strings; if supplied,
-\code{sys.argv[1:]} will be replaced by \var{script_args} for the duration
-of the call.
-
-\var{stop_after} tells \function{setup()} when to stop processing; possible
-values:
-
-\begin{tableii}{c|l}{value}{value}{description}
-\lineii{init}{Stop after the \class{Distribution} instance has been created
-and populated with the keyword arguments to \function{setup()}}
-\lineii{config}{Stop after config files have been parsed (and their data
-stored in the \class{Distribution} instance)}
-\lineii{commandline}{Stop after the command-line (\code{sys.argv[1:]} or
-\var{script_args}) have been parsed (and the data stored in the
-\class{Distribution} instance.)}
-\lineii{run}{Stop after all commands have been run (the same as
-if \function{setup()} had been called in the usual way). This is the default
-value.}
-\end{tableii}
-\end{funcdesc}
-
-In addition, the \module{distutils.core} module exposed a number of
-classes that live elsewhere.
-
-\begin{itemize}
-\item \class{Extension} from \refmodule{distutils.extension}
-\item \class{Command} from \refmodule{distutils.cmd}
-\item \class{Distribution} from \refmodule{distutils.dist}
-\end{itemize}
-
-A short description of each of these follows, but see the relevant
-module for the full reference.
-
-\begin{classdesc*}{Extension}
-
-The Extension class describes a single C or \Cpp extension module in a
-setup script. It accepts the following keyword arguments in its
-constructor
-
-\begin{tableiii}{c|l|l}{argument name}{argument name}{value}{type}
-\lineiii{name}{the full name of the extension, including any packages
---- ie. \emph{not} a filename or pathname, but Python dotted name}{string}
-\lineiii{sources}{list of source filenames, relative to the distribution
-root (where the setup script lives), in \UNIX{} form (slash-separated) for
-portability. Source files may be C, \Cpp, SWIG (.i), platform-specific
-resource files, or whatever else is recognized by the \command{build_ext}
-command as source for a Python extension.}{string}
-\lineiii{include_dirs}{list of directories to search for C/\Cpp{} header
-files (in \UNIX{} form for portability)}{string}
-\lineiii{define_macros}{list of macros to define; each macro is defined
-using a 2-tuple, where 'value' is either the string to define it to or
-\code{None} to define it without a particular value (equivalent of
-\code{\#define FOO} in source or \programopt{-DFOO} on \UNIX{} C
-compiler command line) }{ (string,string)
-tuple or (name,\code{None}) }
-\lineiii{undef_macros}{list of macros to undefine explicitly}{string}
-\lineiii{library_dirs}{list of directories to search for C/\Cpp{} libraries
-at link time }{string}
-\lineiii{libraries}{list of library names (not filenames or paths) to
-link against }{string}
-\lineiii{runtime_library_dirs}{list of directories to search for C/\Cpp{}
-libraries at run time (for shared extensions, this is when the extension
-is loaded)}{string}
-\lineiii{extra_objects}{list of extra files to link with (eg. object
-files not implied by 'sources', static library that must be explicitly
-specified, binary resource files, etc.)}{string}
-\lineiii{extra_compile_args}{any extra platform- and 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.}{string}
-\lineiii{extra_link_args}{any extra platform- and 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'.}{string}
-\lineiii{export_symbols}{list of symbols to be exported from a shared
-extension. Not used on all platforms, and not generally necessary for
-Python extensions, which typically export exactly one symbol: \code{init} +
-extension_name. }{string}
-\lineiii{depends}{list of files that the extension depends on }{string}
-\lineiii{language}{extension language (i.e. \code{'c'}, \code{'c++'},
-\code{'objc'}). Will be detected from the source extensions if not provided.
-}{string}
-\end{tableiii}
-\end{classdesc*}
-
-\begin{classdesc*}{Distribution}
-A \class{Distribution} describes how to build, install and package up a
-Python software package.
-
-See the \function{setup()} function for a list of keyword arguments accepted
-by the Distribution constructor. \function{setup()} creates a Distribution
-instance.
-\end{classdesc*}
-
-\begin{classdesc*}{Command}
-A \class{Command} class (or rather, an instance of one of its subclasses)
-implement a single distutils command.
-\end{classdesc*}
-
-
-\section{\module{distutils.ccompiler} --- CCompiler base class}
-\declaremodule{standard}{distutils.ccompiler}
-\modulesynopsis{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.
-
-\begin{funcdesc}{gen_lib_options}{compiler, library_dirs, runtime_library_dirs, libraries}
-Generate linker options for searching library directories and
-linking with specific libraries. \var{libraries} and \var{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).
-\end{funcdesc}
-
-\begin{funcdesc}{gen_preprocess_options}{macros, include_dirs}
-Generate C pre-processor options (\programopt{-D}, \programopt{-U},
-\programopt{-I}) as used by at least
-two types of compilers: the typical \UNIX{} compiler and Visual \Cpp.
-\var{macros} is the usual thing, a list of 1- or 2-tuples, where
-\code{(\var{name},)} means undefine (\programopt{-U}) macro \var{name},
-and \code{(\var{name}, \var{value})} means define (\programopt{-D})
-macro \var{name} to \var{value}. \var{include_dirs} is just a list of
-directory names to be added to the header file search path (\programopt{-I}).
-Returns a list of command-line options suitable for either \UNIX{} compilers
-or Visual \Cpp.
-\end{funcdesc}
-
-\begin{funcdesc}{get_default_compiler}{osname, platform}
-Determine the default compiler to use for the given platform.
-
-\var{osname} should be one of the standard Python OS names (i.e.\ the
-ones returned by \code{os.name}) and \var{platform} the common value
-returned by \code{sys.platform} for the platform in question.
-
-The default values are \code{os.name} and \code{sys.platform} in case the
-parameters are not given.
-\end{funcdesc}
-
-\begin{funcdesc}{new_compiler}{plat=\code{None}, compiler=\code{None}, verbose=\code{0}, dry_run=\code{0}, force=\code{0}}
-Factory function to generate an instance of some CCompiler subclass
-for the supplied platform/compiler combination. \var{plat} defaults
-to \code{os.name} (eg. \code{'posix'}, \code{'nt'}), and \var{compiler}
-defaults to the default compiler for that platform. Currently only
-\code{'posix'} and \code{'nt'} are supported, and the default
-compilers are ``traditional \UNIX{} interface'' (\class{UnixCCompiler}
-class) and Visual \Cpp (\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 \var{compiler}, \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{show_compilers}{}
-Print list of available compilers (used by the
-\longprogramopt{help-compiler} options to \command{build},
-\command{build_ext}, \command{build_clib}).
-\end{funcdesc}
-
-\begin{classdesc}{CCompiler}{\optional{verbose=\code{0}, dry_run=\code{0}, force=\code{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 \var{verbose} (show verbose output), \var{dry_run}
-(don't actually execute the steps) and \var{force} (rebuild
-everything, regardless of dependencies). All of these flags default to
-\code{0} (off). Note that you probably don't want to instantiate
-\class{CCompiler} or one of its subclasses directly - use the
-\function{distutils.CCompiler.new_compiler()} factory function
-instead.
-
-The following methods allow you to manually alter compiler options for
-the instance of the Compiler class.
-
-\begin{methoddesc}{add_include_dir}{dir}
-Add \var{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
-\method{add_include_dir()}.
-\end{methoddesc}
-
-\begin{methoddesc}{set_include_dirs}{dirs}
-Set the list of directories that will be searched to \var{dirs} (a
-list of strings). Overrides any preceding calls to
-\method{add_include_dir()}; subsequent calls to
-\method{add_include_dir()} add to the list passed to
-\method{set_include_dirs()}. This does not affect any list of
-standard include directories that the compiler may search by default.
-\end{methoddesc}
-
-\begin{methoddesc}{add_library}{libname}
-
-Add \var{libname} to the list of libraries that will be included in
-all links driven by this compiler object. Note that \var{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 \method{add_library()} and/or
-\method{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.
-\end{methoddesc}
-
-\begin{methoddesc}{set_libraries}{libnames}
-Set the list of libraries to be included in all links driven by
-this compiler object to \var{libnames} (a list of strings). This does
-not affect any standard system libraries that the linker may
-include by default.
-\end{methoddesc}
-
-\begin{methoddesc}{add_library_dir}{dir}
-Add \var{dir} to the list of directories that will be searched for
-libraries specified to \method{add_library()} and
-\method{set_libraries()}. The linker will be instructed to search for
-libraries in the order they are supplied to \method{add_library_dir()}
-and/or \method{set_library_dirs()}.
-\end{methoddesc}
-
-\begin{methoddesc}{set_library_dirs}{dirs}
-Set the list of library search directories to \var{dirs} (a list of
-strings). This does not affect any standard library search path
-that the linker may search by default.
-\end{methoddesc}
-
-\begin{methoddesc}{add_runtime_library_dir}{dir}
-Add \var{dir} to the list of directories that will be searched for
-shared libraries at runtime.
-\end{methoddesc}
-
-\begin{methoddesc}{set_runtime_library_dirs}{dirs}
-Set the list of directories to search for shared libraries at
-runtime to \var{dirs} (a list of strings). This does not affect any
-standard search path that the runtime linker may search by
-default.
-\end{methoddesc}
-
-\begin{methoddesc}{define_macro}{name\optional{, value=\code{None}}}
-Define a preprocessor macro for all compilations driven by this
-compiler object. The optional parameter \var{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?)
-\end{methoddesc}
-
-\begin{methoddesc}{undefine_macro}{name}
-Undefine a preprocessor macro for all compilations driven by
-this compiler object. If the same macro is defined by
-\method{define_macro()} and undefined by \method{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 \method{compile()}), then that
-takes precedence.
-\end{methoddesc}
-
-\begin{methoddesc}{add_link_object}{object}
-Add \var{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.
-\end{methoddesc}
-
-\begin{methoddesc}{set_link_objects}{objects}
-Set the list of object files (or analogues) to be included in
-every link to \var{objects}. This does not affect any standard object
-files that the linker may include by default (such as system
-libraries).
-\end{methoddesc}
-
-The following methods implement methods for autodetection of compiler
-options, providing some functionality similar to GNU \program{autoconf}.
-
-\begin{methoddesc}{detect_language}{sources}
-Detect the language of a given file, or list of files. Uses the
-instance attributes \member{language_map} (a dictionary), and
-\member{language_order} (a list) to do the job.
-\end{methoddesc}
-
-\begin{methoddesc}{find_library_file}{dirs, lib\optional{, debug=\code{0}}}
-Search the specified list of directories for a static or shared
-library file \var{lib} and return the full path to that file. If
-\var{debug} is true, look for a debugging version (if that makes sense on
-the current platform). Return \code{None} if \var{lib} wasn't found in any of
-the specified directories.
-\end{methoddesc}
-
-\begin{methoddesc}{has_function}{funcname \optional{, includes=\code{None}, include_dirs=\code{None}, libraries=\code{None}, library_dirs=\code{None}}}
-Return a boolean indicating whether \var{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.
-\end{methoddesc}
-
-\begin{methoddesc}{library_dir_option}{dir}
-Return the compiler option to add \var{dir} to the list of
-directories searched for libraries.
-\end{methoddesc}
-
-\begin{methoddesc}{library_option}{lib}
-Return the compiler option to add \var{dir} to the list of libraries
-linked into the shared library or executable.
-\end{methoddesc}
-
-\begin{methoddesc}{runtime_library_dir_option}{dir}
-Return the compiler option to add \var{dir} to the list of
-directories searched for runtime libraries.
-\end{methoddesc}
-
-\begin{methoddesc}{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:
-
-\begin{tableii}{l|l}{attribute}{attribute}{description}
-\lineii{compiler}{the C/\Cpp{} compiler}
-\lineii{linker_so}{linker used to create shared objects and libraries}
-\lineii{linker_exe}{linker used to create binary executables}
-\lineii{archiver}{static library creator}
-\end{tableii}
-
-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
-\function{distutils.util.split_quoted()}.)
-\end{methoddesc}
-
-The following methods invoke stages in the build process.
-
-\begin{methoddesc}{compile}{sources\optional{, output_dir=\code{None}, macros=\code{None}, include_dirs=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, depends=\code{None}}}
-Compile one or more source files. Generates object files (e.g.
-transforms a \file{.c} file to a \file{.o} file.)
-
-\var{sources} must be a list of filenames, most likely C/\Cpp
-files, but in reality anything that can be handled by a
-particular compiler and compiler class (eg. \class{MSVCCompiler} can
-handle resource files in \var{sources}). Return a list of object
-filenames, one per source filename in \var{sources}. Depending on
-the implementation, not all source files will necessarily be
-compiled, but all corresponding object filenames will be
-returned.
-
-If \var{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
-\var{output_dir} is \var{build}, then it would compile to
-\file{build/foo/bar.o}.
-
-\var{macros}, if given, must be a list of macro definitions. A macro
-definition is either a \code{(\var{name}, \var{value})} 2-tuple or a
-\code{(\var{name},)} 1-tuple.
-The former defines a macro; if the value is \code{None}, the macro is
-defined without an explicit value. The 1-tuple case undefines a
-macro. Later definitions/redefinitions/undefinitions take
-precedence.
-
-\var{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.
-
-\var{debug} is a boolean; if true, the compiler will be instructed to
-output debug symbols in (or alongside) the object file(s).
-
-\var{extra_preargs} and \var{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.
-
-\var{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 \exception{CompileError} on failure.
-\end{methoddesc}
-
-\begin{methoddesc}{create_static_lib}{objects, output_libname\optional{, output_dir=\code{None}, debug=\code{0}, target_lang=\code{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 \var{objects}, the extra object files supplied to
-\method{add_link_object()} and/or \method{set_link_objects()}, the libraries
-supplied to \method{add_library()} and/or \method{set_libraries()}, and the
-libraries supplied as \var{libraries} (if any).
-
-\var{output_libname} should be a library name, not a filename; the
-filename will be inferred from the library name. \var{output_dir} is
-the directory where the library file will be put. XXX defaults to what?
-
-\var{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 \var{debug} flag is included here
-just for consistency).
-
-\var{target_lang} is the target language for which the given objects
-are being compiled. This allows specific linkage time treatment of
-certain languages.
-
-Raises \exception{LibError} on failure.
-\end{methoddesc}
-
-\begin{methoddesc}{link}{target_desc, objects, output_filename\optional{, output_dir=\code{None}, libraries=\code{None}, library_dirs=\code{None}, runtime_library_dirs=\code{None}, export_symbols=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, build_temp=\code{None}, target_lang=\code{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 \var{objects}. \var{output_filename} should be a filename. If
-\var{output_dir} is supplied, \var{output_filename} is relative to it
-(i.e. \var{output_filename} can provide directory components if
-needed).
-
-\var{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. \var{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.
-
-\var{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 \method{add_library_dir()} and/or
-\method{set_library_dirs()}. \var{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.)
-
-\var{export_symbols} is a list of symbols that the shared library will
-export. (This appears to be relevant only on Windows.)
-
-\var{debug} is as for \method{compile()} and \method{create_static_lib()},
-with the slight distinction that it actually matters on most platforms (as
-opposed to \method{create_static_lib()}, which includes a \var{debug} flag
-mostly for form's sake).
-
-\var{extra_preargs} and \var{extra_postargs} are as for \method{compile()}
-(except of course that they supply command-line arguments for the
-particular linker being used).
-
-\var{target_lang} is the target language for which the given objects
-are being compiled. This allows specific linkage time treatment of
-certain languages.
-
-Raises \exception{LinkError} on failure.
-\end{methoddesc}
-
-\begin{methoddesc}{link_executable}{objects, output_progname\optional{, output_dir=\code{None}, libraries=\code{None}, library_dirs=\code{None}, runtime_library_dirs=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, target_lang=\code{None}}}
-Link an executable.
-\var{output_progname} is the name of the file executable,
-while \var{objects} are a list of object filenames to link in. Other arguments
-are as for the \method{link} method.
-\end{methoddesc}
-
-\begin{methoddesc}{link_shared_lib}{objects, output_libname\optional{, output_dir=\code{None}, libraries=\code{None}, library_dirs=\code{None}, runtime_library_dirs=\code{None}, export_symbols=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, build_temp=\code{None}, target_lang=\code{None}}}
-Link a shared library. \var{output_libname} is the name of the output
-library, while \var{objects} is a list of object filenames to link in.
-Other arguments are as for the \method{link} method.
-\end{methoddesc}
-
-\begin{methoddesc}{link_shared_object}{objects, output_filename\optional{, output_dir=\code{None}, libraries=\code{None}, library_dirs=\code{None}, runtime_library_dirs=\code{None}, export_symbols=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, build_temp=\code{None}, target_lang=\code{None}}}
-Link a shared object. \var{output_filename} is the name of the shared object
-that will be created, while \var{objects} is a list of object filenames
-to link in. Other arguments are as for the \method{link} method.
-\end{methoddesc}
-
-\begin{methoddesc}{preprocess}{source\optional{, output_file=\code{None}, macros=\code{None}, include_dirs=\code{None}, extra_preargs=\code{None}, extra_postargs=\code{None}}}
-Preprocess a single C/\Cpp{} source file, named in \var{source}.
-Output will be written to file named \var{output_file}, or \var{stdout} if
-\var{output_file} not supplied. \var{macros} is a list of macro
-definitions as for \method{compile()}, which will augment the macros set
-with \method{define_macro()} and \method{undefine_macro()}.
-\var{include_dirs} is a list of directory names that will be added to the
-default list, in the same way as \method{add_include_dir()}.
-
-Raises \exception{PreprocessError} on failure.
-\end{methoddesc}
-
-The following utility methods are defined by the \class{CCompiler} class,
-for use by the various concrete subclasses.
-
-\begin{methoddesc}{executable_filename}{basename\optional{, strip_dir=\code{0}, output_dir=\code{''}}}
-Returns the filename of the executable for the given \var{basename}.
-Typically for non-Windows platforms this is the same as the basename,
-while Windows will get a \file{.exe} added.
-\end{methoddesc}
-
-\begin{methoddesc}{library_filename}{libname\optional{, lib_type=\code{'static'}, strip_dir=\code{0}, output_dir=\code{''}}}
-Returns the filename for the given library name on the current platform.
-On \UNIX{} a library with \var{lib_type} of \code{'static'} will typically
-be of the form \file{liblibname.a}, while a \var{lib_type} of \code{'dynamic'}
-will be of the form \file{liblibname.so}.
-\end{methoddesc}
-
-\begin{methoddesc}{object_filenames}{source_filenames\optional{, strip_dir=\code{0}, output_dir=\code{''}}}
-Returns the name of the object files for the given source files.
-\var{source_filenames} should be a list of filenames.
-\end{methoddesc}
-
-\begin{methoddesc}{shared_object_filename}{basename\optional{, strip_dir=\code{0}, output_dir=\code{''}}}
-Returns the name of a shared object file for the given file name \var{basename}.
-\end{methoddesc}
-
-\begin{methoddesc}{execute}{func, args\optional{, msg=\code{None}, level=\code{1}}}
-Invokes \function{distutils.util.execute()} This method invokes a
-Python function \var{func} with the given arguments \var{args}, after
-logging and taking into account the \var{dry_run} flag. XXX see also.
-\end{methoddesc}
-
-\begin{methoddesc}{spawn}{cmd}
-Invokes \function{distutils.util.spawn()}. This invokes an external
-process to run the given command. XXX see also.
-\end{methoddesc}
-
-\begin{methoddesc}{mkpath}{name\optional{, mode=\code{511}}}
-
-Invokes \function{distutils.dir_util.mkpath()}. This creates a directory
-and any missing ancestor directories. XXX see also.
-\end{methoddesc}
-
-\begin{methoddesc}{move_file}{src, dst}
-Invokes \method{distutils.file_util.move_file()}. Renames \var{src} to
-\var{dst}. XXX see also.
-\end{methoddesc}
-
-\begin{methoddesc}{announce}{msg\optional{, level=\code{1}}}
-Write a message using \function{distutils.log.debug()}. XXX see also.
-\end{methoddesc}
-
-\begin{methoddesc}{warn}{msg}
-Write a warning message \var{msg} to standard error.
-\end{methoddesc}
-
-\begin{methoddesc}{debug_print}{msg}
-If the \var{debug} flag is set on this \class{CCompiler} instance, print
-\var{msg} to standard output, otherwise do nothing.
-\end{methoddesc}
-
-\end{classdesc}
-
-%\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.
-
-\section{\module{distutils.unixccompiler} --- Unix C Compiler}
-\declaremodule{standard}{distutils.unixccompiler}
-\modulesynopsis{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:
-
-\begin{itemize}
-\item macros defined with \programopt{-D\var{name}\optional{=value}}
-\item macros undefined with \programopt{-U\var{name}}
-\item include search directories specified with
- \programopt{-I\var{dir}}
-\item libraries specified with \programopt{-l\var{lib}}
-\item library search directories specified with \programopt{-L\var{dir}}
-\item compile handled by \program{cc} (or similar) executable with
- \programopt{-c} option: compiles \file{.c} to \file{.o}
-\item link static library handled by \program{ar} command (possibly
- with \program{ranlib})
-\item link shared library handled by \program{cc} \programopt{-shared}
-\end{itemize}
-
-\section{\module{distutils.msvccompiler} --- Microsoft Compiler}
-\declaremodule{standard}{distutils.msvccompiler}
-\modulesynopsis{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
-\var{DISTUTILS\_USE\_SDK} and \var{MSSdk} must be both set. \var{MSSdk}
-indicates that the current environment has been setup by the SDK's
-\code{SetEnv.Cmd} script, or that the environment variables had been
-registered when the SDK was installed; \var{DISTUTILS\_USE\_SDK} indicates
-that the distutils user has made an explicit choice to override the
-compiler selection by \class{MSVCCompiler}.
-
-\section{\module{distutils.bcppcompiler} --- Borland Compiler}
-\declaremodule{standard}{distutils.bcppcompiler}
-This module provides \class{BorlandCCompiler}, an subclass of the abstract \class{CCompiler} class for the Borland \Cpp{} compiler.
-
-\section{\module{distutils.cygwincompiler} --- Cygwin Compiler}
-\declaremodule{standard}{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).
-
-\section{\module{distutils.emxccompiler} --- OS/2 EMX Compiler}
-\declaremodule{standard}{distutils.emxccompiler}
-\modulesynopsis{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.
-
-\section{\module{distutils.mwerkscompiler} --- Metrowerks CodeWarrior support}
-\declaremodule{standard}{distutils.mwerkscompiler}
-\modulesynopsis{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.
-
-\section{\module{distutils.archive_util} ---
- Archiving utilities}
-\declaremodule[distutils.archiveutil]{standard}{distutils.archive_util}
-\modulesynopsis{Utility functions for creating archive files (tarballs, zip files, ...)}
-
-This module provides a few functions for creating archive files, such as
-tarballs or zipfiles.
-
-\begin{funcdesc}{make_archive}{base_name, format\optional{, root_dir=\code{None}, base_dir=\code{None}, verbose=\code{0}, dry_run=\code{0}}}
-Create an archive file (eg. \code{zip} or \code{tar}). \var{base_name}
-is the name of the file to create, minus any format-specific extension;
-\var{format} is the archive format: one of \code{zip}, \code{tar},
-\code{ztar}, or \code{gztar}.
-\var{root_dir} is a directory that will be the root directory of the
-archive; ie. we typically \code{chdir} into \var{root_dir} before
-creating the archive. \var{base_dir} is the directory where we start
-archiving from; ie. \var{base_dir} will be the common prefix of all files and
-directories in the archive. \var{root_dir} and \var{base_dir} both default
-to the current directory. Returns the name of the archive file.
-
-\warning{This should be changed to support bz2 files}
-\end{funcdesc}
-
-\begin{funcdesc}{make_tarball}{base_name, base_dir\optional{, compress=\code{'gzip'}, verbose=\code{0}, dry_run=\code{0}}}'Create an (optional compressed) archive as a tar file from all files in and under \var{base_dir}. \var{compress} must be \code{'gzip'} (the default),
-\code{'compress'}, \code{'bzip2'}, or \code{None}. Both \program{tar}
-and the compression utility named by \var{compress} must be on the
-default program search path, so this is probably \UNIX-specific. The
-output tar file will be named \file{\var{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 \module{tarfile} module.}
-\end{funcdesc}
-
-\begin{funcdesc}{make_zipfile}{base_name, base_dir\optional{, verbose=\code{0}, dry_run=\code{0}}}
-Create a zip file from all files in and under \var{base_dir}. The output
-zip file will be named \var{base_dir} + \file{.zip}. Uses either the
-\module{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 \exception{DistutilsExecError}.
-Returns the name of the output zip file.
-\end{funcdesc}
-
-\section{\module{distutils.dep_util} --- Dependency checking}
-\declaremodule[distutils.deputil]{standard}{distutils.dep_util}
-\modulesynopsis{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.
-
-\begin{funcdesc}{newer}{source, target}
-Return true if \var{source} exists and is more recently modified than
-\var{target}, or if \var{source} exists and \var{target} doesn't.
-Return false if both exist and \var{target} is the same age or newer
-than \var{source}.
-Raise \exception{DistutilsFileError} if \var{source} does not exist.
-\end{funcdesc}
-
-\begin{funcdesc}{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 (\var{sources},
-\var{targets}) where source is newer than target, according to the semantics
-of \function{newer()}
-%% equivalent to a listcomp...
-\end{funcdesc}
-
-\begin{funcdesc}{newer_group}{sources, target\optional{, missing=\code{'error'}}}
-Return true if \var{target} is out-of-date with respect to any file
-listed in \var{sources} In other words, if \var{target} exists and is newer
-than every file in \var{sources}, return false; otherwise return true.
-\var{missing} controls what we do when a source file is missing; the
-default (\code{'error'}) is to blow up with an \exception{OSError} from
-inside \function{os.stat()};
-if it is \code{'ignore'}, we silently drop any missing source files; if it is
-\code{'newer'}, any missing source files make us assume that \var{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).
-\end{funcdesc}
-
-\section{\module{distutils.dir_util} --- Directory tree operations}
-\declaremodule[distutils.dirutil]{standard}{distutils.dir_util}
-\modulesynopsis{Utility functions for operating on directories and directory trees}
-
-This module provides functions for operating on directories and trees
-of directories.
-
-\begin{funcdesc}{mkpath}{name\optional{, mode=\code{0777}, verbose=\code{0}, dry_run=\code{0}}}
-Create a directory and any missing ancestor directories. If the
-directory already exists (or if \var{name} is the empty string, which
-means the current directory, which of course exists), then do
-nothing. Raise \exception{DistutilsFileError} if unable to create some
-directory along the way (eg. some sub-path exists, but is a file
-rather than a directory). If \var{verbose} is true, print a one-line
-summary of each mkdir to stdout. Return the list of directories
-actually created.
-\end{funcdesc}
-
-\begin{funcdesc}{create_tree}{base_dir, files\optional{, mode=\code{0777}, verbose=\code{0}, dry_run=\code{0}}}
-Create all the empty directories under \var{base_dir} needed to
-put \var{files} there. \var{base_dir} is just the a name of a directory
-which doesn't necessarily exist yet; \var{files} is a list of filenames
-to be interpreted relative to \var{base_dir}. \var{base_dir} + the
-directory portion of every file in \var{files} will be created if it
-doesn't already exist. \var{mode}, \var{verbose} and \var{dry_run} flags
-are as for \function{mkpath()}.
-\end{funcdesc}
-
-\begin{funcdesc}{copy_tree}{src, dst\optional{preserve_mode=\code{1}, preserve_times=\code{1}, preserve_symlinks=\code{0}, update=\code{0}, verbose=\code{0}, dry_run=\code{0}}}
-Copy an entire directory tree \var{src} to a new location \var{dst}. Both
-\var{src} and \var{dst} must be directory names. If \var{src} is not a
-directory, raise \exception{DistutilsFileError}. If \var{dst} does
-not exist, it is created with \function{mkpath()}. The end result of the
-copy is that every file in \var{src} is copied to \var{dst}, and
-directories under \var{src} are recursively copied to \var{dst}.
-Return the list of files that were copied or might have been copied,
-using their output name. The return value is unaffected by \var{update}
-or \var{dry_run}: it is simply the list of all files under \var{src},
-with the names changed to be under \var{dst}.
-
-\var{preserve_mode} and \var{preserve_times} are the same as for
-\function{copy_file} in \refmodule[distutils.fileutil]{distutils.file_util};
-note that they only apply to regular files, not to directories. If
-\var{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. \var{update} and
-\var{verbose} are the same as for
-\function{copy_file()}.
-\end{funcdesc}
-
-\begin{funcdesc}{remove_tree}{directory\optional{verbose=\code{0}, dry_run=\code{0}}}
-Recursively remove \var{directory} and all files and directories underneath
-it. Any errors are ignored (apart from being reported to \code{sys.stdout} if
-\var{verbose} is true).
-\end{funcdesc}
-
-\XXX{Some of this could be replaced with the shutil module?}
-
-\section{\module{distutils.file_util} --- Single file operations}
-\declaremodule[distutils.fileutil]{standard}{distutils.file_util}
-\modulesynopsis{Utility functions for operating on single files}
-
-This module contains some utility functions for operating on individual files.
-
-\begin{funcdesc}{copy_file}{src, dst\optional{preserve_mode=\code{1}, preserve_times=\code{1}, update=\code{0}, link=\code{None}, verbose=\code{0}, dry_run=\code{0}}}
-Copy file \var{src} to \var{dst}. If \var{dst} is a directory, then
-\var{src} is copied there with the same name; otherwise, it must be a
-filename. (If the file exists, it will be ruthlessly clobbered.) If
-\var{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 \var{preserve_times} is true (the default), the last-modified
-and last-access times are copied as well. If \var{update} is true,
-\var{src} will only be copied if \var{dst} does not exist, or if
-\var{dst} does exist but is older than \var{src}.
-
-\var{link} allows you to make hard links (using \function{os.link}) or
-symbolic links (using \function{os.symlink}) instead of copying: set it
-to \code{'hard'} or \code{'sym'}; if it is \code{None} (the default),
-files are copied. Don't set \var{link} on systems that don't support
-it: \function{copy_file()} doesn't check if hard or symbolic linking is
-available. It uses \function{_copy_file_contents()} to copy file contents.
-
-Return a tuple \samp{(dest_name, copied)}: \var{dest_name} is the actual
-name of the output file, and \var{copied} is true if the file was copied
-(or would have been copied, if \var{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)).
-\end{funcdesc}
-
-\begin{funcdesc}{move_file}{src, dst\optional{verbose, dry_run}}
-Move file \var{src} to \var{dst}. If \var{dst} is a directory, the file will
-be moved into it with the same name; otherwise, \var{src} is just renamed
-to \var{dst}. Returns the new full name of the file.
-\warning{Handles cross-device moves on \UNIX{} using \function{copy_file()}.
-What about other systems???}
-\end{funcdesc}
-
-\begin{funcdesc}{write_file}{filename, contents}
-Create a file called \var{filename} and write \var{contents} (a
-sequence of strings without line terminators) to it.
-\end{funcdesc}
-
-\section{\module{distutils.util} --- Miscellaneous other utility functions}
-\declaremodule{standard}{distutils.util}
-\modulesynopsis{Miscellaneous other utility functions}
-
-This module contains other assorted bits and pieces that don't fit into
-any other utility module.
-
-\begin{funcdesc}{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:
-\begin{itemize}
-\item \code{linux-i586}
-\item \code{linux-alpha}
-\item \code{solaris-2.6-sun4u}
-\item \code{irix-5.3}
-\item \code{irix64-6.2}
-\end{itemize}
-
-For non-\POSIX{} platforms, currently just returns \code{sys.platform}.
-% XXX isn't this also provided by some other non-distutils module?
-\end{funcdesc}
-
-\begin{funcdesc}{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
-\exception{ValueError} on non-\UNIX-ish systems if \var{pathname} either
-starts or ends with a slash.
-\end{funcdesc}
-
-\begin{funcdesc}{change_root}{new_root, pathname}
-Return \var{pathname} with \var{new_root} prepended. If \var{pathname} is
-relative, this is equivalent to \samp{os.path.join(new_root,pathname)}
-Otherwise, it requires making \var{pathname} relative and then joining the
-two, which is tricky on DOS/Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{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:
-\begin{itemize}
-\item \envvar{HOME} - user's home directory (\UNIX{} only)
-\item \envvar{PLAT} - description of the current platform, including
- hardware and OS (see \function{get_platform()})
-\end{itemize}
-\end{funcdesc}
-
-\begin{funcdesc}{subst_vars}{s, local_vars}
-Perform shell/Perl-style variable substitution on \var{s}. Every
-occurrence of \code{\$} followed by a name is considered a variable, and
-variable is substituted by the value found in the \var{local_vars}
-dictionary, or in \code{os.environ} if it's not in \var{local_vars}.
-\var{os.environ} is first checked/augmented to guarantee that it contains
-certain values: see \function{check_environ()}. Raise \exception{ValueError}
-for any variables not found in either \var{local_vars} or \code{os.environ}.
-
-Note that this is not a fully-fledged string interpolation function. A
-valid \code{\$variable} can consist only of upper and lower case letters,
-numbers and an underscore. No \{ \} or ( ) style quoting is available.
-\end{funcdesc}
-
-\begin{funcdesc}{grok_environment_error}{exc\optional{, prefix=\samp{'error: '}}}
-Generate a useful error message from an \exception{EnvironmentError}
-(\exception{IOError} or \exception{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 \function{rename()} or
-\function{link()}). Returns the error message as a string prefixed
-with \var{prefix}.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{execute}{func, args\optional{, msg=\code{None}, verbose=\code{0}, dry_run=\code{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 \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{strtobool}{val}
-Convert a string representation of truth to true (1) or false (0).
-
-True values are \code{y}, \code{yes}, \code{t}, \code{true}, \code{on}
-and \code{1}; false values are \code{n}, \code{no}, \code{f}, \code{false},
-\code{off} and \code{0}. Raises \exception{ValueError} if \var{val}
-is anything else.
-\end{funcdesc}
-
-\begin{funcdesc}{byte_compile}{py_files\optional{,
- optimize=\code{0}, force=\code{0},
- prefix=\code{None}, base_dir=\code{None},
- verbose=\code{1}, dry_run=\code{0},
- direct=\code{None}}}
-Byte-compile a collection of Python source files to either \file{.pyc}
-or \file{.pyo} files in the same directory. \var{py_files} is a list of files
-to compile; any files that don't end in \file{.py} are silently skipped.
-\var{optimize} must be one of the following:
-\begin{itemize}
-\item \code{0} - don't optimize (generate \file{.pyc})
-\item \code{1} - normal optimization (like \samp{python -O})
-\item \code{2} - extra optimization (like \samp{python -OO})
-\end{itemize}
-
-If \var{force} is true, all files are recompiled regardless of
-timestamps.
-
-The source filename encoded in each bytecode file defaults to the
-filenames listed in \var{py_files}; you can modify these with \var{prefix} and
-\var{basedir}. \var{prefix} is a string that will be stripped off of each
-source filename, and \var{base_dir} is a directory name that will be
-prepended (after \var{prefix} is stripped). You can supply either or both
-(or neither) of \var{prefix} and \var{base_dir}, as you wish.
-
-If \var{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 \module{py_compile} module, or indirectly by writing a
-temporary script and executing it. Normally, you should let
-\function{byte_compile()} figure out to use direct compilation or not (see
-the source for details). The \var{direct} flag is used by the script
-generated in indirect mode; unless you know what you're doing, leave
-it set to \code{None}.
-\end{funcdesc}
-
-\begin{funcdesc}{rfc822_escape}{header}
-Return a version of \var{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
-\end{funcdesc}
-
-%\subsection{Distutils objects}
-
-\section{\module{distutils.dist} --- The Distribution class}
-\declaremodule{standard}{distutils.dist}
-\modulesynopsis{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.
-
-
-\section{\module{distutils.extension} --- The Extension class}
-\declaremodule{standard}{distutils.extension}
-\modulesynopsis{Provides the Extension class, used to describe
- C/\Cpp{} extension modules in setup scripts}
-
-This module provides the \class{Extension} class, used to describe
-C/\Cpp{} extension modules in setup scripts.
-
-%\subsection{Ungrouped modules}
-%The following haven't been moved into a more appropriate section yet.
-
-\section{\module{distutils.debug} --- Distutils debug mode}
-\declaremodule{standard}{distutils.debug}
-\modulesynopsis{Provides the debug flag for distutils}
-
-This module provides the DEBUG flag.
-
-\section{\module{distutils.errors} --- Distutils exceptions}
-\declaremodule{standard}{distutils.errors}
-\modulesynopsis{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 \samp{from ... import *} mode; it only exports
-symbols whose names start with \code{Distutils} and end with \code{Error}.
-
-\section{\module{distutils.fancy_getopt}
- --- Wrapper around the standard getopt module}
-\declaremodule[distutils.fancygetopt]{standard}{distutils.fancy_getopt}
-\modulesynopsis{Additional \module{getopt} functionality}
-
-This module provides a wrapper around the standard \module{getopt}
-module that provides the following additional features:
-
-\begin{itemize}
-\item short and long options are tied together
-\item options have help strings, so \function{fancy_getopt} could potentially
-create a complete usage summary
-\item options set attributes of a passed-in object
-\item boolean options can have ``negative aliases'' --- eg. if
-\longprogramopt{quiet} is the ``negative alias'' of
-\longprogramopt{verbose}, then \longprogramopt{quiet} on the command
-line sets \var{verbose} to false.
-
-\end{itemize}
-
-\XXX{Should be replaced with \module{optik} (which is also now
-known as \module{optparse} in Python 2.3 and later).}
-
-\begin{funcdesc}{fancy_getopt}{options, negative_opt, object, args}
-Wrapper function. \var{options} is a list of
-\samp{(long_option, short_option, help_string)} 3-tuples as described in the
-constructor for \class{FancyGetopt}. \var{negative_opt} should be a dictionary
-mapping option names to option names, both the key and value should be in the
-\var{options} list. \var{object} is an object which will be used to store
-values (see the \method{getopt()} method of the \class{FancyGetopt} class).
-\var{args} is the argument list. Will use \code{sys.argv[1:]} if you
-pass \code{None} as \var{args}.
-\end{funcdesc}
-
-\begin{funcdesc}{wrap_text}{text, width}
-Wraps \var{text} to less than \var{width} wide.
-
-\warning{Should be replaced with \module{textwrap} (which is available
-in Python 2.3 and later).}
-\end{funcdesc}
-
-\begin{classdesc}{FancyGetopt}{\optional{option_table=\code{None}}}
-The option_table is a list of 3-tuples: \samp{(long_option,
-short_option, help_string)}
-
-If an option takes an argument, its \var{long_option} should have \code{'='}
-appended; \var{short_option} should just be a single character, no \code{':'}
-in any case. \var{short_option} should be \code{None} if a \var{long_option}
-doesn't have a corresponding \var{short_option}. All option tuples must have
-long options.
-\end{classdesc}
-
-The \class{FancyGetopt} class provides the following methods:
-
-\begin{methoddesc}{getopt}{\optional{args=\code{None}, object=\code{None}}}
-Parse command-line options in args. Store as attributes on \var{object}.
-
-If \var{args} is \code{None} or not supplied, uses \code{sys.argv[1:]}. If
-\var{object} is \code{None} or not supplied, creates a new \class{OptionDummy}
-instance, stores option values there, and returns a tuple \samp{(args,
-object)}. If \var{object} is supplied, it is modified in place and
-\function{getopt()} just returns \var{args}; in both cases, the returned
-\var{args} is a modified copy of the passed-in \var{args} list, which
-is left untouched.
-% and args returned are?
-\end{methoddesc}
-
-\begin{methoddesc}{get_option_order}{}
-Returns the list of \samp{(option, value)} tuples processed by the
-previous run of \method{getopt()} Raises \exception{RuntimeError} if
-\method{getopt()} hasn't been called yet.
-\end{methoddesc}
-
-\begin{methoddesc}{generate_help}{\optional{header=\code{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 \var{header} at the top of the help.
-\end{methoddesc}
-
-\section{\module{distutils.filelist} --- The FileList class}
-\declaremodule{standard}{distutils.filelist}
-\modulesynopsis{The \class{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.
-
-
-\section{\module{distutils.log} --- Simple PEP 282-style logging}
-\declaremodule{standard}{distutils.log}
-\modulesynopsis{A simple logging mechanism, \pep{282}-style}
-
-\warning{Should be replaced with standard \module{logging} module.}
-
-%\subsubsection{\module{} --- }
-%\declaremodule{standard}{distutils.magic}
-%\modulesynopsis{ }
-
-
-\section{\module{distutils.spawn} --- Spawn a sub-process}
-\declaremodule{standard}{distutils.spawn}
-\modulesynopsis{Provides the spawn() function}
-
-This module provides the \function{spawn()} function, a front-end to
-various platform-specific functions for launching another program in a
-sub-process.
-Also provides \function{find_executable()} to search the path for a given
-executable name.
-
-
-\input{sysconfig}
-
-
-\section{\module{distutils.text_file} --- The TextFile class}
-\declaremodule[distutils.textfile]{standard}{distutils.text_file}
-\modulesynopsis{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.
-
-\begin{classdesc}{TextFile}{\optional{filename=\code{None}, file=\code{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 \code{\#}
-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 \method{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 \method{unreadline()} for implementing line-at-a-time lookahead.
-
-\class{TextFile} instances are create with either \var{filename}, \var{file},
-or both. \exception{RuntimeError} is raised if both are \code{None}.
-\var{filename} should be a string, and \var{file} a file object (or
-something that provides \method{readline()} and \method{close()}
-methods). It is recommended that you supply at least \var{filename},
-so that \class{TextFile} can include it in warning messages. If
-\var{file} is not supplied, \class{TextFile} creates its own using the
-\function{open()} built-in function.
-
-The options are all boolean, and affect the values returned by
-\method{readline()}
-
-\begin{tableiii}{c|l|l}{option name}{option name}{description}{default}
-\lineiii{strip_comments}{
-strip from \character{\#} to end-of-line, as well as any whitespace
-leading up to the \character{\#}---unless it is escaped by a backslash}
-{true}
-\lineiii{lstrip_ws}{
-strip leading whitespace from each line before returning it}
-{false}
-\lineiii{rstrip_ws}{
-strip trailing whitespace (including line terminator!) from
-each line before returning it.}
-{true}
-\lineiii{skip_blanks}{
-skip lines that are empty *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 \var{skip_blanks} is true.)}
-{true}
-\lineiii{join_lines}{
-if a backslash is the last 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.}
-{false}
-\lineiii{collapse_join}{
-strip leading whitespace from lines that are joined to their
-predecessor; only matters if \samp{(join_lines and not lstrip_ws)}}
-{false}
-\end{tableiii}
-
-Note that since \var{rstrip_ws} can strip the trailing newline, the
-semantics of \method{readline()} must differ from those of the builtin file
-object's \method{readline()} method! In particular, \method{readline()}
-returns \code{None} for end-of-file: an empty string might just be a
-blank line (or an all-whitespace line), if \var{rstrip_ws} is true
-but \var{skip_blanks} is not.
-
-\begin{methoddesc}{open}{filename}
-Open a new file \var{filename}. This overrides any \var{file} or
-\var{filename} constructor arguments.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
-Close the current file and forget everything we know about it (including
-the filename and the current line number).
-\end{methoddesc}
-
-\begin{methoddesc}{warn}{msg\optional{,line=\code{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 \samp{"lines 3-5"}. If \var{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.
-\end{methoddesc}
-
-\begin{methoddesc}{readline}{}
-Read and return a single logical line from the current file (or
-from an internal buffer if lines have previously been ``unread''
-with \method{unreadline()}). If the \var{join_lines} option
-is true, this may involve reading multiple physical lines
-concatenated into a single string. Updates the current line number,
-so calling \method{warn()} after \method{readline()} emits a warning
-about the physical line(s) just read. Returns \code{None} on end-of-file,
-since the empty string can occur if \var{rstrip_ws} is true but
-\var{strip_blanks} is not.
-\end{methoddesc}
-\begin{methoddesc}{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.
-\end{methoddesc}
-\begin{methoddesc}{unreadline}{line}
-Push \var{line} (a string) onto an internal buffer that will be
-checked by future \method{readline()} calls. Handy for implementing
-a parser with line-at-a-time lookahead. Note that lines that are ``unread''
-with \method{unreadline} are not subsequently re-cleansed (whitespace
-stripped, or whatever) when read with \method{readline}. If multiple
-calls are made to \method{unreadline} before a call to \method{readline},
-the lines will be returned most in most recent first order.
-\end{methoddesc}
-
-\end{classdesc}
-
-
-\section{\module{distutils.version} --- Version number classes}
-\declaremodule{standard}{distutils.version}
-\modulesynopsis{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.
-
-\section{\module{distutils.cmd} --- Abstract base class for Distutils commands}
-\declaremodule{standard}{distutils.cmd}
-\modulesynopsis{This module provides the abstract base class Command. This
-class is subclassed by the modules in the \refmodule{distutils.command}
-subpackage. }
-
-This module supplies the abstract base class \class{Command}.
-
-\begin{classdesc}{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 \var{options}. The
-options are declared in \method{initialize_options()} and defined
-(given their final values) in \method{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 \method{finalize_options()}. The body of the
-subroutine, where it does all its work based on the values of its
-options, is the \method{run()} method, which must also be implemented
-by every command class.
-
-The class constructor takes a single argument \var{dist}, a
-\class{Distribution} instance.
-\end{classdesc}
-
-
-\section{\module{distutils.command} --- Individual Distutils commands}
-\declaremodule{standard}{distutils.command}
-\modulesynopsis{This subpackage contains one module for each standard Distutils command.}
-
-%\subsubsection{Individual Distutils commands}
-
-% todo
-
-\section{\module{distutils.command.bdist} --- Build a binary installer}
-\declaremodule{standard}{distutils.command.bdist}
-\modulesynopsis{Build a binary installer for a package}
-
-% todo
-
-\section{\module{distutils.command.bdist_packager} --- Abstract base class for packagers}
-\declaremodule[distutils.command.bdistpackager]{standard}{distutils.command.bdist_packager}
-\modulesynopsis{Abstract base class for packagers}
-
-% todo
-
-\section{\module{distutils.command.bdist_dumb} --- Build a ``dumb'' installer}
-\declaremodule[distutils.command.bdistdumb]{standard}{distutils.command.bdist_dumb}
-\modulesynopsis{Build a ``dumb'' installer - a simple archive of files}
-
-% todo
-
-\section{\module{distutils.command.bdist_msi} --- Build a Microsoft Installer binary package}
-\declaremodule[distutils.command.bdistmsi]{standard}{distutils.command.bdist_msi}
-\modulesynopsis{Build a binary distribution as a Windows MSI file}
-
-% todo
-
-\section{\module{distutils.command.bdist_rpm} --- Build a binary distribution as a Redhat RPM and SRPM}
-\declaremodule[distutils.command.bdistrpm]{standard}{distutils.command.bdist_rpm}
-\modulesynopsis{Build a binary distribution as a Redhat RPM and SRPM}
-
-% todo
-
-\section{\module{distutils.command.bdist_wininst} --- Build a Windows installer}
-\declaremodule[distutils.command.bdistwininst]{standard}{distutils.command.bdist_wininst}
-\modulesynopsis{Build a Windows installer}
-
-% todo
-
-\section{\module{distutils.command.sdist} --- Build a source distribution}
-\declaremodule{standard}{distutils.command.sdist}
-\modulesynopsis{Build a source distribution}
-
-% todo
-
-\section{\module{distutils.command.build} --- Build all files of a package}
-\declaremodule{standard}{distutils.command.build}
-\modulesynopsis{Build all files of a package}
-
-% todo
-
-\section{\module{distutils.command.build_clib} --- Build any C libraries in a package}
-\declaremodule[distutils.command.buildclib]{standard}{distutils.command.build_clib}
-\modulesynopsis{Build any C libraries in a package}
-
-% todo
-
-\section{\module{distutils.command.build_ext} --- Build any extensions in a package}
-\declaremodule[distutils.command.buildext]{standard}{distutils.command.build_ext}
-\modulesynopsis{Build any extensions in a package}
-
-% todo
-
-\section{\module{distutils.command.build_py} --- Build the .py/.pyc files of a package}
-\declaremodule[distutils.command.buildpy]{standard}{distutils.command.build_py}
-\modulesynopsis{Build the .py/.pyc files of a package}
-
-% todo
-
-\section{\module{distutils.command.build_scripts} --- Build the scripts of a package}
-\declaremodule[distutils.command.buildscripts]{standard}{distutils.command.build_scripts}
-\modulesynopsis{Build the scripts of a package}
-
-% todo
-
-\section{\module{distutils.command.clean} --- Clean a package build area}
-\declaremodule{standard}{distutils.command.clean}
-\modulesynopsis{Clean a package build area}
-
-% todo
-
-\section{\module{distutils.command.config} --- Perform package configuration}
-\declaremodule{standard}{distutils.command.config}
-\modulesynopsis{Perform package configuration}
-
-% todo
-
-\section{\module{distutils.command.install} --- Install a package}
-\declaremodule{standard}{distutils.command.install}
-\modulesynopsis{Install a package}
-
-% todo
-
-\section{\module{distutils.command.install_data}
- --- Install data files from a package}
-\declaremodule[distutils.command.installdata]{standard}{distutils.command.install_data}
-\modulesynopsis{Install data files from a package}
-
-% todo
-
-\section{\module{distutils.command.install_headers}
- --- Install C/\Cpp{} header files from a package}
-\declaremodule[distutils.command.installheaders]{standard}{distutils.command.install_headers}
-\modulesynopsis{Install C/\Cpp{} header files from a package}
-
-% todo
-
-\section{\module{distutils.command.install_lib}
- --- Install library files from a package}
-\declaremodule[distutils.command.installlib]{standard}{distutils.command.install_lib}
-\modulesynopsis{Install library files from a package}
-
-% todo
-
-\section{\module{distutils.command.install_scripts}
- --- Install script files from a package}
-\declaremodule[distutils.command.installscripts]{standard}{distutils.command.install_scripts}
-\modulesynopsis{Install script files from a package}
-
-% todo
-
-\section{\module{distutils.command.register}
- --- Register a module with the Python Package Index}
-\declaremodule{standard}{distutils.command.register}
-\modulesynopsis{Register a module with the Python Package Index}
-
-The \code{register} command registers the package with the Python Package
-Index. This is described in more detail in \pep{301}.
-% todo
-
-\section{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 \module{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 \code{peel_banana} (so that users
-can run \samp{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.
-
-\begin{methoddesc}[Command]{initialize_options()}
-Set 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, \method{initialize_options()} implementations
-are just a bunch of \samp{self.foo = None} assignments.
-\end{methoddesc}
-
-\begin{methoddesc}[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
-\var{foo} depends on \var{bar}, then it is safe to set \var{foo} from
-\var{bar} as long as \var{foo} still has the same value it was assigned in
-\method{initialize_options()}.
-\end{methoddesc}
-\begin{methoddesc}[Command]{run}{}
-A command's raison d'etre: carry out the action it exists to
-perform, controlled by the options initialized in
-\method{initialize_options()}, customized by other commands, the setup
-script, the command-line, and config files, and finalized in
-\method{finalize_options()}. All terminal output and filesystem
-interaction should be done by \method{run()}.
-\end{methoddesc}
-
-\var{sub_commands} formalizes the notion of a ``family'' of commands,
-eg. \code{install} as the parent with sub-commands \code{install_lib},
-\code{install_headers}, etc. The parent of a family of commands
-defines \var{sub_commands} as a class attribute; it's a list of
-2-tuples \samp{(command_name, predicate)}, with \var{command_name} a string
-and \var{predicate} an unbound method, a string or None.
-\var{predicate} is a method of the parent command that
-determines whether the corresponding command is applicable in the
-current situation. (Eg. we \code{install_headers} is only applicable if
-we have any C header files to install.) If \var{predicate} is None,
-that command is always applicable.
-
-\var{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.
-
-%
-% The ugly "%begin{latexonly}" pseudo-environments are really just to
-% keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
-% not really valuable.
-%
-
-%begin{latexonly}
-\renewcommand{\indexname}{Module Index}
-%end{latexonly}
-\input{moddist.ind} % Module Index
-
-%begin{latexonly}
-\renewcommand{\indexname}{Index}
-%end{latexonly}
-\input{dist.ind} % Index
-
-\end{document}
diff --git a/Doc/dist/sysconfig.tex b/Doc/dist/sysconfig.tex
deleted file mode 100644
index db28e55..0000000
--- a/Doc/dist/sysconfig.tex
+++ /dev/null
@@ -1,113 +0,0 @@
-\section{\module{distutils.sysconfig} ---
- System configuration information}
-
-\declaremodule{standard}{distutils.sysconfig}
-\modulesynopsis{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 \module{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 \module{distutils} package.
-
-
-\begin{datadesc}{PREFIX}
- The result of \code{os.path.normpath(sys.prefix)}.
-\end{datadesc}
-
-\begin{datadesc}{EXEC_PREFIX}
- The result of \code{os.path.normpath(sys.exec_prefix)}.
-\end{datadesc}
-
-\begin{funcdesc}{get_config_var}{name}
- Return the value of a single variable. This is equivalent to
- \code{get_config_vars().get(\var{name})}.
-\end{funcdesc}
-
-\begin{funcdesc}{get_config_vars}{\moreargs}
- 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, \code{None}
- will be included for that variable.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{get_python_inc}{\optional{plat_specific\optional{, prefix}}}
- Return the directory for either the general or platform-dependent C
- include files. If \var{plat_specific} is true, the
- platform-dependent include directory is returned; if false or
- omitted, the platform-independent directory is returned. If
- \var{prefix} is given, it is used as either the prefix instead of
- \constant{PREFIX}, or as the exec-prefix instead of
- \constant{EXEC_PREFIX} if \var{plat_specific} is true.
-\end{funcdesc}
-
-\begin{funcdesc}{get_python_lib}{\optional{plat_specific\optional{,
- standard_lib\optional{, prefix}}}}
- Return the directory for either the general or platform-dependent
- library installation. If \var{plat_specific} is true, the
- platform-dependent include directory is returned; if false or
- omitted, the platform-independent directory is returned. If
- \var{prefix} is given, it is used as either the prefix instead of
- \constant{PREFIX}, or as the exec-prefix instead of
- \constant{EXEC_PREFIX} if \var{plat_specific} is true. If
- \var{standard_lib} is true, the directory for the standard library
- is returned rather than the directory for the installation of
- third-party extensions.
-\end{funcdesc}
-
-
-The following function is only intended for use within the
-\module{distutils} package.
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-
-This function is even more special-purpose, and should only be used
-from Python's own build procedures.
-
-\begin{funcdesc}{set_python_build}{}
- Inform the \module{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.
-\end{funcdesc}
diff --git a/Doc/doc/doc.tex b/Doc/doc/doc.tex
deleted file mode 100644
index 1d0f279..0000000
--- a/Doc/doc/doc.tex
+++ /dev/null
@@ -1,2129 +0,0 @@
-\documentclass{howto}
-\usepackage{ltxmarkup}
-
-\title{Documenting Python}
-
-\makeindex
-
-\input{boilerplate}
-
-% Now override the stuff that includes author information;
-% Guido did *not* write this one!
-
-\author{Fred L. Drake, Jr.}
-\authoraddress{
- PythonLabs \\
- Email: \email{fdrake@acm.org}
-}
-
-
-\begin{document}
-
-\maketitle
-
-\begin{abstract}
-\noindent
-The Python language has a substantial body of
-documentation, much of it contributed by various authors. The markup
-used for the Python documentation is based on \LaTeX{} and requires a
-significant set of macros written specifically for documenting Python.
-This document describes the macros introduced to support Python
-documentation and how they should be used to support a wide range of
-output formats.
-
-This document describes the document classes and special markup used
-in the Python documentation. Authors may use this guide, in
-conjunction with the template files provided with the
-distribution, to create or maintain whole documents or sections.
-
-If you're interested in contributing to Python's documentation,
-there's no need to learn \LaTeX{} if you're not so inclined; plain
-text contributions are more than welcome as well.
-\end{abstract}
-
-\tableofcontents
-
-
-\section{Introduction \label{intro}}
-
- 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. All of these forms of input from
- the community have proved useful during the time I've been involved
- in maintaining the documentation.
-
- 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.
-
- The material in this guide is intended to assist authors using the
- Python documentation tools. It includes information on the source
- distribution of the standard documentation, a discussion of the
- document types, reference material on the markup defined in the
- document classes, a list of the external tools needed for processing
- documents, and reference material on the tools provided with the
- documentation resources. At the end, there is also a section
- discussing future directions for the Python documentation and where
- to turn for more information.
-
- If your interest is in contributing to the Python documentation, but
- you don't have the time or inclination to learn \LaTeX{} 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!
-
-\section{Directory Structure \label{directories}}
-
- The source distribution for the standard Python documentation
- contains a large number of directories. While third-party documents
- do not need to be placed into this structure or need to be placed
- within a similar structure, it can be helpful to know where to look
- for examples and tools when developing new documents using the
- Python documentation tools. This section describes this directory
- structure.
-
- The documentation sources are usually placed within the Python
- source distribution as the top-level directory \file{Doc/}, but
- are not dependent on the Python source distribution in any way.
-
- The \file{Doc/} directory contains a few files and several
- subdirectories. The files are mostly self-explanatory, including a
- \file{README} and a \file{Makefile}. The directories fall into
- three categories:
-
- \begin{definitions}
- \term{Document Sources}
- The \LaTeX{} sources for each document are placed in a
- separate directory. These directories are given short
- names which vaguely indicate the document in each:
-
- \begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Document Title}
- \lineii{api/}
- {\citetitle[../api/api.html]{The Python/C API}}
- \lineii{dist/}
- {\citetitle[../dist/dist.html]{Distributing Python Modules}}
- \lineii{doc/}
- {\citetitle[../doc/doc.html]{Documenting Python}}
- \lineii{ext/}
- {\citetitle[../ext/ext.html]
- {Extending and Embedding the Python Interpreter}}
- \lineii{inst/}
- {\citetitle[../inst/inst.html]{Installing Python Modules}}
- \lineii{lib/}
- {\citetitle[../lib/lib.html]{Python Library Reference}}
- \lineii{mac/}
- {\citetitle[../mac/mac.html]{Macintosh Module Reference}}
- \lineii{ref/}
- {\citetitle[../ref/ref.html]{Python Reference Manual}}
- \lineii{tut/}
- {\citetitle[../tut/tut.html]{Python Tutorial}}
- \lineii{whatsnew/}
- {\citetitle[../whatsnew/whatsnew24.html]
- {What's New in Python \shortversion}}
- \end{tableii}
-
- \term{Format-Specific Output}
- Most output formats have a directory which contains a
- \file{Makefile} which controls the generation of that format
- and provides storage for the formatted documents. The only
- variations within this category are the Portable Document
- Format (PDF) and PostScript versions are placed in the
- directories \file{paper-a4/} and \file{paper-letter/} (this
- causes all the temporary files created by \LaTeX{} to be kept
- in the same place for each paper size, where they can be more
- easily ignored).
-
- \begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Output Formats}
- \lineii{html/}{HTML output}
- \lineii{info/}{GNU info output}
- \lineii{isilo/}{\ulink{iSilo}{http://www.isilo.com/}
- documents (for Palm OS devices)}
- \lineii{paper-a4/}{PDF and PostScript, A4 paper}
- \lineii{paper-letter/}{PDF and PostScript, US-Letter paper}
- \end{tableii}
-
- \term{Supplemental Files}
- Some additional directories are used to store supplemental
- files used for the various processes. Directories are
- included for the shared \LaTeX{} document classes, the
- \LaTeX2HTML support, template files for various document
- components, and the scripts used to perform various steps in
- the formatting processes.
-
- \begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Contents}
- \lineii{commontex/}{Document content shared among documents}
- \lineii{perl/} {Support for \LaTeX2HTML processing}
- \lineii{templates/}{Example files for source documents}
- \lineii{texinputs/}{Style implementation for \LaTeX}
- \lineii{tools/} {Custom processing scripts}
- \end{tableii}
-
- \end{definitions}
-
-
-\section{Style Guide \label{style-guide}}
-
- The Python documentation should follow the \citetitle
- [http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf]
- {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 if necessary.
-
- Footnotes are generally discouraged due to the pain of using
- footnotes in the HTML conversion of documents. Footnotes 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 \LaTeX{} markup
- should appear something like this:
-
-\begin{verbatim}
-This sentence has a footnote reference.%
- \footnote{This is the footnote text.}
-\end{verbatim}
-
- 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. Many of these were assigned \LaTeX{} macros
- at some point in the distant past, and these macros lived on long
- past their usefulness. In the current markup, 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:
-
- \begin{description}
- \item[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.
-
- \item[\POSIX]
- The name assigned to a particular group of standards. This is
- always uppercase. Use the macro \macro{POSIX} to represent this
- name.
-
- \item[Python]
- The name of our favorite programming language is always
- capitalized.
-
- \item[Unicode]
- The name of a character set and matching encoding. This is
- always written capitalized.
-
- \item[\UNIX]
- The name of the operating system developed at AT\&T Bell Labs
- in the early 1970s. Use the macro \macro{UNIX} to use this
- name.
- \end{description}
-
-
-\section{\LaTeX{} Primer \label{latex-primer}}
-
- This section is a brief introduction to \LaTeX{} concepts and
- syntax, to provide authors enough information to author documents
- productively without having to become ``\TeX{}nicians.'' This does
- not teach everything needed to know about writing \LaTeX{} for
- Python documentation; many of the standard ``environments'' are not
- described here (though you will learn how to mark something as an
- environment).
-
- Perhaps the most important concept to keep in mind while marking up
- Python documentation is that while \TeX{} is unstructured, \LaTeX{} was
- designed as a layer on top of \TeX{} which specifically supports
- structured markup. The Python-specific markup is intended to extend
- the structure provided by standard \LaTeX{} document classes to
- support additional information specific to Python.
-
- \LaTeX{} documents contain two parts: the preamble and the body.
- The preamble is used to specify certain metadata about the document
- itself, such as the title, the list of authors, the date, and the
- \emph{class} the document belongs to. Additional information used
- to control index generation and the use of bibliographic databases
- can also be placed in the preamble. For most authors, the preamble
- can be most easily created by copying it from an existing document
- and modifying a few key pieces of information.
-
- The \dfn{class} of a document is used to place a document within a
- broad category of documents and set some fundamental formatting
- properties. For Python documentation, two classes are used: the
- \code{manual} class and the \code{howto} class. These classes also
- define the additional markup used to document Python concepts and
- structures. Specific information about these classes is provided in
- section \ref{classes}, ``Document Classes,'' below. The first thing
- in the preamble is the declaration of the document's class.
-
- After the class declaration, a number of \emph{macros} are used to
- provide further information about the document and setup any
- additional markup that is needed. No output is generated from the
- preamble; it is an error to include free text in the preamble
- because it would cause output.
-
- The document body follows the preamble. This contains all the
- printed components of the document marked up structurally. Generic
- \LaTeX{} structures include hierarchical sections, numbered and
- bulleted lists, and special structures for the document abstract and
- indexes.
-
- \subsection{Syntax \label{latex-syntax}}
-
- There are some things that an author of Python documentation needs
- to know about \LaTeX{} syntax.
-
- A \dfn{comment} is started by the ``percent'' character
- (\character{\%}) and continues through the end of the line
- \emph{and all leading whitespace on the following line}. This is
- a little different from any programming language I know of, so an
- example is in order:
-
-\begin{verbatim}
-This is text.% comment
- This is more text. % another comment
-Still more text.
-\end{verbatim}
-
- The first non-comment character following the first comment is the
- letter \character{T} on the second line; the leading whitespace on
- that line is consumed as part of the first comment. This means
- that there is no space between the first and second sentences, so
- the period and letter \character{T} will be directly adjacent in
- the typeset document.
-
- Note also that though the first non-comment character after the
- second comment is the letter \character{S}, there is whitespace
- preceding the comment, so the two sentences are separated as
- expected.
-
- A \dfn{group} is an enclosure for a collection of text and
- commands which encloses the formatting context and constrains the
- scope of any changes to that context made by commands within the
- group. Groups can be nested hierarchically. The formatting
- context includes the font and the definition of additional macros
- (or overrides of macros defined in outer groups). Syntactically,
- groups are enclosed in braces:
-
-\begin{verbatim}
-{text in a group}
-\end{verbatim}
-
- An alternate syntax for a group using brackets, \code{[...]}, is
- used by macros and environment constructors which take optional
- parameters; brackets do not normally hold syntactic significance.
- A degenerate group, containing only one atomic bit of content,
- does not need to have an explicit group, unless it is required to
- avoid ambiguity. Since Python tends toward the explicit, groups
- are also made explicit in the documentation markup.
-
- Groups are used only sparingly in the Python documentation, except
- for their use in marking parameters to macros and environments.
-
- A \dfn{macro} is usually a simple construct which is identified by
- name and can take some number of parameters. In normal \LaTeX{}
- usage, one of these can be optional. The markup is introduced
- using the backslash character (\character{\e}), and the name is
- given by alphabetic characters (no digits, hyphens, or
- underscores). Required parameters should be marked as a group,
- and optional parameters should be marked using the alternate
- syntax for a group.
-
- For example, a macro which takes a single parameter
- would appear like this:
-
-\begin{verbatim}
-\name{parameter}
-\end{verbatim}
-
- A macro which takes an optional parameter would be typed like this
- when the optional parameter is given:
-
-\begin{verbatim}
-\name[optional]
-\end{verbatim}
-
- If both optional and required parameters are to be required, it
- looks like this:
-
-\begin{verbatim}
-\name[optional]{required}
-\end{verbatim}
-
- A macro name may be followed by a space or newline; a space
- between the macro name and any parameters will be consumed, but
- this usage is not practiced in the Python documentation. Such a
- space is still consumed if there are no parameters to the macro,
- in which case inserting an empty group (\code{\{\}}) or explicit
- word space (\samp{\e\ }) immediately after the macro name helps to
- avoid running the expansion of the macro into the following text.
- Macros which take no parameters but which should not be followed
- by a word space do not need special treatment if the following
- character in the document source if not a name character (such as
- punctuation).
-
- Each line of this example shows an appropriate way to write text
- which includes a macro which takes no parameters:
-
-\begin{verbatim}
-This \UNIX{} is followed by a space.
-This \UNIX\ is also followed by a space.
-\UNIX, followed by a comma, needs no additional markup.
-\end{verbatim}
-
- An \dfn{environment} is a larger construct than a macro, and can
- be used for things with more content than would conveniently fit
- in a macro parameter. They are primarily used when formatting
- parameters need to be changed before and after a large chunk of
- content, but the content itself needs to be highly flexible. Code
- samples are presented using an environment, and descriptions of
- functions, methods, and classes are also marked using environments.
-
- Since the content of an environment is free-form and can consist
- of several paragraphs, they are actually marked using a pair of
- macros: \macro{begin} and \macro{end}. These macros both take the
- name of the environment as a parameter. An example is the
- environment used to mark the abstract of a document:
-
-\begin{verbatim}
-\begin{abstract}
- This is the text of the abstract. It concisely explains what
- information is found in the document.
-
- It can consist of multiple paragraphs.
-\end{abstract}
-\end{verbatim}
-
- An environment can also have required and optional parameters of
- its own. These follow the parameter of the \macro{begin} macro.
- This example shows an environment which takes a single required
- parameter:
-
-\begin{verbatim}
-\begin{datadesc}{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 \samp{SP} for the space character.
-\end{datadesc}
-\end{verbatim}
-
- There are a number of less-used marks in \LaTeX{} which are used
- to enter characters which are not found in \ASCII{} or which a
- considered special, or \emph{active} in \TeX{} or \LaTeX. Given
- that these are often used adjacent to other characters, the markup
- required to produce the proper character may need to be followed
- by a space or an empty group, or the markup can be enclosed in a
- group. Some which are found in Python documentation are:
-
-\begin{tableii}{c|l}{textrm}{Character}{Markup}
- \lineii{\textasciicircum}{\code{\e textasciicircum}}
- \lineii{\textasciitilde}{\code{\e textasciitilde}}
- \lineii{\textgreater}{\code{\e textgreater}}
- \lineii{\textless}{\code{\e textless}}
- \lineii{\c c}{\code{\e c c}}
- \lineii{\"o}{\code{\e"o}}
- \lineii{\o}{\code{\e o}}
-\end{tableii}
-
-
- \subsection{Hierarchical Structure \label{latex-structure}}
-
- \LaTeX{} expects documents to be arranged in a conventional,
- hierarchical way, with chapters, sections, sub-sections,
- appendixes, and the like. These are marked using macros rather
- than environments, probably because the end of a section can be
- safely inferred when a section of equal or higher level starts.
-
- There are six ``levels'' of sectioning in the document classes
- used for Python documentation, and the deepest two
- levels\footnote{The deepest levels have the highest numbers in the
- table.} are not used. The levels are:
-
- \begin{tableiii}{c|l|c}{textrm}{Level}{Macro Name}{Notes}
- \lineiii{1}{\macro{chapter}}{(1)}
- \lineiii{2}{\macro{section}}{}
- \lineiii{3}{\macro{subsection}}{}
- \lineiii{4}{\macro{subsubsection}}{}
- \lineiii{5}{\macro{paragraph}}{(2)}
- \lineiii{6}{\macro{subparagraph}}{}
- \end{tableiii}
-
- \noindent
- Notes:
-
- \begin{description}
- \item[(1)]
- Only used for the \code{manual} documents, as described in
- section \ref{classes}, ``Document Classes.''
- \item[(2)]
- Not the same as a paragraph of text; nobody seems to use this.
- \end{description}
-
-
- \subsection{Common Environments \label{latex-environments}}
-
- \LaTeX{} provides a variety of environments even without the
- additional markup provided by the Python-specific document classes
- introduced in the next section. The following environments are
- provided as part of standard \LaTeX{} and are being used in the
- standard Python documentation; descriptions will be added here as
- time allows.
-
-\begin{verbatim}
-abstract
-alltt
-description
-displaymath
-document
-enumerate
-figure
-flushleft
-itemize
-list
-math
-quotation
-quote
-sloppypar
-verbatim
-\end{verbatim}
-
-
-\section{Document Classes \label{classes}}
-
- Two \LaTeX{} document classes are defined specifically for use with
- the Python documentation. The \code{manual} class is for large
- documents which are sectioned into chapters, and the \code{howto}
- class is for smaller documents.
-
- The \code{manual} documents are larger and are used for most of the
- standard documents. This document class is based on the standard
- \LaTeX{} \code{report} class and is formatted very much like a long
- technical report. The \citetitle[../ref/ref.html]{Python Reference
- Manual} is a good example of a \code{manual} document, and the
- \citetitle[../lib/lib.html]{Python Library Reference} is a large
- example.
-
- The \code{howto} documents are shorter, and don't have the large
- structure of the \code{manual} documents. This class is based on
- the standard \LaTeX{} \code{article} class and is formatted somewhat
- like the Linux Documentation Project's ``HOWTO'' series as done
- originally using the LinuxDoc software. The original intent for the
- document class was that it serve a similar role as the LDP's HOWTO
- series, but the applicability of the class turns out to be somewhat
- broader. This class is used for ``how-to'' documents (this
- document is an example) and for shorter reference manuals for small,
- fairly cohesive module libraries. Examples of the later use include
-\citetitle[http://starship.python.net/crew/fdrake/manuals/krb5py/krb5py.html]{Using
- Kerberos from Python}, which contains reference material for an
- extension package. These documents are roughly equivalent to a
- single chapter from a larger work.
-
-
-\section{Special Markup Constructs \label{special-constructs}}
-
- The Python document classes define a lot of new environments and
- macros. This section contains the reference material for these
- facilities. Documentation for ``standard'' \LaTeX{} constructs is
- not included here, though they are used in the Python documentation.
-
- \subsection{Markup for the Preamble \label{preamble-info}}
-
- \begin{macrodesc}{release}{\p{ver}}
- Set the version number for the software described in the
- document.
- \end{macrodesc}
-
- \begin{macrodesc}{setshortversion}{\p{sver}}
- Specify the ``short'' version number of the documented software
- to be \var{sver}.
- \end{macrodesc}
-
- \subsection{Meta-information Markup \label{meta-info}}
-
- \begin{macrodesc}{sectionauthor}{\p{author}\p{email}}
- Identifies the author of the current section. \var{author}
- should be the author's name such that it can be used for
- presentation (though it isn't), and \var{email} should be the
- author's email address. The domain name portion of
- the address should be lower case.
-
- No presentation is generated from this markup, but it is used to
- help keep track of contributions.
- \end{macrodesc}
-
- \subsection{Information Units \label{info-units}}
-
- XXX Explain terminology, or come up with something more ``lay.''
-
- There are a number of environments used to describe specific
- features provided by modules. Each environment requires
- parameters needed to provide basic information about what is being
- described, and the environment content should be the description.
- Most of these environments make entries in the general index (if
- one is being produced for the document); if no index entry is
- desired, non-indexing variants are available for many of these
- environments. The environments have names of the form
- \code{\var{feature}desc}, and the non-indexing variants are named
- \code{\var{feature}descni}. The available variants are explicitly
- included in the list below.
-
- For each of these environments, the first parameter, \var{name},
- provides the name by which the feature is accessed.
-
- Environments which describe features of objects within a module,
- such as object methods or data attributes, allow an optional
- \var{type name} parameter. When the feature is an attribute of
- class instances, \var{type name} only needs to be given if the
- class was not the most recently described class in the module; the
- \var{name} value from the most recent \env{classdesc} is implied.
- For features of built-in or extension types, the \var{type name}
- value should always be provided. Another special case includes
- methods and members of general ``protocols,'' such as the
- formatter and writer protocols described for the
- \module{formatter} module: these may be documented without any
- specific implementation classes, and will always require the
- \var{type name} parameter to be provided.
-
- \begin{envdesc}{cfuncdesc}{\p{type}\p{name}\p{args}}
- Environment used to described a C function. The \var{type}
- should be specified as a \keyword{typedef} name, \code{struct
- \var{tag}}, or the name of a primitive type. If it is a pointer
- type, the trailing asterisk should not be preceded by a space.
- \var{name} should be the name of the function (or function-like
- pre-processor macro), and \var{args} should give the types and
- names of the parameters. The names need to be given so they may
- be used in the description.
- \end{envdesc}
-
- \begin{envdesc}{cmemberdesc}{\p{container}\p{type}\p{name}}
- Description for a structure member. \var{container} should be
- the \keyword{typedef} name, if there is one, otherwise if should
- be \samp{struct \var{tag}}. The type of the member should given
- as \var{type}, and the name should be given as \var{name}. 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 \macro{member} macro.
- \end{envdesc}
-
- \begin{envdesc}{csimplemacrodesc}{\p{name}}
- Documentation for a ``simple'' 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
- \csimplemacro{PyObject_HEAD} and
- \csimplemacro{Py_BEGIN_ALLOW_THREADS}.
- \end{envdesc}
-
- \begin{envdesc}{ctypedesc}{\op{tag}\p{name}}
- Environment used to described a C type. The \var{name}
- parameter should be the \keyword{typedef} name. If the type is
- defined as a \keyword{struct} without a \keyword{typedef},
- \var{name} should have the form \code{struct \var{tag}}.
- \var{name} will be added to the index unless \var{tag} is
- provided, in which case \var{tag} will be used instead.
- \var{tag} should not be used for a \keyword{typedef} name.
- \end{envdesc}
-
- \begin{envdesc}{cvardesc}{\p{type}\p{name}}
- Description of a global C variable. \var{type} should be the
- \keyword{typedef} name, \code{struct \var{tag}}, or the name of
- a primitive type. If variable has a pointer type, the trailing
- asterisk should \emph{not} be preceded by a space.
- \end{envdesc}
-
- \begin{envdesc}{datadesc}{\p{name}}
- This environment is used to document global data in a module,
- including both variables and values used as ``defined
- constants.'' Class and object attributes are not documented
- using this environment.
- \end{envdesc}
- \begin{envdesc}{datadescni}{\p{name}}
- Like \env{datadesc}, but without creating any index entries.
- \end{envdesc}
-
- \begin{envdesc}{excclassdesc}{\p{name}\p{constructor parameters}}
- Describe an exception defined by a class. \var{constructor
- parameters} should not include the \var{self} parameter or
- the parentheses used in the call syntax. To describe an
- exception class without describing the parameters to its
- constructor, use the \env{excdesc} environment.
- \end{envdesc}
-
- \begin{envdesc}{excdesc}{\p{name}}
- Describe an exception. In the case of class exceptions, the
- constructor parameters are not described; use \env{excclassdesc}
- to describe an exception class and its constructor.
- \end{envdesc}
-
- \begin{envdesc}{funcdesc}{\p{name}\p{parameters}}
- Describe a module-level function. \var{parameters} should
- not include the parentheses used in the call syntax. Object
- methods are not documented using this environment. 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.
- \end{envdesc}
- \begin{envdesc}{funcdescni}{\p{name}\p{parameters}}
- Like \env{funcdesc}, but without creating any index entries.
- \end{envdesc}
-
- \begin{envdesc}{classdesc}{\p{name}\p{constructor parameters}}
- Describe a class and its constructor. \var{constructor
- parameters} should not include the \var{self} parameter or
- the parentheses used in the call syntax.
- \end{envdesc}
-
- \begin{envdesc}{classdesc*}{\p{name}}
- Describe a class without describing the constructor. This can
- be used to describe classes that are merely containers for
- attributes or which should never be instantiated or subclassed
- by user code.
- \end{envdesc}
-
- \begin{envdesc}{memberdesc}{\op{type name}\p{name}}
- Describe 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.
- \end{envdesc}
- \begin{envdesc}{memberdescni}{\op{type name}\p{name}}
- Like \env{memberdesc}, but without creating any index entries.
- \end{envdesc}
-
- \begin{envdesc}{methoddesc}{\op{type name}\p{name}\p{parameters}}
- Describe an object method. \var{parameters} should not include
- the \var{self} parameter or the parentheses used in the call
- syntax. The description should include similar information to
- that described for \env{funcdesc}.
- \end{envdesc}
- \begin{envdesc}{methoddescni}{\op{type name}\p{name}\p{parameters}}
- Like \env{methoddesc}, but without creating any index entries.
- \end{envdesc}
-
-
- \subsection{Showing Code Examples \label{showing-examples}}
-
- Examples of Python source code or interactive sessions are
- represented as \env{verbatim} environments. This environment
- is a standard part of \LaTeX{}. It is important to only use
- spaces for indentation in code examples since \TeX{} drops tabs
- instead of converting them to spaces.
-
- 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 \emph{not} to do:
-
-\begin{verbatim}
->>> 1 + 1
-2
->>>
-\end{verbatim}
-
- Within the \env{verbatim} environment, characters special to
- \LaTeX{} do not need to be specially marked in any way. The entire
- example will be presented in a monospaced font; no attempt at
- ``pretty-printing'' is made, as the environment must work for
- non-Python code and non-code displays. There should be no blank
- lines at the top or bottom of any \env{verbatim} display.
-
- 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 standard \macro{verbatiminput}
- macro; this macro takes a single argument naming the file
- containing the text. For example, to include the Python source
- file \file{example.py}, use:
-
-\begin{verbatim}
-\verbatiminput{example.py}
-\end{verbatim}
-
- Use of \macro{verbatiminput} allows easier use of special editing
- modes for the included file. The file should be placed in the
- same directory as the \LaTeX{} files for the document.
-
- The Python Documentation Special Interest Group has discussed a
- number of approaches to creating pretty-printed code displays and
- interactive sessions; see the Doc-SIG area on the Python Web site
- for more information on this topic.
-
-
- \subsection{Inline Markup \label{inline-markup}}
-
- The macros described in this section are used to mark just about
- anything interesting in the document text. They may be used in
- headings (though anything involving hyperlinks should be avoided
- there) as well as in the body text.
-
- \begin{macrodesc}{bfcode}{\p{text}}
- Like \macro{code}, but also makes the font bold-face.
- \end{macrodesc}
-
- \begin{macrodesc}{cdata}{\p{name}}
- The name of a C-language variable.
- \end{macrodesc}
-
- \begin{macrodesc}{cfunction}{\p{name}}
- The name of a C-language function. \var{name} should include the
- function name and the trailing parentheses.
- \end{macrodesc}
-
- \begin{macrodesc}{character}{\p{char}}
- A character when discussing the character rather than a one-byte
- string value. The character will be typeset as with \macro{samp}.
- \end{macrodesc}
-
- \begin{macrodesc}{citetitle}{\op{url}\p{title}}
- A title for a referenced publication. If \var{url} is specified,
- the title will be made into a hyperlink when formatted as HTML.
- \end{macrodesc}
-
- \begin{macrodesc}{class}{\p{name}}
- A class name; a dotted name may be used.
- \end{macrodesc}
-
- \begin{macrodesc}{code}{\p{text}}
- A short code fragment or literal constant value. Typically, it
- should not include any spaces since no quotation marks are
- added.
- \end{macrodesc}
-
- \begin{macrodesc}{constant}{\p{name}}
- The name of a ``defined'' constant. This may be a C-language
- \code{\#define} or a Python variable that is not intended to be
- changed.
- \end{macrodesc}
-
- \begin{macrodesc}{csimplemacro}{\p{name}}
- The name of a ``simple'' 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
- \csimplemacro{PyObject_HEAD} and
- \csimplemacro{Py_BEGIN_ALLOW_THREADS}.
- \end{macrodesc}
-
- \begin{macrodesc}{ctype}{\p{name}}
- The name of a C \keyword{typedef} or structure. For structures
- defined without a \keyword{typedef}, use \code{\e ctype\{struct
- struct_tag\}} to make it clear that the \keyword{struct} is
- required.
- \end{macrodesc}
-
- \begin{macrodesc}{deprecated}{\p{version}\p{what to do}}
- Declare whatever is being described as being deprecated starting
- with release \var{version}. The text given as \var{what to do}
- should recommend something to use instead. It should be
- complete sentences. The entire deprecation notice will be
- presented as a separate paragraph; it should either precede or
- succeed the description of the deprecated feature.
- \end{macrodesc}
-
- \begin{macrodesc}{dfn}{\p{term}}
- Mark the defining instance of \var{term} in the text. (No index
- entries are generated.)
- \end{macrodesc}
-
- \begin{macrodesc}{e}{}
- Produces a backslash. This is convenient in \macro{code},
- \macro{file}, and similar macros, and the \env{alltt}
- environment, and is only defined there. To
- create a backslash in ordinary text (such as the contents of the
- \macro{citetitle} macro), use the standard \macro{textbackslash}
- macro.
- \end{macrodesc}
-
- \begin{macrodesc}{email}{\p{address}}
- An email address. Note that this is \emph{not} hyperlinked in
- any of the possible output formats. The domain name portion of
- the address should be lower case.
- \end{macrodesc}
-
- \begin{macrodesc}{emph}{\p{text}}
- Emphasized text; this will be presented in an italic font.
- \end{macrodesc}
-
- \begin{macrodesc}{envvar}{\p{name}}
- An environment variable. Index entries are generated.
- \end{macrodesc}
-
- \begin{macrodesc}{exception}{\p{name}}
- The name of an exception. A dotted name may be used.
- \end{macrodesc}
-
- \begin{macrodesc}{file}{\p{file or dir}}
- The name of a file or directory. In the PDF and PostScript
- outputs, single quotes and a font change are used to indicate
- the file name, but no quotes are used in the HTML output.
- \warning{The \macro{file} macro cannot be used in the
- content of a section title due to processing limitations.}
- \end{macrodesc}
-
- \begin{macrodesc}{filenq}{\p{file or dir}}
- Like \macro{file}, but single quotes are never used. This can
- be used in conjunction with tables if a column will only contain
- file or directory names.
- \warning{The \macro{filenq} macro cannot be used in the
- content of a section title due to processing limitations.}
- \end{macrodesc}
-
- \begin{macrodesc}{function}{\p{name}}
- The name of a Python function; dotted names may be used.
- \end{macrodesc}
-
- \begin{macrodesc}{infinity}{}
- The symbol for mathematical infinity: \infinity. Some Web
- browsers are not able to render the HTML representation of this
- symbol properly, but support is growing.
- \end{macrodesc}
-
- \begin{macrodesc}{kbd}{\p{key sequence}}
- Mark a sequence of keystrokes. What form \var{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
- \program{xemacs} key sequence may be marked like
- \code{\e kbd\{C-x C-f\}}, but without reference to a specific
- application or platform, the same sequence should be marked as
- \code{\e kbd\{Control-x Control-f\}}.
- \end{macrodesc}
-
- \begin{macrodesc}{keyword}{\p{name}}
- The name of a keyword in a programming language.
- \end{macrodesc}
-
- \begin{macrodesc}{mailheader}{\p{name}}
- 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. The colon which follows the name of the
- header should not be included.
- For example: \code{\e mailheader\{Content-Type\}}.
- \end{macrodesc}
-
- \begin{macrodesc}{makevar}{\p{name}}
- The name of a \program{make} variable.
- \end{macrodesc}
-
- \begin{macrodesc}{manpage}{\p{name}\p{section}}
- A reference to a \UNIX{} manual page.
- \end{macrodesc}
-
- \begin{macrodesc}{member}{\p{name}}
- The name of a data attribute of an object.
- \end{macrodesc}
-
- \begin{macrodesc}{method}{\p{name}}
- The name of a method of an object. \var{name} should include the
- method name and the trailing parentheses. A dotted name may be
- used.
- \end{macrodesc}
-
- \begin{macrodesc}{mimetype}{\p{name}}
- The name of a MIME type, or a component of a MIME type (the
- major or minor portion, taken alone).
- \end{macrodesc}
-
- \begin{macrodesc}{module}{\p{name}}
- The name of a module; a dotted name may be used. This should
- also be used for package names.
- \end{macrodesc}
-
- \begin{macrodesc}{newsgroup}{\p{name}}
- The name of a Usenet newsgroup.
- \end{macrodesc}
-
- \begin{macrodesc}{note}{\p{text}}
- 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. This should be the last thing in the
- paragraph as the end of the note is not visually marked in
- any way. The content of \var{text} should be written in
- complete sentences and include all appropriate punctuation.
- \end{macrodesc}
-
- \begin{macrodesc}{pep}{\p{number}}
- A reference to a Python Enhancement Proposal. This generates
- appropriate index entries. The text \samp{PEP \var{number}} is
- generated; in the HTML output, this text is a hyperlink to an
- online copy of the specified PEP.
- \end{macrodesc}
-
- \begin{macrodesc}{plusminus}{}
- The symbol for indicating a value that may take a positive or
- negative value of a specified magnitude, typically represented
- by a plus sign placed over a minus sign. For example:
- \code{\e plusminus 3\%{}}.
- \end{macrodesc}
-
- \begin{macrodesc}{program}{\p{name}}
- The name of an executable program. This may differ from the
- file name for the executable for some platforms. In particular,
- the \file{.exe} (or other) extension should be omitted for
- Windows programs.
- \end{macrodesc}
-
- \begin{macrodesc}{programopt}{\p{option}}
- A command-line option to an executable program. Use this only
- for ``short'' options, and include the leading hyphen.
- \end{macrodesc}
-
- \begin{macrodesc}{longprogramopt}{\p{option}}
- A long command-line option to an executable program. This
- should only be used for long option names which will be prefixed
- by two hyphens; the hyphens should not be provided as part of
- \var{option}.
- \end{macrodesc}
-
- \begin{macrodesc}{refmodule}{\op{key}\p{name}}
- Like \macro{module}, but create a hyperlink to the documentation
- for the named module. Note that the corresponding
- \macro{declaremodule} must be in the same document. If the
- \macro{declaremodule} defines a module key different from the
- module name, it must also be provided as \var{key} to the
- \macro{refmodule} macro.
- \end{macrodesc}
-
- \begin{macrodesc}{regexp}{\p{string}}
- Mark a regular expression.
- \end{macrodesc}
-
- \begin{macrodesc}{rfc}{\p{number}}
- A reference to an Internet Request for Comments. This generates
- appropriate index entries. The text \samp{RFC \var{number}} is
- generated; in the HTML output, this text is a hyperlink to an
- online copy of the specified RFC.
- \end{macrodesc}
-
- \begin{macrodesc}{samp}{\p{text}}
- A short code sample, but possibly longer than would be given
- using \macro{code}. Since quotation marks are added, spaces are
- acceptable.
- \end{macrodesc}
-
- \begin{macrodesc}{shortversion}{}
- The ``short'' version number of the documented software, as
- specified using the \macro{setshortversion} macro in the
- preamble. For Python, the short version number for a release is
- the first three characters of the \code{sys.version} value. For
- example, versions 2.0b1 and 2.0.1 both have a short version of
- 2.0. This may not apply for all packages; if
- \macro{setshortversion} is not used, this produces an empty
- expansion. See also the \macro{version} macro.
- \end{macrodesc}
-
- \begin{macrodesc}{strong}{\p{text}}
- Strongly emphasized text; this will be presented using a bold
- font.
- \end{macrodesc}
-
- \begin{macrodesc}{ulink}{\p{text}\p{url}}
- A hypertext link with a target specified by a URL, but for which
- the link text should not be the title of the resource. For
- resources being referenced by name, use the \macro{citetitle}
- macro. Not all formatted versions support arbitrary hypertext
- links. Note that many characters are special to \LaTeX{} and
- this macro does not always do the right thing. In particular,
- the tilde character (\character{\~}) is mis-handled; encoding it
- as a hex-sequence does work, use \samp{\%7e} in place of the
- tilde character.
- \end{macrodesc}
-
- \begin{macrodesc}{url}{\p{url}}
- A URL (or URN). The URL will be presented as text. In the HTML
- and PDF formatted versions, the URL will also be a hyperlink.
- This can be used when referring to external resources without
- specific titles; references to resources which have titles
- should be marked using the \macro{citetitle} macro. See the
- comments about special characters in the description of the
- \macro{ulink} macro for special considerations.
- \end{macrodesc}
-
- \begin{macrodesc}{var}{\p{name}}
- The name of a variable or formal parameter in running text.
- \end{macrodesc}
-
- \begin{macrodesc}{version}{}
- The version number of the described software, as specified using
- \macro{release} in the preamble. See also the
- \macro{shortversion} macro.
- \end{macrodesc}
-
- \begin{macrodesc}{warning}{\p{text}}
- 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. This should be the last thing in the paragraph as
- the end of the warning is not visually marked in any way. The
- content of \var{text} should be written in complete sentences
- and include all appropriate punctuation. This differs from
- \macro{note} in that it is recommended over \macro{note} for
- information regarding security.
- \end{macrodesc}
-
- The following two macros are used to describe information that's
- associated with changes from one release to another. For features
- which are described by a single paragraph, these are typically
- added as separate source lines at the end of the paragraph. When
- adding these to features described by multiple paragraphs, they
- are usually collected in a single separate paragraph after the
- description. When both \macro{versionadded} and
- \macro{versionchanged} are used, \macro{versionadded} should come
- first; the versions should be listed in chronological order. Both
- of these should come before availability statements. The location
- should be selected so the explanation makes sense and may vary as
- needed.
-
- \begin{macrodesc}{versionadded}{\op{explanation}\p{version}}
- The version of Python which added the described feature to the
- library or C API. \var{explanation} should be a \emph{brief}
- explanation of the change consisting of a capitalized sentence
- fragment; a period will be appended by the formatting process.
- When this applies to an entire module, it should be placed at
- the top of the module section before any prose.
- \end{macrodesc}
-
- \begin{macrodesc}{versionchanged}{\op{explanation}\p{version}}
- The version of Python in which the named feature was changed in
- some way (new parameters, changed side effects, etc.).
- \var{explanation} should be a \emph{brief} explanation of the
- change consisting of a capitalized sentence fragment; a
- period will be appended by the formatting process. This should
- not generally be applied to modules.
- \end{macrodesc}
-
-
- \subsection{Miscellaneous Text Markup \label{misc-text-markup}}
-
- In addition to the inline markup, some additional ``block'' markup
- is defined to make it easier to bring attention to various bits of
- text. The markup described here serves this purpose, and is
- intended to be used when marking one or more paragraphs or other
- block constructs (such as \env{verbatim} environments).
-
- \begin{envdesc}{notice}{\op{type}}
- Label some paragraphs as being worthy of additional attention from
- the reader. What sort of attention is warranted can be indicated
- by specifying the \var{type} of the notice. The only values
- defined for \var{type} are \code{note} and \code{warning}; these
- are equivalent in intent to the inline markup of the same name.
- If \var{type} is omitted, \code{note} is used. Additional values
- may be defined in the future.
- \end{envdesc}
-
-
- \subsection{Module-specific Markup \label{module-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 \macro{section}. A typical use of this markup
- appears at the top of that section and might look like this:
-
-\begin{verbatim}
-\section{\module{spam} ---
- Access to the SPAM facility}
-
-\declaremodule{extension}{spam}
- \platform{Unix}
-\modulesynopsis{Access to the SPAM facility of \UNIX.}
-\moduleauthor{Jane Doe}{jane.doe@frobnitz.org}
-\end{verbatim}
-
- Python packages\index{packages} --- collections of modules that can
- be described as a unit --- are documented using the same markup as
- modules. The name for a module in a package should be typed in
- ``fully qualified'' form (it should include the package name).
- For example, a module ``foo'' in package ``bar'' should be marked as
- \code{\e module\{bar.foo\}}, and the beginning of the reference
- section would appear as:
-
-\begin{verbatim}
-\section{\module{bar.foo} ---
- Module from the \module{bar} package}
-
-\declaremodule{extension}{bar.foo}
-\modulesynopsis{Nifty module from the \module{bar} package.}
-\moduleauthor{Jane Doe}{jane.doe@frobnitz.org}
-\end{verbatim}
-
- Note that the name of a package is also marked using
- \macro{module}.
-
- \begin{macrodesc}{declaremodule}{\op{key}\p{type}\p{name}}
- Requires two parameters: module type (\samp{standard},
- \samp{builtin}, \samp{extension}, or \samp{}), and the module
- name. An optional parameter should be given as the basis for the
- module's ``key'' used for linking to or referencing the section.
- The ``key'' should only be given if the module's name contains any
- underscores, and should be the name with the underscores stripped.
- Note that the \var{type} parameter must be one of the values
- listed above or an error will be printed. For modules which are
- contained in packages, the fully-qualified name should be given as
- \var{name} parameter. This should be the first thing after the
- \macro{section} used to introduce the module.
- \end{macrodesc}
-
- \begin{macrodesc}{platform}{\p{specifier}}
- Specifies the portability of the module. \var{specifier} is a
- comma-separated list of keys that specify what platforms the
- module is available on. The keys are short identifiers;
- examples that are in use include \samp{IRIX}, \samp{Mac},
- \samp{Windows}, and \samp{Unix}. It is important to use a key
- which has already been used when applicable. This is used to
- provide annotations in the Module Index and the HTML and GNU info
- output.
- \end{macrodesc}
-
- \begin{macrodesc}{modulesynopsis}{\p{text}}
- The \var{text} is a short, ``one line'' description of the
- module that can be used as part of the chapter introduction.
- This is must be placed after \macro{declaremodule}.
- The synopsis is used in building the contents of the table
- inserted as the \macro{localmoduletable}. No text is
- produced at the point of the markup.
- \end{macrodesc}
-
- \begin{macrodesc}{moduleauthor}{\p{name}\p{email}}
- This macro is used to encode information about who authored a
- module. This is currently not used to generate output, but can be
- used to help determine the origin of the module.
- \end{macrodesc}
-
-
- \subsection{Library-level Markup \label{library-markup}}
-
- This markup is used when describing a selection of modules. For
- example, the \citetitle[../mac/mac.html]{Macintosh Library
- Modules} document uses this to help provide an overview of the
- modules in the collection, and many chapters in the
- \citetitle[../lib/lib.html]{Python Library Reference} use it for
- the same purpose.
-
- \begin{macrodesc}{localmoduletable}{}
- If a \file{.syn} file exists for the current
- chapter (or for the entire document in \code{howto} documents), a
- \env{synopsistable} is created with the contents loaded from the
- \file{.syn} file.
- \end{macrodesc}
-
-
- \subsection{Table Markup \label{table-markup}}
-
- There are three general-purpose table environments defined which
- should be used whenever possible. These environments are defined
- to provide tables of specific widths and some convenience for
- formatting. These environments are not meant to be general
- replacements for the standard \LaTeX{} table environments, but can
- be used for an advantage when the documents are processed using
- the tools for Python documentation processing. In particular, the
- generated HTML looks good! There is also an advantage for the
- eventual conversion of the documentation to XML (see section
- \ref{futures}, ``Future Directions'').
-
- Each environment is named \env{table\var{cols}}, where \var{cols}
- is the number of columns in the table specified in lower-case
- Roman numerals. Within each of these environments, an additional
- macro, \macro{line\var{cols}}, is defined, where \var{cols}
- matches the \var{cols} value of the corresponding table
- environment. These are supported for \var{cols} values of
- \code{ii}, \code{iii}, and \code{iv}. These environments are all
- built on top of the \env{tabular} environment. Variants based on
- the \env{longtable} environment are also provided.
-
- Note that all tables in the standard Python documentation use
- vertical lines between columns, and this must be specified in the
- markup for each table. A general border around the outside of the
- table is not used, but would be the responsibility of the
- processor; the document markup should not include an exterior
- border.
-
- The \env{longtable}-based variants of the table environments are
- formatted with extra space before and after, so should only be
- used on tables which are long enough that splitting over multiple
- pages is reasonable; tables with fewer than twenty rows should
- never by marked using the long flavors of the table environments.
- The header row is repeated across the top of each part of the
- table.
-
- \begin{envdesc}{tableii}{\p{colspec}\p{col1font}\p{heading1}\p{heading2}}
- Create a two-column table using the \LaTeX{} column specifier
- \var{colspec}. The column specifier should indicate vertical
- bars between columns as appropriate for the specific table, but
- should not specify vertical bars on the outside of the table
- (that is considered a stylesheet issue). The \var{col1font}
- parameter is used as a stylistic treatment of the first column
- of the table: the first column is presented as
- \code{\e\var{col1font}\{column1\}}. To avoid treating the first
- column specially, \var{col1font} may be \samp{textrm}. The
- column headings are taken from the values \var{heading1} and
- \var{heading2}.
- \end{envdesc}
-
- \begin{envdesc}{longtableii}{\unspecified}
- Like \env{tableii}, but produces a table which may be broken
- across page boundaries. The parameters are the same as for
- \env{tableii}.
- \end{envdesc}
-
- \begin{macrodesc}{lineii}{\p{column1}\p{column2}}
- Create a single table row within a \env{tableii} or
- \env{longtableii} environment.
- The text for the first column will be generated by applying the
- macro named by the \var{col1font} value when the \env{tableii}
- was opened.
- \end{macrodesc}
-
- \begin{envdesc}{tableiii}{\p{colspec}\p{col1font}\p{heading1}\p{heading2}\p{heading3}}
- Like the \env{tableii} environment, but with a third column.
- The heading for the third column is given by \var{heading3}.
- \end{envdesc}
-
- \begin{envdesc}{longtableiii}{\unspecified}
- Like \env{tableiii}, but produces a table which may be broken
- across page boundaries. The parameters are the same as for
- \env{tableiii}.
- \end{envdesc}
-
- \begin{macrodesc}{lineiii}{\p{column1}\p{column2}\p{column3}}
- Like the \macro{lineii} macro, but with a third column. The
- text for the third column is given by \var{column3}.
- \end{macrodesc}
-
- \begin{envdesc}{tableiv}{\p{colspec}\p{col1font}\p{heading1}\p{heading2}\p{heading3}\p{heading4}}
- Like the \env{tableiii} environment, but with a fourth column.
- The heading for the fourth column is given by \var{heading4}.
- \end{envdesc}
-
- \begin{envdesc}{longtableiv}{\unspecified}
- Like \env{tableiv}, but produces a table which may be broken
- across page boundaries. The parameters are the same as for
- \env{tableiv}.
- \end{envdesc}
-
- \begin{macrodesc}{lineiv}{\p{column1}\p{column2}\p{column3}\p{column4}}
- Like the \macro{lineiii} macro, but with a fourth column. The
- text for the fourth column is given by \var{column4}.
- \end{macrodesc}
-
- \begin{envdesc}{tablev}{\p{colspec}\p{col1font}\p{heading1}\p{heading2}\p{heading3}\p{heading4}\p{heading5}}
- Like the \env{tableiv} environment, but with a fifth column.
- The heading for the fifth column is given by \var{heading5}.
- \end{envdesc}
-
- \begin{envdesc}{longtablev}{\unspecified}
- Like \env{tablev}, but produces a table which may be broken
- across page boundaries. The parameters are the same as for
- \env{tablev}.
- \end{envdesc}
-
- \begin{macrodesc}{linev}{\p{column1}\p{column2}\p{column3}\p{column4}\p{column5}}
- Like the \macro{lineiv} macro, but with a fifth column. The
- text for the fifth column is given by \var{column5}.
- \end{macrodesc}
-
-
- An additional table-like environment is \env{synopsistable}. The
- table generated by this environment contains two columns, and each
- row is defined by an alternate definition of
- \macro{modulesynopsis}. This environment is not normally used by
- authors, but is created by the \macro{localmoduletable} macro.
-
- Here is a small example of a table given in the documentation for
- the \module{warnings} module; markup inside the table cells is
- minimal so the markup for the table itself is readily discernable.
- Here is the markup for the table:
-
-\begin{verbatim}
-\begin{tableii}{l|l}{exception}{Class}{Description}
- \lineii{Warning}
- {This is the base class of all warning category classes. It
- is a subclass of \exception{Exception}.}
- \lineii{UserWarning}
- {The default category for \function{warn()}.}
- \lineii{DeprecationWarning}
- {Base category for warnings about deprecated features.}
- \lineii{SyntaxWarning}
- {Base category for warnings about dubious syntactic
- features.}
- \lineii{RuntimeWarning}
- {Base category for warnings about dubious runtime features.}
- \lineii{FutureWarning}
- {Base category for warnings about constructs that will change
- semantically in the future.}
-\end{tableii}
-\end{verbatim}
-
- Here is the resulting table:
-
-\begin{tableii}{l|l}{exception}{Class}{Description}
- \lineii{Warning}
- {This is the base class of all warning category classes. It
- is a subclass of \exception{Exception}.}
- \lineii{UserWarning}
- {The default category for \function{warn()}.}
- \lineii{DeprecationWarning}
- {Base category for warnings about deprecated features.}
- \lineii{SyntaxWarning}
- {Base category for warnings about dubious syntactic
- features.}
- \lineii{RuntimeWarning}
- {Base category for warnings about dubious runtime features.}
-\end{tableii}
-
- Note that the class names are implicitly marked using the
- \macro{exception} macro, since that is given as the \var{col1font}
- value for the \env{tableii} environment. To create a table using
- different markup for the first column, use \code{textrm} for the
- \var{col1font} value and mark each entry individually.
-
- To add a horizontal line between vertical sections of a table, use
- the standard \macro{hline} macro between the rows which should be
- separated:
-
-\begin{verbatim}
-\begin{tableii}{l|l}{constant}{Language}{Audience}
- \lineii{APL}{Masochists.}
- \lineii{BASIC}{First-time programmers on PC hardware.}
- \lineii{C}{\UNIX{} \&\ Linux kernel developers.}
- \hline
- \lineii{Python}{Everyone!}
-\end{tableii}
-\end{verbatim}
-
- Note that not all presentation formats are capable of displaying a
- horizontal rule in this position. This is how the table looks in
- the format you're reading now:
-
-\begin{tableii}{l|l}{constant}{Language}{Audience}
- \lineii{APL}{Masochists.}
- \lineii{C}{\UNIX{} \&\ Linux kernel developers.}
- \lineii{JavaScript}{Web developers.}
- \hline
- \lineii{Python}{Everyone!}
-\end{tableii}
-
-
- \subsection{Reference List Markup \label{references}}
-
- Many sections include a list of references to module documentation
- or external documents. These lists are created using the
- \env{seealso} or \env{seealso*} environments. These environments
- define some additional macros to support creating reference
- entries in a reasonable manner.
-
- The \env{seealso} environment is typically placed in a section
- just before any sub-sections. This is done to ensure that
- reference links related to the section are not hidden in a
- subsection in the hypertext renditions of the documentation. For
- the HTML output, it is shown as a ``side bar,'' boxed off from the
- main flow of the text. The \env{seealso*} environment is
- different in that it should be used when a list of references is
- being presented as part of the primary content; it is not
- specially set off from the text.
-
- \begin{envdesc}{seealso}{}
- This environment creates a ``See also:'' heading and defines the
- markup used to describe individual references.
- \end{envdesc}
-
- \begin{envdesc}{seealso*}{}
- This environment is used to create a list of references which
- form part of the main content. It is not given a special
- header and is not set off from the main flow of the text. It
- provides the same additional markup used to describe individual
- references.
- \end{envdesc}
-
- For each of the following macros, \var{why} should be one or more
- complete sentences, starting with a capital letter (unless it
- starts with an identifier, which should not be modified), and
- ending with the appropriate punctuation.
-
- These macros are only defined within the content of the
- \env{seealso} and \env{seealso*} environments.
-
- \begin{macrodesc}{seelink}{\p{url}\p{linktext}\p{why}}
- References to specific on-line resources should be given using
- the \macro{seelink} macro if they don't have a meaningful title
- but there is some short description of what's at the end of the
- link. Online documents which have identifiable titles should be
- referenced using the \macro{seetitle} macro, using the optional
- parameter to that macro to provide the URL.
- \end{macrodesc}
-
- \begin{macrodesc}{seemodule}{\op{key}\p{name}\p{why}}
- Refer to another module. \var{why} should be a brief
- explanation of why the reference may be interesting. The module
- name is given in \var{name}, with the link key given in
- \var{key} if necessary. In the HTML and PDF conversions, the
- module name will be a hyperlink to the referred-to module.
- \note{The module must be documented in the same
- document (the corresponding \macro{declaremodule} is required).}
- \end{macrodesc}
-
- \begin{macrodesc}{seepep}{\p{number}\p{title}\p{why}}
- Refer to an Python Enhancement Proposal (PEP). \var{number}
- should be the official number assigned by the PEP Editor,
- \var{title} should be the human-readable title of the PEP as
- found in the official copy of the document, and \var{why} should
- explain what's interesting about the PEP. This should be used
- to refer the reader to PEPs which specify interfaces or language
- features relevant to the material in the annotated section of the
- documentation.
- \end{macrodesc}
-
- \begin{macrodesc}{seerfc}{\p{number}\p{title}\p{why}}
- Refer to an IETF Request for Comments (RFC). Otherwise very
- similar to \macro{seepep}. This should be used
- to refer the reader to PEPs which specify protocols or data
- formats relevant to the material in the annotated section of the
- documentation.
- \end{macrodesc}
-
- \begin{macrodesc}{seetext}{\p{text}}
- Add arbitrary text \var{text} to the ``See also:'' list. This
- can be used to refer to off-line materials or on-line materials
- using the \macro{url} macro. This should consist of one or more
- complete sentences.
- \end{macrodesc}
-
- \begin{macrodesc}{seetitle}{\op{url}\p{title}\p{why}}
- Add a reference to an external document named \var{title}. If
- \var{url} is given, the title is made a hyperlink in the HTML
- version of the documentation, and displayed below the title in
- the typeset versions of the documentation.
- \end{macrodesc}
-
- \begin{macrodesc}{seeurl}{\p{url}\p{why}}
- References to specific on-line resources should be given using
- the \macro{seeurl} macro if they don't have a meaningful title.
- Online documents which have identifiable titles should be
- referenced using the \macro{seetitle} macro, using the optional
- parameter to that macro to provide the URL.
- \end{macrodesc}
-
-
- \subsection{Index-generating Markup \label{indexing}}
-
- Effective index generation for technical documents can be very
- difficult, especially for someone familiar with the topic but not
- the creation of indexes. Much of the difficulty arises in the
- area of terminology: including the terms an expert would use for a
- concept is not sufficient. Coming up with the terms that a novice
- would look up is fairly difficult for an author who, typically, is
- an expert in the area she is writing on.
-
- The truly difficult aspects of index generation are not areas with
- which the documentation tools can help. However, ease
- of producing the index once content decisions are made is within
- the scope of the tools. Markup is provided which the processing
- software is able to use to generate a variety of kinds of index
- entry with minimal effort. Additionally, many of the environments
- described in section \ref{info-units}, ``Information Units,'' will
- generate appropriate entries into the general and module indexes.
-
- The following macro can be used to control the generation of index
- data, and should be used in the document preamble:
-
- \begin{macrodesc}{makemodindex}{}
- This should be used in the document preamble if a ``Module
- Index'' is desired for a document containing reference material
- on many modules. This causes a data file
- \code{lib\var{jobname}.idx} to be created from the
- \macro{declaremodule} macros. This file can be processed by the
- \program{makeindex} program to generate a file which can be
- \macro{input} into the document at the desired location of the
- module index.
- \end{macrodesc}
-
- There are a number of macros that are useful for adding index
- entries for particular concepts, many of which are specific to
- programming languages or even Python.
-
- \begin{macrodesc}{bifuncindex}{\p{name}}
- Add an index entry referring to a built-in function named
- \var{name}; parentheses should not be included after
- \var{name}.
- \end{macrodesc}
-
- \begin{macrodesc}{exindex}{\p{exception}}
- Add a reference to an exception named \var{exception}. The
- exception should be class-based.
- \end{macrodesc}
-
- \begin{macrodesc}{kwindex}{\p{keyword}}
- Add a reference to a language keyword (not a keyword parameter
- in a function or method call).
- \end{macrodesc}
-
- \begin{macrodesc}{obindex}{\p{object type}}
- Add an index entry for a built-in object type.
- \end{macrodesc}
-
- \begin{macrodesc}{opindex}{\p{operator}}
- Add a reference to an operator, such as \samp{+}.
- \end{macrodesc}
-
- \begin{macrodesc}{refmodindex}{\op{key}\p{module}}
- Add an index entry for module \var{module}; if \var{module}
- contains an underscore, the optional parameter \var{key} should
- be provided as the same string with underscores removed. An
- index entry ``\var{module} (module)'' will be generated. This
- is intended for use with non-standard modules implemented in
- Python.
- \end{macrodesc}
-
- \begin{macrodesc}{refexmodindex}{\op{key}\p{module}}
- As for \macro{refmodindex}, but the index entry will be
- ``\var{module} (extension module).'' This is intended for use
- with non-standard modules not implemented in Python.
- \end{macrodesc}
-
- \begin{macrodesc}{refbimodindex}{\op{key}\p{module}}
- As for \macro{refmodindex}, but the index entry will be
- ``\var{module} (built-in module).'' This is intended for use
- with standard modules not implemented in Python.
- \end{macrodesc}
-
- \begin{macrodesc}{refstmodindex}{\op{key}\p{module}}
- As for \macro{refmodindex}, but the index entry will be
- ``\var{module} (standard module).'' This is intended for use
- with standard modules implemented in Python.
- \end{macrodesc}
-
- \begin{macrodesc}{stindex}{\p{statement}}
- Add an index entry for a statement type, such as \keyword{print}
- or \keyword{try}/\keyword{finally}.
-
- XXX Need better examples of difference from \macro{kwindex}.
- \end{macrodesc}
-
-
- Additional macros are provided which are useful for conveniently
- creating general index entries which should appear at many places
- in the index by rotating a list of words. These are simple macros
- that simply use \macro{index} to build some number of index
- entries. Index entries build using these macros contain both
- primary and secondary text.
-
- \begin{macrodesc}{indexii}{\p{word1}\p{word2}}
- Build two index entries. This is exactly equivalent to using
- \code{\e index\{\var{word1}!\var{word2}\}} and
- \code{\e index\{\var{word2}!\var{word1}\}}.
- \end{macrodesc}
-
- \begin{macrodesc}{indexiii}{\p{word1}\p{word2}\p{word3}}
- Build three index entries. This is exactly equivalent to using
- \code{\e index\{\var{word1}!\var{word2} \var{word3}\}},
- \code{\e index\{\var{word2}!\var{word3}, \var{word1}\}}, and
- \code{\e index\{\var{word3}!\var{word1} \var{word2}\}}.
- \end{macrodesc}
-
- \begin{macrodesc}{indexiv}{\p{word1}\p{word2}\p{word3}\p{word4}}
- Build four index entries. This is exactly equivalent to using
- \code{\e index\{\var{word1}!\var{word2} \var{word3} \var{word4}\}},
- \code{\e index\{\var{word2}!\var{word3} \var{word4}, \var{word1}\}},
- \code{\e index\{\var{word3}!\var{word4}, \var{word1} \var{word2}\}},
- and
- \code{\e index\{\var{word4}!\var{word1} \var{word2} \var{word3}\}}.
- \end{macrodesc}
-
- \subsection{Grammar Production Displays \label{grammar-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 one environment and a pair of
- macros:
-
- \begin{envdesc}{productionlist}{\op{language}}
- This environment is used to enclose a group of productions. The
- two macros are only defined within this environment. If a
- document describes more than one language, the optional parameter
- \var{language} should be used to distinguish productions between
- languages. The value of the parameter should be a short name
- that can be used as part of a filename; colons or other
- characters that can't be used in filename across platforms
- should be included.
- \end{envdesc}
-
- \begin{macrodesc}{production}{\p{name}\p{definition}}
- A production rule in the grammar. The rule defines the symbol
- \var{name} to be \var{definition}. \var{name} should not
- contain any markup, and the use of hyphens in a document which
- supports more than one grammar is undefined. \var{definition}
- may contain \macro{token} macros and any additional content
- needed to describe the grammatical model of \var{symbol}. Only
- one \macro{production} may be used to define a symbol ---
- multiple definitions are not allowed.
- \end{macrodesc}
-
- \begin{macrodesc}{token}{\p{name}}
- The name of a symbol defined by a \macro{production} macro, used
- in the \var{definition} of a symbol. Where possible, this will
- be rendered as a hyperlink to the definition of the symbol
- \var{name}.
- \end{macrodesc}
-
- Note that the entire grammar does not need to be defined in a
- single \env{productionlist} environment; any number of
- groupings may be used to describe the grammar. Every use of the
- \macro{token} must correspond to a \macro{production}.
-
- The following is an example taken from the
- \citetitle[../ref/identifiers.html]{Python Reference Manual}:
-
-\begin{verbatim}
-\begin{productionlist}
- \production{identifier}
- {(\token{letter}|"_") (\token{letter} | \token{digit} | "_")*}
- \production{letter}
- {\token{lowercase} | \token{uppercase}}
- \production{lowercase}
- {"a"..."z"}
- \production{uppercase}
- {"A"..."Z"}
- \production{digit}
- {"0"..."9"}
-\end{productionlist}
-\end{verbatim}
-
-
-\subsection{Graphical Interface Components \label{gui-markup}}
-
- The components of graphical interfaces will be assigned markup, but
- most of the specifics have not been determined.
-
- \begin{macrodesc}{guilabel}{\p{label}}
- Labels presented as part of an interactive user interface should
- be marked using \macro{guilabel}. This includes labels from
- text-based interfaces such as those created using \code{curses} or
- other text-based libraries. Any label used in the interface
- should be marked with this macro, including button labels, window
- titles, field names, menu and menu selection names, and even
- values in selection lists.
- \end{macrodesc}
-
- \begin{macrodesc}{menuselection}{\p{menupath}}
- Menu selections should be marked using a combination of
- \macro{menuselection} and \macro{sub}. This macro 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 occurrences of \macro{sub}.
-
- For example, to mark the selection ``\menuselection{Start \sub
- Programs}'', use this markup:
-
-\begin{verbatim}
-\menuselection{Start \sub Programs}
-\end{verbatim}
-
- 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.
-
- Individual selection names within the \macro{menuselection} should
- not be marked using \macro{guilabel} since that's implied by using
- \macro{menuselection}.
- \end{macrodesc}
-
- \begin{macrodesc}{sub}{}
- Separator for menu selections that include multiple levels. This
- macro is only defined within the context of the
- \macro{menuselection} macro.
- \end{macrodesc}
-
-
-\section{Processing Tools \label{tools}}
-
- \subsection{External Tools \label{tools-external}}
-
- Many tools are needed to be able to process the Python
- documentation if all supported formats are required. This
- section lists the tools used and when each is required. Consult
- the \file{Doc/README} file to see if there are specific version
- requirements for any of these.
-
- \begin{description}
- \item[\program{dvips}]
- This program is a typical part of \TeX{} installations. It is
- used to generate PostScript from the ``device independent''
- \file{.dvi} files. It is needed for the conversion to
- PostScript.
-
- \item[\program{emacs}]
- Emacs is the kitchen sink of programmers' editors, and a damn
- fine kitchen sink it is. It also comes with some of the
- processing needed to support the proper menu structures for
- Texinfo documents when an info conversion is desired. This is
- needed for the info conversion. Using \program{xemacs}
- instead of FSF \program{emacs} may lead to instability in the
- conversion, but that's because nobody seems to maintain the
- Emacs Texinfo code in a portable manner.
-
- \item[\program{latex}]
- \LaTeX{} is a large and extensible macro package by Leslie
- Lamport, based on \TeX, a world-class typesetter by Donald
- Knuth. It is used for the conversion to PostScript, and is
- needed for the HTML conversion as well (\LaTeX2HTML requires
- one of the intermediate files it creates).
-
- \item[\program{latex2html}]
- Probably the longest Perl script anyone ever attempted to
- maintain. This converts \LaTeX{} documents to HTML documents,
- and does a pretty reasonable job. It is required for the
- conversions to HTML and GNU info.
-
- \item[\program{lynx}]
- This is a text-mode Web browser which includes an
- HTML-to-plain text conversion. This is used to convert
- \code{howto} documents to text.
-
- \item[\program{make}]
- Just about any version should work for the standard documents,
- but GNU \program{make} is required for the experimental
- processes in \file{Doc/tools/sgmlconv/}, at least while
- they're experimental. This is not required for running the
- \program{mkhowto} script.
-
- \item[\program{makeindex}]
- This is a standard program for converting \LaTeX{} index data
- to a formatted index; it should be included with all \LaTeX{}
- installations. It is needed for the PDF and PostScript
- conversions.
-
- \item[\program{makeinfo}]
- GNU \program{makeinfo} is used to convert Texinfo documents to
- GNU info files. Since Texinfo is used as an intermediate
- format in the info conversion, this program is needed in that
- conversion.
-
- \item[\program{pdflatex}]
- pdf\TeX{} is a relatively new variant of \TeX, and is used to
- generate the PDF version of the manuals. It is typically
- installed as part of most of the large \TeX{} distributions.
- \program{pdflatex} is pdf\TeX{} using the \LaTeX{} format.
-
- \item[\program{perl}]
- Perl is required for \LaTeX2HTML{} and one of the scripts used
- to post-process \LaTeX2HTML output, as well as the
- HTML-to-Texinfo conversion. This is required for
- the HTML and GNU info conversions.
-
- \item[\program{python}]
- Python is used for many of the scripts in the
- \file{Doc/tools/} directory; it is required for all
- conversions. This shouldn't be a problem if you're interested
- in writing documentation for Python!
- \end{description}
-
-
- \subsection{Internal Tools \label{tools-internal}}
-
- This section describes the various scripts that are used to
- implement various stages of document processing or to orchestrate
- entire build sequences. Most of these tools are only useful
- in the context of building the standard documentation, but some
- are more general.
-
- \begin{description}
- \item[\program{mkhowto}]
- This is the primary script used to format third-party
- documents. It contains all the logic needed to ``get it
- right.'' The proper way to use this script is to make a
- symbolic link to it or run it in place; the actual script file
- must be stored as part of the documentation source tree,
- though it may be used to format documents outside the tree.
- Use \program{mkhowto} \longprogramopt{help} for a list of
- command line options.
-
- \program{mkhowto} can be used for both \code{howto} and
- \code{manual} class documents. It is usually a good idea to
- always use the latest version of this tool rather than a
- version from an older source release of Python. It can be
- used to generate DVI, HTML, PDF, PostScript, and plain text
- documents. The GNU info and iSilo formats will be supported
- by this script in some future version.
-
- Use the \longprogramopt{help} option on this script's command
- line to get a summary of options for this script.
-
- XXX Need more here.
- \end{description}
-
-
- \subsection{Working on Cygwin \label{cygwin}}
-
- Installing the required tools under Cygwin under Cygwin can be a
- little tedious. Most of the required packages can be installed
- using Cygwin's graphical installer, while netpbm and \LaTeX2HTML
- must be installed from source.
-
- Start with a reasonably modern version of Cygwin. If you haven't
- upgraded for a few years, now would be a good time.
-
- Using the Cygwin installer, make sure your Cygwin installation
- includes Perl, Python, and the \TeX{} packages. Perl and Python
- are located under the \menuselection{Interpreters} heading. The
- \TeX{} packages are located under the \menuselection{Text}
- heading, and are named \code{tetex-*}. To ensure that all
- required packages are available, install every \code{tetex}
- package, except \code{tetex-x11}. (There may be a more minimal
- set, but I've not spent time trying to minimize the installation.)
-
- The netpbm package is used by \LaTeX2HTML, and \emph{must} be
- installed before \LaTeX2HTML can be successfully installed, even
- though its features will not be used for most Python
- documentation. References to download locations are located in
- the \ulink{netpbm README}{http://netpbm.sourceforge.net/README}.
- Install from the latest stable source distribution according to
- the instructions. (Note that binary packages of netpbm are
- sometimes available, but these may not work correctly with
- \LaTeX2HTML.)
-
- \LaTeX2HTML can be installed from the source archive, but only
- after munging one of the files in the distribution. Download the
- source archive from the \LaTeX2HTML website
- \url{http://www.latex2html.org/} (or one of the many alternate
- sites) and unpack it to a build directory. In the top level of
- this build directory there will be a file named \file{L2hos.pm}.
- Open \file{L2hos.pm} in an editor, and near the bottom of the file
- replace the text \code{\$\textasciicircum{}O} with the text
- \code{'unix'}. Proceed using this command to build and install
- the software:
-
-\begin{verbatim}
-% ./configure && make install
-\end{verbatim}
-
- You should now be able to build at least the DVI, HTML, PDF, and
- PostScript versions of the formatted documentation.
-
-
-\section{Including Graphics \label{graphics}}
-
- The standard documentation included with Python makes no use of
- diagrams or images; this is intentional. The outside tools used to
- format the documentation have not always been suited to working with
- graphics. As the tools have evolved and been improved by their
- maintainers, support for graphics has improved.
-
- The internal tools, starting with the \program{mkhowto} script, do
- not provide any direct support for graphics. However,
- \program{mkhowto} will not interfere with graphics support in the
- external tools.
-
- Experience using graphics together with these tools and the
- \code{howto} and \code{manual} document classes is not extensive,
- but has been known to work. The basic approach is this:
-
- \begin{enumerate}
- \item Create the image or graphic using your favorite
- application.
-
- \item Convert the image to a format supported by the conversion to
- your desired output format. If you want to generate HTML or
- PostScript, you can convert the image or graphic to
- encapsulated PostScript (a \file{.eps} file); \LaTeX2HTML
- can convert that to a \file{.gif} file; it may be possible
- to provide a \file{.gif} file directly. If you want to
- generate PDF, you need to provide an ``encapsulated'' PDF
- file. This can be generated from encapsulated PostScript
- using the \program{epstopdf} tool provided with the te\TeX{}
- distribution on Linux and \UNIX.
-
- \item In your document, add this line to ``import'' the general
- graphics support package \code{graphicx}:
-
-\begin{verbatim}
-\usepackage{graphicx}
-\end{verbatim}
-
- \item Where you want to include your graphic or image, include
- markup similar to this:
-
-\begin{verbatim}
-\begin{figure}
- \centering
- \includegraphics[width=5in]{myimage}
- \caption{Description of my image}
-\end{figure}
-\end{verbatim}
-
- In particular, note for the \macro{includegraphics} macro
- that no file extension is provided. If you're only
- interested in one target format, you can include the
- extension of the appropriate input file, but to allow
- support for multiple formats, omitting the extension makes
- life easier.
-
- \item Run \program{mkhowto} normally.
- \end{enumerate}
-
- If you're working on systems which support some sort of
- \program{make} facility, you can use that to ensure the intermediate
- graphic formats are kept up to date. This example shows a
- \file{Makefile} used to format a document containing a diagram
- created using the \program{dia} application:
-
-\begin{verbatim}
-default: pdf
-all: html pdf ps
-
-html: mydoc/mydoc.html
-pdf: mydoc.pdf
-ps: mydoc.ps
-
-mydoc/mydoc.html: mydoc.tex mygraphic.eps
- mkhowto --html $<
-
-mydoc.pdf: mydoc.tex mygraphic.pdf
- mkhowto --pdf $<
-
-mydoc.ps: mydoc.tex mygraphic.eps
- mkhowto --postscript $<
-
-.SUFFIXES: .dia .eps .pdf
-
-.dia.eps:
- dia --nosplash --export $@ $<
-
-.eps.pdf:
- epstopdf $<
-\end{verbatim} % $ <-- bow to font-lock
-
-
-\section{Future Directions \label{futures}}
-
- The history of the Python documentation is full of changes, most of
- which have been fairly small and evolutionary. There has been a
- great deal of discussion about making large changes in the markup
- languages and tools used to process the documentation. This section
- deals with the nature of the changes and what appears to be the most
- likely path of future development.
-
- \subsection{Structured Documentation \label{structured}}
-
- Most of the small changes to the \LaTeX{} markup have been made
- with an eye to divorcing the markup from the presentation, making
- both a bit more maintainable. Over the course of 1998, a large
- number of changes were made with exactly this in mind; previously,
- changes had been made but in a less systematic manner and with
- more concern for not needing to update the existing content. The
- result has been a highly structured and semantically loaded markup
- language implemented in \LaTeX. With almost no basic \TeX{} or
- \LaTeX{} markup in use, however, the markup syntax is about the
- only evidence of \LaTeX{} in the actual document sources.
-
- One side effect of this is that while we've been able to use
- standard ``engines'' for manipulating the documents, such as
- \LaTeX{} and \LaTeX2HTML, most of the actual transformations have
- been created specifically for Python. The \LaTeX{} document
- classes and \LaTeX2HTML support are both complete implementations
- of the specific markup designed for these documents.
-
- Combining highly customized markup with the somewhat esoteric
- systems used to process the documents leads us to ask some
- questions: Can we do this more easily? and, Can we do this
- better? After a great deal of discussion with the community, we
- have determined that actively pursuing modern structured
- documentation systems is worth some investment of time.
-
- There appear to be two real contenders in this arena: the Standard
- General Markup Language (SGML), and the Extensible Markup Language
- (XML). Both of these standards have advantages and disadvantages,
- and many advantages are shared.
-
- SGML offers advantages which may appeal most to authors,
- especially those using ordinary text editors. There are also
- additional abilities to define content models. A number of
- high-quality tools with demonstrated maturity are available, but
- most are not free; for those which are, portability issues remain
- a problem.
-
- The advantages of XML include the availability of a large number
- of evolving tools. Unfortunately, many of the associated
- standards are still evolving, and the tools will have to follow
- along. This means that developing a robust tool set that uses
- more than the basic XML 1.0 recommendation is not possible in the
- short term. The promised availability of a wide variety of
- high-quality tools which support some of the most important
- related standards is not immediate. Many tools are likely to be
- free, and the portability issues of those which are, are not
- expected to be significant.
-
- It turns out that converting to an XML or SGML system holds
- promise for translators as well; how much can be done to ease the
- burden on translators remains to be seen, and may have some impact
- on the schema and specific technologies used.
-
- XXX Eventual migration to XML.
-
- The documentation will be moved to XML in the future, and tools
- are being written which will convert the documentation from the
- current format to something close to a finished version, to the
- extent that the desired information is already present in the
- documentation. Some XSLT stylesheets have been started for
- presenting a preliminary XML version as HTML, but the results are
- fairly rough.
-
- The timeframe for the conversion is not clear since there doesn't
- seem to be much time available to work on this, but the apparent
- benefits are growing more substantial at a moderately rapid pace.
-
-
- \subsection{Discussion Forums \label{discussion}}
-
- Discussion of the future of the Python documentation and related
- topics takes place in the Documentation Special Interest Group, or
- ``Doc-SIG.'' Information on the group, including mailing list
- archives and subscription information, is available at
- \url{http://www.python.org/sigs/doc-sig/}. The SIG is open to all
- interested parties.
-
- Comments and bug reports on the standard documents should be sent
- to \email{docs@python.org}. This may include comments
- about formatting, content, grammatical and spelling errors, or
- this document. You can also send comments on this document
- directly to the author at \email{fdrake@acm.org}.
-
-\input{doc.ind}
-
-\end{document}
diff --git a/Doc/ext/building.tex b/Doc/ext/building.tex
deleted file mode 100644
index 42384c1..0000000
--- a/Doc/ext/building.tex
+++ /dev/null
@@ -1,143 +0,0 @@
-\chapter{Building C and \Cpp{} Extensions with distutils
- \label{building}}
-
-\sectionauthor{Martin v. L\"owis}{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:
-
-\begin{verbatim}
-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])
-
-\end{verbatim}
-
-With this \file{setup.py}, and a file \file{demo.c}, running
-
-\begin{verbatim}
-python setup.py build
-\end{verbatim}
-
-will compile \file{demo.c}, and produce an extension module named
-\samp{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
-\samp{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 \citetitle[../dist/dist.html]{Distributing Python
-Modules} to learn more about the features of distutils; this section
-explains building extension modules only.
-
-It is common to pre-compute arguments to \function{setup}, to better
-structure the driver script. In the example above,
-the\samp{ext_modules} argument to \function{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 \samp{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.
-
-\begin{verbatim}
-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])
-
-\end{verbatim}
-
-In this example, \function{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
-
-\begin{verbatim}
-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
-\end{verbatim}
-
-These lines are for demonstration purposes only; distutils users
-should trust that distutils gets the invocations right.
-
-\section{Distributing your extension modules
- \label{distributing}}
-
-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
-
-\begin{verbatim}
-python setup.py install
-\end{verbatim}
-
-Module maintainers should produce source packages; to do so, they run
-
-\begin{verbatim}
-python setup.py sdist
-\end{verbatim}
-
-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.
-
-\begin{verbatim}
-python setup.py bdist_wininst
-python setup.py bdist_rpm
-python setup.py bdist_dumb
-\end{verbatim}
-
diff --git a/Doc/ext/embedding.tex b/Doc/ext/embedding.tex
deleted file mode 100644
index 58ec5ca..0000000
--- a/Doc/ext/embedding.tex
+++ /dev/null
@@ -1,316 +0,0 @@
-\chapter{Embedding Python in Another Application
- \label{embedding}}
-
-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/\Cpp{} 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 \Cpp.
-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 \cfunction{Py_Initialize()} (on Mac OS, call
-\cfunction{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
-\cfunction{PyRun_SimpleString()}, or you can pass a stdio file pointer
-and a file name (for identification in error messages only) to
-\cfunction{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.
-
-
-\begin{seealso}
- \seetitle[../api/api.html]{Python/C API Reference Manual}{The
- details of Python's C interface are given in this manual.
- A great deal of necessary information can be found here.}
-\end{seealso}
-
-
-\section{Very High Level Embedding
- \label{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.
-
-\begin{verbatim}
-#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;
-}
-\end{verbatim}
-
-The above code first initializes the Python interpreter with
-\cfunction{Py_Initialize()}, followed by the execution of a hard-coded
-Python script that print the date and time. Afterwards, the
-\cfunction{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 \cfunction{PyRun_SimpleFile()} function, which
-saves you the trouble of allocating memory space and loading the file
-contents.
-
-
-\section{Beyond Very High Level Embedding: An overview
- \label{lower-level-embedding}}
-
-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:
-
-\begin{enumerate}
- \item Convert data values from Python to C,
- \item Perform a function call to a C routine using the
- converted values, and
- \item Convert the data values from the call from C to Python.
-\end{enumerate}
-
-When embedding Python, the interface code does:
-
-\begin{enumerate}
- \item Convert data values from C to Python,
- \item Perform a function call to a Python interface routine
- using the converted values, and
- \item Convert the data values from the call from Python to C.
-\end{enumerate}
-
-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.
-
-
-\section{Pure Embedding
- \label{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:
-
-\verbatiminput{run-func.c}
-
-This code loads a Python script using \code{argv[1]}, and calls the
-function named in \code{argv[2]}. Its integer arguments are the other
-values of the \code{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:
-
-\begin{verbatim}
-def multiply(a,b):
- print "Will compute", a, "times", b
- c = 0
- for i in range(0, a):
- c = c + b
- return c
-\end{verbatim}
-
-then the result should be:
-
-\begin{verbatim}
-$ call multiply multiply 3 2
-Will compute 3 times 2
-Result of call: 6
-\end{verbatim} % $
-
-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
-
-\begin{verbatim}
- Py_Initialize();
- pName = PyString_FromString(argv[1]);
- /* Error checking of pName left out */
- pModule = PyImport_Import(pName);
-\end{verbatim}
-
-After initializing the interpreter, the script is loaded using
-\cfunction{PyImport_Import()}. This routine needs a Python string
-as its argument, which is constructed using the
-\cfunction{PyString_FromString()} data conversion routine.
-
-\begin{verbatim}
- pFunc = PyObject_GetAttrString(pModule, argv[2]);
- /* pFunc is a new reference */
-
- if (pFunc && PyCallable_Check(pFunc)) {
- ...
- }
- Py_XDECREF(pFunc);
-\end{verbatim}
-
-Once the script is loaded, the name we're looking for is retrieved
-using \cfunction{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:
-
-\begin{verbatim}
- pValue = PyObject_CallObject(pFunc, pArgs);
-\end{verbatim}
-
-Upon return of the function, \code{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.
-
-
-\section{Extending Embedded Python
- \label{extending-with-embedding}}
-
-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:
-
-\begin{verbatim}
-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}
-};
-\end{verbatim}
-
-Insert the above code just above the \cfunction{main()} function.
-Also, insert the following two statements directly after
-\cfunction{Py_Initialize()}:
-
-\begin{verbatim}
- numargs = argc;
- Py_InitModule("emb", EmbMethods);
-\end{verbatim}
-
-These two lines initialize the \code{numargs} variable, and make the
-\function{emb.numargs()} function accessible to the embedded Python
-interpreter. With these extensions, the Python script can do things
-like
-
-\begin{verbatim}
-import emb
-print "Number of arguments", emb.numargs()
-\end{verbatim}
-
-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)
-
-
-\section{Embedding Python in \Cpp
- \label{embeddingInCplusplus}}
-
-It is also possible to embed Python in a \Cpp{} program; precisely how this
-is done will depend on the details of the \Cpp{} system used; in general you
-will need to write the main program in \Cpp, and use the \Cpp{} compiler
-to compile and link your program. There is no need to recompile Python
-itself using \Cpp.
-
-
-\section{Linking Requirements
- \label{link-reqs}}
-
-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:
-
-\begin{verbatim}
->>> import distutils.sysconfig
->>> distutils.sysconfig.get_config_var('LINKFORSHARED')
-'-Xlinker -export-dynamic'
-\end{verbatim}
-\refstmodindex{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 \constant{LINKFORSHARED} definition
-corresponds to the variable of the same name in Python's top-level
-\file{Makefile}.
diff --git a/Doc/ext/ext.tex b/Doc/ext/ext.tex
deleted file mode 100644
index b4130d1..0000000
--- a/Doc/ext/ext.tex
+++ /dev/null
@@ -1,67 +0,0 @@
-\documentclass{manual}
-
-% XXX PM explain how to add new types to Python
-
-\title{Extending and Embedding the Python Interpreter}
-
-\input{boilerplate}
-
-% Tell \index to actually write the .idx file
-\makeindex
-
-\begin{document}
-
-\maketitle
-
-\ifhtml
-\chapter*{Front Matter\label{front}}
-\fi
-
-\input{copyright}
-
-
-\begin{abstract}
-
-\noindent
-Python is an interpreted, object-oriented programming language. This
-document describes how to write modules in C or \Cpp{} 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 the
-\citetitle[../tut/tut.html]{Python Tutorial}. The
-\citetitle[../ref/ref.html]{Python Reference Manual} gives a more
-formal definition of the language. The
-\citetitle[../lib/lib.html]{Python Library Reference} 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
-\citetitle[../api/api.html]{Python/C API Reference Manual}.
-
-\end{abstract}
-
-\tableofcontents
-
-
-\input{extending}
-\input{newtypes}
-\input{building}
-\input{windows}
-\input{embedding}
-
-
-\appendix
-\chapter{Reporting Bugs}
-\input{reportingbugs}
-
-\chapter{History and License}
-\input{license}
-
-\end{document}
diff --git a/Doc/ext/extending.tex b/Doc/ext/extending.tex
deleted file mode 100644
index 7796e9e..0000000
--- a/Doc/ext/extending.tex
+++ /dev/null
@@ -1,1386 +0,0 @@
-\chapter{Extending Python with \C{} or \Cpp{} \label{intro}}
-
-
-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
-\code{"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.
-
-
-\section{A Simple Example
- \label{simpleExample}}
-
-Let's create an extension module called \samp{spam} (the favorite food
-of Monty Python fans...) and let's say we want to create a Python
-interface to the C library function \cfunction{system()}.\footnote{An
-interface for this function already exists in the standard module
-\module{os} --- it was chosen as a simple and straightforward example.}
-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:
-
-\begin{verbatim}
->>> import spam
->>> status = spam.system("ls -l")
-\end{verbatim}
-
-Begin by creating a file \file{spammodule.c}. (Historically, if a
-module is called \samp{spam}, the C file containing its implementation
-is called \file{spammodule.c}; if the module name is very long, like
-\samp{spammify}, the module name can be just \file{spammify.c}.)
-
-The first line of our file can be:
-
-\begin{verbatim}
-#include <Python.h>
-\end{verbatim}
-
-which pulls in the Python API (you can add a comment describing the
-purpose of the module and a copyright notice if you like).
-
-\begin{notice}[warning]
- Since Python may define some pre-processor definitions which affect
- the standard headers on some systems, you \emph{must} include
- \file{Python.h} before any standard headers are included.
-\end{notice}
-
-All user-visible symbols defined by \file{Python.h} have a prefix of
-\samp{Py} or \samp{PY}, except those defined in standard header files.
-For convenience, and since they are used extensively by the Python
-interpreter, \code{"Python.h"} includes a few standard header files:
-\code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>}, and
-\code{<stdlib.h>}. If the latter header file does not exist on your
-system, it declares the functions \cfunction{malloc()},
-\cfunction{free()} and \cfunction{realloc()} directly.
-
-The next thing we add to our module file is the C function that will
-be called when the Python expression \samp{spam.system(\var{string})}
-is evaluated (we'll see shortly how it ends up being called):
-
-\begin{verbatim}
-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);
-}
-\end{verbatim}
-
-There is a straightforward translation from the argument list in
-Python (for example, the single expression \code{"ls -l"}) to the
-arguments passed to the C function. The C function always has two
-arguments, conventionally named \var{self} and \var{args}.
-
-The \var{self} argument is only used when the C function implements a
-built-in method, not a function. In the example, \var{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 \var{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 \cfunction{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.
-
-\cfunction{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).
-
-
-\section{Intermezzo: Errors and Exceptions
- \label{errors}}
-
-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 result in Python of
-\method{sys.exc_info()} (see the section on module \module{sys} in the
-\citetitle[../lib/lib.html]{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 \cfunction{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 \cfunction{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 \cfunction{PyErr_SetObject()}, which takes two object
-arguments, the exception and its associated value. You don't need to
-\cfunction{Py_INCREF()} the objects passed to any of these functions.
-
-You can test non-destructively whether an exception has been set with
-\cfunction{PyErr_Occurred()}. This returns the current exception object,
-or \NULL{} if no exception has occurred. You normally don't need
-to call \cfunction{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 \var{f} that calls another function \var{g} detects
-that the latter fails, \var{f} should itself return an error value
-(usually \NULL{} or \code{-1}). It should \emph{not} call one of the
-\cfunction{PyErr_*()} functions --- one has already been called by \var{g}.
-\var{f}'s caller is then supposed to also return an error indication
-to \emph{its} caller, again \emph{without} calling \cfunction{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 \cfunction{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 \cfunction{PyErr_Clear()}.
-The only time C code should call \cfunction{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 \cfunction{malloc()} call must be turned into an
-exception --- the direct caller of \cfunction{malloc()} (or
-\cfunction{realloc()}) must call \cfunction{PyErr_NoMemory()} and
-return a failure indicator itself. All the object-creating functions
-(for example, \cfunction{PyInt_FromLong()}) already do this, so this
-note is only relevant to those who call \cfunction{malloc()} directly.
-
-Also note that, with the important exception of
-\cfunction{PyArg_ParseTuple()} and friends, functions that return an
-integer status usually return a positive value or zero for success and
-\code{-1} for failure, like \UNIX{} system calls.
-
-Finally, be careful to clean up garbage (by making
-\cfunction{Py_XDECREF()} or \cfunction{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 \cfunction{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:
-
-\begin{verbatim}
-static PyObject *SpamError;
-\end{verbatim}
-
-and initialize it in your module's initialization function
-(\cfunction{initspam()}) with an exception object (leaving out
-the error checking for now):
-
-\begin{verbatim}
-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);
-}
-\end{verbatim}
-
-Note that the Python name for the exception object is
-\exception{spam.error}. The \cfunction{PyErr_NewException()} function
-may create a class with the base class being \exception{Exception}
-(unless another class is passed in instead of \NULL), described in the
-\citetitle[../lib/lib.html]{Python Library Reference} under ``Built-in
-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.
-
-\section{Back to the Example
- \label{backToExample}}
-
-Going back to our example function, you should now be able to
-understand this statement:
-
-\begin{verbatim}
- if (!PyArg_ParseTuple(args, "s", &command))
- return NULL;
-\end{verbatim}
-
-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 \cfunction{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 \samp{const char
-*command}).
-
-The next statement is a call to the \UNIX{} function
-\cfunction{system()}, passing it the string we just got from
-\cfunction{PyArg_ParseTuple()}:
-
-\begin{verbatim}
- sts = system(command);
-\end{verbatim}
-
-Our \function{spam.system()} function must return the value of
-\cdata{sts} as a Python object. This is done using the function
-\cfunction{Py_BuildValue()}, which is something like the inverse of
-\cfunction{PyArg_ParseTuple()}: it takes a format string and an
-arbitrary number of C values, and returns a new Python object.
-More info on \cfunction{Py_BuildValue()} is given later.
-
-\begin{verbatim}
- return Py_BuildValue("i", sts);
-\end{verbatim}
-
-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
-\code{None}. You need this idiom to do so (which is implemented by the
-\csimplemacro{Py_RETURN_NONE} macro):
-
-\begin{verbatim}
- Py_INCREF(Py_None);
- return Py_None;
-\end{verbatim}
-
-\cdata{Py_None} is the C name for the special Python object
-\code{None}. It is a genuine Python object rather than a \NULL{}
-pointer, which means ``error'' in most contexts, as we have seen.
-
-
-\section{The Module's Method Table and Initialization Function
- \label{methodTable}}
-
-I promised to show how \cfunction{spam_system()} is called from Python
-programs. First, we need to list its name and address in a ``method
-table'':
-
-\begin{verbatim}
-static PyMethodDef SpamMethods[] = {
- ...
- {"system", spam_system, METH_VARARGS,
- "Execute a shell command."},
- ...
- {NULL, NULL, 0, NULL} /* Sentinel */
-};
-\end{verbatim}
-
-Note the third entry (\samp{METH_VARARGS}). This is a flag telling
-the interpreter the calling convention to be used for the C
-function. It should normally always be \samp{METH_VARARGS} or
-\samp{METH_VARARGS | METH_KEYWORDS}; a value of \code{0} means that an
-obsolete variant of \cfunction{PyArg_ParseTuple()} is used.
-
-When using only \samp{METH_VARARGS}, the function should expect
-the Python-level parameters to be passed in as a tuple acceptable for
-parsing via \cfunction{PyArg_ParseTuple()}; more information on this
-function is provided below.
-
-The \constant{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 \samp{PyObject *} parameter which
-will be a dictionary of keywords. Use
-\cfunction{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
-\cfunction{init\var{name}()}, where \var{name} is the name of the
-module, and should be the only non-\keyword{static} item defined in
-the module file:
-
-\begin{verbatim}
-PyMODINIT_FUNC
-initspam(void)
-{
- (void) Py_InitModule("spam", SpamMethods);
-}
-\end{verbatim}
-
-Note that PyMODINIT_FUNC declares the function as \code{void} return type,
-declares any special linkage declarations required by the platform, and for
-\Cpp{} declares the function as \code{extern "C"}.
-
-When the Python program imports module \module{spam} for the first
-time, \cfunction{initspam()} is called. (See below for comments about
-embedding Python.) It calls
-\cfunction{Py_InitModule()}, which creates a ``module object'' (which
-is inserted in the dictionary \code{sys.modules} under the key
-\code{"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.
-\cfunction{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 \cfunction{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 \cfunction{initspam()} after the call to
-\cfunction{Py_Initialize()}:
-
-\begin{verbatim}
-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();
-\end{verbatim}
-
-An example may be found in the file \file{Demo/embed/demo.c} in the
-Python source distribution.
-
-\note{Removing entries from \code{sys.modules} or importing
-compiled modules into multiple interpreters within a process (or
-following a \cfunction{fork()} without an intervening
-\cfunction{exec()}) can create problems for some extension modules.
-Extension module authors should exercise caution when initializing
-internal data structures.}
-
-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.
-
-
-\section{Compilation and Linkage
- \label{compilation}}
-
-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:
-
-\begin{verbatim}
-spam spammodule.o
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-spam spammodule.o -lX11
-\end{verbatim}
-
-\section{Calling Python Functions from C
- \label{callingPython}}
-
-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 \programopt{-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
-\cfunction{Py_INCREF()} it!) in a global variable --- or wherever you
-see fit. For example, the following function might be part of a module
-definition:
-
-\begin{verbatim}
-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;
-}
-\end{verbatim}
-
-This function must be registered with the interpreter using the
-\constant{METH_VARARGS} flag; this is described in section
-\ref{methodTable}, ``The Module's Method Table and Initialization
-Function.'' The \cfunction{PyArg_ParseTuple()} function and its
-arguments are documented in section~\ref{parseTuple}, ``Extracting
-Parameters in Extension Functions.''
-
-The macros \cfunction{Py_XINCREF()} and \cfunction{Py_XDECREF()}
-increment/decrement the reference count of an object and are safe in
-the presence of \NULL{} pointers (but note that \var{temp} will not be
-\NULL{} in this context). More info on them in
-section~\ref{refcounts}, ``Reference Counts.''
-
-Later, when it is time to call the function, you call the C function
-\cfunction{PyEval_CallObject()}.\ttindex{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.
-\cfunction{Py_BuildValue()} returns a tuple when its format string
-consists of zero or more format codes between parentheses. For
-example:
-
-\begin{verbatim}
- 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);
-\end{verbatim}
-
-\cfunction{PyEval_CallObject()} returns a Python object pointer: this is
-the return value of the Python function. \cfunction{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 \cfunction{Py_DECREF()}-ed immediately after the call.
-
-The return value of \cfunction{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 \cfunction{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
-\cfunction{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 \cfunction{PyErr_Clear()}. For example:
-
-\begin{verbatim}
- if (result == NULL)
- return NULL; /* Pass error back */
- ...use result...
- Py_DECREF(result);
-\end{verbatim}
-
-Depending on the desired interface to the Python callback function,
-you may also have to provide an argument list to
-\cfunction{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 \cfunction{Py_BuildValue()}. For example, if
-you want to pass an integral event code, you might use the following
-code:
-
-\begin{verbatim}
- 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);
-\end{verbatim}
-
-Note the placement of \samp{Py_DECREF(arglist)} immediately after the
-call, before the error check! Also note that strictly spoken this
-code is not complete: \cfunction{Py_BuildValue()} may run out of
-memory, and this should be checked.
-
-
-\section{Extracting Parameters in Extension Functions
- \label{parseTuple}}
-
-\ttindex{PyArg_ParseTuple()}
-
-The \cfunction{PyArg_ParseTuple()} function is declared as follows:
-
-\begin{verbatim}
-int PyArg_ParseTuple(PyObject *arg, char *format, ...);
-\end{verbatim}
-
-The \var{arg} argument must be a tuple object containing an argument
-list passed from Python to a C function. The \var{format} argument
-must be a format string, whose syntax is explained in
-``\ulink{Parsing arguments and building
-values}{../api/arg-parsing.html}'' in the
-\citetitle[../api/api.html]{Python/C API Reference Manual}. The
-remaining arguments must be addresses of variables whose type is
-determined by the format string.
-
-Note that while \cfunction{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 \emph{borrowed} references; do not decrement their
-reference count!
-
-Some example calls:
-
-\begin{verbatim}
- int ok;
- int i, j;
- long k, l;
- const char *s;
- int size;
-
- ok = PyArg_ParseTuple(args, ""); /* No arguments */
- /* Python call: f() */
-\end{verbatim}
-
-\begin{verbatim}
- ok = PyArg_ParseTuple(args, "s", &s); /* A string */
- /* Possible Python call: f('whoops!') */
-\end{verbatim}
-
-\begin{verbatim}
- ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */
- /* Possible Python call: f(1, 2, 'three') */
-\end{verbatim}
-
-\begin{verbatim}
- 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') */
-\end{verbatim}
-
-\begin{verbatim}
- {
- 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) */
- }
-\end{verbatim}
-
-\begin{verbatim}
- {
- 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)) */
- }
-\end{verbatim}
-
-\begin{verbatim}
- {
- 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) */
- }
-\end{verbatim}
-
-
-\section{Keyword Parameters for Extension Functions
- \label{parseTupleAndKeywords}}
-
-\ttindex{PyArg_ParseTupleAndKeywords()}
-
-The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as
-follows:
-
-\begin{verbatim}
-int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
- char *format, char *kwlist[], ...);
-\end{verbatim}
-
-The \var{arg} and \var{format} parameters are identical to those of the
-\cfunction{PyArg_ParseTuple()} function. The \var{kwdict} parameter
-is the dictionary of keywords received as the third parameter from the
-Python runtime. The \var{kwlist} parameter is a \NULL-terminated
-list of strings which identify the parameters; the names are matched
-with the type information from \var{format} from left to right. On
-success, \cfunction{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
-\var{kwlist} will cause \exception{TypeError} to be raised.}
-
-Here is an example module which uses keywords, based on an example by
-Geoff Philbrick (\email{philbrick@hks.com}):%
-\index{Philbrick, Geoff}
-
-\begin{verbatim}
-#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 */
-};
-\end{verbatim}
-
-\begin{verbatim}
-void
-initkeywdarg(void)
-{
- /* Create the module and add the functions */
- Py_InitModule("keywdarg", keywdarg_methods);
-}
-\end{verbatim}
-
-
-\section{Building Arbitrary Values
- \label{buildValue}}
-
-This function is the counterpart to \cfunction{PyArg_ParseTuple()}. It is
-declared as follows:
-
-\begin{verbatim}
-PyObject *Py_BuildValue(char *format, ...);
-\end{verbatim}
-
-It recognizes a set of format units similar to the ones recognized by
-\cfunction{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 \cfunction{PyArg_ParseTuple()}: while the latter
-requires its first argument to be a tuple (since Python argument lists
-are always represented as tuples internally),
-\cfunction{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 \code{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):
-
-\begin{verbatim}
- Py_BuildValue("") None
- Py_BuildValue("i", 123) 123
- Py_BuildValue("iii", 123, 456, 789) (123, 456, 789)
- Py_BuildValue("s", "hello") 'hello'
- Py_BuildValue("y", "hello") b'hello'
- Py_BuildValue("ss", "hello", "world") ('hello', 'world')
- Py_BuildValue("s#", "hello", 4) 'hell'
- Py_BuildValue("y#", "hello", 4) b'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))
-\end{verbatim}
-
-
-\section{Reference Counts
- \label{refcounts}}
-
-In languages like C or \Cpp, the programmer is responsible for
-dynamic allocation and deallocation of memory on the heap. In C,
-this is done using the functions \cfunction{malloc()} and
-\cfunction{free()}. In \Cpp, 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 \cfunction{malloc()} should
-eventually be returned to the pool of available memory by exactly one
-call to \cfunction{free()}. It is important to call
-\cfunction{free()} at the right time. If a block's address is
-forgotten but \cfunction{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
-\cfunction{free()} for a block and then continues to use the block, it
-creates a conflict with re-use of the block through another
-\cfunction{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 \cfunction{malloc()} and
-\cfunction{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 \cfunction{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 \cfunction{malloc()}
-and \cfunction{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
-(\method{__del__()} methods). When there are such finalizers, the
-detector exposes the cycles through the \ulink{\module{gc}
-module}{../lib/module-gc.html} (specifically, the \code{garbage}
-variable in that module). The \module{gc} module also exposes a way
-to run the detector (the \function{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 \longprogramopt{without-cycle-gc} option to the
-\program{configure} script on \UNIX{} platforms (including Mac OS X)
-or by removing the definition of \code{WITH_CYCLE_GC} in the
-\file{pyconfig.h} header on other platforms. If the cycle detector is
-disabled in this way, the \module{gc} module will not be available.
-
-
-\subsection{Reference Counting in Python
- \label{refcountsInPython}}
-
-There are two macros, \code{Py_INCREF(x)} and \code{Py_DECREF(x)},
-which handle the incrementing and decrementing of the reference count.
-\cfunction{Py_DECREF()} also frees the object when the count reaches zero.
-For flexibility, it doesn't call \cfunction{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 \code{Py_INCREF(x)} and
-\code{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 \cfunction{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
-\cfunction{Py_DECREF()}. Forgetting to dispose of an owned reference
-creates a memory leak.
-
-It is also possible to \dfn{borrow}\footnote{The metaphor of
-``borrowing'' a reference is not completely correct: the owner still
-has a copy of the reference.} a reference to an object. The borrower
-of a reference should not call \cfunction{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.\footnote{Checking that the reference count is at least 1
-\strong{does not work} --- the reference count itself could be in
-freed memory and may thus be reused for another object!}
-
-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
-\cfunction{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).
-
-
-\subsection{Ownership Rules
- \label{ownershipRules}}
-
-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 \cfunction{PyInt_FromLong()} and
-\cfunction{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, \cfunction{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
-\cfunction{PyObject_GetAttrString()}. The picture is less clear, here,
-however, since a few common routines are exceptions:
-\cfunction{PyTuple_GetItem()}, \cfunction{PyList_GetItem()},
-\cfunction{PyDict_GetItem()}, and \cfunction{PyDict_GetItemString()}
-all return references that you borrow from the tuple, list or
-dictionary.
-
-The function \cfunction{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
-\code{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 \cfunction{Py_INCREF()} to become an independent
-owner. There are exactly two important exceptions to this rule:
-\cfunction{PyTuple_SetItem()} and \cfunction{PyList_SetItem()}. These
-functions take over ownership of the item passed to them --- even if
-they fail! (Note that \cfunction{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
-\cfunction{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.
-
-
-\subsection{Thin Ice
- \label{thinIce}}
-
-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
-\cfunction{Py_DECREF()} on an unrelated object while borrowing a
-reference to a list item. For instance:
-
-\begin{verbatim}
-void
-bug(PyObject *list)
-{
- PyObject *item = PyList_GetItem(list, 0);
-
- PyList_SetItem(list, 1, PyInt_FromLong(0L));
- PyObject_Print(item, stdout, 0); /* BUG! */
-}
-\end{verbatim}
-
-This function first borrows a reference to \code{list[0]}, then
-replaces \code{list[1]} with the value \code{0}, and finally prints
-the borrowed reference. Looks harmless, right? But it's not!
-
-Let's follow the control flow into \cfunction{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 \method{__del__()} method. If this
-class instance has a reference count of 1, disposing of it will call
-its \method{__del__()} method.
-
-Since it is written in Python, the \method{__del__()} method can execute
-arbitrary Python code. Could it perhaps do something to invalidate
-the reference to \code{item} in \cfunction{bug()}? You bet! Assuming
-that the list passed into \cfunction{bug()} is accessible to the
-\method{__del__()} method, it could execute a statement to the effect of
-\samp{del list[0]}, and assuming this was the last reference to that
-object, it would free the memory associated with it, thereby
-invalidating \code{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:
-
-\begin{verbatim}
-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);
-}
-\end{verbatim}
-
-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 \method{__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
-\csimplemacro{Py_BEGIN_ALLOW_THREADS}, and to re-acquire it using
-\csimplemacro{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:
-
-\begin{verbatim}
-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! */
-}
-\end{verbatim}
-
-
-\subsection{NULL Pointers
- \label{nullPointers}}
-
-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
-\cfunction{malloc()} or from a function that may raise an exception.
-
-The macros \cfunction{Py_INCREF()} and \cfunction{Py_DECREF()}
-do not check for \NULL{} pointers --- however, their variants
-\cfunction{Py_XINCREF()} and \cfunction{Py_XDECREF()} do.
-
-The macros for checking for a particular object type
-(\code{Py\var{type}_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 (\code{args} in the examples) is never
-\NULL{} --- in fact it guarantees that it is always a tuple.\footnote{
-These guarantees don't hold when you use the ``old'' style
-calling convention --- this is still found in much existing code.}
-
-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.
-
-
-\section{Writing Extensions in \Cpp
- \label{cplusplus}}
-
-It is possible to write extension modules in \Cpp. 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 \Cpp{} compiler. Functions that will be called by the
-Python interpreter (in particular, module initialization functions)
-have to be declared using \code{extern "C"}.
-It is unnecessary to enclose the Python header files in
-\code{extern "C" \{...\}} --- they use this form already if the symbol
-\samp{__cplusplus} is defined (all recent \Cpp{} compilers define this
-symbol).
-
-
-\section{Providing a C API for an Extension Module
- \label{using-cobjects}}
-\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 \emph{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 \module{spam} module from
-section~\ref{simpleExample}. The function \function{spam.system()}
-does not call the C library function \cfunction{system()} directly,
-but a function \cfunction{PySpam_System()}, which would of course do
-something more complicated in reality (such as adding ``spam'' to
-every command). This function \cfunction{PySpam_System()} is also
-exported to other extension modules.
-
-The function \cfunction{PySpam_System()} is a plain C function,
-declared \keyword{static} like everything else:
-
-\begin{verbatim}
-static int
-PySpam_System(const char *command)
-{
- return system(command);
-}
-\end{verbatim}
-
-The function \cfunction{spam_system()} is modified in a trivial way:
-
-\begin{verbatim}
-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);
-}
-\end{verbatim}
-
-In the beginning of the module, right after the line
-
-\begin{verbatim}
-#include "Python.h"
-\end{verbatim}
-
-two more lines must be added:
-
-\begin{verbatim}
-#define SPAM_MODULE
-#include "spammodule.h"
-\end{verbatim}
-
-The \code{\#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:
-
-\begin{verbatim}
-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);
-}
-\end{verbatim}
-
-Note that \code{PySpam_API} is declared \keyword{static}; otherwise
-the pointer array would disappear when \function{initspam()} terminates!
-
-The bulk of the work is in the header file \file{spammodule.h},
-which looks like this:
-
-\begin{verbatim}
-#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) */
-\end{verbatim}
-
-All that a client module must do in order to have access to the
-function \cfunction{PySpam_System()} is to call the function (or
-rather macro) \cfunction{import_spam()} in its initialization
-function:
-
-\begin{verbatim}
-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 */
-}
-\end{verbatim}
-
-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 \citetitle[../api/api.html]{Python/C API
-Reference Manual} in the section
-``\ulink{CObjects}{../api/cObjects.html}'' and in the implementation
-of CObjects (files \file{Include/cobject.h} and
-\file{Objects/cobject.c} in the Python source code distribution).
diff --git a/Doc/ext/newtypes.tex b/Doc/ext/newtypes.tex
deleted file mode 100644
index feed54d..0000000
--- a/Doc/ext/newtypes.tex
+++ /dev/null
@@ -1,1758 +0,0 @@
-\chapter{Defining New Types
- \label{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.
-
-\begin{notice}
-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
-\ulink{older versions of this documentation}
- {http://www.python.org/doc/versions/}.
-\end{notice}
-
-\section{The Basics
- \label{dnt-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 \code{[].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:
-
-\verbatiminput{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:
-
-\begin{verbatim}
-typedef struct {
- PyObject_HEAD
-} noddy_NoddyObject;
-\end{verbatim}
-
-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 \code{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 \code{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:
-
-\begin{verbatim}
-typedef struct {
- PyObject_HEAD
- long ob_ival;
-} PyIntObject;
-\end{verbatim}
-
-Moving on, we come to the crunch --- the type object.
-
-\begin{verbatim}
-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 */
-};
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
- PyObject_HEAD_INIT(NULL)
-\end{verbatim}
-
-This line is a bit of a wart; what we'd like to write is:
-
-\begin{verbatim}
- PyObject_HEAD_INIT(&PyType_Type)
-\end{verbatim}
-
-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 \cfunction{PyType_Ready()}.
-
-\begin{verbatim}
- 0, /* ob_size */
-\end{verbatim}
-
-The \member{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.
-
-\begin{verbatim}
- "noddy.Noddy", /* tp_name */
-\end{verbatim}
-
-The name of our type. This will appear in the default textual
-representation of our objects and in some error messages, for example:
-
-\begin{verbatim}
->>> "" + noddy.new_noddy()
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-TypeError: cannot add type "noddy.Noddy" to string
-\end{verbatim}
-
-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
-\module{noddy} and the type is \class{Noddy}, so we set the type name
-to \class{noddy.Noddy}.
-
-\begin{verbatim}
- sizeof(noddy_NoddyObject), /* tp_basicsize */
-\end{verbatim}
-
-This is so that Python knows how much memory to allocate when you call
-\cfunction{PyObject_New()}.
-
-\note{If you want your type to be subclassable from Python, and your
-type has the same \member{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 \member{__bases__}, or
-else it will not be able to call your type's \method{__new__} method
-without getting an error. You can avoid this problem by ensuring
-that your type has a larger value for \member{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.}
-
-\begin{verbatim}
- 0, /* tp_itemsize */
-\end{verbatim}
-
-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 \constant{Py_TPFLAGS_DEFAULT}.
-
-\begin{verbatim}
- Py_TPFLAGS_DEFAULT, /*tp_flags*/
-\end{verbatim}
-
-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 \member{tp_doc}.
-
-\begin{verbatim}
- "Noddy objects", /* tp_doc */
-\end{verbatim}
-
-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
-\member{tp_new} implementation. In this case, we can just use the
-default implementation provided by the API function
-\cfunction{PyType_GenericNew()}. We'd like to just assign this to the
-\member{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 \member{tp_new} slot in the module initialization function
-just before calling \cfunction{PyType_Ready()}:
-
-\begin{verbatim}
- noddy_NoddyType.tp_new = PyType_GenericNew;
- if (PyType_Ready(&noddy_NoddyType) < 0)
- return;
-\end{verbatim}
-
-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 \cfunction{initnoddy()}:
-
-\begin{verbatim}
- if (PyType_Ready(&noddy_NoddyType) < 0)
- return;
-\end{verbatim}
-
-This initializes the \class{Noddy} type, filing in a number of
-members, including \member{ob_type} that we initially set to \NULL.
-
-\begin{verbatim}
- PyModule_AddObject(m, "Noddy", (PyObject *)&noddy_NoddyType);
-\end{verbatim}
-
-This adds the type to the module dictionary. This allows us to create
-\class{Noddy} instances by calling the \class{Noddy} class:
-
-\begin{verbatim}
->>> import noddy
->>> mynoddy = noddy.Noddy()
-\end{verbatim}
-
-That's it! All that remains is to build it; put the above code in a
-file called \file{noddy.c} and
-
-\begin{verbatim}
-from distutils.core import setup, Extension
-setup(name="noddy", version="1.0",
- ext_modules=[Extension("noddy", ["noddy.c"])])
-\end{verbatim}
-
-in a file called \file{setup.py}; then typing
-
-\begin{verbatim}
-$ python setup.py build
-\end{verbatim} %$ <-- bow to font-lock ;-(
-
-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
-\code{import noddy} and play around with Noddy objects.
-
-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.
-
-\subsection{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, \module{noddy2} that adds these capabilities:
-
-\verbatiminput{noddy2.c}
-
-This version of the module has a number of changes.
-
-We've added an extra include:
-
-\begin{verbatim}
-#include "structmember.h"
-\end{verbatim}
-
-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, \var{first},
-\var{last}, and \var{number}. The \var{first} and \var{last}
-variables are Python strings containing first and last names. The
-\var{number} attribute is an integer.
-
-The object structure is updated accordingly:
-
-\begin{verbatim}
-typedef struct {
- PyObject_HEAD
- PyObject *first;
- PyObject *last;
- int number;
-} Noddy;
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-static void
-Noddy_dealloc(Noddy* self)
-{
- Py_XDECREF(self->first);
- Py_XDECREF(self->last);
- self->ob_type->tp_free((PyObject*)self);
-}
-\end{verbatim}
-
-which is assigned to the \member{tp_dealloc} member:
-
-\begin{verbatim}
- (destructor)Noddy_dealloc, /*tp_dealloc*/
-\end{verbatim}
-
-This method decrements the reference counts of the two Python
-attributes. We use \cfunction{Py_XDECREF()} here because the
-\member{first} and \member{last} members could be \NULL. It then
-calls the \member{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:
-
-\begin{verbatim}
-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;
-}
-\end{verbatim}
-
-and install it in the \member{tp_new} member:
-
-\begin{verbatim}
- Noddy_new, /* tp_new */
-\end{verbatim}
-
-The new member is responsible for creating (as opposed to
-initializing) objects of the type. It is exposed in Python as the
-\method{__new__()} method. See the paper titled ``Unifying types and
-classes in Python'' for a detailed discussion of the \method{__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 \member{first} and
-\member{last} are not \NULL. If we didn't care whether the initial
-values were \NULL, we could have used \cfunction{PyType_GenericNew()} as
-our new method, as we did before. \cfunction{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 \member{tp_alloc} slot ourselves. Rather
-\cfunction{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 \member{tp_new} (one that
-calls a base type's \member{tp_new} or \method{__new__}), you
-must \emph{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 \member{tp_new}
-directly, or via \code{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 \exception{TypeError}.)}
-
-We provide an initialization function:
-
-\begin{verbatim}
-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;
-}
-\end{verbatim}
-
-by filling the \member{tp_init} slot.
-
-\begin{verbatim}
- (initproc)Noddy_init, /* tp_init */
-\end{verbatim}
-
-The \member{tp_init} slot is exposed in Python as the
-\method{__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
-\method{__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 \member{first} member like this:
-
-\begin{verbatim}
- if (first) {
- Py_XDECREF(self->first);
- Py_INCREF(first);
- self->first = first;
- }
-\end{verbatim}
-
-But this would be risky. Our type doesn't restrict the type of the
-\member{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 \member{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?
-\begin{itemize}
-\item when we absolutely know that the reference count is greater than
- 1
-\item when we know that deallocation of the object\footnote{This is
- true when we know that the object is a basic type, like a string or
- a float.} will not cause any
- calls back into our type's code
-\item when decrementing a reference count in a \member{tp_dealloc}
- handler when garbage-collections is not supported\footnote{We relied
- on this in the \member{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.}
-\end{itemize}
-
-
-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:
-
-\begin{verbatim}
-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 */
-};
-\end{verbatim}
-
-and put the definitions in the \member{tp_members} slot:
-
-\begin{verbatim}
- Noddy_members, /* tp_members */
-\end{verbatim}
-
-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, \method{name}, that outputs the objects
-name as the concatenation of the first and last names.
-
-\begin{verbatim}
-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;
-}
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
- def name(self):
- return "%s %s" % (self.first, self.last)
-\end{verbatim}
-
-Note that we have to check for the possibility that our \member{first}
-and \member{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:
-
-\begin{verbatim}
-static PyMethodDef Noddy_methods[] = {
- {"name", (PyCFunction)Noddy_name, METH_NOARGS,
- "Return the name, combining the first and last name"
- },
- {NULL} /* Sentinel */
-};
-\end{verbatim}
-
-and assign them to the \member{tp_methods} slot:
-
-\begin{verbatim}
- Noddy_methods, /* tp_methods */
-\end{verbatim}
-
-Note that we used the \constant{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 \constant{Py_TPFLAGS_BASETYPE} to our class flag
-definition:
-
-\begin{verbatim}
- Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
-\end{verbatim}
-
-We rename \cfunction{initnoddy()} to \cfunction{initnoddy2()}
-and update the module name passed to \cfunction{Py_InitModule3()}.
-
-Finally, we update our \file{setup.py} file to build the new module:
-
-\begin{verbatim}
-from distutils.core import setup, Extension
-setup(name="noddy", version="1.0",
- ext_modules=[
- Extension("noddy", ["noddy.c"]),
- Extension("noddy2", ["noddy2.c"]),
- ])
-\end{verbatim}
-
-\subsection{Providing finer control over data attributes}
-
-In this section, we'll provide finer control over how the
-\member{first} and \member{last} attributes are set in the
-\class{Noddy} example. In the previous version of our module, the
-instance variables \member{first} and \member{last} could be set to
-non-string values or even deleted. We want to make sure that these
-attributes always contain strings.
-
-\verbatiminput{noddy3.c}
-
-To provide greater control, over the \member{first} and \member{last}
-attributes, we'll use custom getter and setter functions. Here are
-the functions for getting and setting the \member{first} attribute:
-
-\begin{verbatim}
-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;
-}
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-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 */
-};
-\end{verbatim}
-
-and register it in the \member{tp_getset} slot:
-
-\begin{verbatim}
- Noddy_getseters, /* tp_getset */
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-static PyMemberDef Noddy_members[] = {
- {"number", T_INT, offsetof(Noddy, number), 0,
- "noddy number"},
- {NULL} /* Sentinel */
-};
-\end{verbatim}
-
-We also need to update the \member{tp_init} handler to only allow
-strings\footnote{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.} to be passed:
-
-\begin{verbatim}
-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;
-}
-\end{verbatim}
-
-With these changes, we can assure that the \member{first} and
-\member{last} members are never \NULL{} so we can remove checks for \NULL{}
-values in almost all cases. This means that most of the
-\cfunction{Py_XDECREF()} calls can be converted to \cfunction{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.
-
-\subsection{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:
-
-\begin{verbatim}
->>> l = []
->>> l.append(l)
->>> del l
-\end{verbatim}
-
-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 \member{first} or \member{last}
-attributes.\footnote{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.} This
-means that \class{Noddy} objects can participate in cycles:
-
-\begin{verbatim}
->>> import noddy2
->>> n = noddy2.Noddy()
->>> l = [n]
->>> n.first = l
-\end{verbatim}
-
-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:
-
-\verbatiminput{noddy4.c}
-
-The traversal method provides access to subobjects that
-could participate in cycles:
-
-\begin{verbatim}
-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;
-}
-\end{verbatim}
-
-For each subobject that can participate in cycles, we need to call the
-\cfunction{visit()} function, which is passed to the traversal method.
-The \cfunction{visit()} function takes as arguments the subobject and
-the extra argument \var{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 \cfunction{Py_VISIT()} macro that automates
-calling visit functions. With \cfunction{Py_VISIT()},
-\cfunction{Noddy_traverse()} can be simplified:
-
-
-\begin{verbatim}
-static int
-Noddy_traverse(Noddy *self, visitproc visit, void *arg)
-{
- Py_VISIT(self->first);
- Py_VISIT(self->last);
- return 0;
-}
-\end{verbatim}
-
-\note{Note that the \member{tp_traverse} implementation must name its
- arguments exactly \var{visit} and \var{arg} in order to use
- \cfunction{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:
-
-\begin{verbatim}
-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);
-}
-\end{verbatim}
-
-Notice the use of a temporary variable in \cfunction{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 \member{tp_traverse} handler could get called.
-We can't take a chance of having \cfunction{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 \cfunction{Py_CLEAR()} that automates
-the careful decrementing of reference counts. With
-\cfunction{Py_CLEAR()}, the \cfunction{Noddy_clear()} function can be
-simplified:
-
-\begin{verbatim}
-static int
-Noddy_clear(Noddy *self)
-{
- Py_CLEAR(self->first);
- Py_CLEAR(self->last);
- return 0;
-}
-\end{verbatim}
-
-Finally, we add the \constant{Py_TPFLAGS_HAVE_GC} flag to the class
-flags:
-
-\begin{verbatim}
- Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /*tp_flags*/
-\end{verbatim}
-
-That's pretty much it. If we had written custom \member{tp_alloc} or
-\member{tp_free} slots, we'd need to modify them for cyclic-garbage
-collection. Most extensions will use the versions automatically
-provided.
-
-\subsection{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 \method{increment()} method
-that increases an internal counter.
-
-\begin{verbatim}
->>> import shoddy
->>> s = shoddy.Shoddy(range(3))
->>> s.extend(s)
->>> print len(s)
-6
->>> print s.increment()
-1
->>> print s.increment()
-2
-\end{verbatim}
-
-\verbatiminput{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.
-
-\begin{verbatim}
-typedef struct {
- PyListObject list;
- int state;
-} Shoddy;
-\end{verbatim}
-
-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 \cfunction{PyObject_HEAD} at the beginning of its structure.
-
-When a Python object is a \class{Shoddy} instance, its \var{PyObject*} pointer
-can be safely cast to both \var{PyListObject*} and \var{Shoddy*}.
-
-\begin{verbatim}
-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;
-}
-\end{verbatim}
-
-In the \member{__init__} method for our type, we can see how to call through
-to the \member{__init__} method of the base type.
-
-This pattern is important when writing a type with custom \member{new} and
-\member{dealloc} methods. The \member{new} method should not actually create the
-memory for the object with \member{tp_alloc}, that will be handled by
-the base class when calling its \member{tp_new}.
-
-When filling out the \cfunction{PyTypeObject} for the \class{Shoddy} type,
-you see a slot for \cfunction{tp_base}. Due to cross platform compiler
-issues, you can't fill that field directly with the \cfunction{PyList_Type};
-it can be done later in the module's \cfunction{init} function.
-
-\begin{verbatim}
-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);
-}
-\end{verbatim}
-
-Before calling \cfunction{PyType_Ready}, the type structure must have the
-\member{tp_base} slot filled in. When we are deriving a new type, it is
-not necessary to fill out the \member{tp_alloc} slot with
-\cfunction{PyType_GenericNew} -- the allocate function from the base type
-will be inherited.
-
-After that, calling \cfunction{PyType_Ready} and adding the type object
-to the module is the same as with the basic \class{Noddy} examples.
-
-
-\section{Type Methods
- \label{dnt-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:
-
-\verbatiminput{typestruct.h}
-
-Now that's a \emph{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 \code{0}) and then change the values
-to suit your new type.
-
-\begin{verbatim}
- char *tp_name; /* For printing */
-\end{verbatim}
-
-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!
-
-\begin{verbatim}
- int tp_basicsize, tp_itemsize; /* For allocation */
-\end{verbatim}
-
-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 \member{tp_itemsize} field comes in. This will be dealt with
-later.
-
-\begin{verbatim}
- char *tp_doc;
-\end{verbatim}
-
-Here you can put a string (or its address) that you want returned when
-the Python script references \code{obj.__doc__} to retrieve the
-doc string.
-
-Now we come to the basic type methods---the ones most extension types
-will implement.
-
-
-\subsection{Finalization and De-allocation}
-
-\index{object!deallocation}
-\index{deallocation, object}
-\index{object!finalization}
-\index{finalization, of objects}
-
-\begin{verbatim}
- destructor tp_dealloc;
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-static void
-newdatatype_dealloc(newdatatypeobject * obj)
-{
- free(obj->obj_UnderlyingDatatypePtr);
- obj->ob_type->tp_free(obj);
-}
-\end{verbatim}
-
-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
-\cfunction{PyErr_Fetch()}\ttindex{PyErr_Fetch()} and
-\cfunction{PyErr_Restore()}\ttindex{PyErr_Restore()} functions:
-
-\begin{verbatim}
-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);
-}
-\end{verbatim}
-
-
-\subsection{Object Presentation}
-
-In Python, there are two ways to generate a textual representation
-of an object: the \function{repr()}\bifuncindex{repr} function, and
-the \function{str()}\bifuncindex{str} function. (The
-\keyword{print} function just calls \function{str()}.)
-
-These handlers are both optional.
-
-\begin{verbatim}
- reprfunc tp_repr;
- reprfunc tp_str;
-\end{verbatim}
-
-The \member{tp_repr} handler should return a string object containing
-a representation of the instance for which it is called. Here is a
-simple example:
-
-\begin{verbatim}
-static PyObject *
-newdatatype_repr(newdatatypeobject * obj)
-{
- return PyString_FromFormat("Repr-ified_newdatatype{{size:\%d}}",
- obj->obj_UnderlyingDatatypePtr->size);
-}
-\end{verbatim}
-
-If no \member{tp_repr} handler is specified, the interpreter will
-supply a representation that uses the type's \member{tp_name} and a
-uniquely-identifying value for the object.
-
-The \member{tp_str} handler is to \function{str()} what the
-\member{tp_repr} handler described above is to \function{repr()}; that
-is, it is called when Python code calls \function{str()} on an
-instance of your object. Its implementation is very similar to the
-\member{tp_repr} function, but the resulting string is intended for
-human consumption. If \member{tp_str} is not specified, the
-\member{tp_repr} handler is used instead.
-
-Here is a simple example:
-
-\begin{verbatim}
-static PyObject *
-newdatatype_str(newdatatypeobject * obj)
-{
- return PyString_FromFormat("Stringified_newdatatype{{size:\%d}}",
- obj->obj_UnderlyingDatatypePtr->size);
-}
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-print node
-\end{verbatim}
-
-There is a flags argument and one flag, \constant{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:
-
-\begin{verbatim}
-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;
-}
-\end{verbatim}
-
-
-\subsection{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.
-
-\begin{verbatim}
- getattrfunc tp_getattr; /* char * version */
- setattrfunc tp_setattr;
- /* ... */
- getattrofunc tp_getattrofunc; /* PyObject * version */
- setattrofunc tp_setattrofunc;
-\end{verbatim}
-
-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.
-
-
-\subsubsection{Generic Attribute Management}
-
-\versionadded{2.2}
-
-Most extension types only use \emph{simple} attributes. So, what
-makes the attributes simple? There are only a couple of conditions
-that must be met:
-
-\begin{enumerate}
- \item The name of the attributes must be known when
- \cfunction{PyType_Ready()} is called.
-
- \item 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.
-\end{enumerate}
-
-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 \cfunction{PyType_Ready()} is called, it uses three tables
-referenced by the type object to create \emph{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 \member{tp_getattro} and \member{tp_setattro} fields \NULL{} as
-well, allowing the base type to handle attributes.
-
-The tables are declared as three fields of the type object:
-
-\begin{verbatim}
- struct PyMethodDef *tp_methods;
- struct PyMemberDef *tp_members;
- struct PyGetSetDef *tp_getset;
-\end{verbatim}
-
-If \member{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:
-
-\begin{verbatim}
-typedef struct PyMethodDef {
- char *ml_name; /* method name */
- PyCFunction ml_meth; /* implementation function */
- int ml_flags; /* flags */
- char *ml_doc; /* docstring */
-} PyMethodDef;
-\end{verbatim}
-
-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 \member{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:
-
-\begin{verbatim}
-typedef struct PyMemberDef {
- char *name;
- int type;
- int offset;
- int flags;
- char *doc;
-} PyMemberDef;
-\end{verbatim}
-
-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 \member{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 \member{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.
-
-\begin{tableii}{l|l}{constant}{Constant}{Meaning}
- \lineii{READONLY \ttindex{READONLY}}
- {Never writable.}
- \lineii{RO \ttindex{RO}}
- {Shorthand for \constant{READONLY}.}
- \lineii{READ_RESTRICTED \ttindex{READ_RESTRICTED}}
- {Not readable in restricted mode.}
- \lineii{WRITE_RESTRICTED \ttindex{WRITE_RESTRICTED}}
- {Not writable in restricted mode.}
- \lineii{RESTRICTED \ttindex{RESTRICTED}}
- {Not readable or writable in restricted mode.}
-\end{tableii}
-
-An interesting advantage of using the \member{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 \member{__doc__} attribute.
-
-As with the \member{tp_methods} table, a sentinel entry with a
-\member{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;
-
-
-\subsubsection{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 \member{tp_getattr} handler is called when the object requires an
-attribute look-up. It is called in the same situations where the
-\method{__getattr__()} method of a class would be called.
-
-A likely way to handle this is (1) to implement a set of functions
-(such as \cfunction{newdatatype_getSize()} and
-\cfunction{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 \member{tp_methods} field
-of the type object.
-
-Here is an example:
-
-\begin{verbatim}
-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);
-}
-\end{verbatim}
-
-The \member{tp_setattr} handler is called when the
-\method{__setattr__()} or \method{__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
-\member{tp_setattr} handler should be set to \NULL.
-
-\begin{verbatim}
-static int
-newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
-{
- (void)PyErr_Format(PyExc_RuntimeError, "Read-only attribute: \%s", name);
- return -1;
-}
-\end{verbatim}
-
-
-\subsection{Object Comparison}
-
-\begin{verbatim}
- cmpfunc tp_compare;
-\end{verbatim}
-
-The \member{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 \cfunction{PyObject_Compare()} or \cfunction{PyObject_Cmp()}
-functions are used, or if \function{cmp()} is used from Python.)
-It is analogous to the \method{__cmp__()} method. This function
-should return \code{-1} if \var{obj1} is less than
-\var{obj2}, \code{0} if they are equal, and \code{1} if
-\var{obj1} is greater than
-\var{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 \member{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 \cfunction{PyErr_Occurred()}.
-
-
-Here is a sample implementation:
-
-\begin{verbatim}
-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;
-}
-\end{verbatim}
-
-
-\subsection{Abstract Protocol Support}
-
-Python supports a variety of \emph{abstract} `protocols;' the specific
-interfaces provided to use these interfaces are documented in the
-\citetitle[../api/api.html]{Python/C API Reference Manual} in the
-chapter ``\ulink{Abstract Objects Layer}{../api/abstract.html}.''
-
-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.)
-
-\begin{verbatim}
- PyNumberMethods tp_as_number;
- PySequenceMethods tp_as_sequence;
- PyMappingMethods tp_as_mapping;
-\end{verbatim}
-
-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.
-
-
-\begin{verbatim}
- hashfunc tp_hash;
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-static long
-newdatatype_hash(newdatatypeobject *obj)
-{
- long result;
- result = obj->obj_UnderlyingDatatypePtr->size;
- result = result * 3;
- return result;
-}
-\end{verbatim}
-
-\begin{verbatim}
- ternaryfunc tp_call;
-\end{verbatim}
-
-This function is called when an instance of your data type is "called",
-for example, if \code{obj1} is an instance of your data type and the Python
-script contains \code{obj1('hello')}, the \member{tp_call} handler is
-invoked.
-
-This function takes three arguments:
-
-\begin{enumerate}
- \item
- \var{arg1} is the instance of the data type which is the subject of
- the call. If the call is \code{obj1('hello')}, then \var{arg1} is
- \code{obj1}.
-
- \item
- \var{arg2} is a tuple containing the arguments to the call. You
- can use \cfunction{PyArg_ParseTuple()} to extract the arguments.
-
- \item
- \var{arg3} is a dictionary of keyword arguments that were passed.
- If this is non-\NULL{} and you support keyword arguments, use
- \cfunction{PyArg_ParseTupleAndKeywords()} to extract the
- arguments. If you do not want to support keyword arguments and
- this is non-\NULL, raise a \exception{TypeError} with a message
- saying that keyword arguments are not supported.
-\end{enumerate}
-
-Here is a desultory example of the implementation of the call function.
-
-\begin{verbatim}
-/* 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;
-}
-\end{verbatim}
-
-XXX some fields need to be added here...
-
-
-\begin{verbatim}
- /* Added in release 2.2 */
- /* Iterators */
- getiterfunc tp_iter;
- iternextfunc tp_iternext;
-\end{verbatim}
-
-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 \code{tp_iter}
-handler. Objects which are returned by a \code{tp_iter} handler must
-implement both the \code{tp_iter} and \code{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
-\code{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 \code{tp_iternext} handler. File objects are an
-example of such an iterator.
-
-Iterator objects should implement both handlers. The \code{tp_iter}
-handler should return a new reference to the iterator (this is the
-same as the \code{tp_iter} handler for objects which can only be
-iterated over destructively). The \code{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 \exception{StopIteration};
-avoiding the exception can yield slightly better performance. If an
-actual error occurs, it should set an exception and return \NULL.
-
-
-\subsection{Weak Reference Support\label{weakref-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 \member{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:
-
-\begin{verbatim}
-typedef struct {
- PyObject_HEAD
- PyClassObject *in_class; /* The class object */
- PyObject *in_dict; /* A dictionary */
- PyObject *in_weakreflist; /* List of weak references */
-} PyInstanceObject;
-\end{verbatim}
-
-The statically-declared type object for instances is defined this way:
-
-\begin{verbatim}
-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 */
-};
-\end{verbatim}
-
-The type constructor is responsible for initializing the weak reference
-list to \NULL:
-
-\begin{verbatim}
-static PyObject *
-instance_new() {
- /* Other initialization stuff omitted for brevity */
-
- self->in_weakreflist = NULL;
-
- return (PyObject *) self;
-}
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-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. */
-}
-\end{verbatim}
-
-
-\subsection{More Suggestions}
-
-Remember that you can omit most of these functions, in which case you
-provide \code{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 \code{tp_} plus the function you want (for
-example, \code{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 \cfunction{PyObject_TypeCheck} function.
-A sample of its use might be something like the following:
-
-\begin{verbatim}
- if (! PyObject_TypeCheck(some_object, &MyType)) {
- PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");
- return NULL;
- }
-\end{verbatim}
diff --git a/Doc/ext/noddy.c b/Doc/ext/noddy.c
deleted file mode 100644
index ec2d669..0000000
--- a/Doc/ext/noddy.c
+++ /dev/null
@@ -1,54 +0,0 @@
-#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);
-}
diff --git a/Doc/ext/noddy2.c b/Doc/ext/noddy2.c
deleted file mode 100644
index 2caf985..0000000
--- a/Doc/ext/noddy2.c
+++ /dev/null
@@ -1,190 +0,0 @@
-#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);
-}
diff --git a/Doc/ext/noddy3.c b/Doc/ext/noddy3.c
deleted file mode 100644
index 60260ad..0000000
--- a/Doc/ext/noddy3.c
+++ /dev/null
@@ -1,243 +0,0 @@
-#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);
-}
diff --git a/Doc/ext/noddy4.c b/Doc/ext/noddy4.c
deleted file mode 100644
index 878e086..0000000
--- a/Doc/ext/noddy4.c
+++ /dev/null
@@ -1,224 +0,0 @@
-#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);
-}
diff --git a/Doc/ext/run-func.c b/Doc/ext/run-func.c
deleted file mode 100644
index 5a7df0d..0000000
--- a/Doc/ext/run-func.c
+++ /dev/null
@@ -1,68 +0,0 @@
-#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;
-}
diff --git a/Doc/ext/setup.py b/Doc/ext/setup.py
deleted file mode 100644
index b853d23..0000000
--- a/Doc/ext/setup.py
+++ /dev/null
@@ -1,8 +0,0 @@
-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"]),
- ])
diff --git a/Doc/ext/shoddy.c b/Doc/ext/shoddy.c
deleted file mode 100644
index 07a4177..0000000
--- a/Doc/ext/shoddy.c
+++ /dev/null
@@ -1,91 +0,0 @@
-#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);
-}
diff --git a/Doc/ext/test.py b/Doc/ext/test.py
deleted file mode 100644
index 7ebf46a..0000000
--- a/Doc/ext/test.py
+++ /dev/null
@@ -1,213 +0,0 @@
-"""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__)
diff --git a/Doc/ext/windows.tex b/Doc/ext/windows.tex
deleted file mode 100644
index f9de548..0000000
--- a/Doc/ext/windows.tex
+++ /dev/null
@@ -1,320 +0,0 @@
-\chapter{Building C and \Cpp{} Extensions on Windows%
- \label{building-on-windows}}
-
-
-This chapter briefly explains how to create a Windows extension module
-for Python using Microsoft Visual \Cpp, 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 \Cpp.
-
-\begin{notice}
- This chapter mentions a number of filenames that include an encoded
- Python version number. These filenames are represented with the
- version number shown as \samp{XY}; in practive, \character{X} will
- be the major version number and \character{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, \samp{XY} will actually be
- \samp{22}.
-\end{notice}
-
-
-\section{A Cookbook Approach \label{win-cookbook}}
-
-There are two approaches to building extension modules on Windows,
-just as there are on \UNIX: use the
-\ulink{\module{distutils}}{../lib/module-distutils.html} package to
-control the build process, or do things manually. The distutils
-approach works well for most extensions; documentation on using
-\ulink{\module{distutils}}{../lib/module-distutils.html} to build and
-package extension modules is available in
-\citetitle[../dist/dist.html]{Distributing Python Modules}. This
-section describes the manual approach to building Python extensions
-written in C or \Cpp.
-
-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 \Cpp{} ``Developer Studio''; project
-files are supplied for V\Cpp{} version 7.1, but you can use older
-versions of V\Cpp. Notice that you should use the same version of
-V\Cpp that was used to build Python itself. The example files
-described here are distributed with the Python sources in the
-\file{PC\textbackslash example_nt\textbackslash} directory.
-
-\begin{enumerate}
- \item
- \strong{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.
-
- \item
- \strong{Open the project}\\
- From V\Cpp, use the \menuselection{File \sub Open Solution}
- dialog (not \menuselection{File \sub Open}!). Navigate to and
- select the file \file{example.sln}, in the \emph{copy} of the
- \file{example_nt} directory you made above. Click Open.
-
- \item
- \strong{Build the example DLL}\\
- In order to check that everything is set up right, try building:
-
- \begin{enumerate}
- \item
- Select a configuration. This step is optional. Choose
- \menuselection{Build \sub Configuration Manager \sub Active
- Solution Configuration} and select either \guilabel{Release}
- or\guilabel{Debug}. If you skip this step,
- V\Cpp{} will use the Debug configuration by default.
-
- \item
- Build the DLL. Choose \menuselection{Build \sub 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.
- \end{enumerate}
-
- \item
- \strong{Testing the debug-mode DLL}\\
- Once the Debug build has succeeded, bring up a DOS box, and change
- to the \file{example_nt\textbackslash Debug} directory. You
- should now be able to repeat the following session (\code{C>} is
- the DOS prompt, \code{>>>} is the Python prompt; note that
- build information and various debug output from Python may not
- match this screen dump exactly):
-
-\begin{verbatim}
-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]
->>>
-\end{verbatim}
-
- Congratulations! You've successfully built your first Python
- extension module.
-
- \item
- \strong{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 \module{spam} if its initialization function
- is called \cfunction{initspam()}, and it should call
- \cfunction{Py_InitModule()} with the string \code{"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:
-
- \begin{enumerate}
- \item Copy \file{example.sln} and \file{example.vcproj}, rename
- them to \file{spam.*}, and edit them by hand, or
- \item Create a brand new project; instructions are below.
- \end{enumerate}
-
- In either case, copy \file{example_nt\textbackslash example.def}
- to \file{spam\textbackslash spam.def}, and edit the new
- \file{spam.def} so its second line contains the string
- `\code{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
- \programopt{/export:initspam} somewhere to the Link settings, by
- manually editing the setting in Project Properties dialog).
-
- \item
- \strong{Creating a brand new project}\\
- Use the \menuselection{File \sub New \sub Project} dialog to
- create a new Project Workspace. Select \guilabel{Visual C++
- Projects/Win32/ Win32 Project}, enter the name (\samp{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 \sub Add Existing Item}. Set the pattern to
- \code{*.*} 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 \sub 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/\Cpp{} 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}:
-
-\begin{verbatim}
-..\Include,..\PC
-\end{verbatim}
-
- Then, choose the General category in the Linker tab, and enter
-
-\begin{verbatim}
-..\PCbuild
-\end{verbatim}
-
- 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 \code{pythonXY.lib} to the
- list in the \guilabel{Additional Dependencies} box.
-
- Select \guilabel{Debug} in the \guilabel{Configuration} dropdown
- list, and append \code{pythonXY_d.lib} to the list in the
- \guilabel{Additional Dependencies} box. Then click the C/\Cpp{}
- 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.
-\end{enumerate}
-
-
-If your module creates a new type, you may have trouble with this line:
-
-\begin{verbatim}
- PyObject_HEAD_INIT(&PyType_Type)
-\end{verbatim}
-
-Change it to:
-
-\begin{verbatim}
- PyObject_HEAD_INIT(NULL)
-\end{verbatim}
-
-and add the following to the module initialization function:
-
-\begin{verbatim}
- MyObject_Type.ob_type = &PyType_Type;
-\end{verbatim}
-
-Refer to section~3 of the
-\citetitle[http://www.python.org/doc/FAQ.html]{Python FAQ} for details
-on why you must do this.
-
-
-\section{Differences Between \UNIX{} and Windows
- \label{dynamic-linking}}
-\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 \emph{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 \emph{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 \samp{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
-\samp{from spam import *}; it does create a separate copy.
-
-
-\section{Using DLLs in Practice \label{win-dlls}}
-\sectionauthor{Chris Phoenix}{cphoenix@best.com}
-
-Windows Python is built in Microsoft Visual \Cpp; using other
-compilers may or may not work (though Borland seems to). The rest of
-this section is MSV\Cpp{} 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:
-
-\begin{verbatim}
-cl /LD /I/python/include spam.c ../libs/pythonXY.lib
-cl /LD /I/python/include ni.c spam.lib ../libs/pythonXY.lib
-\end{verbatim}
-
-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 \cfunction{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 \samp{_declspec(dllexport)}, as in \samp{void
-_declspec(dllexport) initspam(void)} or \samp{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
-\emph{ignore default libraries}. Add the correct
-\file{msvcrt\var{xx}.lib} to the list of libraries.
diff --git a/Doc/howto/Makefile b/Doc/howto/Makefile
deleted file mode 100644
index 18110a2..0000000
--- a/Doc/howto/Makefile
+++ /dev/null
@@ -1,84 +0,0 @@
-# Makefile for the HOWTO directory
-# LaTeX HOWTOs can be turned into HTML, PDF, PS, DVI or plain text output.
-# reST HOWTOs can only be turned into HTML.
-
-# Variables to change
-
-# Paper size for non-HTML formats (letter or a4)
-PAPER=letter
-
-# Arguments to rst2html.py, and location of the script
-RSTARGS = --input-encoding=utf-8
-RST2HTML = rst2html.py
-
-# List of HOWTOs that aren't to be processed. This should contain the
-# base name of the HOWTO without any extension (e.g. 'advocacy',
-# 'unicode').
-REMOVE_HOWTOS =
-
-MKHOWTO=../tools/mkhowto
-WEBDIR=.
-PAPERDIR=../paper-$(PAPER)
-HTMLDIR=../html
-
-# Determine list of files to be built
-TEX_SOURCES = $(wildcard *.tex)
-RST_SOURCES = $(wildcard *.rst)
-TEX_NAMES = $(filter-out $(REMOVE_HOWTOS),$(patsubst %.tex,%,$(TEX_SOURCES)))
-
-PAPER_PATHS=$(addprefix $(PAPERDIR)/,$(TEX_NAMES))
-DVI =$(addsuffix .dvi,$(PAPER_PATHS))
-PDF =$(addsuffix .pdf,$(PAPER_PATHS))
-PS =$(addsuffix .ps,$(PAPER_PATHS))
-
-ALL_HOWTO_NAMES = $(TEX_NAMES) $(patsubst %.rst,%,$(RST_SOURCES))
-HOWTO_NAMES = $(filter-out $(REMOVE_HOWTOS),$(ALL_HOWTO_NAMES))
-HTML = $(addprefix $(HTMLDIR)/,$(HOWTO_NAMES))
-
-# Rules for building various formats
-
-# reST to HTML
-$(HTMLDIR)/%: %.rst
- if [ ! -d $@ ] ; then mkdir $@ ; fi
- $(RST2HTML) $(RSTARGS) $< >$@/index.html
-
-# LaTeX to various output formats
-$(PAPERDIR)/%.dvi : %.tex
- $(MKHOWTO) --dvi $<
- mv $*.dvi $@
-
-$(PAPERDIR)/%.pdf : %.tex
- $(MKHOWTO) --pdf $<
- mv $*.pdf $@
-
-$(PAPERDIR)/%.ps : %.tex
- $(MKHOWTO) --ps $<
- mv $*.ps $@
-
-$(HTMLDIR)/% : %.tex
- $(MKHOWTO) --html --iconserver="." --dir $@ $<
-
-# Rule that isn't actually used -- we no longer support the 'txt' target.
-$(PAPERDIR)/%.txt : %.tex
- $(MKHOWTO) --text $<
- mv $@ txt
-
-default:
- @echo "'all' -- build all files"
- @echo "'dvi', 'pdf', 'ps', 'html' -- build one format"
-
-all: dvi pdf ps html
-
-.PHONY : dvi pdf ps html
-dvi: $(DVI)
-pdf: $(PDF)
-ps: $(PS)
-html: $(HTML)
-
-clean:
- rm -f *~ *.log *.ind *.l2h *.aux *.toc *.how *.bkm
- rm -f *.dvi *.pdf *.ps
-
-clobber:
- rm -rf $(HTML)
- rm -rf $(DVI) $(PDF) $(PS)
diff --git a/Doc/howto/TODO b/Doc/howto/TODO
deleted file mode 100644
index c229828..0000000
--- a/Doc/howto/TODO
+++ /dev/null
@@ -1,13 +0,0 @@
-
-Short-term tasks:
- Quick revision pass to make HOWTOs match the current state of Python
-doanddont regex sockets
-
-Medium-term tasks:
- Revisit the regex howto.
- * Add exercises with answers for each section
- * More examples?
-
-Long-term tasks:
- Integrate with other Python docs?
-
diff --git a/Doc/howto/advocacy.tex b/Doc/howto/advocacy.tex
deleted file mode 100644
index 9074b3f..0000000
--- a/Doc/howto/advocacy.tex
+++ /dev/null
@@ -1,411 +0,0 @@
-
-\documentclass{howto}
-
-\title{Python Advocacy HOWTO}
-
-\release{0.03}
-
-\author{A.M. Kuchling}
-\authoraddress{\email{amk@amk.ca}}
-
-\begin{document}
-\maketitle
-
-\begin{abstract}
-\noindent
-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 \emph{shouldn't}
-try to use Python.
-
-This document is available from the Python HOWTO page at
-\url{http://www.python.org/doc/howto}.
-
-\end{abstract}
-
-\tableofcontents
-
-\section{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.
-
- \subsection{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 \samp{Date} to a value such as \samp{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.
-
- \subsection{Prototyping}
-
-In \emph{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
-\code{eval()}, or regular expressions, or the \module{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 \Cpp, shipping with some \Cpp code and some Python code. Version
-3.0 didn't contain any Python at all; all the code had been translated
-into \Cpp. 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 \code{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.
-
- \subsection{Simplicity and Ease of Understanding}
-
-Python is definitely \emph{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 \emph{The New Hacker's Dictionary}, Eric S. Raymond gives the following
-definition for "compact":
-
-\begin{quotation}
- Compact \emph{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).
-\end{quotation}
-
-(From \url{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 \code{import math}, and
-you create a new namespace called \samp{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 \url{http://www.cwi.nl/~steven/abc/} and
-\url{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.
-
- \subsection{Java Integration}
-
-If you're working with Java, Jython
-(\url{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.
-
-\section{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.
-
-\emph{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 \url{http://www.opensource.org}.
-
-\emph{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.
-
-\emph{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:
-
-\begin{itemize}
-\item Run Web sites
-\item Write GUI interfaces
-\item Control
-number-crunching code on supercomputers
-\item Make a commercial application scriptable by embedding the Python
-interpreter inside it
-\item Process large XML data sets
-\item Build test suites for C or Java code
-\end{itemize}
-
-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 \url{http://wiki.python.org/moin/OrganizationsUsingPython} for a list of some of the
-organizations that use Python.
-
-\emph{What are the restrictions on Python's use?}
-
-They're practically nonexistent. Consult the \file{Misc/COPYRIGHT}
-file in the source distribution, or
-\url{http://www.python.org/doc/Copyright.html} for the full language,
-but it boils down to three conditions.
-
-\begin{itemize}
-
-\item 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.
-
-\item Don't claim that the institutions that have developed Python
-endorse your product in any way.
-
-\item If something goes wrong, you can't sue for damages. Practically
-all software licences contain this condition.
-
-\end{itemize}
-
-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.
-
-\emph{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.
-
-
-\section{Useful Resources}
-
-\begin{definitions}
-
-
-\term{\url{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.
-
-\term{\url{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.
-
-\term{\url{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:
-
-\begin{quotation}
- 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.
-\end{quotation}
-
-\term{\url{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.
-
-\term{\url{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.
-
-\term{\url{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.
-
-\term{\url{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.
-
-\end{definitions}
-
-\end{document}
-
-
diff --git a/Doc/howto/curses.tex b/Doc/howto/curses.tex
deleted file mode 100644
index 3e4cada..0000000
--- a/Doc/howto/curses.tex
+++ /dev/null
@@ -1,486 +0,0 @@
-\documentclass{howto}
-
-\title{Curses Programming with Python}
-
-\release{2.02}
-
-\author{A.M. Kuchling, Eric S. Raymond}
-\authoraddress{\email{amk@amk.ca}, \email{esr@thyrsus.com}}
-
-\begin{document}
-\maketitle
-
-\begin{abstract}
-\noindent
-This document describes how to write text-mode programs with Python 2.x,
-using the \module{curses} extension module to control the display.
-
-This document is available from the Python HOWTO page at
-\url{http://www.python.org/doc/howto}.
-\end{abstract}
-
-\tableofcontents
-
-\section{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
-\url{http://effbot.org/efflib/console}.
-
-\subsection{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 \function{addstr},
-\function{mvaddstr}, \function{mvwaddstr}, into a single
-\method{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.
-
-\section{Starting and ending a curses application}
-
-Before doing anything, curses must be initialized. This is done by
-calling the \function{initscr()} function, which will determine the
-terminal type, send any required setup codes to the terminal, and
-create various internal data structures. If successful,
-\function{initscr()} returns a window object representing the entire
-screen; this is usually called \code{stdscr}, after the name of the
-corresponding C
-variable.
-
-\begin{verbatim}
-import curses
-stdscr = curses.initscr()
-\end{verbatim}
-
-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 \function{noecho()}
-function.
-
-\begin{verbatim}
-curses.noecho()
-\end{verbatim}
-
-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.
-
-\begin{verbatim}
-curses.cbreak()
-\end{verbatim}
-
-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 \constant{curses.KEY_LEFT}. To get
-curses to do the job, you'll have to enable keypad mode.
-
-\begin{verbatim}
-stdscr.keypad(1)
-\end{verbatim}
-
-Terminating a curses application is much easier than starting one.
-You'll need to call
-
-\begin{verbatim}
-curses.nocbreak(); stdscr.keypad(0); curses.echo()
-\end{verbatim}
-
-to reverse the curses-friendly terminal settings. Then call the
-\function{endwin()} function to restore the terminal to its original
-operating mode.
-
-\begin{verbatim}
-curses.endwin()
-\end{verbatim}
-
-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 \module{curses.wrapper}. It supplies a
-\function{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.
-
-\section{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 \code{stdscr} object returned by the \function{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 \function{newwin()} function creates a new window of a given size,
-returning the new window object.
-
-\begin{verbatim}
-begin_x = 20 ; begin_y = 7
-height = 5 ; width = 40
-win = curses.newwin(height, width, begin_y, begin_x)
-\end{verbatim}
-
-A word about the coordinate system used in curses: coordinates are
-always passed in the order \emph{y,x}, and the top-left corner of a
-window is coordinate (0,0). This breaks a common convention for
-handling coordinates, where the \emph{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 \function{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 \code{stdscr.refresh()} or the
-\function{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.
-
-\begin{verbatim}
-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)
-\end{verbatim}
-
-The \function{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 \method{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
-\function{doupdate()}. The normal \method{refresh()} method calls
-\function{doupdate()} as its last act.
-
-\section{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,
-\function{addstr()} displays a string at the current cursor location
-in the \code{stdscr} window, while \function{mvaddstr()} moves to a
-given y,x coordinate first before displaying the string.
-\function{waddstr()} is just like \function{addstr()}, but allows
-specifying a window to use, instead of using \code{stdscr} by default.
-\function{mvwaddstr()} follows similarly.
-
-Fortunately the Python interface hides all these details;
-\code{stdscr} is a window object like any other, and methods like
-\function{addstr()} accept multiple argument forms. Usually there are
-four different forms.
-
-\begin{tableii}{|c|l|}{textrm}{Form}{Description}
-\lineii{\var{str} or \var{ch}}{Display the string \var{str} or
-character \var{ch} at the current position}
-\lineii{\var{str} or \var{ch}, \var{attr}}{Display the string \var{str} or
-character \var{ch}, using attribute \var{attr} at the current position}
-\lineii{\var{y}, \var{x}, \var{str} or \var{ch}}
-{Move to position \var{y,x} within the window, and display \var{str}
-or \var{ch}}
-\lineii{\var{y}, \var{x}, \var{str} or \var{ch}, \var{attr}}
-{Move to position \var{y,x} within the window, and display \var{str}
-or \var{ch}, using attribute \var{attr}}
-\end{tableii}
-
-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 \function{addstr()} function takes a Python string as the value to
-be displayed, while the \function{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,
-\constant{ACS_PLMINUS} is a +/- symbol, and \constant{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 \var{y,x} coordinates, the string or character
-will be displayed wherever the last operation left off. You can also
-move the cursor with the \function{move(\var{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 \function{curs_set(0)} to make it invisible. Equivalently, and
-for compatibility with older curses versions, there's a
-\function{leaveok(\var{bool})} function. When \var{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.
-
-\subsection{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.
-
-\begin{tableii}{|c|l|}{constant}{Attribute}{Description}
-\lineii{A_BLINK}{Blinking text}
-\lineii{A_BOLD}{Extra bright or bold text}
-\lineii{A_DIM}{Half bright text}
-\lineii{A_REVERSE}{Reverse-video text}
-\lineii{A_STANDOUT}{The best highlighting mode available}
-\lineii{A_UNDERLINE}{Underlined text}
-\end{tableii}
-
-So, to display a reverse-video status line on the top line of the
-screen,
-you could code:
-
-\begin{verbatim}
-stdscr.addstr(0, 0, "Current mode: Typing mode",
- curses.A_REVERSE)
-stdscr.refresh()
-\end{verbatim}
-
-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 \function{start_color()} function soon
-after calling \function{initscr()}, to initialize the default color
-set (the \function{curses.wrapper.wrapper()} function does this
-automatically). Once that's done, the \function{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
-\function{color_pair()} function; this can be bitwise-OR'ed with other
-attributes such as \constant{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:
-
-\begin{verbatim}
-stdscr.addstr( "Pretty text", curses.color_pair(1) )
-stdscr.refresh()
-\end{verbatim}
-
-As I said before, a color pair consists of a foreground and
-background color. \function{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:
-\constant{curses.COLOR_BLACK}, \constant{curses.COLOR_RED}, and so
-forth.
-
-The \function{init_pair(\var{n, f, b})} function changes the
-definition of color pair \var{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:
-
-\begin{verbatim}
-curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE)
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-stdscr.addstr(0,0, "RED ALERT!", curses.color_pair(1) )
-\end{verbatim}
-
-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 \function{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.
-
-\section{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
-\method{getch()} method. \method{getch()} pauses and waits for the
-user to hit a key, displaying it if \function{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
-\method{nodelay()}. After \method{nodelay(1)}, \method{getch()} for
-the window becomes non-blocking and returns \code{curses.ERR} (a value
-of -1) when no input is ready. There's also a \function{halfdelay()}
-function, which can be used to (in effect) set a timer on each
-\method{getch()}; if no input becomes available within the number of
-milliseconds specified as the argument to \function{halfdelay()},
-curses raises an exception.
-
-The \method{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
-\constant{curses.KEY_PPAGE}, \constant{curses.KEY_HOME}, or
-\constant{curses.KEY_LEFT}. Usually the main loop of your program
-will look something like this:
-
-\begin{verbatim}
-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
-\end{verbatim}
-
-The \module{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, \function{curses.ascii.ctrl()} returns
-the control character corresponding to its argument.
-
-There's also a method to retrieve an entire string,
-\constant{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.
-
-\begin{verbatim}
-curses.echo() # Enable echoing of characters
-
-# Get a 15-character string, with the cursor on the top line
-s = stdscr.getstr(0,0, 15)
-\end{verbatim}
-
-The Python \module{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 \module{curses.textpad} for the details.
-
-\section{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 \constant{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: \url{http://dickey.his.com/ncurses/ncurses.faq.html}
-
-\end{document}
diff --git a/Doc/howto/doanddont.tex b/Doc/howto/doanddont.tex
deleted file mode 100644
index b54f069..0000000
--- a/Doc/howto/doanddont.tex
+++ /dev/null
@@ -1,332 +0,0 @@
-\documentclass{howto}
-
-\title{Idioms and Anti-Idioms in Python}
-
-\release{0.00}
-
-\author{Moshe Zadka}
-\authoraddress{howto@zadka.site.co.il}
-
-\begin{document}
-\maketitle
-
-This document is placed in the public doman.
-
-\begin{abstract}
-\noindent
-This document can be considered a companion to the tutorial. It
-shows how to use Python, and even more importantly, how {\em not}
-to use Python.
-\end{abstract}
-
-\tableofcontents
-
-\section{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.
-
-\subsection{from module import *}
-
-\subsubsection{Inside Function Definitions}
-
-\code{from module import *} is {\em 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.
-
-\subsubsection{At Module Level}
-
-While it is valid to use \code{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:
-
-\begin{verbatim}
-f = open("www")
-f.read()
-\end{verbatim}
-
-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 \code{from os import *} is present. The \module{os} module
-has a function called \function{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 --- \code{from module import name1, name2}, or keep them in
-the module and access on a per-need basis ---
-\code{import module;print module.name}.
-
-\subsubsection{When It Is Just Fine}
-
-There are situations in which \code{from module import *} is just fine:
-
-\begin{itemize}
-
-\item The interactive prompt. For example, \code{from math import *} makes
- Python an amazing scientific calculator.
-
-\item When extending a module in C with a module in Python.
-
-\item When the module advertises itself as \code{from import *} safe.
-
-\end{itemize}
-
-\subsection{Unadorned \function{exec} and friends}
-
-The word ``unadorned'' refers to the use without an explicit dictionary,
-in which case those constructs evaluate code in the {\em current} environment.
-This is dangerous for the same reasons \code{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:
-
-\begin{verbatim}
->>> 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!
->>> exec(open("handler.py").read())
->>> handle()
-\end{verbatim}
-
-Good examples:
-
-\begin{verbatim}
->>> 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={}
->>> exec(open("handler.py").read(), d, d)
->>> handle = d['handle']
->>> handle()
-\end{verbatim}
-
-\subsection{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:
-
-\begin{verbatim}
-# foo.py
-a = 1
-
-# bar.py
-from foo import a
-if something():
- a = 2 # danger: foo.a != a
-\end{verbatim}
-
-Good example:
-
-\begin{verbatim}
-# foo.py
-a = 1
-
-# bar.py
-import foo
-if something():
- foo.a = 2
-\end{verbatim}
-
-\subsection{except:}
-
-Python has the \code{except:} clause, which catches all exceptions.
-Since {\em 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:
-
-\begin{verbatim}
-try:
- foo = opne("file") # misspelled "open"
-except:
- sys.exit("could not open file!")
-\end{verbatim}
-
-The second line triggers a \exception{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 \code{"file"}.
-
-The example above is better written
-
-\begin{verbatim}
-try:
- foo = opne("file") # will be changed to "open" as soon as we run it
-except IOError:
- sys.exit("could not open file")
-\end{verbatim}
-
-There are some situations in which the \code{except:} clause is useful:
-for example, in a framework when running callbacks, it is good not to
-let any callback disturb the framework.
-
-\section{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
-
-\begin{verbatim}
-def get_status(file):
- if not os.path.exists(file):
- print "file not found"
- sys.exit(1)
- return open(file).readline()
-\end{verbatim}
-
-Consider the case the file gets deleted between the time the call to
-\function{os.path.exists} is made and the time \function{open} is called.
-That means the last line will throw an \exception{IOError}. The same would
-happen if \var{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 \exception{IOError} escapes to the user, who
-has to watch the ugly traceback.
-
-Here is a better way to do it.
-
-\begin{verbatim}
-def get_status(file):
- try:
- return open(file).readline()
- except (IOError, OSError):
- print "file not found"
- sys.exit(1)
-\end{verbatim}
-
-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, \function{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
-
-\begin{verbatim}
-try:
- status = get_status(log)
-except SystemExit:
- status = None
-\end{verbatim}
-
-So, try to make as few \code{except} clauses in your code --- those will
-usually be a catch-all in the \function{main}, or inside calls which
-should always succeed.
-
-So, the best version is probably
-
-\begin{verbatim}
-def get_status(file):
- return open(file).readline()
-\end{verbatim}
-
-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 {\em 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).
-
-\begin{verbatim}
-def get_status(file):
- fp = open(file)
- try:
- return fp.readline()
- finally:
- fp.close()
-\end{verbatim}
-
-\section{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 \module{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:
-
-\begin{verbatim}
-# ugh!
-return dir+"/"+file
-# better
-return os.path.join(dir, file)
-\end{verbatim}
-
-More useful functions in \module{os.path}: \function{basename},
-\function{dirname} and \function{splitext}.
-
-There are also many useful builtin functions people seem not to be
-aware of for some reason: \function{min()} and \function{max()} can
-find the minimum/maximum of any sequence with comparable semantics,
-for example, yet many people write their own
-\function{max()}/\function{min()}.
-
-On the same note, note that \function{float()}, \function{int()} and
-\function{long()} all accept arguments of type string, and so are
-suited to parsing --- assuming you are ready to deal with the
-\exception{ValueError} they raise.
-
-\section{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:
-
-\begin{verbatim}
-if foo.bar()['first'][0] == baz.quux(1, 2)[5:9] and \
- calculate_number(10, 20) != forbulate(500, 360):
- pass
-\end{verbatim}
-
-You should realize that this is dangerous: a stray space after the
-\code{\\} 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:
-
-\begin{verbatim}
-value = foo.bar()['first'][0]*baz.quux(1, 2)[5:9] \
- + calculate_number(10, 20)*forbulate(500, 360)
-\end{verbatim}
-
-then it would just be subtly wrong.
-
-It is usually much better to use the implicit continuation inside parenthesis:
-
-This version is bulletproof:
-
-\begin{verbatim}
-value = (foo.bar()['first'][0]*baz.quux(1, 2)[5:9]
- + calculate_number(10, 20)*forbulate(500, 360))
-\end{verbatim}
-
-\end{document}
diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst
deleted file mode 100644
index 5a55339..0000000
--- a/Doc/howto/functional.rst
+++ /dev/null
@@ -1,1474 +0,0 @@
-Functional Programming HOWTO
-================================
-
-**Version 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 ``itertools`` and ``functools``.
-
-
-.. contents::
-
-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 ``next()`` function is normally used to call the iterator's
-``__next__()`` method.
-
-The built-in ``iter()`` function takes an arbitrary object and tries
-to return an iterator that will return the object's contents or
-elements, raising ``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>
- >>> next(it)
- 1
- >>> next(it)
- 2
- >>> next(it)
- 3
- >>> next(it)
- 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
-``list()`` or ``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 ``max()`` and ``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 ``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 ``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 ``next(generator)``,
-the function will resume executing.
-
-Here's a sample usage of the ``generate_ints()`` generator::
-
- >>> gen = generate_ints(3)
- >>> gen
- <generator object at 0x8117f90>
- >>> next(gen)
- 0
- >>> next(gen)
- 1
- >>> next(gen)
- 2
- >>> next(gen)
- 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.
-``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 next(it)
- 0
- >>> print next(it)
- 1
- >>> print it.send(8)
- 8
- >>> print next(it)
- 9
- >>> print next(it)
- Traceback (most recent call last):
- File ``t.py'', line 15, in ?
- print next(it)
- 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 ``GeneratorExit``
- exception inside the generator to terminate the iteration.
- On receiving this
- exception, the generator's code must either raise
- ``GeneratorExit`` or ``StopIteration``; catching the
- exception and doing anything else is illegal and will trigger
- a ``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 ``GeneratorExit`` occurs,
- I suggest using a ``try: ... finally:`` suite instead of
- catching ``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, ``map()`` and ``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 ``itertools.imap()`` function does the same thing
-but can handle infinite iterators; it'll be discussed later, in the section on
-the ``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 ``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]
-
-``filter()`` also has a counterpart in the ``itertools`` module,
-``itertools.ifilter()``, that returns an iterator and
-can therefore handle infinite sequences just as ``itertools.imap()`` can.
-
-``reduce(func, iter, [initial_value])`` doesn't have a counterpart in
-the ``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. ``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 ``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 ``operator.add`` with ``reduce()``, you'll add up all the
-elements of the iterable. This case is so common that there's a special
-built-in called ``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 ``reduce()``, though, it can be clearer to just write
-the obvious ``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')
-
-``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. ``any()`` returns
-True if any element in the iterable is a true value, and ``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 statement
-----------------------------------------------
-
-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 ``sum()`` built-in and a generator expression::
-
- total = sum(b for a,b in items)
-
-Many uses of ``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 ``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 ``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 ``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 ``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 ``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 <http://docs.python.org/lib/module-operator.html>`__ 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
-'''''''''''''''''''''''''''
-
-http://docs.python.org/lib/module-itertools.html:
-Documentation for the ``itertools`` module.
-
-http://docs.python.org/lib/module-operator.html:
-Documentation for the ``operator`` module.
-
-http://www.python.org/dev/peps/pep-0289/:
-PEP 289: "Generator Expressions"
-
-http://www.python.org/dev/peps/pep-0342/
-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]
-
-
diff --git a/Doc/howto/regex.tex b/Doc/howto/regex.tex
deleted file mode 100644
index d911be6..0000000
--- a/Doc/howto/regex.tex
+++ /dev/null
@@ -1,1476 +0,0 @@
-\documentclass{howto}
-
-% 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)
-
-\title{Regular Expression HOWTO}
-
-\release{0.05}
-
-\author{A.M. Kuchling}
-\authoraddress{\email{amk@amk.ca}}
-
-\begin{document}
-\maketitle
-
-\begin{abstract}
-\noindent
-This document is an introductory tutorial to using regular expressions
-in Python with the \module{re} module. It provides a gentler
-introduction than the corresponding section in the Library Reference.
-
-This document is available from
-\url{http://www.amk.ca/python/howto}.
-
-\end{abstract}
-
-\tableofcontents
-
-\section{Introduction}
-
-The \module{re} module was added in Python 1.5, and provides
-Perl-style regular expression patterns. Earlier versions of Python
-came with the \module{regex} module, which provided Emacs-style
-patterns. The \module{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 \module{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 \emph{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.
-
-\section{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.
-
-\subsection{Matching Characters}
-
-Most letters and characters will simply match themselves. For
-example, the regular expression \regexp{test} will match the string
-\samp{test} exactly. (You can enable a case-insensitive mode that
-would let this RE match \samp{Test} or \samp{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.
-
-\begin{verbatim}
-. ^ $ * + ? { [ ] \ | ( )
-\end{verbatim}
-% $
-
-The first metacharacters we'll look at are \samp{[} and \samp{]}.
-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 \character{-}. For example,
-\regexp{[abc]} will match any of the characters \samp{a}, \samp{b}, or
-\samp{c}; this is the same as
-\regexp{[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 \regexp{[a-z]}.
-
-Metacharacters are not active inside classes. For example,
-\regexp{[akm\$]} will match any of the characters \character{a},
-\character{k}, \character{m}, or \character{\$}; \character{\$} 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
-\character{\^} as the first character of the class; \character{\^}
-outside a character class will simply match the
-\character{\^} character. For example, \verb|[^5]| will match any
-character except \character{5}.
-
-Perhaps the most important metacharacter is the backslash, \samp{\e}.
-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 \samp{[} or
-\samp{\e}, you can precede them with a backslash to remove their
-special meaning: \regexp{\e[} or \regexp{\e\e}.
-
-Some of the special sequences beginning with \character{\e} 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:
-
-\begin{itemize}
-\item[\code{\e d}]Matches any decimal digit; this is
-equivalent to the class \regexp{[0-9]}.
-
-\item[\code{\e D}]Matches any non-digit character; this is
-equivalent to the class \verb|[^0-9]|.
-
-\item[\code{\e s}]Matches any whitespace character; this is
-equivalent to the class \regexp{[ \e t\e n\e r\e f\e v]}.
-
-\item[\code{\e S}]Matches any non-whitespace character; this is
-equivalent to the class \verb|[^ \t\n\r\f\v]|.
-
-\item[\code{\e w}]Matches any alphanumeric character; this is equivalent to the class
-\regexp{[a-zA-Z0-9_]}.
-
-\item[\code{\e W}]Matches any non-alphanumeric character; this is equivalent to the class
-\verb|[^a-zA-Z0-9_]|.
-\end{itemize}
-
-These sequences can be included inside a character class. For
-example, \regexp{[\e s,.]} is a character class that will match any
-whitespace character, or \character{,} or \character{.}.
-
-The final metacharacter in this section is \regexp{.}. It matches
-anything except a newline character, and there's an alternate mode
-(\code{re.DOTALL}) where it will match even a newline. \character{.}
-is often used where you want to match ``any character''.
-
-\subsection{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
-\regexp{*}. \regexp{*} doesn't match the literal character \samp{*};
-instead, it specifies that the previous character can be matched zero
-or more times, instead of exactly once.
-
-For example, \regexp{ca*t} will match \samp{ct} (0 \samp{a}
-characters), \samp{cat} (1 \samp{a}), \samp{caaat} (3 \samp{a}
-characters), and so forth. The RE engine has various internal
-limitations stemming from the size of C's \code{int} type that will
-prevent it from matching over 2 billion \samp{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 \regexp{*} 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 \regexp{a[bcd]*b}. This matches the letter
-\character{a}, zero or more letters from the class \code{[bcd]}, and
-finally ends with a \character{b}. Now imagine matching this RE
-against the string \samp{abcbd}.
-
-\begin{tableiii}{c|l|l}{}{Step}{Matched}{Explanation}
-\lineiii{1}{\code{a}}{The \regexp{a} in the RE matches.}
-\lineiii{2}{\code{abcbd}}{The engine matches \regexp{[bcd]*}, going as far as
-it can, which is to the end of the string.}
-\lineiii{3}{\emph{Failure}}{The engine tries to match \regexp{b}, but the
-current position is at the end of the string, so it fails.}
-\lineiii{4}{\code{abcb}}{Back up, so that \regexp{[bcd]*} matches
-one less character.}
-\lineiii{5}{\emph{Failure}}{Try \regexp{b} again, but the
-current position is at the last character, which is a \character{d}.}
-\lineiii{6}{\code{abc}}{Back up again, so that \regexp{[bcd]*} is
-only matching \samp{bc}.}
-\lineiii{6}{\code{abcb}}{Try \regexp{b} again. This time
-but the character at the current position is \character{b}, so it succeeds.}
-\end{tableiii}
-
-The end of the RE has now been reached, and it has matched
-\samp{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 \regexp{[bcd]*}, and if that
-subsequently fails, the engine will conclude that the string doesn't
-match the RE at all.
-
-Another repeating metacharacter is \regexp{+}, which matches one or
-more times. Pay careful attention to the difference between
-\regexp{*} and \regexp{+}; \regexp{*} matches \emph{zero} or more
-times, so whatever's being repeated may not be present at all, while
-\regexp{+} requires at least \emph{one} occurrence. To use a similar
-example, \regexp{ca+t} will match \samp{cat} (1 \samp{a}),
-\samp{caaat} (3 \samp{a}'s), but won't match \samp{ct}.
-
-There are two more repeating qualifiers. The question mark character,
-\regexp{?}, matches either once or zero times; you can think of it as
-marking something as being optional. For example, \regexp{home-?brew}
-matches either \samp{homebrew} or \samp{home-brew}.
-
-The most complicated repeated qualifier is
-\regexp{\{\var{m},\var{n}\}}, where \var{m} and \var{n} are decimal
-integers. This qualifier means there must be at least \var{m}
-repetitions, and at most \var{n}. For example, \regexp{a/\{1,3\}b}
-will match \samp{a/b}, \samp{a//b}, and \samp{a///b}. It won't match
-\samp{ab}, which has no slashes, or \samp{a////b}, which has four.
-
-You can omit either \var{m} or \var{n}; in that case, a reasonable
-value is assumed for the missing value. Omitting \var{m} is
-interpreted as a lower limit of 0, while omitting \var{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. \regexp{\{0,\}} is the same
-as \regexp{*}, \regexp{\{1,\}} is equivalent to \regexp{+}, and
-\regexp{\{0,1\}} is the same as \regexp{?}. It's better to use
-\regexp{*}, \regexp{+}, or \regexp{?} when you can, simply because
-they're shorter and easier to read.
-
-\section{Using Regular Expressions}
-
-Now that we've looked at some simple regular expressions, how do we
-actually use them in Python? The \module{re} module provides an
-interface to the regular expression engine, allowing you to compile
-REs into objects and then perform matches with them.
-
-\subsection{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.
-
-\begin{verbatim}
->>> import re
->>> p = re.compile('ab*')
->>> print p
-<re.RegexObject instance at 80b4150>
-\end{verbatim}
-
-\function{re.compile()} also accepts an optional \var{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:
-
-\begin{verbatim}
->>> p = re.compile('ab*', re.IGNORECASE)
-\end{verbatim}
-
-The RE is passed to \function{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 \module{re} module is simply a C extension module
-included with Python, just like the \module{socket} or \module{zlib}
-modules.
-
-Putting REs in strings keeps the Python language simpler, but has one
-disadvantage which is the topic of the next section.
-
-\subsection{The Backslash Plague}
-
-As stated earlier, regular expressions use the backslash
-character (\character{\e}) 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
-\samp{{\e}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 \samp{\e\e section}. The resulting string that must be passed
-to \function{re.compile()} must be \verb|\\section|. However, to
-express this as a Python string literal, both backslashes must be
-escaped \emph{again}.
-
-\begin{tableii}{c|l}{code}{Characters}{Stage}
- \lineii{\e section}{Text string to be matched}
- \lineii{\e\e section}{Escaped backslash for \function{re.compile}}
- \lineii{"\e\e\e\e section"}{Escaped backslashes for a string literal}
-\end{tableii}
-
-In short, to match a literal backslash, one has to write
-\code{'\e\e\e\e'} as the RE string, because the regular expression
-must be \samp{\e\e}, and each backslash must be expressed as
-\samp{\e\e} 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 \character{r}, so \code{r"\e n"} is a
-two-character string containing \character{\e} and \character{n},
-while \code{"\e n"} is a one-character string containing a newline.
-Regular expressions will often be written in Python
-code using this raw string notation.
-
-\begin{tableii}{c|c}{code}{Regular String}{Raw string}
- \lineii{"ab*"}{\code{r"ab*"}}
- \lineii{"\e\e\e\e section"}{\code{r"\e\e section"}}
- \lineii{"\e\e w+\e\e s+\e\e 1"}{\code{r"\e w+\e s+\e 1"}}
-\end{tableii}
-
-\subsection{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 \ulink{the Library
-Reference}{http://www.python.org/doc/lib/module-re.html} for a
-complete listing.
-
-\begin{tableii}{c|l}{code}{Method/Attribute}{Purpose}
- \lineii{match()}{Determine if the RE matches at the beginning of
- the string.}
- \lineii{search()}{Scan through a string, looking for any location
- where this RE matches.}
- \lineii{findall()}{Find all substrings where the RE matches,
-and returns them as a list.}
- \lineii{finditer()}{Find all substrings where the RE matches,
-and returns them as an iterator.}
-\end{tableii}
-
-\method{match()} and \method{search()} return \code{None} if no match
-can be found. If they're successful, a \code{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
-\module{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
-\ulink{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 \module{re} module, and
-compile a RE:
-
-\begin{verbatim}
-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>
-\end{verbatim}
-
-Now, you can try matching various strings against the RE
-\regexp{[a-z]+}. An empty string shouldn't match at all, since
-\regexp{+} means 'one or more repetitions'. \method{match()} should
-return \code{None} in this case, which will cause the interpreter to
-print no output. You can explicitly print the result of
-\method{match()} to make this clear.
-
-\begin{verbatim}
->>> p.match("")
->>> print p.match("")
-None
-\end{verbatim}
-
-Now, let's try it on a string that it should match, such as
-\samp{tempo}. In this case, \method{match()} will return a
-\class{MatchObject}, so you should store the result in a variable for
-later use.
-
-\begin{verbatim}
->>> m = p.match('tempo')
->>> print m
-<_sre.SRE_Match object at 80c4f68>
-\end{verbatim}
-
-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:
-
-\begin{tableii}{c|l}{code}{Method/Attribute}{Purpose}
- \lineii{group()}{Return the string matched by the RE}
- \lineii{start()}{Return the starting position of the match}
- \lineii{end()}{Return the ending position of the match}
- \lineii{span()}{Return a tuple containing the (start, end) positions
- of the match}
-\end{tableii}
-
-Trying these methods will soon clarify their meaning:
-
-\begin{verbatim}
->>> m.group()
-'tempo'
->>> m.start(), m.end()
-(0, 5)
->>> m.span()
-(0, 5)
-\end{verbatim}
-
-\method{group()} returns the substring that was matched by the
-RE. \method{start()} and \method{end()} return the starting and
-ending index of the match. \method{span()} returns both start and end
-indexes in a single tuple. Since the \method{match} method only
-checks if the RE matches at the start of a string,
-\method{start()} will always be zero. However, the \method{search}
-method of \class{RegexObject} instances scans through the string, so
-the match may not start at zero in that case.
-
-\begin{verbatim}
->>> print p.match('::: message')
-None
->>> m = p.search('::: message') ; print m
-<re.MatchObject instance at 80c9650>
->>> m.group()
-'message'
->>> m.span()
-(4, 11)
-\end{verbatim}
-
-In actual programs, the most common style is to store the
-\class{MatchObject} in a variable, and then check if it was
-\code{None}. This usually looks like:
-
-\begin{verbatim}
-p = re.compile( ... )
-m = p.match( 'string goes here' )
-if m:
- print 'Match found: ', m.group()
-else:
- print 'No match'
-\end{verbatim}
-
-Two \class{RegexObject} methods return all of the matches for a pattern.
-\method{findall()} returns a list of matching strings:
-
-\begin{verbatim}
->>> p = re.compile('\d+')
->>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping')
-['12', '11', '10']
-\end{verbatim}
-
-\method{findall()} has to create the entire list before it can be
-returned as the result. The \method{finditer()} method returns a
-sequence of \class{MatchObject} instances as an
-iterator.\footnote{Introduced in Python 2.2.2.}
-
-\begin{verbatim}
->>> 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)
-\end{verbatim}
-
-
-\subsection{Module-Level Functions}
-
-You don't have to create a \class{RegexObject} and call its methods;
-the \module{re} module also provides top-level functions called
-\function{match()}, \function{search()}, \function{findall()},
-\function{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
-\code{None} or a \class{MatchObject} instance.
-
-\begin{verbatim}
->>> 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>
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-ref = re.compile( ... )
-entityref = re.compile( ... )
-charref = re.compile( ... )
-starttagopen = re.compile( ... )
-\end{verbatim}
-
-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.
-
-\subsection{Compilation Flags}
-
-Compilation flags let you modify some aspects of how regular
-expressions work. Flags are available in the \module{re} module under
-two names, a long name such as \constant{IGNORECASE} and a short,
-one-letter form such as \constant{I}. (If you're familiar with Perl's
-pattern modifiers, the one-letter forms use the same letters; the
-short form of \constant{re.VERBOSE} is \constant{re.X}, for example.)
-Multiple flags can be specified by bitwise OR-ing them; \code{re.I |
-re.M} sets both the \constant{I} and \constant{M} flags, for example.
-
-Here's a table of the available flags, followed by
-a more detailed explanation of each one.
-
-\begin{tableii}{c|l}{}{Flag}{Meaning}
- \lineii{\constant{DOTALL}, \constant{S}}{Make \regexp{.} match any
- character, including newlines}
- \lineii{\constant{IGNORECASE}, \constant{I}}{Do case-insensitive matches}
- \lineii{\constant{LOCALE}, \constant{L}}{Do a locale-aware match}
- \lineii{\constant{MULTILINE}, \constant{M}}{Multi-line matching,
- affecting \regexp{\^} and \regexp{\$}}
- \lineii{\constant{VERBOSE}, \constant{X}}{Enable verbose REs,
- which can be organized more cleanly and understandably.}
-\end{tableii}
-
-\begin{datadesc}{I}
-\dataline{IGNORECASE}
-Perform case-insensitive matching; character class and literal strings
-will match
-letters by ignoring case. For example, \regexp{[A-Z]} will match
-lowercase letters, too, and \regexp{Spam} will match \samp{Spam},
-\samp{spam}, or \samp{spAM}.
-This lowercasing doesn't take the current locale into account; it will
-if you also set the \constant{LOCALE} flag.
-\end{datadesc}
-
-\begin{datadesc}{L}
-\dataline{LOCALE}
-Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b},
-and \regexp{\e 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
-\regexp{\e w+} to match words, but \regexp{\e w} only matches the
-character class \regexp{[A-Za-z]}; it won't match \character{\'e} or
-\character{\c c}. If your system is configured properly and a French
-locale is selected, certain C functions will tell the program that
-\character{\'e} should also be considered a letter. Setting the
-\constant{LOCALE} flag when compiling a regular expression will cause the
-resulting compiled object to use these C functions for \regexp{\e w};
-this is slower, but also enables \regexp{\e w+} to match French words as
-you'd expect.
-\end{datadesc}
-
-\begin{datadesc}{M}
-\dataline{MULTILINE}
-(\regexp{\^} and \regexp{\$} haven't been explained yet;
-they'll be introduced in section~\ref{more-metacharacters}.)
-
-Usually \regexp{\^} matches only at the beginning of the string, and
-\regexp{\$} 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, \regexp{\^} matches at the beginning of the string and at
-the beginning of each line within the string, immediately following
-each newline. Similarly, the \regexp{\$} metacharacter matches either at
-the end of the string and at the end of each line (immediately
-preceding each newline).
-
-\end{datadesc}
-
-\begin{datadesc}{S}
-\dataline{DOTALL}
-Makes the \character{.} special character match any character at all,
-including a newline; without this flag, \character{.} will match
-anything \emph{except} a newline.
-\end{datadesc}
-
-\begin{datadesc}{X}
-\dataline{VERBOSE} 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 \character{\#} that's neither in a character class or preceded by an
-unescaped backslash.
-
-For example, here's a RE that uses \constant{re.VERBOSE}; see how
-much easier it is to read?
-
-\begin{verbatim}
-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)
-\end{verbatim}
-
-Without the verbose setting, the RE would look like this:
-\begin{verbatim}
-charref = re.compile("&#(0[0-7]+"
- "|[0-9]+"
- "|x[0-9a-fA-F]+);")
-\end{verbatim}
-
-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
-\constant{re.VERBOSE}.
-
-\end{datadesc}
-
-\section{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.
-
-\subsection{More Metacharacters\label{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, \regexp{\e b} is an
-assertion that the current position is located at a word boundary; the
-position isn't changed by the \regexp{\e 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.
-
-\begin{list}{}{}
-
-\item[\regexp{|}]
-Alternation, or the ``or'' operator.
-If A and B are regular expressions,
-\regexp{A|B} will match any string that matches either \samp{A} or \samp{B}.
-\regexp{|} has very low precedence in order to make it work reasonably when
-you're alternating multi-character strings.
-\regexp{Crow|Servo} will match either \samp{Crow} or \samp{Servo}, not
-\samp{Cro}, a \character{w} or an \character{S}, and \samp{ervo}.
-
-To match a literal \character{|},
-use \regexp{\e|}, or enclose it inside a character class, as in \regexp{[|]}.
-
-\item[\regexp{\^}] Matches at the beginning of lines. Unless the
-\constant{MULTILINE} flag has been set, this will only match at the
-beginning of the string. In \constant{MULTILINE} mode, this also
-matches immediately after each newline within the string.
-
-For example, if you wish to match the word \samp{From} only at the
-beginning of a line, the RE to use is \verb|^From|.
-
-\begin{verbatim}
->>> print re.search('^From', 'From Here to Eternity')
-<re.MatchObject instance at 80c1520>
->>> print re.search('^From', 'Reciting From Memory')
-None
-\end{verbatim}
-
-%To match a literal \character{\^}, use \regexp{\e\^} or enclose it
-%inside a character class, as in \regexp{[{\e}\^]}.
-
-\item[\regexp{\$}] 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.
-
-\begin{verbatim}
->>> print re.search('}$', '{block}')
-<re.MatchObject instance at 80adfa8>
->>> print re.search('}$', '{block} ')
-None
->>> print re.search('}$', '{block}\n')
-<re.MatchObject instance at 80adfa8>
-\end{verbatim}
-% $
-
-To match a literal \character{\$}, use \regexp{\e\$} or enclose it
-inside a character class, as in \regexp{[\$]}.
-
-\item[\regexp{\e A}] Matches only at the start of the string. When
-not in \constant{MULTILINE} mode, \regexp{\e A} and \regexp{\^} are
-effectively the same. In \constant{MULTILINE} mode, they're
-different: \regexp{\e A} still matches only at the beginning of the
-string, but \regexp{\^} may match at any location inside the string
-that follows a newline character.
-
-\item[\regexp{\e Z}] Matches only at the end of the string.
-
-\item[\regexp{\e 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 \samp{class} only when it's a complete
-word; it won't match when it's contained inside another word.
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
-
-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, \samp{\e b} is the backspace character, ASCII value 8. If
-you're not using raw strings, then Python will convert the \samp{\e 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 \character{r} in front of the RE string.
-
-\begin{verbatim}
->>> p = re.compile('\bclass\b')
->>> print p.search('no class at all')
-None
->>> print p.search('\b' + 'class' + '\b')
-<re.MatchObject instance at 80c3ee0>
-\end{verbatim}
-
-Second, inside a character class, where there's no use for this
-assertion, \regexp{\e b} represents the backspace character, for
-compatibility with Python's string literals.
-
-\item[\regexp{\e B}] Another zero-width assertion, this is the
-opposite of \regexp{\e b}, only matching when the current
-position is not at a word boundary.
-
-\end{list}
-
-\subsection{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
-\character{:}, like this:
-
-\begin{verbatim}
-From: author@example.com
-User-Agent: Thunderbird 1.5.0.9 (X11/20061227)
-MIME-Version: 1.0
-To: editor@example.com
-\end{verbatim}
-
-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 \character{(}, \character{)} metacharacters.
-\character{(} and \character{)} 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 \regexp{*}, \regexp{+},
-\regexp{?}, or \regexp{\{\var{m},\var{n}\}}. For example,
-\regexp{(ab)*} will match zero or more repetitions of \samp{ab}.
-
-\begin{verbatim}
->>> p = re.compile('(ab)*')
->>> print p.match('ababababab').span()
-(0, 10)
-\end{verbatim}
-
-Groups indicated with \character{(}, \character{)} also capture the
-starting and ending index of the text that they match; this can be
-retrieved by passing an argument to \method{group()},
-\method{start()}, \method{end()}, and \method{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.
-
-\begin{verbatim}
->>> p = re.compile('(a)b')
->>> m = p.match('ab')
->>> m.group()
-'ab'
->>> m.group(0)
-'ab'
-\end{verbatim}
-
-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.
-
-\begin{verbatim}
->>> p = re.compile('(a(b)c)d')
->>> m = p.match('abcd')
->>> m.group(0)
-'abcd'
->>> m.group(1)
-'abc'
->>> m.group(2)
-'b'
-\end{verbatim}
-
-\method{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.
-
-\begin{verbatim}
->>> m.group(2,1,2)
-('b', 'abc', 'b')
-\end{verbatim}
-
-The \method{groups()} method returns a tuple containing the strings
-for all the subgroups, from 1 up to however many there are.
-
-\begin{verbatim}
->>> m.groups()
-('abc', 'b')
-\end{verbatim}
-
-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, \regexp{\e 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.
-
-\begin{verbatim}
->>> p = re.compile(r'(\b\w+)\s+\1')
->>> p.search('Paris in the the spring').group()
-'the the'
-\end{verbatim}
-
-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 \emph{very} useful
-when performing string substitutions.
-
-\subsection{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 \module{re} module supports most of them.
-It would have been difficult to choose new
-single-keystroke metacharacters or new special sequences beginning
-with \samp{\e} to represent the new features without making Perl's
-regular expressions confusingly different from standard REs. If you
-chose \samp{\&} as a new metacharacter, for example, old expressions
-would be assuming that
-\samp{\&} was a regular character and wouldn't have escaped it by
-writing \regexp{\e \&} or \regexp{[\&]}.
-
-The solution chosen by the Perl developers was to use \regexp{(?...)}
-as the extension syntax. \samp{?} immediately after a parenthesis was
-a syntax error because the \samp{?} would have nothing to repeat, so
-this didn't introduce any compatibility problems. The characters
-immediately after the \samp{?} indicate what extension is being used,
-so \regexp{(?=foo)} is one thing (a positive lookahead assertion) and
-\regexp{(?:foo)} is something else (a non-capturing group containing
-the subexpression \regexp{foo}).
-
-Python adds an extension syntax to Perl's extension syntax. If the
-first character after the question mark is a \samp{P}, you know that
-it's an extension that's specific to Python. Currently there are two
-such extensions: \regexp{(?P<\var{name}>...)} defines a named group,
-and \regexp{(?P=\var{name})} is a backreference to a named group. If
-future versions of Perl 5 add similar features using a different
-syntax, the \module{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:
-\regexp{(?:...)}, where you can replace the \regexp{...}
-with any other regular expression.
-
-\begin{verbatim}
->>> m = re.match("([abc])+", "abc")
->>> m.groups()
-('c',)
->>> m = re.match("(?:[abc])+", "abc")
->>> m.groups()
-()
-\end{verbatim}
-
-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 \samp{*}, and nest it within other
-groups (capturing or non-capturing). \regexp{(?:...)} 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:
-\regexp{(?P<\var{name}>...)}. \var{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:
-
-\begin{verbatim}
->>> p = re.compile(r'(?P<word>\b\w+\b)')
->>> m = p.search( '(((( Lots of punctuation )))' )
->>> m.group('word')
-'Lots'
->>> m.group(1)
-'Lots'
-\end{verbatim}
-
-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 \module{imaplib} module:
-
-\begin{verbatim}
-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'"')
-\end{verbatim}
-
-It's obviously much easier to retrieve \code{m.group('zonem')},
-instead of having to remember to retrieve group 9.
-
-The syntax for backreferences in an expression such as
-\regexp{(...)\e 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: \regexp{(?P=\var{name})} indicates
-that the contents of the group called \var{name} should again be matched
-at the current point. The regular expression for finding doubled
-words, \regexp{(\e b\e w+)\e s+\e 1} can also be written as
-\regexp{(?P<word>\e b\e w+)\e s+(?P=word)}:
-
-\begin{verbatim}
->>> p = re.compile(r'(?P<word>\b\w+)\s+(?P=word)')
->>> p.search('Paris in the the spring').group()
-'the the'
-\end{verbatim}
-
-\subsection{Lookahead Assertions}
-
-Another zero-width assertion is the lookahead assertion. Lookahead
-assertions are available in both positive and negative form, and
-look like this:
-
-\begin{itemize}
-\item[\regexp{(?=...)}] Positive lookahead assertion. This succeeds
-if the contained regular expression, represented here by \code{...},
-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.
-
-\item[\regexp{(?!...)}] Negative lookahead assertion. This is the
-opposite of the positive assertion; it succeeds if the contained expression
-\emph{doesn't} match at the current position in the string.
-\end{itemize}
-
-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 \samp{.}. For
-example, in \samp{news.rc}, \samp{news} is the base name, and
-\samp{rc} is the filename's extension.
-
-The pattern to match this is quite simple:
-
-\regexp{.*[.].*\$}
-
-Notice that the \samp{.} needs to be treated specially because it's a
-metacharacter; I've put it inside a character class. Also notice the
-trailing \regexp{\$}; this is added to ensure that all the rest of the
-string must be included in the extension. This regular expression
-matches \samp{foo.bar} and \samp{autoexec.bat} and \samp{sendmail.cf} and
-\samp{printers.conf}.
-
-Now, consider complicating the problem a bit; what if you want to
-match filenames where the extension is not \samp{bat}?
-Some incorrect attempts:
-
-\verb|.*[.][^b].*$|
-% $
-
-The first attempt above tries to exclude \samp{bat} by requiring that
-the first character of the extension is not a \samp{b}. This is
-wrong, because the pattern also doesn't match \samp{foo.bar}.
-
-% Messes up the HTML without the curly braces around \^
-\regexp{.*[.]([{\^}b]..|.[{\^}a].|..[{\^}t])\$}
-
-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 \samp{b}; the second character isn't
-\samp{a}; or the third character isn't \samp{t}. This accepts
-\samp{foo.bar} and rejects \samp{autoexec.bat}, but it requires a
-three-letter extension and won't accept a filename with a two-letter
-extension such as \samp{sendmail.cf}. We'll complicate the pattern
-again in an effort to fix it.
-
-\regexp{.*[.]([{\^}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 \samp{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 \samp{bat} and \samp{exe} as extensions, the pattern
-would get even more complicated and confusing.
-
-A negative lookahead cuts through all this confusion:
-
-\regexp{.*[.](?!bat\$).*\$}
-% $
-
-The negative lookahead means: if the expression \regexp{bat} doesn't match at
-this point, try the rest of the pattern; if \regexp{bat\$} does match,
-the whole pattern will fail. The trailing \regexp{\$} is required to
-ensure that something like \samp{sample.batch}, where the extension
-only starts with \samp{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 \samp{bat} or \samp{exe}:
-
-\regexp{.*[.](?!bat\$|exe\$).*\$}
-% $
-
-
-\section{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:
-
-\begin{tableii}{c|l}{code}{Method/Attribute}{Purpose}
- \lineii{split()}{Split the string into a list, splitting it wherever the RE matches}
- \lineii{sub()}{Find all substrings where the RE matches, and replace them with a different string}
- \lineii{subn()}{Does the same thing as \method{sub()},
- but returns the new string and the number of replacements}
-\end{tableii}
-
-
-\subsection{Splitting Strings}
-
-The \method{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 \method{split()} method of strings but
-provides much more
-generality in the delimiters that you can split by;
-\method{split()} only supports splitting by whitespace or by
-a fixed string. As you'd expect, there's a module-level
-\function{re.split()} function, too.
-
-\begin{methoddesc}{split}{string \optional{, maxsplit\code{ = 0}}}
- Split \var{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 \var{maxsplit}
- is nonzero, at most \var{maxsplit} splits are performed.
-\end{methoddesc}
-
-You can limit the number of splits made, by passing a value for
-\var{maxsplit}. When \var{maxsplit} is nonzero, at most
-\var{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.
-
-\begin{verbatim}
->>> 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().']
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
->>> 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', '.', '']
-\end{verbatim}
-
-The module-level function \function{re.split()} adds the RE to be
-used as the first argument, but is otherwise the same.
-
-\begin{verbatim}
->>> 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.']
-\end{verbatim}
-
-\subsection{Search and Replace}
-
-Another common task is to find all the matches for a pattern, and
-replace them with a different string. The \method{sub()} method takes
-a replacement value, which can be either a string or a function, and
-the string to be processed.
-
-\begin{methoddesc}{sub}{replacement, string\optional{, count\code{ = 0}}}
-Returns the string obtained by replacing the leftmost non-overlapping
-occurrences of the RE in \var{string} by the replacement
-\var{replacement}. If the pattern isn't found, \var{string} is returned
-unchanged.
-
-The optional argument \var{count} is the maximum number of pattern
-occurrences to be replaced; \var{count} must be a non-negative
-integer. The default value of 0 means to replace all occurrences.
-\end{methoddesc}
-
-Here's a simple example of using the \method{sub()} method. It
-replaces colour names with the word \samp{colour}:
-
-\begin{verbatim}
->>> 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'
-\end{verbatim}
-
-The \method{subn()} method does the same work, but returns a 2-tuple
-containing the new string value and the number of replacements
-that were performed:
-
-\begin{verbatim}
->>> 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)
-\end{verbatim}
-
-Empty matches are replaced only when they're not
-adjacent to a previous match.
-
-\begin{verbatim}
->>> p = re.compile('x*')
->>> p.sub('-', 'abxd')
-'-a-b-d-'
-\end{verbatim}
-
-If \var{replacement} is a string, any backslash escapes in it are
-processed. That is, \samp{\e n} is converted to a single newline
-character, \samp{\e r} is converted to a carriage return, and so forth.
-Unknown escapes such as \samp{\e j} are left alone. Backreferences,
-such as \samp{\e 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 \samp{section} followed by a string
-enclosed in \samp{\{}, \samp{\}}, and changes \samp{section} to
-\samp{subsection}:
-
-\begin{verbatim}
->>> p = re.compile('section{ ( [^}]* ) }', re.VERBOSE)
->>> p.sub(r'subsection{\1}','section{First} section{second}')
-'subsection{First} subsection{second}'
-\end{verbatim}
-
-There's also a syntax for referring to named groups as defined by the
-\regexp{(?P<name>...)} syntax. \samp{\e g<name>} will use the
-substring matched by the group named \samp{name}, and
-\samp{\e g<\var{number}>}
-uses the corresponding group number.
-\samp{\e g<2>} is therefore equivalent to \samp{\e 2},
-but isn't ambiguous in a
-replacement string such as \samp{\e g<2>0}. (\samp{\e 20} would be
-interpreted as a reference to group 20, not a reference to group 2
-followed by the literal character \character{0}.) The following
-substitutions are all equivalent, but use all three variations of the
-replacement string.
-
-\begin{verbatim}
->>> 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}'
-\end{verbatim}
-
-\var{replacement} can also be a function, which gives you even more
-control. If \var{replacement} is a function, the function is
-called for every non-overlapping occurrence of \var{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:
-
-\begin{verbatim}
->>> 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.'
-\end{verbatim}
-
-When using the module-level \function{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. \code{sub("(?i)b+", "x", "bbbb
-BBBB")} returns \code{'x x'}.
-
-\section{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.
-
-\subsection{Use String Methods}
-
-Sometimes using the \module{re} module is a mistake. If you're
-matching a fixed string, or a single character class, and you're not
-using any \module{re} features such as the \constant{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 \samp{word}
-with \samp{deed}. \code{re.sub()} seems like the function to use for
-this, but consider the \method{replace()} method. Note that
-\function{replace()} will also replace \samp{word} inside
-words, turning \samp{swordfish} into \samp{sdeedfish}, but the
-na{\"\i}ve RE \regexp{word} would have done that, too. (To avoid performing
-the substitution on parts of words, the pattern would have to be
-\regexp{\e bword\e b}, in order to require that \samp{word} have a
-word boundary on either side. This takes the job beyond
-\method{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 \code{re.sub('\e n', ' ', S)}, but
-\method{translate()} is capable of doing both tasks
-and will be faster than any regular expression operation can be.
-
-In short, before turning to the \module{re} module, consider whether
-your problem can be solved with a faster and simpler string method.
-
-\subsection{match() versus search()}
-
-The \function{match()} function only checks if the RE matches at
-the beginning of the string while \function{search()} will scan
-forward through the string for a match.
-It's important to keep this distinction in mind. Remember,
-\function{match()} will only report a successful match which
-will start at 0; if the match wouldn't start at zero,
-\function{match()} will \emph{not} report it.
-
-\begin{verbatim}
->>> print re.match('super', 'superstition').span()
-(0, 5)
->>> print re.match('super', 'insuperable')
-None
-\end{verbatim}
-
-On the other hand, \function{search()} will scan forward through the
-string, reporting the first match it finds.
-
-\begin{verbatim}
->>> print re.search('super', 'superstition').span()
-(0, 5)
->>> print re.search('super', 'insuperable').span()
-(2, 7)
-\end{verbatim}
-
-Sometimes you'll be tempted to keep using \function{re.match()}, and
-just add \regexp{.*} to the front of your RE. Resist this temptation
-and use \function{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
-\regexp{Crow} must match starting with a \character{C}. The analysis
-lets the engine quickly scan through the string looking for the
-starting character, only trying the full match if a \character{C} is found.
-
-Adding \regexp{.*} 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 \function{re.search()} instead.
-
-\subsection{Greedy versus Non-Greedy}
-
-When repeating a regular expression, as in \regexp{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 na{\"\i}ve pattern for matching a single HTML tag doesn't
-work because of the greedy nature of \regexp{.*}.
-
-\begin{verbatim}
->>> 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>
-\end{verbatim}
-
-The RE matches the \character{<} in \samp{<html>}, and the
-\regexp{.*} consumes the rest of the string. There's still more left
-in the RE, though, and the \regexp{>} 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 \regexp{>}.
-The final match extends from the \character{<} in \samp{<html>}
-to the \character{>} in \samp{</title>}, which isn't what you want.
-
-In this case, the solution is to use the non-greedy qualifiers
-\regexp{*?}, \regexp{+?}, \regexp{??}, or
-\regexp{\{\var{m},\var{n}\}?}, which match as \emph{little} text as
-possible. In the above example, the \character{>} is tried
-immediately after the first \character{<} matches, and when it fails,
-the engine advances a character at a time, retrying the \character{>}
-at every step. This produces just the right result:
-
-\begin{verbatim}
->>> print re.match('<.*?>', s).group()
-<html>
-\end{verbatim}
-
-(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 \emph{very} complicated. Use an
-HTML or XML parser module for such tasks.)
-
-\subsection{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 \code{re.VERBOSE} flag when
-compiling the regular expression can be helpful, because it allows
-you to format the regular expression more clearly.
-
-The \code{re.VERBOSE} flag has several effects. Whitespace in the
-regular expression that \emph{isn't} inside a character class is
-ignored. This means that an expression such as \regexp{dog | cat} is
-equivalent to the less readable \regexp{dog|cat}, but \regexp{[a b]}
-will still match the characters \character{a}, \character{b}, or a
-space. In addition, you can also put comments inside a RE; comments
-extend from a \samp{\#} character to the next newline. When used with
-triple-quoted strings, this enables REs to be formatted more neatly:
-
-\begin{verbatim}
-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)
-\end{verbatim}
-% $
-
-This is far more readable than:
-
-\begin{verbatim}
-pat = re.compile(r"\s*(?P<header>[^:]+)\s*:(?P<value>.*?)\s*$")
-\end{verbatim}
-% $
-
-\section{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 \citetitle{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
-\module{regex} module, which won't help you much.) Consider checking
-it out from your library.
-
-\end{document}
-
diff --git a/Doc/howto/sockets.tex b/Doc/howto/sockets.tex
deleted file mode 100644
index 0cecbb9..0000000
--- a/Doc/howto/sockets.tex
+++ /dev/null
@@ -1,465 +0,0 @@
-\documentclass{howto}
-
-\title{Socket Programming HOWTO}
-
-\release{0.00}
-
-\author{Gordon McMillan}
-\authoraddress{\email{gmcm@hypernet.com}}
-
-\begin{document}
-\maketitle
-
-\begin{abstract}
-\noindent
-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.
-
-This document is available from the Python HOWTO page at
-\url{http://www.python.org/doc/howto}.
-
-\end{abstract}
-
-\tableofcontents
-
-\section{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.
-
-
-\subsection{History}
-
-Of the various forms of IPC (\emph{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).
-
-\section{Creating a Socket}
-
-Roughly speaking, when you clicked on the link that brought you to
-this page, your browser did something like the following:
-
-\begin{verbatim}
- #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))
-\end{verbatim}
-
-When the \code{connect} completes, the socket \code{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".
-
-\begin{verbatim}
- #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)
-\end{verbatim}
-
-A couple things to notice: we used \code{socket.gethostname()}
-so that the socket would be visible to the outside world. If we had
-used \code{s.bind(('', 80))} or \code{s.bind(('localhost',
-80))} or \code{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 \code{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:
-
-\begin{verbatim}
- 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()
-\end{verbatim}
-
-There's actually 3 general ways in which this loop could work -
-dispatching a thread to handle \code{clientsocket}, create a new
-process to handle \code{clientsocket}, or restructure this app
-to use non-blocking sockets, and mulitplex between our "server" socket
-and any active \code{clientsocket}s using
-\code{select}. More about that later. The important thing to
-understand now is this: this is \emph{all} a "server" socket
-does. It doesn't send any data. It doesn't receive any data. It just
-produces "client" sockets. Each \code{clientsocket} is created
-in response to some \emph{other} "client" socket doing a
-\code{connect()} to the host and port we're bound to. As soon as
-we've created that \code{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.
-
-\subsection{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
-\code{'localhost'}. On most platforms, this will take a shortcut
-around a couple of layers of network code and be quite a bit faster.
-
-
-\section{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, \emph{as the
-designer, you will have to decide what the rules of etiquette are for
-a conversation}. Normally, the \code{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
-\code{send} and \code{recv}, or you can transform your
-client socket into a file-like beast and use \code{read} and
-\code{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 \code{flush} on sockets. These are buffered
-"files", and a common mistake is to \code{write} something, and
-then \code{read} for a reply. Without a \code{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 - \code{send}
-and \code{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
-(\code{send}) or emptied (\code{recv}). They then tell you
-how many bytes they handled. It is \emph{your} responsibility to call
-them again until your message has been completely dealt with.
-
-When a \code{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 \emph{there is no "EOT" (End of Transfer) on a
-socket.} I repeat: if a socket \code{send} or
-\code{recv} returns after handling 0 bytes, the connection has
-been broken. If the connection has \emph{not} been broken, you may
-wait on a \code{recv} forever, because the socket will
-\emph{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: \emph{messages must either be fixed length} (yuck),
-\emph{or be delimited} (shrug), \emph{or indicate how long they are}
-(much better), \emph{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:
-
-\begin{verbatim}
-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
-\end{verbatim}
-
-The sending code here is usable for almost any messaging scheme - in
-Python you send strings, and you can use \code{len()} to
-determine its length (even if it has embedded \code{\e 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
-\code{strlen} if the message has embedded \code{\e 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 \code{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 \code{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 \code{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 \code{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
-\code{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.
-
-\subsection{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 - \code{ntohl, htonl, ntohs,
-htons} where "n" means \emph{network} and "h" means \emph{host},
-"s" means \emph{short} and "l" means \emph{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.
-
-\section{Disconnecting}
-
-Strictly speaking, you're supposed to use \code{shutdown} on a
-socket before you \code{close} it. The \code{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 \code{close} is the same as
-\code{shutdown(); close()}. So in most situations, an explicit
-\code{shutdown} is not needed.
-
-One way to use \code{shutdown} effectively is in an HTTP-like
-exchange. The client sends a request and then does a
-\code{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 \code{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 \code{close} if it's needed. But relying on this is a very bad habit. If your socket just disappears without doing a \code{close}, the socket at the other end may hang indefinitely, thinking you're just being slow. \emph{Please} \code{close} your sockets when you're done.
-
-
-\subsection{When Sockets Die}
-
-Probably the worst thing about using blocking sockets is what happens
-when the other side comes down hard (without doing a
-\code{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 \emph{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.
-
-\section{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 \code{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 \code{O_NONBLOCK} and the almost
-indistinguishable Posix flavor \code{O_NDELAY}, which is
-completely different from \code{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 \code{send},
-\code{recv}, \code{connect} and \code{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 \code{select}.
-
-In C, coding \code{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 \code{select} in Python, you'll have little trouble
-with it in C.
-
-\begin{verbatim} ready_to_read, ready_to_write, in_error = \\
- select.select(
- potential_readers,
- potential_writers,
- potential_errs,
- timeout)
-\end{verbatim}
-
-You pass \code{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 \code{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
-\code{recv} on that socket will return \emph{something}. Same
-idea for the writable list. You'll be able to send
-\emph{something}. Maybe not all you want to, but \emph{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 \code{accept}
-will (almost certainly) work. If you have created a new socket to
-\code{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 \code{select}: if somewhere in those
-input lists of sockets is one which has died a nasty death, the
-\code{select} will fail. You then need to loop through every
-single damn socket in all those lists and do a
-\code{select([sock],[],[],0)} until you find the bad one. That
-timeout of 0 means it won't take long, but it's ugly.
-
-Actually, \code{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.
-
-\textbf{Portability alert}: On Unix, \code{select} works both with
-the sockets and files. Don't try this on Windows. On Windows,
-\code{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.)
-
-\subsection{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 \code{select} instead of
-\code{recv}.
-
-\end{document}
diff --git a/Doc/howto/unicode.rst b/Doc/howto/unicode.rst
deleted file mode 100644
index dffe2cb..0000000
--- a/Doc/howto/unicode.rst
+++ /dev/null
@@ -1,766 +0,0 @@
-Unicode HOWTO
-================
-
-**Version 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
- ``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 ``unicode`` type,
-one of Python's repertoire of built-in types. It derives from an
-abstract type called ``basestring``, which is also an ancestor of the
-``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 ``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
-``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 `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 ``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 ``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
-``codecs`` module here. If you need to implement a completely new
-encoding, you'll need to learn about the ``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 ``codecs`` module is the
-``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
-``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 <http://docs.python.org/lib/typesseq.html>.
-
-The documentation for the ``unicodedata`` module is at
-<http://docs.python.org/lib/module-unicodedata.html>.
-
-The documentation for the ``codecs`` module is at
-<http://docs.python.org/lib/module-codecs.html>.
-
-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 ``codecs`` module includes a
-version of the ``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 ``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 ``os`` module such as ``os.stat()`` will also accept
-Unicode filenames.
-
-``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? ``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 ``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)
diff --git a/Doc/howto/urllib2.rst b/Doc/howto/urllib2.rst
deleted file mode 100644
index f8f4a2b..0000000
--- a/Doc/howto/urllib2.rst
+++ /dev/null
@@ -1,603 +0,0 @@
-==============================================
- HOWTO Fetch Internet Resources Using urllib2
-==============================================
-----------------------------
- Fetching URLs With Python
-----------------------------
-
-
-.. 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>`_.
-
-.. contents:: urllib2 Tutorial
-
-
-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.
-
- This HOWTO is written by `Michael Foord
- <http://www.voidspace.org.uk/python/index.shtml>`_.
-
-**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 `urllib2 docs <http://docs.python.org/lib/module-urllib2.html>`_ ,
-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 as 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 as 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 as e:
- print 'The server couldn\'t fulfill the request.'
- print 'Error code: ', e.code
- except URLError as 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 as 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 ``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>`_.
-
diff --git a/Doc/html/about.dat b/Doc/html/about.dat
deleted file mode 100644
index e6f8b55..0000000
--- a/Doc/html/about.dat
+++ /dev/null
@@ -1,24 +0,0 @@
-<p> This document was generated using the <a
- href="http://saftsack.fs.uni-bayreuth.de/;SPMtilde;latex2ht/">
- <strong>LaTeX</strong>2<tt>HTML</tt></a> translator.
-</p>
-
-<p> <a
- href="http://saftsack.fs.uni-bayreuth.de/;SPMtilde;latex2ht/">
- <strong>LaTeX</strong>2<tt>HTML</tt></a> is Copyright ©
- 1993, 1994, 1995, 1996, 1997, <a
- href="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos
- Drakos</a>, Computer Based Learning Unit, University of
- Leeds, and Copyright © 1997, 1998, <a
- href="http://www.maths.mq.edu.au/;SPMtilde;ross/">Ross
- Moore</a>, Mathematics Department, Macquarie University,
- Sydney.
-</p>
-
-<p> The application of <a
- href="http://saftsack.fs.uni-bayreuth.de/;SPMtilde;latex2ht/">
- <strong>LaTeX</strong>2<tt>HTML</tt></a> to the Python
- documentation has been heavily tailored by Fred L. Drake,
- Jr. Original navigation icons were contributed by Christopher
- Petrilli.
-</p>
diff --git a/Doc/html/about.html b/Doc/html/about.html
deleted file mode 100644
index 3b15a65..0000000
--- a/Doc/html/about.html
+++ /dev/null
@@ -1,84 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<html>
- <head>
- <title>About the Python Documentation</title>
- <meta name="description"
- content="Overview information about the Python documentation">
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <link rel="contents" href="index.html" title="Python Documentation Index">
- <link rel="index" href="modindex.html" title="Global Module Index">
- <link rel="start" href="index.html" title="Python Documentation Index">
- <link rel="up" href="index.html" title="Python Documentation Index">
- <link rel="SHORTCUT ICON" href="icons/pyfav.png" type="image/png">
- <link rel="STYLESHEET" href="lib/lib.css">
- </head>
- <body>
- <div class="navigation">
- <table width="100%" cellpadding="0" cellspacing="2">
- <tr>
- <td><img width="32" height="32" align="bottom" border="0" alt=""
- src="icons/blank.png"></td>
- <td><a href="index.html"
- title="Python Documentation Index"><img width="32" height="32"
- align="bottom" border="0" alt="up"
- src="icons/up.png"></a></td>
- <td><img width="32" height="32" align="bottom" border="0" alt=""
- src="icons/blank.png"></td>
- <td align="center" width="100%">About the Python Documentation</td>
- <td><img width="32" height="32" align="bottom" border="0" alt=""
- src="icons/blank.png"></td>
- <td><img width="32" height="32" align="bottom" border="0" alt=""
- src="icons/blank.png"></td>
- <td><img width="32" height="32" align="bottom" border="0" alt=""
- src="icons/blank.png"></td>
- </tr>
- </table>
- <b class="navlabel">Up:</b>
- <span class="sectref">
- <a href="index.html" title="Python Documentation Index">
- Python Documentation Index</A></span>
- <br>
- </div>
- <hr>
-
- <h2>About the Python Documentation</h2>
-
- <p>The Python documentation was originally written by Guido van
- Rossum, but has increasingly become a community effort over the
- past several years. This growing collection of documents is
- available in several formats, including typeset versions in PDF
- and PostScript for printing, from the <a
- href="http://www.python.org/">Python Web site</a>.
-
- <p>A <a href="acks.html">list of contributors</a> is available.
-
- <h2>Comments and Questions</h2>
-
- <p> General comments and questions regarding this document should
- be sent by email to <a href="mailto:docs@python.org"
- >docs@python.org</a>. If you find specific errors in
- this document, please report the bug at the <a
- href="http://sourceforge.net/bugs/?group_id=5470">Python Bug
- Tracker</a> at <a href="http://sourceforge.net/">SourceForge</a>.
- If you are able to provide suggested text, either to replace
- existing incorrect or unclear material, or additional text to
- supplement what's already available, we'd appreciate the
- contribution. There's no need to worry about text markup; our
- documentation team will gladly take care of that.
- </p>
-
- <p> Questions regarding how to use the information in this
- document should be sent to the Python news group, <a
- href="news:comp.lang.python">comp.lang.python</a>, or the <a
- href="http://www.python.org/mailman/listinfo/python-list"
- >Python mailing list</a> (which is gated to the newsgroup and
- carries the same content).
- </p>
-
- <p> For any of these channels, please be sure not to send HTML email.
- Thanks.
- </p>
-
- <hr>
- </body>
-</html>
diff --git a/Doc/html/icons/blank.gif b/Doc/html/icons/blank.gif
deleted file mode 100644
index 2e31f4e..0000000
--- a/Doc/html/icons/blank.gif
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/blank.png b/Doc/html/icons/blank.png
deleted file mode 100644
index 2af5639..0000000
--- a/Doc/html/icons/blank.png
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/contents.gif b/Doc/html/icons/contents.gif
deleted file mode 100644
index 6d299c4..0000000
--- a/Doc/html/icons/contents.gif
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/contents.png b/Doc/html/icons/contents.png
deleted file mode 100644
index 3429be0..0000000
--- a/Doc/html/icons/contents.png
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/index.gif b/Doc/html/icons/index.gif
deleted file mode 100644
index 32eecfb..0000000
--- a/Doc/html/icons/index.gif
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/index.png b/Doc/html/icons/index.png
deleted file mode 100644
index cd918af..0000000
--- a/Doc/html/icons/index.png
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/modules.gif b/Doc/html/icons/modules.gif
deleted file mode 100644
index f5860b6..0000000
--- a/Doc/html/icons/modules.gif
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/modules.png b/Doc/html/icons/modules.png
deleted file mode 100644
index 8fa8b75..0000000
--- a/Doc/html/icons/modules.png
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/next.gif b/Doc/html/icons/next.gif
deleted file mode 100644
index 5dcaff8..0000000
--- a/Doc/html/icons/next.gif
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/next.png b/Doc/html/icons/next.png
deleted file mode 100644
index cfe5e51..0000000
--- a/Doc/html/icons/next.png
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/previous.gif b/Doc/html/icons/previous.gif
deleted file mode 100644
index de1da16..0000000
--- a/Doc/html/icons/previous.gif
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/previous.png b/Doc/html/icons/previous.png
deleted file mode 100644
index 497def4..0000000
--- a/Doc/html/icons/previous.png
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/pyfav.gif b/Doc/html/icons/pyfav.gif
deleted file mode 100644
index 58271ed..0000000
--- a/Doc/html/icons/pyfav.gif
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/pyfav.png b/Doc/html/icons/pyfav.png
deleted file mode 100644
index d2d8669..0000000
--- a/Doc/html/icons/pyfav.png
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/up.gif b/Doc/html/icons/up.gif
deleted file mode 100644
index a9d3e13..0000000
--- a/Doc/html/icons/up.gif
+++ /dev/null
Binary files differ
diff --git a/Doc/html/icons/up.png b/Doc/html/icons/up.png
deleted file mode 100644
index a90e028..0000000
--- a/Doc/html/icons/up.png
+++ /dev/null
Binary files differ
diff --git a/Doc/html/index.html.in b/Doc/html/index.html.in
deleted file mode 100644
index 412f1d5..0000000
--- a/Doc/html/index.html.in
+++ /dev/null
@@ -1,140 +0,0 @@
-<html>
- <head>
- <title>Python @RELEASE@ Documentation - @DATE@</title>
- <meta name="aesop" content="links">
- <meta name="description"
- content="Top-level index to the standard documentation for
- Python @RELEASE@.">
- <link rel="SHORTCUT ICON" href="icons/pyfav.png" type="image/png">
- <link rel="STYLESHEET" href="lib/lib.css" type="text/css">
- <link rel="author" href="acks.html" title="Acknowledgements">
- <link rel="help" href="about.html" title="About the Python Documentation">
- <link rel="index" href="modindex.html" title="Global Module Index">
- <style type="text/css">
- a.title { font-weight: bold; font-size: 110%; }
- ul { margin-left: 1em; padding: 0pt; border: 0pt; }
- ul li { margin-top: 0.2em; }
- td.left-column { padding-right: 1em; }
- td.right-column { padding-left: 1em; }
- </style>
- </head>
- <body>
- <div class="navigation">
- <table align="center" width="100%" cellpadding="0" cellspacing="2">
- <tr>
- <td><img width="32" height="32" align="bottom" border="0" alt=""
- src="icons/blank.png"></td>
- <td><img width="32" height="32" align="bottom" border="0" alt=""
- src="icons/blank.png"></td>
- <td><img width="32" height="32" align="bottom" border="0" alt=""
- src="icons/blank.png"></td>
- <td align="center" width="100%">
- <b class="title">Python Documentation</b></td>
- <td><img width="32" height="32" align="bottom" border="0" alt=""
- src="icons/blank.png"></td>
- <td><a href="modindex.html"><img width="32" height="32"
- align="bottom" border="0" alt="Module Index"
- src="icons/modules.png"></a></td>
- <td><img width="32" height="32" align="bottom" border="0" alt=""
- src="icons/blank.png"></A></td>
- </tr>
- </table>
- <hr>
- </div>
- <div align="center" class="titlepage">
- <h1>Python Documentation</h1>
-
- <p>
- <strong>Release @RELEASE@</strong>
- <br>
- <strong>@DATE@</strong>
- </p>
- </div>
-
- <table align="center">
- <tbody>
- <tr>
- <td class="left-column">
- <ul>
- <li> <a href="tut/tut.html" class="title">Tutorial</a>
- <br>(start here)
- </ul>
- </td>
- <td class="right-column">
- <ul>
- <li> <a href="whatsnew/@WHATSNEW@.html" class="title"
- >What's New in Python</a>
- <br>(changes since the last major release)
- </ul>
- </td>
- </tr>
- <tr>
- <td valign="baseline" class="left-column">
-
- <ul>
- <li> <a href="modindex.html" class="title">Global Module Index</a>
- <br>(for quick access to all documentation)
-
- <li> <a href="lib/lib.html" class="title">Library Reference</a>
- <br>(keep this under your pillow)
-
- <li> <a href="mac/mac.html" class="title">Macintosh Module
- Reference</a>
- <br>(this too, if you use a Macintosh)
-
- <li> <a href="inst/inst.html" class="title">Installing
- Python Modules</a>
- <br>(for administrators)
-
- <li> <a href="dist/dist.html" class="title">Distributing
- Python Modules</a>
- <br>(for developers and packagers)
- </ul>
- </td>
- <td valign="baseline" class="right-column">
-
- <ul>
- <li> <a href="ref/ref.html" class="title">Language Reference</a>
- <br>(for language lawyers)
-
- <li> <a href="ext/ext.html" class="title">Extending and
- Embedding</a>
- <br>(tutorial for C/C++ programmers)
-
- <li> <a href="api/api.html" class="title">Python/C API</a>
- <br>(reference for C/C++ programmers)
-
- <li> <a href="doc/doc.html" class="title">Documenting Python</a>
- <br>(information for documentation authors)
- </ul>
- </td>
- </tr>
- <tr>
- <td valign="baseline" class="left-column">
-
- <ul>
- <li> <a href="http://www.python.org/doc/" class="title"
- >Documentation Central</a>
- <br>(for everyone)
- </ul>
- </td>
- <td valign="baseline" class="right-column">
-
- <ul>
- <li> <a href="http://www.python.org/doc/howto/" class="title"
- >Python How-To Guides</a>
- <br>(special topics)
- </ul>
- </td>
- </tr>
- </tbody>
- </table>
- <p>
-
- <address>
- <hr>
- See <i><a href="about.html">About the Python Documentation</a></i>
- for information on suggesting changes.
- </address>
- </body>
-</html>
diff --git a/Doc/html/stdabout.dat b/Doc/html/stdabout.dat
deleted file mode 100644
index 7509354..0000000
--- a/Doc/html/stdabout.dat
+++ /dev/null
@@ -1,54 +0,0 @@
-<p> This document was generated using the <a
- href="http://saftsack.fs.uni-bayreuth.de/;SPMtilde;latex2ht/">
- <strong>LaTeX</strong>2<tt>HTML</tt></a> translator.
-</p>
-
-<p> <a
- href="http://saftsack.fs.uni-bayreuth.de/;SPMtilde;latex2ht/">
- <strong>LaTeX</strong>2<tt>HTML</tt></a> is Copyright ©
- 1993, 1994, 1995, 1996, 1997, <a
- href="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos
- Drakos</a>, Computer Based Learning Unit, University of
- Leeds, and Copyright © 1997, 1998, <a
- href="http://www.maths.mq.edu.au/;SPMtilde;ross/">Ross
- Moore</a>, Mathematics Department, Macquarie University,
- Sydney.
-</p>
-
-<p> The application of <a
- href="http://saftsack.fs.uni-bayreuth.de/;SPMtilde;latex2ht/">
- <strong>LaTeX</strong>2<tt>HTML</tt></a> to the Python
- documentation has been heavily tailored by Fred L. Drake,
- Jr. Original navigation icons were contributed by Christopher
- Petrilli.
-</p>
-
-<hr>
-
-<h2>Comments and Questions</h2>
-
-<p> General comments and questions regarding this document should
- be sent by email to <a href="mailto:docs@python.org"
- >docs@python.org</a>. If you find specific errors in
- this document, either in the content or the presentation, please
- report the bug at the <a
- href="http://sourceforge.net/bugs/?group_id=5470">Python Bug
- Tracker</a> at <a href="http://sourceforge.net/">SourceForge</a>.
- If you are able to provide suggested text, either to replace
- existing incorrect or unclear material, or additional text to
- supplement what's already available, we'd appreciate the
- contribution. There's no need to worry about text markup; our
- documentation team will gladly take care of that.
-</p>
-
-<p> Questions regarding how to use the information in this
- document should be sent to the Python news group, <a
- href="news:comp.lang.python">comp.lang.python</a>, or the <a
- href="http://www.python.org/mailman/listinfo/python-list"
- >Python mailing list</a> (which is gated to the newsgroup and
- carries the same content).
-</p>
-
-<p> For any of these channels, please be sure not to send HTML email.
- Thanks.
-</p>
diff --git a/Doc/html/style.css b/Doc/html/style.css
deleted file mode 100644
index f0a2086..0000000
--- a/Doc/html/style.css
+++ /dev/null
@@ -1,246 +0,0 @@
-/*
- * The first part of this is the standard CSS generated by LaTeX2HTML,
- * with the "empty" declarations removed.
- */
-
-/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */
-.math { font-family: "Century Schoolbook", serif; }
-.math i { font-family: "Century Schoolbook", serif;
- font-weight: bold }
-.boldmath { font-family: "Century Schoolbook", serif;
- font-weight: bold }
-
-/*
- * Implement both fixed-size and relative sizes.
- *
- * I think these can be safely removed, as it doesn't appear that
- * LaTeX2HTML ever generates these, even though these are carried
- * over from the LaTeX2HTML stylesheet.
- */
-small.xtiny { font-size : xx-small; }
-small.tiny { font-size : x-small; }
-small.scriptsize { font-size : smaller; }
-small.footnotesize { font-size : small; }
-big.xlarge { font-size : large; }
-big.xxlarge { font-size : x-large; }
-big.huge { font-size : larger; }
-big.xhuge { font-size : xx-large; }
-
-/*
- * Document-specific styles come next;
- * these are added for the Python documentation.
- *
- * Note that the size specifications for the H* elements are because
- * Netscape on Solaris otherwise doesn't get it right; they all end up
- * the normal text size.
- */
-
-body { color: #000000;
- background-color: #ffffff; }
-
-a:link:active { color: #ff0000; }
-a:link:hover { background-color: #bbeeff; }
-a:visited:hover { background-color: #bbeeff; }
-a:visited { color: #551a8b; }
-a:link { color: #0000bb; }
-
-h1, h2, h3, h4, h5, h6 { font-family: avantgarde, sans-serif;
- font-weight: bold; }
-h1 { font-size: 180%; }
-h2 { font-size: 150%; }
-h3, h4 { font-size: 120%; }
-
-/* These are section titles used in navigation links, so make sure we
- * match the section header font here, even it not the weight.
- */
-.sectref { font-family: avantgarde, sans-serif; }
-/* And the label before the titles in navigation: */
-.navlabel { font-size: 85%; }
-
-
-/* LaTeX2HTML insists on inserting <br> elements into headers which
- * are marked with \label. This little bit of CSS magic ensures that
- * these elements don't cause spurious whitespace to be added.
- */
-h1>br, h2>br, h3>br,
-h4>br, h5>br, h6>br { display: none; }
-
-code, tt { font-family: "lucida typewriter", lucidatypewriter,
- monospace; }
-var { font-family: times, serif;
- font-style: italic;
- font-weight: normal; }
-
-.Unix { font-variant: small-caps; }
-
-.typelabel { font-family: lucida, sans-serif; }
-
-.navigation td { background-color: #99ccff;
- font-weight: bold;
- font-family: avantgarde, sans-serif;
- font-size: 110%; }
-
-div.warning { background-color: #fffaf0;
- border: thin solid black;
- padding: 1em;
- margin-left: 2em;
- margin-right: 2em; }
-
-div.warning .label { font-family: sans-serif;
- font-size: 110%;
- margin-right: 0.5em; }
-
-div.note { background-color: #fffaf0;
- border: thin solid black;
- padding: 1em;
- margin-left: 2em;
- margin-right: 2em; }
-
-div.note .label { margin-right: 0.5em;
- font-family: sans-serif; }
-
-.versionnote1 { display: none; }
-.versionnote2 { display: none; }
-
-address { font-size: 80%; }
-.release-info { font-style: italic;
- font-size: 80%; }
-
-.titlegraphic { vertical-align: top; }
-
-.verbatim pre { color: #00008b;
- font-family: "lucida typewriter", lucidatypewriter,
- monospace;
- font-size: 90%; }
-.verbatim { margin-left: 2em; }
-.verbatim .footer { padding: 0.05in;
- font-size: 85%;
- background-color: #99ccff;
- margin-right: 0.5in; }
-
-.grammar { background-color: #99ccff;
- margin-right: 0.5in;
- padding: 0.05in; }
-.grammar-footer { padding: 0.05in;
- font-size: 85%; }
-.grammartoken { font-family: "lucida typewriter", lucidatypewriter,
- monospace; }
-
-.productions { background-color: #bbeeff; }
-.productions a:active { color: #ff0000; }
-.productions a:link:hover { background-color: #99ccff; }
-.productions a:visited:hover { background-color: #99ccff; }
-.productions a:visited { color: #551a8b; }
-.productions a:link { color: #0000bb; }
-.productions table { vertical-align: baseline;
- empty-cells: show; }
-.productions > table td,
-.productions > table th { padding: 2px; }
-.productions > table td:first-child,
-.productions > table td:last-child {
- font-family: "lucida typewriter",
- lucidatypewriter,
- monospace;
- }
-/* same as the second selector above, but expressed differently for Opera */
-.productions > table td:first-child + td + td {
- font-family: "lucida typewriter",
- lucidatypewriter,
- monospace;
- vertical-align: baseline;
- }
-.productions > table td:first-child + td {
- padding-left: 1em;
- padding-right: 1em;
- }
-.productions > table tr { vertical-align: baseline; }
-
-.email { font-family: avantgarde, sans-serif; }
-.mailheader { font-family: avantgarde, sans-serif; }
-.mimetype { font-family: avantgarde, sans-serif; }
-.newsgroup { font-family: avantgarde, sans-serif; }
-.url { font-family: avantgarde, sans-serif; }
-.file { font-family: avantgarde, sans-serif; }
-.guilabel { font-family: avantgarde, sans-serif; }
-
-.realtable { border-collapse: collapse;
- border-color: black;
- border-style: solid;
- border-width: 0px 0px 2px 0px;
- empty-cells: show;
- margin-left: auto;
- margin-right: auto;
- padding-left: 0.4em;
- padding-right: 0.4em;
- }
-.realtable tbody { vertical-align: baseline; }
-.realtable tfoot { display: table-footer-group; }
-.realtable thead { background-color: #99ccff;
- border-width: 0px 0px 2px 1px;
- display: table-header-group;
- font-family: avantgarde, sans-serif;
- font-weight: bold;
- vertical-align: baseline;
- }
-.realtable thead :first-child {
- border-width: 0px 0px 2px 0px;
- }
-.realtable thead th { border-width: 0px 0px 2px 1px }
-.realtable td,
-.realtable th { border-color: black;
- border-style: solid;
- border-width: 0px 0px 1px 1px;
- padding-left: 0.4em;
- padding-right: 0.4em;
- }
-.realtable td:first-child,
-.realtable th:first-child {
- border-left-width: 0px;
- vertical-align: baseline;
- }
-.center { text-align: center; }
-.left { text-align: left; }
-.right { text-align: right; }
-
-.refcount-info { font-style: italic; }
-.refcount-info .value { font-weight: bold;
- color: #006600; }
-
-/*
- * Some decoration for the "See also:" blocks, in part inspired by some of
- * the styling on Lars Marius Garshol's XSA pages.
- * (The blue in the navigation bars is #99CCFF.)
- */
-.seealso { background-color: #fffaf0;
- border: thin solid black;
- padding: 0pt 1em 4pt 1em; }
-
-.seealso > .heading { font-size: 110%;
- font-weight: bold; }
-
-/*
- * Class 'availability' is used for module availability statements at
- * the top of modules.
- */
-.availability .platform { font-weight: bold; }
-
-
-/*
- * Additional styles for the distutils package.
- */
-.du-command { font-family: monospace; }
-.du-option { font-family: avantgarde, sans-serif; }
-.du-filevar { font-family: avantgarde, sans-serif;
- font-style: italic; }
-.du-xxx:before { content: "** ";
- font-weight: bold; }
-.du-xxx:after { content: " **";
- font-weight: bold; }
-
-
-/*
- * Some specialization for printed output.
- */
-@media print {
- .online-navigation { display: none; }
- }
diff --git a/Doc/info/Makefile b/Doc/info/Makefile
deleted file mode 100644
index a9a037b..0000000
--- a/Doc/info/Makefile
+++ /dev/null
@@ -1,82 +0,0 @@
-# Generate the Python "info" documentation.
-
-TOPDIR=..
-TOOLSDIR=$(TOPDIR)/tools
-HTMLDIR=$(TOPDIR)/html
-
-# The emacs binary used to build the info docs. GNU Emacs 21 is required.
-EMACS=emacs
-
-MKINFO=$(TOOLSDIR)/mkinfo
-SCRIPTS=$(TOOLSDIR)/checkargs.pm $(TOOLSDIR)/mkinfo $(TOOLSDIR)/py2texi.el
-
-# set VERSION to code the VERSION number into the info file name
-# allowing installation of more than one set of python info docs
-# into the same directory
-VERSION=
-
-all: check-emacs-version \
- api dist ext mac ref tut whatsnew \
- lib
-# doc inst
-
-api: python$(VERSION)-api.info
-dist: python$(VERSION)-dist.info
-doc: python$(VERSION)-doc.info
-ext: python$(VERSION)-ext.info
-inst: python$(VERSION)-inst.info
-lib: python$(VERSION)-lib.info
-mac: python$(VERSION)-mac.info
-ref: python$(VERSION)-ref.info
-tut: python$(VERSION)-tut.info
-whatsnew: $(WHATSNEW)
-$(WHATSNEW): python$(VERSION)-$(WHATSNEW).info
-
-check-emacs-version:
- @v="`$(EMACS) --version 2>&1 | egrep '^(GNU |X)Emacs [12]*'`"; \
- if `echo "$$v" | grep '^GNU Emacs 2[12]' >/dev/null 2>&1`; then \
- echo "Using $(EMACS) to build the info docs"; \
- else \
- echo "GNU Emacs 21 or 22 is required to build the info docs"; \
- echo "Found $$v"; \
- false; \
- fi
-
-python$(VERSION)-api.info: ../api/api.tex $(SCRIPTS)
- EMACS=$(EMACS) $(MKINFO) $< $*.texi $@
-
-python$(VERSION)-ext.info: ../ext/ext.tex $(SCRIPTS)
- EMACS=$(EMACS) $(MKINFO) $< $*.texi $@
-
-python$(VERSION)-lib.info: ../lib/lib.tex $(SCRIPTS)
- EMACS=$(EMACS) $(MKINFO) $< $*.texi $@
-
-python$(VERSION)-mac.info: ../mac/mac.tex $(SCRIPTS)
- EMACS=$(EMACS) $(MKINFO) $< $*.texi $@
-
-python$(VERSION)-ref.info: ../ref/ref.tex $(SCRIPTS)
- EMACS=$(EMACS) $(MKINFO) $< $*.texi $@
-
-python$(VERSION)-tut.info: ../tut/tut.tex $(SCRIPTS)
- EMACS=$(EMACS) $(MKINFO) $< $*.texi $@
-
-# Not built by default; the conversion doesn't handle \p and \op
-python$(VERSION)-doc.info: ../doc/doc.tex $(SCRIPTS)
- EMACS=$(EMACS) $(MKINFO) $< $*.texi $@
-
-python$(VERSION)-dist.info: ../dist/dist.tex $(SCRIPTS)
- EMACS=$(EMACS) $(MKINFO) $< $*.texi $@
-
-# Not built by default; the conversion chokes on \installscheme
-python$(VERSION)-inst.info: ../inst/inst.tex $(SCRIPTS)
- EMACS=$(EMACS) $(MKINFO) $< $*.texi $@
-
-# "whatsnew20" doesn't currently work
-python$(VERSION)-$(WHATSNEW).info: ../whatsnew/$(WHATSNEW).tex $(SCRIPTS)
- EMACS=$(EMACS) $(MKINFO) $< $*.texi $@
-
-clean:
- rm -f *.texi~ *.texi
-
-clobber: clean
- rm -f *.texi python*-*.info python*-*.info-[0-9]*
diff --git a/Doc/info/README b/Doc/info/README
deleted file mode 100644
index bcee2be..0000000
--- a/Doc/info/README
+++ /dev/null
@@ -1,21 +0,0 @@
-This archive contains the standard Python documentation in GNU info
-format. Five manuals are included:
-
- python-ref.info* Python Reference Manual
- python-mac.info* Python Macintosh Modules
- python-lib.info* Python Library Reference
- python-ext.info* Extending and Embedding the Python Interpreter
- python-api.info* Python/C API Reference
- python-tut.info* Python Tutorial
-
-The file python.dir is a fragment of a "dir" file that can be used to
-incorporate these documents into an existing GNU info installation:
-insert the contents of this file into the "dir" or "localdir" file at
-an appropriate point and copy the python-*.info* files to the same
-directory.
-
-Thanks go to Milan Zamazal <pdm@zamazal.org> for providing this
-conversion to the info format.
-
-Questions and comments on these documents should be directed to
-docs@python.org.
diff --git a/Doc/info/python.dir b/Doc/info/python.dir
deleted file mode 100644
index a215dec..0000000
--- a/Doc/info/python.dir
+++ /dev/null
@@ -1,11 +0,0 @@
-
-Python Standard Documentation
-
-* What's New: (python-whatsnew25). What's New in Python 2.5?
-* Python Library: (python-lib). Python Library Reference
-* Python Mac Modules: (python-mac). Python Macintosh Modules
-* Python Reference: (python-ref). Python Reference Manual
-* Python API: (python-api). Python/C API Reference Manual
-* Python Extending: (python-ext). Extending & Embedding Python
-* Python Tutorial: (python-tut). Python Tutorial
-* Distributing Modules: (python-dist). Distributing Python Modules
diff --git a/Doc/inst/inst.tex b/Doc/inst/inst.tex
deleted file mode 100644
index adc686e..0000000
--- a/Doc/inst/inst.tex
+++ /dev/null
@@ -1,1112 +0,0 @@
-\documentclass{howto}
-\usepackage{distutils}
-
-% TODO:
-% Fill in XXX comments
-
-\title{Installing Python Modules}
-
-% 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!
-
-\input{boilerplate}
-
-\author{Greg Ward}
-\authoraddress{
- \strong{Python Software Foundation}\\
- Email: \email{distutils-sig@python.org}
-}
-
-\makeindex
-
-\begin{document}
-
-\maketitle
-
-\begin{abstract}
- \noindent
- 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.
-\end{abstract}
-
-%\begin{abstract}
-%\noindent
-%Abstract this!
-%\end{abstract}
-
-
-% The ugly "%begin{latexonly}" pseudo-environment suppresses the table
-% of contents for HTML generation.
-%
-%begin{latexonly}
-\tableofcontents
-%end{latexonly}
-
-
-\section{Introduction}
-\label{intro}
-
-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 \citetitle[../dist/dist.html]{Distributing Python Modules} manual.
-
-
-\subsection{Best case: trivial installation}
-\label{trivial-install}
-
-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, \code{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.
-
-
-\subsection{The new standard: Distutils}
-\label{new-standard}
-
-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
-
-\begin{verbatim}
-python setup.py install
-\end{verbatim}
-
-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.
-
-
-\section{Standard Build and Install}
-\label{standard-install}
-
-As described in section~\ref{new-standard}, building and installing
-a module distribution using the Distutils is usually one simple command:
-
-\begin{verbatim}
-python setup.py install
-\end{verbatim}
-
-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.
-
-
-\subsection{Platform variations}
-\label{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:
-
-\begin{verbatim}
-gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0
-cd foo-1.0
-python setup.py install
-\end{verbatim}
-
-On Windows, you'd probably download \file{foo-1.0.zip}. If you
-downloaded the archive file to \file{C:\textbackslash{}Temp}, then it
-would unpack into \file{C:\textbackslash{}Temp\textbackslash{}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:
-
-\begin{verbatim}
-cd c:\Temp\foo-1.0
-python setup.py install
-\end{verbatim}
-
-\subsection{Splitting the job up}
-\label{splitting-up}
-
-Running \code{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:
-
-\begin{verbatim}
-python setup.py build
-python setup.py install
-\end{verbatim}
-
-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.
-
-
-\subsection{How building works}
-\label{how-build-works}
-
-As implied above, the \command{build} command is responsible for putting
-the files to install into a \emph{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 \longprogramopt{build-base} option.
-For example:
-
-\begin{verbatim}
-python setup.py build --build-base=/tmp/pybuild/foo-1.0
-\end{verbatim}
-
-(Or you could do this permanently with a directive in your system or
-personal Distutils configuration file; see
-section~\ref{config-files}.) Normally, this isn't necessary.
-
-The default layout for the build tree is as follows:
-
-\begin{verbatim}
---- build/ --- lib/
-or
---- build/ --- lib.<plat>/
- temp.<plat>/
-\end{verbatim}
-
-where \code{<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/\Cpp),
-then the second form, with two \code{<plat>} directories, is used. In
-that case, the \file{temp.\filevar{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.\filevar{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.
-
-
-\subsection{How installation works}
-\label{how-install-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.\filevar{plat}})
-to your chosen installation directory.
-
-If you don't choose an installation directory---i.e., if you just run
-\code{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''):
-\begin{tableiv}{l|l|l|c}{textrm}%
- {Platform}{Standard installation location}{Default value}{Notes}
- \lineiv{\UNIX{} (pure)}
- {\filenq{\filevar{prefix}/lib/python\shortversion/site-packages}}
- {\filenq{/usr/local/lib/python\shortversion/site-packages}}
- {(1)}
- \lineiv{\UNIX{} (non-pure)}
- {\filenq{\filevar{exec-prefix}/lib/python\shortversion/site-packages}}
- {\filenq{/usr/local/lib/python\shortversion/site-packages}}
- {(1)}
- \lineiv{Windows}
- {\filenq{\filevar{prefix}}}
- {\filenq{C:\textbackslash{}Python}}
- {(2)}
-\end{tableiv}
-
-\noindent Notes:
-\begin{description}
-\item[(1)] Most Linux distributions include Python as a standard part of
- the system, so \filevar{prefix} and \filevar{exec-prefix} are usually
- both \file{/usr} on Linux. If you build Python yourself on Linux (or
- any \UNIX-like system), the default \filevar{prefix} and
- \filevar{exec-prefix} are \file{/usr/local}.
-\item[(2)] The default installation directory on Windows was
- \file{C:\textbackslash{}Program Files\textbackslash{}Python} under
- Python 1.6a1, 1.5.2, and earlier.
-\end{description}
-
-\filevar{prefix} and \filevar{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 \filevar{prefix} and \filevar{exec-prefix} by
-running Python in interactive mode and typing a few simple commands.
-Under \UNIX, just type \code{python} at the shell prompt. Under
-Windows, choose \menuselection{Start \sub Programs \sub Python
-\shortversion \sub 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
-\filevar{prefix} and \filevar{exec-prefix}:
-
-\begin{verbatim}
-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'
-\end{verbatim}
-
-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{alt-install}. If you want to
-customize your installation directories more heavily, see
-section~\ref{custom-install} on custom installations.
-
-
-% This rather nasty macro is used to generate the tables that describe
-% each installation scheme. It's nasty because it takes two arguments
-% for each "slot" in an installation scheme, there will soon be more
-% than five of these slots, and TeX has a limit of 10 arguments to a
-% macro. Uh-oh.
-
-\newcommand{\installscheme}[8]
- {\begin{tableiii}{l|l|l}{textrm}
- {Type of file}
- {Installation Directory}
- {Override option}
- \lineiii{pure module distribution}
- {\filevar{#1}\filenq{#2}}
- {\longprogramopt{install-purelib}}
- \lineiii{non-pure module distribution}
- {\filevar{#3}\filenq{#4}}
- {\longprogramopt{install-platlib}}
- \lineiii{scripts}
- {\filevar{#5}\filenq{#6}}
- {\longprogramopt{install-scripts}}
- \lineiii{data}
- {\filevar{#7}\filenq{#8}}
- {\longprogramopt{install-data}}
- \end{tableiii}}
-
-
-\section{Alternate Installation}
-\label{alt-install}
-
-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
-\emph{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.
-
-
-\subsection{Alternate installation: the home scheme}
-\label{alt-install-prefix}
-
-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
-
-\begin{verbatim}
-python setup.py install --home=<dir>
-\end{verbatim}
-
-where you can supply any directory you like for the
-\longprogramopt{home} option. On \UNIX, lazy typists can just type a
-tilde (\code{\textasciitilde}); the \command{install} command will
-expand this to your home directory:
-
-\begin{verbatim}
-python setup.py install --home=~
-\end{verbatim}
-
-The \longprogramopt{home} option defines the installation base
-directory. Files are installed to the following directories under the
-installation base as follows:
-\installscheme{home}{/lib/python}
- {home}{/lib/python}
- {home}{/bin}
- {home}{/share}
-
-
-\versionchanged[The \longprogramopt{home} option used to be supported
- only on \UNIX]{2.4}
-
-
-\subsection{Alternate installation: \UNIX{} (the prefix scheme)}
-\label{alt-install-home}
-
-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.\filevar{X}} rather than
-\file{/usr/lib/python2.\filevar{X}}. This can be done with
-
-\begin{verbatim}
-/usr/bin/python setup.py install --prefix=/usr/local
-\end{verbatim}
-
-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.\filevar{X}},
-but those modules would have to be installed to, say,
-\file{/mnt/\filevar{@server}/export/lib/python2.\filevar{X}}. This
-could be done with
-
-\begin{verbatim}
-/usr/local/bin/python setup.py install --prefix=/mnt/@server/export
-\end{verbatim}
-
-In either case, the \longprogramopt{prefix} option defines the
-installation base, and the \longprogramopt{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 \longprogramopt{exec-prefix} is not supplied, it defaults to
-\longprogramopt{prefix}. Files are installed as follows:
-
-\installscheme{prefix}{/lib/python2.\filevar{X}/site-packages}
- {exec-prefix}{/lib/python2.\filevar{X}/site-packages}
- {prefix}{/bin}
- {prefix}{/share}
-
-There is no requirement that \longprogramopt{prefix} or
-\longprogramopt{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
-\longprogramopt{prefix} and \longprogramopt{exec-prefix} supplied by
-Python itself as \code{sys.prefix} and \code{sys.exec\_prefix}. Thus,
-you might think you'll never use the prefix scheme, but every time you
-run \code{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 \longprogramopt{prefix} and \longprogramopt{exec-prefix} don't even
-point to an alternate Python installation, this is immaterial.)
-
-
-\subsection{Alternate installation: Windows (the prefix scheme)}
-\label{alt-install-windows}
-
-Windows has no concept of a user's home directory, and since the
-standard Python installation under Windows is simpler than under
-\UNIX, the \longprogramopt{prefix} option has traditionally been used
-to install additional packages in separate locations on Windows.
-
-\begin{verbatim}
-python setup.py install --prefix="\Temp\Python"
-\end{verbatim}
-
-to install modules to the
-\file{\textbackslash{}Temp\textbackslash{}Python} directory on the
-current drive.
-
-The installation base is defined by the \longprogramopt{prefix} option;
-the \longprogramopt{exec-prefix} option is not supported under Windows.
-Files are installed as follows:
-\installscheme{prefix}{}
- {prefix}{}
- {prefix}{\textbackslash{}Scripts}
- {prefix}{\textbackslash{}Data}
-
-
-
-\section{Custom Installation}
-\label{custom-install}
-
-Sometimes, the alternate installation schemes described in
-section~\ref{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 \emph{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
-\longprogramopt{prefix} and \longprogramopt{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{\textasciitilde/scripts} rather than \file{\textasciitilde/bin}.
-As you might expect, you can override this directory with the
-\longprogramopt{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):
-
-\begin{verbatim}
-python setup.py install --home=~ --install-scripts=scripts
-\end{verbatim}
-
-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 \longprogramopt{install-scripts} option:
-
-\begin{verbatim}
-python setup.py install --install-scripts=/usr/local/bin
-\end{verbatim}
-
-(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 \filevar{prefix}, rather than right in
-\filevar{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:
-
-\begin{verbatim}
-python setup.py install --install-purelib=Site --install-platlib=Site
-\end{verbatim}
-
-The specified installation directories are relative to
-\filevar{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 \filevar{prefix}. See section~\ref{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:
-
-\begin{verbatim}
-python setup.py install --home=~ \
- --install-purelib=python/lib \
- --install-platlib=python/lib.$PLAT \
- --install-scripts=python/scripts
- --install-data=python/data
-\end{verbatim}
-% $ % -- bow to font-lock
-
-or, equivalently,
-
-\begin{verbatim}
-python setup.py install --home=~/python \
- --install-purelib=lib \
- --install-platlib='lib.$PLAT' \
- --install-scripts=scripts
- --install-data=data
-\end{verbatim}
-% $ % -- bow to font-lock
-
-\code{\$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).
-
-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{config-files}):
-
-\begin{verbatim}
-[install]
-install-base=$HOME
-install-purelib=python/lib
-install-platlib=python/lib.$PLAT
-install-scripts=python/scripts
-install-data=python/data
-\end{verbatim}
-
-or, equivalently,
-
-\begin{verbatim}
-[install]
-install-base=$HOME/python
-install-purelib=lib
-install-platlib=lib.$PLAT
-install-scripts=scripts
-install-data=data
-\end{verbatim}
-
-Note that these two are \emph{not} equivalent if you supply a different
-installation base directory when you run the setup script. For example,
-
-\begin{verbatim}
-python setup.py install --install-base=/tmp
-\end{verbatim}
-
-would install pure modules to \filevar{/tmp/python/lib} in the first
-case, and to \filevar{/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 \code{\$HOME} and \code{\$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 \code{\$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{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.
-\subsection{Modifying Python's Search Path}
-\label{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 \module{sys} module and printing the value of
-\code{sys.path}.
-
-\begin{verbatim}
-$ 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']
->>>
-\end{verbatim} % $ <-- bow to font-lock
-
-The null string in \code{sys.path} represents the current working
-directory.
-
-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 \code{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 \code{sys.path}. (Because the new paths are
-appended to \code{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
-\citetitle[http://www.python.org/dev/doc/devel/lib/module-site.html]
-{site module documentation} for more information.
-
-A slightly less convenient way is to edit the \file{site.py} file in
-Python's standard library, and modify \code{sys.path}. \file{site.py}
-is automatically imported when the Python interpreter is executed,
-unless the \programopt{-S} switch is supplied to suppress this
-behaviour. So you could simply edit \file{site.py} and add two lines to it:
-
-\begin{verbatim}
-import sys
-sys.path.append('/www/python/')
-\end{verbatim}
-
-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 \code{sys.path}.
-\envvar{PYTHONHOME} sets an alternate value for the prefix of the
-Python installation. For example, if \envvar{PYTHONHOME} is set to
-\samp{/www/python}, the search path will be set to \code{['',
-'/www/python/lib/python\shortversion/',
-'/www/python/lib/python\shortversion/plat-linux2', ...]}.
-
-The \envvar{PYTHONPATH} variable can be set to a list of paths that
-will be added to the beginning of \code{sys.path}. For example, if
-\envvar{PYTHONPATH} is set to \samp{/www/python:/opt/py}, the search
-path will begin with \code{['/www/python', '/opt/py']}. (Note that
-directories must exist in order to be added to \code{sys.path}; the
-\module{site} module removes paths that don't exist.)
-
-Finally, \code{sys.path} is just a regular Python list, so any Python
-application can modify it by adding or removing entries.
-
-
-\section{Distutils Configuration Files}
-\label{config-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.
-
-
-\subsection{Location and names of config files}
-\label{config-filenames}
-
-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:
-\begin{tableiii}{l|l|c}{textrm}
- {Type of file}{Location and filename}{Notes}
- \lineiii{system}{\filenq{\filevar{prefix}/lib/python\filevar{ver}/distutils/distutils.cfg}}{(1)}
- \lineiii{personal}{\filenq{\$HOME/.pydistutils.cfg}}{(2)}
- \lineiii{local}{\filenq{setup.cfg}}{(3)}
-\end{tableiii}
-
-And on Windows, the configuration files are:
-\begin{tableiii}{l|l|c}{textrm}
- {Type of file}{Location and filename}{Notes}
- \lineiii{system}{\filenq{\filevar{prefix}\textbackslash{}Lib\textbackslash{}distutils\textbackslash{}distutils.cfg}}{(4)}
- \lineiii{personal}{\filenq{\%HOME\%\textbackslash{}pydistutils.cfg}}{(5)}
- \lineiii{local}{\filenq{setup.cfg}}{(3)}
-\end{tableiii}
-
-\noindent Notes:
-\begin{description}
-\item[(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{\filevar{prefix}/lib/python1.5/site-packages/distutils},
- so the system configuration file should be put there under Python
- 1.5.2.
-\item[(2)] On \UNIX, if the \envvar{HOME} environment variable is not
- defined, the user's home directory will be determined with the
- \function{getpwuid()} function from the standard
- \ulink{\module{pwd}}{../lib/module-pwd.html} module.
-\item[(3)] I.e., in the current directory (usually the location of the
- setup script).
-\item[(4)] (See also note (1).) Under Python 1.6 and later, Python's
- default ``installation prefix'' is \file{C:\textbackslash{}Python}, so
- the system configuration file is normally
- \file{C:\textbackslash{}Python\textbackslash{}Lib\textbackslash{}distutils\textbackslash{}distutils.cfg}.
- Under Python 1.5.2, the default prefix was
- \file{C:\textbackslash{}Program~Files\textbackslash{}Python}, and the
- Distutils were not part of the standard library---so the system
- configuration file would be
- \file{C:\textbackslash{}Program~Files\textbackslash{}Python\textbackslash{}distutils\textbackslash{}distutils.cfg}
- in a standard Python 1.5.2 installation under Windows.
-\item[(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.)
-\end{description}
-
-
-\subsection{Syntax of config files}
-\label{config-syntax}
-
-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 \code{global} section for global options that affect
-every command. Each section consists of one option per line, specified
-as \code{option=value}.
-
-For example, the following is a complete config file that just forces
-all commands to run quietly by default:
-
-\begin{verbatim}
-[global]
-verbose=0
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-[build]
-build-base=blib
-force=1
-\end{verbatim}
-
-which corresponds to the command-line arguments
-
-\begin{verbatim}
-python setup.py build --build-base=blib --force
-\end{verbatim}
-
-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
-\longprogramopt{help} option, e.g.:
-
-\begin{verbatim}
-python setup.py build --help
-\end{verbatim}
-
-and you can find out the complete list of global options by using
-\longprogramopt{help} without a command:
-
-\begin{verbatim}
-python setup.py --help
-\end{verbatim}
-
-See also the ``Reference'' section of the ``Distributing Python
-Modules'' manual.
-
-\section{Building Extensions: Tips and Tricks}
-\label{building-ext}
-
-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.
-
-\subsection{Tweaking compiler/linker flags}
-\label{tweak-flags}
-
-Compiling a Python extension written in C or \Cpp{} 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:
-
-\begin{alltt}
-\var{module} ... [\var{sourcefile} ...] [\var{cpparg} ...] [\var{library} ...]
-\end{alltt}
-
-Let's examine each of the fields in turn.
-
-\begin{itemize}
-
-\item \var{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.
-
-\item \var{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
- \Cpp, and filenames ending in \file{.m} or \file{.mm} are
- assumed to be in Objective C.
-
-\item \var{cpparg} is an argument for the C preprocessor,
- and is anything starting with \programopt{-I}, \programopt{-D},
- \programopt{-U} or \programopt{-C}.
-
-\item \var{library} is anything ending in \file{.a} or beginning with
- \programopt{-l} or \programopt{-L}.
-\end{itemize}
-
-If a particular platform requires a special library on your platform,
-you can add it by editing the \file{Setup} file and running
-\code{python setup.py build}. For example, if the module defined by the line
-
-\begin{verbatim}
-foo foomodule.c
-\end{verbatim}
-
-must be linked with the math library \file{libm.a} on your platform,
-simply add \programopt{-lm} to the line:
-
-\begin{verbatim}
-foo foomodule.c -lm
-\end{verbatim}
-
-Arbitrary switches intended for the compiler or the linker can be
-supplied with the \programopt{-Xcompiler} \var{arg} and
-\programopt{-Xlinker} \var{arg} options:
-
-\begin{verbatim}
-foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
-\end{verbatim}
-
-The next option after \programopt{-Xcompiler} and
-\programopt{-Xlinker} will be appended to the proper command line, so
-in the above example the compiler will be passed the \programopt{-o32}
-option, and the linker will be passed \programopt{-shared}. If a
-compiler option requires an argument, you'll have to supply multiple
-\programopt{-Xcompiler} options; for example, to pass \code{-x c++} the
-\file{Setup} file would have to contain
-\code{-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.
-
-
-\subsection{Using non-Microsoft compilers on Windows \label{non-ms-compilers}}
-\sectionauthor{Rene Liebscher}{R.Liebscher@gmx.de}
-
-\subsubsection{Borland \Cpp}
-
-This subsection describes the necessary steps to use Distutils with the
-Borland \Cpp{} compiler version 5.5.
-%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
-
-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 \Cpp, 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:
-
-\begin{verbatim}
-coff2omf python25.lib python25_bcpp.lib
-\end{verbatim}
-
-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}.)\footnote{This also means you could replace all
-existing COFF-libraries with OMF-libraries of the same name.}
-
-To let Distutils compile your extension with Borland \Cpp{} you now have
-to type:
-
-\begin{verbatim}
-python setup.py build --compiler=bcpp
-\end{verbatim}
-
-If you want to use the Borland \Cpp{} compiler as the default, you
-could specify this in your personal or system-wide configuration file
-for Distutils (see section~\ref{config-files}.)
-
-\begin{seealso}
- \seetitle[http://www.borland.com/bcppbuilder/freecompiler/]
- {\Cpp{}Builder Compiler}
- {Information about the free \Cpp{} compiler from Borland,
- including links to the download pages.}
-
- \seetitle[http://www.cyberus.ca/\~{}g_will/pyExtenDL.shtml]
- {Creating Python Extensions Using Borland's Free Compiler}
- {Document describing how to use Borland's free command-line \Cpp
- compiler to build Python.}
-\end{seealso}
-
-
-\subsubsection{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/\Cpp{} compilers in their Cygwin and MinGW
-distributions.\footnote{Check
-\url{http://sources.redhat.com/cygwin/} and
-\url{http://www.mingw.org/} for more information}
-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 \Cpp, because there is no
-program to convert the library.
-% I don't understand what the next line means. --amk
-% (inclusive the references on data structures.)
-
-First you have to create a list of symbols which the Python DLL exports.
-(You can find a good program for this task at
-\url{http://starship.python.net/crew/kernr/mingw32/Notes.html}, see at
-PExports 0.42h there.)
-
-\begin{verbatim}
-pexports python25.dll >python25.def
-\end{verbatim}
-
-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.
-
-\begin{verbatim}
-/cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a
-\end{verbatim}
-
-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
-
-\begin{verbatim}
-python setup.py build --compiler=cygwin
-\end{verbatim}
-
-and for Cygwin in no-cygwin mode\footnote{Then you have no
-\POSIX{} emulation available, but you also don't need
-\file{cygwin1.dll}.} or for MinGW type:
-
-\begin{verbatim}
-python setup.py build --compiler=mingw32
-\end{verbatim}
-
-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{config-files}.)
-
-\begin{seealso}
- \seetitle[http://www.zope.org/Members/als/tips/win32_mingw_modules]
- {Building Python modules on MS Windows platform with MinGW}
- {Information about building the required libraries for the MinGW
- environment.}
-
- \seeurl{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.}
-\end{seealso}
-
-
-
-\end{document}
diff --git a/Doc/lib/archiving.tex b/Doc/lib/archiving.tex
deleted file mode 100644
index 93f5bf7..0000000
--- a/Doc/lib/archiving.tex
+++ /dev/null
@@ -1,8 +0,0 @@
-\chapter{Data Compression and Archiving}
-\label{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.
-
-\localmoduletable
diff --git a/Doc/lib/asttable.tex b/Doc/lib/asttable.tex
deleted file mode 100644
index 326bbbb..0000000
--- a/Doc/lib/asttable.tex
+++ /dev/null
@@ -1,280 +0,0 @@
-\begin{longtableiii}{lll}{class}{Node type}{Attribute}{Value}
-
-\lineiii{Add}{\member{left}}{left operand}
-\lineiii{}{\member{right}}{right operand}
-\hline
-
-\lineiii{And}{\member{nodes}}{list of operands}
-\hline
-
-\lineiii{AssAttr}{}{\emph{attribute as target of assignment}}
-\lineiii{}{\member{expr}}{expression on the left-hand side of the dot}
-\lineiii{}{\member{attrname}}{the attribute name, a string}
-\lineiii{}{\member{flags}}{XXX}
-\hline
-
-\lineiii{AssList}{\member{nodes}}{list of list elements being assigned to}
-\hline
-
-\lineiii{AssName}{\member{name}}{name being assigned to}
-\lineiii{}{\member{flags}}{XXX}
-\hline
-
-\lineiii{AssTuple}{\member{nodes}}{list of tuple elements being assigned to}
-\hline
-
-\lineiii{Assert}{\member{test}}{the expression to be tested}
-\lineiii{}{\member{fail}}{the value of the \exception{AssertionError}}
-\hline
-
-\lineiii{Assign}{\member{nodes}}{a list of assignment targets, one per equal sign}
-\lineiii{}{\member{expr}}{the value being assigned}
-\hline
-
-\lineiii{AugAssign}{\member{node}}{}
-\lineiii{}{\member{op}}{}
-\lineiii{}{\member{expr}}{}
-\hline
-
-\lineiii{Bitand}{\member{nodes}}{}
-\hline
-
-\lineiii{Bitor}{\member{nodes}}{}
-\hline
-
-\lineiii{Bitxor}{\member{nodes}}{}
-\hline
-
-\lineiii{Break}{}{}
-\hline
-
-\lineiii{CallFunc}{\member{node}}{expression for the callee}
-\lineiii{}{\member{args}}{a list of arguments}
-\lineiii{}{\member{star_args}}{the extended *-arg value}
-\lineiii{}{\member{dstar_args}}{the extended **-arg value}
-\hline
-
-\lineiii{Class}{\member{name}}{the name of the class, a string}
-\lineiii{}{\member{bases}}{a list of base classes}
-\lineiii{}{\member{doc}}{doc string, a string or \code{None}}
-\lineiii{}{\member{code}}{the body of the class statement}
-\hline
-
-\lineiii{Compare}{\member{expr}}{}
-\lineiii{}{\member{ops}}{}
-\hline
-
-\lineiii{Const}{\member{value}}{}
-\hline
-
-\lineiii{Continue}{}{}
-\hline
-
-\lineiii{Decorators}{\member{nodes}}{List of function decorator expressions}
-\hline
-
-\lineiii{Dict}{\member{items}}{}
-\hline
-
-\lineiii{Discard}{\member{expr}}{}
-\hline
-
-\lineiii{Div}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{Ellipsis}{}{}
-\hline
-
-\lineiii{Expression}{\member{node}}{}
-
-\lineiii{Exec}{\member{expr}}{}
-\lineiii{}{\member{locals}}{}
-\lineiii{}{\member{globals}}{}
-\hline
-
-\lineiii{FloorDiv}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{For}{\member{assign}}{}
-\lineiii{}{\member{list}}{}
-\lineiii{}{\member{body}}{}
-\lineiii{}{\member{else_}}{}
-\hline
-
-\lineiii{From}{\member{modname}}{}
-\lineiii{}{\member{names}}{}
-\hline
-
-\lineiii{Function}{\member{decorators}}{\class{Decorators} or \code{None}}
-\lineiii{}{\member{name}}{name used in def, a string}
-\lineiii{}{\member{argnames}}{list of argument names, as strings}
-\lineiii{}{\member{defaults}}{list of default values}
-\lineiii{}{\member{flags}}{xxx}
-\lineiii{}{\member{doc}}{doc string, a string or \code{None}}
-\lineiii{}{\member{code}}{the body of the function}
-\hline
-
-\lineiii{GenExpr}{\member{code}}{}
-\hline
-
-\lineiii{GenExprFor}{\member{assign}}{}
-\lineiii{}{\member{iter}}{}
-\lineiii{}{\member{ifs}}{}
-\hline
-
-\lineiii{GenExprIf}{\member{test}}{}
-\hline
-
-\lineiii{GenExprInner}{\member{expr}}{}
-\lineiii{}{\member{quals}}{}
-\hline
-
-\lineiii{Getattr}{\member{expr}}{}
-\lineiii{}{\member{attrname}}{}
-\hline
-
-\lineiii{Global}{\member{names}}{}
-\hline
-
-\lineiii{If}{\member{tests}}{}
-\lineiii{}{\member{else_}}{}
-\hline
-
-\lineiii{Import}{\member{names}}{}
-\hline
-
-\lineiii{Invert}{\member{expr}}{}
-\hline
-
-\lineiii{Keyword}{\member{name}}{}
-\lineiii{}{\member{expr}}{}
-\hline
-
-\lineiii{Lambda}{\member{argnames}}{}
-\lineiii{}{\member{defaults}}{}
-\lineiii{}{\member{flags}}{}
-\lineiii{}{\member{code}}{}
-\hline
-
-\lineiii{LeftShift}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{List}{\member{nodes}}{}
-\hline
-
-\lineiii{ListComp}{\member{expr}}{}
-\lineiii{}{\member{quals}}{}
-\hline
-
-\lineiii{ListCompFor}{\member{assign}}{}
-\lineiii{}{\member{list}}{}
-\lineiii{}{\member{ifs}}{}
-\hline
-
-\lineiii{ListCompIf}{\member{test}}{}
-\hline
-
-\lineiii{Mod}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{Module}{\member{doc}}{doc string, a string or \code{None}}
-\lineiii{}{\member{node}}{body of the module, a \class{Stmt}}
-\hline
-
-\lineiii{Mul}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{Name}{\member{name}}{}
-\hline
-
-\lineiii{Not}{\member{expr}}{}
-\hline
-
-\lineiii{Or}{\member{nodes}}{}
-\hline
-
-\lineiii{Pass}{}{}
-\hline
-
-\lineiii{Power}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{Print}{\member{nodes}}{}
-\lineiii{}{\member{dest}}{}
-\hline
-
-\lineiii{Printnl}{\member{nodes}}{}
-\lineiii{}{\member{dest}}{}
-\hline
-
-\lineiii{Raise}{\member{expr1}}{}
-\lineiii{}{\member{expr2}}{}
-\lineiii{}{\member{expr3}}{}
-\hline
-
-\lineiii{Return}{\member{value}}{}
-\hline
-
-\lineiii{RightShift}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{Slice}{\member{expr}}{}
-\lineiii{}{\member{flags}}{}
-\lineiii{}{\member{lower}}{}
-\lineiii{}{\member{upper}}{}
-\hline
-
-\lineiii{Sliceobj}{\member{nodes}}{list of statements}
-\hline
-
-\lineiii{Stmt}{\member{nodes}}{}
-\hline
-
-\lineiii{Sub}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{Subscript}{\member{expr}}{}
-\lineiii{}{\member{flags}}{}
-\lineiii{}{\member{subs}}{}
-\hline
-
-\lineiii{TryExcept}{\member{body}}{}
-\lineiii{}{\member{handlers}}{}
-\lineiii{}{\member{else_}}{}
-\hline
-
-\lineiii{TryFinally}{\member{body}}{}
-\lineiii{}{\member{final}}{}
-\hline
-
-\lineiii{Tuple}{\member{nodes}}{}
-\hline
-
-\lineiii{UnaryAdd}{\member{expr}}{}
-\hline
-
-\lineiii{UnarySub}{\member{expr}}{}
-\hline
-
-\lineiii{While}{\member{test}}{}
-\lineiii{}{\member{body}}{}
-\lineiii{}{\member{else_}}{}
-\hline
-
-\lineiii{With}{\member{expr}}{}
-\lineiii{}{\member{vars}}{}
-\lineiii{}{\member{body}}{}
-\hline
-
-\lineiii{Yield}{\member{value}}{}
-\hline
-
-\end{longtableiii}
diff --git a/Doc/lib/caseless.py b/Doc/lib/caseless.py
deleted file mode 100755
index cae94be..0000000
--- a/Doc/lib/caseless.py
+++ /dev/null
@@ -1,60 +0,0 @@
-from optparse import Option, OptionParser, _match_abbrev
-
-# This case-insensitive option parser relies on having a
-# case-insensitive dictionary type available. Here's one
-# for Python 2.2. Note that a *real* case-insensitive
-# dictionary type would also have to implement __new__(),
-# update(), and setdefault() -- but that's not the point
-# of this exercise.
-
-class caseless_dict (dict):
- def __setitem__ (self, key, value):
- dict.__setitem__(self, key.lower(), value)
-
- def __getitem__ (self, key):
- return dict.__getitem__(self, key.lower())
-
- def get (self, key, default=None):
- return dict.get(self, key.lower())
-
- def has_key (self, key):
- return dict.has_key(self, key.lower())
-
-
-class CaselessOptionParser (OptionParser):
-
- def _create_option_list (self):
- self.option_list = []
- self._short_opt = caseless_dict()
- self._long_opt = caseless_dict()
- self._long_opts = []
- self.defaults = {}
-
- def _match_long_opt (self, opt):
- return _match_abbrev(opt.lower(), self._long_opt.keys())
-
-
-if __name__ == "__main__":
- from optik.errors import OptionConflictError
-
- # test 1: no options to start with
- parser = CaselessOptionParser()
- try:
- parser.add_option("-H", dest="blah")
- except OptionConflictError:
- print "ok: got OptionConflictError for -H"
- else:
- print "not ok: no conflict between -h and -H"
-
- parser.add_option("-f", "--file", dest="file")
- #print repr(parser.get_option("-f"))
- #print repr(parser.get_option("-F"))
- #print repr(parser.get_option("--file"))
- #print repr(parser.get_option("--fIlE"))
- (options, args) = parser.parse_args(["--FiLe", "foo"])
- assert options.file == "foo", options.file
- print "ok: case insensitive long options work"
-
- (options, args) = parser.parse_args(["-F", "bar"])
- assert options.file == "bar", options.file
- print "ok: case insensitive short options work"
diff --git a/Doc/lib/custominterp.tex b/Doc/lib/custominterp.tex
deleted file mode 100644
index 555b888..0000000
--- a/Doc/lib/custominterp.tex
+++ /dev/null
@@ -1,13 +0,0 @@
-\chapter{Custom Python Interpreters}
-\label{custominterp}
-
-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 \module{code} module. (The \module{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:
-
-\localmoduletable
diff --git a/Doc/lib/datatypes.tex b/Doc/lib/datatypes.tex
deleted file mode 100644
index 0fe03c7..0000000
--- a/Doc/lib/datatypes.tex
+++ /dev/null
@@ -1,10 +0,0 @@
-\chapter{Data Types}
-\label{datatypes}
-
-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.
-
-The following modules are documented in this chapter:
-
-\localmoduletable
diff --git a/Doc/lib/development.tex b/Doc/lib/development.tex
deleted file mode 100644
index 4b4fadc..0000000
--- a/Doc/lib/development.tex
+++ /dev/null
@@ -1,13 +0,0 @@
-\chapter{Development Tools}
-\label{development}
-
-The modules described in this chapter help you write software. For
-example, the \module{pydoc} module takes a module and generates
-documentation based on the module's contents. The \module{doctest}
-and \module{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:
-
-\localmoduletable
diff --git a/Doc/lib/distutils.tex b/Doc/lib/distutils.tex
deleted file mode 100644
index 3de9dde..0000000
--- a/Doc/lib/distutils.tex
+++ /dev/null
@@ -1,38 +0,0 @@
-\section{\module{distutils} ---
- Building and installing Python modules}
-
-\declaremodule{standard}{distutils}
-\modulesynopsis{Support for building and installing Python modules
- into an existing Python installation.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-The \module{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 documents which are included
-in the Python documentation package. To learn about distributing new
-modules using the \module{distutils} facilities, read
-\citetitle[../dist/dist.html]{Distributing Python Modules}; this
-includes documentation needed to extend distutils. To learn
-about installing Python modules, whether or not the author made use of
-the \module{distutils} package, read
-\citetitle[../inst/inst.html]{Installing Python Modules}.
-
-
-\begin{seealso}
- \seetitle[../dist/dist.html]{Distributing Python Modules}{The manual
- for developers and packagers of Python modules. This
- describes how to prepare \module{distutils}-based packages
- so that they may be easily installed into an existing
- Python installation.}
-
- \seetitle[../inst/inst.html]{Installing Python Modules}{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.}
-\end{seealso}
diff --git a/Doc/lib/email-dir.py b/Doc/lib/email-dir.py
deleted file mode 100644
index c04f57d..0000000
--- a/Doc/lib/email-dir.py
+++ /dev/null
@@ -1,115 +0,0 @@
-#!/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()
diff --git a/Doc/lib/email-mime.py b/Doc/lib/email-mime.py
deleted file mode 100644
index 5097253..0000000
--- a/Doc/lib/email-mime.py
+++ /dev/null
@@ -1,32 +0,0 @@
-# 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()
diff --git a/Doc/lib/email-simple.py b/Doc/lib/email-simple.py
deleted file mode 100644
index 44152a4..0000000
--- a/Doc/lib/email-simple.py
+++ /dev/null
@@ -1,25 +0,0 @@
-# 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()
diff --git a/Doc/lib/email-unpack.py b/Doc/lib/email-unpack.py
deleted file mode 100644
index e596b98..0000000
--- a/Doc/lib/email-unpack.py
+++ /dev/null
@@ -1,68 +0,0 @@
-#!/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 as 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()
diff --git a/Doc/lib/email.tex b/Doc/lib/email.tex
deleted file mode 100644
index 3de3df3..0000000
--- a/Doc/lib/email.tex
+++ /dev/null
@@ -1,402 +0,0 @@
-% Copyright (C) 2001-2007 Python Software Foundation
-% Author: barry@python.org (Barry Warsaw)
-
-\section{\module{email} ---
- An email and MIME handling package}
-
-\declaremodule{standard}{email}
-\modulesynopsis{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 \module{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 \refmodule{rfc822}, \refmodule{mimetools},
-\refmodule{multifile}, and other non-standard packages such as
-\module{mimecntl}. It is specifically \emph{not} designed to do any
-sending of email messages to SMTP (\rfc{2821}), NNTP, or other servers; those
-are functions of modules such as \refmodule{smtplib} and \refmodule{nntplib}.
-The \module{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 \module{email} package is
-that it splits the parsing and generating of email messages from the
-internal \emph{object model} representation of email. Applications
-using the \module{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
-\module{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 \module{email} package provides, the exception
-classes you might encounter while using the \module{email} package,
-some auxiliary utilities, and a few examples. For users of the older
-\module{mimelib} package, or previous versions of the \module{email}
-package, a section on differences and porting is provided.
-
-\begin{seealso}
- \seemodule{smtplib}{SMTP protocol client}
- \seemodule{nntplib}{NNTP protocol client}
-\end{seealso}
-
-\subsection{Representing an email message}
-\input{emailmessage}
-
-\subsection{Parsing email messages}
-\input{emailparser}
-
-\subsection{Generating MIME documents}
-\input{emailgenerator}
-
-\subsection{Creating email and MIME objects from scratch}
-\input{emailmimebase}
-
-\subsection{Internationalized headers}
-\input{emailheaders}
-
-\subsection{Representing character sets}
-\input{emailcharsets}
-
-\subsection{Encoders}
-\input{emailencoders}
-
-\subsection{Exception and Defect classes}
-\input{emailexc}
-
-\subsection{Miscellaneous utilities}
-\input{emailutil}
-
-\subsection{Iterators}
-\input{emailiter}
-
-\subsection{Package History\label{email-pkg-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, \emph{not} the email package
-version. This table also describes the Python compatibility of each version
-of the package.
-
-\begin{tableiii}{l|l|l}{constant}{email version}{distributed with}{compatible with}
-\lineiii{1.x}{Python 2.2.0 to Python 2.2.1}{\emph{no longer supported}}
-\lineiii{2.5}{Python 2.2.2+ and Python 2.3}{Python 2.1 to 2.5}
-\lineiii{3.0}{Python 2.4}{Python 2.3 to 2.5}
-\lineiii{4.0}{Python 2.5}{Python 2.3 to 2.5}
-\end{tableiii}
-
-Here are the major differences between \module{email} version 4 and version 3:
-
-\begin{itemize}
-\item All modules have been renamed according to \pep{8} standards. For
- example, the version 3 module \module{email.Message} was renamed to
- \module{email.message} in version 4.
-
-\item A new subpackage \module{email.mime} was added and all the version 3
- \module{email.MIME*} modules were renamed and situated into the
- \module{email.mime} subpackage. For example, the version 3 module
- \module{email.MIMEText} was renamed to \module{email.mime.text}.
-
- \emph{Note that the version 3 names will continue to work until Python
- 2.6}.
-
-\item The \module{email.mime.application} module was added, which contains the
- \class{MIMEApplication} class.
-
-\item Methods that were deprecated in version 3 have been removed. These
- include \method{Generator.__call__()}, \method{Message.get_type()},
- \method{Message.get_main_type()}, \method{Message.get_subtype()}.
-
-\item Fixes have been added for \rfc{2231} support which can change some of
- the return types for \function{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.
-\end{itemize}
-
-Here are the major differences between \module{email} version 3 and version 2:
-
-\begin{itemize}
-\item 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 \var{defect} attribute.
-
-\item All aspects of the API which raised \exception{DeprecationWarning}s in
- version 2 have been removed. These include the \var{_encoder} argument
- to the \class{MIMEText} constructor, the \method{Message.add_payload()}
- method, the \function{Utils.dump_address_pair()} function, and the
- functions \function{Utils.decode()} and \function{Utils.encode()}.
-
-\item New \exception{DeprecationWarning}s have been added to:
- \method{Generator.__call__()}, \method{Message.get_type()},
- \method{Message.get_main_type()}, \method{Message.get_subtype()}, and
- the \var{strict} argument to the \class{Parser} class. These are
- expected to be removed in future versions.
-
-\item Support for Pythons earlier than 2.3 has been removed.
-\end{itemize}
-
-Here are the differences between \module{email} version 2 and version 1:
-
-\begin{itemize}
-\item The \module{email.Header} and \module{email.Charset} modules
- have been added.
-
-\item 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 \module{email} version 2, \class{Message}
- instances now have private variables \var{_charset} and
- \var{_default_type}.
-
-\item 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.
-
-\item The object structure has changed in the face of
- \mimetype{message/rfc822} content types. In \module{email}
- version 1, such a type would be represented by a scalar payload,
- i.e. the container message's \method{is_multipart()} returned
- false, \method{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 \module{email} version 2, the container
- \emph{does} return \code{True} from \method{is_multipart()}, and
- \method{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 \method{get_payload()}, you should be
- fine. You just need to make sure your code doesn't do a
- \method{set_payload()} with a \class{Message} instance on a
- container with a content type of \mimetype{message/rfc822}.
-
-\item The \class{Parser} constructor's \var{strict} argument was
- added, and its \method{parse()} and \method{parsestr()} methods
- grew a \var{headersonly} argument. The \var{strict} flag was
- also added to functions \function{email.message_from_file()}
- and \function{email.message_from_string()}.
-
-\item \method{Generator.__call__()} is deprecated; use
- \method{Generator.flatten()} instead. The \class{Generator}
- class has also grown the \method{clone()} method.
-
-\item The \class{DecodedGenerator} class in the
- \module{email.Generator} module was added.
-
-\item 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.
-
-\item The \var{_encoder} argument to the \class{MIMEText} constructor
- has been deprecated. Encoding now happens implicitly based
- on the \var{_charset} argument.
-
-\item The following functions in the \module{email.Utils} module have
- been deprecated: \function{dump_address_pairs()},
- \function{decode()}, and \function{encode()}. The following
- functions have been added to the module:
- \function{make_msgid()}, \function{decode_rfc2231()},
- \function{encode_rfc2231()}, and \function{decode_params()}.
-
-\item The non-public function \function{email.Iterators._structure()}
- was added.
-\end{itemize}
-
-\subsection{Differences from \module{mimelib}}
-
-The \module{email} package was originally prototyped as a separate
-library called
-\ulink{\texttt{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
-\module{mimelib} is still available in the \refmodule{email} package,
-albeit often in a different way. Backward compatibility between
-the \module{mimelib} package and the \module{email} package was not a
-priority.
-
-Here is a brief description of the differences between the
-\module{mimelib} and the \refmodule{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 \refmodule{email}. In
-addition, the top-level package has the following differences:
-
-\begin{itemize}
-\item \function{messageFromString()} has been renamed to
- \function{message_from_string()}.
-
-\item \function{messageFromFile()} has been renamed to
- \function{message_from_file()}.
-
-\end{itemize}
-
-The \class{Message} class has the following differences:
-
-\begin{itemize}
-\item The method \method{asString()} was renamed to \method{as_string()}.
-
-\item The method \method{ismultipart()} was renamed to
- \method{is_multipart()}.
-
-\item The \method{get_payload()} method has grown a \var{decode}
- optional argument.
-
-\item The method \method{getall()} was renamed to \method{get_all()}.
-
-\item The method \method{addheader()} was renamed to \method{add_header()}.
-
-\item The method \method{gettype()} was renamed to \method{get_type()}.
-
-\item The method \method{getmaintype()} was renamed to
- \method{get_main_type()}.
-
-\item The method \method{getsubtype()} was renamed to
- \method{get_subtype()}.
-
-\item The method \method{getparams()} was renamed to
- \method{get_params()}.
- Also, whereas \method{getparams()} returned a list of strings,
- \method{get_params()} returns a list of 2-tuples, effectively
- the key/value pairs of the parameters, split on the \character{=}
- sign.
-
-\item The method \method{getparam()} was renamed to \method{get_param()}.
-
-\item The method \method{getcharsets()} was renamed to
- \method{get_charsets()}.
-
-\item The method \method{getfilename()} was renamed to
- \method{get_filename()}.
-
-\item The method \method{getboundary()} was renamed to
- \method{get_boundary()}.
-
-\item The method \method{setboundary()} was renamed to
- \method{set_boundary()}.
-
-\item The method \method{getdecodedpayload()} was removed. To get
- similar functionality, pass the value 1 to the \var{decode} flag
- of the {get_payload()} method.
-
-\item The method \method{getpayloadastext()} was removed. Similar
- functionality
- is supported by the \class{DecodedGenerator} class in the
- \refmodule{email.generator} module.
-
-\item The method \method{getbodyastext()} was removed. You can get
- similar functionality by creating an iterator with
- \function{typed_subpart_iterator()} in the
- \refmodule{email.iterators} module.
-\end{itemize}
-
-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\footnote{Delivery Status Notifications (DSN) are defined
-in \rfc{1894}.}.
-
-The \class{Generator} class has no differences in its public
-interface. There is a new class in the \refmodule{email.generator}
-module though, called \class{DecodedGenerator} which provides most of
-the functionality previously available in the
-\method{Message.getpayloadastext()} method.
-
-The following modules and classes have been changed:
-
-\begin{itemize}
-\item The \class{MIMEBase} class constructor arguments \var{_major}
- and \var{_minor} have changed to \var{_maintype} and
- \var{_subtype} respectively.
-
-\item The \code{Image} class/module has been renamed to
- \code{MIMEImage}. The \var{_minor} argument has been renamed to
- \var{_subtype}.
-
-\item The \code{Text} class/module has been renamed to
- \code{MIMEText}. The \var{_minor} argument has been renamed to
- \var{_subtype}.
-
-\item The \code{MessageRFC822} class/module has been renamed to
- \code{MIMEMessage}. Note that an earlier version of
- \module{mimelib} called this class/module \code{RFC822}, but
- that clashed with the Python standard library module
- \refmodule{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 \var{_subtype} which is used to set the MIME
- subtype. \var{_subtype} defaults to \mimetype{rfc822}.
-\end{itemize}
-
-\module{mimelib} provided some utility functions in its
-\module{address} and \module{date} modules. All of these functions
-have been moved to the \refmodule{email.utils} module.
-
-The \code{MsgReader} class/module has been removed. Its functionality
-is most closely supported in the \function{body_line_iterator()}
-function in the \refmodule{email.iterators} module.
-
-\subsection{Examples}
-
-Here are a few examples of how to use the \module{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:
-
-\verbatiminput{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:
-
-\verbatiminput{email-mime.py}
-
-Here's an example of how to send the entire contents of a directory as
-an email message:
-\footnote{Thanks to Matthew Dixon Cowles for the original inspiration
- and examples.}
-
-\verbatiminput{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:
-
-\verbatiminput{email-unpack.py}
diff --git a/Doc/lib/emailcharsets.tex b/Doc/lib/emailcharsets.tex
deleted file mode 100644
index e0be68a..0000000
--- a/Doc/lib/emailcharsets.tex
+++ /dev/null
@@ -1,244 +0,0 @@
-\declaremodule{standard}{email.charset}
-\modulesynopsis{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 \module{email} package.
-
-Import this class from the \module{email.charset} module.
-
-\versionadded{2.2.2}
-
-\begin{classdesc}{Charset}{\optional{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 \var{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
-\var{input_charset} is \code{iso-8859-1}, then headers and bodies will
-be encoded using quoted-printable and no output conversion codec is
-necessary. If \var{input_charset} is \code{euc-jp}, then headers will
-be encoded with base64, bodies will not be encoded, but output text
-will be converted from the \code{euc-jp} character set to the
-\code{iso-2022-jp} character set.
-\end{classdesc}
-
-\class{Charset} instances have the following data attributes:
-
-\begin{datadesc}{input_charset}
-The initial character set specified. Common aliases are converted to
-their \emph{official} email names (e.g. \code{latin_1} is converted to
-\code{iso-8859-1}). Defaults to 7-bit \code{us-ascii}.
-\end{datadesc}
-
-\begin{datadesc}{header_encoding}
-If the character set must be encoded before it can be used in an
-email header, this attribute will be set to \code{Charset.QP} (for
-quoted-printable), \code{Charset.BASE64} (for base64 encoding), or
-\code{Charset.SHORTEST} for the shortest of QP or BASE64 encoding.
-Otherwise, it will be \code{None}.
-\end{datadesc}
-
-\begin{datadesc}{body_encoding}
-Same as \var{header_encoding}, but describes the encoding for the
-mail message's body, which indeed may be different than the header
-encoding. \code{Charset.SHORTEST} is not allowed for
-\var{body_encoding}.
-\end{datadesc}
-
-\begin{datadesc}{output_charset}
-Some character sets must be converted before they can be used in
-email headers or bodies. If the \var{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 \code{None}.
-\end{datadesc}
-
-\begin{datadesc}{input_codec}
-The name of the Python codec used to convert the \var{input_charset} to
-Unicode. If no conversion codec is necessary, this attribute will be
-\code{None}.
-\end{datadesc}
-
-\begin{datadesc}{output_codec}
-The name of the Python codec used to convert Unicode to the
-\var{output_charset}. If no conversion codec is necessary, this
-attribute will have the same value as the \var{input_codec}.
-\end{datadesc}
-
-\class{Charset} instances also have the following methods:
-
-\begin{methoddesc}[Charset]{get_body_encoding}{}
-Return the content transfer encoding used for body encoding.
-
-This is either the string \samp{quoted-printable} or \samp{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 \samp{quoted-printable} if
-\var{body_encoding} is \code{QP}, returns the string
-\samp{base64} if \var{body_encoding} is \code{BASE64}, and returns the
-string \samp{7bit} otherwise.
-\end{methoddesc}
-
-\begin{methoddesc}{convert}{s}
-Convert the string \var{s} from the \var{input_codec} to the
-\var{output_codec}.
-\end{methoddesc}
-
-\begin{methoddesc}{to_splittable}{s}
-Convert a possibly multibyte string to a safely splittable format.
-\var{s} is the string to split.
-
-Uses the \var{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 \var{s} to
-Unicode with the \var{input_charset}.
-
-Characters that could not be converted to Unicode will be replaced
-with the Unicode replacement character \character{U+FFFD}.
-\end{methoddesc}
-
-\begin{methoddesc}{from_splittable}{ustr\optional{, to_output}}
-Convert a splittable string back into an encoded string. \var{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 \character{?}).
-
-If \var{to_output} is \code{True} (the default), uses
-\var{output_codec} to convert to an
-encoded format. If \var{to_output} is \code{False}, it uses
-\var{input_codec}.
-\end{methoddesc}
-
-\begin{methoddesc}{get_output_charset}{}
-Return the output character set.
-
-This is the \var{output_charset} attribute if that is not \code{None},
-otherwise it is \var{input_charset}.
-\end{methoddesc}
-
-\begin{methoddesc}{encoded_header_len}{}
-Return the length of the encoded header string, properly calculating
-for quoted-printable or base64 encoding.
-\end{methoddesc}
-
-\begin{methoddesc}{header_encode}{s\optional{, convert}}
-Header-encode the string \var{s}.
-
-If \var{convert} is \code{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
-\refmodule{email.header}). \var{convert} defaults to \code{False}.
-
-The type of encoding (base64 or quoted-printable) will be based on
-the \var{header_encoding} attribute.
-\end{methoddesc}
-
-\begin{methoddesc}{body_encode}{s\optional{, convert}}
-Body-encode the string \var{s}.
-
-If \var{convert} is \code{True} (the default), the string will be
-converted from the input charset to output charset automatically.
-Unlike \method{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 \var{body_encoding} attribute.
-\end{methoddesc}
-
-The \class{Charset} class also provides a number of methods to support
-standard operations and built-in functions.
-
-\begin{methoddesc}[Charset]{__str__}{}
-Returns \var{input_charset} as a string coerced to lower case.
-\method{__repr__()} is an alias for \method{__str__()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Charset]{__eq__}{other}
-This method allows you to compare two \class{Charset} instances for equality.
-\end{methoddesc}
-
-\begin{methoddesc}[Header]{__ne__}{other}
-This method allows you to compare two \class{Charset} instances for inequality.
-\end{methoddesc}
-
-The \module{email.charset} module also provides the following
-functions for adding new entries to the global character set, alias,
-and codec registries:
-
-\begin{funcdesc}{add_charset}{charset\optional{, header_enc\optional{,
- body_enc\optional{, output_charset}}}}
-Add character properties to the global registry.
-
-\var{charset} is the input character set, and must be the canonical
-name of a character set.
-
-Optional \var{header_enc} and \var{body_enc} is either
-\code{Charset.QP} for quoted-printable, \code{Charset.BASE64} for
-base64 encoding, \code{Charset.SHORTEST} for the shortest of
-quoted-printable or base64 encoding, or \code{None} for no encoding.
-\code{SHORTEST} is only valid for \var{header_enc}. The default is
-\code{None} for no encoding.
-
-Optional \var{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
-\method{Charset.convert()} is called. The default is to output in the
-same character set as the input.
-
-Both \var{input_charset} and \var{output_charset} must have Unicode
-codec entries in the module's character set-to-codec mapping; use
-\function{add_codec()} to add codecs the module does
-not know about. See the \refmodule{codecs} module's documentation for
-more information.
-
-The global character set registry is kept in the module global
-dictionary \code{CHARSETS}.
-\end{funcdesc}
-
-\begin{funcdesc}{add_alias}{alias, canonical}
-Add a character set alias. \var{alias} is the alias name,
-e.g. \code{latin-1}. \var{canonical} is the character set's canonical
-name, e.g. \code{iso-8859-1}.
-
-The global charset alias registry is kept in the module global
-dictionary \code{ALIASES}.
-\end{funcdesc}
-
-\begin{funcdesc}{add_codec}{charset, codecname}
-Add a codec that map characters in the given character set to and from
-Unicode.
-
-\var{charset} is the canonical name of a character set.
-\var{codecname} is the name of a Python codec, as appropriate for the
-second argument to the \function{unicode()} built-in, or to the
-\method{encode()} method of a Unicode string.
-\end{funcdesc}
diff --git a/Doc/lib/emailencoders.tex b/Doc/lib/emailencoders.tex
deleted file mode 100644
index 3d05c2a..0000000
--- a/Doc/lib/emailencoders.tex
+++ /dev/null
@@ -1,47 +0,0 @@
-\declaremodule{standard}{email.encoders}
-\modulesynopsis{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 \module{email} package provides some convenient encodings in its
-\module{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:
-
-\begin{funcdesc}{encode_quopri}{msg}
-Encodes the payload into quoted-printable form and sets the
-\mailheader{Content-Transfer-Encoding} header to
-\code{quoted-printable}\footnote{Note that encoding with
-\method{encode_quopri()} also encodes all tabs and space characters in
-the data.}.
-This is a good encoding to use when most of your payload is normal
-printable data, but contains a few unprintable characters.
-\end{funcdesc}
-
-\begin{funcdesc}{encode_base64}{msg}
-Encodes the payload into base64 form and sets the
-\mailheader{Content-Transfer-Encoding} header to
-\code{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.
-\end{funcdesc}
-
-\begin{funcdesc}{encode_7or8bit}{msg}
-This doesn't actually modify the message's payload, but it does set
-the \mailheader{Content-Transfer-Encoding} header to either \code{7bit} or
-\code{8bit} as appropriate, based on the payload data.
-\end{funcdesc}
-
-\begin{funcdesc}{encode_noop}{msg}
-This does nothing; it doesn't even set the
-\mailheader{Content-Transfer-Encoding} header.
-\end{funcdesc}
diff --git a/Doc/lib/emailexc.tex b/Doc/lib/emailexc.tex
deleted file mode 100644
index 3cef1d5..0000000
--- a/Doc/lib/emailexc.tex
+++ /dev/null
@@ -1,87 +0,0 @@
-\declaremodule{standard}{email.errors}
-\modulesynopsis{The exception classes used by the email package.}
-
-The following exception classes are defined in the
-\module{email.errors} module:
-
-\begin{excclassdesc}{MessageError}{}
-This is the base class for all exceptions that the \module{email}
-package can raise. It is derived from the standard
-\exception{Exception} class and defines no additional methods.
-\end{excclassdesc}
-
-\begin{excclassdesc}{MessageParseError}{}
-This is the base class for exceptions thrown by the \class{Parser}
-class. It is derived from \exception{MessageError}.
-\end{excclassdesc}
-
-\begin{excclassdesc}{HeaderParseError}{}
-Raised under some error conditions when parsing the \rfc{2822} headers of
-a message, this class is derived from \exception{MessageParseError}.
-It can be raised from the \method{Parser.parse()} or
-\method{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.
-\end{excclassdesc}
-
-\begin{excclassdesc}{BoundaryError}{}
-Raised under some error conditions when parsing the \rfc{2822} headers of
-a message, this class is derived from \exception{MessageParseError}.
-It can be raised from the \method{Parser.parse()} or
-\method{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.
-\end{excclassdesc}
-
-\begin{excclassdesc}{MultipartConversionError}{}
-Raised when a payload is added to a \class{Message} object using
-\method{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. \exception{MultipartConversionError}
-multiply inherits from \exception{MessageError} and the built-in
-\exception{TypeError}.
-
-Since \method{Message.add_payload()} is deprecated, this exception is
-rarely raised in practice. However the exception may also be raised
-if the \method{attach()} method is called on an instance of a class
-derived from \class{MIMENonMultipart} (e.g. \class{MIMEImage}).
-\end{excclassdesc}
-
-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 \emph{not} an exception!
-
-\versionadded[All the defect classes were added]{2.4}
-
-\begin{itemize}
-\item \class{NoBoundaryInMultipartDefect} -- A message claimed to be a
- multipart, but had no \mimetype{boundary} parameter.
-
-\item \class{StartBoundaryNotFoundDefect} -- The start boundary claimed in the
- \mailheader{Content-Type} header was never found.
-
-\item \class{FirstHeaderLineIsContinuationDefect} -- The message had a
- continuation line as its first header line.
-
-\item \class{MisplacedEnvelopeHeaderDefect} - A ``Unix From'' header was found
- in the middle of a header block.
-
-\item \class{MalformedHeaderDefect} -- A header was found that was missing a
- colon, or was otherwise malformed.
-
-\item \class{MultipartInvariantViolationDefect} -- A message claimed to be a
- \mimetype{multipart}, but no subparts were found. Note that when a
- message has this defect, its \method{is_multipart()} method may return
- false even though its content type claims to be \mimetype{multipart}.
-\end{itemize}
diff --git a/Doc/lib/emailgenerator.tex b/Doc/lib/emailgenerator.tex
deleted file mode 100644
index 7ab0a53..0000000
--- a/Doc/lib/emailgenerator.tex
+++ /dev/null
@@ -1,133 +0,0 @@
-\declaremodule{standard}{email.generator}
-\modulesynopsis{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 \refmodule{smtplib}
-module or the \refmodule{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 \refmodule{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
-\module{email.generator} module:
-
-\begin{classdesc}{Generator}{outfp\optional{, mangle_from_\optional{,
- maxheaderlen}}}
-The constructor for the \class{Generator} class takes a file-like
-object called \var{outfp} for an argument. \var{outfp} must support
-the \method{write()} method and be usable as the output file in a
-Python extended print statement.
-
-Optional \var{mangle_from_} is a flag that, when \code{True}, puts a
-\samp{>} character in front of any line in the body that starts exactly as
-\samp{From }, i.e. \code{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
-\ulink{WHY THE CONTENT-LENGTH FORMAT IS BAD}
-{http://www.jwz.org/doc/content-length.html}
-for details). \var{mangle_from_} defaults to \code{True}, but you
-might want to set this to \code{False} if you are not writing \UNIX{}
-mailbox format files.
-
-Optional \var{maxheaderlen} specifies the longest length for a
-non-continued header. When a header line is longer than
-\var{maxheaderlen} (in characters, with tabs expanded to 8 spaces),
-the header will be split as defined in the \module{email.header.Header}
-class. Set to zero to disable header wrapping. The default is 78, as
-recommended (but not required) by \rfc{2822}.
-\end{classdesc}
-
-The other public \class{Generator} methods are:
-
-\begin{methoddesc}[Generator]{flatten}{msg\optional{, unixfrom}}
-Print the textual representation of the message object structure rooted at
-\var{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 \var{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 \code{False} to
-inhibit the printing of the envelope delimiter.
-
-Note that for subparts, no envelope header is ever printed.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Generator]{clone}{fp}
-Return an independent clone of this \class{Generator} instance with
-the exact same options.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Generator]{write}{s}
-Write the string \var{s} to the underlying file object,
-i.e. \var{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.
-\end{methoddesc}
-
-As a convenience, see the methods \method{Message.as_string()} and
-\code{str(aMessage)}, a.k.a. \method{Message.__str__()}, which
-simplify the generation of a formatted string representation of a
-message object. For more detail, see \refmodule{email.message}.
-
-The \module{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.
-
-\begin{classdesc}{DecodedGenerator}{outfp\optional{, mangle_from_\optional{,
- maxheaderlen\optional{, 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 \var{_mangle_from_} and \var{maxheaderlen} are as with the
-\class{Generator} base class.
-
-If the subpart is not of main type \mimetype{text}, optional \var{fmt}
-is a format string that is used instead of the message payload.
-\var{fmt} is expanded with the following keywords, \samp{\%(keyword)s}
-format:
-
-\begin{itemize}
-\item \code{type} -- Full MIME type of the non-\mimetype{text} part
-
-\item \code{maintype} -- Main MIME type of the non-\mimetype{text} part
-
-\item \code{subtype} -- Sub-MIME type of the non-\mimetype{text} part
-
-\item \code{filename} -- Filename of the non-\mimetype{text} part
-
-\item \code{description} -- Description associated with the
- non-\mimetype{text} part
-
-\item \code{encoding} -- Content transfer encoding of the
- non-\mimetype{text} part
-
-\end{itemize}
-
-The default value for \var{fmt} is \code{None}, meaning
-
-\begin{verbatim}
-[Non-text (%(type)s) part of message omitted, filename %(filename)s]
-\end{verbatim}
-
-\versionadded{2.2.2}
-\end{classdesc}
-
-\versionchanged[The previously deprecated method \method{__call__()} was
-removed]{2.5}
diff --git a/Doc/lib/emailheaders.tex b/Doc/lib/emailheaders.tex
deleted file mode 100644
index 524d08c..0000000
--- a/Doc/lib/emailheaders.tex
+++ /dev/null
@@ -1,178 +0,0 @@
-\declaremodule{standard}{email.header}
-\modulesynopsis{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 \module{email} package supports these standards in its
-\module{email.header} and \module{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
-\module{email.header} module. For example:
-
-\begin{verbatim}
->>> 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?=
-
-
-\end{verbatim}
-
-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:
-
-\begin{classdesc}{Header}{\optional{s\optional{, charset\optional{,
- maxlinelen\optional{, header_name\optional{, continuation_ws\optional{,
- errors}}}}}}}
-Create a MIME-compliant header that can contain strings in different
-character sets.
-
-Optional \var{s} is the initial header value. If \code{None} (the
-default), the initial header value is not set. You can later append
-to the header with \method{append()} method calls. \var{s} may be a
-byte string or a Unicode string, but see the \method{append()}
-documentation for semantics.
-
-Optional \var{charset} serves two purposes: it has the same meaning as
-the \var{charset} argument to the \method{append()} method. It also
-sets the default character set for all subsequent \method{append()}
-calls that omit the \var{charset} argument. If \var{charset} is not
-provided in the constructor (the default), the \code{us-ascii}
-character set is used both as \var{s}'s initial charset and as the
-default for subsequent \method{append()} calls.
-
-The maximum line length can be specified explicit via
-\var{maxlinelen}. For splitting the first line to a shorter value (to
-account for the field header which isn't included in \var{s},
-e.g. \mailheader{Subject}) pass in the name of the field in
-\var{header_name}. The default \var{maxlinelen} is 76, and the
-default value for \var{header_name} is \code{None}, meaning it is not
-taken into account for the first line of a long, split header.
-
-Optional \var{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.
-\end{classdesc}
-
-Optional \var{errors} is passed straight through to the
-\method{append()} method.
-
-\begin{methoddesc}[Header]{append}{s\optional{, charset\optional{, errors}}}
-Append the string \var{s} to the MIME header.
-
-Optional \var{charset}, if given, should be a \class{Charset} instance
-(see \refmodule{email.charset}) or the name of a character set, which
-will be converted to a \class{Charset} instance. A value of
-\code{None} (the default) means that the \var{charset} given in the
-constructor is used.
-
-\var{s} may be a byte string or a Unicode string. If it is a byte
-string (i.e. \code{isinstance(s, str)} is true), then
-\var{charset} is the encoding of that byte string, and a
-\exception{UnicodeError} will be raised if the string cannot be
-decoded with that character set.
-
-If \var{s} is a Unicode string, then \var{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: \code{us-ascii}, the \var{charset} hint, \code{utf-8}. The
-first character set to not provoke a \exception{UnicodeError} is used.
-
-Optional \var{errors} is passed through to any \function{unicode()} or
-\function{ustr.encode()} call, and defaults to ``strict''.
-\end{methoddesc}
-
-\begin{methoddesc}[Header]{encode}{\optional{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 \var{splitchars} is a string
-containing characters to split long ASCII lines on, in rough support
-of \rfc{2822}'s \emph{highest level syntactic breaks}. This doesn't
-affect \rfc{2047} encoded lines.
-\end{methoddesc}
-
-The \class{Header} class also provides a number of methods to support
-standard operators and built-in functions.
-
-\begin{methoddesc}[Header]{__str__}{}
-A synonym for \method{Header.encode()}. Useful for
-\code{str(aHeader)}.
-\end{methoddesc}
-
-\begin{methoddesc}[Header]{__unicode__}{}
-A helper for the built-in \function{unicode()} function. Returns the
-header as a Unicode string.
-\end{methoddesc}
-
-\begin{methoddesc}[Header]{__eq__}{other}
-This method allows you to compare two \class{Header} instances for equality.
-\end{methoddesc}
-
-\begin{methoddesc}[Header]{__ne__}{other}
-This method allows you to compare two \class{Header} instances for inequality.
-\end{methoddesc}
-
-The \module{email.header} module also provides the following
-convenient functions.
-
-\begin{funcdesc}{decode_header}{header}
-Decode a message header value without converting the character set.
-The header value is in \var{header}.
-
-This function returns a list of \code{(decoded_string, charset)} pairs
-containing each of the decoded parts of the header. \var{charset} is
-\code{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:
-
-\begin{verbatim}
->>> from email.header import decode_header
->>> decode_header('=?iso-8859-1?q?p=F6stal?=')
-[('p\xf6stal', 'iso-8859-1')]
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{make_header}{decoded_seq\optional{, maxlinelen\optional{,
- header_name\optional{, continuation_ws}}}}
-Create a \class{Header} instance from a sequence of pairs as returned
-by \function{decode_header()}.
-
-\function{decode_header()} takes a header value string and returns a
-sequence of pairs of the format \code{(decoded_string, charset)} where
-\var{charset} is the name of the character set.
-
-This function takes one of those sequence of pairs and returns a
-\class{Header} instance. Optional \var{maxlinelen},
-\var{header_name}, and \var{continuation_ws} are as in the
-\class{Header} constructor.
-\end{funcdesc}
diff --git a/Doc/lib/emailiter.tex b/Doc/lib/emailiter.tex
deleted file mode 100644
index ef8ef6f..0000000
--- a/Doc/lib/emailiter.tex
+++ /dev/null
@@ -1,65 +0,0 @@
-\declaremodule{standard}{email.iterators}
-\modulesynopsis{Iterate over a message object tree.}
-
-Iterating over a message object tree is fairly easy with the
-\method{Message.walk()} method. The \module{email.iterators} module
-provides some useful higher level iterations over message object
-trees.
-
-\begin{funcdesc}{body_line_iterator}{msg\optional{, decode}}
-This iterates over all the payloads in all the subparts of \var{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
-\method{readline()}, skipping over all the intervening headers.
-
-Optional \var{decode} is passed through to \method{Message.get_payload()}.
-\end{funcdesc}
-
-\begin{funcdesc}{typed_subpart_iterator}{msg\optional{,
- maintype\optional{, subtype}}}
-This iterates over all the subparts of \var{msg}, returning only those
-subparts that match the MIME type specified by \var{maintype} and
-\var{subtype}.
-
-Note that \var{subtype} is optional; if omitted, then subpart MIME
-type matching is done only with the main type. \var{maintype} is
-optional too; it defaults to \mimetype{text}.
-
-Thus, by default \function{typed_subpart_iterator()} returns each
-subpart that has a MIME type of \mimetype{text/*}.
-\end{funcdesc}
-
-The following function has been added as a useful debugging tool. It
-should \emph{not} be considered part of the supported public interface
-for the package.
-
-\begin{funcdesc}{_structure}{msg\optional{, fp\optional{, level}}}
-Prints an indented representation of the content types of the
-message object structure. For example:
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
-
-Optional \var{fp} is a file-like object to print the output to. It
-must be suitable for Python's extended print statement. \var{level}
-is used internally.
-\end{funcdesc}
diff --git a/Doc/lib/emailmessage.tex b/Doc/lib/emailmessage.tex
deleted file mode 100644
index 7bd7dd8..0000000
--- a/Doc/lib/emailmessage.tex
+++ /dev/null
@@ -1,561 +0,0 @@
-\declaremodule{standard}{email.message}
-\modulesynopsis{The base class representing email messages.}
-
-The central class in the \module{email} package is the
-\class{Message} class, imported from the \module{email.message} module. It is
-the base class for the \module{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 \emph{headers} and
-\emph{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 \emph{Unix-From} header or the
-\code{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:
-
-\begin{classdesc}{Message}{}
-The constructor takes no arguments.
-\end{classdesc}
-
-\begin{methoddesc}[Message]{as_string}{\optional{unixfrom}}
-Return the entire message flatten as a string. When optional
-\var{unixfrom} is \code{True}, the envelope header is included in the
-returned string. \var{unixfrom} defaults to \code{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 \code{From }. For more flexibility, instantiate a
-\class{Generator} instance and use its
-\method{flatten()} method directly. For example:
-
-\begin{verbatim}
-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()
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{__str__}{}
-Equivalent to \method{as_string(unixfrom=True)}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{is_multipart}{}
-Return \code{True} if the message's payload is a list of
-sub-\class{Message} objects, otherwise return \code{False}. When
-\method{is_multipart()} returns False, the payload should be a string
-object.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_unixfrom}{unixfrom}
-Set the message's envelope header to \var{unixfrom}, which should be a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_unixfrom}{}
-Return the message's envelope header. Defaults to \code{None} if the
-envelope header was never set.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{attach}{payload}
-Add the given \var{payload} to the current payload, which must be
-\code{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 \method{set_payload()} instead.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_payload}{\optional{i\optional{, decode}}}
-Return a reference the current payload, which will be a list of
-\class{Message} objects when \method{is_multipart()} is \code{True}, or a
-string when \method{is_multipart()} is \code{False}. If the
-payload is a list and you mutate the list object, you modify the
-message's payload in place.
-
-With optional argument \var{i}, \method{get_payload()} will return the
-\var{i}-th element of the payload, counting from zero, if
-\method{is_multipart()} is \code{True}. An \exception{IndexError}
-will be raised if \var{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. \method{is_multipart()} is \code{False}) and \var{i} is given, a
-\exception{TypeError} is raised.
-
-Optional \var{decode} is a flag indicating whether the payload should be
-decoded or not, according to the \mailheader{Content-Transfer-Encoding} header.
-When \code{True} and the message is not a multipart, the payload will be
-decoded if this header's value is \samp{quoted-printable} or
-\samp{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
-\var{decode} flag is \code{True}, then \code{None} is returned. The
-default for \var{decode} is \code{False}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_payload}{payload\optional{, charset}}
-Set the entire message object's payload to \var{payload}. It is the
-client's responsibility to ensure the payload invariants. Optional
-\var{charset} sets the message's default character set; see
-\method{set_charset()} for details.
-
-\versionchanged[\var{charset} argument added]{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_charset}{charset}
-Set the character set of the payload to \var{charset}, which can
-either be a \class{Charset} instance (see \refmodule{email.charset}), a
-string naming a character set,
-or \code{None}. If it is a string, it will be converted to a
-\class{Charset} instance. If \var{charset} is \code{None}, the
-\code{charset} parameter will be removed from the
-\mailheader{Content-Type} header. Anything else will generate a
-\exception{TypeError}.
-
-The message will be assumed to be of type \mimetype{text/*} encoded with
-\var{charset.input_charset}. It will be converted to
-\var{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}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_charset}{}
-Return the \class{Charset} instance associated with the message's payload.
-\versionadded{2.2.2}
-\end{methoddesc}
-
-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
-\method{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.
-
-\begin{methoddesc}[Message]{__len__}{}
-Return the total number of headers, including duplicates.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{__contains__}{name}
-Return true if the message object has a field named \var{name}.
-Matching is done case-insensitively and \var{name} should not include the
-trailing colon. Used for the \code{in} operator,
-e.g.:
-
-\begin{verbatim}
-if 'message-id' in myMessage:
- print 'Message-ID:', myMessage['message-id']
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{__getitem__}{name}
-Return the value of the named header field. \var{name} should not
-include the colon field separator. If the header is missing,
-\code{None} is returned; a \exception{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 \method{get_all()} method to get the values of all
-the extant named headers.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{__setitem__}{name, val}
-Add a header to the message with field name \var{name} and value
-\var{val}. The field is appended to the end of the message's existing
-fields.
-
-Note that this does \emph{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
-\var{name}, delete the field first, e.g.:
-
-\begin{verbatim}
-del msg['subject']
-msg['subject'] = 'Python roolz!'
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{__delitem__}{name}
-Delete all occurrences of the field with name \var{name} from the
-message's headers. No exception is raised if the named field isn't
-present in the headers.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{has_key}{name}
-Return true if the message contains a header field named \var{name},
-otherwise return false.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{keys}{}
-Return a list of all the message's header field names.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{values}{}
-Return a list of all the message's field values.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{items}{}
-Return a list of 2-tuples containing all the message's field headers
-and values.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get}{name\optional{, failobj}}
-Return the value of the named header field. This is identical to
-\method{__getitem__()} except that optional \var{failobj} is returned
-if the named header is missing (defaults to \code{None}).
-\end{methoddesc}
-
-Here are some additional useful methods:
-
-\begin{methoddesc}[Message]{get_all}{name\optional{, failobj}}
-Return a list of all the values for the field named \var{name}.
-If there are no such named headers in the message, \var{failobj} is
-returned (defaults to \code{None}).
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{add_header}{_name, _value, **_params}
-Extended header setting. This method is similar to
-\method{__setitem__()} except that additional header parameters can be
-provided as keyword arguments. \var{_name} is the header field to add
-and \var{_value} is the \emph{primary} value for the header.
-
-For each item in the keyword argument dictionary \var{_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 \code{key="value"} unless the value is
-\code{None}, in which case only the key will be added.
-
-Here's an example:
-
-\begin{verbatim}
-msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
-\end{verbatim}
-
-This will add a header that looks like
-
-\begin{verbatim}
-Content-Disposition: attachment; filename="bud.gif"
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{replace_header}{_name, _value}
-Replace a header. Replace the first header found in the message that
-matches \var{_name}, retaining header order and field name case. If
-no matching header was found, a \exception{KeyError} is raised.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[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 \method{get_default_type()} will be returned. Since
-according to \rfc{2045}, messages always have a default type,
-\method{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}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_content_maintype}{}
-Return the message's main content type. This is the
-\mimetype{maintype} part of the string returned by
-\method{get_content_type()}.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_content_subtype}{}
-Return the message's sub-content type. This is the \mimetype{subtype}
-part of the string returned by \method{get_content_type()}.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[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}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_default_type}{ctype}
-Set the default content type. \var{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}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_params}{\optional{failobj\optional{,
- header\optional{, 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 \character{=} sign. The left hand side of the
-\character{=} is the key, while the right hand side is the value. If
-there is no \character{=} sign in the parameter the value is the empty
-string, otherwise the value is as described in \method{get_param()} and is
-unquoted if optional \var{unquote} is \code{True} (the default).
-
-Optional \var{failobj} is the object to return if there is no
-\mailheader{Content-Type} header. Optional \var{header} is the header to
-search instead of \mailheader{Content-Type}.
-
-\versionchanged[\var{unquote} argument added]{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_param}{param\optional{,
- failobj\optional{, header\optional{, unquote}}}}
-Return the value of the \mailheader{Content-Type} header's parameter
-\var{param} as a string. If the message has no \mailheader{Content-Type}
-header or if there is no such parameter, then \var{failobj} is
-returned (defaults to \code{None}).
-
-Optional \var{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 \code{(CHARSET, LANGUAGE, VALUE)}. Note that both \code{CHARSET} and
-\code{LANGUAGE} can be \code{None}, in which case you should consider
-\code{VALUE} to be encoded in the \code{us-ascii} charset. You can
-usually ignore \code{LANGUAGE}.
-
-If your application doesn't care whether the parameter was encoded as in
-\rfc{2231}, you can collapse the parameter value by calling
-\function{email.Utils.collapse_rfc2231_value()}, passing in the return value
-from \method{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:
-
-\begin{verbatim}
-rawparam = msg.get_param('foo')
-param = email.Utils.collapse_rfc2231_value(rawparam)
-\end{verbatim}
-
-In any case, the parameter value (either the returned string, or the
-\code{VALUE} item in the 3-tuple) is always unquoted, unless
-\var{unquote} is set to \code{False}.
-
-\versionchanged[\var{unquote} argument added, and 3-tuple return value
-possible]{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_param}{param, value\optional{,
- header\optional{, requote\optional{, charset\optional{, language}}}}}
-
-Set a parameter in the \mailheader{Content-Type} header. If the
-parameter already exists in the header, its value will be replaced
-with \var{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 \var{header} specifies an alternative header to
-\mailheader{Content-Type}, and all parameters will be quoted as
-necessary unless optional \var{requote} is \code{False} (the default
-is \code{True}).
-
-If optional \var{charset} is specified, the parameter will be encoded
-according to \rfc{2231}. Optional \var{language} specifies the RFC
-2231 language, defaulting to the empty string. Both \var{charset} and
-\var{language} should be strings.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{del_param}{param\optional{, header\optional{,
- 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 \var{requote} is \code{False} (the default is
-\code{True}). Optional \var{header} specifies an alternative to
-\mailheader{Content-Type}.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_type}{type\optional{, header}\optional{,
- requote}}
-Set the main type and subtype for the \mailheader{Content-Type}
-header. \var{type} must be a string in the form
-\mimetype{maintype/subtype}, otherwise a \exception{ValueError} is
-raised.
-
-This method replaces the \mailheader{Content-Type} header, keeping all
-the parameters in place. If \var{requote} is \code{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 \var{header} argument.
-When the \mailheader{Content-Type} header is set a
-\mailheader{MIME-Version} header is also added.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_filename}{\optional{failobj}}
-Return the value of the \code{filename} parameter of the
-\mailheader{Content-Disposition} header of the message. If the header does
-not have a \code{filename} parameter, this method falls back to looking for
-the \code{name} parameter. If neither is found, or the header is missing,
-then \var{failobj} is returned. The returned string will always be unquoted
-as per \method{Utils.unquote()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_boundary}{\optional{failobj}}
-Return the value of the \code{boundary} parameter of the
-\mailheader{Content-Type} header of the message, or \var{failobj} if either
-the header is missing, or has no \code{boundary} parameter. The
-returned string will always be unquoted as per
-\method{Utils.unquote()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_boundary}{boundary}
-Set the \code{boundary} parameter of the \mailheader{Content-Type}
-header to \var{boundary}. \method{set_boundary()} will always quote
-\var{boundary} if necessary. A \exception{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 \method{add_header()}, because \method{set_boundary()} preserves the
-order of the \mailheader{Content-Type} header in the list of headers.
-However, it does \emph{not} preserve any continuation lines which may
-have been present in the original \mailheader{Content-Type} header.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_content_charset}{\optional{failobj}}
-Return the \code{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
-\code{charset} parameter, \var{failobj} is returned.
-
-Note that this method differs from \method{get_charset()} which
-returns the \class{Charset} instance for the default encoding of the
-message body.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_charsets}{\optional{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
-\code{charset} parameter in the \mailheader{Content-Type} header for the
-represented subpart. However, if the subpart has no
-\mailheader{Content-Type} header, no \code{charset} parameter, or is not of
-the \mimetype{text} main MIME type, then that item in the returned list
-will be \var{failobj}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{walk}{}
-The \method{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
-\method{walk()} as the iterator in a \code{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:
-
-\begin{verbatim}
->>> for part in msg.walk():
-... print part.get_content_type()
-multipart/report
-text/plain
-message/delivery-status
-text/plain
-text/plain
-message/rfc822
-\end{verbatim}
-\end{methoddesc}
-
-\versionchanged[The previously deprecated methods \method{get_type()},
-\method{get_main_type()}, and \method{get_subtype()} were removed]{2.5}
-
-\class{Message} objects can also optionally contain two instance
-attributes, which can be used when generating the plain text of a MIME
-message.
-
-\begin{datadesc}{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 \var{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 \var{preamble} attribute. When the \class{Generator}
-is writing out the plain text representation of a MIME message, and it
-finds the message has a \var{preamble} attribute, it will write this
-text in the area between the headers and the first boundary. See
-\refmodule{email.parser} and \refmodule{email.generator} for details.
-
-Note that if the message object has no preamble, the
-\var{preamble} attribute will be \code{None}.
-\end{datadesc}
-
-\begin{datadesc}{epilogue}
-The \var{epilogue} attribute acts the same way as the \var{preamble}
-attribute, except that it contains text that appears between the last
-boundary and the end of the message.
-
-\versionchanged[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]{2.5}
-\end{datadesc}
-
-\begin{datadesc}{defects}
-The \var{defects} attribute contains a list of all the problems found when
-parsing this message. See \refmodule{email.errors} for a detailed description
-of the possible parsing defects.
-
-\versionadded{2.4}
-\end{datadesc}
diff --git a/Doc/lib/emailmimebase.tex b/Doc/lib/emailmimebase.tex
deleted file mode 100644
index 4735be3..0000000
--- a/Doc/lib/emailmimebase.tex
+++ /dev/null
@@ -1,186 +0,0 @@
-\declaremodule{standard}{email.mime}
-\declaremodule{standard}{email.mime.base}
-\declaremodule{standard}{email.mime.nonmultipart}
-\declaremodule{standard}{email.mime.multipart}
-\declaremodule{standard}{email.mime.audio}
-\declaremodule{standard}{email.mime.image}
-\declaremodule{standard}{email.mime.message}
-\declaremodule{standard}{email.mime.text}
-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 \module{email} package provides some convenient
-subclasses to make things easier.
-
-Here are the classes:
-
-\begin{classdesc}{MIMEBase}{_maintype, _subtype, **_params}
-Module: \module{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.
-
-\var{_maintype} is the \mailheader{Content-Type} major type
-(e.g. \mimetype{text} or \mimetype{image}), and \var{_subtype} is the
-\mailheader{Content-Type} minor type
-(e.g. \mimetype{plain} or \mimetype{gif}). \var{_params} is a parameter
-key/value dictionary and is passed directly to
-\method{Message.add_header()}.
-
-The \class{MIMEBase} class always adds a \mailheader{Content-Type} header
-(based on \var{_maintype}, \var{_subtype}, and \var{_params}), and a
-\mailheader{MIME-Version} header (always set to \code{1.0}).
-\end{classdesc}
-
-\begin{classdesc}{MIMENonMultipart}{}
-Module: \module{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 \method{attach()} method,
-which only makes sense for \mimetype{multipart} messages. If
-\method{attach()} is called, a \exception{MultipartConversionError}
-exception is raised.
-
-\versionadded{2.2.2}
-\end{classdesc}
-
-\begin{classdesc}{MIMEMultipart}{\optional{subtype\optional{,
- boundary\optional{, _subparts\optional{, _params}}}}}
-Module: \module{email.mime.multipart}
-
-A subclass of \class{MIMEBase}, this is an intermediate base class for
-MIME messages that are \mimetype{multipart}. Optional \var{_subtype}
-defaults to \mimetype{mixed}, but can be used to specify the subtype
-of the message. A \mailheader{Content-Type} header of
-\mimetype{multipart/}\var{_subtype} will be added to the message
-object. A \mailheader{MIME-Version} header will also be added.
-
-Optional \var{boundary} is the multipart boundary string. When
-\code{None} (the default), the boundary is calculated when needed.
-
-\var{_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
-\method{Message.attach()} method.
-
-Additional parameters for the \mailheader{Content-Type} header are
-taken from the keyword arguments, or passed into the \var{_params}
-argument, which is a keyword dictionary.
-
-\versionadded{2.2.2}
-\end{classdesc}
-
-\begin{classdesc}{MIMEApplication}{_data\optional{, _subtype\optional{,
- _encoder\optional{, **_params}}}}
-Module: \module{email.mime.application}
-
-A subclass of \class{MIMENonMultipart}, the \class{MIMEApplication} class is
-used to represent MIME message objects of major type \mimetype{application}.
-\var{_data} is a string containing the raw byte data. Optional \var{_subtype}
-specifies the MIME subtype and defaults to \mimetype{octet-stream}.
-
-Optional \var{_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 \method{get_payload()} and \method{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
-\refmodule{email.encoders} module for a list of the built-in encoders.
-
-\var{_params} are passed straight through to the base class constructor.
-\versionadded{2.5}
-\end{classdesc}
-
-\begin{classdesc}{MIMEAudio}{_audiodata\optional{, _subtype\optional{,
- _encoder\optional{, **_params}}}}
-Module: \module{email.mime.audio}
-
-A subclass of \class{MIMENonMultipart}, the \class{MIMEAudio} class
-is used to create MIME message objects of major type \mimetype{audio}.
-\var{_audiodata} is a string containing the raw audio data. If this
-data can be decoded by the standard Python module \refmodule{sndhdr},
-then the subtype will be automatically included in the
-\mailheader{Content-Type} header. Otherwise you can explicitly specify the
-audio subtype via the \var{_subtype} parameter. If the minor type could
-not be guessed and \var{_subtype} was not given, then \exception{TypeError}
-is raised.
-
-Optional \var{_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 \method{get_payload()} and \method{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
-\refmodule{email.encoders} module for a list of the built-in encoders.
-
-\var{_params} are passed straight through to the base class constructor.
-\end{classdesc}
-
-\begin{classdesc}{MIMEImage}{_imagedata\optional{, _subtype\optional{,
- _encoder\optional{, **_params}}}}
-Module: \module{email.mime.image}
-
-A subclass of \class{MIMENonMultipart}, the \class{MIMEImage} class is
-used to create MIME message objects of major type \mimetype{image}.
-\var{_imagedata} is a string containing the raw image data. If this
-data can be decoded by the standard Python module \refmodule{imghdr},
-then the subtype will be automatically included in the
-\mailheader{Content-Type} header. Otherwise you can explicitly specify the
-image subtype via the \var{_subtype} parameter. If the minor type could
-not be guessed and \var{_subtype} was not given, then \exception{TypeError}
-is raised.
-
-Optional \var{_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 \method{get_payload()} and \method{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
-\refmodule{email.encoders} module for a list of the built-in encoders.
-
-\var{_params} are passed straight through to the \class{MIMEBase}
-constructor.
-\end{classdesc}
-
-\begin{classdesc}{MIMEMessage}{_msg\optional{, _subtype}}
-Module: \module{email.mime.message}
-
-A subclass of \class{MIMENonMultipart}, the \class{MIMEMessage} class
-is used to create MIME objects of main type \mimetype{message}.
-\var{_msg} is used as the payload, and must be an instance of class
-\class{Message} (or a subclass thereof), otherwise a
-\exception{TypeError} is raised.
-
-Optional \var{_subtype} sets the subtype of the message; it defaults
-to \mimetype{rfc822}.
-\end{classdesc}
-
-\begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{, _charset}}}
-Module: \module{email.mime.text}
-
-A subclass of \class{MIMENonMultipart}, the \class{MIMEText} class is
-used to create MIME objects of major type \mimetype{text}.
-\var{_text} is the string for the payload. \var{_subtype} is the
-minor type and defaults to \mimetype{plain}. \var{_charset} is the
-character set of the text and is passed as a parameter to the
-\class{MIMENonMultipart} constructor; it defaults to \code{us-ascii}. No
-guessing or encoding is performed on the text data.
-
-\versionchanged[The previously deprecated \var{_encoding} argument has
-been removed. Encoding happens implicitly based on the \var{_charset}
-argument]{2.4}
-\end{classdesc}
diff --git a/Doc/lib/emailparser.tex b/Doc/lib/emailparser.tex
deleted file mode 100644
index 609fa40..0000000
--- a/Doc/lib/emailparser.tex
+++ /dev/null
@@ -1,208 +0,0 @@
-\declaremodule{standard}{email.parser}
-\modulesynopsis{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 \method{attach()} and
-\method{set_payload()} calls, or they can be created by parsing a flat text
-representation of the email message.
-
-The \module{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 \code{True} from its
-\method{is_multipart()} method, and the subparts can be accessed via
-the \method{get_payload()} and \method{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\footnote{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.}.
-
-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 \module{email} package's bundled
-parser and the \class{Message} class, so your custom parser can create
-message object trees any way it finds necessary.
-
-\subsubsection{FeedParser API}
-
-\versionadded{2.4}
-
-The \class{FeedParser}, imported from the \module{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 \var{defects}
-attribute with a list of any problems it found in a message. See the
-\refmodule{email.errors} module for the list of defects that it can find.
-
-Here is the API for the \class{FeedParser}:
-
-\begin{classdesc}{FeedParser}{\optional{_factory}}
-Create a \class{FeedParser} instance. Optional \var{_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.
-\end{classdesc}
-
-\begin{methoddesc}[FeedParser]{feed}{data}
-Feed the \class{FeedParser} some more data. \var{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).
-\end{methoddesc}
-
-\begin{methoddesc}[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}.
-\end{methoddesc}
-
-\subsubsection{Parser class API}
-
-The \class{Parser} class, imported from the \module{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
-\module{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.
-
-\begin{classdesc}{Parser}{\optional{_class}}
-The constructor for the \class{Parser} class takes an optional
-argument \var{_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
-\refmodule{email.message}). The factory will be called without
-arguments.
-
-The optional \var{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}, \emph{all} parsing is effectively
-non-strict. You should simply stop passing a \var{strict} flag to the
-\class{Parser} constructor.}
-
-\versionchanged[The \var{strict} flag was added]{2.2.2}
-\versionchanged[The \var{strict} flag was deprecated]{2.4}
-\end{classdesc}
-
-The other public \class{Parser} methods are:
-
-\begin{methoddesc}[Parser]{parse}{fp\optional{, headersonly}}
-Read all the data from the file-like object \var{fp}, parse the
-resulting text, and return the root message object. \var{fp} must
-support both the \method{readline()} and the \method{read()} methods
-on file-like objects.
-
-The text contained in \var{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 \var{headersonly} is as with the \method{parse()} method.
-
-\versionchanged[The \var{headersonly} flag was added]{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Parser]{parsestr}{text\optional{, headersonly}}
-Similar to the \method{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 \var{text} in a \class{StringIO}
-instance first and calling \method{parse()}.
-
-Optional \var{headersonly} is a flag specifying whether to stop
-parsing after reading the headers or not. The default is \code{False},
-meaning it parses the entire contents of the file.
-
-\versionchanged[The \var{headersonly} flag was added]{2.2.2}
-\end{methoddesc}
-
-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 \module{email}
-package namespace.
-
-\begin{funcdesc}{message_from_string}{s\optional{, _class\optional{, strict}}}
-Return a message object structure from a string. This is exactly
-equivalent to \code{Parser().parsestr(s)}. Optional \var{_class} and
-\var{strict} are interpreted as with the \class{Parser} class constructor.
-
-\versionchanged[The \var{strict} flag was added]{2.2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{message_from_file}{fp\optional{, _class\optional{, strict}}}
-Return a message object structure tree from an open file object. This
-is exactly equivalent to \code{Parser().parse(fp)}. Optional
-\var{_class} and \var{strict} are interpreted as with the
-\class{Parser} class constructor.
-
-\versionchanged[The \var{strict} flag was added]{2.2.2}
-\end{funcdesc}
-
-Here's an example of how you might use this at an interactive Python
-prompt:
-
-\begin{verbatim}
->>> import email
->>> msg = email.message_from_string(myString)
-\end{verbatim}
-
-\subsubsection{Additional notes}
-
-Here are some notes on the parsing semantics:
-
-\begin{itemize}
-\item Most non-\mimetype{multipart} type messages are parsed as a single
- message object with a string payload. These objects will return
- \code{False} for \method{is_multipart()}. Their
- \method{get_payload()} method will return a string object.
-
-\item 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
- \code{True} for \method{is_multipart()} and their
- \method{get_payload()} method will return the list of
- \class{Message} subparts.
-
-\item 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
- \method{is_multipart()} method will return \code{True}. The
- single element in the list payload will be a sub-message object.
-
-\item 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
- \method{is_multipart()} method may return \code{False}. If such
- messages were parsed with the \class{FeedParser}, they will have an
- instance of the \class{MultipartInvariantViolationDefect} class in their
- \var{defects} attribute list. See \refmodule{email.errors} for
- details.
-\end{itemize}
diff --git a/Doc/lib/emailutil.tex b/Doc/lib/emailutil.tex
deleted file mode 100644
index f9fe2d4..0000000
--- a/Doc/lib/emailutil.tex
+++ /dev/null
@@ -1,157 +0,0 @@
-\declaremodule{standard}{email.utils}
-\modulesynopsis{Miscellaneous email package utilities.}
-
-There are several useful utilities provided in the \module{email.utils}
-module:
-
-\begin{funcdesc}{quote}{str}
-Return a new string with backslashes in \var{str} replaced by two
-backslashes, and double quotes replaced by backslash-double quote.
-\end{funcdesc}
-
-\begin{funcdesc}{unquote}{str}
-Return a new string which is an \emph{unquoted} version of \var{str}.
-If \var{str} ends and begins with double quotes, they are stripped
-off. Likewise if \var{str} ends and begins with angle brackets, they
-are stripped off.
-\end{funcdesc}
-
-\begin{funcdesc}{parseaddr}{address}
-Parse address -- which should be the value of some address-containing
-field such as \mailheader{To} or \mailheader{Cc} -- into its constituent
-\emph{realname} and \emph{email address} parts. Returns a tuple of that
-information, unless the parse fails, in which case a 2-tuple of
-\code{('', '')} is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{formataddr}{pair}
-The inverse of \method{parseaddr()}, this takes a 2-tuple of the form
-\code{(realname, email_address)} and returns the string value suitable
-for a \mailheader{To} or \mailheader{Cc} header. If the first element of
-\var{pair} is false, then the second element is returned unmodified.
-\end{funcdesc}
-
-\begin{funcdesc}{getaddresses}{fieldvalues}
-This method returns a list of 2-tuples of the form returned by
-\code{parseaddr()}. \var{fieldvalues} is a sequence of header field
-values as might be returned by \method{Message.get_all()}. Here's a
-simple example that gets all the recipients of a message:
-
-\begin{verbatim}
-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)
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{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
-\function{parsedate()} tries to guess correctly in such cases.
-\var{date} is a string containing an \rfc{2822} date, such as
-\code{"Mon, 20 Nov 1995 19:12:08 -0500"}. If it succeeds in parsing
-the date, \function{parsedate()} returns a 9-tuple that can be passed
-directly to \function{time.mktime()}; otherwise \code{None} will be
-returned. Note that indexes 6, 7, and 8 of the result tuple are not
-usable.
-\end{funcdesc}
-
-\begin{funcdesc}{parsedate_tz}{date}
-Performs the same function as \function{parsedate()}, but returns
-either \code{None} or a 10-tuple; the first 9 elements make up a tuple
-that can be passed directly to \function{time.mktime()}, and the tenth
-is the offset of the date's timezone from UTC (which is the official
-term for Greenwich Mean Time)\footnote{Note that the sign of the timezone
-offset is the opposite of the sign of the \code{time.timezone}
-variable for the same timezone; the latter variable follows the
-\POSIX{} standard while this module follows \rfc{2822}.}. If the input
-string has no timezone, the last element of the tuple returned is
-\code{None}. Note that indexes 6, 7, and 8 of the result tuple are not
-usable.
-\end{funcdesc}
-
-\begin{funcdesc}{mktime_tz}{tuple}
-Turn a 10-tuple as returned by \function{parsedate_tz()} into a UTC
-timestamp. It the timezone item in the tuple is \code{None}, assume
-local time. Minor deficiency: \function{mktime_tz()} interprets the
-first 8 elements of \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{formatdate}{\optional{timeval\optional{, localtime}\optional{, usegmt}}}
-Returns a date string as per \rfc{2822}, e.g.:
-
-\begin{verbatim}
-Fri, 09 Nov 2001 01:08:47 -0000
-\end{verbatim}
-
-Optional \var{timeval} if given is a floating point time value as
-accepted by \function{time.gmtime()} and \function{time.localtime()},
-otherwise the current time is used.
-
-Optional \var{localtime} is a flag that when \code{True}, interprets
-\var{timeval}, and returns a date relative to the local timezone
-instead of UTC, properly taking daylight savings time into account.
-The default is \code{False} meaning UTC is used.
-
-Optional \var{usegmt} is a flag that when \code{True}, outputs a
-date string with the timezone as an ascii string \code{GMT}, rather
-than a numeric \code{-0000}. This is needed for some protocols (such
-as HTTP). This only applies when \var{localtime} is \code{False}.
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{make_msgid}{\optional{idstring}}
-Returns a string suitable for an \rfc{2822}-compliant
-\mailheader{Message-ID} header. Optional \var{idstring} if given, is
-a string used to strengthen the uniqueness of the message id.
-\end{funcdesc}
-
-\begin{funcdesc}{decode_rfc2231}{s}
-Decode the string \var{s} according to \rfc{2231}.
-\end{funcdesc}
-
-\begin{funcdesc}{encode_rfc2231}{s\optional{, charset\optional{, language}}}
-Encode the string \var{s} according to \rfc{2231}. Optional
-\var{charset} and \var{language}, if given is the character set name
-and language name to use. If neither is given, \var{s} is returned
-as-is. If \var{charset} is given but \var{language} is not, the
-string is encoded using the empty string for \var{language}.
-\end{funcdesc}
-
-\begin{funcdesc}{collapse_rfc2231_value}{value\optional{, errors\optional{,
- fallback_charset}}}
-When a header parameter is encoded in \rfc{2231} format,
-\method{Message.get_param()} may return a 3-tuple containing the character
-set, language, and value. \function{collapse_rfc2231_value()} turns this into
-a unicode string. Optional \var{errors} is passed to the \var{errors}
-argument of the built-in \function{unicode()} function; it defaults to
-\code{replace}. Optional \var{fallback_charset} specifies the character set
-to use if the one in the \rfc{2231} header is not known by Python; it defaults
-to \code{us-ascii}.
-
-For convenience, if the \var{value} passed to
-\function{collapse_rfc2231_value()} is not a tuple, it should be a string and
-it is returned unquoted.
-\end{funcdesc}
-
-\begin{funcdesc}{decode_params}{params}
-Decode parameters list according to \rfc{2231}. \var{params} is a
-sequence of 2-tuples containing elements of the form
-\code{(content-type, string-value)}.
-\end{funcdesc}
-
-\versionchanged[The \function{dump_address_pair()} function has been removed;
-use \function{formataddr()} instead]{2.4}
-
-\versionchanged[The \function{decode()} function has been removed; use the
-\method{Header.decode_header()} method instead]{2.4}
-
-\versionchanged[The \function{encode()} function has been removed; use the
-\method{Header.encode()} method instead]{2.4}
diff --git a/Doc/lib/fileformats.tex b/Doc/lib/fileformats.tex
deleted file mode 100644
index 9f9c116..0000000
--- a/Doc/lib/fileformats.tex
+++ /dev/null
@@ -1,7 +0,0 @@
-\chapter{File Formats}
-\label{fileformats}
-
-The modules described in this chapter parse various miscellaneous file
-formats that aren't markup languages or are related to e-mail.
-
-\localmoduletable
diff --git a/Doc/lib/filesys.tex b/Doc/lib/filesys.tex
deleted file mode 100644
index 0c682c8..0000000
--- a/Doc/lib/filesys.tex
+++ /dev/null
@@ -1,18 +0,0 @@
-\chapter{File and Directory Access}
-\label{filesys}
-
-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:
-
-\localmoduletable
-
-% XXX can this be included in the seealso environment? --amk
-Also see section \ref{bltin-file-objects} for a description
-of Python's built-in file objects.
-
-\begin{seealso}
- \seemodule{os}{Operating system interfaces, including functions to
- work with files at a lower level than the built-in file object.}
-\end{seealso}
diff --git a/Doc/lib/frameworks.tex b/Doc/lib/frameworks.tex
deleted file mode 100644
index ffe300e..0000000
--- a/Doc/lib/frameworks.tex
+++ /dev/null
@@ -1,10 +0,0 @@
-\chapter{Program Frameworks}
-\label{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:
-
-\localmoduletable
diff --git a/Doc/lib/i18n.tex b/Doc/lib/i18n.tex
deleted file mode 100644
index 699a60c..0000000
--- a/Doc/lib/i18n.tex
+++ /dev/null
@@ -1,11 +0,0 @@
-\chapter{Internationalization}
-\label{i18n}
-
-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:
-
-\localmoduletable
diff --git a/Doc/lib/internet.tex b/Doc/lib/internet.tex
deleted file mode 100644
index 72ac4b3..0000000
--- a/Doc/lib/internet.tex
+++ /dev/null
@@ -1,13 +0,0 @@
-\chapter{Internet Protocols and Support \label{internet}}
-
-\index{WWW}
-\index{Internet}
-\index{World Wide Web}
-
-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 \refmodule{socket}\refbimodindex{socket}, which is currently
-supported on most popular platforms. Here is an overview:
-
-\localmoduletable
diff --git a/Doc/lib/ipc.tex b/Doc/lib/ipc.tex
deleted file mode 100644
index cd95056..0000000
--- a/Doc/lib/ipc.tex
+++ /dev/null
@@ -1,14 +0,0 @@
-\chapter{Interprocess Communication and Networking}
-\label{ipc}
-
-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. \module{signal} and \module{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:
-
-\localmoduletable
diff --git a/Doc/lib/language.tex b/Doc/lib/language.tex
deleted file mode 100644
index 5cdb113..0000000
--- a/Doc/lib/language.tex
+++ /dev/null
@@ -1,10 +0,0 @@
-\chapter{Python Language Services
- \label{language}}
-
-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:
-
-\localmoduletable
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
deleted file mode 100644
index 445ac55..0000000
--- a/Doc/lib/lib.tex
+++ /dev/null
@@ -1,452 +0,0 @@
-\documentclass{manual}
-
-% NOTE: this file controls which chapters/sections of the library
-% manual are actually printed. It is easy to customize your manual
-% by commenting out sections that you're not interested in.
-
-\title{Python Library Reference}
-
-\input{boilerplate}
-
-\makeindex % tell \index to actually write the
- % .idx file
-\makemodindex % ... and the module index as well.
-
-
-\begin{document}
-
-\maketitle
-
-\ifhtml
-\chapter*{Front Matter\label{front}}
-\fi
-
-\input{copyright}
-
-\begin{abstract}
-
-\noindent
-Python is an extensible, interpreted, object-oriented programming
-language. It supports a wide range of applications, from simple text
-processing scripts to interactive Web browsers.
-
-While the \citetitle[../ref/ref.html]{Python Reference Manual}
-describes the exact syntax and semantics of the language, it does not
-describe the standard library that is distributed with the language,
-and which greatly enhances its immediate usability. This 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.
-
-This library reference manual documents Python's standard library, as
-well as many optional library modules (which may or may not be
-available, depending on whether the underlying platform supports them
-and on the configuration choices made at compile time). It also
-documents the standard types of the language and its built-in
-functions and exceptions, many of which are not or incompletely
-documented in the Reference Manual.
-
-This manual assumes basic knowledge about the Python language. For an
-informal introduction to Python, see the
-\citetitle[../tut/tut.html]{Python Tutorial}; the
-\citetitle[../ref/ref.html]{Python Reference Manual} remains the
-highest authority on syntactic and semantic questions. Finally, the
-manual entitled \citetitle[../ext/ext.html]{Extending and Embedding
-the Python Interpreter} describes how to add new extensions to Python
-and how to embed it in other applications.
-
-\end{abstract}
-
-\tableofcontents
-
- % Chapter title:
-
-\input{libintro} % Introduction
-
-
-% =============
-% BUILT-INs
-% =============
-
-\input{libobjs} % Built-in Exceptions and Functions
-\input{libfuncs}
-\input{libexcs}
-\input{libconsts}
-
-\input{libstdtypes} % Built-in types
-
-
-% =============
-% BASIC/GENERAL-PURPOSE OBJECTS
-% =============
-
-% Strings
-\input{libstrings} % String Services
-\input{libstring}
-\input{libre}
-\input{libstruct} % XXX also/better in File Formats?
-\input{libdifflib}
-\input{libstringio}
-\input{libtextwrap}
-\input{libcodecs}
-\input{libunicodedata}
-\input{libstringprep}
-\input{libfpformat}
-
-
-\input{datatypes} % Data types and structures
-\input{libdatetime}
-\input{libcalendar}
-\input{libcollections}
-\input{libheapq}
-\input{libbisect}
-\input{libarray}
-\input{libsched}
-\input{libmutex}
-\input{libqueue}
-\input{libweakref}
-\input{libuserdict}
-
-% General object services
-% XXX intro
-\input{libtypes}
-\input{libnew}
-\input{libcopy}
-\input{libpprint}
-\input{librepr}
-
-
-\input{numeric} % Numeric/Mathematical modules
-\input{libmath}
-\input{libcmath}
-\input{libdecimal}
-\input{librandom}
-
-% Functions, Functional, Generators and Iterators
-% XXX intro functional
-\input{libitertools}
-\input{libfunctools}
-\input{liboperator} % from runtime - better with itertools and functools
-
-
-% =============
-% DATA FORMATS
-% =============
-
-% Big move - include all the markup and internet formats here
-
-% MIME & email stuff
-\input{netdata} % Internet Data Handling
-\input{email}
-\input{libmailcap}
-\input{libmailbox}
-\input{libmhlib}
-\input{libmimetools}
-\input{libmimetypes}
-\input{libmultifile}
-\input{librfc822}
-
-% encoding stuff
-\input{libbase64}
-\input{libbinhex}
-\input{libbinascii}
-\input{libquopri}
-\input{libuu}
-
-\input{markup} % Structured Markup Processing Tools
-\input{libhtmlparser}
-\input{libsgmllib}
-\input{libhtmllib}
-\input{libpyexpat}
-\input{xmldom}
-\input{xmldomminidom}
-\input{xmldompulldom}
-\input{xmlsax}
-\input{xmlsaxhandler}
-\input{xmlsaxutils}
-\input{xmlsaxreader}
-\input{libetree}
-
-\input{fileformats} % Miscellaneous file formats
-\input{libcsv}
-\input{libcfgparser}
-\input{librobotparser}
-\input{libnetrc}
-\input{libxdrlib}
-
-\input{libcrypto} % Cryptographic Services
-\input{libhashlib}
-\input{libhmac}
-
-% =============
-% FILE & DATABASE STORAGE
-% =============
-
-\input{filesys} % File/directory support
-\input{libposixpath} % os.path
-\input{libfileinput}
-\input{libstat}
-\input{libstatvfs}
-\input{libfilecmp}
-\input{libtempfile}
-\input{libglob}
-\input{libfnmatch}
-\input{liblinecache}
-\input{libshutil}
-\input{libdircache}
-
-
-\input{archiving} % Data compression and archiving
-\input{libzlib}
-\input{libgzip}
-\input{libbz2}
-\input{libzipfile}
-\input{libtarfile}
-
-
-\input{persistence} % Persistent storage
-\input{libpickle}
-\input{libcopyreg} % really copy_reg % from runtime...
-\input{libshelve}
-\input{libmarshal}
-\input{libanydbm}
-\input{libwhichdb}
-\input{libdbm}
-\input{libgdbm}
-\input{libdbhash}
-\input{libbsddb}
-\input{libdumbdbm}
-\input{libsqlite3}
-
-
-% =============
-% OS
-% =============
-
-
-\input{liballos} % Generic Operating System Services
-\input{libos}
-\input{libtime}
-\input{liboptparse}
-\input{libgetopt}
-\input{liblogging}
-\input{libgetpass}
-\input{libcurses}
-\input{libascii} % curses.ascii
-\input{libcursespanel}
-\input{libplatform}
-\input{liberrno}
-\input{libctypes}
-
-\input{libsomeos} % Optional Operating System Services
-\input{libselect}
-\input{libthread}
-\input{libthreading}
-\input{libdummythread}
-\input{libdummythreading}
-\input{libmmap}
-\input{libreadline}
-\input{librlcompleter}
-
-\input{libunix} % UNIX Specific Services
-\input{libposix}
-\input{libpwd}
-\input{libspwd}
-\input{libgrp}
-\input{libcrypt}
-\input{libdl}
-\input{libtermios}
-\input{libtty}
-\input{libpty}
-\input{libfcntl}
-\input{libpipes}
-\input{libresource}
-\input{libnis}
-\input{libsyslog}
-\input{libcommands}
-
-
-% =============
-% NETWORK & COMMUNICATIONS
-% =============
-
-\input{ipc} % Interprocess communication/networking
-\input{libsubprocess}
-\input{libsocket}
-\input{libsignal}
-\input{libasyncore}
-\input{libasynchat}
-
-\input{internet} % Internet Protocols
-\input{libwebbrowser}
-\input{libcgi}
-\input{libcgitb}
-\input{libwsgiref}
-\input{liburllib}
-\input{liburllib2}
-\input{libhttplib}
-\input{libftplib}
-\input{libpoplib}
-\input{libimaplib}
-\input{libnntplib}
-\input{libsmtplib}
-\input{libsmtpd}
-\input{libtelnetlib}
-\input{libuuid}
-\input{liburlparse}
-\input{libsocksvr}
-\input{libbasehttp}
-\input{libsimplehttp}
-\input{libcgihttp}
-\input{libcookielib}
-\input{libcookie}
-\input{libxmlrpclib}
-\input{libsimplexmlrpc}
-\input{libdocxmlrpc}
-
-% =============
-% MULTIMEDIA
-% =============
-
-\input{libmm} % Multimedia Services
-\input{libaudioop}
-\input{libaifc}
-\input{libsunau}
-\input{libwave}
-\input{libchunk}
-\input{libcolorsys}
-\input{libimghdr}
-\input{libsndhdr}
-\input{libossaudiodev}
-
-% Tkinter is a chapter in its own right.
-\input{tkinter}
-
-% % Internationalization
-\input{i18n}
-\input{libgettext}
-\input{liblocale}
-
-% =============
-% PROGRAM FRAMEWORKS
-% =============
-\input{frameworks}
-\input{libcmd}
-\input{libshlex}
-
-
-% =============
-% DEVELOPMENT TOOLS
-% =============
-% % Software development support
-\input{development}
-\input{libpydoc}
-\input{libdoctest}
-\input{libunittest}
-\input{libtest}
-
-\input{libpdb} % The Python Debugger
-
-\input{libprofile} % The Python Profiler
-\input{libhotshot} % unmaintained C profiler
-\input{libtimeit}
-\input{libtrace}
-
-% =============
-% PYTHON ENGINE
-% =============
-
-% Runtime services
-\input{libpython} % Python Runtime Services
-\input{libsys}
-\input{libbltin} % really __builtin__
-\input{libmain} % really __main__
-\input{libwarnings}
-\input{libcontextlib}
-\input{libatexit}
-\input{libtraceback}
-\input{libfuture} % really __future__
-\input{libgc}
-\input{libinspect}
-\input{libsite}
-\input{libuser}
-\input{libfpectl}
-
-
-\input{custominterp} % Custom interpreter
-\input{libcode}
-\input{libcodeop}
-
-
-\input{modules} % Importing Modules
-\input{libimp}
-\input{libzipimport}
-\input{libpkgutil}
-\input{libmodulefinder}
-\input{librunpy}
-
-
-% =============
-% PYTHON LANGUAGE & COMPILER
-% =============
-
-\input{language} % Python Language Services
-\input{libparser}
-\input{libsymbol}
-\input{libtoken}
-\input{libkeyword}
-\input{libtokenize}
-\input{libtabnanny}
-\input{libpyclbr}
-\input{libpycompile} % really py_compile
-\input{libcompileall}
-\input{libdis}
-\input{libpickletools}
-\input{distutils}
-
-\input{libast}
-
-\input{libmisc} % Miscellaneous Services
-\input{libformatter}
-
-% =============
-% OTHER PLATFORM-SPECIFIC STUFF
-% =============
-
-\input{windows} % MS Windows ONLY
-\input{libmsilib}
-\input{libmsvcrt}
-\input{libwinreg}
-\input{libwinsound}
-
-\appendix
-\input{libundoc}
-
-%\chapter{Obsolete Modules}
-
-\chapter{Reporting Bugs}
-\input{reportingbugs}
-
-\chapter{History and License}
-\input{license}
-
-%
-% The ugly "%begin{latexonly}" pseudo-environments are really just to
-% keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
-% not really valuable.
-%
-
-%begin{latexonly}
-\renewcommand{\indexname}{Module Index}
-%end{latexonly}
-\input{modlib.ind} % Module Index
-
-%begin{latexonly}
-\renewcommand{\indexname}{Index}
-%end{latexonly}
-\input{lib.ind} % Index
-
-\end{document}
diff --git a/Doc/lib/libaifc.tex b/Doc/lib/libaifc.tex
deleted file mode 100644
index 65abe84..0000000
--- a/Doc/lib/libaifc.tex
+++ /dev/null
@@ -1,202 +0,0 @@
-\section{\module{aifc} ---
- Read and write AIFF and AIFC files}
-
-\declaremodule{standard}{aifc}
-\modulesynopsis{Read and write audio files in AIFF or AIFC format.}
-
-
-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.
-\index{Audio Interchange File Format}
-\index{AIFF}
-\index{AIFF-C}
-
-\strong{Caveat:} Some operations may only work under IRIX; these will
-raise \exception{ImportError} when attempting to import the
-\module{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 \var{nchannels}*\var{samplesize} bytes, and a
-second's worth of audio consists of
-\var{nchannels}*\var{samplesize}*\var{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 \module{aifc} defines the following function:
-
-\begin{funcdesc}{open}{file\optional{, mode}}
-Open an AIFF or AIFF-C file and return an object instance with
-methods that are described below. The argument \var{file} is either a
-string naming a file or a file object. \var{mode} must be \code{'r'}
-or \code{'rb'} when the file must be opened for reading, or \code{'w'}
-or \code{'wb'} when the file must be opened for writing. If omitted,
-\code{\var{file}.mode} is used if it exists, otherwise \code{'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 \method{writeframesraw()} and \method{setnframes()}.
-\end{funcdesc}
-
-Objects returned by \function{open()} when a file is opened for
-reading have the following methods:
-
-\begin{methoddesc}[aifc]{getnchannels}{}
-Return the number of audio channels (1 for mono, 2 for stereo).
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getsampwidth}{}
-Return the size in bytes of individual samples.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getframerate}{}
-Return the sampling rate (number of audio frames per second).
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getnframes}{}
-Return the number of audio frames in the file.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getcomptype}{}
-Return a four-character string describing the type of compression used
-in the audio file. For AIFF files, the returned value is
-\code{'NONE'}.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getcompname}{}
-Return a human-readable description of the type of compression used in
-the audio file. For AIFF files, the returned value is \code{'not
-compressed'}.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getparams}{}
-Return a tuple consisting of all of the above values in the above
-order.
-\end{methoddesc}
-
-\begin{methoddesc}[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).
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getmark}{id}
-Return the tuple as described in \method{getmarkers()} for the mark
-with the given \var{id}.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{readframes}{nframes}
-Read and return the next \var{nframes} frames from the audio file. The
-returned data is a string containing for each frame the uncompressed
-samples of all channels.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{rewind}{}
-Rewind the read pointer. The next \method{readframes()} will start from
-the beginning.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{setpos}{pos}
-Seek to the specified frame number.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{tell}{}
-Return the current frame number.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{close}{}
-Close the AIFF file. After calling this method, the object can no
-longer be used.
-\end{methoddesc}
-
-Objects returned by \function{open()} when a file is opened for
-writing have all the above methods, except for \method{readframes()} and
-\method{setpos()}. In addition the following methods exist. The
-\method{get*()} methods can only be called after the corresponding
-\method{set*()} methods have been called. Before the first
-\method{writeframes()} or \method{writeframesraw()}, all parameters
-except for the number of frames must be filled in.
-
-\begin{methoddesc}[aifc]{aiff}{}
-Create an AIFF file. The default is that an AIFF-C file is created,
-unless the name of the file ends in \code{'.aiff'} in which case the
-default is an AIFF file.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \code{'.aiff'} in which case the
-default is an AIFF file.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{setnchannels}{nchannels}
-Specify the number of channels in the audio file.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{setsampwidth}{width}
-Specify the size in bytes of audio samples.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{setframerate}{rate}
-Specify the sampling frequency in frames per second.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{setcomptype}{type, name}
-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.
-\index{u-LAW}
-\index{A-LAW}
-\index{G.722}
-\end{methoddesc}
-
-\begin{methoddesc}[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 \method{getparams()} call as argument to
-\method{setparams()}.
-\end{methoddesc}
-
-\begin{methoddesc}[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
-\method{close()}.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{tell}{}
-Return the current write position in the output file. Useful in
-combination with \method{setmark()}.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{writeframes}{data}
-Write data to the output file. This method can only be called after
-the audio file parameters have been set.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{writeframesraw}{data}
-Like \method{writeframes()}, except that the header of the audio file
-is not updated.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
diff --git a/Doc/lib/liballos.tex b/Doc/lib/liballos.tex
deleted file mode 100644
index dd046c9..0000000
--- a/Doc/lib/liballos.tex
+++ /dev/null
@@ -1,9 +0,0 @@
-\chapter{Generic Operating System Services \label{allos}}
-
-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:
-
-\localmoduletable
diff --git a/Doc/lib/libanydbm.tex b/Doc/lib/libanydbm.tex
deleted file mode 100644
index badc6ec..0000000
--- a/Doc/lib/libanydbm.tex
+++ /dev/null
@@ -1,85 +0,0 @@
-\section{\module{anydbm} ---
- Generic access to DBM-style databases}
-
-\declaremodule{standard}{anydbm}
-\modulesynopsis{Generic interface to DBM-style database modules.}
-
-
-\module{anydbm} is a generic interface to variants of the DBM
-database --- \refmodule{dbhash}\refstmodindex{dbhash} (requires
-\refmodule{bsddb}\refbimodindex{bsddb}),
-\refmodule{gdbm}\refbimodindex{gdbm}, or
-\refmodule{dbm}\refbimodindex{dbm}. If none of these modules is
-installed, the slow-but-simple implementation in module
-\refmodule{dumbdbm}\refstmodindex{dumbdbm} will be used.
-
-\begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}}
-Open the database file \var{filename} and return a corresponding object.
-
-If the database file already exists, the \refmodule{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 \var{flag} argument can be
-\code{'r'} to open an existing database for reading only,
-\code{'w'} to open an existing database for reading and writing,
-\code{'c'} to create the database if it doesn't exist, or
-\code{'n'}, which will always create a new empty database. If not
-specified, the default value is \code{'r'}.
-
-The optional \var{mode} argument is the \UNIX{} mode of the file, used
-only when the database has to be created. It defaults to octal
-\code{0666} (and will be modified by the prevailing umask).
-\end{funcdesc}
-
-\begin{excdesc}{error}
-A tuple containing the exceptions that can be raised by each of the
-supported modules, with a unique exception \exception{anydbm.error} as
-the first item --- the latter is used when \exception{anydbm.error} is
-raised.
-\end{excdesc}
-
-The object returned by \function{open()} supports most of the same
-functionality as dictionaries; keys and their corresponding values can
-be stored, retrieved, and deleted, and the \method{has_key()} and
-\method{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:
-
-\begin{verbatim}
-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()
-\end{verbatim}
-
-
-\begin{seealso}
- \seemodule{dbhash}{BSD \code{db} database interface.}
- \seemodule{dbm}{Standard \UNIX{} database interface.}
- \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}
- \seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.}
- \seemodule{shelve}{General object persistence built on top of
- the Python \code{dbm} interface.}
- \seemodule{whichdb}{Utility module used to determine the type of an
- existing database.}
-\end{seealso}
diff --git a/Doc/lib/libarray.tex b/Doc/lib/libarray.tex
deleted file mode 100644
index eaf5888..0000000
--- a/Doc/lib/libarray.tex
+++ /dev/null
@@ -1,241 +0,0 @@
-\section{\module{array} ---
- Efficient arrays of numeric values}
-
-\declaremodule{builtin}{array}
-\modulesynopsis{Efficient arrays of uniformly typed numeric values.}
-
-
-This module defines an object type which can efficiently represent
-an array of basic values: characters, integers, floating point
-numbers. Arrays\index{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:
-
-\begin{tableiv}{c|l|l|c}{code}{Type code}{C Type}{Python Type}{Minimum size in bytes}
- \lineiv{'c'}{char} {character} {1}
- \lineiv{'b'}{signed char} {int} {1}
- \lineiv{'B'}{unsigned char} {int} {1}
- \lineiv{'u'}{Py_UNICODE} {Unicode character}{2}
- \lineiv{'h'}{signed short} {int} {2}
- \lineiv{'H'}{unsigned short}{int} {2}
- \lineiv{'i'}{signed int} {int} {2}
- \lineiv{'I'}{unsigned int} {long} {2}
- \lineiv{'l'}{signed long} {int} {4}
- \lineiv{'L'}{unsigned long} {long} {4}
- \lineiv{'f'}{float} {float} {4}
- \lineiv{'d'}{double} {float} {8}
-\end{tableiv}
-
-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 \member{itemsize} attribute. The values
-stored for \code{'L'} and \code{'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:
-
-\begin{funcdesc}{array}{typecode\optional{, initializer}}
-Return a new array whose items are restricted by \var{typecode},
-and initialized from the optional \var{initializer} value, which
-must be a list, string, or iterable over elements of the
-appropriate type.
-\versionchanged[Formerly, only lists or strings were accepted]{2.4}
-If given a list or string, the initializer is passed to the
-new array's \method{fromlist()}, \method{fromstring()}, or
-\method{fromunicode()} method (see below) to add initial items to
-the array. Otherwise, the iterable initializer is passed to the
-\method{extend()} method.
-\end{funcdesc}
-
-\begin{datadesc}{ArrayType}
-Obsolete alias for \function{array}.
-\end{datadesc}
-
-
-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, \exception{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:
-
-\begin{memberdesc}[array]{typecode}
-The typecode character used to create the array.
-\end{memberdesc}
-
-\begin{memberdesc}[array]{itemsize}
-The length in bytes of one array item in the internal representation.
-\end{memberdesc}
-
-
-\begin{methoddesc}[array]{append}{x}
-Append a new item with value \var{x} to the end of the array.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{buffer_info}{}
-Return a tuple \code{(\var{address}, \var{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 \code{\var{array}.buffer_info()[1] *
-\var{array}.itemsize}. This is occasionally useful when working with
-low-level (and inherently unsafe) I/O interfaces that require memory
-addresses, such as certain \cfunction{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
-\Cpp{} (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
-the \citetitle[../api/newTypes.html]{Python/C API Reference Manual}.}
-\end{methoddesc}
-
-\begin{methoddesc}[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, \exception{RuntimeError} is raised. It is useful when reading
-data from a file written on a machine with a different byte order.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{count}{x}
-Return the number of occurrences of \var{x} in the array.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{extend}{iterable}
-Append items from \var{iterable} to the end of the array. If
-\var{iterable} is another array, it must have \emph{exactly} the same
-type code; if not, \exception{TypeError} will be raised. If
-\var{iterable} is not an array, it must be iterable and its
-elements must be the right type to be appended to the array.
-\versionchanged[Formerly, the argument could only be another array]{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[array]{fromfile}{f, n}
-Read \var{n} items (as machine values) from the file object \var{f}
-and append them to the end of the array. If less than \var{n} items
-are available, \exception{EOFError} is raised, but the items that were
-available are still inserted into the array. \var{f} must be a real
-built-in file object; something else with a \method{read()} method won't
-do.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{fromlist}{list}
-Append items from the list. This is equivalent to
-\samp{for x in \var{list}:\ a.append(x)}
-except that if there is a type error, the array is unchanged.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \method{fromfile()} method).
-\end{methoddesc}
-
-\begin{methoddesc}[array]{fromunicode}{s}
-Extends this array with data from the given unicode string. The array
-must be a type \code{'u'} array; otherwise a \exception{ValueError}
-is raised. Use \samp{array.fromstring(ustr.decode(enc))} to
-append Unicode data to an array of some other type.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{index}{x}
-Return the smallest \var{i} such that \var{i} is the index of
-the first occurrence of \var{x} in the array.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{insert}{i, x}
-Insert a new item with value \var{x} in the array before position
-\var{i}. Negative values are treated as being relative to the end
-of the array.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{pop}{\optional{i}}
-Removes the item with the index \var{i} from the array and returns
-it. The optional argument defaults to \code{-1}, so that by default
-the last item is removed and returned.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{read}{f, n}
-\deprecated {1.5.1}
- {Use the \method{fromfile()} method.}
-Read \var{n} items (as machine values) from the file object \var{f}
-and append them to the end of the array. If less than \var{n} items
-are available, \exception{EOFError} is raised, but the items that were
-available are still inserted into the array. \var{f} must be a real
-built-in file object; something else with a \method{read()} method won't
-do.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{remove}{x}
-Remove the first occurrence of \var{x} from the array.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{reverse}{}
-Reverse the order of the items in the array.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{tofile}{f}
-Write all items (as machine values) to the file object \var{f}.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{tolist}{}
-Convert the array to an ordinary list with the same items.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \method{tofile()} method.)
-\end{methoddesc}
-
-\begin{methoddesc}[array]{tounicode}{}
-Convert the array to a unicode string. The array must be
-a type \code{'u'} array; otherwise a \exception{ValueError} is raised.
-Use \samp{array.tostring().decode(enc)} to obtain a unicode string
-from an array of some other type.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{write}{f}
-\deprecated {1.5.1}
- {Use the \method{tofile()} method.}
-Write all items (as machine values) to the file object \var{f}.
-\end{methoddesc}
-
-When an array object is printed or converted to a string, it is
-represented as \code{array(\var{typecode}, \var{initializer})}. The
-\var{initializer} is omitted if the array is empty, otherwise it is a
-string if the \var{typecode} is \code{'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 reverse quotes
-(\code{``}), so long as the \function{array()} function has been
-imported using \code{from array import array}. Examples:
-
-\begin{verbatim}
-array('l')
-array('c', 'hello world')
-array('u', u'hello \textbackslash u2641')
-array('l', [1, 2, 3, 4, 5])
-array('d', [1.0, 2.0, 3.14])
-\end{verbatim}
-
-
-\begin{seealso}
- \seemodule{struct}{Packing and unpacking of heterogeneous binary data.}
- \seemodule{xdrlib}{Packing and unpacking of External Data
- Representation (XDR) data as used in some remote
- procedure call systems.}
- \seetitle[http://numpy.sourceforge.net/numdoc/HTML/numdoc.htm]{The
- Numerical Python Manual}{The Numeric Python extension
- (NumPy) defines another array type; see
- \url{http://numpy.sourceforge.net/} for further information
- about Numerical Python. (A PDF version of the NumPy manual
- is available at
- \url{http://numpy.sourceforge.net/numdoc/numdoc.pdf}).}
-\end{seealso}
diff --git a/Doc/lib/libascii.tex b/Doc/lib/libascii.tex
deleted file mode 100644
index 003bd95..0000000
--- a/Doc/lib/libascii.tex
+++ /dev/null
@@ -1,175 +0,0 @@
-\section{\module{curses.ascii} ---
- Utilities for ASCII characters}
-
-\declaremodule{standard}{curses.ascii}
-\modulesynopsis{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 \module{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:
-
-\begin{tableii}{l|l}{constant}{Name}{Meaning}
- \lineii{NUL}{}
- \lineii{SOH}{Start of heading, console interrupt}
- \lineii{STX}{Start of text}
- \lineii{ETX}{End of text}
- \lineii{EOT}{End of transmission}
- \lineii{ENQ}{Enquiry, goes with \constant{ACK} flow control}
- \lineii{ACK}{Acknowledgement}
- \lineii{BEL}{Bell}
- \lineii{BS}{Backspace}
- \lineii{TAB}{Tab}
- \lineii{HT}{Alias for \constant{TAB}: ``Horizontal tab''}
- \lineii{LF}{Line feed}
- \lineii{NL}{Alias for \constant{LF}: ``New line''}
- \lineii{VT}{Vertical tab}
- \lineii{FF}{Form feed}
- \lineii{CR}{Carriage return}
- \lineii{SO}{Shift-out, begin alternate character set}
- \lineii{SI}{Shift-in, resume default character set}
- \lineii{DLE}{Data-link escape}
- \lineii{DC1}{XON, for flow control}
- \lineii{DC2}{Device control 2, block-mode flow control}
- \lineii{DC3}{XOFF, for flow control}
- \lineii{DC4}{Device control 4}
- \lineii{NAK}{Negative acknowledgement}
- \lineii{SYN}{Synchronous idle}
- \lineii{ETB}{End transmission block}
- \lineii{CAN}{Cancel}
- \lineii{EM}{End of medium}
- \lineii{SUB}{Substitute}
- \lineii{ESC}{Escape}
- \lineii{FS}{File separator}
- \lineii{GS}{Group separator}
- \lineii{RS}{Record separator, block-mode terminator}
- \lineii{US}{Unit separator}
- \lineii{SP}{Space}
- \lineii{DEL}{Delete}
-\end{tableii}
-
-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:
-
-
-\begin{funcdesc}{isalnum}{c}
-Checks for an \ASCII{} alphanumeric character; it is equivalent to
-\samp{isalpha(\var{c}) or isdigit(\var{c})}.
-\end{funcdesc}
-
-\begin{funcdesc}{isalpha}{c}
-Checks for an \ASCII{} alphabetic character; it is equivalent to
-\samp{isupper(\var{c}) or islower(\var{c})}.
-\end{funcdesc}
-
-\begin{funcdesc}{isascii}{c}
-Checks for a character value that fits in the 7-bit \ASCII{} set.
-\end{funcdesc}
-
-\begin{funcdesc}{isblank}{c}
-Checks for an \ASCII{} whitespace character.
-\end{funcdesc}
-
-\begin{funcdesc}{iscntrl}{c}
-Checks for an \ASCII{} control character (in the range 0x00 to 0x1f).
-\end{funcdesc}
-
-\begin{funcdesc}{isdigit}{c}
-Checks for an \ASCII{} decimal digit, \character{0} through
-\character{9}. This is equivalent to \samp{\var{c} in string.digits}.
-\end{funcdesc}
-
-\begin{funcdesc}{isgraph}{c}
-Checks for \ASCII{} any printable character except space.
-\end{funcdesc}
-
-\begin{funcdesc}{islower}{c}
-Checks for an \ASCII{} lower-case character.
-\end{funcdesc}
-
-\begin{funcdesc}{isprint}{c}
-Checks for any \ASCII{} printable character including space.
-\end{funcdesc}
-
-\begin{funcdesc}{ispunct}{c}
-Checks for any printable \ASCII{} character which is not a space or an
-alphanumeric character.
-\end{funcdesc}
-
-\begin{funcdesc}{isspace}{c}
-Checks for \ASCII{} white-space characters; space, line feed,
-carriage return, form feed, horizontal tab, vertical tab.
-\end{funcdesc}
-
-\begin{funcdesc}{isupper}{c}
-Checks for an \ASCII{} uppercase letter.
-\end{funcdesc}
-
-\begin{funcdesc}{isxdigit}{c}
-Checks for an \ASCII{} hexadecimal digit. This is equivalent to
-\samp{\var{c} in string.hexdigits}.
-\end{funcdesc}
-
-\begin{funcdesc}{isctrl}{c}
-Checks for an \ASCII{} control character (ordinal values 0 to 31).
-\end{funcdesc}
-
-\begin{funcdesc}{ismeta}{c}
-Checks for a non-\ASCII{} character (ordinal values 0x80 and above).
-\end{funcdesc}
-
-These functions accept either integers or strings; when the argument
-is a string, it is first converted using the built-in function
-\function{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 \refmodule{string} module.
-
-The following two functions take either a single-character string or
-integer byte value; they return a value of the same type.
-
-\begin{funcdesc}{ascii}{c}
-Return the ASCII value corresponding to the low 7 bits of \var{c}.
-\end{funcdesc}
-
-\begin{funcdesc}{ctrl}{c}
-Return the control character corresponding to the given character
-(the character bit value is bitwise-anded with 0x1f).
-\end{funcdesc}
-
-\begin{funcdesc}{alt}{c}
-Return the 8-bit character corresponding to the given ASCII character
-(the character bit value is bitwise-ored with 0x80).
-\end{funcdesc}
-
-The following function takes either a single-character string or
-integer value; it returns a string.
-
-\begin{funcdesc}{unctrl}{c}
-Return a string representation of the \ASCII{} character \var{c}. If
-\var{c} is printable, this string is the character itself. If the
-character is a control character (0x00-0x1f) the string consists of a
-caret (\character{\^}) followed by the corresponding uppercase letter.
-If the character is an \ASCII{} delete (0x7f) the string is
-\code{'\^{}?'}. If the character has its meta bit (0x80) set, the meta
-bit is stripped, the preceding rules applied, and
-\character{!} prepended to the result.
-\end{funcdesc}
-
-\begin{datadesc}{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 \samp{SP} for the space character.
-\end{datadesc}
diff --git a/Doc/lib/libast.tex b/Doc/lib/libast.tex
deleted file mode 100644
index b2956ae..0000000
--- a/Doc/lib/libast.tex
+++ /dev/null
@@ -1,57 +0,0 @@
-% XXX Label can't be _ast?
-% XXX Where should this section/chapter go?
-\chapter{Abstract Syntax Trees\label{ast}}
-
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\versionadded{2.5}
-
-The \code{_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 \code{_ast.PyCF_ONLY_AST}
-as a flag to the \function{compile} builtin function. The result will be a tree
-of objects whose classes all inherit from \code{_ast.AST}.
-
-The actual classes are derived from the \code{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, \code{_ast.stmt} or \code{_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, \code{_ast.BinOp} inherits from \code{_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 \code{_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, \code{_ast.BinOp}
-instances have an attribute \code{left} of type \code{_ast.expr}.
-Instances of \code{_ast.expr} and \code{_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 \code{None}. If the attributes
-can have zero-or-more values (marked with an asterisk), the
-values are represented as Python lists.
-
-\section{Abstract Grammar}
-
-The module defines a string constant \code{__version__} which
-is the decimal subversion revision number of the file shown below.
-
-The abstract grammar is currently defined as follows:
-
-\verbatiminput{../../Parser/Python.asdl}
diff --git a/Doc/lib/libasynchat.tex b/Doc/lib/libasynchat.tex
deleted file mode 100644
index 223bfed7..0000000
--- a/Doc/lib/libasynchat.tex
+++ /dev/null
@@ -1,254 +0,0 @@
-\section{\module{asynchat} ---
- Asynchronous socket command/response handler}
-
-\declaremodule{standard}{asynchat}
-\modulesynopsis{Support for asynchronous command/response protocols.}
-\moduleauthor{Sam Rushing}{rushing@nightmare.com}
-\sectionauthor{Steve Holden}{sholden@holdenweb.com}
-
-This module builds on the \refmodule{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. \refmodule{asynchat} defines the abstract class
-\class{async_chat} that you subclass, providing implementations of the
-\method{collect_incoming_data()} and \method{found_terminator()}
-methods. It uses the same asynchronous loop as \refmodule{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.
-
-\begin{classdesc}{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 \method{collect_incoming_data()} and \method{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
- \cfunction{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 \emph{producers}. A producer need have
- only one method, \method{more()}, which should return data to be transmitted
- on the channel. The producer indicates exhaustion (\emph{i.e.} that it contains
- no more data) by having its \method{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 \method{handle_write()} method does nothing. You use the channel object's
- \method{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 \method{collect_incoming_data()} and
- \method{found_terminator()} must handle the data that the channel receives
- asynchronously. The methods are described below.
-\end{classdesc}
-
-\begin{methoddesc}{close_when_done}{}
- Pushes a \code{None} on to the producer fifo. When this producer is
- popped off the fifo it causes the channel to be closed.
-\end{methoddesc}
-
-\begin{methoddesc}{collect_incoming_data}{data}
- Called with \var{data} holding an arbitrary amount of received data.
- The default method, which must be overridden, raises a \exception{NotImplementedError} exception.
-\end{methoddesc}
-
-\begin{methoddesc}{discard_buffers}{}
- In emergencies this method will discard any data held in the input and/or
- output buffers and the producer fifo.
-\end{methoddesc}
-
-\begin{methoddesc}{found_terminator}{}
- Called when the incoming data stream matches the termination condition
- set by \method{set_terminator}. The default method, which must be overridden,
- raises a \exception{NotImplementedError} exception. The buffered input data should
- be available via an instance attribute.
-\end{methoddesc}
-
-\begin{methoddesc}{get_terminator}{}
- Returns the current terminator for the channel.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_close}{}
- Called when the channel is closed. The default method silently closes
- the channel's socket.
-\end{methoddesc}
-
-\begin{methoddesc}{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 \method{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,
- \method{handle_read} calls the \method{found_terminator()} method after
- calling \method{collect_incoming_data()} with any data preceding the
- terminating condition.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_write}{}
- Called when the application may write data to the channel.
- The default method calls the \method{initiate_send()} method, which in turn
- will call \method{refill_buffer()} to collect data from the producer
- fifo associated with the channel.
-\end{methoddesc}
-
-\begin{methoddesc}{push}{data}
- Creates a \class{simple_producer} object (\emph{see below}) containing the data and
- pushes it on to the channel's \code{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.
-\end{methoddesc}
-
-\begin{methoddesc}{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
- \method{more()} method and send the data to the remote endpoint.
-\end{methoddesc}
-
-\begin{methoddesc}{readable}{}
- Should return \code{True} for the channel to be included in the set of
- channels tested by the \cfunction{select()} loop for readability.
-\end{methoddesc}
-
-\begin{methoddesc}{refill_buffer}{}
- Refills the output buffer by calling the \method{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, \code{None} then the channel
- is closed.
-\end{methoddesc}
-
-\begin{methoddesc}{set_terminator}{term}
- Sets the terminating condition to be recognised on the channel. \code{term}
- may be any of three types of value, corresponding to three different ways
- to handle incoming protocol data.
-
- \begin{tableii}{l|l}{}{term}{Description}
- \lineii{\emph{string}}{Will call \method{found_terminator()} when the
- string is found in the input stream}
- \lineii{\emph{integer}}{Will call \method{found_terminator()} when the
- indicated number of characters have been received}
- \lineii{\code{None}}{The channel continues to collect data forever}
- \end{tableii}
-
- Note that any data following the terminator will be available for reading by
- the channel after \method{found_terminator()} is called.
-\end{methoddesc}
-
-\begin{methoddesc}{writable}{}
- Should return \code{True} as long as items remain on the producer fifo,
- or the channel is connected and the channel's output buffer is non-empty.
-\end{methoddesc}
-
-\subsection{asynchat - Auxiliary Classes and Functions}
-
-\begin{classdesc}{simple_producer}{data\optional{, buffer_size=512}}
- A \class{simple_producer} takes a chunk of data and an optional buffer size.
- Repeated calls to its \method{more()} method yield successive chunks of the
- data no larger than \var{buffer_size}.
-\end{classdesc}
-
-\begin{methoddesc}{more}{}
- Produces the next chunk of information from the producer, or returns the empty string.
-\end{methoddesc}
-
-\begin{classdesc}{fifo}{\optional{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 \var{list} argument is provided then it should contain producers or
- data items to be written to the channel.
-\end{classdesc}
-
-\begin{methoddesc}{is_empty}{}
- Returns \code{True} iff the fifo is empty.
-\end{methoddesc}
-
-\begin{methoddesc}{first}{}
- Returns the least-recently \method{push()}ed item from the fifo.
-\end{methoddesc}
-
-\begin{methoddesc}{push}{data}
- Adds the given data (which may be a string or a producer object) to the
- producer fifo.
-\end{methoddesc}
-
-\begin{methoddesc}{pop}{}
- If the fifo is not empty, returns \code{True, first()}, deleting the popped
- item. Returns \code{False, None} for an empty fifo.
-\end{methoddesc}
-
-The \module{asynchat} module also defines one utility function, which may be
-of use in network and textual analysis operations.
-
-\begin{funcdesc}{find_prefix_at_end}{haystack, needle}
- Returns \code{True} if string \var{haystack} ends with any non-empty
- prefix of string \var{needle}.
-\end{funcdesc}
-
-\subsection{asynchat Example \label{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
-\code{Content-Length:} header is used to set a numeric terminator to
-read the right amount of data from the channel.
-
-The \method{handle_request()} method is called once all relevant input
-has been marshalled, after setting the channel terminator to \code{None}
-to ensure that any extraneous data sent by the web client are ignored.
-
-\begin{verbatim}
-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()
-\end{verbatim}
-
diff --git a/Doc/lib/libasyncore.tex b/Doc/lib/libasyncore.tex
deleted file mode 100644
index 0552896..0000000
--- a/Doc/lib/libasyncore.tex
+++ /dev/null
@@ -1,260 +0,0 @@
-\section{\module{asyncore} ---
- Asynchronous socket handler}
-
-\declaremodule{builtin}{asyncore}
-\modulesynopsis{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}
-% Heavily adapted from original documentation by Sam Rushing.
-
-This module provides the basic infrastructure for writing asynchronous
-socket service clients and servers.
-
-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 \cfunction{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 \module{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 \refmodule{asynchat} module is invaluable.
-
-The basic idea behind both modules is to create one or more network
-\emph{channels}, instances of class \class{asyncore.dispatcher} and
-\class{asynchat.async_chat}. Creating the channels adds them to a global
-map, used by the \function{loop()} function if you do not provide it
-with your own \var{map}.
-
-Once the initial channel(s) is(are) created, calling the \function{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.
-
-\begin{funcdesc}{loop}{\optional{timeout\optional{, use_poll\optional{,
- map\optional{,count}}}}}
- Enter a polling loop that terminates after count passes or all open
- channels have been closed. All arguments are optional. The \var{count}
- parameter defaults to None, resulting in the loop terminating only
- when all channels have been closed. The \var{timeout} argument sets the
- timeout parameter for the appropriate \function{select()} or
- \function{poll()} call, measured in seconds; the default is 30 seconds.
- The \var{use_poll} parameter, if true, indicates that \function{poll()}
- should be used in preference to \function{select()} (the default is
- \code{False}).
-
- The \var{map} parameter is a dictionary whose items are
- the channels to watch. As channels are closed they are deleted from their
- map. If \var{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.
-\end{funcdesc}
-
-\begin{classdesc}{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.
-
- \begin{datadesc}{ac_in_buffer_size}
- The asynchronous input buffer size (default \code{4096}).
- \end{datadesc}
-
- \begin{datadesc}{ac_out_buffer_size}
- The asynchronous output buffer size (default \code{4096}).
- \end{datadesc}
-
- 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:
-
- \begin{tableii}{l|l}{code}{Event}{Description}
- \lineii{handle_connect()}{Implied by the first write event}
- \lineii{handle_close()}{Implied by a read event with no data available}
- \lineii{handle_accept()}{Implied by a read event on a listening socket}
- \end{tableii}
-
- During asynchronous processing, each mapped channel's \method{readable()}
- and \method{writable()} methods are used to determine whether the channel's
- socket should be added to the list of channels \cfunction{select()}ed or
- \cfunction{poll()}ed for read and write events.
-
-\end{classdesc}
-
-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:
-
-\begin{methoddesc}{handle_read}{}
- Called when the asynchronous loop detects that a \method{read()}
- call on the channel's socket will succeed.
-\end{methoddesc}
-
-\begin{methoddesc}{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:
-
-\begin{verbatim}
-def handle_write(self):
- sent = self.send(self.buffer)
- self.buffer = self.buffer[sent:]
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_close}{}
- Called when the socket is closed.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_error}{}
- Called when an exception is raised and not otherwise handled. The default
- version prints a condensed traceback.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_accept}{}
- Called on listening channels (passive openers) when a
- connection can be established with a new remote endpoint that
- has issued a \method{connect()} call for the local endpoint.
-\end{methoddesc}
-
-\begin{methoddesc}{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 \code{True},
- indicating that by default, all channels will be interested in
- read events.
-\end{methoddesc}
-
-\begin{methoddesc}{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 \code{True},
- indicating that by default, all channels will be interested in
- write events.
-\end{methoddesc}
-
-In addition, each channel delegates or extends many of the socket methods.
-Most of these are nearly identical to their socket partners.
-
-\begin{methoddesc}{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
- \refmodule{socket} documentation for information on creating
- sockets.
-\end{methoddesc}
-
-\begin{methoddesc}{connect}{address}
- As with the normal socket object, \var{address} is a
- tuple with the first element the host to connect to, and the
- second the port number.
-\end{methoddesc}
-
-\begin{methoddesc}{send}{data}
- Send \var{data} to the remote end-point of the socket.
-\end{methoddesc}
-
-\begin{methoddesc}{recv}{buffer_size}
- Read at most \var{buffer_size} bytes from the socket's remote end-point.
- An empty string implies that the channel has been closed from the other
- end.
-\end{methoddesc}
-
-\begin{methoddesc}{listen}{backlog}
- Listen for connections made to the socket. The \var{backlog}
- argument specifies the maximum number of queued connections
- and should be at least 1; the maximum value is
- system-dependent (usually 5).
-\end{methoddesc}
-
-\begin{methoddesc}{bind}{address}
- Bind the socket to \var{address}. The socket must not already be
- bound. (The format of \var{address} depends on the address family
- --- see above.) To mark the socket as re-usable (setting the
- \constant{SO_REUSEADDR} option), call the \class{dispatcher}
- object's \method{set_reuse_addr()} method.
-\end{methoddesc}
-
-\begin{methoddesc}{accept}{}
- Accept a connection. The socket must be bound to an address
- and listening for connections. The return value is a pair
- \code{(\var{conn}, \var{address})} where \var{conn} is a
- \emph{new} socket object usable to send and receive data on
- the connection, and \var{address} is the address bound to the
- socket on the other end of the connection.
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-\end{methoddesc}
-
-
-\subsection{asyncore Example basic HTTP client \label{asyncore-example}}
-
-Here is a very basic HTTP client that uses the \class{dispatcher}
-class to implement its socket handling:
-
-\begin{verbatim}
-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()
-\end{verbatim}
diff --git a/Doc/lib/libatexit.tex b/Doc/lib/libatexit.tex
deleted file mode 100644
index 04f1d49..0000000
--- a/Doc/lib/libatexit.tex
+++ /dev/null
@@ -1,108 +0,0 @@
-\section{\module{atexit} ---
- Exit handlers}
-
-\declaremodule{builtin}{atexit}
-\moduleauthor{Skip Montanaro}{skip@mojam.com}
-\sectionauthor{Skip Montanaro}{skip@mojam.com}
-\modulesynopsis{Register and execute cleanup functions.}
-
-\versionadded{2.0}
-
-
-The \module{atexit} module defines functions to register and
-unregister 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 \function{os._exit()} is called.
-
-\begin{funcdesc}{register}{func\optional{, *args\optional{, **kargs}}}
-Register \var{func} as a function to be executed at termination. Any
-optional arguments that are to be passed to \var{func} must be passed
-as arguments to \function{register()}.
-
-At normal program termination (for instance, if
-\function{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 \exception{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[This function now returns \var{func} which makes it
- possible to use it as a decorator without binding the
- original name to \code{None}]{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{unregister}{func}
-Remove a function \var{func} from the list of functions to be run at
-interpreter-shutdown. After calling \function{unregister()},
-\var{func} is guaranteed not to be called when the interpreter
-shuts down.
-
-\versionadded{3.0}
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{readline}{Useful example of \module{atexit} to read and
- write \refmodule{readline} history files.}
-\end{seealso}
-
-
-\subsection{\module{atexit} Example \label{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.
-
-\begin{verbatim}
-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)
-\end{verbatim}
-
-Positional and keyword arguments may also be passed to
-\function{register()} to be passed along to the registered function
-when it is called:
-
-\begin{verbatim}
-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')
-\end{verbatim}
-
-Usage as a decorator:
-
-\begin{verbatim}
-import atexit
-
-@atexit.register
-def goodbye():
- print "You are now leaving the Python sector."
-\end{verbatim}
-
-This obviously only works with functions that don't take arguments.
diff --git a/Doc/lib/libaudioop.tex b/Doc/lib/libaudioop.tex
deleted file mode 100644
index e827e76..0000000
--- a/Doc/lib/libaudioop.tex
+++ /dev/null
@@ -1,258 +0,0 @@
-\section{\module{audioop} ---
- Manipulate raw audio data}
-
-\declaremodule{builtin}{audioop}
-\modulesynopsis{Manipulate raw audio data.}
-
-
-The \module{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.
-All scalar items are integers, unless specified otherwise.
-
-% This para is mostly here to provide an excuse for the index entries...
-This module provides support for a-LAW, u-LAW and Intel/DVI ADPCM encodings.
-\index{Intel/DVI ADPCM}
-\index{ADPCM, Intel/DVI}
-\index{a-LAW}
-\index{u-LAW}
-
-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:
-
-\begin{excdesc}{error}
-This exception is raised on all errors, such as unknown number of bytes
-per sample, etc.
-\end{excdesc}
-
-\begin{funcdesc}{add}{fragment1, fragment2, width}
-Return a fragment which is the addition of the two samples passed as
-parameters. \var{width} is the sample width in bytes, either
-\code{1}, \code{2} or \code{4}. Both fragments should have the same
-length.
-\end{funcdesc}
-
-\begin{funcdesc}{adpcm2lin}{adpcmfragment, width, state}
-Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See
-the description of \function{lin2adpcm()} for details on ADPCM coding.
-Return a tuple \code{(\var{sample}, \var{newstate})} where the sample
-has the width specified in \var{width}.
-\end{funcdesc}
-
-\begin{funcdesc}{alaw2lin}{fragment, width}
-Convert sound fragments in a-LAW encoding to linearly encoded sound
-fragments. a-LAW encoding always uses 8 bits samples, so \var{width}
-refers only to the sample width of the output fragment here.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{avg}{fragment, width}
-Return the average over all samples in the fragment.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{bias}{fragment, width, bias}
-Return a fragment that is the original fragment with a bias added to
-each sample.
-\end{funcdesc}
-
-\begin{funcdesc}{cross}{fragment, width}
-Return the number of zero crossings in the fragment passed as an
-argument.
-\end{funcdesc}
-
-\begin{funcdesc}{findfactor}{fragment, reference}
-Return a factor \var{F} such that
-\code{rms(add(\var{fragment}, mul(\var{reference}, -\var{F})))} is
-minimal, i.e., return the factor with which you should multiply
-\var{reference} to make it match as well as possible to
-\var{fragment}. The fragments should both contain 2-byte samples.
-
-The time taken by this routine is proportional to
-\code{len(\var{fragment})}.
-\end{funcdesc}
-
-\begin{funcdesc}{findfit}{fragment, reference}
-Try to match \var{reference} as well as possible to a portion of
-\var{fragment} (which should be the longer fragment). This is
-(conceptually) done by taking slices out of \var{fragment}, using
-\function{findfactor()} to compute the best match, and minimizing the
-result. The fragments should both contain 2-byte samples. Return a
-tuple \code{(\var{offset}, \var{factor})} where \var{offset} is the
-(integer) offset into \var{fragment} where the optimal match started
-and \var{factor} is the (floating-point) factor as per
-\function{findfactor()}.
-\end{funcdesc}
-
-\begin{funcdesc}{findmax}{fragment, length}
-Search \var{fragment} for a slice of length \var{length} samples (not
-bytes!)\ with maximum energy, i.e., return \var{i} for which
-\code{rms(fragment[i*2:(i+length)*2])} is maximal. The fragments
-should both contain 2-byte samples.
-
-The routine takes time proportional to \code{len(\var{fragment})}.
-\end{funcdesc}
-
-\begin{funcdesc}{getsample}{fragment, width, index}
-Return the value of sample \var{index} from the fragment.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-
-\var{state} is a tuple containing the state of the coder. The coder
-returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the
-\var{newstate} should be passed to the next call of
-\function{lin2adpcm()}. In the initial call, \code{None} can be
-passed as the state. \var{adpcmfrag} is the ADPCM coded fragment
-packed 2 4-bit values per byte.
-\end{funcdesc}
-
-\begin{funcdesc}{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}
-\end{funcdesc}
-
-\begin{funcdesc}{lin2lin}{fragment, width, newwidth}
-Convert samples between 1-, 2- and 4-byte formats.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{minmax}{fragment, width}
-Return a tuple consisting of the minimum and maximum values of all
-samples in the sound fragment.
-\end{funcdesc}
-
-\begin{funcdesc}{max}{fragment, width}
-Return the maximum of the \emph{absolute value} of all samples in a
-fragment.
-\end{funcdesc}
-
-\begin{funcdesc}{maxpp}{fragment, width}
-Return the maximum peak-peak value in the sound fragment.
-\end{funcdesc}
-
-\begin{funcdesc}{mul}{fragment, width, factor}
-Return a fragment that has all samples in the original fragment
-multiplied by the floating-point value \var{factor}. Overflow is
-silently ignored.
-\end{funcdesc}
-
-\begin{funcdesc}{ratecv}{fragment, width, nchannels, inrate, outrate,
- state\optional{, weightA\optional{, weightB}}}
-Convert the frame rate of the input fragment.
-
-\var{state} is a tuple containing the state of the converter. The
-converter returns a tuple \code{(\var{newfragment}, \var{newstate})},
-and \var{newstate} should be passed to the next call of
-\function{ratecv()}. The initial call should pass \code{None}
-as the state.
-
-The \var{weightA} and \var{weightB} arguments are parameters for a
-simple digital filter and default to \code{1} and \code{0} respectively.
-\end{funcdesc}
-
-\begin{funcdesc}{reverse}{fragment, width}
-Reverse the samples in a fragment and returns the modified fragment.
-\end{funcdesc}
-
-\begin{funcdesc}{rms}{fragment, width}
-Return the root-mean-square of the fragment, i.e.
-\begin{displaymath}
-\catcode`_=8
-\sqrt{\frac{\sum{{S_{i}}^{2}}}{n}}
-\end{displaymath}
-This is a measure of the power in an audio signal.
-\end{funcdesc}
-
-\begin{funcdesc}{tomono}{fragment, width, lfactor, rfactor}
-Convert a stereo fragment to a mono fragment. The left channel is
-multiplied by \var{lfactor} and the right channel by \var{rfactor}
-before adding the two channels to give a mono signal.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \var{lfactor} and right channel
-samples by \var{rfactor}.
-\end{funcdesc}
-
-\begin{funcdesc}{ulaw2lin}{fragment, width}
-Convert sound fragments in u-LAW encoding to linearly encoded sound
-fragments. u-LAW encoding always uses 8 bits samples, so \var{width}
-refers only to the sample width of the output fragment here.
-\end{funcdesc}
-
-Note that operations such as \function{mul()} or \function{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:
-
-\begin{verbatim}
-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)
-\end{verbatim}
-
-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 \var{initial} state (the one you passed to
-\function{lin2adpcm()}) along to the decoder, not the final state (as
-returned by the coder). If you want to use \function{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 \function{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:
-
-\begin{verbatim}
-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)
-\end{verbatim}
diff --git a/Doc/lib/libbase64.tex b/Doc/lib/libbase64.tex
deleted file mode 100644
index 23b74f0..0000000
--- a/Doc/lib/libbase64.tex
+++ /dev/null
@@ -1,169 +0,0 @@
-\section{\module{base64} ---
- RFC 3548: Base16, Base32, Base64 Data Encodings}
-
-\declaremodule{standard}{base64}
-\modulesynopsis{RFC 3548: Base16, Base32, Base64 Data Encodings}
-
-
-\indexii{base64}{encoding}
-\index{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:
-
-\begin{funcdesc}{b64encode}{s\optional{, altchars}}
-Encode a string use Base64.
-
-\var{s} is the string to encode. Optional \var{altchars} must be a
-string of at least length 2 (additional characters are ignored) which
-specifies an alternative alphabet for the \code{+} and \code{/}
-characters. This allows an application to e.g. generate URL or
-filesystem safe Base64 strings. The default is \code{None}, for which
-the standard Base64 alphabet is used.
-
-The encoded string is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{b64decode}{s\optional{, altchars}}
-Decode a Base64 encoded string.
-
-\var{s} is the string to decode. Optional \var{altchars} must be a
-string of at least length 2 (additional characters are ignored) which
-specifies the alternative alphabet used instead of the \code{+} and
-\code{/} characters.
-
-The decoded string is returned. A \exception{TypeError} is raised if
-\var{s} were incorrectly padded or if there are non-alphabet
-characters present in the string.
-\end{funcdesc}
-
-\begin{funcdesc}{standard_b64encode}{s}
-Encode string \var{s} using the standard Base64 alphabet.
-\end{funcdesc}
-
-\begin{funcdesc}{standard_b64decode}{s}
-Decode string \var{s} using the standard Base64 alphabet.
-\end{funcdesc}
-
-\begin{funcdesc}{urlsafe_b64encode}{s}
-Encode string \var{s} using a URL-safe alphabet, which substitutes
-\code{-} instead of \code{+} and \code{_} instead of \code{/} in the
-standard Base64 alphabet.
-\end{funcdesc}
-
-\begin{funcdesc}{urlsafe_b64decode}{s}
-Decode string \var{s} using a URL-safe alphabet, which substitutes
-\code{-} instead of \code{+} and \code{_} instead of \code{/} in the
-standard Base64 alphabet.
-\end{funcdesc}
-
-\begin{funcdesc}{b32encode}{s}
-Encode a string using Base32. \var{s} is the string to encode. The
-encoded string is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{b32decode}{s\optional{, casefold\optional{, map01}}}
-Decode a Base32 encoded string.
-
-\var{s} is the string to decode. Optional \var{casefold} is a flag
-specifying whether a lowercase alphabet is acceptable as input. For
-security purposes, the default is \code{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
-\var{map01} when not \code{None}, specifies which letter the digit 1 should
-be mapped to (when \var{map01} is not \code{None}, the digit 0 is always
-mapped to the letter O). For security purposes the default is
-\code{None}, so that 0 and 1 are not allowed in the input.
-
-The decoded string is returned. A \exception{TypeError} is raised if
-\var{s} were incorrectly padded or if there are non-alphabet characters
-present in the string.
-\end{funcdesc}
-
-\begin{funcdesc}{b16encode}{s}
-Encode a string using Base16.
-
-\var{s} is the string to encode. The encoded string is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{b16decode}{s\optional{, casefold}}
-Decode a Base16 encoded string.
-
-\var{s} is the string to decode. Optional \var{casefold} is a flag
-specifying whether a lowercase alphabet is acceptable as input. For
-security purposes, the default is \code{False}.
-
-The decoded string is returned. A \exception{TypeError} is raised if
-\var{s} were incorrectly padded or if there are non-alphabet
-characters present in the string.
-\end{funcdesc}
-
-The legacy interface:
-
-\begin{funcdesc}{decode}{input, output}
-Decode the contents of the \var{input} file and write the resulting
-binary data to the \var{output} file.
-\var{input} and \var{output} must either be file objects or objects that
-mimic the file object interface. \var{input} will be read until
-\code{\var{input}.read()} returns an empty string.
-\end{funcdesc}
-
-\begin{funcdesc}{decodestring}{s}
-Decode the string \var{s}, which must contain one or more lines of
-base64 encoded data, and return a string containing the resulting
-binary data.
-\end{funcdesc}
-
-\begin{funcdesc}{encode}{input, output}
-Encode the contents of the \var{input} file and write the resulting
-base64 encoded data to the \var{output} file.
-\var{input} and \var{output} must either be file objects or objects that
-mimic the file object interface. \var{input} will be read until
-\code{\var{input}.read()} returns an empty string. \function{encode()}
-returns the encoded data plus a trailing newline character
-(\code{'\e n'}).
-\end{funcdesc}
-
-\begin{funcdesc}{encodestring}{s}
-Encode the string \var{s}, which can contain arbitrary binary data,
-and return a string containing one or more lines of
-base64-encoded data. \function{encodestring()} returns a
-string containing one or more lines of base64-encoded data
-always including an extra trailing newline (\code{'\e n'}).
-\end{funcdesc}
-
-An example usage of the module:
-
-\begin{verbatim}
->>> import base64
->>> encoded = base64.b64encode('data to be encoded')
->>> encoded
-'ZGF0YSB0byBiZSBlbmNvZGVk'
->>> data = base64.b64decode(encoded)
->>> data
-'data to be encoded'
-\end{verbatim}
-
-\begin{seealso}
- \seemodule{binascii}{Support module containing \ASCII-to-binary
- and binary-to-\ASCII{} conversions.}
- \seerfc{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.}
-\end{seealso}
diff --git a/Doc/lib/libbasehttp.tex b/Doc/lib/libbasehttp.tex
deleted file mode 100644
index 64c069f..0000000
--- a/Doc/lib/libbasehttp.tex
+++ /dev/null
@@ -1,245 +0,0 @@
-\section{\module{BaseHTTPServer} ---
- Basic HTTP server}
-
-\declaremodule{standard}{BaseHTTPServer}
-\modulesynopsis{Basic HTTP server (base class for
- \class{SimpleHTTPServer} and \class{CGIHTTPServer}).}
-
-
-\indexii{WWW}{server}
-\indexii{HTTP}{protocol}
-\index{URL}
-\index{httpd}
-
-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
-\refmodule{SimpleHTTPServer}\refstmodindex{SimpleHTTPServer} and
-\refmodule{CGIHTTPServer}\refstmodindex{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:
-
-\begin{verbatim}
-def run(server_class=BaseHTTPServer.HTTPServer,
- handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
- server_address = ('', 8000)
- httpd = server_class(server_address, handler_class)
- httpd.serve_forever()
-\end{verbatim}
-
-\begin{classdesc}{HTTPServer}{server_address, RequestHandlerClass}
-This class builds on the \class{TCPServer} class by
-storing the server address as instance
-variables named \member{server_name} and \member{server_port}. The
-server is accessible by the handler, typically through the handler's
-\member{server} instance variable.
-\end{classdesc}
-
-\begin{classdesc}{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 \samp{SPAM}, the
-\method{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
-\method{__init__()} method.
-\end{classdesc}
-
-
-\class{BaseHTTPRequestHandler} has the following instance variables:
-
-\begin{memberdesc}{client_address}
-Contains a tuple of the form \code{(\var{host}, \var{port})} referring
-to the client's address.
-\end{memberdesc}
-
-\begin{memberdesc}{command}
-Contains the command (request type). For example, \code{'GET'}.
-\end{memberdesc}
-
-\begin{memberdesc}{path}
-Contains the request path.
-\end{memberdesc}
-
-\begin{memberdesc}{request_version}
-Contains the version string from the request. For example,
-\code{'HTTP/1.0'}.
-\end{memberdesc}
-
-\begin{memberdesc}{headers}
-Holds an instance of the class specified by the \member{MessageClass}
-class variable. This instance parses and manages the headers in
-the HTTP request.
-\end{memberdesc}
-
-\begin{memberdesc}{rfile}
-Contains an input stream, positioned at the start of the optional
-input data.
-\end{memberdesc}
-
-\begin{memberdesc}{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.
-\end{memberdesc}
-
-
-\class{BaseHTTPRequestHandler} has the following class variables:
-
-\begin{memberdesc}{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, \code{'BaseHTTP/0.2'}.
-\end{memberdesc}
-
-\begin{memberdesc}{sys_version}
-Contains the Python system version, in a form usable by the
-\member{version_string} method and the \member{server_version} class
-variable. For example, \code{'Python/1.4'}.
-\end{memberdesc}
-
-\begin{memberdesc}{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 \var{code} key should
-be an integer, specifying the numeric HTTP error code value.
-\var{message} should be a string containing a (detailed) error
-message of what occurred, and \var{explain} should be an
-explanation of the error code number. Default \var{message}
-and \var{explain} values can found in the \var{responses}
-class variable.
-\end{memberdesc}
-
-\begin{memberdesc}{protocol_version}
-This specifies the HTTP protocol version used in responses. If set
-to \code{'HTTP/1.1'}, the server will permit HTTP persistent
-connections; however, your server \emph{must} then include an
-accurate \code{Content-Length} header (using \method{send_header()})
-in all of its responses to clients. For backwards compatibility,
-the setting defaults to \code{'HTTP/1.0'}.
-\end{memberdesc}
-
-\begin{memberdesc}{MessageClass}
-Specifies a \class{rfc822.Message}-like class to parse HTTP
-headers. Typically, this is not overridden, and it defaults to
-\class{mimetools.Message}.
-\withsubitem{(in module mimetools)}{\ttindex{Message}}
-\end{memberdesc}
-
-\begin{memberdesc}{responses}
-This variable contains a mapping of error code integers to two-element
-tuples containing a short and long message. For example,
-\code{\{\var{code}: (\var{shortmessage}, \var{longmessage})\}}. The
-\var{shortmessage} is usually used as the \var{message} key in an
-error response, and \var{longmessage} as the \var{explain} key
-(see the \member{error_message_format} class variable).
-\end{memberdesc}
-
-
-A \class{BaseHTTPRequestHandler} instance has the following methods:
-
-\begin{methoddesc}{handle}{}
-Calls \method{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
-\method{do_*()} methods.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_one_request}{}
-This method will parse and dispatch
-the request to the appropriate \method{do_*()} method. You should
-never need to override it.
-\end{methoddesc}
-
-\begin{methoddesc}{send_error}{code\optional{, message}}
-Sends and logs a complete error reply to the client. The numeric
-\var{code} specifies the HTTP error code, with \var{message} as
-optional, more specific text. A complete set of headers is sent,
-followed by text composed using the \member{error_message_format}
-class variable.
-\end{methoddesc}
-
-\begin{methoddesc}{send_response}{code\optional{, message}}
-Sends a response header and logs the accepted request. The HTTP
-response line is sent, followed by \emph{Server} and \emph{Date}
-headers. The values for these two headers are picked up from the
-\method{version_string()} and \method{date_time_string()} methods,
-respectively.
-\end{methoddesc}
-
-\begin{methoddesc}{send_header}{keyword, value}
-Writes a specific HTTP header to the output stream. \var{keyword}
-should specify the header keyword, with \var{value} specifying
-its value.
-\end{methoddesc}
-
-\begin{methoddesc}{end_headers}{}
-Sends a blank line, indicating the end of the HTTP headers in
-the response.
-\end{methoddesc}
-
-\begin{methoddesc}{log_request}{\optional{code\optional{, size}}}
-Logs an accepted (successful) request. \var{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
-\var{size} parameter.
-\end{methoddesc}
-
-\begin{methoddesc}{log_error}{...}
-Logs an error when a request cannot be fulfilled. By default,
-it passes the message to \method{log_message()}, so it takes the
-same arguments (\var{format} and additional values).
-\end{methoddesc}
-
-\begin{methoddesc}{log_message}{format, ...}
-Logs an arbitrary message to \code{sys.stderr}. This is typically
-overridden to create custom error logging mechanisms. The
-\var{format} argument is a standard printf-style format string,
-where the additional arguments to \method{log_message()} are applied
-as inputs to the formatting. The client address and current date
-and time are prefixed to every message logged.
-\end{methoddesc}
-
-\begin{methoddesc}{version_string}{}
-Returns the server software's version string. This is a combination
-of the \member{server_version} and \member{sys_version} class variables.
-\end{methoddesc}
-
-\begin{methoddesc}{date_time_string}{\optional{timestamp}}
-Returns the date and time given by \var{timestamp} (which must be in the
-format returned by \function{time.time()}), formatted for a message header.
-If \var{timestamp} is omitted, it uses the current date and time.
-
-The result looks like \code{'Sun, 06 Nov 1994 08:49:37 GMT'}.
-\versionadded[The \var{timestamp} parameter]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{log_date_time_string}{}
-Returns the current date and time, formatted for logging.
-\end{methoddesc}
-
-\begin{methoddesc}{address_string}{}
-Returns the client address, formatted for logging. A name lookup
-is performed on the client's IP address.
-\end{methoddesc}
-
-
-\begin{seealso}
- \seemodule{CGIHTTPServer}{Extended request handler that supports CGI
- scripts.}
-
- \seemodule{SimpleHTTPServer}{Basic request handler that limits response
- to files actually under the document root.}
-\end{seealso}
diff --git a/Doc/lib/libbinascii.tex b/Doc/lib/libbinascii.tex
deleted file mode 100644
index 84d29c6..0000000
--- a/Doc/lib/libbinascii.tex
+++ /dev/null
@@ -1,147 +0,0 @@
-\section{\module{binascii} ---
- Convert between binary and \ASCII}
-
-\declaremodule{builtin}{binascii}
-\modulesynopsis{Tools for converting between binary and various
- \ASCII-encoded binary representations.}
-
-
-The \module{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 \refmodule{uu}\refstmodindex{uu},
-\refmodule{base64}\refstmodindex{base64}, or
-\refmodule{binhex}\refstmodindex{binhex} instead. The \module{binascii} module
-contains low-level functions written in C for greater speed
-that are used by the higher-level modules.
-
-The \module{binascii} module defines the following functions:
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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
-\var{data} should be at most 45.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \var{data} should be at most 57 to adhere to the base64
-standard.
-\end{funcdesc}
-
-\begin{funcdesc}{a2b_qp}{string\optional{, 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 \var{header} is present and true, underscores
-will be decoded as spaces.
-\end{funcdesc}
-
-\begin{funcdesc}{b2a_qp}{data\optional{, 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 \var{quotetabs} is present and true, all tabs
-and spaces will be encoded.
-If the optional argument \var{istext} is present and true,
-newlines are not encoded but trailing whitespace will be encoded.
-If the optional argument \var{header} is
-present and true, spaces will be encoded as underscores per RFC1522.
-If the optional argument \var{header} is present and false, newline
-characters will be encoded as well; otherwise linefeed conversion might
-corrupt the binary data stream.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{rledecode_hqx}{data}
-Perform RLE-decompression on the data, as per the binhex4
-standard. The algorithm uses \code{0x90} after a byte as a repeat
-indicator, followed by a count. A count of \code{0} specifies a byte
-value of \code{0x90}. The routine returns the decompressed data,
-unless data input data ends in an orphaned repeat indicator, in which
-case the \exception{Incomplete} exception is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{rlecode_hqx}{data}
-Perform binhex4 style RLE-compression on \var{data} and return the
-result.
-\end{funcdesc}
-
-\begin{funcdesc}{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).
-\end{funcdesc}
-
-\begin{funcdesc}{crc_hqx}{data, crc}
-Compute the binhex4 crc value of \var{data}, starting with an initial
-\var{crc} and returning the result.
-\end{funcdesc}
-
-\begin{funcdesc}{crc32}{data\optional{, 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:
-\begin{verbatim}
- print binascii.crc32("hello world")
- # Or, in two pieces:
- crc = binascii.crc32("hello")
- crc = binascii.crc32(" world", crc)
- print crc
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{b2a_hex}{data}
-\funcline{hexlify}{data}
-Return the hexadecimal representation of the binary \var{data}. Every
-byte of \var{data} is converted into the corresponding 2-digit hex
-representation. The resulting string is therefore twice as long as
-the length of \var{data}.
-\end{funcdesc}
-
-\begin{funcdesc}{a2b_hex}{hexstr}
-\funcline{unhexlify}{hexstr}
-Return the binary data represented by the hexadecimal string
-\var{hexstr}. This function is the inverse of \function{b2a_hex()}.
-\var{hexstr} must contain an even number of hexadecimal digits (which
-can be upper or lower case), otherwise a \exception{TypeError} is
-raised.
-\end{funcdesc}
-
-\begin{excdesc}{Error}
-Exception raised on errors. These are usually programming errors.
-\end{excdesc}
-
-\begin{excdesc}{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.
-\end{excdesc}
-
-
-\begin{seealso}
- \seemodule{base64}{Support for base64 encoding used in MIME email messages.}
-
- \seemodule{binhex}{Support for the binhex format used on the Macintosh.}
-
- \seemodule{uu}{Support for UU encoding used on \UNIX.}
-
- \seemodule{quopri}{Support for quoted-printable encoding used in MIME email messages. }
-\end{seealso}
diff --git a/Doc/lib/libbinhex.tex b/Doc/lib/libbinhex.tex
deleted file mode 100644
index d30f2b4..0000000
--- a/Doc/lib/libbinhex.tex
+++ /dev/null
@@ -1,55 +0,0 @@
-\section{\module{binhex} ---
- Encode and decode binhex4 files}
-
-\declaremodule{standard}{binhex}
-\modulesynopsis{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 \module{binhex} module defines the following functions:
-
-\begin{funcdesc}{binhex}{input, output}
-Convert a binary file with filename \var{input} to binhex file
-\var{output}. The \var{output} parameter can either be a filename or a
-file-like object (any object supporting a \method{write()} and
-\method{close()} method).
-\end{funcdesc}
-
-\begin{funcdesc}{hexbin}{input\optional{, output}}
-Decode a binhex file \var{input}. \var{input} may be a filename or a
-file-like object supporting \method{read()} and \method{close()} methods.
-The resulting file is written to a file named \var{output}, unless the
-argument is omitted in which case the output filename is read from the
-binhex file.
-\end{funcdesc}
-
-The following exception is also defined:
-
-\begin{excdesc}{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.
-\end{excdesc}
-
-
-\begin{seealso}
- \seemodule{binascii}{Support module containing \ASCII-to-binary
- and binary-to-\ASCII{} conversions.}
-\end{seealso}
-
-
-\subsection{Notes \label{binhex-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, \function{hexbin()} appears to not work in all
-cases.
diff --git a/Doc/lib/libbisect.tex b/Doc/lib/libbisect.tex
deleted file mode 100644
index 516e5cf..0000000
--- a/Doc/lib/libbisect.tex
+++ /dev/null
@@ -1,84 +0,0 @@
-\section{\module{bisect} ---
- Array bisection algorithm}
-
-\declaremodule{standard}{bisect}
-\modulesynopsis{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
-\module{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:
-
-\begin{funcdesc}{bisect_left}{list, item\optional{, lo\optional{, hi}}}
- Locate the proper insertion point for \var{item} in \var{list} to
- maintain sorted order. The parameters \var{lo} and \var{hi} may be
- used to specify a subset of the list which should be considered; by
- default the entire list is used. If \var{item} is already present
- in \var{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 \code{\var{list}.insert()}. This assumes that
- \var{list} is already sorted.
-\versionadded{2.1}
-\end{funcdesc}
-
-\begin{funcdesc}{bisect_right}{list, item\optional{, lo\optional{, hi}}}
- Similar to \function{bisect_left()}, but returns an insertion point
- which comes after (to the right of) any existing entries of
- \var{item} in \var{list}.
-\versionadded{2.1}
-\end{funcdesc}
-
-\begin{funcdesc}{bisect}{\unspecified}
- Alias for \function{bisect_right()}.
-\end{funcdesc}
-
-\begin{funcdesc}{insort_left}{list, item\optional{, lo\optional{, hi}}}
- Insert \var{item} in \var{list} in sorted order. This is equivalent
- to \code{\var{list}.insert(bisect.bisect_left(\var{list}, \var{item},
- \var{lo}, \var{hi}), \var{item})}. This assumes that \var{list} is
- already sorted.
-\versionadded{2.1}
-\end{funcdesc}
-
-\begin{funcdesc}{insort_right}{list, item\optional{, lo\optional{, hi}}}
- Similar to \function{insort_left()}, but inserting \var{item} in
- \var{list} after any existing entries of \var{item}.
-\versionadded{2.1}
-\end{funcdesc}
-
-\begin{funcdesc}{insort}{\unspecified}
- Alias for \function{insort_right()}.
-\end{funcdesc}
-
-
-\subsection{Examples}
-\nodename{bisect-example}
-
-The \function{bisect()} function is generally useful for categorizing
-numeric data. This example uses \function{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.
-
-\begin{verbatim}
->>> 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']
-
-\end{verbatim}
diff --git a/Doc/lib/libbltin.tex b/Doc/lib/libbltin.tex
deleted file mode 100644
index f6abe25..0000000
--- a/Doc/lib/libbltin.tex
+++ /dev/null
@@ -1,44 +0,0 @@
-\section{\module{__builtin__} ---
- Built-in objects}
-
-\declaremodule[builtin]{builtin}{__builtin__}
-\modulesynopsis{The module that provides the built-in namespace.}
-
-
-This module provides direct access to all `built-in' identifiers of
-Python; for example, \code{__builtin__.open} is the full name for the
-built-in function \function{open()}. See chapter~\ref{builtin},
-``Built-in Objects.''
-
-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
-\function{open()} function that wraps the built-in \function{open()},
-this module can be used directly:
-
-\begin{verbatim}
-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()
-
- # ...
-\end{verbatim}
-
-As an implementation detail, most modules have the name
-\code{__builtins__} (note the \character{s}) made available as part of
-their globals. The value of \code{__builtins__} is normally either
-this module or the value of this modules's \member{__dict__}
-attribute. Since this is an implementation detail, it may not be used
-by alternate implementations of Python.
diff --git a/Doc/lib/libbsddb.tex b/Doc/lib/libbsddb.tex
deleted file mode 100644
index 8f23324..0000000
--- a/Doc/lib/libbsddb.tex
+++ /dev/null
@@ -1,211 +0,0 @@
-\section{\module{bsddb} ---
- Interface to Berkeley DB library}
-
-\declaremodule{extension}{bsddb}
-\modulesynopsis{Interface to Berkeley DB database library}
-\sectionauthor{Skip Montanaro}{skip@mojam.com}
-
-
-The \module{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 \function{marshal.dumps()} or
-\function{pickle.dumps()}.
-
-The \module{bsddb} module requires a Berkeley DB library version from
-3.3 thru 4.5.
-
-\begin{seealso}
- \seeurl{http://pybsddb.sourceforge.net/}
- {The website with documentation for the \module{bsddb.db}
- Python Berkeley DB interface that closely mirrors the object
- oriented interface provided in Berkeley DB 3 and 4.}
-
- \seeurl{http://www.oracle.com/database/berkeley-db/}
- {The Berkeley DB library.}
-\end{seealso}
-
-A more modern DB, DBEnv and DBSequence object interface is available in the
-\module{bsddb.db} module which closely matches the Berkeley DB C API
-documented at the above URLs. Additional features provided by the
-\module{bsddb.db} API include fine tuning, transactions, logging, and
-multiprocess concurrent database access.
-
-The following is a description of the legacy \module{bsddb} interface
-compatible with the old Python bsddb module. Starting in Python 2.5 this
-interface should be safe for multithreaded access. The \module{bsddb.db}
-API is recommended for threading users as it provides better control.
-
-The \module{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.
-
-\begin{funcdesc}{hashopen}{filename\optional{, flag\optional{,
- mode\optional{, pgsize\optional{,
- ffactor\optional{, nelem\optional{,
- cachesize\optional{, lorder\optional{,
- hflags}}}}}}}}}
-Open the hash format file named \var{filename}. Files never intended
-to be preserved on disk may be created by passing \code{None} as the
-\var{filename}. The optional
-\var{flag} identifies the mode used to open the file. It may be
-\character{r} (read only), \character{w} (read-write) ,
-\character{c} (read-write - create if necessary; the default) or
-\character{n} (read-write - truncate to zero length). The other
-arguments are rarely used and are just passed to the low-level
-\cfunction{dbopen()} function. Consult the Berkeley DB documentation
-for their use and interpretation.
-\end{funcdesc}
-
-\begin{funcdesc}{btopen}{filename\optional{, flag\optional{,
-mode\optional{, btflags\optional{, cachesize\optional{, maxkeypage\optional{,
-minkeypage\optional{, pgsize\optional{, lorder}}}}}}}}}
-
-Open the btree format file named \var{filename}. Files never intended
-to be preserved on disk may be created by passing \code{None} as the
-\var{filename}. The optional
-\var{flag} identifies the mode used to open the file. It may be
-\character{r} (read only), \character{w} (read-write),
-\character{c} (read-write - create if necessary; the default) or
-\character{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.
-\end{funcdesc}
-
-\begin{funcdesc}{rnopen}{filename\optional{, flag\optional{, mode\optional{,
-rnflags\optional{, cachesize\optional{, pgsize\optional{, lorder\optional{,
-rlen\optional{, delim\optional{, source\optional{, pad}}}}}}}}}}}
-
-Open a DB record format file named \var{filename}. Files never intended
-to be preserved on disk may be created by passing \code{None} as the
-\var{filename}. The optional
-\var{flag} identifies the mode used to open the file. It may be
-\character{r} (read only), \character{w} (read-write),
-\character{c} (read-write - create if necessary; the default) or
-\character{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.
-\end{funcdesc}
-
-\begin{classdesc}{StringKeys}{db}
- Wrapper class around a DB object that supports string keys
- (rather than bytes). All keys are encoded as UTF-8, then passed
- to the underlying object. \versionadded{3.0}
-\end{classdesc}
-
-\begin{classdesc}{StringValues}{db}
- Wrapper class around a DB object that supports string values
- (rather than bytes). All values are encoded as UTF-8, then passed
- to the underlying object. \versionadded{3.0}
-\end{classdesc}
-
-\begin{seealso}
- \seemodule{dbhash}{DBM-style interface to the \module{bsddb}}
-\end{seealso}
-
-\subsection{Hash, BTree and Record Objects \label{bsddb-objects}}
-
-Once instantiated, hash, btree and record objects support
-the same methods as dictionaries. In addition, they support
-the methods listed below.
-\versionchanged[Added dictionary methods]{2.3.1}
-
-\begin{methoddesc}[bsddbobject]{close}{}
-Close the underlying file. The object can no longer be accessed. Since
-there is no open \method{open} method for these objects, to open the file
-again a new \module{bsddb} module open function must be called.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{methoddesc}[bsddbobject]{has_key}{key}
-Return \code{1} if the DB file contains the argument as a key.
-\end{methoddesc}
-
-\begin{methoddesc}[bsddbobject]{set_location}{key}
-Set the cursor to the item indicated by \var{key} and return a tuple
-containing the key and its value. For binary tree databases (opened
-using \function{btopen()}), if \var{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,
-\exception{KeyError} will be raised if \var{key} is not found in the
-database.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \exception{bsddb.error} if the database is empty.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \function{hashopen()}).
-\end{methoddesc}
-
-\begin{methoddesc}[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 \function{hashopen()}).
-This method raises \exception{bsddb.error} if the database is empty.
-\end{methoddesc}
-
-\begin{methoddesc}[bsddbobject]{sync}{}
-Synchronize the database on disk.
-\end{methoddesc}
-
-Example:
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
diff --git a/Doc/lib/libbz2.tex b/Doc/lib/libbz2.tex
deleted file mode 100644
index 36bc0d2..0000000
--- a/Doc/lib/libbz2.tex
+++ /dev/null
@@ -1,165 +0,0 @@
-\section{\module{bz2} ---
- Compression compatible with \program{bzip2}}
-
-\declaremodule{builtin}{bz2}
-\modulesynopsis{Interface to compression and decompression
- routines compatible with \program{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:
-
-\begin{itemize}
-\item \class{BZ2File} class implements a complete file interface, including
- \method{readline()}, \method{readlines()},
- \method{writelines()}, \method{seek()}, etc;
-\item \class{BZ2File} class implements emulated \method{seek()} support;
-\item \class{BZ2File} class implements universal newline support;
-\item \class{BZ2File} class offers an optimized line iteration using
- the readahead algorithm borrowed from file objects;
-\item Sequential (de)compression supported by \class{BZ2Compressor} and
- \class{BZ2Decompressor} classes;
-\item One-shot (de)compression supported by \function{compress()} and
- \function{decompress()} functions;
-\item Thread safety uses individual locking mechanism;
-\item Complete inline documentation;
-\end{itemize}
-
-
-\subsection{(De)compression of files}
-
-Handling of compressed files is offered by the \class{BZ2File} class.
-
-\begin{classdesc}{BZ2File}{filename\optional{, mode\optional{,
- buffering\optional{, compresslevel}}}}
-Open a bz2 file. Mode can be either \code{'r'} or \code{'w'}, for reading
-(default) or writing. When opened for writing, the file will be created if
-it doesn't exist, and truncated otherwise. If \var{buffering} is given,
-\code{0} means unbuffered, and larger numbers specify the buffer size;
-the default is \code{0}. If
-\var{compresslevel} is given, it must be a number between \code{1} and
-\code{9}; the default is \code{9}.
-Add a \character{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
-\character{\e n} in Python. Also, a file so opened gains the
-attribute \member{newlines}; the value for this attribute is one of
-\code{None} (no newline read yet), \code{'\e r'}, \code{'\e n'},
-\code{'\e r\e 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.
-\end{classdesc}
-
-\begin{methoddesc}[BZ2File]{close}{}
-Close the file. Sets data attribute \member{closed} to true. A closed file
-cannot be used for further I/O operations. \method{close()} may be called
-more than once without error.
-\end{methoddesc}
-
-\begin{methoddesc}[BZ2File]{read}{\optional{size}}
-Read at most \var{size} uncompressed bytes, returned as a string. If the
-\var{size} argument is negative or omitted, read until EOF is reached.
-\end{methoddesc}
-
-\begin{methoddesc}[BZ2File]{readline}{\optional{size}}
-Return the next line from the file, as a string, retaining newline.
-A non-negative \var{size} argument limits the maximum number of bytes to
-return (an incomplete line may be returned then). Return an empty
-string at EOF.
-\end{methoddesc}
-
-\begin{methoddesc}[BZ2File]{readlines}{\optional{size}}
-Return a list of lines read. The optional \var{size} argument, if given,
-is an approximate bound on the total number of bytes in the lines returned.
-\end{methoddesc}
-
-\begin{methoddesc}[BZ2File]{seek}{offset\optional{, whence}}
-Move to new file position. Argument \var{offset} is a byte count. Optional
-argument \var{whence} defaults to \code{os.SEEK_SET} or \code{0} (offset from start of file;
-offset should be \code{>= 0}); other values are \code{os.SEEK_CUR} or \code{1} (move relative to
-current position; offset can be positive or negative), and \code{os.SEEK_END} or \code{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.
-\end{methoddesc}
-
-\begin{methoddesc}[BZ2File]{tell}{}
-Return the current file position, an integer (may be a long integer).
-\end{methoddesc}
-
-\begin{methoddesc}[BZ2File]{write}{data}
-Write string \var{data} to file. Note that due to buffering, \method{close()}
-may be needed before the file on disk reflects the data written.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-
-\subsection{Sequential (de)compression}
-
-Sequential compression and decompression is done using the classes
-\class{BZ2Compressor} and \class{BZ2Decompressor}.
-
-\begin{classdesc}{BZ2Compressor}{\optional{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
-\function{compress()} function instead. The \var{compresslevel} parameter,
-if given, must be a number between \code{1} and \code{9}; the default
-is \code{9}.
-\end{classdesc}
-
-\begin{methoddesc}[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 \method{flush()} method to finish the compression process, and return what
-is left in internal buffers.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{classdesc}{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
-\function{decompress()} function instead.
-\end{classdesc}
-
-\begin{methoddesc}[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, \exception{EOFError} will be raised. If any data was
-found after the end of stream, it'll be ignored and saved in
-\member{unused\_data} attribute.
-\end{methoddesc}
-
-
-\subsection{One-shot (de)compression}
-
-One-shot compression and decompression is provided through the
-\function{compress()} and \function{decompress()} functions.
-
-\begin{funcdesc}{compress}{data\optional{, compresslevel}}
-Compress \var{data} in one shot. If you want to compress data sequentially,
-use an instance of \class{BZ2Compressor} instead. The \var{compresslevel}
-parameter, if given, must be a number between \code{1} and \code{9};
-the default is \code{9}.
-\end{funcdesc}
-
-\begin{funcdesc}{decompress}{data}
-Decompress \var{data} in one shot. If you want to decompress data
-sequentially, use an instance of \class{BZ2Decompressor} instead.
-\end{funcdesc}
diff --git a/Doc/lib/libcalendar.tex b/Doc/lib/libcalendar.tex
deleted file mode 100644
index acfd2da..0000000
--- a/Doc/lib/libcalendar.tex
+++ /dev/null
@@ -1,304 +0,0 @@
-\section{\module{calendar} ---
- General calendar-related functions}
-
-\declaremodule{standard}{calendar}
-\modulesynopsis{Functions for working with calendars,
- including some emulation of the \UNIX\ \program{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 \function{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.
-
-Most of these functions and classses rely on the \module{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.
-
-\begin{classdesc}{Calendar}{\optional{firstweekday}}
-Creates a \class{Calendar} object. \var{firstweekday} is an integer
-specifying the first day of the week. \code{0} is Monday (the default),
-\code{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}
-\end{classdesc}
-
-\class{Calendar} instances have the following methods:
-
-\begin{methoddesc}{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 \method{firstweekday()}.
-\end{methoddesc}
-
-\begin{methoddesc}{itermonthdates}{year, month}
-Return an iterator for the month \var{month} (1-12) in the
-year \var{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.
-\end{methoddesc}
-
-\begin{methoddesc}{itermonthdays2}{year, month}
-Return an iterator for the month \var{month} in the year
-\var{year} similar to \method{itermonthdates()}. Days returned
-will be tuples consisting of a day number and a week day
-number.
-\end{methoddesc}
-
-\begin{methoddesc}{itermonthdays}{year, month}
-Return an iterator for the month \var{month} in the year
-\var{year} similar to \method{itermonthdates()}. Days returned
-will simply be day numbers.
-\end{methoddesc}
-
-\begin{methoddesc}{monthdatescalendar}{year, month}
-Return a list of the weeks in the month \var{month} of
-the \var{year} as full weeks. Weeks are lists of seven
-\class{datetime.date} objects.
-\end{methoddesc}
-
-\begin{methoddesc}{monthdays2calendar}{year, month}
-Return a list of the weeks in the month \var{month} of
-the \var{year} as full weeks. Weeks are lists of seven
-tuples of day numbers and weekday numbers.
-\end{methoddesc}
-
-\begin{methoddesc}{monthdayscalendar}{year, month}
-Return a list of the weeks in the month \var{month} of
-the \var{year} as full weeks. Weeks are lists of seven
-day numbers.
-\end{methoddesc}
-
-\begin{methoddesc}{yeardatescalendar}{year, month\optional{, 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 \var{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.
-\end{methoddesc}
-
-\begin{methoddesc}{yeardays2calendar}{year, month\optional{, width}}
-Return the data for the specified year ready for formatting (similar to
-\method{yeardatescalendar()}). Entries in the week lists are tuples of
-day numbers and weekday numbers. Day numbers outside this month are zero.
-\end{methoddesc}
-
-\begin{methoddesc}{yeardayscalendar}{year, month\optional{, width}}
-Return the data for the specified year ready for formatting (similar to
-\method{yeardatescalendar()}). Entries in the week lists are day numbers.
-Day numbers outside this month are zero.
-\end{methoddesc}
-
-
-\begin{classdesc}{TextCalendar}{\optional{firstweekday}}
-This class can be used to generate plain text calendars.
-
-\versionadded{2.5}
-\end{classdesc}
-
-\class{TextCalendar} instances have the following methods:
-
-\begin{methoddesc}{formatmonth}{theyear, themonth\optional{, w\optional{, l}}}
-Return a month's calendar in a multi-line string. If \var{w} is
-provided, it specifies the width of the date columns, which are
-centered. If \var{l} is given, it specifies the number of lines that
-each week will use. Depends on the first weekday as set by
-\function{setfirstweekday()}.
-\end{methoddesc}
-
-\begin{methoddesc}{prmonth}{theyear, themonth\optional{, w\optional{, l}}}
-Print a month's calendar as returned by \method{formatmonth()}.
-\end{methoddesc}
-
-\begin{methoddesc}{formatyear}{theyear, themonth\optional{, w\optional{,
- l\optional{, c\optional{, m}}}}}
-Return a \var{m}-column calendar for an entire year as a multi-line string.
-Optional parameters \var{w}, \var{l}, and \var{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
-\method{setfirstweekday()}. The earliest year for which a calendar can
-be generated is platform-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}{pryear}{theyear\optional{, w\optional{, l\optional{,
- c\optional{, m}}}}}
-Print the calendar for an entire year as returned by \method{formatyear()}.
-\end{methoddesc}
-
-
-\begin{classdesc}{HTMLCalendar}{\optional{firstweekday}}
-This class can be used to generate HTML calendars.
-
-\versionadded{2.5}
-\end{classdesc}
-
-\class{HTMLCalendar} instances have the following methods:
-
-\begin{methoddesc}{formatmonth}{theyear, themonth\optional{, withyear}}
-Return a month's calendar as an HTML table. If \var{withyear} is
-true the year will be included in the header, otherwise just the
-month name will be used.
-\end{methoddesc}
-
-\begin{methoddesc}{formatyear}{theyear, themonth\optional{, width}}
-Return a year's calendar as an HTML table. \var{width} (defaulting to 3)
-specifies the number of months per row.
-\end{methoddesc}
-
-\begin{methoddesc}{formatyearpage}{theyear, themonth\optional{,
- width\optional{, css\optional{, encoding}}}}
-Return a year's calendar as a complete HTML page. \var{width}
-(defaulting to 3) specifies the number of months per row. \var{css}
-is the name for the cascading style sheet to be used. \constant{None}
-can be passed if no style sheet should be used. \var{encoding}
-specifies the encoding to be used for the output (defaulting
-to the system default encoding).
-\end{methoddesc}
-
-
-\begin{classdesc}{LocaleTextCalendar}{\optional{firstweekday\optional{, 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}
-\end{classdesc}
-
-
-\begin{classdesc}{LocaleHTMLCalendar}{\optional{firstweekday\optional{, 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}
-\end{classdesc}
-
-
-For simple text calendars this module provides the following functions.
-
-\begin{funcdesc}{setfirstweekday}{weekday}
-Sets the weekday (\code{0} is Monday, \code{6} is Sunday) to start
-each week. The values \constant{MONDAY}, \constant{TUESDAY},
-\constant{WEDNESDAY}, \constant{THURSDAY}, \constant{FRIDAY},
-\constant{SATURDAY}, and \constant{SUNDAY} are provided for
-convenience. For example, to set the first weekday to Sunday:
-
-\begin{verbatim}
-import calendar
-calendar.setfirstweekday(calendar.SUNDAY)
-\end{verbatim}
-\versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{firstweekday}{}
-Returns the current setting for the weekday to start each week.
-\versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{isleap}{year}
-Returns \constant{True} if \var{year} is a leap year, otherwise
-\constant{False}.
-\end{funcdesc}
-
-\begin{funcdesc}{leapdays}{y1, y2}
-Returns the number of leap years in the range
-[\var{y1}\ldots\var{y2}), where \var{y1} and \var{y2} are years.
-\versionchanged[This function didn't work for ranges spanning
- a century change in Python 1.5.2]{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{weekday}{year, month, day}
-Returns the day of the week (\code{0} is Monday) for \var{year}
-(\code{1970}--\ldots), \var{month} (\code{1}--\code{12}), \var{day}
-(\code{1}--\code{31}).
-\end{funcdesc}
-
-\begin{funcdesc}{weekheader}{n}
-Return a header containing abbreviated weekday names. \var{n} specifies
-the width in characters for one weekday.
-\end{funcdesc}
-
-\begin{funcdesc}{monthrange}{year, month}
-Returns weekday of first day of the month and number of days in month,
-for the specified \var{year} and \var{month}.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \function{setfirstweekday()}.
-\end{funcdesc}
-
-\begin{funcdesc}{prmonth}{theyear, themonth\optional{, w\optional{, l}}}
-Prints a month's calendar as returned by \function{month()}.
-\end{funcdesc}
-
-\begin{funcdesc}{month}{theyear, themonth\optional{, w\optional{, l}}}
-Returns a month's calendar in a multi-line string using the
-\method{formatmonth} of the \class{TextCalendar} class.
-\versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{prcal}{year\optional{, w\optional{, l\optional{c}}}}
-Prints the calendar for an entire year as returned by
-\function{calendar()}.
-\end{funcdesc}
-
-\begin{funcdesc}{calendar}{year\optional{, w\optional{, l\optional{c}}}}
-Returns a 3-column calendar for an entire year as a multi-line string
-using the \method{formatyear} of the \class{TextCalendar} class.
-\versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{timegm}{tuple}
-An unrelated but handy function that takes a time tuple such as
-returned by the \function{gmtime()} function in the \refmodule{time}
-module, and returns the corresponding \UNIX{} timestamp value, assuming
-an epoch of 1970, and the POSIX encoding. In fact,
-\function{time.gmtime()} and \function{timegm()} are each others' inverse.
-\versionadded{2.0}
-\end{funcdesc}
-
-The \module{calendar} module exports the following data attributes:
-
-\begin{datadesc}{day_name}
-An array that represents the days of the week in the
-current locale.
-\end{datadesc}
-
-\begin{datadesc}{day_abbr}
-An array that represents the abbreviated days of the week
-in the current locale.
-\end{datadesc}
-
-\begin{datadesc}{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
-\code{month_name[0]} is the empty string.
-\end{datadesc}
-
-\begin{datadesc}{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
-\code{month_abbr[0]} is the empty string.
-\end{datadesc}
-
-\begin{seealso}
- \seemodule{datetime}{Object-oriented interface to dates and times
- with similar functionality to the
- \refmodule{time} module.}
- \seemodule{time}{Low-level time related functions.}
-\end{seealso}
diff --git a/Doc/lib/libcfgparser.tex b/Doc/lib/libcfgparser.tex
deleted file mode 100644
index a41aee1..0000000
--- a/Doc/lib/libcfgparser.tex
+++ /dev/null
@@ -1,322 +0,0 @@
-\section{\module{ConfigParser} ---
- Configuration file parser}
-
-\declaremodule{standard}{ConfigParser}
-\modulesynopsis{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}
-
-This module defines the class \class{ConfigParser}.
-\indexii{.ini}{file}\indexii{configuration}{file}\index{ini file}
-\index{Windows ini file}
-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.
-
-\begin{notice}[warning]
- This library does \emph{not} interpret or write the value-type
- prefixes used in the Windows Registry extended version of INI syntax.
-\end{notice}
-
-The configuration file consists of sections, led by a
-\samp{[section]} header and followed by \samp{name: value} entries,
-with continuations in the style of \rfc{822}; \samp{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
-\code{DEFAULT} section. Additional defaults can be provided on
-initialization and retrieval. Lines beginning with \character{\#} or
-\character{;} are ignored and may be used to provide comments.
-
-For example:
-
-\begin{verbatim}
-[My Section]
-foodir: %(dir)s/whatever
-dir=frob
-\end{verbatim}
-
-would resolve the \samp{\%(dir)s} to the value of
-\samp{dir} (\samp{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 \method{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.
-
-\begin{classdesc}{RawConfigParser}{\optional{defaults\optional{, dict_type}}}
-The basic configuration object. When \var{defaults} is given, it is
-initialized into the dictionary of intrinsic defaults. When \var{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[\var{dict_type} was added]{2.6}
-\end{classdesc}
-
-\begin{classdesc}{ConfigParser}{\optional{defaults}}
-Derived class of \class{RawConfigParser} that implements the magical
-interpolation feature and adds optional arguments to the \method{get()}
-and \method{items()} methods. The values in \var{defaults} must be
-appropriate for the \samp{\%()s} string interpolation. Note that
-\var{__name__} is an intrinsic default; its value is the section name,
-and will override any value provided in \var{defaults}.
-
-All option names used in interpolation will be passed through the
-\method{optionxform()} method just like any other option name
-reference. For example, using the default implementation of
-\method{optionxform()} (which converts option names to lower case),
-the values \samp{foo \%(bar)s} and \samp{foo \%(BAR)s} are
-equivalent.
-\end{classdesc}
-
-\begin{classdesc}{SafeConfigParser}{\optional{defaults}}
-Derived class of \class{ConfigParser} that implements a more-sane
-variant of the magical interpolation feature. This implementation is
-more predictable as well.
-% XXX Need to explain what's safer/more predictable about it.
-New applications should prefer this version if they don't need to be
-compatible with older versions of Python.
-\versionadded{2.3}
-\end{classdesc}
-
-\begin{excdesc}{NoSectionError}
-Exception raised when a specified section is not found.
-\end{excdesc}
-
-\begin{excdesc}{DuplicateSectionError}
-Exception raised if \method{add_section()} is called with the name of
-a section that is already present.
-\end{excdesc}
-
-\begin{excdesc}{NoOptionError}
-Exception raised when a specified option is not found in the specified
-section.
-\end{excdesc}
-
-\begin{excdesc}{InterpolationError}
-Base class for exceptions raised when problems occur performing string
-interpolation.
-\end{excdesc}
-
-\begin{excdesc}{InterpolationDepthError}
-Exception raised when string interpolation cannot be completed because
-the number of iterations exceeds \constant{MAX_INTERPOLATION_DEPTH}.
-Subclass of \exception{InterpolationError}.
-\end{excdesc}
-
-\begin{excdesc}{InterpolationMissingOptionError}
-Exception raised when an option referenced from a value does not exist.
-Subclass of \exception{InterpolationError}.
-\versionadded{2.3}
-\end{excdesc}
-
-\begin{excdesc}{InterpolationSyntaxError}
-Exception raised when the source text into which substitutions are
-made does not conform to the required syntax.
-Subclass of \exception{InterpolationError}.
-\versionadded{2.3}
-\end{excdesc}
-
-\begin{excdesc}{MissingSectionHeaderError}
-Exception raised when attempting to parse a file which has no section
-headers.
-\end{excdesc}
-
-\begin{excdesc}{ParsingError}
-Exception raised when errors occur attempting to parse a file.
-\end{excdesc}
-
-\begin{datadesc}{MAX_INTERPOLATION_DEPTH}
-The maximum depth for recursive interpolation for \method{get()} when
-the \var{raw} parameter is false. This is relevant only for the
-\class{ConfigParser} class.
-\end{datadesc}
-
-
-\begin{seealso}
- \seemodule{shlex}{Support for a creating \UNIX{} shell-like
- mini-languages which can be used as an alternate
- format for application configuration files.}
-\end{seealso}
-
-
-\subsection{RawConfigParser Objects \label{RawConfigParser-objects}}
-
-\class{RawConfigParser} instances have the following methods:
-
-\begin{methoddesc}[RawConfigParser]{defaults}{}
-Return a dictionary containing the instance-wide defaults.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{sections}{}
-Return a list of the sections available; \code{DEFAULT} is not
-included in the list.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{add_section}{section}
-Add a section named \var{section} to the instance. If a section by
-the given name already exists, \exception{DuplicateSectionError} is
-raised.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{has_section}{section}
-Indicates whether the named section is present in the
-configuration. The \code{DEFAULT} section is not acknowledged.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{options}{section}
-Returns a list of options available in the specified \var{section}.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{has_option}{section, option}
-If the given section exists, and contains the given option,
-return \constant{True}; otherwise return \constant{False}.
-\versionadded{1.6}
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{read}{filenames}
-Attempt to read and parse a list of filenames, returning a list of filenames
-which were successfully parsed. If \var{filenames} is a string or
-Unicode string, it is treated as a single filename.
-If a file named in \var{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
-\method{readfp()} before calling \method{read()} for any optional
-files:
-
-\begin{verbatim}
-import ConfigParser, os
-
-config = ConfigParser.ConfigParser()
-config.readfp(open('defaults.cfg'))
-config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
-\end{verbatim}
-\versionchanged[Returns list of successfully parsed filenames]{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{readfp}{fp\optional{, filename}}
-Read and parse configuration data from the file or file-like object in
-\var{fp} (only the \method{readline()} method is used). If
-\var{filename} is omitted and \var{fp} has a \member{name} attribute,
-that is used for \var{filename}; the default is \samp{<???>}.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{get}{section, option}
-Get an \var{option} value for the named \var{section}.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{getint}{section, option}
-A convenience method which coerces the \var{option} in the specified
-\var{section} to an integer.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{getfloat}{section, option}
-A convenience method which coerces the \var{option} in the specified
-\var{section} to a floating point number.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{getboolean}{section, option}
-A convenience method which coerces the \var{option} in the specified
-\var{section} to a Boolean value. Note that the accepted values
-for the option are \code{"1"}, \code{"yes"}, \code{"true"}, and \code{"on"},
-which cause this method to return \code{True}, and \code{"0"}, \code{"no"},
-\code{"false"}, and \code{"off"}, which cause it to return \code{False}. These
-string values are checked in a case-insensitive manner. Any other value will
-cause it to raise \exception{ValueError}.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{items}{section}
-Return a list of \code{(\var{name}, \var{value})} pairs for each
-option in the given \var{section}.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{set}{section, option, value}
-If the given section exists, set the given option to the specified
-value; otherwise raise \exception{NoSectionError}. While it is
-possible to use \class{RawConfigParser} (or \class{ConfigParser} with
-\var{raw} parameters set to true) for \emph{internal} storage of
-non-string values, full functionality (including interpolation and
-output to files) can only be achieved using string values.
-\versionadded{1.6}
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{write}{fileobject}
-Write a representation of the configuration to the specified file
-object. This representation can be parsed by a future \method{read()}
-call.
-\versionadded{1.6}
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{remove_option}{section, option}
-Remove the specified \var{option} from the specified \var{section}.
-If the section does not exist, raise \exception{NoSectionError}.
-If the option existed to be removed, return \constant{True};
-otherwise return \constant{False}.
-\versionadded{1.6}
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{remove_section}{section}
-Remove the specified \var{section} from the configuration.
-If the section in fact existed, return \code{True}.
-Otherwise return \code{False}.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{optionxform}{option}
-Transforms the option name \var{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 \var{option}; subclasses may override this or client code
-can set an attribute of this name on instances to affect this
-behavior. Setting this to \function{str()}, for example, would make
-option names case sensitive.
-\end{methoddesc}
-
-
-\subsection{ConfigParser Objects \label{ConfigParser-objects}}
-
-The \class{ConfigParser} class extends some methods of the
-\class{RawConfigParser} interface, adding some optional arguments.
-
-\begin{methoddesc}[ConfigParser]{get}{section, option\optional{, raw\optional{, vars}}}
-Get an \var{option} value for the named \var{section}. All the
-\character{\%} interpolations are expanded in the return values, based
-on the defaults passed into the constructor, as well as the options
-\var{vars} provided, unless the \var{raw} argument is true.
-\end{methoddesc}
-
-\begin{methoddesc}[ConfigParser]{items}{section\optional{, raw\optional{, vars}}}
-Return a list of \code{(\var{name}, \var{value})} pairs for each
-option in the given \var{section}. Optional arguments have the
-same meaning as for the \method{get()} method.
-\versionadded{2.3}
-\end{methoddesc}
-
-
-\subsection{SafeConfigParser Objects \label{SafeConfigParser-objects}}
-
-The \class{SafeConfigParser} class implements the same extended
-interface as \class{ConfigParser}, with the following addition:
-
-\begin{methoddesc}[SafeConfigParser]{set}{section, option, value}
-If the given section exists, set the given option to the specified
-value; otherwise raise \exception{NoSectionError}. \var{value} must
-be a string (\class{str} or \class{unicode}); if not,
-\exception{TypeError} is raised.
-\versionadded{2.4}
-\end{methoddesc}
diff --git a/Doc/lib/libcgi.tex b/Doc/lib/libcgi.tex
deleted file mode 100644
index 1dd7e03..0000000
--- a/Doc/lib/libcgi.tex
+++ /dev/null
@@ -1,602 +0,0 @@
-\section{\module{cgi} ---
- Common Gateway Interface support.}
-\declaremodule{standard}{cgi}
-
-\modulesynopsis{Common Gateway Interface support, used to interpret
-forms in server-side scripts.}
-
-\indexii{WWW}{server}
-\indexii{CGI}{protocol}
-\indexii{HTTP}{protocol}
-\indexii{MIME}{headers}
-\index{URL}
-
-
-Support module for Common Gateway Interface (CGI) scripts.%
-\index{Common Gateway Interface}
-
-This module defines a number of utilities for use by CGI scripts
-written in Python.
-
-\subsection{Introduction}
-\nodename{cgi-intro}
-
-A CGI script is invoked by an HTTP server, usually to process user
-input submitted through an HTML \code{<FORM>} or \code{<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:
-
-\begin{verbatim}
-print "Content-Type: text/html" # HTML is following
-print # blank line, end of headers
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-print "<TITLE>CGI script output</TITLE>"
-print "<H1>This is my first CGI script</H1>"
-print "Hello, world!"
-\end{verbatim}
-
-\subsection{Using the cgi module}
-\nodename{Using the cgi module}
-
-Begin by writing \samp{import cgi}. Do not use \samp{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:
-
-\begin{verbatim}
-import cgitb; cgitb.enable()
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-import cgitb; cgitb.enable(display=0, logdir="/tmp")
-\end{verbatim}
-
-It's very helpful to use this feature during script development.
-The reports produced by \refmodule{cgitb} provide information that
-can save you a lot of time in tracking down bugs. You can always
-remove the \code{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
-\method{has_key()} and \method{keys()}. The built-in \function{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 \var{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 \code{name} and \code{addr} are both
-set to a non-empty string:
-
-\begin{verbatim}
-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...
-\end{verbatim}
-
-Here the fields, accessed through \samp{form[\var{key}]}, are
-themselves instances of \class{FieldStorage} (or
-\class{MiniFieldStorage}, depending on the form encoding).
-The \member{value} attribute of the instance yields the string value
-of the field. The \method{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 \samp{form[\var{key}]} is not a
-\class{FieldStorage} or \class{MiniFieldStorage}
-instance but a list of such instances. Similarly, in this situation,
-\samp{form.getvalue(\var{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 \function{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:
-
-\begin{verbatim}
-value = form.getlist("username")
-usernames = ",".join(value)
-\end{verbatim}
-
-If a field represents an uploaded file, accessing the value via the
-\member{value} attribute or the \function{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 \member{filename}
-attribute or the \member{file} attribute. You can then read the data at
-leisure from the \member{file} attribute:
-
-\begin{verbatim}
-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
-\end{verbatim}
-
-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 \member{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
-\member{list}, \member{file}, and \member{filename} attributes are
-always \code{None}.
-
-
-\subsection{Higher Level Interface}
-
-\versionadded{2.2} % XXX: Is this true ?
-
-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.
-
-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:
-
-\begin{verbatim}
-item = form.getvalue("item")
-if isinstance(item, list):
- # The user is requesting more than one item.
-else:
- # The user is requesting only one item.
-\end{verbatim}
-
-This situation is common for example when a form contains a group of
-multiple checkboxes with the same name:
-
-\begin{verbatim}
-<input type="checkbox" name="item" value="1" />
-<input type="checkbox" name="item" value="2" />
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-user = form.getvalue("user").upper()
-\end{verbatim}
-
-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 \samp{user=foo} pair to the query string,
-then the script would crash, because in this situation the
-\code{getvalue("user")} method call returns a list instead of a
-string. Calling the \method{toupper()} method on a list is not valid
-(since lists do not have a method of this name) and results in an
-\exception{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 \method{getfirst()}
-and \method{getlist()} provided by this higher level interface.
-
-\begin{methoddesc}[FieldStorage]{getfirst}{name\optional{, default}}
- This method always returns only one value associated with form field
- \var{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.\footnote{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.} If no such form
- field or value exists then the method returns the value specified by
- the optional parameter \var{default}. This parameter defaults to
- \code{None} if not specified.
-\end{methoddesc}
-
-\begin{methoddesc}[FieldStorage]{getlist}{name}
- This method always returns a list of values associated with form
- field \var{name}. The method returns an empty list if no such form
- field or value exists for \var{name}. It returns a list consisting
- of one item if only one such value exists.
-\end{methoddesc}
-
-Using these methods you can write nice compact code:
-
-\begin{verbatim}
-import cgi
-form = cgi.FieldStorage()
-user = form.getfirst("user", "").upper() # This way it's safe.
-for item in form.getlist("item"):
- do_something(item)
-\end{verbatim}
-
-
-\subsection{Old classes}
-
-These classes, present in earlier versions of the \module{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.
-
-
-\subsection{Functions}
-\nodename{Functions in cgi module}
-
-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.
-
-\begin{funcdesc}{parse}{fp\optional{, keep_blank_values\optional{,
- strict_parsing}}}
- Parse a query in the environment or from a file (the file defaults
- to \code{sys.stdin}). The \var{keep_blank_values} and
- \var{strict_parsing} parameters are passed to \function{parse_qs()}
- unchanged.
-\end{funcdesc}
-
-\begin{funcdesc}{parse_qs}{qs\optional{, keep_blank_values\optional{,
- 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 \var{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 \var{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 \exception{ValueError}
-exception.
-
-Use the \function{\refmodule{urllib}.urlencode()} function to convert
-such dictionaries into query strings.
-
-\end{funcdesc}
-
-\begin{funcdesc}{parse_qsl}{qs\optional{, keep_blank_values\optional{,
- 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 \var{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 \var{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 \exception{ValueError}
-exception.
-
-Use the \function{\refmodule{urllib}.urlencode()} function to convert
-such lists of pairs into query strings.
-\end{funcdesc}
-
-\begin{funcdesc}{parse_multipart}{fp, pdict}
-Parse input of type \mimetype{multipart/form-data} (for
-file uploads). Arguments are \var{fp} for the input file and
-\var{pdict} for a dictionary containing other parameters in
-the \mailheader{Content-Type} header.
-
-Returns a dictionary just like \function{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.
-\end{funcdesc}
-
-\begin{funcdesc}{parse_header}{string}
-Parse a MIME header (such as \mailheader{Content-Type}) into a main
-value and a dictionary of parameters.
-\end{funcdesc}
-
-\begin{funcdesc}{test}{}
-Robust test CGI script, usable as main program.
-Writes minimal HTTP headers and formats all information provided to
-the script in HTML form.
-\end{funcdesc}
-
-\begin{funcdesc}{print_environ}{}
-Format the shell environment in HTML.
-\end{funcdesc}
-
-\begin{funcdesc}{print_form}{form}
-Format a form in HTML.
-\end{funcdesc}
-
-\begin{funcdesc}{print_directory}{}
-Format the current directory in HTML.
-\end{funcdesc}
-
-\begin{funcdesc}{print_environ_usage}{}
-Print a list of useful (used by CGI) environment variables in
-HTML.
-\end{funcdesc}
-
-\begin{funcdesc}{escape}{s\optional{, quote}}
-Convert the characters
-\character{\&}, \character{<} and \character{>} in string \var{s} to
-HTML-safe sequences. Use this if you need to display text that might
-contain such characters in HTML. If the optional flag \var{quote} is
-true, the quotation mark character (\character{"}) is also translated;
-this helps for inclusion in an HTML attribute value, as in \code{<A
-HREF="...">}. If the value to be quoted might include single- or
-double-quote characters, or both, consider using the
-\function{quoteattr()} function in the \refmodule{xml.sax.saxutils}
-module instead.
-\end{funcdesc}
-
-
-\subsection{Caring about security \label{cgi-security}}
-
-\indexii{CGI}{security}
-
-There's one important rule: if you invoke an external program (via the
-\function{os.system()} or \function{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.
-
-
-\subsection{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 \code{0755} octal (use \samp{chmod 0755
-\var{filename}}). Make sure that the first line of the script contains
-\code{\#!} starting in column 1 followed by the pathname of the Python
-interpreter, for instance:
-
-\begin{verbatim}
-#!/usr/local/bin/python
-\end{verbatim}
-
-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 \code{0644} for readable and \code{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:
-
-\begin{verbatim}
-import sys
-sys.path.insert(0, "/usr/home/joe/lib/python")
-sys.path.insert(0, "/usr/local/lib/python")
-\end{verbatim}
-
-(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).
-
-
-\subsection{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.
-
-
-\subsection{Debugging CGI scripts} \indexii{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:
-
-\begin{verbatim}
-http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
-\end{verbatim}
-
-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 \module{cgi} module's
-\function{test()} function from your script: replace its main code
-with the single statement
-
-\begin{verbatim}
-cgi.test()
-\end{verbatim}
-
-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
-\emph{some} code, you can easily send tracebacks to the Web browser
-using the \refmodule{cgitb} module. If you haven't done so already,
-just add the line:
-
-\begin{verbatim}
-import cgitb; cgitb.enable()
-\end{verbatim}
-
-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
-\refmodule{cgitb} module, you can use an even more robust approach
-(which only uses built-in modules):
-
-\begin{verbatim}
-import sys
-sys.stderr = sys.stdout
-print "Content-Type: text/plain"
-print
-...your code here...
-\end{verbatim}
-
-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.
-
-
-\subsection{Common problems and solutions}
-
-\begin{itemize}
-\item 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.
-
-\item Check the installation instructions above.
-
-\item Check the HTTP server's log files. (\samp{tail -f logfile} in a
-separate window may be useful!)
-
-\item Always check a script for syntax errors first, by doing something
-like \samp{python script.py}.
-
-\item If your script does not have any syntax errors, try adding
-\samp{import cgitb; cgitb.enable()} to the top of the script.
-
-\item 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.
-
-\item 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 \samp{suexec} feature.
-
-\item 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.
-\end{itemize}
-
diff --git a/Doc/lib/libcgihttp.tex b/Doc/lib/libcgihttp.tex
deleted file mode 100644
index df0728e..0000000
--- a/Doc/lib/libcgihttp.tex
+++ /dev/null
@@ -1,70 +0,0 @@
-\section{\module{CGIHTTPServer} ---
- CGI-capable HTTP request handler}
-
-
-\declaremodule{standard}{CGIHTTPServer}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{This module provides a request handler for HTTP servers
- which can run CGI scripts.}
-
-
-The \module{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 \module{CGIHTTPServer} module defines the following class:
-
-\begin{classdesc}{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 \function{do_GET()} and \function{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
-\code{cgi_directories} path.
-\end{classdesc}
-
-The \class{CGIHTTPRequestHandler} defines the following data member:
-
-\begin{memberdesc}{cgi_directories}
-This defaults to \code{['/cgi-bin', '/htbin']} and describes
-directories to treat as containing CGI scripts.
-\end{memberdesc}
-
-The \class{CGIHTTPRequestHandler} defines the following methods:
-
-\begin{methoddesc}{do_POST}{}
-This method serves the \code{'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.
-\end{methoddesc}
-
-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 \function{test()}
-function.
-
-
-\begin{seealso}
- \seemodule{BaseHTTPServer}{Base class implementation for Web server
- and request handler.}
-\end{seealso}
diff --git a/Doc/lib/libcgitb.tex b/Doc/lib/libcgitb.tex
deleted file mode 100644
index ca9959f..0000000
--- a/Doc/lib/libcgitb.tex
+++ /dev/null
@@ -1,67 +0,0 @@
-\section{\module{cgitb} ---
- Traceback manager for CGI scripts}
-
-\declaremodule{standard}{cgitb}
-\modulesynopsis{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{CGI!exceptions}
-\index{CGI!tracebacks}
-\index{exceptions!in CGI scripts}
-\index{tracebacks!in CGI scripts}
-
-The \module{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:
-
-\begin{verbatim}
-import cgitb; cgitb.enable()
-\end{verbatim}
-
-The options to the \function{enable()} function control whether the
-report is displayed in the browser and whether the report is logged
-to a file for later analysis.
-
-
-\begin{funcdesc}{enable}{\optional{display\optional{, logdir\optional{,
- context\optional{, format}}}}}
- This function causes the \module{cgitb} module to take over the
- interpreter's default handling for exceptions by setting the
- value of \member{\refmodule{sys}.excepthook}.
- \withsubitem{(in module sys)}{\ttindex{excepthook()}}
-
- The optional argument \var{display} defaults to \code{1} and can be set
- to \code{0} to suppress sending the traceback to the browser.
- If the argument \var{logdir} is present, the traceback reports are
- written to files. The value of \var{logdir} should be a directory
- where these files will be placed.
- The optional argument \var{context} is the number of lines of
- context to display around the current line of source code in the
- traceback; this defaults to \code{5}.
- If the optional argument \var{format} is \code{"html"}, the output is
- formatted as HTML. Any other value forces plain text output. The default
- value is \code{"html"}.
-\end{funcdesc}
-
-\begin{funcdesc}{handler}{\optional{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 \module{cgitb}. The optional \var{info} argument
- should be a 3-tuple containing an exception type, exception
- value, and traceback object, exactly like the tuple returned by
- \function{\refmodule{sys}.exc_info()}. If the \var{info} argument
- is not supplied, the current exception is obtained from
- \function{\refmodule{sys}.exc_info()}.
-\end{funcdesc}
diff --git a/Doc/lib/libchunk.tex b/Doc/lib/libchunk.tex
deleted file mode 100644
index 8e2a494..0000000
--- a/Doc/lib/libchunk.tex
+++ /dev/null
@@ -1,111 +0,0 @@
-\section{\module{chunk} ---
- Read IFF chunked data}
-
-\declaremodule{standard}{chunk}
-\modulesynopsis{Module to read IFF chunks.}
-\moduleauthor{Sjoerd Mullender}{sjoerd@acm.org}
-\sectionauthor{Sjoerd Mullender}{sjoerd@acm.org}
-
-
-
-This module provides an interface for reading files that use EA IFF 85
-chunks.\footnote{``EA IFF 85'' Standard for Interchange Format Files,
-Jerry Morrison, Electronic Arts, January 1985.} This format is used
-in at least the Audio\index{Audio Interchange File
-Format}\index{AIFF}\index{AIFF-C} Interchange File Format
-(AIFF/AIFF-C) and the Real\index{Real Media File Format} Media File
-Format\index{RMFF} (RMFF). The WAVE audio file format is closely
-related and can also be read using this module.
-
-A chunk has the following structure:
-
-\begin{tableiii}{c|c|l}{textrm}{Offset}{Length}{Contents}
- \lineiii{0}{4}{Chunk ID}
- \lineiii{4}{4}{Size of chunk in big-endian byte order, not including the
- header}
- \lineiii{8}{\var{n}}{Data bytes, where \var{n} is the size given in
- the preceding field}
- \lineiii{8 + \var{n}}{0 or 1}{Pad byte needed if \var{n} is odd and
- chunk alignment is used}
-\end{tableiii}
-
-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
-\exception{EOFError} exception.
-
-\begin{classdesc}{Chunk}{file\optional{, align, bigendian, inclheader}}
-Class which represents a chunk. The \var{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 \method{read()}. If the
-methods \method{seek()} and \method{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 \var{align} is true, chunks are
-assumed to be aligned on 2-byte boundaries. If \var{align} is
-false, no alignment is assumed. The default value is true. If the
-optional argument \var{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 \var{inclheader}
-is true, the size given in the chunk header includes the size of the
-header. The default value is false.
-\end{classdesc}
-
-A \class{Chunk} object supports the following methods:
-
-\begin{methoddesc}{getname}{}
-Returns the name (ID) of the chunk. This is the first 4 bytes of the
-chunk.
-\end{methoddesc}
-
-\begin{methoddesc}{getsize}{}
-Returns the size of the chunk.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
-Close and skip to the end of the chunk. This does not close the
-underlying file.
-\end{methoddesc}
-
-The remaining methods will raise \exception{IOError} if called after
-the \method{close()} method has been called.
-
-\begin{methoddesc}{isatty}{}
-Returns \code{False}.
-\end{methoddesc}
-
-\begin{methoddesc}{seek}{pos\optional{, whence}}
-Set the chunk's current position. The \var{whence} argument is
-optional and defaults to \code{0} (absolute file positioning); other
-values are \code{1} (seek relative to the current position) and
-\code{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.
-\end{methoddesc}
-
-\begin{methoddesc}{tell}{}
-Return the current position into the chunk.
-\end{methoddesc}
-
-\begin{methoddesc}{read}{\optional{size}}
-Read at most \var{size} bytes from the chunk (less if the read hits
-the end of the chunk before obtaining \var{size} bytes). If the
-\var{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.
-\end{methoddesc}
-
-\begin{methoddesc}{skip}{}
-Skip to the end of the chunk. All further calls to \method{read()}
-for the chunk will return \code{''}. 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.
-\end{methoddesc}
diff --git a/Doc/lib/libcmath.tex b/Doc/lib/libcmath.tex
deleted file mode 100644
index f8aa45b..0000000
--- a/Doc/lib/libcmath.tex
+++ /dev/null
@@ -1,149 +0,0 @@
-\section{\module{cmath} ---
- Mathematical functions for complex numbers}
-
-\declaremodule{builtin}{cmath}
-\modulesynopsis{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
-\method{__complex__} or a \method{__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:
-
-\begin{funcdesc}{acos}{x}
-Return the arc cosine of \var{x}.
-There are two branch cuts:
-One extends right from 1 along the real axis to \infinity, continuous
-from below.
-The other extends left from -1 along the real axis to -\infinity,
-continuous from above.
-\end{funcdesc}
-
-\begin{funcdesc}{acosh}{x}
-Return the hyperbolic arc cosine of \var{x}.
-There is one branch cut, extending left from 1 along the real axis
-to -\infinity, continuous from above.
-\end{funcdesc}
-
-\begin{funcdesc}{asin}{x}
-Return the arc sine of \var{x}.
-This has the same branch cuts as \function{acos()}.
-\end{funcdesc}
-
-\begin{funcdesc}{asinh}{x}
-Return the hyperbolic arc sine of \var{x}.
-There are two branch cuts, extending left from \plusminus\code{1j} to
-\plusminus-\infinity\code{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 \code{1j} up to \infinity\code{j} and continuous from the
-right, and one from -\code{1j} down to -\infinity\code{j} and
-continuous from the left.
-\end{funcdesc}
-
-\begin{funcdesc}{atan}{x}
-Return the arc tangent of \var{x}.
-There are two branch cuts:
-One extends from \code{1j} along the imaginary axis to
-\infinity\code{j}, continuous from the left.
-The other extends from -\code{1j} along the imaginary axis to
--\infinity\code{j}, continuous from the left.
-(This should probably be changed so the upper cut becomes continuous
-from the other side.)
-\end{funcdesc}
-
-\begin{funcdesc}{atanh}{x}
-Return the hyperbolic arc tangent of \var{x}.
-There are two branch cuts:
-One extends from 1 along the real axis to \infinity, continuous
-from above.
-The other extends from -1 along the real axis to -\infinity,
-continuous from above.
-(This should probably be changed so the right cut becomes continuous from
-the other side.)
-\end{funcdesc}
-
-\begin{funcdesc}{cos}{x}
-Return the cosine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{cosh}{x}
-Return the hyperbolic cosine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{exp}{x}
-Return the exponential value \code{e**\var{x}}.
-\end{funcdesc}
-
-\begin{funcdesc}{log}{x\optional{, base}}
-Returns the logarithm of \var{x} to the given \var{base}.
-If the \var{base} is not specified, returns the natural logarithm of \var{x}.
-There is one branch cut, from 0 along the negative real axis to
--\infinity, continuous from above.
-\versionchanged[\var{base} argument added]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{log10}{x}
-Return the base-10 logarithm of \var{x}.
-This has the same branch cut as \function{log()}.
-\end{funcdesc}
-
-\begin{funcdesc}{sin}{x}
-Return the sine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{sinh}{x}
-Return the hyperbolic sine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{sqrt}{x}
-Return the square root of \var{x}.
-This has the same branch cut as \function{log()}.
-\end{funcdesc}
-
-\begin{funcdesc}{tan}{x}
-Return the tangent of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{tanh}{x}
-Return the hyperbolic tangent of \var{x}.
-\end{funcdesc}
-
-The module also defines two mathematical constants:
-
-\begin{datadesc}{pi}
-The mathematical constant \emph{pi}, as a real.
-\end{datadesc}
-
-\begin{datadesc}{e}
-The mathematical constant \emph{e}, as a real.
-\end{datadesc}
-
-Note that the selection of functions is similar, but not identical, to
-that in module \refmodule{math}\refbimodindex{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
-\code{math.sqrt(-1)} raise an exception than return a complex number.
-Also note that the functions defined in \module{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:
-
-\begin{seealso}
- \seetext{Kahan, W: Branch cuts for complex elementary functions;
- or, Much ado about nothing's sign bit. In Iserles, A.,
- and Powell, M. (eds.), \citetitle{The state of the art in
- numerical analysis}. Clarendon Press (1987) pp165-211.}
-\end{seealso}
diff --git a/Doc/lib/libcmd.tex b/Doc/lib/libcmd.tex
deleted file mode 100644
index 810f19c..0000000
--- a/Doc/lib/libcmd.tex
+++ /dev/null
@@ -1,198 +0,0 @@
-\section{\module{cmd} ---
- Support for line-oriented command interpreters}
-
-\declaremodule{standard}{cmd}
-\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-\modulesynopsis{Build line-oriented command interpreters.}
-
-
-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.
-
-\begin{classdesc}{Cmd}{\optional{completekey\optional{,
- stdin\optional{, 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 \var{completekey} is the \refmodule{readline} name
-of a completion key; it defaults to \kbd{Tab}. If \var{completekey} is
-not \constant{None} and \refmodule{readline} is available, command completion
-is done automatically.
-
-The optional arguments \var{stdin} and \var{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 \var{sys.stdin} and \var{sys.stdout}.
-
-\versionchanged[The \var{stdin} and \var{stdout} parameters were added]{2.3}
-\end{classdesc}
-
-\subsection{Cmd Objects}
-\label{Cmd-objects}
-
-A \class{Cmd} instance has the following methods:
-
-\begin{methoddesc}[Cmd]{cmdloop}{\optional{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 \member{intro} class member).
-
-If the \refmodule{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 \code{'EOF'}.
-
-An interpreter instance will recognize a command name \samp{foo} if
-and only if it has a method \method{do_foo()}. As a special case,
-a line beginning with the character \character{?} is dispatched to
-the method \method{do_help()}. As another special case, a line
-beginning with the character \character{!} is dispatched to the
-method \method{do_shell()} (if such a method is defined).
-
-This method will return when the \method{postcmd()} method returns a
-true value. The \var{stop} argument to \method{postcmd()} is the
-return value from the command's corresponding \method{do_*()} method.
-
-If completion is enabled, completing commands will be done
-automatically, and completing of commands args is done by calling
-\method{complete_foo()} with arguments \var{text}, \var{line},
-\var{begidx}, and \var{endidx}. \var{text} is the string prefix we
-are attempting to match: all returned matches must begin with it.
-\var{line} is the current input line with leading whitespace removed,
-\var{begidx} and \var{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 \method{do_help()}.
-This method, called with an argument \code{'bar'}, invokes the
-corresponding method \method{help_bar()}. With no argument,
-\method{do_help()} lists all available help topics (that is, all
-commands with corresponding \method{help_*()} methods), and also lists
-any undocumented commands.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \method{precmd()} and \method{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 \method{do_*()} method for the command \var{str}, the return
-value of that method is returned, otherwise the return value from the
-\method{default()} method is returned.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{methoddesc}[Cmd]{completedefault}{text, line, begidx, endidx}
-Method called to complete an input line when no command-specific
-\method{complete_*()} method is available. By default, it returns an
-empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[Cmd]{precmd}{line}
-Hook method executed just before the command line \var{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 \method{onecmd()} method; the \method{precmd()}
-implementation may re-write the command or simply return \var{line}
-unchanged.
-\end{methoddesc}
-
-\begin{methoddesc}[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. \var{line} is the command line which was executed, and
-\var{stop} is a flag which indicates whether execution will be
-terminated after the call to \method{postcmd()}; this will be the
-return value of the \method{onecmd()} method. The return value of
-this method will be used as the new value for the internal flag which
-corresponds to \var{stop}; returning false will cause interpretation
-to continue.
-\end{methoddesc}
-
-\begin{methoddesc}[Cmd]{preloop}{}
-Hook method executed once when \method{cmdloop()} is called. This
-method is a stub in \class{Cmd}; it exists to be overridden by
-subclasses.
-\end{methoddesc}
-
-\begin{methoddesc}[Cmd]{postloop}{}
-Hook method executed once when \method{cmdloop()} is about to return.
-This method is a stub in \class{Cmd}; it exists to be overridden by
-subclasses.
-\end{methoddesc}
-
-Instances of \class{Cmd} subclasses have some public instance variables:
-
-\begin{memberdesc}[Cmd]{prompt}
-The prompt issued to solicit input.
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{identchars}
-The string of characters accepted for the command prefix.
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{lastcmd}
-The last nonempty command prefix seen.
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{intro}
-A string to issue as an intro or banner. May be overridden by giving
-the \method{cmdloop()} method an argument.
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{doc_header}
-The header to issue if the help output has a section for documented
-commands.
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{misc_header}
-The header to issue if the help output has a section for miscellaneous
-help topics (that is, there are \method{help_*()} methods without
-corresponding \method{do_*()} methods).
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{undoc_header}
-The header to issue if the help output has a section for undocumented
-commands (that is, there are \method{do_*()} methods without
-corresponding \method{help_*()} methods).
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{ruler}
-The character used to draw separator lines under the help-message
-headers. If empty, no ruler line is drawn. It defaults to
-\character{=}.
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{use_rawinput}
-A flag, defaulting to true. If true, \method{cmdloop()} uses
-\function{input()} to display a prompt and read the next command;
-if false, \method{sys.stdout.write()} and
-\method{sys.stdin.readline()} are used. (This means that by
-importing \refmodule{readline}, on systems that support it, the
-interpreter will automatically support \program{Emacs}-like line editing
-and command-history keystrokes.)
-\end{memberdesc}
diff --git a/Doc/lib/libcmp.tex b/Doc/lib/libcmp.tex
deleted file mode 100644
index 489efee..0000000
--- a/Doc/lib/libcmp.tex
+++ /dev/null
@@ -1,36 +0,0 @@
-\section{\module{cmp} ---
- File comparisons}
-
-\declaremodule{standard}{cmp}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Compare files very efficiently.}
-
-\deprecated{1.6}{Use the \refmodule{filecmp} module instead.}
-
-The \module{cmp} module defines a function to compare files, taking all
-sort of short-cuts to make it a highly efficient operation.
-
-The \module{cmp} module defines the following function:
-
-\begin{funcdesc}{cmp}{f1, f2}
-Compare two files given as names. The following tricks are used to
-optimize the comparisons:
-
-\begin{itemize}
- \item Files with identical type, size and mtime are assumed equal.
- \item Files with different type or size are never equal.
- \item The module only compares files it already compared if their
- signature (type, size and mtime) changed.
- \item No external programs are called.
-\end{itemize}
-\end{funcdesc}
-
-Example:
-
-\begin{verbatim}
->>> import cmp
->>> cmp.cmp('libundoc.tex', 'libundoc.tex')
-1
->>> cmp.cmp('libundoc.tex', 'lib.tex')
-0
-\end{verbatim}
diff --git a/Doc/lib/libcmpcache.tex b/Doc/lib/libcmpcache.tex
deleted file mode 100644
index 8991477..0000000
--- a/Doc/lib/libcmpcache.tex
+++ /dev/null
@@ -1,21 +0,0 @@
-\section{\module{cmpcache} ---
- Efficient file comparisons}
-
-\declaremodule{standard}{cmpcache}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Compare files very efficiently.}
-
-\deprecated{1.6}{Use the \refmodule{filecmp} module instead.}
-
-The \module{cmpcache} module provides an identical interface and similar
-functionality as the \refmodule{cmp} module, but can be a bit more efficient
-as it uses \function{statcache.stat()} instead of \function{os.stat()}
-(see the \refmodule{statcache} module for information on the
-difference).
-
-\note{Using the \refmodule{statcache} module to provide
-\function{stat()} information results in trashing the cache
-invalidation mechanism: results are not as reliable. To ensure
-``current'' results, use \function{cmp.cmp()} instead of the version
-defined in this module, or use \function{statcache.forget()} to
-invalidate the appropriate entries.}
diff --git a/Doc/lib/libcode.tex b/Doc/lib/libcode.tex
deleted file mode 100644
index 8e14b02..0000000
--- a/Doc/lib/libcode.tex
+++ /dev/null
@@ -1,173 +0,0 @@
-\section{\module{code} ---
- Interpreter base classes}
-\declaremodule{standard}{code}
-
-\modulesynopsis{Base classes for interactive Python interpreters.}
-
-
-The \code{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.
-
-
-\begin{classdesc}{InteractiveInterpreter}{\optional{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 \var{locals} argument specifies the dictionary in
-which code will be executed; it defaults to a newly created
-dictionary with key \code{'__name__'} set to \code{'__console__'}
-and key \code{'__doc__'} set to \code{None}.
-\end{classdesc}
-
-\begin{classdesc}{InteractiveConsole}{\optional{locals\optional{, filename}}}
-Closely emulate the behavior of the interactive Python interpreter.
-This class builds on \class{InteractiveInterpreter} and adds
-prompting using the familiar \code{sys.ps1} and \code{sys.ps2}, and
-input buffering.
-\end{classdesc}
-
-
-\begin{funcdesc}{interact}{\optional{banner\optional{,
- readfunc\optional{, local}}}}
-Convenience function to run a read-eval-print loop. This creates a
-new instance of \class{InteractiveConsole} and sets \var{readfunc}
-to be used as the \method{raw_input()} method, if provided. If
-\var{local} is provided, it is passed to the
-\class{InteractiveConsole} constructor for use as the default
-namespace for the interpreter loop. The \method{interact()} method
-of the instance is then run with \var{banner} passed as the banner
-to use, if provided. The console object is discarded after use.
-\end{funcdesc}
-
-\begin{funcdesc}{compile_command}{source\optional{,
- filename\optional{, 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
-\emph{almost} always makes the same decision as the real interpreter
-main loop.
-
-\var{source} is the source string; \var{filename} is the optional
-filename from which source was read, defaulting to \code{'<input>'};
-and \var{symbol} is the optional grammar start symbol, which should
-be either \code{'single'} (the default) or \code{'eval'}.
-
-Returns a code object (the same as \code{compile(\var{source},
-\var{filename}, \var{symbol})}) if the command is complete and
-valid; \code{None} if the command is incomplete; raises
-\exception{SyntaxError} if the command is complete and contains a
-syntax error, or raises \exception{OverflowError} or
-\exception{ValueError} if the command contains an invalid literal.
-\end{funcdesc}
-
-
-\subsection{Interactive Interpreter Objects
- \label{interpreter-objects}}
-
-\begin{methoddesc}[InteractiveInterpreter]{runsource}{source\optional{, filename\optional{, symbol}}}
-Compile and run some source in the interpreter.
-Arguments are the same as for \function{compile_command()}; the
-default for \var{filename} is \code{'<input>'}, and for
-\var{symbol} is \code{'single'}. One several things can happen:
-
-\begin{itemize}
-\item
-The input is incorrect; \function{compile_command()} raised an
-exception (\exception{SyntaxError} or \exception{OverflowError}). A
-syntax traceback will be printed by calling the
-\method{showsyntaxerror()} method. \method{runsource()} returns
-\code{False}.
-
-\item
-The input is incomplete, and more input is required;
-\function{compile_command()} returned \code{None}.
-\method{runsource()} returns \code{True}.
-
-\item
-The input is complete; \function{compile_command()} returned a code
-object. The code is executed by calling the \method{runcode()} (which
-also handles run-time exceptions, except for \exception{SystemExit}).
-\method{runsource()} returns \code{False}.
-\end{itemize}
-
-The return value can be used to decide whether to use
-\code{sys.ps1} or \code{sys.ps2} to prompt the next line.
-\end{methoddesc}
-
-\begin{methoddesc}[InteractiveInterpreter]{runcode}{code}
-Execute a code object.
-When an exception occurs, \method{showtraceback()} is called to
-display a traceback. All exceptions are caught except
-\exception{SystemExit}, which is allowed to propagate.
-
-A note about \exception{KeyboardInterrupt}: this exception may occur
-elsewhere in this code, and may not always be caught. The caller
-should be prepared to deal with it.
-\end{methoddesc}
-
-\begin{methoddesc}[InteractiveInterpreter]{showsyntaxerror}{\optional{filename}}
-Display the syntax error that just occurred. This does not display
-a stack trace because there isn't one for syntax errors.
-If \var{filename} is given, it is stuffed into the exception instead
-of the default filename provided by Python's parser, because it
-always uses \code{'<string>'} when reading from a string.
-The output is written by the \method{write()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \method{write()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[InteractiveInterpreter]{write}{data}
-Write a string to the standard error stream (\code{sys.stderr}).
-Derived classes should override this to provide the appropriate output
-handling as needed.
-\end{methoddesc}
-
-
-\subsection{Interactive Console Objects
- \label{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.
-
-\begin{methoddesc}[InteractiveConsole]{interact}{\optional{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!).
-\end{methoddesc}
-
-\begin{methoddesc}[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
-\method{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 \code{True} if more input is required,
-\code{False} if the line was dealt with in some way (this is the same as
-\method{runsource()}).
-\end{methoddesc}
-
-\begin{methoddesc}[InteractiveConsole]{resetbuffer}{}
-Remove any unhandled source text from the input buffer.
-\end{methoddesc}
-
-\begin{methoddesc}[InteractiveConsole]{raw_input}{\optional{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,
-\exception{EOFError} is raised. The base implementation reads from
-\code{sys.stdin}; a subclass may replace this
-with a different implementation.
-\end{methoddesc}
diff --git a/Doc/lib/libcodecs.tex b/Doc/lib/libcodecs.tex
deleted file mode 100644
index ee141d9..0000000
--- a/Doc/lib/libcodecs.tex
+++ /dev/null
@@ -1,1341 +0,0 @@
-\section{\module{codecs} ---
- Codec registry and base classes}
-
-\declaremodule{standard}{codecs}
-\modulesynopsis{Encode and decode data and streams.}
-\moduleauthor{Marc-Andre Lemburg}{mal@lemburg.com}
-\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\index{Unicode}
-\index{Codecs}
-\indexii{Codecs}{encode}
-\indexii{Codecs}{decode}
-\index{streams}
-\indexii{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:
-
-\begin{funcdesc}{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:
-
-\begin{itemize}
- \item \code{name} The name of the encoding;
- \item \code{encoder} The stateless encoding function;
- \item \code{decoder} The stateless decoding function;
- \item \code{incrementalencoder} An incremental encoder class or factory function;
- \item \code{incrementaldecoder} An incremental decoder class or factory function;
- \item \code{streamwriter} A stream writer class or factory function;
- \item \code{streamreader} A stream reader class or factory function.
-\end{itemize}
-
-The various functions or classes take the following arguments:
-
- \var{encoder} and \var{decoder}: These must be functions or methods
- which have the same interface as the
- \method{encode()}/\method{decode()} methods of Codec instances (see
- Codec Interface). The functions/methods are expected to work in a
- stateless mode.
-
- \var{incrementalencoder} and \var{incrementalencoder}: These have to be
- factory functions providing the following interface:
-
- \code{factory(\var{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.
-
- \var{streamreader} and \var{streamwriter}: These have to be
- factory functions providing the following interface:
-
- \code{factory(\var{stream}, \var{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 \code{'strict'} (raise an exception
- in case of an encoding error), \code{'replace'} (replace malformed
- data with a suitable replacement marker, such as \character{?}),
- \code{'ignore'} (ignore malformed data and continue without further
- notice), \code{'xmlcharrefreplace'} (replace with the appropriate XML
- character reference (for encoding only)) and \code{'backslashreplace'}
- (replace with backslashed escape sequences (for encoding only)) as
- well as any other error handling name defined via
- \function{register_error()}.
-
-In case a search function cannot find a given encoding, it should
-return \code{None}.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \exception{LookupError} is raised. Otherwise, the
-\class{CodecInfo} object is stored in the cache and returned to the caller.
-\end{funcdesc}
-
-To simplify access to the various codecs, the module provides these
-additional functions which use \function{lookup()} for the codec
-lookup:
-
-\begin{funcdesc}{getencoder}{encoding}
-Look up the codec for the given encoding and return its encoder
-function.
-
-Raises a \exception{LookupError} in case the encoding cannot be found.
-\end{funcdesc}
-
-\begin{funcdesc}{getdecoder}{encoding}
-Look up the codec for the given encoding and return its decoder
-function.
-
-Raises a \exception{LookupError} in case the encoding cannot be found.
-\end{funcdesc}
-
-\begin{funcdesc}{getincrementalencoder}{encoding}
-Look up the codec for the given encoding and return its incremental encoder
-class or factory function.
-
-Raises a \exception{LookupError} in case the encoding cannot be found or the
-codec doesn't support an incremental encoder.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{getincrementaldecoder}{encoding}
-Look up the codec for the given encoding and return its incremental decoder
-class or factory function.
-
-Raises a \exception{LookupError} in case the encoding cannot be found or the
-codec doesn't support an incremental decoder.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{getreader}{encoding}
-Look up the codec for the given encoding and return its StreamReader
-class or factory function.
-
-Raises a \exception{LookupError} in case the encoding cannot be found.
-\end{funcdesc}
-
-\begin{funcdesc}{getwriter}{encoding}
-Look up the codec for the given encoding and return its StreamWriter
-class or factory function.
-
-Raises a \exception{LookupError} in case the encoding cannot be found.
-\end{funcdesc}
-
-\begin{funcdesc}{register_error}{name, error_handler}
-Register the error handling function \var{error_handler} under the
-name \var{name}. \var{error_handler} will be called during encoding
-and decoding in case of an error, when \var{name} is specified as the
-errors parameter.
-
-For encoding \var{error_handler} will be called with a
-\exception{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 \exception{IndexError} will be raised.
-
-Decoding and translating works similar, except \exception{UnicodeDecodeError}
-or \exception{UnicodeTranslateError} will be passed to the handler and
-that the replacement from the error handler will be put into the output
-directly.
-\end{funcdesc}
-
-\begin{funcdesc}{lookup_error}{name}
-Return the error handler previously registered under the name \var{name}.
-
-Raises a \exception{LookupError} in case the handler cannot be found.
-\end{funcdesc}
-
-\begin{funcdesc}{strict_errors}{exception}
-Implements the \code{strict} error handling.
-\end{funcdesc}
-
-\begin{funcdesc}{replace_errors}{exception}
-Implements the \code{replace} error handling.
-\end{funcdesc}
-
-\begin{funcdesc}{ignore_errors}{exception}
-Implements the \code{ignore} error handling.
-\end{funcdesc}
-
-\begin{funcdesc}{xmlcharrefreplace_errors_errors}{exception}
-Implements the \code{xmlcharrefreplace} error handling.
-\end{funcdesc}
-
-\begin{funcdesc}{backslashreplace_errors_errors}{exception}
-Implements the \code{backslashreplace} error handling.
-\end{funcdesc}
-
-To simplify working with encoded files or stream, the module
-also defines these utility functions:
-
-\begin{funcdesc}{open}{filename, mode\optional{, encoding\optional{,
- errors\optional{, buffering}}}}
-Open an encoded file using the given \var{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.}
-
-\var{encoding} specifies the encoding which is to be used for the
-file.
-
-\var{errors} may be given to define the error handling. It defaults
-to \code{'strict'} which causes a \exception{ValueError} to be raised
-in case an encoding error occurs.
-
-\var{buffering} has the same meaning as for the built-in
-\function{open()} function. It defaults to line buffered.
-\end{funcdesc}
-
-\begin{funcdesc}{EncodedFile}{file, input\optional{,
- output\optional{, errors}}}
-Return a wrapped version of file which provides transparent
-encoding translation.
-
-Strings written to the wrapped file are interpreted according to the
-given \var{input} encoding and then written to the original file as
-strings using the \var{output} encoding. The intermediate encoding will
-usually be Unicode but depends on the specified codecs.
-
-If \var{output} is not given, it defaults to \var{input}.
-
-\var{errors} may be given to define the error handling. It defaults to
-\code{'strict'}, which causes \exception{ValueError} to be raised in case
-an encoding error occurs.
-\end{funcdesc}
-
-\begin{funcdesc}{iterencode}{iterable, encoding\optional{, errors}}
-Uses an incremental encoder to iteratively encode the input provided by
-\var{iterable}. This function is a generator. \var{errors} (as well as
-any other keyword argument) is passed through to the incremental encoder.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{iterdecode}{iterable, encoding\optional{, errors}}
-Uses an incremental decoder to iteratively decode the input provided by
-\var{iterable}. This function is a generator. \var{errors} (as well as
-any other keyword argument) is passed through to the incremental decoder.
-\versionadded{2.5}
-\end{funcdesc}
-
-The module also provides the following constants which are useful
-for reading and writing to platform dependent files:
-
-\begin{datadesc}{BOM}
-\dataline{BOM_BE}
-\dataline{BOM_LE}
-\dataline{BOM_UTF8}
-\dataline{BOM_UTF16}
-\dataline{BOM_UTF16_BE}
-\dataline{BOM_UTF16_LE}
-\dataline{BOM_UTF32}
-\dataline{BOM_UTF32_BE}
-\dataline{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.
-\constant{BOM_UTF16} is either \constant{BOM_UTF16_BE} or
-\constant{BOM_UTF16_LE} depending on the platform's native byte order,
-\constant{BOM} is an alias for \constant{BOM_UTF16}, \constant{BOM_LE}
-for \constant{BOM_UTF16_LE} and \constant{BOM_BE} for \constant{BOM_UTF16_BE}.
-The others represent the BOM in UTF-8 and UTF-32 encodings.
-\end{datadesc}
-
-
-\subsection{Codec Base Classes \label{codec-base-classes}}
-
-The \module{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 \method{encode()} and
-\method{decode()} methods may implement different error handling
-schemes by providing the \var{errors} string argument. The following
-string values are defined and implemented by all standard Python
-codecs:
-
-\begin{tableii}{l|l}{code}{Value}{Meaning}
- \lineii{'strict'}{Raise \exception{UnicodeError} (or a subclass);
- this is the default.}
- \lineii{'ignore'}{Ignore the character and continue with the next.}
- \lineii{'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.}
- \lineii{'xmlcharrefreplace'}{Replace with the appropriate XML
- character reference (only for encoding).}
- \lineii{'backslashreplace'}{Replace with backslashed escape sequences
- (only for encoding).}
-\end{tableii}
-
-The set of allowed values can be extended via \method{register_error}.
-
-
-\subsubsection{Codec Objects \label{codec-objects}}
-
-The \class{Codec} class defines these methods which also define the
-function interfaces of the stateless encoder and decoder:
-
-\begin{methoddesc}[Codec]{encode}{input\optional{, errors}}
- Encodes the object \var{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., \code{cp1252} or
- \code{iso-8859-1}).
-
- \var{errors} defines the error handling to apply. It defaults to
- \code{'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.
-\end{methoddesc}
-
-\begin{methoddesc}[Codec]{decode}{input\optional{, errors}}
- Decodes the object \var{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.
-
- \var{input} must be an object which provides the \code{bf_getreadbuf}
- buffer slot. Python strings, buffer objects and memory mapped files
- are examples of objects providing this slot.
-
- \var{errors} defines the error handling to apply. It defaults to
- \code{'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.
-\end{methoddesc}
-
-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 \method{encode}/\method{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 \method{encode}/\method{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.
-
-
-\subsubsection{IncrementalEncoder Objects \label{incremental-encoder-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.
-
-\begin{classdesc}{IncrementalEncoder}{\optional{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 \var{errors} keyword argument. These
- parameters are predefined:
-
- \begin{itemize}
- \item \code{'strict'} Raise \exception{ValueError} (or a subclass);
- this is the default.
- \item \code{'ignore'} Ignore the character and continue with the next.
- \item \code{'replace'} Replace with a suitable replacement character
- \item \code{'xmlcharrefreplace'} Replace with the appropriate XML
- character reference
- \item \code{'backslashreplace'} Replace with backslashed escape sequences.
- \end{itemize}
-
- The \var{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 \var{errors} argument can
- be extended with \function{register_error()}.
-\end{classdesc}
-
-\begin{methoddesc}{encode}{object\optional{, final}}
- Encodes \var{object} (taking the current state of the encoder into account)
- and returns the resulting encoded object. If this is the last call to
- \method{encode} \var{final} must be true (the default is false).
-\end{methoddesc}
-
-\begin{methoddesc}{reset}{}
- Reset the encoder to the initial state.
-\end{methoddesc}
-
-\begin{methoddesc}{getstate}{}
- Return the current state of the encoder which must be an integer.
- The implementation should make sure that \code{0} is the most common state.
- (States that are more complicated than integers can be converted into an
- integer by marshaling/pickling the state and encoding the bytes of the
- resulting string into an integer).
- \versionadded{3.0}
-\end{methoddesc}
-
-\begin{methoddesc}{setstate}{state}
- Set the state of the encoder to \var{state}. \var{state} must be an
- encoder state returned by \method{getstate}.
- \versionadded{3.0}
-\end{methoddesc}
-
-
-\subsubsection{IncrementalDecoder Objects \label{incremental-decoder-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.
-
-\begin{classdesc}{IncrementalDecoder}{\optional{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 \var{errors} keyword argument. These
- parameters are predefined:
-
- \begin{itemize}
- \item \code{'strict'} Raise \exception{ValueError} (or a subclass);
- this is the default.
- \item \code{'ignore'} Ignore the character and continue with the next.
- \item \code{'replace'} Replace with a suitable replacement character.
- \end{itemize}
-
- The \var{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 \var{errors} argument can
- be extended with \function{register_error()}.
-\end{classdesc}
-
-\begin{methoddesc}{decode}{object\optional{, final}}
- Decodes \var{object} (taking the current state of the decoder into account)
- and returns the resulting decoded object. If this is the last call to
- \method{decode} \var{final} must be true (the default is false).
- If \var{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).
-\end{methoddesc}
-
-\begin{methoddesc}{reset}{}
- Reset the decoder to the initial state.
-\end{methoddesc}
-
-\begin{methoddesc}{getstate}{}
- Return the current state of the decoder. This must be a tuple with two
- items, the first must be the buffer containing the still undecoded input.
- The second must be an integer and can be additional state info.
- (The implementation should make sure that \code{0} is the most common
- additional state info.) If this additional state info is \code{0} it must
- be possible to set the decoder to the state which has no input buffered
- and \code{0} as the additional state info, so that feeding the previously
- buffered input to the decoder returns it to the previous state without
- producing any output. (Additional state info that is more complicated
- than integers can be converted into an integer by marshaling/pickling
- the info and encoding the bytes of the resulting string into an integer.)
- \versionadded{3.0}
-\end{methoddesc}
-
-\begin{methoddesc}{setstate}{state}
- Set the state of the encoder to \var{state}. \var{state} must be a
- decoder state returned by \method{getstate}.
- \versionadded{3.0}
-\end{methoddesc}
-
-
-The \class{StreamWriter} and \class{StreamReader} classes provide
-generic working interfaces which can be used to implement new
-encoding submodules very easily. See \module{encodings.utf_8} for an
-example of how this is done.
-
-
-\subsubsection{StreamWriter Objects \label{stream-writer-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.
-
-\begin{classdesc}{StreamWriter}{stream\optional{, 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.
-
- \var{stream} must be a file-like object open for writing binary
- data.
-
- The \class{StreamWriter} may implement different error handling
- schemes by providing the \var{errors} keyword argument. These
- parameters are predefined:
-
- \begin{itemize}
- \item \code{'strict'} Raise \exception{ValueError} (or a subclass);
- this is the default.
- \item \code{'ignore'} Ignore the character and continue with the next.
- \item \code{'replace'} Replace with a suitable replacement character
- \item \code{'xmlcharrefreplace'} Replace with the appropriate XML
- character reference
- \item \code{'backslashreplace'} Replace with backslashed escape sequences.
- \end{itemize}
-
- The \var{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 \var{errors} argument can
- be extended with \function{register_error()}.
-\end{classdesc}
-
-\begin{methoddesc}{write}{object}
- Writes the object's contents encoded to the stream.
-\end{methoddesc}
-
-\begin{methoddesc}{writelines}{list}
- Writes the concatenated list of strings to the stream (possibly by
- reusing the \method{write()} method).
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-\end{methoddesc}
-
-In addition to the above methods, the \class{StreamWriter} must also
-inherit all other methods and attributes from the underlying stream.
-
-
-\subsubsection{StreamReader Objects \label{stream-reader-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.
-
-\begin{classdesc}{StreamReader}{stream\optional{, 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.
-
- \var{stream} must be a file-like object open for reading (binary)
- data.
-
- The \class{StreamReader} may implement different error handling
- schemes by providing the \var{errors} keyword argument. These
- parameters are defined:
-
- \begin{itemize}
- \item \code{'strict'} Raise \exception{ValueError} (or a subclass);
- this is the default.
- \item \code{'ignore'} Ignore the character and continue with the next.
- \item \code{'replace'} Replace with a suitable replacement character.
- \end{itemize}
-
- The \var{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 \var{errors} argument can
- be extended with \function{register_error()}.
-\end{classdesc}
-
-\begin{methoddesc}{read}{\optional{size\optional{, chars, \optional{firstline}}}}
- Decodes data from the stream and returns the resulting object.
-
- \var{chars} indicates the number of characters to read from the
- stream. \function{read()} will never return more than \var{chars}
- characters, but it might return less, if there are not enough
- characters available.
-
- \var{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. \var{size} is intended to prevent having
- to decode huge files in one step.
-
- \var{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[\var{chars} argument added]{2.4}
- \versionchanged[\var{firstline} argument added]{2.4.2}
-\end{methoddesc}
-
-\begin{methoddesc}{readline}{\optional{size\optional{, keepends}}}
- Read one line from the input stream and return the
- decoded data.
-
- \var{size}, if given, is passed as size argument to the stream's
- \method{readline()} method.
-
- If \var{keepends} is false line-endings will be stripped from the
- lines returned.
-
- \versionchanged[\var{keepends} argument added]{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}{readlines}{\optional{sizehint\optional{, 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 \var{keepends} is true.
-
- \var{sizehint}, if given, is passed as the \var{size} argument to the
- stream's \method{read()} method.
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-\end{methoddesc}
-
-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.
-
-
-\subsubsection{StreamReaderWriter Objects \label{stream-reader-writer}}
-
-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 \function{lookup()} function to construct the instance.
-
-\begin{classdesc}{StreamReaderWriter}{stream, Reader, Writer, errors}
- Creates a \class{StreamReaderWriter} instance.
- \var{stream} must be a file-like object.
- \var{Reader} and \var{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.
-\end{classdesc}
-
-\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.
-
-
-\subsubsection{StreamRecoder Objects \label{stream-recoder-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 \function{lookup()} function to construct the instance.
-
-\begin{classdesc}{StreamRecoder}{stream, encode, decode,
- Reader, Writer, errors}
- Creates a \class{StreamRecoder} instance which implements a two-way
- conversion: \var{encode} and \var{decode} work on the frontend (the
- input to \method{read()} and output of \method{write()}) while
- \var{Reader} and \var{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.
-
- \var{stream} must be a file-like object.
-
- \var{encode}, \var{decode} must adhere to the \class{Codec}
- interface. \var{Reader}, \var{Writer} must be factory functions or
- classes providing objects of the \class{StreamReader} and
- \class{StreamWriter} interface respectively.
-
- \var{encode} and \var{decode} are needed for the frontend
- translation, \var{Reader} and \var{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.
-\end{classdesc}
-
-\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.
-
-\subsection{Encodings and Unicode\label{encodings-overview}}
-
-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 \longprogramopt{enable-unicode=ucs2} or
-\longprogramopt{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
-\code{0x0}-\code{0xff}. This means that a unicode object that contains
-codepoints above \code{U+00FF} can't be encoded with this method (which
-is called \code{'latin-1'} or \code{'iso-8859-1'}).
-\function{unicode.encode()} will raise a \exception{UnicodeEncodeError}
-that looks like this: \samp{UnicodeEncodeError: 'latin-1' codec can't
-encode character u'\e 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 \code{0x0}-\code{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 \code{U+FEFF}. This character will be prepended to every UTF-16
-byte sequence. The byte swapped version of this character (\code{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 \code{U+FFFE}
-the bytes have to be swapped on decoding. Unfortunately upto Unicode
-4.0 the character \code{U+FEFF} had a second purpose as a \samp{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 \code{U+FEFF} as a \samp{ZERO WIDTH NO-BREAK
-SPACE} has been deprecated (with \code{U+2060} (\samp{WORD JOINER}) assuming
-this role). Nevertheless Unicode software still must be able to handle
-\code{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 \samp{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):
-
-\begin{tableii}{l|l}{textrm}{Range}{Encoding}
-\lineii{\code{U-00000000} ... \code{U-0000007F}}{0xxxxxxx}
-\lineii{\code{U-00000080} ... \code{U-000007FF}}{110xxxxx 10xxxxxx}
-\lineii{\code{U-00000800} ... \code{U-0000FFFF}}{1110xxxx 10xxxxxx 10xxxxxx}
-\lineii{\code{U-00010000} ... \code{U-001FFFFF}}{11110xxx 10xxxxxx 10xxxxxx 10xxxxxx}
-\lineii{\code{U-00200000} ... \code{U-03FFFFFF}}{111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx}
-\lineii{\code{U-04000000} ... \code{U-7FFFFFFF}}{1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx}
-\end{tableii}
-
-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 \code{U+FEFF}
-character in the decoded Unicode string (even if it's the first
-character) is treated as a \samp{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 \code{"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: \code{0xef},
-\code{0xbb}, \code{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
-\code{0xef}, \code{0xbb}, \code{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.
-
-
-\subsection{Standard Encodings\label{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:
-
-\begin{itemize}
-\item an ISO 8859 codeset
-\item a Microsoft Windows code page, which is typically derived from
- a 8859 codeset, but replaces control characters with additional
- graphic characters
-\item an IBM EBCDIC code page
-\item an IBM PC code page, which is \ASCII{} compatible
-\end{itemize}
-
-\begin{longtableiii}{l|l|l}{textrm}{Codec}{Aliases}{Languages}
-
-\lineiii{ascii}
- {646, us-ascii}
- {English}
-
-\lineiii{big5}
- {big5-tw, csbig5}
- {Traditional Chinese}
-
-\lineiii{big5hkscs}
- {big5-hkscs, hkscs}
- {Traditional Chinese}
-
-\lineiii{cp037}
- {IBM037, IBM039}
- {English}
-
-\lineiii{cp424}
- {EBCDIC-CP-HE, IBM424}
- {Hebrew}
-
-\lineiii{cp437}
- {437, IBM437}
- {English}
-
-\lineiii{cp500}
- {EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500}
- {Western Europe}
-
-\lineiii{cp737}
- {}
- {Greek}
-
-\lineiii{cp775}
- {IBM775}
- {Baltic languages}
-
-\lineiii{cp850}
- {850, IBM850}
- {Western Europe}
-
-\lineiii{cp852}
- {852, IBM852}
- {Central and Eastern Europe}
-
-\lineiii{cp855}
- {855, IBM855}
- {Bulgarian, Byelorussian, Macedonian, Russian, Serbian}
-
-\lineiii{cp856}
- {}
- {Hebrew}
-
-\lineiii{cp857}
- {857, IBM857}
- {Turkish}
-
-\lineiii{cp860}
- {860, IBM860}
- {Portuguese}
-
-\lineiii{cp861}
- {861, CP-IS, IBM861}
- {Icelandic}
-
-\lineiii{cp862}
- {862, IBM862}
- {Hebrew}
-
-\lineiii{cp863}
- {863, IBM863}
- {Canadian}
-
-\lineiii{cp864}
- {IBM864}
- {Arabic}
-
-\lineiii{cp865}
- {865, IBM865}
- {Danish, Norwegian}
-
-\lineiii{cp866}
- {866, IBM866}
- {Russian}
-
-\lineiii{cp869}
- {869, CP-GR, IBM869}
- {Greek}
-
-\lineiii{cp874}
- {}
- {Thai}
-
-\lineiii{cp875}
- {}
- {Greek}
-
-\lineiii{cp932}
- {932, ms932, mskanji, ms-kanji}
- {Japanese}
-
-\lineiii{cp949}
- {949, ms949, uhc}
- {Korean}
-
-\lineiii{cp950}
- {950, ms950}
- {Traditional Chinese}
-
-\lineiii{cp1006}
- {}
- {Urdu}
-
-\lineiii{cp1026}
- {ibm1026}
- {Turkish}
-
-\lineiii{cp1140}
- {ibm1140}
- {Western Europe}
-
-\lineiii{cp1250}
- {windows-1250}
- {Central and Eastern Europe}
-
-\lineiii{cp1251}
- {windows-1251}
- {Bulgarian, Byelorussian, Macedonian, Russian, Serbian}
-
-\lineiii{cp1252}
- {windows-1252}
- {Western Europe}
-
-\lineiii{cp1253}
- {windows-1253}
- {Greek}
-
-\lineiii{cp1254}
- {windows-1254}
- {Turkish}
-
-\lineiii{cp1255}
- {windows-1255}
- {Hebrew}
-
-\lineiii{cp1256}
- {windows1256}
- {Arabic}
-
-\lineiii{cp1257}
- {windows-1257}
- {Baltic languages}
-
-\lineiii{cp1258}
- {windows-1258}
- {Vietnamese}
-
-\lineiii{euc_jp}
- {eucjp, ujis, u-jis}
- {Japanese}
-
-\lineiii{euc_jis_2004}
- {jisx0213, eucjis2004}
- {Japanese}
-
-\lineiii{euc_jisx0213}
- {eucjisx0213}
- {Japanese}
-
-\lineiii{euc_kr}
- {euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001}
- {Korean}
-
-\lineiii{gb2312}
- {chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980,
- gb2312-80, iso-ir-58}
- {Simplified Chinese}
-
-\lineiii{gbk}
- {936, cp936, ms936}
- {Unified Chinese}
-
-\lineiii{gb18030}
- {gb18030-2000}
- {Unified Chinese}
-
-\lineiii{hz}
- {hzgb, hz-gb, hz-gb-2312}
- {Simplified Chinese}
-
-\lineiii{iso2022_jp}
- {csiso2022jp, iso2022jp, iso-2022-jp}
- {Japanese}
-
-\lineiii{iso2022_jp_1}
- {iso2022jp-1, iso-2022-jp-1}
- {Japanese}
-
-\lineiii{iso2022_jp_2}
- {iso2022jp-2, iso-2022-jp-2}
- {Japanese, Korean, Simplified Chinese, Western Europe, Greek}
-
-\lineiii{iso2022_jp_2004}
- {iso2022jp-2004, iso-2022-jp-2004}
- {Japanese}
-
-\lineiii{iso2022_jp_3}
- {iso2022jp-3, iso-2022-jp-3}
- {Japanese}
-
-\lineiii{iso2022_jp_ext}
- {iso2022jp-ext, iso-2022-jp-ext}
- {Japanese}
-
-\lineiii{iso2022_kr}
- {csiso2022kr, iso2022kr, iso-2022-kr}
- {Korean}
-
-\lineiii{latin_1}
- {iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1}
- {West Europe}
-
-\lineiii{iso8859_2}
- {iso-8859-2, latin2, L2}
- {Central and Eastern Europe}
-
-\lineiii{iso8859_3}
- {iso-8859-3, latin3, L3}
- {Esperanto, Maltese}
-
-\lineiii{iso8859_4}
- {iso-8859-4, latin4, L4}
- {Baltic languagues}
-
-\lineiii{iso8859_5}
- {iso-8859-5, cyrillic}
- {Bulgarian, Byelorussian, Macedonian, Russian, Serbian}
-
-\lineiii{iso8859_6}
- {iso-8859-6, arabic}
- {Arabic}
-
-\lineiii{iso8859_7}
- {iso-8859-7, greek, greek8}
- {Greek}
-
-\lineiii{iso8859_8}
- {iso-8859-8, hebrew}
- {Hebrew}
-
-\lineiii{iso8859_9}
- {iso-8859-9, latin5, L5}
- {Turkish}
-
-\lineiii{iso8859_10}
- {iso-8859-10, latin6, L6}
- {Nordic languages}
-
-\lineiii{iso8859_13}
- {iso-8859-13}
- {Baltic languages}
-
-\lineiii{iso8859_14}
- {iso-8859-14, latin8, L8}
- {Celtic languages}
-
-\lineiii{iso8859_15}
- {iso-8859-15}
- {Western Europe}
-
-\lineiii{johab}
- {cp1361, ms1361}
- {Korean}
-
-\lineiii{koi8_r}
- {}
- {Russian}
-
-\lineiii{koi8_u}
- {}
- {Ukrainian}
-
-\lineiii{mac_cyrillic}
- {maccyrillic}
- {Bulgarian, Byelorussian, Macedonian, Russian, Serbian}
-
-\lineiii{mac_greek}
- {macgreek}
- {Greek}
-
-\lineiii{mac_iceland}
- {maciceland}
- {Icelandic}
-
-\lineiii{mac_latin2}
- {maclatin2, maccentraleurope}
- {Central and Eastern Europe}
-
-\lineiii{mac_roman}
- {macroman}
- {Western Europe}
-
-\lineiii{mac_turkish}
- {macturkish}
- {Turkish}
-
-\lineiii{ptcp154}
- {csptcp154, pt154, cp154, cyrillic-asian}
- {Kazakh}
-
-\lineiii{shift_jis}
- {csshiftjis, shiftjis, sjis, s_jis}
- {Japanese}
-
-\lineiii{shift_jis_2004}
- {shiftjis2004, sjis_2004, sjis2004}
- {Japanese}
-
-\lineiii{shift_jisx0213}
- {shiftjisx0213, sjisx0213, s_jisx0213}
- {Japanese}
-
-\lineiii{utf_16}
- {U16, utf16}
- {all languages}
-
-\lineiii{utf_16_be}
- {UTF-16BE}
- {all languages (BMP only)}
-
-\lineiii{utf_16_le}
- {UTF-16LE}
- {all languages (BMP only)}
-
-\lineiii{utf_7}
- {U7, unicode-1-1-utf-7}
- {all languages}
-
-\lineiii{utf_8}
- {U8, UTF, utf8}
- {all languages}
-
-\lineiii{utf_8_sig}
- {}
- {all languages}
-
-\end{longtableiii}
-
-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.
-
-\begin{tableiv}{l|l|l|l}{textrm}{Codec}{Aliases}{Operand type}{Purpose}
-
-\lineiv{idna}
- {}
- {Unicode string}
- {Implements \rfc{3490},
- see also \refmodule{encodings.idna}}
-
-\lineiv{mbcs}
- {dbcs}
- {Unicode string}
- {Windows only: Encode operand according to the ANSI codepage (CP_ACP)}
-
-\lineiv{palmos}
- {}
- {Unicode string}
- {Encoding of PalmOS 3.5}
-
-\lineiv{punycode}
- {}
- {Unicode string}
- {Implements \rfc{3492}}
-
-\lineiv{raw_unicode_escape}
- {}
- {Unicode string}
- {Produce a string that is suitable as raw Unicode literal in
- Python source code}
-
-\lineiv{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.}
-
-\lineiv{unicode_escape}
- {}
- {Unicode string}
- {Produce a string that is suitable as Unicode literal in
- Python source code}
-
-\lineiv{unicode_internal}
- {}
- {Unicode string}
- {Return the internal representation of the operand}
-\end{tableiv}
-
-\versionadded[The \code{idna} and \code{punycode} encodings]{2.3}
-
-\subsection{\module{encodings.idna} ---
- Internationalized Domain Names in Applications}
-
-\declaremodule{standard}{encodings.idna}
-\modulesynopsis{Internationalized Domain Names implementation}
-% XXX The next line triggers a formatting bug, so it's commented out
-% until that can be fixed.
-%\moduleauthor{Martin v. L\"owis}
-
-\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
-\code{punycode} encoding and \refmodule{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\c caise.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 \code{idna} codec
-allows to convert between Unicode and the ACE. Furthermore, the
-\refmodule{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
-\refmodule{httplib} and \refmodule{ftplib}, accept Unicode host names
-(\refmodule{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 \module{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.
-
-\begin{funcdesc}{nameprep}{label}
-Return the nameprepped version of \var{label}. The implementation
-currently assumes query strings, so \code{AllowUnassigned} is
-true.
-\end{funcdesc}
-
-\begin{funcdesc}{ToASCII}{label}
-Convert a label to \ASCII, as specified in \rfc{3490}.
-\code{UseSTD3ASCIIRules} is assumed to be false.
-\end{funcdesc}
-
-\begin{funcdesc}{ToUnicode}{label}
-Convert a label to Unicode, as specified in \rfc{3490}.
-\end{funcdesc}
-
- \subsection{\module{encodings.utf_8_sig} ---
- UTF-8 codec with BOM signature}
-\declaremodule{standard}{encodings.utf-8-sig} % XXX utf_8_sig gives TeX errors
-\modulesynopsis{UTF-8 codec with BOM signature}
-\moduleauthor{Walter D\"orwald}{}
-
-\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.
diff --git a/Doc/lib/libcodeop.tex b/Doc/lib/libcodeop.tex
deleted file mode 100644
index 6972b6f..0000000
--- a/Doc/lib/libcodeop.tex
+++ /dev/null
@@ -1,103 +0,0 @@
-\section{\module{codeop} ---
- Compile Python code}
-
-% LaTeXed from excellent doc-string.
-
-\declaremodule{standard}{codeop}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\sectionauthor{Michael Hudson}{mwh@python.net}
-\modulesynopsis{Compile (possibly incomplete) Python code.}
-
-The \module{codeop} module provides utilities upon which the Python
-read-eval-print loop can be emulated, as is done in the
-\refmodule{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 \refmodule{code} module instead.
-
-There are two parts to this job:
-
-\begin{enumerate}
- \item Being able to tell if a line of input completes a Python
- statement: in short, telling whether to print
- `\code{>>>~}' or `\code{...~}' next.
- \item Remembering which future statements the user has entered, so
- subsequent input can be compiled with these in effect.
-\end{enumerate}
-
-The \module{codeop} module provides a way of doing each of these
-things, and a way of doing them both.
-
-To do just the former:
-
-\begin{funcdesc}{compile_command}
- {source\optional{, filename\optional{, symbol}}}
-Tries to compile \var{source}, which should be a string of Python
-code and return a code object if \var{source} is valid
-Python code. In that case, the filename attribute of the code object
-will be \var{filename}, which defaults to \code{'<input>'}.
-Returns \code{None} if \var{source} is \emph{not} valid Python
-code, but is a prefix of valid Python code.
-
-If there is a problem with \var{source}, an exception will be raised.
-\exception{SyntaxError} is raised if there is invalid Python syntax,
-and \exception{OverflowError} or \exception{ValueError} if there is an
-invalid literal.
-
-The \var{symbol} argument determines whether \var{source} is compiled
-as a statement (\code{'single'}, the default) or as an expression
-(\code{'eval'}). Any other value will cause \exception{ValueError} to
-be raised.
-
-\strong{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.
-\end{funcdesc}
-
-\begin{classdesc}{Compile}{}
-Instances of this class have \method{__call__()} methods identical in
-signature to the built-in function \function{compile()}, but with the
-difference that if the instance compiles program text containing a
-\module{__future__} statement, the instance 'remembers' and compiles
-all subsequent program texts with the statement in force.
-\end{classdesc}
-
-\begin{classdesc}{CommandCompiler}{}
-Instances of this class have \method{__call__()} methods identical in
-signature to \function{compile_command()}; the difference is that if
-the instance compiles program text containing a \code{__future__}
-statement, the instance 'remembers' and compiles all subsequent
-program texts with the statement in force.
-\end{classdesc}
-
-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
-
-\begin{verbatim}
-try:
- from codeop import CommandCompiler
- compile_command = CommandCompiler()
- del CommandCompiler
-except ImportError:
- from codeop import compile_command
-\end{verbatim}
-
-which is a low-impact change, but introduces possibly unwanted global
-state into your program, or you can write:
-
-\begin{verbatim}
-try:
- from codeop import CommandCompiler
-except ImportError:
- def CommandCompiler():
- from codeop import compile_command
- return compile_command
-\end{verbatim}
-
-and then call \code{CommandCompiler} every time you need a fresh
-compiler object.
diff --git a/Doc/lib/libcollections.tex b/Doc/lib/libcollections.tex
deleted file mode 100644
index fc44e01..0000000
--- a/Doc/lib/libcollections.tex
+++ /dev/null
@@ -1,402 +0,0 @@
-\section{\module{collections} ---
- High-performance container datatypes}
-
-\declaremodule{standard}{collections}
-\modulesynopsis{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, deque and defaultdict, and one datatype factory
-function, \function{NamedTuple}.
-Future additions may include balanced trees and ordered dictionaries.
-\versionchanged[Added defaultdict]{2.5}
-\versionchanged[Added NamedTuple]{2.6}
-
-\subsection{\class{deque} objects \label{deque-objects}}
-
-\begin{classdesc}{deque}{\optional{iterable}}
- Returns a new deque object initialized left-to-right (using
- \method{append()}) with data from \var{iterable}. If \var{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 \code{O(1)} performance in either direction.
-
- Though \class{list} objects support similar operations, they are optimized
- for fast fixed-length operations and incur \code{O(n)} memory movement costs
- for \samp{pop(0)} and \samp{insert(0, v)} operations which change both the
- size and position of the underlying data representation.
- \versionadded{2.4}
-\end{classdesc}
-
-Deque objects support the following methods:
-
-\begin{methoddesc}{append}{x}
- Add \var{x} to the right side of the deque.
-\end{methoddesc}
-
-\begin{methoddesc}{appendleft}{x}
- Add \var{x} to the left side of the deque.
-\end{methoddesc}
-
-\begin{methoddesc}{clear}{}
- Remove all elements from the deque leaving it with length 0.
-\end{methoddesc}
-
-\begin{methoddesc}{extend}{iterable}
- Extend the right side of the deque by appending elements from
- the iterable argument.
-\end{methoddesc}
-
-\begin{methoddesc}{extendleft}{iterable}
- Extend the left side of the deque by appending elements from
- \var{iterable}. Note, the series of left appends results in
- reversing the order of elements in the iterable argument.
-\end{methoddesc}
-
-\begin{methoddesc}{pop}{}
- Remove and return an element from the right side of the deque.
- If no elements are present, raises an \exception{IndexError}.
-\end{methoddesc}
-
-\begin{methoddesc}{popleft}{}
- Remove and return an element from the left side of the deque.
- If no elements are present, raises an \exception{IndexError}.
-\end{methoddesc}
-
-\begin{methoddesc}{remove}{value}
- Removed the first occurrence of \var{value}. If not found,
- raises a \exception{ValueError}.
- \versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{rotate}{n}
- Rotate the deque \var{n} steps to the right. If \var{n} is
- negative, rotate to the left. Rotating one step to the right
- is equivalent to: \samp{d.appendleft(d.pop())}.
-\end{methoddesc}
-
-In addition to the above, deques support iteration, pickling, \samp{len(d)},
-\samp{reversed(d)}, \samp{copy.copy(d)}, \samp{copy.deepcopy(d)},
-membership testing with the \keyword{in} operator, and subscript references
-such as \samp{d[-1]}.
-
-Example:
-
-\begin{verbatim}
->>> 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'])
-\end{verbatim}
-
-\subsubsection{Recipes \label{deque-recipes}}
-
-This section shows various approaches to working with deques.
-
-The \method{rotate()} method provides a way to implement \class{deque}
-slicing and deletion. For example, a pure python implementation of
-\code{del d[n]} relies on the \method{rotate()} method to position
-elements to be popped:
-
-\begin{verbatim}
-def delete_nth(d, n):
- d.rotate(-n)
- d.popleft()
- d.rotate(n)
-\end{verbatim}
-
-To implement \class{deque} slicing, use a similar approach applying
-\method{rotate()} to bring a target element to the left side of the deque.
-Remove old entries with \method{popleft()}, add new entries with
-\method{extend()}, and then reverse the rotation.
-
-With minor variations on that approach, it is easy to implement Forth style
-stack manipulations such as \code{dup}, \code{drop}, \code{swap}, \code{over},
-\code{pick}, \code{rot}, and \code{roll}.
-
-A roundrobin task server can be built from a \class{deque} using
-\method{popleft()} to select the current task and \method{append()}
-to add it back to the tasklist if the input stream is not exhausted:
-
-\begin{verbatim}
-def roundrobin(*iterables):
- pending = deque(iter(i) for i in iterables)
- while pending:
- task = pending.popleft()
- try:
- yield next(task)
- except StopIteration:
- continue
- pending.append(task)
-
->>> for value in roundrobin('abc', 'd', 'efgh'):
-... print value
-
-a
-d
-e
-b
-f
-c
-g
-h
-
-\end{verbatim}
-
-
-Multi-pass data reduction algorithms can be succinctly expressed and
-efficiently coded by extracting elements with multiple calls to
-\method{popleft()}, applying the reduction function, and calling
-\method{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:
-
-\begin{verbatim}
-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']]]]
-
-\end{verbatim}
-
-
-
-\subsection{\class{defaultdict} objects \label{defaultdict-objects}}
-
-\begin{classdesc}{defaultdict}{\optional{default_factory\optional{, ...}}}
- 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
- \member{default_factory} attribute; it defaults to \code{None}.
- All remaining arguments are treated the same as if they were
- passed to the \class{dict} constructor, including keyword arguments.
-
- \versionadded{2.5}
-\end{classdesc}
-
-\class{defaultdict} objects support the following method in addition to
-the standard \class{dict} operations:
-
-\begin{methoddesc}{__missing__}{key}
- If the \member{default_factory} attribute is \code{None}, this raises
- an \exception{KeyError} exception with the \var{key} as argument.
-
- If \member{default_factory} is not \code{None}, it is called without
- arguments to provide a default value for the given \var{key}, this
- value is inserted in the dictionary for the \var{key}, and returned.
-
- If calling \member{default_factory} raises an exception this exception
- is propagated unchanged.
-
- This method is called by the \method{__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 \method{__getitem__}.
-\end{methoddesc}
-
-\class{defaultdict} objects support the following instance variable:
-
-\begin{memberdesc}{default_factory}
- This attribute is used by the \method{__missing__} method; it is initialized
- from the first argument to the constructor, if present, or to \code{None},
- if absent.
-\end{memberdesc}
-
-
-\subsubsection{\class{defaultdict} Examples \label{defaultdict-examples}}
-
-Using \class{list} as the \member{default_factory}, it is easy to group
-a sequence of key-value pairs into a dictionary of lists:
-
-\begin{verbatim}
->>> 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])]
-\end{verbatim}
-
-When each key is encountered for the first time, it is not already in the
-mapping; so an entry is automatically created using the
-\member{default_factory} function which returns an empty \class{list}. The
-\method{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 \method{list.append()} operation adds another value to
-the list. This technique is simpler and faster than an equivalent technique
-using \method{dict.setdefault()}:
-
-\begin{verbatim}
->>> d = {}
->>> for k, v in s:
- d.setdefault(k, []).append(v)
-
->>> d.items()
-[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
-\end{verbatim}
-
-Setting the \member{default_factory} to \class{int} makes the
-\class{defaultdict} useful for counting (like a bag or multiset in other
-languages):
-
-\begin{verbatim}
->>> s = 'mississippi'
->>> d = defaultdict(int)
->>> for k in s:
- d[k] += 1
-
->>> d.items()
-[('i', 4), ('p', 2), ('s', 4), ('m', 1)]
-\end{verbatim}
-
-When a letter is first encountered, it is missing from the mapping, so the
-\member{default_factory} function calls \function{int()} to supply a default
-count of zero. The increment operation then builds up the count for each
-letter.
-
-The function \function{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 a lambda function which can supply
-any constant value (not just zero):
-
-\begin{verbatim}
->>> def constant_factory(value):
-... return lambda: value
->>> d = defaultdict(constant_factory('<missing>'))
->>> d.update(name='John', action='ran')
->>> '%(name)s %(action)s to %(object)s' % d
-'John ran to <missing>'
-\end{verbatim}
-
-Setting the \member{default_factory} to \class{set} makes the
-\class{defaultdict} useful for building a dictionary of sets:
-
-\begin{verbatim}
->>> 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]))]
-\end{verbatim}
-
-
-
-\subsection{\function{NamedTuple} datatype factory function \label{named-tuple-factory}}
-
-\begin{funcdesc}{NamedTuple}{typename, fieldnames}
- Returns a new tuple subclass named \var{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
- \method{__repr__()} method which lists the tuple contents in a \code{name=value}
- format.
- \versionadded{2.6}
-
- The \var{fieldnames} are specified in a single string and are separated by spaces.
- Any valid Python identifier may be used for a field name.
-
- Example:
- \begin{verbatim}
->>> 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)
-\end{verbatim}
-
- 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 \module{csv} or \module{sqlite3} modules.
- For example:
-
- \begin{verbatim}
-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
-\end{verbatim}
-
- To cast an individual record stored as \class{list}, \class{tuple}, or some other
- iterable type, use the star-operator to unpack the values:
-
- \begin{verbatim}
->>> Color = NamedTuple('Color', 'name code')
->>> m = dict(red=1, green=2, blue=3)
->>> print Color(*m.popitem())
-Color(name='blue', code=3)
-\end{verbatim}
-
-\end{funcdesc}
diff --git a/Doc/lib/libcolorsys.tex b/Doc/lib/libcolorsys.tex
deleted file mode 100644
index 2748377..0000000
--- a/Doc/lib/libcolorsys.tex
+++ /dev/null
@@ -1,54 +0,0 @@
-\section{\module{colorsys} ---
- Conversions between color systems}
-
-\declaremodule{standard}{colorsys}
-\modulesynopsis{Conversion functions between RGB and other color systems.}
-\sectionauthor{David Ascher}{da@python.net}
-
-The \module{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
-\url{http://www.poynton.com/ColorFAQ.html}.
-
-The \module{colorsys} module defines the following functions:
-
-\begin{funcdesc}{rgb_to_yiq}{r, g, b}
-Convert the color from RGB coordinates to YIQ coordinates.
-\end{funcdesc}
-
-\begin{funcdesc}{yiq_to_rgb}{y, i, q}
-Convert the color from YIQ coordinates to RGB coordinates.
-\end{funcdesc}
-
-\begin{funcdesc}{rgb_to_hls}{r, g, b}
-Convert the color from RGB coordinates to HLS coordinates.
-\end{funcdesc}
-
-\begin{funcdesc}{hls_to_rgb}{h, l, s}
-Convert the color from HLS coordinates to RGB coordinates.
-\end{funcdesc}
-
-\begin{funcdesc}{rgb_to_hsv}{r, g, b}
-Convert the color from RGB coordinates to HSV coordinates.
-\end{funcdesc}
-
-\begin{funcdesc}{hsv_to_rgb}{h, s, v}
-Convert the color from HSV coordinates to RGB coordinates.
-\end{funcdesc}
-
-Example:
-
-\begin{verbatim}
->>> 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)
-\end{verbatim}
diff --git a/Doc/lib/libcommands.tex b/Doc/lib/libcommands.tex
deleted file mode 100644
index 4a5fa55..0000000
--- a/Doc/lib/libcommands.tex
+++ /dev/null
@@ -1,54 +0,0 @@
-\section{\module{commands} ---
- Utilities for running commands}
-
-\declaremodule{standard}{commands}
- \platform{Unix}
-\modulesynopsis{Utility functions for running external commands.}
-\sectionauthor{Sue Williams}{sbw@provis.com}
-
-
-The \module{commands} module contains wrapper functions for
-\function{os.popen()} which take a system command as a string and
-return any output generated by the command and, optionally, the exit
-status.
-
-The \module{subprocess} module provides more powerful facilities for
-spawning new processes and retrieving their results. Using the
-\module{subprocess} module is preferable to using the \module{commands}
-module.
-
-The \module{commands} module defines the following functions:
-
-
-\begin{funcdesc}{getstatusoutput}{cmd}
-Execute the string \var{cmd} in a shell with \function{os.popen()} and
-return a 2-tuple \code{(\var{status}, \var{output})}. \var{cmd} is
-actually run as \code{\{ \var{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
-\cfunction{wait()}.
-\end{funcdesc}
-
-\begin{funcdesc}{getoutput}{cmd}
-Like \function{getstatusoutput()}, except the exit status is ignored
-and the return value is a string containing the command's output.
-\end{funcdesc}
-
-Example:
-
-\begin{verbatim}
->>> 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'
-\end{verbatim}
-
-\begin{seealso}
- \seemodule{subprocess}{Module for spawning and managing subprocesses.}
-\end{seealso}
diff --git a/Doc/lib/libcompileall.tex b/Doc/lib/libcompileall.tex
deleted file mode 100644
index 3e9667d..0000000
--- a/Doc/lib/libcompileall.tex
+++ /dev/null
@@ -1,63 +0,0 @@
-\section{\module{compileall} ---
- Byte-compile Python libraries}
-
-\declaremodule{standard}{compileall}
-\modulesynopsis{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
-\code{sys.path}.
-
-
-\begin{funcdesc}{compile_dir}{dir\optional{, maxlevels\optional{,
- ddir\optional{, force\optional{,
- rx\optional{, quiet}}}}}}
- Recursively descend the directory tree named by \var{dir}, compiling
- all \file{.py} files along the way. The \var{maxlevels} parameter
- is used to limit the depth of the recursion; it defaults to
- \code{10}. If \var{ddir} is given, it is used as the base path from
- which the filenames used in error messages will be generated. If
- \var{force} is true, modules are re-compiled even if the timestamps
- are up to date.
-
- If \var{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 \var{quiet} is true, nothing is printed to the standard output
- in normal operation.
-\end{funcdesc}
-
-\begin{funcdesc}{compile_path}{\optional{skip_curdir\optional{,
- maxlevels\optional{, force}}}}
- Byte-compile all the \file{.py} files found along \code{sys.path}.
- If \var{skip_curdir} is true (the default), the current directory is
- not included in the search. The \var{maxlevels} and
- \var{force} parameters default to \code{0} and are passed to the
- \function{compile_dir()} function.
-\end{funcdesc}
-
-To force a recompile of all the \file{.py} files in the \file{Lib/}
-subdirectory and all its subdirectories:
-
-\begin{verbatim}
-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)
-\end{verbatim}
-
-
-\begin{seealso}
- \seemodule[pycompile]{py_compile}{Byte-compile a single source file.}
-\end{seealso}
diff --git a/Doc/lib/libconsts.tex b/Doc/lib/libconsts.tex
deleted file mode 100644
index bf36281..0000000
--- a/Doc/lib/libconsts.tex
+++ /dev/null
@@ -1,33 +0,0 @@
-\section{Built-in Constants}
-
-A small number of constants live in the built-in namespace. They are:
-
-\begin{datadesc}{False}
- The false value of the \class{bool} type.
- \versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{True}
- The true value of the \class{bool} type.
- \versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{None}
- The sole value of \member{\refmodule{types}.NoneType}. \code{None} is
- frequently used to represent the absence of a value, as when default
- arguments are not passed to a function.
-\end{datadesc}
-
-\begin{datadesc}{NotImplemented}
- Special value which can be returned by the ``rich comparison''
- special methods (\method{__eq__()}, \method{__lt__()}, and friends),
- to indicate that the comparison is not implemented with respect to
- the other type.
-\end{datadesc}
-
-\begin{datadesc}{Ellipsis}
- The same as \code{...}.
- Special value used mostly in conjunction with extended slicing syntax
- for user-defined container data types.
- % XXX Someone who understands extended slicing should fill in here.
-\end{datadesc}
diff --git a/Doc/lib/libcontextlib.tex b/Doc/lib/libcontextlib.tex
deleted file mode 100644
index 0ac5442..0000000
--- a/Doc/lib/libcontextlib.tex
+++ /dev/null
@@ -1,130 +0,0 @@
-\section{\module{contextlib} ---
- Utilities for \keyword{with}-statement contexts.}
-
-\declaremodule{standard}{contextlib}
-\modulesynopsis{Utilities for \keyword{with}-statement contexts.}
-
-\versionadded{2.5}
-
-This module provides utilities for common tasks involving the
-\keyword{with} statement.
-
-Functions provided:
-
-\begin{funcdesc}{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 \method{__enter__()} and
-\method{__exit__()} methods.
-
-A simple example (this is not recommended as a real way of
-generating HTML!):
-
-\begin{verbatim}
-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>
-\end{verbatim}
-
-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.
-\end{funcdesc}
-
-\begin{funcdesc}{nested}{mgr1\optional{, mgr2\optional{, ...}}}
-Combine multiple context managers into a single nested context manager.
-
-Code like this:
-
-\begin{verbatim}
-from contextlib import nested
-
-with nested(A, B, C) as (X, Y, Z):
- do_something()
-\end{verbatim}
-
-is equivalent to this:
-
-\begin{verbatim}
-with A as X:
- with B as Y:
- with C as Z:
- do_something()
-\end{verbatim}
-
-Note that if the \method{__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 \method{__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
-\method{__exit__()} methods of any remaining outer context managers.
-In general, \method{__exit__()} methods should avoid raising
-exceptions, and in particular they should not re-raise a
-passed-in exception.
-\end{funcdesc}
-
-\label{context-closing}
-\begin{funcdesc}{closing}{thing}
-Return a context manager that closes \var{thing} upon completion of
-the block. This is basically equivalent to:
-
-\begin{verbatim}
-from contextlib import contextmanager
-
-@contextmanager
-def closing(thing):
- try:
- yield thing
- finally:
- thing.close()
-\end{verbatim}
-
-And lets you write code like this:
-\begin{verbatim}
-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
-\end{verbatim}
-
-without needing to explicitly close \code{page}. Even if an error
-occurs, \code{page.close()} will be called when the \keyword{with}
-block is exited.
-\end{funcdesc}
-
-\begin{seealso}
- \seepep{0343}{The "with" statement}
- {The specification, background, and examples for the
- Python \keyword{with} statement.}
-\end{seealso}
diff --git a/Doc/lib/libcookie.tex b/Doc/lib/libcookie.tex
deleted file mode 100644
index e5d2038..0000000
--- a/Doc/lib/libcookie.tex
+++ /dev/null
@@ -1,260 +0,0 @@
-\section{\module{Cookie} ---
- HTTP state management}
-
-\declaremodule{standard}{Cookie}
-\modulesynopsis{Support for HTTP state management (cookies).}
-\moduleauthor{Timothy O'Malley}{timo@alum.mit.edu}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-
-
-The \module{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.
-
-\begin{excdesc}{CookieError}
-Exception failing because of \rfc{2109} invalidity: incorrect
-attributes, incorrect \mailheader{Set-Cookie} header, etc.
-\end{excdesc}
-
-\begin{classdesc}{BaseCookie}{\optional{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 \var{input} is given, it is passed to the \method{load()} method.
-\end{classdesc}
-
-\begin{classdesc}{SimpleCookie}{\optional{input}}
-This class derives from \class{BaseCookie} and overrides
-\method{value_decode()} and \method{value_encode()} to be the identity
-and \function{str()} respectively.
-\end{classdesc}
-
-\begin{classdesc}{SerialCookie}{\optional{input}}
-This class derives from \class{BaseCookie} and overrides
-\method{value_decode()} and \method{value_encode()} to be the
-\function{pickle.loads()} and \function{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.}
-\end{classdesc}
-
-\begin{classdesc}{SmartCookie}{\optional{input}}
-This class derives from \class{BaseCookie}. It overrides
-\method{value_decode()} to be \function{pickle.loads()} if it is a
-valid pickle, and otherwise the value itself. It overrides
-\method{value_encode()} to be \function{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.}
-\end{classdesc}
-
-A further security note is warranted. For backwards compatibility,
-the \module{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.
-
-
-\begin{seealso}
- \seemodule{cookielib}{HTTP cookie handling for web
- \emph{clients}. The \module{cookielib} and \module{Cookie}
- modules do not depend on each other.}
-
- \seerfc{2109}{HTTP State Management Mechanism}{This is the state
- management specification implemented by this module.}
-\end{seealso}
-
-
-\subsection{Cookie Objects \label{cookie-objects}}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{methoddesc}[BaseCookie]{value_encode}{val}
-Return an encoded value. \var{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 \method{value_encode()} and
-\method{value_decode()} are inverses on the range of \var{value_decode}.
-\end{methoddesc}
-
-\begin{methoddesc}[BaseCookie]{output}{\optional{attrs\optional{, header\optional{, sep}}}}
-Return a string representation suitable to be sent as HTTP headers.
-\var{attrs} and \var{header} are sent to each \class{Morsel}'s
-\method{output()} method. \var{sep} is used to join the headers
-together, and is by default the combination \code{'\e r\e n'} (CRLF).
-\versionchanged[The default separator has been changed from \code{'\e n'}
-to match the cookie specification]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[BaseCookie]{js_output}{\optional{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 \var{attrs} is the same as in \method{output()}.
-\end{methoddesc}
-
-\begin{methoddesc}[BaseCookie]{load}{rawdata}
-If \var{rawdata} is a string, parse it as an \code{HTTP_COOKIE} and add
-the values found there as \class{Morsel}s. If it is a dictionary, it
-is equivalent to:
-
-\begin{verbatim}
-for k, v in rawdata.items():
- cookie[k] = v
-\end{verbatim}
-\end{methoddesc}
-
-
-\subsection{Morsel Objects \label{morsel-objects}}
-
-\begin{classdesc}{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
-
-\begin{itemize}
-\item \code{expires}
-\item \code{path}
-\item \code{comment}
-\item \code{domain}
-\item \code{max-age}
-\item \code{secure}
-\item \code{version}
-\end{itemize}
-
-The keys are case-insensitive.
-\end{classdesc}
-
-\begin{memberdesc}[Morsel]{value}
-The value of the cookie.
-\end{memberdesc}
-
-\begin{memberdesc}[Morsel]{coded_value}
-The encoded value of the cookie --- this is what should be sent.
-\end{memberdesc}
-
-\begin{memberdesc}[Morsel]{key}
-The name of the cookie.
-\end{memberdesc}
-
-\begin{methoddesc}[Morsel]{set}{key, value, coded_value}
-Set the \var{key}, \var{value} and \var{coded_value} members.
-\end{methoddesc}
-
-\begin{methoddesc}[Morsel]{isReservedKey}{K}
-Whether \var{K} is a member of the set of keys of a \class{Morsel}.
-\end{methoddesc}
-
-\begin{methoddesc}[Morsel]{output}{\optional{attrs\optional{, header}}}
-Return a string representation of the Morsel, suitable
-to be sent as an HTTP header. By default, all the attributes are included,
-unless \var{attrs} is given, in which case it should be a list of attributes
-to use. \var{header} is by default \code{"Set-Cookie:"}.
-\end{methoddesc}
-
-\begin{methoddesc}[Morsel]{js_output}{\optional{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 \var{attrs} is the same as in \method{output()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Morsel]{OutputString}{\optional{attrs}}
-Return a string representing the Morsel, without any surrounding HTTP
-or JavaScript.
-
-The meaning for \var{attrs} is the same as in \method{output()}.
-\end{methoddesc}
-
-
-\subsection{Example \label{cookie-example}}
-
-The following example demonstrates how to use the \module{Cookie} module.
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
diff --git a/Doc/lib/libcookielib.tex b/Doc/lib/libcookielib.tex
deleted file mode 100644
index 2ea3554..0000000
--- a/Doc/lib/libcookielib.tex
+++ /dev/null
@@ -1,720 +0,0 @@
-\section{\module{cookielib} ---
- Cookie handling for HTTP clients}
-
-\declaremodule{standard}{cookielib}
-\moduleauthor{John J. Lee}{jjl@pobox.com}
-\sectionauthor{John J. Lee}{jjl@pobox.com}
-
-\versionadded{2.4}
-
-\modulesynopsis{Cookie handling for HTTP clients}
-
-The \module{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. \module{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 \code{max-age} and \code{port} cookie-attributes
-introduced with RFC 2965. \note{The various named parameters found in
-\mailheader{Set-Cookie} and \mailheader{Set-Cookie2} headers
-(eg. \code{domain} and \code{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:
-
-\begin{excdesc}{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 \exception{IOError}),
-\exception{LoadError} is a subclass of \exception{IOError}}.
-\end{excdesc}
-
-
-The following classes are provided:
-
-\begin{classdesc}{CookieJar}{policy=\constant{None}}
-\var{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.
-\end{classdesc}
-
-\begin{classdesc}{FileCookieJar}{filename, delayload=\constant{None},
- policy=\constant{None}}
-\var{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 \strong{NOT} loaded from the
-named file until either the \method{load()} or \method{revert()}
-method is called. Subclasses of this class are documented in section
-\ref{file-cookie-jar-classes}.
-\end{classdesc}
-
-\begin{classdesc}{CookiePolicy}{}
-This class is responsible for deciding whether each cookie should be
-accepted from / returned to the server.
-\end{classdesc}
-
-\begin{classdesc}{DefaultCookiePolicy}{
- blocked_domains=\constant{None},
- allowed_domains=\constant{None},
- netscape=\constant{True}, rfc2965=\constant{False},
- rfc2109_as_netscape=\constant{None},
- hide_cookie2=\constant{False},
- strict_domain=\constant{False},
- strict_rfc2965_unverifiable=\constant{True},
- strict_ns_unverifiable=\constant{False},
- strict_ns_domain=\constant{DefaultCookiePolicy.DomainLiberal},
- strict_ns_set_initial_dollar=\constant{False},
- strict_ns_set_path=\constant{False}
- }
-
-Constructor arguments should be passed as keyword arguments only.
-\var{blocked_domains} is a sequence of domain names that we never
-accept cookies from, nor return cookies to. \var{allowed_domains} if
-not \constant{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
-\member{rfc2109_as_netscape} is True, RFC 2109 cookies are
-'downgraded' by the \class{CookieJar} instance to Netscape cookies, by
-setting the \member{version} attribute of the \class{Cookie} instance
-to 0. \class{DefaultCookiePolicy} also provides some parameters to
-allow some fine-tuning of policy.
-\end{classdesc}
-
-\begin{classdesc}{Cookie}{}
-This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is
-not expected that users of \module{cookielib} construct their own
-\class{Cookie} instances. Instead, if necessary, call
-\method{make_cookies()} on a \class{CookieJar} instance.
-\end{classdesc}
-
-\begin{seealso}
-
-\seemodule{urllib2}{URL opening with automatic cookie handling.}
-
-\seemodule{Cookie}{HTTP cookie classes, principally useful for
-server-side code. The \module{cookielib} and \module{Cookie} modules
-do not depend on each other.}
-
-\seeurl{http://wwwsearch.sf.net/ClientCookie/}{Extensions to this
-module, including a class for reading Microsoft Internet Explorer
-cookies on Windows.}
-
-\seeurl{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 \module{cookielib}) only
-bears a passing resemblance to the one sketched out in
-\code{cookie_spec.html}.}
-
-\seerfc{2109}{HTTP State Management Mechanism}{Obsoleted by RFC 2965.
-Uses \mailheader{Set-Cookie} with version=1.}
-
-\seerfc{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.}
-
-\seeurl{http://kristol.org/cookie/errata.html}{Unfinished errata to
-RFC 2965.}
-
-\seerfc{2964}{Use of HTTP State Management}{}
-
-\end{seealso}
-
-
-\subsection{CookieJar and FileCookieJar Objects \label{cookie-jar-objects}}
-
-\class{CookieJar} objects support the iterator protocol for iterating
-over contained \class{Cookie} objects.
-
-\class{CookieJar} has the following methods:
-
-\begin{methoddesc}[CookieJar]{add_cookie_header}{request}
-Add correct \mailheader{Cookie} header to \var{request}.
-
-If policy allows (ie. the \member{rfc2965} and \member{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 \var{request} object (usually a \class{urllib2.Request} instance)
-must support the methods \method{get_full_url()}, \method{get_host()},
-\method{get_type()}, \method{unverifiable()},
-\method{get_origin_req_host()}, \method{has_header()},
-\method{get_header()}, \method{header_items()}, and
-\method{add_unredirected_header()},as documented by \module{urllib2}.
-\end{methoddesc}
-
-\begin{methoddesc}[CookieJar]{extract_cookies}{response, request}
-Extract cookies from HTTP \var{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 \var{response} argument,
-and store cookies as appropriate (subject to the
-\method{CookiePolicy.set_ok()} method's approval).
-
-The \var{response} object (usually the result of a call to
-\method{urllib2.urlopen()}, or similar) should support an
-\method{info()} method, which returns an object with a
-\method{getallmatchingheaders()} method (usually a
-\class{mimetools.Message} instance).
-
-The \var{request} object (usually a \class{urllib2.Request} instance)
-must support the methods \method{get_full_url()}, \method{get_host()},
-\method{unverifiable()}, and \method{get_origin_req_host()}, as
-documented by \module{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.
-\end{methoddesc}
-
-\begin{methoddesc}[CookieJar]{set_policy}{policy}
-Set the \class{CookiePolicy} instance to be used.
-\end{methoddesc}
-
-\begin{methoddesc}[CookieJar]{make_cookies}{response, request}
-Return sequence of \class{Cookie} objects extracted from
-\var{response} object.
-
-See the documentation for \method{extract_cookies} for the interfaces
-required of the \var{response} and \var{request} arguments.
-\end{methoddesc}
-
-\begin{methoddesc}[CookieJar]{set_cookie_if_ok}{cookie, request}
-Set a \class{Cookie} if policy says it's OK to do so.
-\end{methoddesc}
-
-\begin{methoddesc}[CookieJar]{set_cookie}{cookie}
-Set a \class{Cookie}, without checking with policy to see whether or
-not it should be set.
-\end{methoddesc}
-
-\begin{methoddesc}[CookieJar]{clear}{\optional{domain\optional{,
- path\optional{, name}}}}
-Clear some cookies.
-
-If invoked without arguments, clear all cookies. If given a single
-argument, only cookies belonging to that \var{domain} will be removed.
-If given two arguments, cookies belonging to the specified
-\var{domain} and URL \var{path} are removed. If given three
-arguments, then the cookie with the specified \var{domain}, \var{path}
-and \var{name} is removed.
-
-Raises \exception{KeyError} if no matching cookie exists.
-\end{methoddesc}
-
-\begin{methoddesc}[CookieJar]{clear_session_cookies}{}
-Discard all session cookies.
-
-Discards all contained cookies that have a true \member{discard}
-attribute (usually because they had either no \code{max-age} or
-\code{expires} cookie-attribute, or an explicit \code{discard}
-cookie-attribute). For interactive browsers, the end of a session
-usually corresponds to closing the browser window.
-
-Note that the \method{save()} method won't save session cookies
-anyway, unless you ask otherwise by passing a true
-\var{ignore_discard} argument.
-\end{methoddesc}
-
-\class{FileCookieJar} implements the following additional methods:
-
-\begin{methoddesc}[FileCookieJar]{save}{filename=\constant{None},
- ignore_discard=\constant{False}, ignore_expires=\constant{False}}
-Save cookies to a file.
-
-This base class raises \exception{NotImplementedError}. Subclasses may
-leave this method unimplemented.
-
-\var{filename} is the name of file in which to save cookies. If
-\var{filename} is not specified, \member{self.filename} is used (whose
-default is the value passed to the constructor, if any); if
-\member{self.filename} is \constant{None}, \exception{ValueError} is
-raised.
-
-\var{ignore_discard}: save even cookies set to be discarded.
-\var{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
-\method{load()} or \method{revert()} methods.
-\end{methoddesc}
-
-\begin{methoddesc}[FileCookieJar]{load}{filename=\constant{None},
- ignore_discard=\constant{False}, ignore_expires=\constant{False}}
-Load cookies from a file.
-
-Old cookies are kept unless overwritten by newly loaded ones.
-
-Arguments are as for \method{save()}.
-
-The named file must be in the format understood by the class, or
-\exception{LoadError} will be raised. Also, \exception{IOError} may
-be raised, for example if the file does not exist. \note{For
-backwards-compatibility with Python 2.4 (which raised
-an \exception{IOError}), \exception{LoadError} is a subclass
-of \exception{IOError}.}
-\end{methoddesc}
-
-\begin{methoddesc}[FileCookieJar]{revert}{filename=\constant{None},
- ignore_discard=\constant{False}, ignore_expires=\constant{False}}
-Clear all cookies and reload cookies from a saved file.
-
-\method{revert()} can raise the same exceptions as \method{load()}.
-If there is a failure, the object's state will not be altered.
-\end{methoddesc}
-
-\class{FileCookieJar} instances have the following public attributes:
-
-\begin{memberdesc}[FileCookieJar]{filename}
-Filename of default file in which to keep cookies. This attribute may
-be assigned to.
-\end{memberdesc}
-
-\begin{memberdesc}[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.
-\end{memberdesc}
-
-
-\subsection{FileCookieJar subclasses and co-operation with web browsers
- \label{file-cookie-jar-classes}}
-
-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
-\url{http://wwwsearch.sf.net/ClientCookie/}.
-
-\begin{classdesc}{MozillaCookieJar}{filename, delayload=\constant{None},
- policy=\constant{None}}
-A \class{FileCookieJar} that can load from and save cookies to disk in
-the Mozilla \code{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 \code{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.
-\end{classdesc}
-
-\begin{classdesc}{LWPCookieJar}{filename, delayload=\constant{None},
- policy=\constant{None}}
-A \class{FileCookieJar} that can load from and save cookies to disk in
-format compatible with the libwww-perl library's \code{Set-Cookie3}
-file format. This is convenient if you want to store cookies in a
-human-readable file.
-\end{classdesc}
-
-
-\subsection{CookiePolicy Objects \label{cookie-policy-objects}}
-
-Objects implementing the \class{CookiePolicy} interface have the
-following methods:
-
-\begin{methoddesc}[CookiePolicy]{set_ok}{cookie, request}
-Return boolean value indicating whether cookie should be accepted from server.
-
-\var{cookie} is a \class{cookielib.Cookie} instance. \var{request} is
-an object implementing the interface defined by the documentation for
-\method{CookieJar.extract_cookies()}.
-\end{methoddesc}
-
-\begin{methoddesc}[CookiePolicy]{return_ok}{cookie, request}
-Return boolean value indicating whether cookie should be returned to server.
-
-\var{cookie} is a \class{cookielib.Cookie} instance. \var{request} is
-an object implementing the interface defined by the documentation for
-\method{CookieJar.add_cookie_header()}.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \method{domain_return_ok()} and
-\method{path_return_ok()} leaves all the work to \method{return_ok()}.
-
-If \method{domain_return_ok()} returns true for the cookie domain,
-\method{path_return_ok()} is called for the cookie path. Otherwise,
-\method{path_return_ok()} and \method{return_ok()} are never called
-for that cookie domain. If \method{path_return_ok()} returns true,
-\method{return_ok()} is called with the \class{Cookie} object itself
-for a full check. Otherwise, \method{return_ok()} is never called for
-that cookie path.
-
-Note that \method{domain_return_ok()} is called for every
-\emph{cookie} domain, not just for the \emph{request} domain. For
-example, the function might be called with both \code{".example.com"}
-and \code{"www.example.com"} if the request domain is
-\code{"www.example.com"}. The same goes for
-\method{path_return_ok()}.
-
-The \var{request} argument is as documented for \method{return_ok()}.
-\end{methoddesc}
-
-\begin{methoddesc}[CookiePolicy]{path_return_ok}{path, request}
-Return false if cookies should not be returned, given cookie path.
-
-See the documentation for \method{domain_return_ok()}.
-\end{methoddesc}
-
-
-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.
-
-\begin{memberdesc}[CookiePolicy]{netscape}
-Implement Netscape protocol.
-\end{memberdesc}
-\begin{memberdesc}[CookiePolicy]{rfc2965}
-Implement RFC 2965 protocol.
-\end{memberdesc}
-\begin{memberdesc}[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).
-\end{memberdesc}
-
-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).
-
-
-\subsection{DefaultCookiePolicy Objects \label{default-cookie-policy-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:
-
-\begin{verbatim}
-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
-\end{verbatim}
-
-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 \var{blocked_domains} constructor argument, and
-\method{blocked_domains()} and \method{set_blocked_domains()} methods
-(and the corresponding argument and methods for
-\var{allowed_domains}). If you set a whitelist, you can turn it off
-again by setting it to \constant{None}.
-
-Domains in block or allow lists that do not start with a dot must
-equal the cookie domain to be matched. For example,
-\code{"example.com"} matches a blacklist entry of
-\code{"example.com"}, but \code{"www.example.com"} does not. Domains
-that do start with a dot are matched by more specific domains too.
-For example, both \code{"www.example.com"} and
-\code{"www.coyote.example.com"} match \code{".example.com"} (but
-\code{"example.com"} itself does not). IP addresses are an exception,
-and must match exactly. For example, if blocked_domains contains
-\code{"192.168.1.2"} and \code{".168.1.2"}, 192.168.1.2 is blocked,
-but 193.168.1.2 is not.
-
-\class{DefaultCookiePolicy} implements the following additional
-methods:
-
-\begin{methoddesc}[DefaultCookiePolicy]{blocked_domains}{}
-Return the sequence of blocked domains (as a tuple).
-\end{methoddesc}
-
-\begin{methoddesc}[DefaultCookiePolicy]{set_blocked_domains}
- {blocked_domains}
-Set the sequence of blocked domains.
-\end{methoddesc}
-
-\begin{methoddesc}[DefaultCookiePolicy]{is_blocked}{domain}
-Return whether \var{domain} is on the blacklist for setting or
-receiving cookies.
-\end{methoddesc}
-
-\begin{methoddesc}[DefaultCookiePolicy]{allowed_domains}{}
-Return \constant{None}, or the sequence of allowed domains (as a tuple).
-\end{methoddesc}
-
-\begin{methoddesc}[DefaultCookiePolicy]{set_allowed_domains}
- {allowed_domains}
-Set the sequence of allowed domains, or \constant{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[DefaultCookiePolicy]{is_not_allowed}{domain}
-Return whether \var{domain} is not on the whitelist for setting or
-receiving cookies.
-\end{methoddesc}
-
-\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.
-
-\begin{memberdesc}[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 \constant{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}
-\end{memberdesc}
-
-General strictness switches:
-
-\begin{memberdesc}[DefaultCookiePolicy]{strict_domain}
-Don't allow sites to set two-component domains with country-code
-top-level domains like \code{.co.uk}, \code{.gov.uk},
-\code{.co.nz}.etc. This is far from perfect and isn't guaranteed to
-work!
-\end{memberdesc}
-
-RFC 2965 protocol strictness switches:
-
-\begin{memberdesc}[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
-\emph{never} blocked on the basis of verifiability
-\end{memberdesc}
-
-Netscape protocol strictness switches:
-
-\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_unverifiable}
-apply RFC 2965 rules on unverifiable transactions even to Netscape
-cookies
-\end{memberdesc}
-\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_domain}
-Flags indicating how strict to be with domain-matching rules for
-Netscape cookies. See below for acceptable values.
-\end{memberdesc}
-\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_set_initial_dollar}
-Ignore cookies in Set-Cookie: headers that have names starting with
-\code{'\$'}.
-\end{memberdesc}
-\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_set_path}
-Don't allow setting cookies whose path doesn't path-match request URI.
-\end{memberdesc}
-
-\member{strict_ns_domain} is a collection of flags. Its value is
-constructed by or-ing together (for example,
-\code{DomainStrictNoDots|DomainStrictNonDomain} means both flags are
-set).
-
-\begin{memberdesc}[DefaultCookiePolicy]{DomainStrictNoDots}
-When setting cookies, the 'host prefix' must not contain a dot
-(eg. \code{www.foo.bar.com} can't set a cookie for \code{.bar.com},
-because \code{www.foo} contains a dot).
-\end{memberdesc}
-\begin{memberdesc}[DefaultCookiePolicy]{DomainStrictNonDomain}
-Cookies that did not explicitly specify a \code{domain}
-cookie-attribute can only be returned to a domain equal to the domain
-that set the cookie (eg. \code{spam.example.com} won't be returned
-cookies from \code{example.com} that had no \code{domain}
-cookie-attribute).
-\end{memberdesc}
-\begin{memberdesc}[DefaultCookiePolicy]{DomainRFC2965Match}
-When setting cookies, require a full RFC 2965 domain-match.
-\end{memberdesc}
-
-The following attributes are provided for convenience, and are the
-most useful combinations of the above flags:
-
-\begin{memberdesc}[DefaultCookiePolicy]{DomainLiberal}
-Equivalent to 0 (ie. all of the above Netscape domain strictness flags
-switched off).
-\end{memberdesc}
-\begin{memberdesc}[DefaultCookiePolicy]{DomainStrict}
-Equivalent to \code{DomainStrictNoDots|DomainStrictNonDomain}.
-\end{memberdesc}
-
-
-\subsection{Cookie Objects \label{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
-\code{max-age} and \code{expires} cookie-attributes contain equivalent
-information, and because RFC 2109 cookies may be 'downgraded' by
-\module{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.
-
-\begin{memberdesc}[Cookie]{version}
-Integer or \constant{None}. Netscape cookies have \member{version} 0.
-RFC 2965 and RFC 2109 cookies have a \code{version} cookie-attribute
-of 1. However, note that \module{cookielib} may 'downgrade' RFC 2109
-cookies to Netscape cookies, in which case \member{version} is 0.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{name}
-Cookie name (a string).
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{value}
-Cookie value (a string), or \constant{None}.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{port}
-String representing a port or a set of ports (eg. '80', or '80,8080'),
-or \constant{None}.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{path}
-Cookie path (a string, eg. \code{'/acme/rocket_launchers'}).
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{secure}
-True if cookie should only be returned over a secure connection.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{expires}
-Integer expiry date in seconds since epoch, or \constant{None}. See
-also the \method{is_expired()} method.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{discard}
-True if this is a session cookie.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{comment}
-String comment from the server explaining the function of this cookie,
-or \constant{None}.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{comment_url}
-URL linking to a comment from the server explaining the function of
-this cookie, or \constant{None}.
-\end{memberdesc}
-\begin{memberdesc}[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 \module{cookielib} may 'downgrade' RFC 2109 cookies
-to Netscape cookies, in which case \member{version} is 0.
-\versionadded{2.5}
-\end{memberdesc}
-
-\begin{memberdesc}[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).
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{domain_specified}
-True if a domain was explicitly specified by the server.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{domain_initial_dot}
-True if the domain explicitly specified by the server began with a
-dot (\code{'.'}).
-\end{memberdesc}
-
-Cookies may have additional non-standard cookie-attributes. These may
-be accessed using the following methods:
-
-\begin{methoddesc}[Cookie]{has_nonstandard_attr}{name}
-Return true if cookie has the named cookie-attribute.
-\end{methoddesc}
-\begin{methoddesc}[Cookie]{get_nonstandard_attr}{name, default=\constant{None}}
-If cookie has the named cookie-attribute, return its value.
-Otherwise, return \var{default}.
-\end{methoddesc}
-\begin{methoddesc}[Cookie]{set_nonstandard_attr}{name, value}
-Set the value of the named cookie-attribute.
-\end{methoddesc}
-
-The \class{Cookie} class also defines the following method:
-
-\begin{methoddesc}[Cookie]{is_expired}{\optional{now=\constant{None}}}
-True if cookie has passed the time at which the server requested it
-should expire. If \var{now} is given (in seconds since the epoch),
-return whether the cookie has expired at the specified time.
-\end{methoddesc}
-
-
-\subsection{Examples \label{cookielib-examples}}
-
-The first example shows the most common usage of \module{cookielib}:
-
-\begin{verbatim}
-import cookielib, urllib2
-cj = cookielib.CookieJar()
-opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
-r = opener.open("http://example.com/")
-\end{verbatim}
-
-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):
-
-\begin{verbatim}
-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/")
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-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/")
-\end{verbatim}
diff --git a/Doc/lib/libcopy.tex b/Doc/lib/libcopy.tex
deleted file mode 100644
index 5964187..0000000
--- a/Doc/lib/libcopy.tex
+++ /dev/null
@@ -1,97 +0,0 @@
-\section{\module{copy} ---
- Shallow and deep copy operations}
-
-\declaremodule{standard}{copy}
-\modulesynopsis{Shallow and deep copy operations.}
-
-
-This module provides generic (shallow and deep) copying operations.
-\withsubitem{(in copy)}{\ttindex{copy()}\ttindex{deepcopy()}}
-
-Interface summary:
-
-\begin{verbatim}
-import copy
-
-x = copy.copy(y) # make a shallow copy of y
-x = copy.deepcopy(y) # make a deep copy of y
-\end{verbatim}
-%
-For module specific errors, \exception{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):
-
-\begin{itemize}
-
-\item
-A \emph{shallow copy} constructs a new compound object and then (to the
-extent possible) inserts \emph{references} into it to the objects found
-in the original.
-
-\item
-A \emph{deep copy} constructs a new compound object and then,
-recursively, inserts \emph{copies} into it of the objects found in the
-original.
-
-\end{itemize}
-
-Two problems often exist with deep copy operations that don't exist
-with shallow copy operations:
-
-\begin{itemize}
-
-\item
-Recursive objects (compound objects that, directly or indirectly,
-contain a reference to themselves) may cause a recursive loop.
-
-\item
-Because deep copy copies \emph{everything} it may copy too much,
-e.g., administrative data structures that should be shared even
-between copies.
-
-\end{itemize}
-
-The \function{deepcopy()} function avoids these problems by:
-
-\begin{itemize}
-
-\item
-keeping a ``memo'' dictionary of objects already copied during the current
-copying pass; and
-
-\item
-letting user-defined classes override the copying operation or the
-set of components copied.
-
-\end{itemize}
-
-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 \module{pickle} module.
-\versionchanged[Added copying functions]{2.5}
-
-Classes can use the same interfaces to control copying that they use
-to control pickling. See the description of module
-\refmodule{pickle}\refstmodindex{pickle} for information on these
-methods. The \module{copy} module does not use the
-\refmodule[copyreg]{copy_reg} registration module.
-
-In order for a class to define its own copy implementation, it can
-define special methods \method{__copy__()} and
-\method{__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 \method{__deepcopy__()}
-implementation needs to make a deep copy of a component, it should
-call the \function{deepcopy()} function with the component as first
-argument and the memo dictionary as second argument.
-\withsubitem{(copy protocol)}{\ttindex{__copy__()}\ttindex{__deepcopy__()}}
-
-\begin{seealso}
-\seemodule{pickle}{Discussion of the special methods used to
-support object state retrieval and restoration.}
-\end{seealso}
diff --git a/Doc/lib/libcopyreg.tex b/Doc/lib/libcopyreg.tex
deleted file mode 100644
index 594978c..0000000
--- a/Doc/lib/libcopyreg.tex
+++ /dev/null
@@ -1,40 +0,0 @@
-\section{\module{copy_reg} ---
- Register \module{pickle} support functions}
-
-\declaremodule[copyreg]{standard}{copy_reg}
-\modulesynopsis{Register \module{pickle} support functions.}
-
-
-The \module{copy_reg} module provides support for the
-\refmodule{pickle}\refstmodindex{pickle}\ and
-\refmodule{cPickle}\refbimodindex{cPickle}\ modules. The
-\refmodule{copy}\refstmodindex{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.
-
-
-\begin{funcdesc}{constructor}{object}
- Declares \var{object} to be a valid constructor. If \var{object} is
- not callable (and hence not valid as a constructor), raises
- \exception{TypeError}.
-\end{funcdesc}
-
-\begin{funcdesc}{pickle}{type, function\optional{, constructor}}
- Declares that \var{function} should be used as a ``reduction''
- function for objects of type \var{type}; \var{type} must not be a
- ``classic'' class object. (Classic classes are handled differently;
- see the documentation for the \refmodule{pickle} module for
- details.) \var{function} should return either a string or a tuple
- containing two or three elements.
-
- The optional \var{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 \var{function} at
- pickling time. \exception{TypeError} will be raised if
- \var{object} is a class or \var{constructor} is not callable.
-
- See the \refmodule{pickle} module for more
- details on the interface expected of \var{function} and
- \var{constructor}.
-\end{funcdesc}
diff --git a/Doc/lib/libcrypt.tex b/Doc/lib/libcrypt.tex
deleted file mode 100644
index 55e7163..0000000
--- a/Doc/lib/libcrypt.tex
+++ /dev/null
@@ -1,60 +0,0 @@
-\section{\module{crypt} ---
- Function to check \UNIX{} passwords}
-
-\declaremodule{builtin}{crypt}
- \platform{Unix}
-\modulesynopsis{The \cfunction{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}
-
-
-This module implements an interface to the
-\manpage{crypt}{3}\index{crypt(3)} routine, which is a one-way hash
-function based upon a modified DES\indexii{cipher}{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.
-
-Notice that the behavior of this module depends on the actual implementation
-of the \manpage{crypt}{3}\index{crypt(3)} routine in the running system.
-Therefore, any extensions available on the current implementation will also
-be available on this module.
-\begin{funcdesc}{crypt}{word, salt}
- \var{word} will usually be a user's password as typed at a prompt or
- in a graphical interface. \var{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 \var{salt} must be in the
- set \regexp{[./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).
-
- Since a few \manpage{crypt}{3}\index{crypt(3)} extensions allow different
- values, with different sizes in the \var{salt}, it is recommended to use
- the full crypted password as salt when checking for a password.
-\end{funcdesc}
-
-
-A simple example illustrating typical use:
-
-\begin{verbatim}
-import crypt, getpass, pwd
-
-def raw_input(prompt):
- import sys
- sys.stdout.write(prompt)
- sys.stdout.flush()
- return sys.stdin.readline()
-
-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
-\end{verbatim}
diff --git a/Doc/lib/libcrypto.tex b/Doc/lib/libcrypto.tex
deleted file mode 100644
index 75987bf..0000000
--- a/Doc/lib/libcrypto.tex
+++ /dev/null
@@ -1,19 +0,0 @@
-\chapter{Cryptographic Services}
-\label{crypto}
-\index{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:
-
-\localmoduletable
-
-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
-\url{http://www.amk.ca/python/code/crypto.html}
-for more information.
-\indexii{AES}{algorithm}
-\index{cryptography}
-\index{Kuchling, Andrew}
diff --git a/Doc/lib/libcsv.tex b/Doc/lib/libcsv.tex
deleted file mode 100644
index 54fc8db..0000000
--- a/Doc/lib/libcsv.tex
+++ /dev/null
@@ -1,538 +0,0 @@
-\section{\module{csv} --- CSV File Reading and Writing}
-
-\declaremodule{standard}{csv}
-\modulesynopsis{Write and read tabular data to and from delimited files.}
-\sectionauthor{Skip Montanaro}{skip@pobox.com}
-
-\versionadded{2.3}
-\index{csv}
-\indexii{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 \module{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 \module{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.
-
-\begin{notice}
- This version of the \module{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.
-\end{notice}
-
-\begin{seealso}
-% \seemodule{array}{Arrays of uniformly types numeric values.}
- \seepep{305}{CSV File API}
- {The Python Enhancement Proposal which proposed this addition
- to Python.}
-\end{seealso}
-
-
-\subsection{Module Contents \label{csv-contents}}
-
-The \module{csv} module defines the following functions:
-
-\begin{funcdesc}{reader}{csvfile\optional{,
- dialect=\code{'excel'}}\optional{, fmtparam}}
-Return a reader object which will iterate over lines in the given
-{}\var{csvfile}. \var{csvfile} can be any object which supports the
-iterator protocol and returns a string each time its \method{next}
-method is called --- file objects and list objects are both suitable.
-If \var{csvfile} is a file object, it must be opened with
-the 'b' flag on platforms where that makes a difference. An optional
-{}\var{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 \function{list_dialects}
-function. The other optional {}\var{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}, ``Dialects and Formatting
-Parameters''.
-
-All data read are returned as strings. No automatic data type
-conversion is performed.
-
-\versionchanged[
-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]{2.5}
-
-\end{funcdesc}
-
-\begin{funcdesc}{writer}{csvfile\optional{,
- dialect=\code{'excel'}}\optional{, fmtparam}}
-Return a writer object responsible for converting the user's data into
-delimited strings on the given file-like object. \var{csvfile} can be any
-object with a \function{write} method. If \var{csvfile} is a file object,
-it must be opened with the 'b' flag on platforms where that makes a
-difference. An optional
-{}\var{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 \function{list_dialects} function. The other optional
-{}\var{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}, ``Dialects and Formatting Parameters''.
-To make it as easy as possible to
-interface with modules which implement the DB API, the value
-\constant{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
-\code{cursor.fetch*()} call. All other non-string data are stringified
-with \function{str()} before being written.
-\end{funcdesc}
-
-\begin{funcdesc}{register_dialect}{name\optional{, dialect}\optional{, fmtparam}}
-Associate \var{dialect} with \var{name}. \var{name} must be a string
-or Unicode object. The dialect can be specified either by passing a
-sub-class of \class{Dialect}, or by \var{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}, ``Dialects and Formatting Parameters''.
-\end{funcdesc}
-
-\begin{funcdesc}{unregister_dialect}{name}
-Delete the dialect associated with \var{name} from the dialect registry. An
-\exception{Error} is raised if \var{name} is not a registered dialect
-name.
-\end{funcdesc}
-
-\begin{funcdesc}{get_dialect}{name}
-Return the dialect associated with \var{name}. An \exception{Error} is
-raised if \var{name} is not a registered dialect name.
-\end{funcdesc}
-
-\begin{funcdesc}{list_dialects}{}
-Return the names of all registered dialects.
-\end{funcdesc}
-
-\begin{funcdesc}{field_size_limit}{\optional{new_limit}}
- Returns the current maximum field size allowed by the parser. If
- \var{new_limit} is given, this becomes the new limit.
- \versionadded{2.5}
-\end{funcdesc}
-
-
-The \module{csv} module defines the following classes:
-
-\begin{classdesc}{DictReader}{csvfile\optional{,
- fieldnames=\constant{None},\optional{,
- restkey=\constant{None}\optional{,
- restval=\constant{None}\optional{,
- dialect=\code{'excel'}\optional{,
- *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
-{} \var{fieldnames}
-parameter. If the \var{fieldnames} parameter is omitted, the values in
-the first row of the \var{csvfile} will be used as the fieldnames.
-If the row read has fewer fields than the fieldnames sequence,
-the value of \var{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 \var{restkey}. If the row read
-has fewer fields than the fieldnames sequence, the remaining keys take the
-value of the optional \var{restval} parameter. Any other optional or
-keyword arguments are passed to the underlying \class{reader} instance.
-\end{classdesc}
-
-
-\begin{classdesc}{DictWriter}{csvfile, fieldnames\optional{,
- restval=""\optional{,
- extrasaction=\code{'raise'}\optional{,
- dialect=\code{'excel'}\optional{,
- *args, **kwds}}}}}
-Create an object which operates like a regular writer but maps dictionaries
-onto output rows. The \var{fieldnames} parameter identifies the order in
-which values in the dictionary passed to the \method{writerow()} method are
-written to the \var{csvfile}. The optional \var{restval} parameter
-specifies the value to be written if the dictionary is missing a key in
-\var{fieldnames}. If the dictionary passed to the \method{writerow()}
-method contains a key not found in \var{fieldnames}, the optional
-\var{extrasaction} parameter indicates what action to take. If it is set
-to \code{'raise'} a \exception{ValueError} is raised. If it is set to
-\code{'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 \var{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
-\var{csvfile}.
-
-\end{classdesc}
-
-\begin{classdesc*}{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.
-\end{classdesc*}
-
-\begin{classdesc}{excel}{}
-The \class{excel} class defines the usual properties of an Excel-generated
-CSV file. It is registered with the dialect name \code{'excel'}.
-\end{classdesc}
-
-\begin{classdesc}{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
-\code{'excel-tab'}.
-\end{classdesc}
-
-\begin{classdesc}{Sniffer}{}
-The \class{Sniffer} class is used to deduce the format of a CSV file.
-\end{classdesc}
-
-The \class{Sniffer} class provides two methods:
-
-\begin{methoddesc}{sniff}{sample\optional{,delimiters=None}}
-Analyze the given \var{sample} and return a \class{Dialect} subclass
-reflecting the parameters found. If the optional \var{delimiters} parameter
-is given, it is interpreted as a string containing possible valid delimiter
-characters.
-\end{methoddesc}
-
-\begin{methoddesc}{has_header}{sample}
-Analyze the sample text (presumed to be in CSV format) and return
-\constant{True} if the first row appears to be a series of column
-headers.
-\end{methoddesc}
-
-
-The \module{csv} module defines the following constants:
-
-\begin{datadesc}{QUOTE_ALL}
-Instructs \class{writer} objects to quote all fields.
-\end{datadesc}
-
-\begin{datadesc}{QUOTE_MINIMAL}
-Instructs \class{writer} objects to only quote those fields which contain
-special characters such as \var{delimiter}, \var{quotechar} or any of the
-characters in \var{lineterminator}.
-\end{datadesc}
-
-\begin{datadesc}{QUOTE_NONNUMERIC}
-Instructs \class{writer} objects to quote all non-numeric
-fields.
-
-Instructs the reader to convert all non-quoted fields to type \var{float}.
-\end{datadesc}
-
-\begin{datadesc}{QUOTE_NONE}
-Instructs \class{writer} objects to never quote fields. When the current
-\var{delimiter} occurs in output data it is preceded by the current
-\var{escapechar} character. If \var{escapechar} is not set, the writer
-will raise \exception{Error} if any characters that require escaping
-are encountered.
-
-Instructs \class{reader} to perform no special processing of quote characters.
-\end{datadesc}
-
-
-The \module{csv} module defines the following exception:
-
-\begin{excdesc}{Error}
-Raised by any of the functions when an error is detected.
-\end{excdesc}
-
-
-\subsection{Dialects and Formatting Parameters\label{csv-fmt-params}}
-
-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 \method{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 \var{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:
-
-\begin{memberdesc}[Dialect]{delimiter}
-A one-character string used to separate fields. It defaults to \code{','}.
-\end{memberdesc}
-
-\begin{memberdesc}[Dialect]{doublequote}
-Controls how instances of \var{quotechar} appearing inside a field should
-be themselves be quoted. When \constant{True}, the character is doubled.
-When \constant{False}, the \var{escapechar} is used as a prefix to the
-\var{quotechar}. It defaults to \constant{True}.
-
-On output, if \var{doublequote} is \constant{False} and no
-\var{escapechar} is set, \exception{Error} is raised if a \var{quotechar}
-is found in a field.
-\end{memberdesc}
-
-\begin{memberdesc}[Dialect]{escapechar}
-A one-character string used by the writer to escape the \var{delimiter} if
-\var{quoting} is set to \constant{QUOTE_NONE} and the \var{quotechar}
-if \var{doublequote} is \constant{False}. On reading, the \var{escapechar}
-removes any special meaning from the following character. It defaults
-to \constant{None}, which disables escaping.
-\end{memberdesc}
-
-\begin{memberdesc}[Dialect]{lineterminator}
-The string used to terminate lines produced by the \class{writer}.
-It defaults to \code{'\e r\e n'}.
-
-\note{The \class{reader} is hard-coded to recognise either \code{'\e r'}
-or \code{'\e n'} as end-of-line, and ignores \var{lineterminator}. This
-behavior may change in the future.}
-\end{memberdesc}
-
-\begin{memberdesc}[Dialect]{quotechar}
-A one-character string used to quote fields containing special characters,
-such as the \var{delimiter} or \var{quotechar}, or which contain new-line
-characters. It defaults to \code{'"'}.
-\end{memberdesc}
-
-\begin{memberdesc}[Dialect]{quoting}
-Controls when quotes should be generated by the writer and recognised
-by the reader. It can take on any of the \constant{QUOTE_*} constants
-(see section~\ref{csv-contents}) and defaults to \constant{QUOTE_MINIMAL}.
-\end{memberdesc}
-
-\begin{memberdesc}[Dialect]{skipinitialspace}
-When \constant{True}, whitespace immediately following the \var{delimiter}
-is ignored. The default is \constant{False}.
-\end{memberdesc}
-
-
-\subsection{Reader Objects}
-
-Reader objects (\class{DictReader} instances and objects returned by
-the \function{reader()} function) have the following public methods:
-
-\begin{methoddesc}[csv reader]{next}{}
-Return the next row of the reader's iterable object as a list, parsed
-according to the current dialect.
-\end{methoddesc}
-
-Reader objects have the following public attributes:
-
-\begin{memberdesc}[csv reader]{dialect}
-A read-only description of the dialect in use by the parser.
-\end{memberdesc}
-
-\begin{memberdesc}[csv reader]{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}
-\end{memberdesc}
-
-
-\subsection{Writer Objects}
-
-\class{Writer} objects (\class{DictWriter} instances and objects returned by
-the \function{writer()} function) have the following public methods. A
-{}\var{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 \function{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).
-
-\begin{methoddesc}[csv writer]{writerow}{row}
-Write the \var{row} parameter to the writer's file object, formatted
-according to the current dialect.
-\end{methoddesc}
-
-\begin{methoddesc}[csv writer]{writerows}{rows}
-Write all the \var{rows} parameters (a list of \var{row} objects as
-described above) to the writer's file object, formatted
-according to the current dialect.
-\end{methoddesc}
-
-Writer objects have the following public attribute:
-
-\begin{memberdesc}[csv writer]{dialect}
-A read-only description of the dialect in use by the writer.
-\end{memberdesc}
-
-
-
-\subsection{Examples\label{csv-examples}}
-
-The simplest example of reading a CSV file:
-
-\begin{verbatim}
-import csv
-reader = csv.reader(open("some.csv", "rb"))
-for row in reader:
- print row
-\end{verbatim}
-
-Reading a file with an alternate format:
-
-\begin{verbatim}
-import csv
-reader = csv.reader(open("passwd", "rb"), delimiter=':', quoting=csv.QUOTE_NONE)
-for row in reader:
- print row
-\end{verbatim}
-
-The corresponding simplest possible writing example is:
-
-\begin{verbatim}
-import csv
-writer = csv.writer(open("some.csv", "wb"))
-writer.writerows(someiterable)
-\end{verbatim}
-
-Registering a new dialect:
-
-\begin{verbatim}
-import csv
-
-csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
-
-reader = csv.reader(open("passwd", "rb"), 'unixpwd')
-\end{verbatim}
-
-A slightly more advanced use of the reader --- catching and reporting errors:
-
-\begin{verbatim}
-import csv, sys
-filename = "some.csv"
-reader = csv.reader(open(filename, "rb"))
-try:
- for row in reader:
- print row
-except csv.Error as e:
- sys.exit('file %s, line %d: %s' % (filename, reader.line_num, e))
-\end{verbatim}
-
-And while the module doesn't directly support parsing strings, it can
-easily be done:
-
-\begin{verbatim}
-import csv
-for row in csv.reader(['one,two,three']):
- print row
-\end{verbatim}
-
-The \module{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.
-
-\function{unicode_csv_reader} below is a generator that wraps
-\class{csv.reader} to handle Unicode CSV data (a list of Unicode
-strings). \function{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
-\function{unicode_csv_reader} decodes the UTF-8-encoded cells back
-into Unicode:
-
-\begin{verbatim}
-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')
-\end{verbatim}
-
-For all other encodings the following \class{UnicodeReader} and
-\class{UnicodeWriter} classes can be used. They take an additional
-\var{encoding} parameter in their constructor and make sure that the data
-passes the real reader or writer encoded as UTF-8:
-
-\begin{verbatim}
-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 next(self.reader).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 = next(self.reader)
- 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)
-\end{verbatim}
diff --git a/Doc/lib/libctypes.tex b/Doc/lib/libctypes.tex
deleted file mode 100755
index 346863d..0000000
--- a/Doc/lib/libctypes.tex
+++ /dev/null
@@ -1,2450 +0,0 @@
-\ifx\locallinewidth\undefined\newlength{\locallinewidth}\fi
-\setlength{\locallinewidth}{\linewidth}
-\section{\module{ctypes} --- A foreign function library for Python.}
-\declaremodule{standard}{ctypes}
-\moduleauthor{Thomas Heller}{theller@python.net}
-\modulesynopsis{A foreign function library for Python.}
-\versionadded{2.5}
-
-\code{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.
-
-
-\subsection{ctypes tutorial\label{ctypes-ctypes-tutorial}}
-
-Note: The code samples in this tutorial use \code{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.
-
-
-\subsubsection{Loading dynamic link libraries\label{ctypes-loading-dynamic-link-libraries}}
-
-\code{ctypes} exports the \var{cdll}, and on Windows also \var{windll} and
-\var{oledll} objects to load dynamic link libraries.
-
-You load libraries by accessing them as attributes of these objects.
-\var{cdll} loads libraries which export functions using the standard
-\code{cdecl} calling convention, while \var{windll} libraries call
-functions using the \code{stdcall} calling convention. \var{oledll} also
-uses the \code{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 \code{msvcrt} is the MS
-standard C library containing most standard C functions, and uses the
-cdecl calling convention:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-Windows appends the usual '.dll' file suffix automatically.
-
-On Linux, it is required to specify the filename \emph{including} the
-extension to load a library, so attribute access does not work.
-Either the \method{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:
-\begin{verbatim}
->>> 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 ...>
->>>
-\end{verbatim}
-% XXX Add section for Mac OS X.
-
-
-\subsubsection{Accessing functions from loaded dlls\label{ctypes-accessing-functions-from-loaded-dlls}}
-
-Functions are accessed as attributes of dll objects:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-Note that win32 system dlls like \code{kernel32} and \code{user32} often
-export ANSI as well as UNICODE versions of a function. The UNICODE
-version is exported with an \code{W} appended to the name, while the ANSI
-version is exported with an \code{A} appended to the name. The win32
-\code{GetModuleHandle} function, which returns a \emph{module handle} for a
-given module name, has the following C prototype, and a macro is used
-to expose one of them as \code{GetModuleHandle} depending on whether
-UNICODE is defined or not:
-\begin{verbatim}
-/* ANSI version */
-HMODULE GetModuleHandleA(LPCSTR lpModuleName);
-/* UNICODE version */
-HMODULE GetModuleHandleW(LPCWSTR lpModuleName);
-\end{verbatim}
-
-\var{windll} does not try to select one of them by magic, you must
-access the version you need by specifying \code{GetModuleHandleA} or
-\code{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 \code{"??2@YAPAXI@Z"}. In this case you have to use
-\code{getattr} to retrieve the function:
-\begin{verbatim}
->>> getattr(cdll.msvcrt, "??2@YAPAXI@Z") # doctest: +WINDOWS
-<_FuncPtr object at 0x...>
->>>
-\end{verbatim}
-
-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:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-
-\subsubsection{Calling functions\label{ctypes-calling-functions}}
-
-You can call these functions like any other Python callable. This
-example uses the \code{time()} function, which returns system time in
-seconds since the \UNIX{} epoch, and the \code{GetModuleHandleA()} function,
-which returns a win32 module handle.
-
-This example calls both functions with a NULL pointer (\code{None} should
-be used as the NULL pointer):
-\begin{verbatim}
->>> print libc.time(None) # doctest: +SKIP
-1150640792
->>> print hex(windll.kernel32.GetModuleHandleA(None)) # doctest: +WINDOWS
-0x1d000000
->>>
-\end{verbatim}
-
-\code{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
-\emph{has} been called:
-\begin{verbatim}
->>> 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)
->>>
-\end{verbatim}
-
-The same exception is raised when you call an \code{stdcall} function
-with the \code{cdecl} calling convention, or vice versa:
-\begin{verbatim}
->>> 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)
->>>
-\end{verbatim}
-
-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, \code{ctypes} uses win32 structured exception handling to
-prevent crashes from general protection faults when functions are
-called with invalid argument values:
-\begin{verbatim}
->>> windll.kernel32.GetModuleHandleA(32) # doctest: +WINDOWS
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-WindowsError: exception: access violation reading 0x00000020
->>>
-\end{verbatim}
-
-There are, however, enough ways to crash Python with \code{ctypes}, so
-you should be careful anyway.
-
-\code{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. \code{None} is passed as a C \code{NULL} pointer,
-byte strings and unicode strings are passed as pointer to the memory
-block that contains their data (\code{char *} or \code{wchar{\_}t *}). Python
-integers and Python longs are passed as the platforms default C
-\code{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 \code{ctypes} data types.
-
-
-\subsubsection{Fundamental data types\label{ctypes-fundamental-data-types}}
-
-\code{ctypes} defines a number of primitive C compatible data types :
-\begin{quote}
-\begin{tableiii}{l|l|l}{textrm}
-{
-ctypes type
-}
-{
-C type
-}
-{
-Python type
-}
-\lineiii{
-\class{c{\_}char}
-}
-{
-\code{char}
-}
-{
-1-character
-string
-}
-\lineiii{
-\class{c{\_}wchar}
-}
-{
-\code{wchar{\_}t}
-}
-{
-1-character
-unicode string
-}
-\lineiii{
-\class{c{\_}byte}
-}
-{
-\code{char}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}ubyte}
-}
-{
-\code{unsigned char}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}short}
-}
-{
-\code{short}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}ushort}
-}
-{
-\code{unsigned short}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}int}
-}
-{
-\code{int}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}uint}
-}
-{
-\code{unsigned int}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}long}
-}
-{
-\code{long}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}ulong}
-}
-{
-\code{unsigned long}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}longlong}
-}
-{
-\code{{\_}{\_}int64} or
-\code{long long}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}ulonglong}
-}
-{
-\code{unsigned {\_}{\_}int64} or
-\code{unsigned long long}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}float}
-}
-{
-\code{float}
-}
-{
-float
-}
-\lineiii{
-\class{c{\_}double}
-}
-{
-\code{double}
-}
-{
-float
-}
-\lineiii{
-\class{c{\_}char{\_}p}
-}
-{
-\code{char *}
-(NUL terminated)
-}
-{
-string or
-\code{None}
-}
-\lineiii{
-\class{c{\_}wchar{\_}p}
-}
-{
-\code{wchar{\_}t *}
-(NUL terminated)
-}
-{
-unicode or
-\code{None}
-}
-\lineiii{
-\class{c{\_}void{\_}p}
-}
-{
-\code{void *}
-}
-{
-int/long
-or \code{None}
-}
-\end{tableiii}
-\end{quote}
-
-All these types can be created by calling them with an optional
-initializer of the correct type and value:
-\begin{verbatim}
->>> c_int()
-c_long(0)
->>> c_char_p("Hello, World")
-c_char_p('Hello, World')
->>> c_ushort(-3)
-c_ushort(65533)
->>>
-\end{verbatim}
-
-Since these types are mutable, their value can also be changed
-afterwards:
-\begin{verbatim}
->>> i = c_int(42)
->>> print i
-c_long(42)
->>> print i.value
-42
->>> i.value = -99
->>> print i.value
--99
->>>
-\end{verbatim}
-
-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 \emph{memory location} they
-point to, \emph{not the contents} of the memory block (of course not,
-because Python strings are immutable):
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-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 \code{create{\_}string{\_}buffer} function which creates
-these in various ways. The current memory block contents can be
-accessed (or changed) with the \code{raw} property; if you want to access
-it as NUL terminated string, use the \code{value} property:
-\begin{verbatim}
->>> 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'
->>>
-\end{verbatim}
-
-The \code{create{\_}string{\_}buffer} function replaces the \code{c{\_}buffer}
-function (which is still available as an alias), as well as the
-\code{c{\_}string} function from earlier ctypes releases. To create a
-mutable memory block containing unicode characters of the C type
-\code{wchar{\_}t} use the \code{create{\_}unicode{\_}buffer} function.
-
-
-\subsubsection{Calling functions, continued\label{ctypes-calling-functions-continued}}
-
-Note that printf prints to the real standard output channel, \emph{not} to
-\code{sys.stdout}, so these examples will only work at the console
-prompt, not from within \emph{IDLE} or \emph{PythonWin}:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-As has been mentioned before, all Python types except integers,
-strings, and unicode strings have to be wrapped in their corresponding
-\code{ctypes} type, so that they can be converted to the required C data
-type:
-\begin{verbatim}
->>> printf("An int %d, a double %f\n", 1234, c_double(3.14))
-Integer 1234, double 3.1400001049
-31
->>>
-\end{verbatim}
-
-
-\subsubsection{Calling functions with your own custom data types\label{ctypes-calling-functions-with-own-custom-data-types}}
-
-You can also customize \code{ctypes} argument conversion to allow
-instances of your own classes be used as function arguments.
-\code{ctypes} looks for an \member{{\_}as{\_}parameter{\_}} attribute and uses this as
-the function argument. Of course, it must be one of integer, string,
-or unicode:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-If you don't want to store the instance's data in the
-\member{{\_}as{\_}parameter{\_}} instance variable, you could define a \code{property}
-which makes the data avaiblable.
-
-
-\subsubsection{Specifying the required argument types (function prototypes)\label{ctypes-specifying-required-argument-types}}
-
-It is possible to specify the required argument types of functions
-exported from DLLs by setting the \member{argtypes} attribute.
-
-\member{argtypes} must be a sequence of C data types (the \code{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):
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-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:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-If you have defined your own classes which you pass to function calls,
-you have to implement a \method{from{\_}param} class method for them to be
-able to use them in the \member{argtypes} sequence. The \method{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
-\member{{\_}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 \code{ctypes} instance, or something having
-the \member{{\_}as{\_}parameter{\_}} attribute.
-
-
-\subsubsection{Return types\label{ctypes-return-types}}
-
-By default functions are assumed to return the C \code{int} type. Other
-return types can be specified by setting the \member{restype} attribute of
-the function object.
-
-Here is a more advanced example, it uses the \code{strchr} function, which
-expects a string pointer and a char, and returns a pointer to a
-string:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-If you want to avoid the \code{ord("x")} calls above, you can set the
-\member{argtypes} attribute, and the second argument will be converted from
-a single character Python string into a C char:
-\begin{verbatim}
->>> 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'
->>>
-\end{verbatim}
-
-You can also use a callable Python object (a function or a class for
-example) as the \member{restype} attribute, if the foreign function returns
-an integer. The callable will be called with the \code{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:
-\begin{verbatim}
->>> 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.
->>>
-\end{verbatim}
-
-\code{WinError} is a function which will call Windows \code{FormatMessage()}
-api to get the string representation of an error code, and \emph{returns}
-an exception. \code{WinError} takes an optional error code parameter, if
-no one is used, it calls \function{GetLastError()} to retrieve it.
-
-Please note that a much more powerful error checking mechanism is
-available through the \member{errcheck} attribute; see the reference manual
-for details.
-
-
-\subsubsection{Passing pointers (or: passing parameters by reference)\label{ctypes-passing-pointers}}
-
-Sometimes a C api function expects a \emph{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
-\emph{passing parameters by reference}.
-
-\code{ctypes} exports the \function{byref} function which is used to pass
-parameters by reference. The same effect can be achieved with the
-\code{pointer} function, although \code{pointer} does a lot more work since
-it constructs a real pointer object, so it is faster to use \function{byref}
-if you don't need the pointer object in Python itself:
-\begin{verbatim}
->>> 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'
->>>
-\end{verbatim}
-
-
-\subsubsection{Structures and unions\label{ctypes-structures-unions}}
-
-Structures and unions must derive from the \class{Structure} and \class{Union}
-base classes which are defined in the \code{ctypes} module. Each subclass
-must define a \member{{\_}fields{\_}} attribute. \member{{\_}fields{\_}} must be a list of
-\emph{2-tuples}, containing a \emph{field name} and a \emph{field type}.
-
-The field type must be a \code{ctypes} type like \class{c{\_}int}, or any other
-derived \code{ctypes} type: structure, union, array, pointer.
-
-Here is a simple example of a POINT structure, which contains two
-integers named \code{x} and \code{y}, and also shows how to initialize a
-structure in the constructor:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-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 \code{upperleft}
-and \code{lowerright}
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-Nested structures can also be initialized in the constructor in
-several ways:
-\begin{verbatim}
->>> r = RECT(POINT(1, 2), POINT(3, 4))
->>> r = RECT((1, 2), (3, 4))
-\end{verbatim}
-
-Fields descriptors can be retrieved from the \emph{class}, they are useful
-for debugging because they can provide useful information:
-\begin{verbatim}
->>> print POINT.x
-<Field type=c_long, ofs=0, size=4>
->>> print POINT.y
-<Field type=c_long, ofs=4, size=4>
->>>
-\end{verbatim}
-
-
-\subsubsection{Structure/union alignment and byte order\label{ctypes-structureunion-alignment-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 \member{{\_}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 \code{{\#}pragma pack(n)}
-also does in MSVC.
-
-\code{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.
-
-
-\subsubsection{Bit fields in structures and unions\label{ctypes-bit-fields-in-structures-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 \member{{\_}fields{\_}} tuples:
-\begin{verbatim}
->>> 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>
->>>
-\end{verbatim}
-
-
-\subsubsection{Arrays\label{ctypes-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:
-\begin{verbatim}
-TenPointsArrayType = POINT * 10
-\end{verbatim}
-
-Here is an example of an somewhat artifical data type, a structure
-containing 4 POINTs among other stuff:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-Instances are created in the usual way, by calling the class:
-\begin{verbatim}
-arr = TenPointsArrayType()
-for pt in arr:
- print pt.x, pt.y
-\end{verbatim}
-
-The above code print a series of \code{0 0} lines, because the array
-contents is initialized to zeros.
-
-Initializers of the correct type can also be specified:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-
-\subsubsection{Pointers\label{ctypes-pointers}}
-
-Pointer instances are created by calling the \code{pointer} function on a
-\code{ctypes} type:
-\begin{verbatim}
->>> from ctypes import *
->>> i = c_int(42)
->>> pi = pointer(i)
->>>
-\end{verbatim}
-
-Pointer instances have a \code{contents} attribute which returns the
-object to which the pointer points, the \code{i} object above:
-\begin{verbatim}
->>> pi.contents
-c_long(42)
->>>
-\end{verbatim}
-
-Note that \code{ctypes} does not have OOR (original object return), it
-constructs a new, equivalent object each time you retrieve an
-attribute:
-\begin{verbatim}
->>> pi.contents is i
-False
->>> pi.contents is pi.contents
-False
->>>
-\end{verbatim}
-
-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:
-\begin{verbatim}
->>> i = c_int(99)
->>> pi.contents = i
->>> pi.contents
-c_long(99)
->>>
-\end{verbatim}
-
-Pointer instances can also be indexed with integers:
-\begin{verbatim}
->>> pi[0]
-99
->>>
-\end{verbatim}
-
-Assigning to an integer index changes the pointed to value:
-\begin{verbatim}
->>> print i
-c_long(99)
->>> pi[0] = 22
->>> print i
-c_long(22)
->>>
-\end{verbatim}
-
-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 \emph{know} that the pointer actually
-points to an array instead of a single item.
-
-Behind the scenes, the \code{pointer} function does more than simply
-create pointer instances, it has to create pointer \emph{types} first.
-This is done with the \code{POINTER} function, which accepts any
-\code{ctypes} type, and returns a new type:
-\begin{verbatim}
->>> 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...>
->>>
-\end{verbatim}
-
-Calling the pointer type without an argument creates a \code{NULL}
-pointer. \code{NULL} pointers have a \code{False} boolean value:
-\begin{verbatim}
->>> null_ptr = POINTER(c_int)()
->>> print bool(null_ptr)
-False
->>>
-\end{verbatim}
-
-\code{ctypes} checks for \code{NULL} when dereferencing pointers (but
-dereferencing non-\code{NULL} pointers would crash Python):
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-
-\subsubsection{Type conversions\label{ctypes-type-conversions}}
-
-Usually, ctypes does strict type checking. This means, if you have
-\code{POINTER(c{\_}int)} in the \member{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
-\code{POINTER(c{\_}int)}, ctypes accepts an array of c{\_}int:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-To set a POINTER type field to \code{NULL}, you can assign \code{None}:
-\begin{verbatim}
->>> bar.values = None
->>>
-\end{verbatim}
-
-XXX list other conversions...
-
-Sometimes you have instances of incompatible types. In \code{C}, you can
-cast one type into another type. \code{ctypes} provides a \code{cast}
-function which can be used in the same way. The \code{Bar} structure
-defined above accepts \code{POINTER(c{\_}int)} pointers or \class{c{\_}int} arrays
-for its \code{values} field, but not instances of other types:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-For these cases, the \code{cast} function is handy.
-
-The \code{cast} function can be used to cast a ctypes instance into a
-pointer to a different ctypes data type. \code{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:
-\begin{verbatim}
->>> a = (c_byte * 4)()
->>> cast(a, POINTER(c_int))
-<ctypes.LP_c_long object at ...>
->>>
-\end{verbatim}
-
-So, \code{cast} can be used to assign to the \code{values} field of \code{Bar}
-the structure:
-\begin{verbatim}
->>> bar = Bar()
->>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
->>> print bar.values[0]
-0
->>>
-\end{verbatim}
-
-
-\subsubsection{Incomplete Types\label{ctypes-incomplete-types}}
-
-\emph{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:
-\begin{verbatim}
-struct cell; /* forward declaration */
-
-struct {
- char *name;
- struct cell *next;
-} cell;
-\end{verbatim}
-
-The straightforward translation into ctypes code would be this, but it
-does not work:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-because the new \code{class cell} is not available in the class statement
-itself. In \code{ctypes}, we can define the \code{cell} class and set the
-\member{{\_}fields{\_}} attribute later, after the class statement:
-\begin{verbatim}
->>> from ctypes import *
->>> class cell(Structure):
-... pass
-...
->>> cell._fields_ = [("name", c_char_p),
-... ("next", POINTER(cell))]
->>>
-\end{verbatim}
-
-Lets try it. We create two instances of \code{cell}, and let them point
-to each other, and finally follow the pointer chain a few times:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-
-\subsubsection{Callback functions\label{ctypes-callback-functions}}
-
-\code{ctypes} allows to create C callable function pointers from Python
-callables. These are sometimes called \emph{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
-\function{qsort} function, this is used to sort items with the help of a
-callback function. \function{qsort} will be used to sort an array of
-integers:
-\begin{verbatim}
->>> IntArray5 = c_int * 5
->>> ia = IntArray5(5, 1, 7, 33, 99)
->>> qsort = libc.qsort
->>> qsort.restype = None
->>>
-\end{verbatim}
-
-\function{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 \code{type} for the callback
-function:
-\begin{verbatim}
->>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
->>>
-\end{verbatim}
-
-For the first implementation of the callback function, we simply print
-the arguments we get, and return 0 (incremental development ;-):
-\begin{verbatim}
->>> def py_cmp_func(a, b):
-... print "py_cmp_func", a, b
-... return 0
-...
->>>
-\end{verbatim}
-
-Create the C callable callback:
-\begin{verbatim}
->>> cmp_func = CMPFUNC(py_cmp_func)
->>>
-\end{verbatim}
-
-And we're ready to go:
-\begin{verbatim}
->>> 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...>
->>>
-\end{verbatim}
-
-We know how to access the contents of a pointer, so lets redefine our callback:
-\begin{verbatim}
->>> def py_cmp_func(a, b):
-... print "py_cmp_func", a[0], b[0]
-... return 0
-...
->>> cmp_func = CMPFUNC(py_cmp_func)
->>>
-\end{verbatim}
-
-Here is what we get on Windows:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-It is funny to see that on linux the sort function seems to work much
-more efficient, it is doing less comparisons:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-Ah, we're nearly done! The last step is to actually compare the two
-items and return a useful result:
-\begin{verbatim}
->>> def py_cmp_func(a, b):
-... print "py_cmp_func", a[0], b[0]
-... return a[0] - b[0]
-...
->>>
-\end{verbatim}
-
-Final run on Windows:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-and on Linux:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-It is quite interesting to see that the Windows \function{qsort} function
-needs more comparisons than the linux version!
-
-As we can easily check, our array is sorted now:
-\begin{verbatim}
->>> for i in ia: print i,
-...
-1 5 7 33 99
->>>
-\end{verbatim}
-
-\textbf{Important note for callback functions:}
-
-Make sure you keep references to CFUNCTYPE objects as long as they are
-used from C code. \code{ctypes} doesn't, and if you don't, they may be
-garbage collected, crashing your program when a callback is made.
-
-
-\subsubsection{Accessing values exported from dlls\label{ctypes-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
-\code{Py{\_}OptimizeFlag}, an integer set to 0, 1, or 2, depending on the
-\programopt{-O} or \programopt{-OO} flag given on startup.
-
-\code{ctypes} can access values like this with the \method{in{\_}dll} class
-methods of the type. \var{pythonapi} is a predefined symbol giving
-access to the Python C api:
-\begin{verbatim}
->>> opt_flag = c_int.in_dll(pythonapi, "Py_OptimizeFlag")
->>> print opt_flag
-c_long(0)
->>>
-\end{verbatim}
-
-If the interpreter would have been started with \programopt{-O}, the sample
-would have printed \code{c{\_}long(1)}, or \code{c{\_}long(2)} if \programopt{-OO} would have
-been specified.
-
-An extended example which also demonstrates the use of pointers
-accesses the \code{PyImport{\_}FrozenModules} pointer exported by Python.
-
-Quoting the Python docs: \emph{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
-\code{ctypes}:
-\begin{verbatim}
->>> from ctypes import *
->>>
->>> class struct_frozen(Structure):
-... _fields_ = [("name", c_char_p),
-... ("code", POINTER(c_ubyte)),
-... ("size", c_int)]
-...
->>>
-\end{verbatim}
-
-We have defined the \code{struct {\_}frozen} data type, so we can get the
-pointer to the table:
-\begin{verbatim}
->>> FrozenTable = POINTER(struct_frozen)
->>> table = FrozenTable.in_dll(pythonapi, "PyImport_FrozenModules")
->>>
-\end{verbatim}
-
-Since \code{table} is a \code{pointer} to the array of \code{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:
-\begin{verbatim}
->>> for item in table:
-... print item.name, item.size
-... if item.name is None:
-... break
-...
-__hello__ 104
-__phello__ -104
-__phello__.spam 104
-None 0
->>>
-\end{verbatim}
-
-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 \code{import {\_}{\_}hello{\_}{\_}} for example.
-
-
-\subsubsection{Surprises\label{ctypes-surprises}}
-
-There are some edges in \code{ctypes} where you may be expect something
-else than what actually happens.
-
-Consider the following example:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-Hm. We certainly expected the last statement to print \code{3 4 1 2}.
-What happended? Here are the steps of the \code{rc.a, rc.b = rc.b, rc.a}
-line above:
-\begin{verbatim}
->>> temp0, temp1 = rc.b, rc.a
->>> rc.a = temp0
->>> rc.b = temp1
->>>
-\end{verbatim}
-
-Note that \code{temp0} and \code{temp1} are objects still using the internal
-buffer of the \code{rc} object above. So executing \code{rc.a = temp0}
-copies the buffer contents of \code{temp0} into \code{rc} 's buffer. This,
-in turn, changes the contents of \code{temp1}. So, the last assignment
-\code{rc.b = temp1}, doesn't have the expected effect.
-
-Keep in mind that retrieving subobjects from Structure, Unions, and
-Arrays doesn't \emph{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:
-\begin{verbatim}
->>> s = c_char_p()
->>> s.value = "abc def ghi"
->>> s.value
-'abc def ghi'
->>> s.value is s.value
-False
->>>
-\end{verbatim}
-
-Why is it printing \code{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 \code{contents} of the object is stored.
-Accessing the contents again constructs a new Python each time!
-
-
-\subsubsection{Variable-sized data types\label{ctypes-variable-sized-data-types}}
-
-\code{ctypes} provides some support for variable-sized arrays and
-structures (this was added in version 0.9.9.7).
-
-The \code{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 \code{ValueError} is raised if this is
-tried:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-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:
-\begin{verbatim}
->>> short_array[:]
-[0, 0, 0, 0]
->>> short_array[7]
-Traceback (most recent call last):
- ...
-IndexError: invalid index
->>>
-\end{verbatim}
-
-Another way to use variable-sized data types with \code{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.
-
-
-\subsubsection{Bugs, ToDo and non-implemented things\label{ctypes-bugs-todo-non-implemented-things}}
-
-Enumeration types are not implemented. You can do it easily yourself,
-using \class{c{\_}int} as the base class.
-
-\code{long double} is not implemented.
-% Local Variables:
-% compile-command: "make.bat"
-% End:
-
-
-\subsection{ctypes reference\label{ctypes-ctypes-reference}}
-
-
-\subsubsection{Finding shared libraries\label{ctypes-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 \code{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 \code{ctypes.util} module provides a function which can help to
-determine the library to load.
-
-\begin{datadescni}{find_library(name)}
-Try to find a library and return a pathname. \var{name} is the
-library name without any prefix like \var{lib}, suffix like \code{.so},
-\code{.dylib} or version number (this is the form used for the posix
-linker option \programopt{-l}). If no library can be found, returns
-\code{None}.
-\end{datadescni}
-
-The exact functionality is system dependend.
-
-On Linux, \code{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:
-\begin{verbatim}
->>> 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'
->>>
-\end{verbatim}
-
-On OS X, \code{find{\_}library} tries several predefined naming schemes and
-paths to locate the library, and returns a full pathname if successfull:
-\begin{verbatim}
->>> 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'
->>>
-\end{verbatim}
-
-On Windows, \code{find{\_}library} searches along the system search path,
-and returns the full pathname, but since there is no predefined naming
-scheme a call like \code{find{\_}library("c")} will fail and return
-\code{None}.
-
-If wrapping a shared library with \code{ctypes}, it \emph{may} be better to
-determine the shared library name at development type, and hardcode
-that into the wrapper module instead of using \code{find{\_}library} to
-locate the library at runtime.
-
-
-\subsubsection{Loading shared libraries\label{ctypes-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:
-
-\begin{classdesc}{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 \code{int}.
-\end{classdesc}
-
-\begin{classdesc}{OleDLL}{name, mode=DEFAULT_MODE, handle=None}
-Windows only: Instances of this class represent loaded shared
-libraries, functions in these libraries use the \code{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.
-\end{classdesc}
-
-\begin{classdesc}{WinDLL}{name, mode=DEFAULT_MODE, handle=None}
-Windows only: Instances of this class represent loaded shared
-libraries, functions in these libraries use the \code{stdcall}
-calling convention, and are assumed to return \code{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.
-\end{classdesc}
-
-The Python GIL is released before calling any function exported by
-these libraries, and reaquired afterwards.
-
-\begin{classdesc}{PyDLL}{name, mode=DEFAULT_MODE, handle=None}
-Instances of this class behave like \class{CDLL} instances, except
-that the Python GIL is \emph{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.
-\end{classdesc}
-
-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 \code{handle} named parameter, otherwise the underlying platforms
-\code{dlopen} or \method{LoadLibrary} function is used to load the library
-into the process, and to get a handle to it.
-
-The \var{mode} parameter can be used to specify how the library is
-loaded. For details, consult the \code{dlopen(3)} manpage, on Windows,
-\var{mode} is ignored.
-
-\begin{datadescni}{RTLD_GLOBAL}
-Flag to use as \var{mode} parameter. On platforms where this flag
-is not available, it is defined as the integer zero.
-\end{datadescni}
-
-\begin{datadescni}{RTLD_LOCAL}
-Flag to use as \var{mode} parameter. On platforms where this is not
-available, it is the same as \var{RTLD{\_}GLOBAL}.
-\end{datadescni}
-
-\begin{datadescni}{DEFAULT_MODE}
-The default mode which is used to load shared libraries. On OSX
-10.3, this is \var{RTLD{\_}GLOBAL}, otherwise it is the same as
-\var{RTLD{\_}LOCAL}.
-\end{datadescni}
-
-Instances of these classes have no public methods, however
-\method{{\_}{\_}getattr{\_}{\_}} and \method{{\_}{\_}getitem{\_}{\_}} have special behaviour: functions
-exported by the shared library can be accessed as attributes of by
-index. Please note that both \method{{\_}{\_}getattr{\_}{\_}} and \method{{\_}{\_}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:
-
-\begin{memberdesc}{_handle}
-The system handle used to access the library.
-\end{memberdesc}
-
-\begin{memberdesc}{_name}
-The name of the library passed in the contructor.
-\end{memberdesc}
-
-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 \method{LoadLibrary} method, or by retrieving the library as
-attribute of the loader instance.
-
-\begin{classdesc}{LibraryLoader}{dlltype}
-Class which loads shared libraries. \code{dlltype} should be one
-of the \class{CDLL}, \class{PyDLL}, \class{WinDLL}, or \class{OleDLL} types.
-
-\method{{\_}{\_}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.
-\end{classdesc}
-
-\begin{methoddesc}{LoadLibrary}{name}
-Load a shared library into the process and return it. This method
-always returns a new instance of the library.
-\end{methoddesc}
-
-These prefabricated library loaders are available:
-
-\begin{datadescni}{cdll}
-Creates \class{CDLL} instances.
-\end{datadescni}
-
-\begin{datadescni}{windll}
-Windows only: Creates \class{WinDLL} instances.
-\end{datadescni}
-
-\begin{datadescni}{oledll}
-Windows only: Creates \class{OleDLL} instances.
-\end{datadescni}
-
-\begin{datadescni}{pydll}
-Creates \class{PyDLL} instances.
-\end{datadescni}
-
-For accessing the C Python api directly, a ready-to-use Python shared
-library object is available:
-
-\begin{datadescni}{pythonapi}
-An instance of \class{PyDLL} that exposes Python C api functions as
-attributes. Note that all these functions are assumed to return C
-\code{int}, which is of course not always the truth, so you have to
-assign the correct \member{restype} attribute to use these functions.
-\end{datadescni}
-
-
-\subsubsection{Foreign functions\label{ctypes-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:
-
-\begin{classdesc*}{_FuncPtr}
-Base class for C callable foreign functions.
-\end{classdesc*}
-
-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.
-
-\begin{memberdesc}{restype}
-Assign a ctypes type to specify the result type of the foreign
-function. Use \code{None} for \code{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 \code{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 \member{restype} and assign a callable to the
-\member{errcheck} attribute.
-\end{memberdesc}
-
-\begin{memberdesc}{argtypes}
-Assign a tuple of ctypes types to specify the argument types that
-the function accepts. Functions using the \code{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 \method{from{\_}param} class method of the items in the
-\member{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 \member{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 \method{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.
-\end{memberdesc}
-
-\begin{memberdesc}{errcheck}
-Assign a Python function or another callable to this attribute.
-The callable will be called with three or more arguments:
-\end{memberdesc}
-
-\begin{funcdescni}{callable}{result, func, arguments}
-\code{result} is what the foreign function returns, as specified by the
-\member{restype} attribute.
-
-\code{func} is the foreign function object itself, this allows to
-reuse the same callable object to check or postprocess the results
-of several functions.
-
-\code{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.
-\end{funcdescni}
-
-\begin{excdesc}{ArgumentError()}
-This exception is raised when a foreign function call cannot
-convert one of the passed arguments.
-\end{excdesc}
-
-
-\subsubsection{Function prototypes\label{ctypes-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.
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{WINFUNCTYPE}{restype, *argtypes}
-Windows only: The returned function prototype creates functions
-that use the \code{stdcall} calling convention, except on Windows CE
-where \function{WINFUNCTYPE} is the same as \function{CFUNCTYPE}. The function
-will release the GIL during the call.
-\end{funcdesc}
-
-\begin{funcdesc}{PYFUNCTYPE}{restype, *argtypes}
-The returned function prototype creates functions that use the
-Python calling convention. The function will \emph{not} release the
-GIL during the call.
-\end{funcdesc}
-
-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.
-
-\begin{funcdescni}{prototype}{address}
-Returns a foreign function at the specified address.
-\end{funcdescni}
-
-\begin{funcdescni}{prototype}{callable}
-Create a C callable function (a callback function) from a Python
-\code{callable}.
-\end{funcdescni}
-
-\begin{funcdescni}{prototype}{func_spec\optional{, paramflags}}
-Returns a foreign function exported by a shared library.
-\code{func{\_}spec} must be a 2-tuple \code{(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.
-\end{funcdescni}
-
-\begin{funcdescni}{prototype}{vtbl_index, name\optional{, paramflags\optional{, iid}}}
-Returns a foreign function that will call a COM method.
-\code{vtbl{\_}index} is the index into the virtual function table, a
-small nonnegative integer. \var{name} is name of the COM method.
-\var{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 \member{argtypes} tuple.
-\end{funcdescni}
-
-The optional \var{paramflags} parameter creates foreign function
-wrappers with much more functionality than the features described
-above.
-
-\var{paramflags} must be a tuple of the same length as \member{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:
-
-\begin{datadescni}{1}
-Specifies an input parameter to the function.
-\end{datadescni}
-
-\begin{datadescni}{2}
-Output parameter. The foreign function fills in a value.
-\end{datadescni}
-
-\begin{datadescni}{4}
-Input parameter which defaults to the integer zero.
-\end{datadescni}
-
-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 \code{MessageBoxA}
-function so that it supports default parameters and named arguments.
-The C declaration from the windows header file is this:
-\begin{verbatim}
-WINUSERAPI int WINAPI
-MessageBoxA(
- HWND hWnd ,
- LPCSTR lpText,
- LPCSTR lpCaption,
- UINT uType);
-\end{verbatim}
-
-Here is the wrapping with \code{ctypes}:
-\begin{quote}
-\begin{verbatim}>>> 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)
->>>\end{verbatim}
-\end{quote}
-
-The MessageBox foreign function can now be called in these ways:
-\begin{verbatim}
->>> MessageBox()
->>> MessageBox(text="Spam, spam, spam")
->>> MessageBox(flags=2, text="foo bar")
->>>
-\end{verbatim}
-
-A second example demonstrates output parameters. The win32
-\code{GetWindowRect} function retrieves the dimensions of a specified
-window by copying them into \code{RECT} structure that the caller has to
-supply. Here is the C declaration:
-\begin{verbatim}
-WINUSERAPI BOOL WINAPI
-GetWindowRect(
- HWND hWnd,
- LPRECT lpRect);
-\end{verbatim}
-
-Here is the wrapping with \code{ctypes}:
-\begin{quote}
-\begin{verbatim}>>> 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)
->>>\end{verbatim}
-\end{quote}
-
-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 \member{errcheck} protocol to do
-further output processing and error checking. The win32
-\code{GetWindowRect} api function returns a \code{BOOL} to signal success or
-failure, so this function could do the error checking, and raises an
-exception when the api call failed:
-\begin{verbatim}
->>> def errcheck(result, func, args):
-... if not result:
-... raise WinError()
-... return args
->>> GetWindowRect.errcheck = errcheck
->>>
-\end{verbatim}
-
-If the \member{errcheck} function returns the argument tuple it receives
-unchanged, \code{ctypes} continues the normal processing it does on the
-output parameters. If you want to return a tuple of window
-coordinates instead of a \code{RECT} instance, you can retrieve the
-fields in the function and return them instead, the normal processing
-will no longer take place:
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-
-\subsubsection{Utility functions\label{ctypes-utility-functions}}
-
-\begin{funcdesc}{addressof}{obj}
-Returns the address of the memory buffer as integer. \code{obj} must
-be an instance of a ctypes type.
-\end{funcdesc}
-
-\begin{funcdesc}{alignment}{obj_or_type}
-Returns the alignment requirements of a ctypes type.
-\code{obj{\_}or{\_}type} must be a ctypes type or instance.
-\end{funcdesc}
-
-\begin{funcdesc}{byref}{obj}
-Returns a light-weight pointer to \code{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
-\code{pointer(obj)}, but the construction is a lot faster.
-\end{funcdesc}
-
-\begin{funcdesc}{cast}{obj, type}
-This function is similar to the cast operator in C. It returns a
-new instance of \code{type} which points to the same memory block as
-\code{obj}. \code{type} must be a pointer type, and \code{obj} must be an
-object that can be interpreted as a pointer.
-\end{funcdesc}
-
-\begin{funcdesc}{create_string_buffer}{init_or_size\optional{, size}}
-This function creates a mutable character buffer. The returned
-object is a ctypes array of \class{c{\_}char}.
-
-\code{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.
-\end{funcdesc}
-
-\begin{funcdesc}{create_unicode_buffer}{init_or_size\optional{, size}}
-This function creates a mutable unicode character buffer. The
-returned object is a ctypes array of \class{c{\_}wchar}.
-
-\code{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \code{{\_}ctypes} extension dll exports.
-\end{funcdesc}
-
-\begin{funcdesc}{FormatError}{\optional{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.
-\end{funcdesc}
-
-\begin{funcdesc}{GetLastError}{}
-Windows only: Returns the last error code set by Windows in the
-calling thread.
-\end{funcdesc}
-
-\begin{funcdesc}{memmove}{dst, src, count}
-Same as the standard C memmove library function: copies \var{count}
-bytes from \code{src} to \var{dst}. \var{dst} and \code{src} must be
-integers or ctypes instances that can be converted to pointers.
-\end{funcdesc}
-
-\begin{funcdesc}{memset}{dst, c, count}
-Same as the standard C memset library function: fills the memory
-block at address \var{dst} with \var{count} bytes of value
-\var{c}. \var{dst} must be an integer specifying an address, or a
-ctypes instance.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{pointer}{obj}
-This function creates a new pointer instance, pointing to
-\code{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 \code{byref(obj)} which is much faster.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \code{'utf-8'} or
-\code{'mbcs'}, errors must be a string specifying the error handling
-on encoding/decoding errors. Examples of possible values are
-\code{"strict"}, \code{"replace"}, or \code{"ignore"}.
-
-\code{set{\_}conversion{\_}mode} returns a 2-tuple containing the previous
-conversion rules. On windows, the initial conversion rules are
-\code{('mbcs', 'ignore')}, on other systems \code{('ascii', 'strict')}.
-\end{funcdesc}
-
-\begin{funcdesc}{sizeof}{obj_or_type}
-Returns the size in bytes of a ctypes type or instance memory
-buffer. Does the same as the C \code{sizeof()} function.
-\end{funcdesc}
-
-\begin{funcdesc}{string_at}{address\optional{, 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.
-\end{funcdesc}
-
-\begin{funcdesc}{WinError}{code=None, descr=None}
-Windows only: this function is probably the worst-named thing in
-ctypes. It creates an instance of WindowsError. If \var{code} is not
-specified, \code{GetLastError} is called to determine the error
-code. If \code{descr} is not spcified, \function{FormatError} is called to
-get a textual description of the error.
-\end{funcdesc}
-
-\begin{funcdesc}{wstring_at}{address}
-This function returns the wide character string starting at memory
-address \code{address} as unicode string. If \code{size} is specified,
-it is used as the number of characters of the string, otherwise
-the string is assumed to be zero-terminated.
-\end{funcdesc}
-
-
-\subsubsection{Data types\label{ctypes-data-types}}
-
-\begin{classdesc*}{_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 \code{addressof()} helper function.
-Another instance variable is exposed as \member{{\_}objects}; this
-contains other Python objects that need to be kept alive in case
-the memory block contains pointers.
-\end{classdesc*}
-
-Common methods of ctypes data types, these are all class methods (to
-be exact, they are methods of the metaclass):
-
-\begin{methoddesc}{from_address}{address}
-This method returns a ctypes type instance using the memory
-specified by address which must be an integer.
-\end{methoddesc}
-
-\begin{methoddesc}{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 \member{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 \code{obj} if that is an instance of
-the type. Some types accept other objects as well.
-\end{methoddesc}
-
-\begin{methoddesc}{in_dll}{library, name}
-This method returns a ctypes type instance exported by a shared
-library. \var{name} is the name of the symbol that exports the data,
-\var{library} is the loaded shared library.
-\end{methoddesc}
-
-Common instance variables of ctypes data types:
-
-\begin{memberdesc}{_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 \member{{\_}b{\_}base{\_}} readonly member is the root ctypes
-object that owns the memory block.
-\end{memberdesc}
-
-\begin{memberdesc}{_b_needsfree_}
-This readonly variable is true when the ctypes data instance has
-allocated the memory block itself, false otherwise.
-\end{memberdesc}
-
-\begin{memberdesc}{_objects}
-This member is either \code{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.
-\end{memberdesc}
-
-
-\subsubsection{Fundamental data types\label{ctypes-fundamental-data-types-2}}
-
-\begin{classdesc*}{_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. \code{{\_}SimpleCData}
-is a subclass of \code{{\_}CData}, so it inherits their methods and
-attributes.
-\end{classdesc*}
-
-Instances have a single attribute:
-
-\begin{memberdesc}{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 \code{value} attribute is retrieved from a ctypes instance,
-usually a new object is returned each time. \code{ctypes} does \emph{not}
-implement original object return, always a new object is
-constructed. The same is true for all other ctypes object
-instances.
-\end{memberdesc}
-
-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 \member{restype} of \class{c{\_}char{\_}p},
-you will always receive a Python string, \emph{not} a \class{c{\_}char{\_}p}
-instance.
-
-Subclasses of fundamental data types do \emph{not} inherit this behaviour.
-So, if a foreign functions \member{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
-\code{value} attribute.
-
-These are the fundamental ctypes data types:
-
-\begin{classdesc*}{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.
-\end{classdesc*}
-
-\begin{classdesc*}{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.
-\end{classdesc*}
-
-\begin{classdesc*}{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.
-\end{classdesc*}
-
-\begin{classdesc*}{c_double}
-Represents the C double datatype. The constructor accepts an
-optional float initializer.
-\end{classdesc*}
-
-\begin{classdesc*}{c_float}
-Represents the C double datatype. The constructor accepts an
-optional float initializer.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int}
-Represents the C signed int datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done. On
-platforms where \code{sizeof(int) == sizeof(long)} it is an alias to
-\class{c{\_}long}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int8}
-Represents the C 8-bit \code{signed int} datatype. Usually an alias for
-\class{c{\_}byte}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int16}
-Represents the C 16-bit signed int datatype. Usually an alias for
-\class{c{\_}short}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int32}
-Represents the C 32-bit signed int datatype. Usually an alias for
-\class{c{\_}int}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int64}
-Represents the C 64-bit \code{signed int} datatype. Usually an alias
-for \class{c{\_}longlong}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_long}
-Represents the C \code{signed long} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_longlong}
-Represents the C \code{signed long long} datatype. The constructor accepts
-an optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_short}
-Represents the C \code{signed short} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_size_t}
-Represents the C \code{size{\_}t} datatype.
-\end{classdesc*}
-
-\begin{classdesc*}{c_ubyte}
-Represents the C \code{unsigned char} datatype, it interprets the
-value as small integer. The constructor accepts an optional
-integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint}
-Represents the C \code{unsigned int} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done. On
-platforms where \code{sizeof(int) == sizeof(long)} it is an alias for
-\class{c{\_}ulong}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint8}
-Represents the C 8-bit unsigned int datatype. Usually an alias for
-\class{c{\_}ubyte}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint16}
-Represents the C 16-bit unsigned int datatype. Usually an alias for
-\class{c{\_}ushort}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint32}
-Represents the C 32-bit unsigned int datatype. Usually an alias for
-\class{c{\_}uint}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint64}
-Represents the C 64-bit unsigned int datatype. Usually an alias for
-\class{c{\_}ulonglong}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_ulong}
-Represents the C \code{unsigned long} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_ulonglong}
-Represents the C \code{unsigned long long} datatype. The constructor
-accepts an optional integer initializer; no overflow checking is
-done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_ushort}
-Represents the C \code{unsigned short} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_void_p}
-Represents the C \code{void *} type. The value is represented as
-integer. The constructor accepts an optional integer initializer.
-\end{classdesc*}
-
-\begin{classdesc*}{c_wchar}
-Represents the C \code{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.
-\end{classdesc*}
-
-\begin{classdesc*}{c_wchar_p}
-Represents the C \code{wchar{\_}t *} datatype, which must be a pointer to
-a zero-terminated wide character string. The constructor accepts
-an integer address, or a string.
-\end{classdesc*}
-
-\begin{classdesc*}{c_bool}
-Represent the C \code{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}
-\end{classdesc*}
-
-\begin{classdesc*}{HRESULT}
-Windows only: Represents a \class{HRESULT} value, which contains success
-or error information for a function or method call.
-\end{classdesc*}
-
-\begin{classdesc*}{py_object}
-Represents the C \code{PyObject *} datatype. Calling this without an
-argument creates a \code{NULL} \code{PyObject *} pointer.
-\end{classdesc*}
-
-The \code{ctypes.wintypes} module provides quite some other Windows
-specific data types, for example \code{HWND}, \code{WPARAM}, or \code{DWORD}.
-Some useful structures like \code{MSG} or \code{RECT} are also defined.
-
-
-\subsubsection{Structured data types\label{ctypes-structured-data-types}}
-
-\begin{classdesc}{Union}{*args, **kw}
-Abstract base class for unions in native byte order.
-\end{classdesc}
-
-\begin{classdesc}{BigEndianStructure}{*args, **kw}
-Abstract base class for structures in \emph{big endian} byte order.
-\end{classdesc}
-
-\begin{classdesc}{LittleEndianStructure}{*args, **kw}
-Abstract base class for structures in \emph{little endian} byte order.
-\end{classdesc}
-
-Structures with non-native byte order cannot contain pointer type
-fields, or any other data types containing pointer type fields.
-
-\begin{classdesc}{Structure}{*args, **kw}
-Abstract base class for structures in \emph{native} byte order.
-\end{classdesc}
-
-Concrete structure and union types must be created by subclassing one
-of these types, and at least define a \member{{\_}fields{\_}} class variable.
-\code{ctypes} will create descriptors which allow reading and writing the
-fields by direct attribute accesses. These are the
-
-\begin{memberdesc}{_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 \member{{\_}fields{\_}} class variable \emph{after}
-the class statement that defines the Structure subclass, this
-allows to create data types that directly or indirectly reference
-themselves:
-\begin{verbatim}
-class List(Structure):
- pass
-List._fields_ = [("pnext", POINTER(List)),
- ...
- ]
-\end{verbatim}
-
-The \member{{\_}fields{\_}} class variable must, however, be defined before
-the type is first used (an instance is created, \code{sizeof()} is
-called on it, and so on). Later assignments to the \member{{\_}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 \member{{\_}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 \member{{\_}fields{\_}} defined
-in the sub-subclass, if any.
-\end{memberdesc}
-
-\begin{memberdesc}{_pack_}
-An optional small integer that allows to override the alignment of
-structure fields in the instance. \member{{\_}pack{\_}} must already be
-defined when \member{{\_}fields{\_}} is assigned, otherwise it will have no
-effect.
-\end{memberdesc}
-
-\begin{memberdesc}{_anonymous_}
-An optional sequence that lists the names of unnamed (anonymous)
-fields. \code{{\_}anonymous{\_}} must be already defined when \member{{\_}fields{\_}}
-is assigned, otherwise it will have no effect.
-
-The fields listed in this variable must be structure or union type
-fields. \code{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):
-\begin{verbatim}
-class _U(Union):
- _fields_ = [("lptdesc", POINTER(TYPEDESC)),
- ("lpadesc", POINTER(ARRAYDESC)),
- ("hreftype", HREFTYPE)]
-
-class TYPEDESC(Structure):
- _fields_ = [("u", _U),
- ("vt", VARTYPE)]
-
- _anonymous_ = ("u",)
-\end{verbatim}
-
-The \code{TYPEDESC} structure describes a COM data type, the \code{vt}
-field specifies which one of the union fields is valid. Since the
-\code{u} field is defined as anonymous field, it is now possible to
-access the members directly off the TYPEDESC instance.
-\code{td.lptdesc} and \code{td.u.lptdesc} are equivalent, but the former
-is faster since it does not need to create a temporary union
-instance:
-\begin{verbatim}
-td = TYPEDESC()
-td.vt = VT_PTR
-td.lptdesc = POINTER(some_type)
-td.u.lptdesc = POINTER(some_type)
-\end{verbatim}
-\end{memberdesc}
-
-It is possible to defined sub-subclasses of structures, they inherit
-the fields of the base class. If the subclass definition has a
-separate \member{{\_}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 \member{{\_}fields{\_}}. Keyword
-arguments in the constructor are interpreted as attribute assignments,
-so they will initialize \member{{\_}fields{\_}} with the same name, or create new
-attributes for names not present in \member{{\_}fields{\_}}.
-
-
-\subsubsection{Arrays and pointers\label{ctypes-arrays-pointers}}
-
-Not yet written - please see section~\ref{ctypes-pointers}, pointers and
-section~\ref{ctypes-arrays}, arrays in the tutorial.
-
diff --git a/Doc/lib/libcurses.tex b/Doc/lib/libcurses.tex
deleted file mode 100644
index 33dea5a..0000000
--- a/Doc/lib/libcurses.tex
+++ /dev/null
@@ -1,1405 +0,0 @@
-\section{\module{curses} ---
- Terminal handling for character-cell displays}
-
-\declaremodule{standard}{curses}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\sectionauthor{Eric Raymond}{esr@thyrsus.com}
-\modulesynopsis{An interface to the curses library, providing portable
- terminal handling.}
-
-\versionchanged[Added support for the \code{ncurses} library and
- converted to a package]{1.6}
-
-The \module{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.
-
-\begin{seealso}
- \seemodule{curses.ascii}{Utilities for working with \ASCII{}
- characters, regardless of your locale
- settings.}
- \seemodule{curses.panel}{A panel stack extension that adds depth to
- curses windows.}
- \seemodule{curses.textpad}{Editable text widget for curses supporting
- \program{Emacs}-like bindings.}
- \seemodule{curses.wrapper}{Convenience function to ensure proper
- terminal setup and resetting on
- application entry and exit.}
- \seetitle[http://www.python.org/doc/howto/curses/curses.html]{Curses
- Programming with Python}{Tutorial material on using curses
- with Python, by Andrew Kuchling and Eric Raymond, is
- available on the Python Web site.}
- \seetext{The \file{Demo/curses/} directory in the Python source
- distribution contains some example programs using the
- curses bindings provided by this module.}
-\end{seealso}
-
-
-\subsection{Functions \label{curses-functions}}
-
-The module \module{curses} defines the following exception:
-
-\begin{excdesc}{error}
-Exception raised when a curses library function returns an error.
-\end{excdesc}
-
-\note{Whenever \var{x} or \var{y} arguments to a function
-or a method are optional, they default to the current cursor location.
-Whenever \var{attr} is optional, it defaults to \constant{A_NORMAL}.}
-
-The module \module{curses} defines the following functions:
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{beep}{}
-Emit a short attention sound.
-\end{funcdesc}
-
-\begin{funcdesc}{can_change_color}{}
-Returns true or false, depending on whether the programmer can change
-the colors displayed by the terminal.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \function{raw()}
-then \function{cbreak()} leaves the terminal in cbreak mode.
-\end{funcdesc}
-
-\begin{funcdesc}{color_content}{color_number}
-Returns the intensity of the red, green, and blue (RGB) components in
-the color \var{color_number}, which must be between \code{0} and
-\constant{COLORS}. A 3-tuple is returned, containing the R,G,B values
-for the given color, which will be between \code{0} (no component) and
-\code{1000} (maximum amount of component).
-\end{funcdesc}
-
-\begin{funcdesc}{color_pair}{color_number}
-Returns the attribute value for displaying text in the specified
-color. This attribute value can be combined with
-\constant{A_STANDOUT}, \constant{A_REVERSE}, and the other
-\constant{A_*} attributes. \function{pair_number()} is the
-counterpart to this function.
-\end{funcdesc}
-
-\begin{funcdesc}{curs_set}{visibility}
-Sets the cursor state. \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \function{reset_prog_mode()} will restore this mode.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \function{reset_shell_mode()} will restore this mode.
-\end{funcdesc}
-
-\begin{funcdesc}{delay_output}{ms}
-Inserts an \var{ms} millisecond pause in output.
-\end{funcdesc}
-
-\begin{funcdesc}{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
-\function{doupdate()} ground updates the physical screen to match the
-virtual screen.
-
-The virtual screen may be updated by a \method{noutrefresh()} call
-after write operations such as \method{addstr()} have been performed
-on a window. The normal \method{refresh()} call is simply
-\method{noutrefresh()} followed by \function{doupdate()}; if you have
-to update multiple windows, you can speed performance and perhaps
-reduce screen flicker by issuing \method{noutrefresh()} calls on
-all windows, followed by a single \function{doupdate()}.
-\end{funcdesc}
-
-\begin{funcdesc}{echo}{}
-Enter echo mode. In echo mode, each character input is echoed to the
-screen as it is entered.
-\end{funcdesc}
-
-\begin{funcdesc}{endwin}{}
-De-initialize the library, and return terminal to normal status.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{filter}{}
-The \function{filter()} routine, if used, must be called before
-\function{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \function{beep()}.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{getmouse}{}
-After \method{getch()} returns \constant{KEY_MOUSE} to signal a mouse
-event, this method should be call to retrieve the queued mouse event,
-represented as a 5-tuple
-\code{(\var{id}, \var{x}, \var{y}, \var{z}, \var{bstate})}.
-\var{id} is an ID value used to distinguish multiple devices,
-and \var{x}, \var{y}, \var{z} are the event's coordinates. (\var{z}
-is currently unused.). \var{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 \var{n} is the button
-number from 1 to 4:
-\constant{BUTTON\var{n}_PRESSED},
-\constant{BUTTON\var{n}_RELEASED},
-\constant{BUTTON\var{n}_CLICKED},
-\constant{BUTTON\var{n}_DOUBLE_CLICKED},
-\constant{BUTTON\var{n}_TRIPLE_CLICKED},
-\constant{BUTTON_SHIFT},
-\constant{BUTTON_CTRL},
-\constant{BUTTON_ALT}.
-\end{funcdesc}
-
-\begin{funcdesc}{getsyx}{}
-Returns the current coordinates of the virtual screen cursor in y and
-x. If leaveok is currently true, then -1,-1 is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{getwin}{file}
-Reads window related data stored in the file by an earlier
-\function{putwin()} call. The routine then creates and initializes a
-new window using that data, returning the new window object.
-\end{funcdesc}
-
-\begin{funcdesc}{has_colors}{}
-Returns true if the terminal can display colors; otherwise, it
-returns false.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{has_key}{ch}
-Takes a key value \var{ch}, and returns true if the current terminal
-type recognizes a key with that value.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \var{tenths} tenths of seconds, an
-exception is raised if nothing has been typed. The value of
-\var{tenths} must be a number between 1 and 255. Use
-\function{nocbreak()} to leave half-delay mode.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \var{color_number} must be
-between \code{0} and \constant{COLORS}. Each of \var{r}, \var{g},
-\var{b}, must be a value between \code{0} and \code{1000}. When
-\function{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
-\function{can_change_color()} returns \code{1}.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \var{pair_number} must
-be between \code{1} and \code{COLOR_PAIRS - 1} (the \code{0} color
-pair is wired to white on black and cannot be changed). The value of
-\var{fg} and \var{bg} arguments must be between \code{0} and
-\constant{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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.}
-\end{funcdesc}
-
-\begin{funcdesc}{isendwin}{}
-Returns true if \function{endwin()} has been called (that is, the
-curses library has been deinitialized).
-\end{funcdesc}
-
-\begin{funcdesc}{keyname}{k}
-Return the name of the key numbered \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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
-\function{initscr()}.
-\end{funcdesc}
-
-\begin{funcdesc}{meta}{yes}
-If \var{yes} is 1, allow 8-bit characters to be input. If \var{yes} is 0,
-allow only 7-bit chars.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{mousemask}{mousemask}
-Sets the mouse events to be reported, and returns a tuple
-\code{(\var{availmask}, \var{oldmask})}.
-\var{availmask} indicates which of the
-specified mouse events can be reported; on complete failure it returns
-0. \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{napms}{ms}
-Sleep for \var{ms} milliseconds.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \method{refresh()} and \method{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.
-\end{funcdesc}
-
-\begin{funcdesc}{newwin}{\optional{nlines, ncols,} begin_y, begin_x}
-Return a new window, whose left-upper corner is at
-\code{(\var{begin_y}, \var{begin_x})}, and whose height/width is
-\var{nlines}/\var{ncols}.
-
-By default, the window will extend from the
-specified position to the lower right corner of the screen.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{nocbreak}{}
-Leave cbreak mode. Return to normal ``cooked'' mode with line buffering.
-\end{funcdesc}
-
-\begin{funcdesc}{noecho}{}
-Leave echo mode. Echoing of input characters is turned off.
-\end{funcdesc}
-
-\begin{funcdesc}{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
-\code{addch('\e 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.
-\end{funcdesc}
-
-\begin{funcdesc}{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
-\function{noqiflush()} in a signal handler if you want output
-to continue as though the interrupt had not occurred, after the
-handler exits.
-\end{funcdesc}
-
-\begin{funcdesc}{noraw}{}
-Leave raw mode. Return to normal ``cooked'' mode with line buffering.
-\end{funcdesc}
-
-\begin{funcdesc}{pair_content}{pair_number}
-Returns a tuple \code{(\var{fg}, \var{bg})} containing the colors for
-the requested color pair. The value of \var{pair_number} must be
-between \code{1} and \code{\constant{COLOR_PAIRS} - 1}.
-\end{funcdesc}
-
-\begin{funcdesc}{pair_number}{attr}
-Returns the number of the color-pair set by the attribute value
-\var{attr}. \function{color_pair()} is the counterpart to this
-function.
-\end{funcdesc}
-
-\begin{funcdesc}{putp}{string}
-Equivalent to \code{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.
-\end{funcdesc}
-
-\begin{funcdesc}{qiflush}{ \optional{flag} }
-If \var{flag} is false, the effect is the same as calling
-\function{noqiflush()}. If \var{flag} is true, or no argument is
-provided, the queues will be flushed when these control characters are
-read.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{reset_prog_mode}{}
-Restores the terminal to ``program'' mode, as previously saved
-by \function{def_prog_mode()}.
-\end{funcdesc}
-
-\begin{funcdesc}{reset_shell_mode}{}
-Restores the terminal to ``shell'' mode, as previously saved
-by \function{def_shell_mode()}.
-\end{funcdesc}
-
-\begin{funcdesc}{setsyx}{y, x}
-Sets the virtual screen cursor to \var{y}, \var{x}.
-If \var{y} and \var{x} are both -1, then leaveok is set.
-\end{funcdesc}
-
-\begin{funcdesc}{setupterm}{\optional{termstr, fd}}
-Initializes the terminal. \var{termstr} is a string giving the
-terminal name; if omitted, the value of the TERM environment variable
-will be used. \var{fd} is the file descriptor to which any
-initialization sequences will be sent; if not supplied, the file
-descriptor for \code{sys.stdout} will be used.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \function{initscr()}.
-
-\function{start_color()} initializes eight basic colors (black, red,
-green, yellow, blue, magenta, cyan, and white), and two global
-variables in the \module{curses} module, \constant{COLORS} and
-\constant{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{termname}{}
-Returns the value of the environment variable TERM, truncated to 14
-characters.
-\end{funcdesc}
-
-\begin{funcdesc}{tigetflag}{capname}
-Returns the value of the Boolean capability corresponding to the
-terminfo capability name \var{capname}. The value \code{-1} is
-returned if \var{capname} is not a Boolean capability, or \code{0} if
-it is canceled or absent from the terminal description.
-\end{funcdesc}
-
-\begin{funcdesc}{tigetnum}{capname}
-Returns the value of the numeric capability corresponding to the
-terminfo capability name \var{capname}. The value \code{-2} is
-returned if \var{capname} is not a numeric capability, or \code{-1} if
-it is canceled or absent from the terminal description.
-\end{funcdesc}
-
-\begin{funcdesc}{tigetstr}{capname}
-Returns the value of the string capability corresponding to the
-terminfo capability name \var{capname}. \code{None} is returned if
-\var{capname} is not a string capability, or is canceled or absent
-from the terminal description.
-\end{funcdesc}
-
-\begin{funcdesc}{tparm}{str\optional{,...}}
-Instantiates the string \var{str} with the supplied parameters, where
-\var{str} should be a parameterized string obtained from the terminfo
-database. E.g. \code{tparm(tigetstr("cup"), 5, 3)} could result in
-\code{'\e{}033[6;4H'}, the exact result depending on terminal type.
-\end{funcdesc}
-
-\begin{funcdesc}{typeahead}{fd}
-Specifies that the file descriptor \var{fd} be used for typeahead
-checking. If \var{fd} is \code{-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.
-\end{funcdesc}
-
-\begin{funcdesc}{unctrl}{ch}
-Returns a string which is a printable representation of the character
-\var{ch}. Control characters are displayed as a caret followed by the
-character, for example as \code{\textasciicircum C}. Printing
-characters are left as they are.
-\end{funcdesc}
-
-\begin{funcdesc}{ungetch}{ch}
-Push \var{ch} so the next \method{getch()} will return it.
-\note{Only one \var{ch} can be pushed before \method{getch()}
-is called.}
-\end{funcdesc}
-
-\begin{funcdesc}{ungetmouse}{id, x, y, z, bstate}
-Push a \constant{KEY_MOUSE} event onto the input queue, associating
-the given state data with it.
-\end{funcdesc}
-
-\begin{funcdesc}{use_env}{flag}
-If used, this function should be called before \function{initscr()} or
-newterm are called. When \var{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).
-\end{funcdesc}
-
-\begin{funcdesc}{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,
-\code{init_pair(x, curses.COLOR_RED, -1)} initializes, for instance,
-color pair \var{x} to a red foreground color on the default background.
-\end{funcdesc}
-
-\subsection{Window Objects \label{curses-window-objects}}
-
-Window objects, as returned by \function{initscr()} and
-\function{newwin()} above, have the
-following methods:
-
-\begin{methoddesc}[window]{addch}{\optional{y, x,} ch\optional{, attr}}
-\note{A \emph{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 \function{ord()} is handy for conveying strings to codes.}
-
-Paint character \var{ch} at \code{(\var{y}, \var{x})} with attributes
-\var{attr}, overwriting any character previously painter at that
-location. By default, the character position and attributes are the
-current settings for the window object.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{addnstr}{\optional{y, x,} str, n\optional{, attr}}
-Paint at most \var{n} characters of the
-string \var{str} at \code{(\var{y}, \var{x})} with attributes
-\var{attr}, overwriting anything previously on the display.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{addstr}{\optional{y, x,} str\optional{, attr}}
-Paint the string \var{str} at \code{(\var{y}, \var{x})} with attributes
-\var{attr}, overwriting anything previously on the display.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{attroff}{attr}
-Remove attribute \var{attr} from the ``background'' set applied to all
-writes to the current window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{attron}{attr}
-Add attribute \var{attr} from the ``background'' set applied to all
-writes to the current window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{attrset}{attr}
-Set the ``background'' set of attributes to \var{attr}. This set is
-initially 0 (no attributes).
-\end{methoddesc}
-
-\begin{methoddesc}[window]{bkgd}{ch\optional{, attr}}
-Sets the background property of the window to the character \var{ch},
-with attributes \var{attr}. The change is then applied to every
-character position in that window:
-\begin{itemize}
-\item
-The attribute of every character in the window is
-changed to the new background attribute.
-\item
-Wherever the former background character appears,
-it is changed to the new background character.
-\end{itemize}
-
-\end{methoddesc}
-
-\begin{methoddesc}[window]{bkgdset}{ch\optional{, 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.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{border}{\optional{ls\optional{, rs\optional{,
- ts\optional{, bs\optional{, tl\optional{,
- tr\optional{, bl\optional{, 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 \code{0} value for any parameter will cause the
-default character to be used for that parameter. Keyword parameters
-can \emph{not} be used. The defaults are listed in this table:}
-
-\begin{tableiii}{l|l|l}{var}{Parameter}{Description}{Default value}
- \lineiii{ls}{Left side}{\constant{ACS_VLINE}}
- \lineiii{rs}{Right side}{\constant{ACS_VLINE}}
- \lineiii{ts}{Top}{\constant{ACS_HLINE}}
- \lineiii{bs}{Bottom}{\constant{ACS_HLINE}}
- \lineiii{tl}{Upper-left corner}{\constant{ACS_ULCORNER}}
- \lineiii{tr}{Upper-right corner}{\constant{ACS_URCORNER}}
- \lineiii{bl}{Bottom-left corner}{\constant{ACS_LLCORNER}}
- \lineiii{br}{Bottom-right corner}{\constant{ACS_LRCORNER}}
-\end{tableiii}
-\end{methoddesc}
-
-\begin{methoddesc}[window]{box}{\optional{vertch, horch}}
-Similar to \method{border()}, but both \var{ls} and \var{rs} are
-\var{vertch} and both \var{ts} and {bs} are \var{horch}. The default
-corner characters are always used by this function.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{chgat}{\optional{y, x, } \optional{num,} attr}
-Sets the attributes of \var{num} characters at the current cursor
-position, or at position \code{(\var{y}, \var{x})} if supplied. If no
-value of \var{num} is given or \var{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 \method{touchline} method so that the
-contents will be redisplayed by the next window refresh.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{clear}{}
-Like \method{erase()}, but also causes the whole window to be repainted
-upon next call to \method{refresh()}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{clearok}{yes}
-If \var{yes} is 1, the next call to \method{refresh()}
-will clear the window completely.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{clrtobot}{}
-Erase from cursor to the end of the window: all lines below the cursor
-are deleted, and then the equivalent of \method{clrtoeol()} is performed.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{clrtoeol}{}
-Erase from cursor to the end of the line.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{cursyncup}{}
-Updates the current cursor position of all the ancestors of the window
-to reflect the current cursor position of the window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{delch}{\optional{y, x}}
-Delete any character at \code{(\var{y}, \var{x})}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{deleteln}{}
-Delete the line under the cursor. All following lines are moved up
-by 1 line.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{derwin}{\optional{nlines, ncols,} begin_y, begin_x}
-An abbreviation for ``derive window'', \method{derwin()} is the same
-as calling \method{subwin()}, except that \var{begin_y} and
-\var{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.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{echochar}{ch\optional{, attr}}
-Add character \var{ch} with attribute \var{attr}, and immediately
-call \method{refresh()} on the window.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{erase}{}
-Clear the window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{getbegyx}{}
-Return a tuple \code{(\var{y}, \var{x})} of co-ordinates of upper-left
-corner.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{getch}{\optional{y, x}}
-Get a character. Note that the integer returned does \emph{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.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{getkey}{\optional{y, x}}
-Get a character, returning a string instead of an integer, as
-\method{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.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{getmaxyx}{}
-Return a tuple \code{(\var{y}, \var{x})} of the height and width of
-the window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{getparyx}{}
-Returns the beginning coordinates of this window relative to its
-parent window into two integer variables y and x. Returns
-\code{-1,-1} if this window has no parent.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{getstr}{\optional{y, x}}
-Read a string from the user, with primitive line editing capacity.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{getyx}{}
-Return a tuple \code{(\var{y}, \var{x})} of current cursor position
-relative to the window's upper-left corner.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{hline}{\optional{y, x,} ch, n}
-Display a horizontal line starting at \code{(\var{y}, \var{x})} with
-length \var{n} consisting of the character \var{ch}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{idcok}{flag}
-If \var{flag} is false, curses no longer considers using the hardware
-insert/delete character feature of the terminal; if \var{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.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{idlok}{yes}
-If called with \var{yes} equal to 1, \module{curses} will try and use
-hardware line editing facilities. Otherwise, line insertion/deletion
-are disabled.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{immedok}{flag}
-If \var{flag} is true, any change in the window image
-automatically causes the window to be refreshed; you no longer
-have to call \method{refresh()} yourself. However, it may
-degrade performance considerably, due to repeated calls to
-wrefresh. This option is disabled by default.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{inch}{\optional{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.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{insch}{\optional{y, x,} ch\optional{, attr}}
-Paint character \var{ch} at \code{(\var{y}, \var{x})} with attributes
-\var{attr}, moving the line from position \var{x} right by one
-character.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{insdelln}{nlines}
-Inserts \var{nlines} lines into the specified window above the current
-line. The \var{nlines} bottom lines are lost. For negative
-\var{nlines}, delete \var{nlines} lines starting with the one under
-the cursor, and move the remaining lines up. The bottom \var{nlines}
-lines are cleared. The current cursor position remains the same.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{insertln}{}
-Insert a blank line under the cursor. All following lines are moved
-down by 1 line.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{insnstr}{\optional{y, x,} str, n \optional{, attr}}
-Insert a character string (as many characters as will fit on the line)
-before the character under the cursor, up to \var{n} characters.
-If \var{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
-\var{y}, \var{x}, if specified).
-\end{methoddesc}
-
-\begin{methoddesc}[window]{insstr}{\optional{y, x, } str \optional{, 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
-\var{y}, \var{x}, if specified).
-\end{methoddesc}
-
-\begin{methoddesc}[window]{instr}{\optional{y, x} \optional{, n}}
-Returns a string of characters, extracted from the window starting at
-the current cursor position, or at \var{y}, \var{x} if specified.
-Attributes are stripped from the characters. If \var{n} is specified,
-\method{instr()} returns return a string at most \var{n} characters
-long (exclusive of the trailing NUL).
-\end{methoddesc}
-
-\begin{methoddesc}[window]{is_linetouched}{\var{line}}
-Returns true if the specified line was modified since the last call to
-\method{refresh()}; otherwise returns false. Raises a
-\exception{curses.error} exception if \var{line} is not valid
-for the given window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{is_wintouched}{}
-Returns true if the specified window was modified since the last call to
-\method{refresh()}; otherwise returns false.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{keypad}{yes}
-If \var{yes} is 1, escape sequences generated by some keys (keypad,
-function keys) will be interpreted by \module{curses}.
-If \var{yes} is 0, escape sequences will be left as is in the input
-stream.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{leaveok}{yes}
-If \var{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 \var{yes} is 0, cursor will always be at ``cursor position'' after
-an update.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{move}{new_y, new_x}
-Move cursor to \code{(\var{new_y}, \var{new_x})}.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{mvwin}{new_y, new_x}
-Move the window so its upper-left corner is at
-\code{(\var{new_y}, \var{new_x})}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{nodelay}{yes}
-If \var{yes} is \code{1}, \method{getch()} will be non-blocking.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{notimeout}{yes}
-If \var{yes} is \code{1}, escape sequences will not be timed out.
-
-If \var{yes} is \code{0}, after a few milliseconds, an escape sequence
-will not be interpreted, and will be left in the input stream as is.
-\end{methoddesc}
-
-\begin{methoddesc}[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
-\function{doupdate()}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{overlay}{destwin\optional{, sminrow, smincol,
- dminrow, dmincol, dmaxrow, dmaxcol}}
-Overlay the window on top of \var{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 \var{destwin}.
-
-To get fine-grained control over the copied region, the second form
-of \method{overlay()} can be used. \var{sminrow} and \var{smincol} are
-the upper-left coordinates of the source window, and the other variables
-mark a rectangle in the destination window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{overwrite}{destwin\optional{, sminrow, smincol,
- dminrow, dmincol, dmaxrow, dmaxcol}}
-Overwrite the window on top of \var{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 \var{destwin}.
-
-To get fine-grained control over the copied region, the second form
-of \method{overwrite()} can be used. \var{sminrow} and \var{smincol} are
-the upper-left coordinates of the source window, the other variables
-mark a rectangle in the destination window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{putwin}{file}
-Writes all data associated with the window into the provided file
-object. This information can be later retrieved using the
-\function{getwin()} function.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{redrawln}{beg, num}
-Indicates that the \var{num} screen lines, starting at line \var{beg},
-are corrupted and should be completely redrawn on the next
-\method{refresh()} call.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{redrawwin}{}
-Touches the entire window, causing it to be completely redrawn on the
-next \method{refresh()} call.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{refresh}{\optional{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 \function{newpad()}. The additional parameters are
-needed to indicate what part of the pad and screen are involved.
-\var{pminrow} and \var{pmincol} specify the upper left-hand corner of the
-rectangle to be displayed in the pad. \var{sminrow}, \var{smincol},
-\var{smaxrow}, and \var{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 \var{pminrow}, \var{pmincol},
-\var{sminrow}, or \var{smincol} are treated as if they were zero.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{scroll}{\optional{lines\code{ = 1}}}
-Scroll the screen or scrolling region upward by \var{lines} lines.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \var{flag} is false, the cursor is left
-on the bottom line. If \var{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
-\method{idlok()}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{setscrreg}{top, bottom}
-Set the scrolling region from line \var{top} to line \var{bottom}. All
-scrolling actions will take place in this region.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{standend}{}
-Turn off the standout attribute. On some terminals this has the
-side effect of turning off all attributes.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{standout}{}
-Turn on attribute \var{A_STANDOUT}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{subpad}{\optional{nlines, ncols,} begin_y, begin_x}
-Return a sub-window, whose upper-left corner is at
-\code{(\var{begin_y}, \var{begin_x})}, and whose width/height is
-\var{ncols}/\var{nlines}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{subwin}{\optional{nlines, ncols,} begin_y, begin_x}
-Return a sub-window, whose upper-left corner is at
-\code{(\var{begin_y}, \var{begin_x})}, and whose width/height is
-\var{ncols}/\var{nlines}.
-
-By default, the sub-window will extend from the
-specified position to the lower right corner of the window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{syncdown}{}
-Touches each location in the window that has been touched in any of
-its ancestor windows. This routine is called by \method{refresh()},
-so it should almost never be necessary to call it manually.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{syncok}{flag}
-If called with \var{flag} set to true, then \method{syncup()} is
-called automatically whenever there is a change in the window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{syncup}{}
-Touches all locations in ancestors of the window that have been changed in
-the window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{timeout}{delay}
-Sets blocking or non-blocking read behavior for the window. If
-\var{delay} is negative, blocking read is used (which will wait
-indefinitely for input). If \var{delay} is zero, then non-blocking
-read is used, and -1 will be returned by \method{getch()} if no input
-is waiting. If \var{delay} is positive, then \method{getch()} will
-block for \var{delay} milliseconds, and return -1 if there is still no
-input at the end of that time.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{touchline}{start, count\optional{, changed}}
-Pretend \var{count} lines have been changed, starting with line
-\var{start}. If \var{changed} is supplied, it specifies
-whether the affected lines are marked as
-having been changed (\var{changed}=1) or unchanged (\var{changed}=0).
-\end{methoddesc}
-
-\begin{methoddesc}[window]{touchwin}{}
-Pretend the whole window has been changed, for purposes of drawing
-optimizations.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{untouchwin}{}
-Marks all lines in the window as unchanged since the last call to
-\method{refresh()}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{vline}{\optional{y, x,} ch, n}
-Display a vertical line starting at \code{(\var{y}, \var{x})} with
-length \var{n} consisting of the character \var{ch}.
-\end{methoddesc}
-
-\subsection{Constants}
-
-The \module{curses} module defines the following data members:
-
-\begin{datadesc}{ERR}
-Some curses routines that return an integer, such as
-\function{getch()}, return \constant{ERR} upon failure.
-\end{datadesc}
-
-\begin{datadesc}{OK}
-Some curses routines that return an integer, such as
-\function{napms()}, return \constant{OK} upon success.
-\end{datadesc}
-
-\begin{datadesc}{version}
-A string representing the current version of the module.
-Also available as \constant{__version__}.
-\end{datadesc}
-
-Several constants are available to specify character cell attributes:
-
-\begin{tableii}{l|l}{code}{Attribute}{Meaning}
- \lineii{A_ALTCHARSET}{Alternate character set mode.}
- \lineii{A_BLINK}{Blink mode.}
- \lineii{A_BOLD}{Bold mode.}
- \lineii{A_DIM}{Dim mode.}
- \lineii{A_NORMAL}{Normal attribute.}
- \lineii{A_STANDOUT}{Standout mode.}
- \lineii{A_UNDERLINE}{Underline mode.}
-\end{tableii}
-
-Keys are referred to by integer constants with names starting with
-\samp{KEY_}. The exact keycaps available are system dependent.
-
-% XXX this table is far too large!
-% XXX should this table be alphabetized?
-
-\begin{longtableii}{l|l}{code}{Key constant}{Key}
- \lineii{KEY_MIN}{Minimum key value}
- \lineii{KEY_BREAK}{ Break key (unreliable) }
- \lineii{KEY_DOWN}{ Down-arrow }
- \lineii{KEY_UP}{ Up-arrow }
- \lineii{KEY_LEFT}{ Left-arrow }
- \lineii{KEY_RIGHT}{ Right-arrow }
- \lineii{KEY_HOME}{ Home key (upward+left arrow) }
- \lineii{KEY_BACKSPACE}{ Backspace (unreliable) }
- \lineii{KEY_F0}{ Function keys. Up to 64 function keys are supported. }
- \lineii{KEY_F\var{n}}{ Value of function key \var{n} }
- \lineii{KEY_DL}{ Delete line }
- \lineii{KEY_IL}{ Insert line }
- \lineii{KEY_DC}{ Delete character }
- \lineii{KEY_IC}{ Insert char or enter insert mode }
- \lineii{KEY_EIC}{ Exit insert char mode }
- \lineii{KEY_CLEAR}{ Clear screen }
- \lineii{KEY_EOS}{ Clear to end of screen }
- \lineii{KEY_EOL}{ Clear to end of line }
- \lineii{KEY_SF}{ Scroll 1 line forward }
- \lineii{KEY_SR}{ Scroll 1 line backward (reverse) }
- \lineii{KEY_NPAGE}{ Next page }
- \lineii{KEY_PPAGE}{ Previous page }
- \lineii{KEY_STAB}{ Set tab }
- \lineii{KEY_CTAB}{ Clear tab }
- \lineii{KEY_CATAB}{ Clear all tabs }
- \lineii{KEY_ENTER}{ Enter or send (unreliable) }
- \lineii{KEY_SRESET}{ Soft (partial) reset (unreliable) }
- \lineii{KEY_RESET}{ Reset or hard reset (unreliable) }
- \lineii{KEY_PRINT}{ Print }
- \lineii{KEY_LL}{ Home down or bottom (lower left) }
- \lineii{KEY_A1}{ Upper left of keypad }
- \lineii{KEY_A3}{ Upper right of keypad }
- \lineii{KEY_B2}{ Center of keypad }
- \lineii{KEY_C1}{ Lower left of keypad }
- \lineii{KEY_C3}{ Lower right of keypad }
- \lineii{KEY_BTAB}{ Back tab }
- \lineii{KEY_BEG}{ Beg (beginning) }
- \lineii{KEY_CANCEL}{ Cancel }
- \lineii{KEY_CLOSE}{ Close }
- \lineii{KEY_COMMAND}{ Cmd (command) }
- \lineii{KEY_COPY}{ Copy }
- \lineii{KEY_CREATE}{ Create }
- \lineii{KEY_END}{ End }
- \lineii{KEY_EXIT}{ Exit }
- \lineii{KEY_FIND}{ Find }
- \lineii{KEY_HELP}{ Help }
- \lineii{KEY_MARK}{ Mark }
- \lineii{KEY_MESSAGE}{ Message }
- \lineii{KEY_MOVE}{ Move }
- \lineii{KEY_NEXT}{ Next }
- \lineii{KEY_OPEN}{ Open }
- \lineii{KEY_OPTIONS}{ Options }
- \lineii{KEY_PREVIOUS}{ Prev (previous) }
- \lineii{KEY_REDO}{ Redo }
- \lineii{KEY_REFERENCE}{ Ref (reference) }
- \lineii{KEY_REFRESH}{ Refresh }
- \lineii{KEY_REPLACE}{ Replace }
- \lineii{KEY_RESTART}{ Restart }
- \lineii{KEY_RESUME}{ Resume }
- \lineii{KEY_SAVE}{ Save }
- \lineii{KEY_SBEG}{ Shifted Beg (beginning) }
- \lineii{KEY_SCANCEL}{ Shifted Cancel }
- \lineii{KEY_SCOMMAND}{ Shifted Command }
- \lineii{KEY_SCOPY}{ Shifted Copy }
- \lineii{KEY_SCREATE}{ Shifted Create }
- \lineii{KEY_SDC}{ Shifted Delete char }
- \lineii{KEY_SDL}{ Shifted Delete line }
- \lineii{KEY_SELECT}{ Select }
- \lineii{KEY_SEND}{ Shifted End }
- \lineii{KEY_SEOL}{ Shifted Clear line }
- \lineii{KEY_SEXIT}{ Shifted Dxit }
- \lineii{KEY_SFIND}{ Shifted Find }
- \lineii{KEY_SHELP}{ Shifted Help }
- \lineii{KEY_SHOME}{ Shifted Home }
- \lineii{KEY_SIC}{ Shifted Input }
- \lineii{KEY_SLEFT}{ Shifted Left arrow }
- \lineii{KEY_SMESSAGE}{ Shifted Message }
- \lineii{KEY_SMOVE}{ Shifted Move }
- \lineii{KEY_SNEXT}{ Shifted Next }
- \lineii{KEY_SOPTIONS}{ Shifted Options }
- \lineii{KEY_SPREVIOUS}{ Shifted Prev }
- \lineii{KEY_SPRINT}{ Shifted Print }
- \lineii{KEY_SREDO}{ Shifted Redo }
- \lineii{KEY_SREPLACE}{ Shifted Replace }
- \lineii{KEY_SRIGHT}{ Shifted Right arrow }
- \lineii{KEY_SRSUME}{ Shifted Resume }
- \lineii{KEY_SSAVE}{ Shifted Save }
- \lineii{KEY_SSUSPEND}{ Shifted Suspend }
- \lineii{KEY_SUNDO}{ Shifted Undo }
- \lineii{KEY_SUSPEND}{ Suspend }
- \lineii{KEY_UNDO}{ Undo }
- \lineii{KEY_MOUSE}{ Mouse event has occurred }
- \lineii{KEY_RESIZE}{ Terminal resize event }
- \lineii{KEY_MAX}{Maximum key value}
-\end{longtableii}
-
-On VT100s and their software emulations, such as X terminal emulators,
-there are normally at least four function keys (\constant{KEY_F1},
-\constant{KEY_F2}, \constant{KEY_F3}, \constant{KEY_F4}) available,
-and the arrow keys mapped to \constant{KEY_UP}, \constant{KEY_DOWN},
-\constant{KEY_LEFT} and \constant{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:
-
-\begin{tableii}{l|l}{kbd}{Keycap}{Constant}
- \lineii{Insert}{KEY_IC}
- \lineii{Delete}{KEY_DC}
- \lineii{Home}{KEY_HOME}
- \lineii{End}{KEY_END}
- \lineii{Page Up}{KEY_NPAGE}
- \lineii{Page Down}{KEY_PPAGE}
-\end{tableii}
-
-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 \function{initscr()} has
-been called.}
-
-\begin{longtableii}{l|l}{code}{ACS code}{Meaning}
- \lineii{ACS_BBSS}{alternate name for upper right corner}
- \lineii{ACS_BLOCK}{solid square block}
- \lineii{ACS_BOARD}{board of squares}
- \lineii{ACS_BSBS}{alternate name for horizontal line}
- \lineii{ACS_BSSB}{alternate name for upper left corner}
- \lineii{ACS_BSSS}{alternate name for top tee}
- \lineii{ACS_BTEE}{bottom tee}
- \lineii{ACS_BULLET}{bullet}
- \lineii{ACS_CKBOARD}{checker board (stipple)}
- \lineii{ACS_DARROW}{arrow pointing down}
- \lineii{ACS_DEGREE}{degree symbol}
- \lineii{ACS_DIAMOND}{diamond}
- \lineii{ACS_GEQUAL}{greater-than-or-equal-to}
- \lineii{ACS_HLINE}{horizontal line}
- \lineii{ACS_LANTERN}{lantern symbol}
- \lineii{ACS_LARROW}{left arrow}
- \lineii{ACS_LEQUAL}{less-than-or-equal-to}
- \lineii{ACS_LLCORNER}{lower left-hand corner}
- \lineii{ACS_LRCORNER}{lower right-hand corner}
- \lineii{ACS_LTEE}{left tee}
- \lineii{ACS_NEQUAL}{not-equal sign}
- \lineii{ACS_PI}{letter pi}
- \lineii{ACS_PLMINUS}{plus-or-minus sign}
- \lineii{ACS_PLUS}{big plus sign}
- \lineii{ACS_RARROW}{right arrow}
- \lineii{ACS_RTEE}{right tee}
- \lineii{ACS_S1}{scan line 1}
- \lineii{ACS_S3}{scan line 3}
- \lineii{ACS_S7}{scan line 7}
- \lineii{ACS_S9}{scan line 9}
- \lineii{ACS_SBBS}{alternate name for lower right corner}
- \lineii{ACS_SBSB}{alternate name for vertical line}
- \lineii{ACS_SBSS}{alternate name for right tee}
- \lineii{ACS_SSBB}{alternate name for lower left corner}
- \lineii{ACS_SSBS}{alternate name for bottom tee}
- \lineii{ACS_SSSB}{alternate name for left tee}
- \lineii{ACS_SSSS}{alternate name for crossover or big plus}
- \lineii{ACS_STERLING}{pound sterling}
- \lineii{ACS_TTEE}{top tee}
- \lineii{ACS_UARROW}{up arrow}
- \lineii{ACS_ULCORNER}{upper left corner}
- \lineii{ACS_URCORNER}{upper right corner}
- \lineii{ACS_VLINE}{vertical line}
-\end{longtableii}
-
-The following table lists the predefined colors:
-
-\begin{tableii}{l|l}{code}{Constant}{Color}
- \lineii{COLOR_BLACK}{Black}
- \lineii{COLOR_BLUE}{Blue}
- \lineii{COLOR_CYAN}{Cyan (light greenish blue)}
- \lineii{COLOR_GREEN}{Green}
- \lineii{COLOR_MAGENTA}{Magenta (purplish red)}
- \lineii{COLOR_RED}{Red}
- \lineii{COLOR_WHITE}{White}
- \lineii{COLOR_YELLOW}{Yellow}
-\end{tableii}
-
-\section{\module{curses.textpad} ---
- Text input widget for curses programs}
-
-\declaremodule{standard}{curses.textpad}
-\sectionauthor{Eric Raymond}{esr@thyrsus.com}
-\moduleauthor{Eric Raymond}{esr@thyrsus.com}
-\modulesynopsis{Emacs-like input editing in a curses window.}
-\versionadded{1.6}
-
-The \module{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 \module{curses.textpad} defines the following function:
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-
-\subsection{Textbox objects \label{curses-textpad-objects}}
-
-You can instantiate a \class{Textbox} object as follows:
-
-\begin{classdesc}{Textbox}{win}
-Return a textbox widget object. The \var{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 \code{(0, 0)}.
-The instance's \member{stripspaces} flag is initially on.
-\end{classdesc}
-
-\class{Textbox} objects have the following methods:
-
-\begin{methoddesc}{edit}{\optional{validator}}
-This is the entry point you will normally use. It accepts editing
-keystrokes until one of the termination keystrokes is entered. If
-\var{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 \member{stripspaces} member.
-\end{methoddesc}
-
-\begin{methoddesc}{do_command}{ch}
-Process a single command keystroke. Here are the supported special
-keystrokes:
-
-\begin{tableii}{l|l}{kbd}{Keystroke}{Action}
- \lineii{Control-A}{Go to left edge of window.}
- \lineii{Control-B}{Cursor left, wrapping to previous line if appropriate.}
- \lineii{Control-D}{Delete character under cursor.}
- \lineii{Control-E}{Go to right edge (stripspaces off) or end of line
- (stripspaces on).}
- \lineii{Control-F}{Cursor right, wrapping to next line when appropriate.}
- \lineii{Control-G}{Terminate, returning the window contents.}
- \lineii{Control-H}{Delete character backward.}
- \lineii{Control-J}{Terminate if the window is 1 line, otherwise
- insert newline.}
- \lineii{Control-K}{If line is blank, delete it, otherwise clear to
- end of line.}
- \lineii{Control-L}{Refresh screen.}
- \lineii{Control-N}{Cursor down; move down one line.}
- \lineii{Control-O}{Insert a blank line at cursor location.}
- \lineii{Control-P}{Cursor up; move up one line.}
-\end{tableii}
-
-Move operations do nothing if the cursor is at an edge where the
-movement is not possible. The following synonyms are supported where
-possible:
-
-\begin{tableii}{l|l}{constant}{Constant}{Keystroke}
- \lineii{KEY_LEFT}{\kbd{Control-B}}
- \lineii{KEY_RIGHT}{\kbd{Control-F}}
- \lineii{KEY_UP}{\kbd{Control-P}}
- \lineii{KEY_DOWN}{\kbd{Control-N}}
- \lineii{KEY_BACKSPACE}{\kbd{Control-h}}
-\end{tableii}
-
-All other keystrokes are treated as a command to insert the given
-character and move right (with line wrapping).
-\end{methoddesc}
-
-\begin{methoddesc}{gather}{}
-This method returns the window contents as a string; whether blanks in
-the window are included is affected by the \member{stripspaces}
-member.
-\end{methoddesc}
-
-\begin{memberdesc}{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.
-\end{memberdesc}
-
-
-\section{\module{curses.wrapper} ---
- Terminal handler for curses programs}
-
-\declaremodule{standard}{curses.wrapper}
-\sectionauthor{Eric Raymond}{esr@thyrsus.com}
-\moduleauthor{Eric Raymond}{esr@thyrsus.com}
-\modulesynopsis{Terminal configuration wrapper for curses programs.}
-\versionadded{1.6}
-
-This module supplies one function, \function{wrapper()}, which runs
-another function which should be the rest of your curses-using
-application. If the application raises an exception,
-\function{wrapper()} will restore the terminal to a sane state before
-re-raising the exception and generating a traceback.
-
-\begin{funcdesc}{wrapper}{func, \moreargs}
-Wrapper function that initializes curses and calls another function,
-\var{func}, restoring normal keyboard/screen behavior on error.
-The callable object \var{func} is then passed the main window 'stdscr'
-as its first argument, followed by any other arguments passed to
-\function{wrapper()}.
-\end{funcdesc}
-
-Before calling the hook function, \function{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.
-
diff --git a/Doc/lib/libcursespanel.tex b/Doc/lib/libcursespanel.tex
deleted file mode 100644
index 14d83e3..0000000
--- a/Doc/lib/libcursespanel.tex
+++ /dev/null
@@ -1,96 +0,0 @@
-\section{\module{curses.panel} ---
- A panel stack extension for curses.}
-
-\declaremodule{standard}{curses.panel}
-\sectionauthor{A.M. Kuchling}{amk@amk.ca}
-\modulesynopsis{A panel stack extension that adds depth to
- curses windows.}
-
-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.
-
-\subsection{Functions \label{cursespanel-functions}}
-
-The module \module{curses.panel} defines the following functions:
-
-
-\begin{funcdesc}{bottom_panel}{}
-Returns the bottom panel in the panel stack.
-\end{funcdesc}
-
-\begin{funcdesc}{new_panel}{win}
-Returns a panel object, associating it with the given window \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{top_panel}{}
-Returns the top panel in the panel stack.
-\end{funcdesc}
-
-\begin{funcdesc}{update_panels}{}
-Updates the virtual screen after changes in the panel stack. This does
-not call \function{curses.doupdate()}, so you'll have to do this yourself.
-\end{funcdesc}
-
-\subsection{Panel Objects \label{curses-panel-objects}}
-
-Panel objects, as returned by \function{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:
-
-\begin{methoddesc}[Panel]{above}{}
-Returns the panel above the current panel.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{below}{}
-Returns the panel below the current panel.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{bottom}{}
-Push the panel to the bottom of the stack.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{hidden}{}
-Returns true if the panel is hidden (not visible), false otherwise.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{hide}{}
-Hide the panel. This does not delete the object, it just makes the
-window on screen invisible.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{move}{y, x}
-Move the panel to the screen coordinates \code{(\var{y}, \var{x})}.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{replace}{win}
-Change the window associated with the panel to the window \var{win}.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{set_userptr}{obj}
-Set the panel's user pointer to \var{obj}. This is used to associate an
-arbitrary piece of data with the panel, and can be any Python object.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{show}{}
-Display the panel (which might have been hidden).
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{top}{}
-Push panel to the top of the stack.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{userptr}{}
-Returns the user pointer for the panel. This might be any Python object.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{window}{}
-Returns the window object associated with the panel.
-\end{methoddesc}
diff --git a/Doc/lib/libdatetime.tex b/Doc/lib/libdatetime.tex
deleted file mode 100644
index fb13ea7..0000000
--- a/Doc/lib/libdatetime.tex
+++ /dev/null
@@ -1,1441 +0,0 @@
-% XXX what order should the types be discussed in?
-
-\section{\module{datetime} ---
- Basic date and time types}
-
-\declaremodule{builtin}{datetime}
-\modulesynopsis{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 \module{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.
-
-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,
-\member{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 \module{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 \module{datetime} module exports the following constants:
-
-\begin{datadesc}{MINYEAR}
- The smallest year number allowed in a \class{date} or
- \class{datetime} object. \constant{MINYEAR}
- is \code{1}.
-\end{datadesc}
-
-\begin{datadesc}{MAXYEAR}
- The largest year number allowed in a \class{date} or \class{datetime}
- object. \constant{MAXYEAR} is \code{9999}.
-\end{datadesc}
-
-\begin{seealso}
- \seemodule{calendar}{General calendar related functions.}
- \seemodule{time}{Time access and conversions.}
-\end{seealso}
-
-\subsection{Available Types}
-
-\begin{classdesc*}{date}
- An idealized naive date, assuming the current Gregorian calendar
- always was, and always will be, in effect.
- Attributes: \member{year}, \member{month}, and \member{day}.
-\end{classdesc*}
-
-\begin{classdesc*}{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: \member{hour}, \member{minute}, \member{second},
- \member{microsecond}, and \member{tzinfo}.
-\end{classdesc*}
-
-\begin{classdesc*}{datetime}
- A combination of a date and a time.
- Attributes: \member{year}, \member{month}, \member{day},
- \member{hour}, \member{minute}, \member{second},
- \member{microsecond}, and \member{tzinfo}.
-\end{classdesc*}
-
-\begin{classdesc*}{timedelta}
- A duration expressing the difference between two \class{date},
- \class{time}, or \class{datetime} instances to microsecond
- resolution.
-\end{classdesc*}
-
-\begin{classdesc*}{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).
-\end{classdesc*}
-
-Objects of these types are immutable.
-
-Objects of the \class{date} type are always naive.
-
-An object \var{d} of type \class{time} or \class{datetime} may be
-naive or aware. \var{d} is aware if \code{\var{d}.tzinfo} is not
-\code{None} and \code{\var{d}.tzinfo.utcoffset(\var{d})} does not return
-\code{None}. If \code{\var{d}.tzinfo} is \code{None}, or if
-\code{\var{d}.tzinfo} is not \code{None} but
-\code{\var{d}.tzinfo.utcoffset(\var{d})} returns \code{None}, \var{d}
-is naive.
-
-The distinction between naive and aware doesn't apply to
-\class{timedelta} objects.
-
-Subclass relationships:
-
-\begin{verbatim}
-object
- timedelta
- tzinfo
- time
- date
- datetime
-\end{verbatim}
-
-\subsection{\class{timedelta} Objects \label{datetime-timedelta}}
-
-A \class{timedelta} object represents a duration, the difference
-between two dates or times.
-
-\begin{classdesc}{timedelta}{\optional{days\optional{, seconds\optional{,
- microseconds\optional{, milliseconds\optional{,
- minutes\optional{, hours\optional{, weeks}}}}}}}}
- All arguments are optional and default to \code{0}. Arguments may
- be ints, longs, or floats, and may be positive or negative.
-
- Only \var{days}, \var{seconds} and \var{microseconds} are stored
- internally. Arguments are converted to those units:
-
-\begin{itemize}
- \item A millisecond is converted to 1000 microseconds.
- \item A minute is converted to 60 seconds.
- \item An hour is converted to 3600 seconds.
- \item A week is converted to 7 days.
-\end{itemize}
-
- and days, seconds and microseconds are then normalized so that the
- representation is unique, with
-
-\begin{itemize}
- \item \code{0 <= \var{microseconds} < 1000000}
- \item \code{0 <= \var{seconds} < 3600*24} (the number of seconds in one day)
- \item \code{-999999999 <= \var{days} <= 999999999}
-\end{itemize}
-
- 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,
- \exception{OverflowError} is raised.
-
- Note that normalization of negative values may be surprising at first.
- For example,
-
-\begin{verbatim}
->>> d = timedelta(microseconds=-1)
->>> (d.days, d.seconds, d.microseconds)
-(-1, 86399, 999999)
-\end{verbatim}
-\end{classdesc}
-
-Class attributes are:
-
-\begin{memberdesc}{min}
- The most negative \class{timedelta} object,
- \code{timedelta(-999999999)}.
-\end{memberdesc}
-
-\begin{memberdesc}{max}
- The most positive \class{timedelta} object,
- \code{timedelta(days=999999999, hours=23, minutes=59, seconds=59,
- microseconds=999999)}.
-\end{memberdesc}
-
-\begin{memberdesc}{resolution}
- The smallest possible difference between non-equal
- \class{timedelta} objects, \code{timedelta(microseconds=1)}.
-\end{memberdesc}
-
-Note that, because of normalization, \code{timedelta.max} \textgreater
-\code{-timedelta.min}. \code{-timedelta.max} is not representable as
-a \class{timedelta} object.
-
-Instance attributes (read-only):
-
-\begin{tableii}{c|l}{code}{Attribute}{Value}
- \lineii{days}{Between -999999999 and 999999999 inclusive}
- \lineii{seconds}{Between 0 and 86399 inclusive}
- \lineii{microseconds}{Between 0 and 999999 inclusive}
-\end{tableii}
-
-Supported operations:
-
-% XXX this table is too wide!
-\begin{tableii}{c|l}{code}{Operation}{Result}
- \lineii{\var{t1} = \var{t2} + \var{t3}}
- {Sum of \var{t2} and \var{t3}.
- Afterwards \var{t1}-\var{t2} == \var{t3} and \var{t1}-\var{t3}
- == \var{t2} are true.
- (1)}
- \lineii{\var{t1} = \var{t2} - \var{t3}}
- {Difference of \var{t2} and \var{t3}.
- Afterwards \var{t1} == \var{t2} - \var{t3} and
- \var{t2} == \var{t1} + \var{t3} are true.
- (1)}
- \lineii{\var{t1} = \var{t2} * \var{i} or \var{t1} = \var{i} * \var{t2}}
- {Delta multiplied by an integer or long.
- Afterwards \var{t1} // i == \var{t2} is true,
- provided \code{i != 0}.}
- \lineii{}{In general, \var{t1} * i == \var{t1} * (i-1) + \var{t1} is true.
- (1)}
- \lineii{\var{t1} = \var{t2} // \var{i}}
- {The floor is computed and the remainder (if any) is thrown away.
- (3)}
- \lineii{+\var{t1}}
- {Returns a \class{timedelta} object with the same value.
- (2)}
- \lineii{-\var{t1}}
- {equivalent to \class{timedelta}(-\var{t1.days}, -\var{t1.seconds},
- -\var{t1.microseconds}), and to \var{t1}* -1.
- (1)(4)}
- \lineii{abs(\var{t})}
- {equivalent to +\var{t} when \code{t.days >= 0}, and to
- -\var{t} when \code{t.days < 0}.
- (2)}
-\end{tableii}
-\noindent
-Notes:
-
-\begin{description}
-\item[(1)]
- This is exact, but may overflow.
-
-\item[(2)]
- This is exact, and cannot overflow.
-
-\item[(3)]
- Division by 0 raises \exception{ZeroDivisionError}.
-
-\item[(4)]
- -\var{timedelta.max} is not representable as a \class{timedelta} object.
-\end{description}
-
-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, \exception{TypeError} is
-raised unless the comparison is \code{==} or \code{!=}. The latter
-cases return \constant{False} or \constant{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
-\code{timedelta(0)}.
-
-
-\subsection{\class{date} Objects \label{datetime-date}}
-
-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
-\citetitle{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.
-
-\begin{classdesc}{date}{year, month, day}
- All arguments are required. Arguments may be ints or longs, in the
- following ranges:
-
- \begin{itemize}
- \item \code{MINYEAR <= \var{year} <= MAXYEAR}
- \item \code{1 <= \var{month} <= 12}
- \item \code{1 <= \var{day} <= number of days in the given month and year}
- \end{itemize}
-
- If an argument outside those ranges is given, \exception{ValueError}
- is raised.
-\end{classdesc}
-
-Other constructors, all class methods:
-
-\begin{methoddesc}{today}{}
- Return the current local date. This is equivalent to
- \code{date.fromtimestamp(time.time())}.
-\end{methoddesc}
-
-\begin{methoddesc}{fromtimestamp}{timestamp}
- Return the local date corresponding to the POSIX timestamp, such
- as is returned by \function{time.time()}. This may raise
- \exception{ValueError}, if the timestamp is out of the range of
- values supported by the platform C \cfunction{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
- \method{fromtimestamp()}.
-\end{methoddesc}
-
-\begin{methoddesc}{fromordinal}{ordinal}
- Return the date corresponding to the proleptic Gregorian ordinal,
- where January 1 of year 1 has ordinal 1. \exception{ValueError} is
- raised unless \code{1 <= \var{ordinal} <= date.max.toordinal()}.
- For any date \var{d}, \code{date.fromordinal(\var{d}.toordinal()) ==
- \var{d}}.
-\end{methoddesc}
-
-Class attributes:
-
-\begin{memberdesc}{min}
- The earliest representable date, \code{date(MINYEAR, 1, 1)}.
-\end{memberdesc}
-
-\begin{memberdesc}{max}
- The latest representable date, \code{date(MAXYEAR, 12, 31)}.
-\end{memberdesc}
-
-\begin{memberdesc}{resolution}
- The smallest possible difference between non-equal date
- objects, \code{timedelta(days=1)}.
-\end{memberdesc}
-
-Instance attributes (read-only):
-
-\begin{memberdesc}{year}
- Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive.
-\end{memberdesc}
-
-\begin{memberdesc}{month}
- Between 1 and 12 inclusive.
-\end{memberdesc}
-
-\begin{memberdesc}{day}
- Between 1 and the number of days in the given month of the given
- year.
-\end{memberdesc}
-
-Supported operations:
-
-\begin{tableii}{c|l}{code}{Operation}{Result}
- \lineii{\var{date2} = \var{date1} + \var{timedelta}}
- {\var{date2} is \code{\var{timedelta}.days} days removed from
- \var{date1}. (1)}
-
-
- \lineii{\var{date2} = \var{date1} - \var{timedelta}}
- {Computes \var{date2} such that \code{\var{date2} + \var{timedelta}
- == \var{date1}}. (2)}
-
- \lineii{\var{timedelta} = \var{date1} - \var{date2}}
- {(3)}
-
- \lineii{\var{date1} < \var{date2}}
- {\var{date1} is considered less than \var{date2} when \var{date1}
- precedes \var{date2} in time. (4)}
-
-\end{tableii}
-
-Notes:
-\begin{description}
-
-\item[(1)]
- \var{date2} is moved forward in time if \code{\var{timedelta}.days
- > 0}, or backward if \code{\var{timedelta}.days < 0}. Afterward
- \code{\var{date2} - \var{date1} == \var{timedelta}.days}.
- \code{\var{timedelta}.seconds} and
- \code{\var{timedelta}.microseconds} are ignored.
- \exception{OverflowError} is raised if \code{\var{date2}.year}
- would be smaller than \constant{MINYEAR} or larger than
- \constant{MAXYEAR}.
-
-\item[(2)]
- This isn't quite equivalent to date1 +
- (-timedelta), because -timedelta in isolation can overflow in cases
- where date1 - timedelta does not. \code{\var{timedelta}.seconds}
- and \code{\var{timedelta}.microseconds} are ignored.
-
-\item[(3)]
-This is exact, and cannot overflow. timedelta.seconds and
- timedelta.microseconds are 0, and date2 + timedelta == date1
- after.
-
-\item[(4)]
-In other words, \code{date1 < date2}
- if and only if \code{\var{date1}.toordinal() <
- \var{date2}.toordinal()}.
-In order to stop comparison from falling back to the default
-scheme of comparing object addresses, date comparison
-normally raises \exception{TypeError} if the other comparand
-isn't also a \class{date} object. However, \code{NotImplemented}
-is returned instead if the other comparand has a
-\method{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, \exception{TypeError} is
-raised unless the comparison is \code{==} or \code{!=}. The latter
-cases return \constant{False} or \constant{True}, respectively.
-
-\end{description}
-
-
-Dates can be used as dictionary keys. In Boolean contexts, all
-\class{date} objects are considered to be true.
-
-Instance methods:
-
-\begin{methoddesc}{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 \code{d == date(2002, 12, 31)}, then
- \code{d.replace(day=26) == date(2002, 12, 26)}.
-\end{methoddesc}
-
-\begin{methoddesc}{timetuple}{}
- Return a \class{time.struct_time} such as returned by
- \function{time.localtime()}. The hours, minutes and seconds are
- 0, and the DST flag is -1.
- \code{\var{d}.timetuple()} is equivalent to
- \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day,
- 0, 0, 0,
- \var{d}.weekday(),
- \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
- -1))}
-\end{methoddesc}
-
-\begin{methoddesc}{toordinal}{}
- Return the proleptic Gregorian ordinal of the date, where January 1
- of year 1 has ordinal 1. For any \class{date} object \var{d},
- \code{date.fromordinal(\var{d}.toordinal()) == \var{d}}.
-\end{methoddesc}
-
-\begin{methoddesc}{weekday}{}
- Return the day of the week as an integer, where Monday is 0 and
- Sunday is 6. For example, \code{date(2002, 12, 4).weekday() == 2}, a
- Wednesday.
- See also \method{isoweekday()}.
-\end{methoddesc}
-
-\begin{methoddesc}{isoweekday}{}
- Return the day of the week as an integer, where Monday is 1 and
- Sunday is 7. For example, \code{date(2002, 12, 4).isoweekday() == 3}, a
- Wednesday.
- See also \method{weekday()}, \method{isocalendar()}.
-\end{methoddesc}
-
-\begin{methoddesc}{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 \url{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
- \code{date(2003, 12, 29).isocalendar() == (2004, 1, 1)}
- and
- \code{date(2004, 1, 4).isocalendar() == (2004, 1, 7)}.
-\end{methoddesc}
-
-\begin{methoddesc}{isoformat}{}
- Return a string representing the date in ISO 8601 format,
- 'YYYY-MM-DD'. For example,
- \code{date(2002, 12, 4).isoformat() == '2002-12-04'}.
-\end{methoddesc}
-
-\begin{methoddesc}{__str__}{}
- For a date \var{d}, \code{str(\var{d})} is equivalent to
- \code{\var{d}.isoformat()}.
-\end{methoddesc}
-
-\begin{methoddesc}{ctime}{}
- Return a string representing the date, for example
- date(2002, 12, 4).ctime() == 'Wed Dec 4 00:00:00 2002'.
- \code{\var{d}.ctime()} is equivalent to
- \code{time.ctime(time.mktime(\var{d}.timetuple()))}
- on platforms where the native C \cfunction{ctime()} function
- (which \function{time.ctime()} invokes, but which
- \method{date.ctime()} does not invoke) conforms to the C standard.
-\end{methoddesc}
-
-\begin{methoddesc}{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} -- \method{strftime()} behavior.
-\end{methoddesc}
-
-
-\subsection{\class{datetime} Objects \label{datetime-datetime}}
-
-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:
-
-\begin{classdesc}{datetime}{year, month, day\optional{,
- hour\optional{, minute\optional{,
- second\optional{, microsecond\optional{,
- tzinfo}}}}}}
- The year, month and day arguments are required. \var{tzinfo} may
- be \code{None}, or an instance of a \class{tzinfo} subclass. The
- remaining arguments may be ints or longs, in the following ranges:
-
- \begin{itemize}
- \item \code{MINYEAR <= \var{year} <= MAXYEAR}
- \item \code{1 <= \var{month} <= 12}
- \item \code{1 <= \var{day} <= number of days in the given month and year}
- \item \code{0 <= \var{hour} < 24}
- \item \code{0 <= \var{minute} < 60}
- \item \code{0 <= \var{second} < 60}
- \item \code{0 <= \var{microsecond} < 1000000}
- \end{itemize}
-
- If an argument outside those ranges is given,
- \exception{ValueError} is raised.
-\end{classdesc}
-
-Other constructors, all class methods:
-
-\begin{methoddesc}{today}{}
- Return the current local datetime, with \member{tzinfo} \code{None}.
- This is equivalent to
- \code{datetime.fromtimestamp(time.time())}.
- See also \method{now()}, \method{fromtimestamp()}.
-\end{methoddesc}
-
-\begin{methoddesc}{now}{\optional{tz}}
- Return the current local date and time. If optional argument
- \var{tz} is \code{None} or not specified, this is like
- \method{today()}, but, if possible, supplies more precision than can
- be gotten from going through a \function{time.time()} timestamp (for
- example, this may be possible on platforms supplying the C
- \cfunction{gettimeofday()} function).
-
- Else \var{tz} must be an instance of a class \class{tzinfo} subclass,
- and the current date and time are converted to \var{tz}'s time
- zone. In this case the result is equivalent to
- \code{\var{tz}.fromutc(datetime.utcnow().replace(tzinfo=\var{tz}))}.
- See also \method{today()}, \method{utcnow()}.
-\end{methoddesc}
-
-\begin{methoddesc}{utcnow}{}
- Return the current UTC date and time, with \member{tzinfo} \code{None}.
- This is like \method{now()}, but returns the current UTC date and time,
- as a naive \class{datetime} object.
- See also \method{now()}.
-\end{methoddesc}
-
-\begin{methoddesc}{fromtimestamp}{timestamp\optional{, tz}}
- Return the local date and time corresponding to the \POSIX{}
- timestamp, such as is returned by \function{time.time()}.
- If optional argument \var{tz} is \code{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 \var{tz} must be an instance of a class \class{tzinfo} subclass,
- and the timestamp is converted to \var{tz}'s time zone. In this case
- the result is equivalent to
- \code{\var{tz}.fromutc(datetime.utcfromtimestamp(\var{timestamp}).replace(tzinfo=\var{tz}))}.
-
- \method{fromtimestamp()} may raise \exception{ValueError}, if the
- timestamp is out of the range of values supported by the platform C
- \cfunction{localtime()} or \cfunction{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
- \method{fromtimestamp()}, and then it's possible to have two timestamps
- differing by a second that yield identical \class{datetime} objects.
- See also \method{utcfromtimestamp()}.
-\end{methoddesc}
-
-\begin{methoddesc}{utcfromtimestamp}{timestamp}
- Return the UTC \class{datetime} corresponding to the \POSIX{}
- timestamp, with \member{tzinfo} \code{None}.
- This may raise \exception{ValueError}, if the
- timestamp is out of the range of values supported by the platform
- C \cfunction{gmtime()} function. It's common for this to be
- restricted to years in 1970 through 2038.
- See also \method{fromtimestamp()}.
-\end{methoddesc}
-
-\begin{methoddesc}{fromordinal}{ordinal}
- Return the \class{datetime} corresponding to the proleptic
- Gregorian ordinal, where January 1 of year 1 has ordinal 1.
- \exception{ValueError} is raised unless \code{1 <= ordinal <=
- datetime.max.toordinal()}. The hour, minute, second and
- microsecond of the result are all 0,
- and \member{tzinfo} is \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}{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 \member{tzinfo} members are equal to the given \class{time} object's.
- For any \class{datetime} object \var{d}, \code{\var{d} ==
- datetime.combine(\var{d}.date(), \var{d}.timetz())}. If date is a
- \class{datetime} object, its time and \member{tzinfo} members are
- ignored.
- \end{methoddesc}
-
-\begin{methoddesc}{strptime}{date_string, format}
- Return a \class{datetime} corresponding to \var{date_string}, parsed
- according to \var{format}. This is equivalent to
- \code{datetime(*(time.strptime(date_string,
- format)[0:6]))}. \exception{ValueError} is raised if the date_string and
- format can't be parsed by \function{time.strptime()} or if it returns a
- value which isn't a time tuple.
-
- \versionadded{2.5}
-\end{methoddesc}
-
-Class attributes:
-
-\begin{memberdesc}{min}
- The earliest representable \class{datetime},
- \code{datetime(MINYEAR, 1, 1, tzinfo=None)}.
-\end{memberdesc}
-
-\begin{memberdesc}{max}
- The latest representable \class{datetime},
- \code{datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)}.
-\end{memberdesc}
-
-\begin{memberdesc}{resolution}
- The smallest possible difference between non-equal \class{datetime}
- objects, \code{timedelta(microseconds=1)}.
-\end{memberdesc}
-
-Instance attributes (read-only):
-
-\begin{memberdesc}{year}
- Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive.
-\end{memberdesc}
-
-\begin{memberdesc}{month}
- Between 1 and 12 inclusive.
-\end{memberdesc}
-
-\begin{memberdesc}{day}
- Between 1 and the number of days in the given month of the given
- year.
-\end{memberdesc}
-
-\begin{memberdesc}{hour}
- In \code{range(24)}.
-\end{memberdesc}
-
-\begin{memberdesc}{minute}
- In \code{range(60)}.
-\end{memberdesc}
-
-\begin{memberdesc}{second}
- In \code{range(60)}.
-\end{memberdesc}
-
-\begin{memberdesc}{microsecond}
- In \code{range(1000000)}.
-\end{memberdesc}
-
-\begin{memberdesc}{tzinfo}
- The object passed as the \var{tzinfo} argument to the
- \class{datetime} constructor, or \code{None} if none was passed.
-\end{memberdesc}
-
-Supported operations:
-
-\begin{tableii}{c|l}{code}{Operation}{Result}
- \lineii{\var{datetime2} = \var{datetime1} + \var{timedelta}}{(1)}
-
- \lineii{\var{datetime2} = \var{datetime1} - \var{timedelta}}{(2)}
-
- \lineii{\var{timedelta} = \var{datetime1} - \var{datetime2}}{(3)}
-
- \lineii{\var{datetime1} < \var{datetime2}}
- {Compares \class{datetime} to \class{datetime}.
- (4)}
-
-\end{tableii}
-
-\begin{description}
-
-\item[(1)]
-
- datetime2 is a duration of timedelta removed from datetime1, moving
- forward in time if \code{\var{timedelta}.days} > 0, or backward if
- \code{\var{timedelta}.days} < 0. The result has the same \member{tzinfo} member
- as the input datetime, and datetime2 - datetime1 == timedelta after.
- \exception{OverflowError} is raised if datetime2.year would be
- smaller than \constant{MINYEAR} or larger than \constant{MAXYEAR}.
- Note that no time zone adjustments are done even if the input is an
- aware object.
-
-\item[(2)]
- Computes the datetime2 such that datetime2 + timedelta == datetime1.
- As for addition, the result has the same \member{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.
-
-\item[(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, \exception{TypeError} is raised.
-
- If both are naive, or both are aware and have the same \member{tzinfo}
- member, the \member{tzinfo} members are ignored, and the result is
- a \class{timedelta} object \var{t} such that
- \code{\var{datetime2} + \var{t} == \var{datetime1}}. No time zone
- adjustments are done in this case.
-
- If both are aware and have different \member{tzinfo} members,
- \code{a-b} acts as if \var{a} and \var{b} were first converted to
- naive UTC datetimes first. The result is
- \code{(\var{a}.replace(tzinfo=None) - \var{a}.utcoffset()) -
- (\var{b}.replace(tzinfo=None) - \var{b}.utcoffset())}
- except that the implementation never overflows.
-
-\item[(4)]
-
-\var{datetime1} is considered less than \var{datetime2}
-when \var{datetime1} precedes \var{datetime2} in time.
-
-If one comparand is naive and
-the other is aware, \exception{TypeError} is raised. If both
- comparands are aware, and have the same \member{tzinfo} member,
- the common \member{tzinfo} member is ignored and the base datetimes
- are compared. If both comparands are aware and have different
- \member{tzinfo} members, the comparands are first adjusted by
- subtracting their UTC offsets (obtained from \code{self.utcoffset()}).
- \note{In order to stop comparison from falling back to the default
- scheme of comparing object addresses, datetime comparison
- normally raises \exception{TypeError} if the other comparand
- isn't also a \class{datetime} object. However,
- \code{NotImplemented} is returned instead if the other comparand
- has a \method{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, \exception{TypeError}
- is raised unless the comparison is \code{==} or \code{!=}. The
- latter cases return \constant{False} or \constant{True},
- respectively.}
-
-\end{description}
-
-\class{datetime} objects can be used as dictionary keys. In Boolean
-contexts, all \class{datetime} objects are considered to be true.
-
-
-Instance methods:
-
-\begin{methoddesc}{date}{}
- Return \class{date} object with same year, month and day.
-\end{methoddesc}
-
-\begin{methoddesc}{time}{}
- Return \class{time} object with same hour, minute, second and microsecond.
- \member{tzinfo} is \code{None}. See also method \method{timetz()}.
-\end{methoddesc}
-
-\begin{methoddesc}{timetz}{}
- Return \class{time} object with same hour, minute, second, microsecond,
- and tzinfo members. See also method \method{time()}.
-\end{methoddesc}
-
-\begin{methoddesc}{replace}{\optional{year\optional{, month\optional{,
- day\optional{, hour\optional{, minute\optional{,
- second\optional{, microsecond\optional{,
- tzinfo}}}}}}}}}
- Return a datetime with the same members, except for those members given
- new values by whichever keyword arguments are specified. Note that
- \code{tzinfo=None} can be specified to create a naive datetime from
- an aware datetime with no conversion of date and time members.
-\end{methoddesc}
-
-\begin{methoddesc}{astimezone}{tz}
- Return a \class{datetime} object with new \member{tzinfo} member
- \var{tz}, adjusting the date and time members so the result is the
- same UTC time as \var{self}, but in \var{tz}'s local time.
-
- \var{tz} must be an instance of a \class{tzinfo} subclass, and its
- \method{utcoffset()} and \method{dst()} methods must not return
- \code{None}. \var{self} must be aware (\code{\var{self}.tzinfo} must
- not be \code{None}, and \code{\var{self}.utcoffset()} must not return
- \code{None}).
-
- If \code{\var{self}.tzinfo} is \var{tz},
- \code{\var{self}.astimezone(\var{tz})} is equal to \var{self}: no
- adjustment of date or time members is performed.
- Else the result is local time in time zone \var{tz}, representing the
- same UTC time as \var{self}: after \code{\var{astz} =
- \var{dt}.astimezone(\var{tz})},
- \code{\var{astz} - \var{astz}.utcoffset()} will usually have the same
- date and time members as \code{\var{dt} - \var{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 \var{tz} models both standard and daylight time).
-
- If you merely want to attach a time zone object \var{tz} to a
- datetime \var{dt} without adjustment of date and time members,
- use \code{\var{dt}.replace(tzinfo=\var{tz})}. If
- you merely want to remove the time zone object from an aware datetime
- \var{dt} without conversion of date and time members, use
- \code{\var{dt}.replace(tzinfo=None)}.
-
- Note that the default \method{tzinfo.fromutc()} method can be overridden
- in a \class{tzinfo} subclass to affect the result returned by
- \method{astimezone()}. Ignoring error cases, \method{astimezone()}
- acts like:
-
- \begin{verbatim}
- 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)
- \end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}{utcoffset}{}
- If \member{tzinfo} is \code{None}, returns \code{None}, else
- returns \code{\var{self}.tzinfo.utcoffset(\var{self})}, and
- raises an exception if the latter doesn't return \code{None}, or
- a \class{timedelta} object representing a whole number of minutes
- with magnitude less than one day.
-\end{methoddesc}
-
-\begin{methoddesc}{dst}{}
- If \member{tzinfo} is \code{None}, returns \code{None}, else
- returns \code{\var{self}.tzinfo.dst(\var{self})}, and
- raises an exception if the latter doesn't return \code{None}, or
- a \class{timedelta} object representing a whole number of minutes
- with magnitude less than one day.
-\end{methoddesc}
-
-\begin{methoddesc}{tzname}{}
- If \member{tzinfo} is \code{None}, returns \code{None}, else
- returns \code{\var{self}.tzinfo.tzname(\var{self})},
- raises an exception if the latter doesn't return \code{None} or
- a string object,
-\end{methoddesc}
-
-\begin{methoddesc}{timetuple}{}
- Return a \class{time.struct_time} such as returned by
- \function{time.localtime()}.
- \code{\var{d}.timetuple()} is equivalent to
- \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day,
- \var{d}.hour, \var{d}.minute, \var{d}.second,
- \var{d}.weekday(),
- \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
- dst))}
- The \member{tm_isdst} flag of the result is set according to
- the \method{dst()} method: \member{tzinfo} is \code{None} or
- \method{dst()} returns \code{None},
- \member{tm_isdst} is set to \code{-1}; else if \method{dst()} returns
- a non-zero value, \member{tm_isdst} is set to \code{1};
- else \code{tm_isdst} is set to \code{0}.
-\end{methoddesc}
-
-\begin{methoddesc}{utctimetuple}{}
- If \class{datetime} instance \var{d} is naive, this is the same as
- \code{\var{d}.timetuple()} except that \member{tm_isdst} is forced to 0
- regardless of what \code{d.dst()} returns. DST is never in effect
- for a UTC time.
-
- If \var{d} is aware, \var{d} is normalized to UTC time, by subtracting
- \code{\var{d}.utcoffset()}, and a \class{time.struct_time} for the
- normalized time is returned. \member{tm_isdst} is forced to 0.
- Note that the result's \member{tm_year} member may be
- \constant{MINYEAR}-1 or \constant{MAXYEAR}+1, if \var{d}.year was
- \code{MINYEAR} or \code{MAXYEAR} and UTC adjustment spills over a
- year boundary.
-\end{methoddesc}
-
-\begin{methoddesc}{toordinal}{}
- Return the proleptic Gregorian ordinal of the date. The same as
- \code{self.date().toordinal()}.
-\end{methoddesc}
-
-\begin{methoddesc}{weekday}{}
- Return the day of the week as an integer, where Monday is 0 and
- Sunday is 6. The same as \code{self.date().weekday()}.
- See also \method{isoweekday()}.
-\end{methoddesc}
-
-\begin{methoddesc}{isoweekday}{}
- Return the day of the week as an integer, where Monday is 1 and
- Sunday is 7. The same as \code{self.date().isoweekday()}.
- See also \method{weekday()}, \method{isocalendar()}.
-\end{methoddesc}
-
-\begin{methoddesc}{isocalendar}{}
- Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The
- same as \code{self.date().isocalendar()}.
-\end{methoddesc}
-
-\begin{methoddesc}{isoformat}{\optional{sep}}
- Return a string representing the date and time in ISO 8601 format,
- YYYY-MM-DDTHH:MM:SS.mmmmmm
- or, if \member{microsecond} is 0,
- YYYY-MM-DDTHH:MM:SS
-
- If \method{utcoffset()} does not return \code{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 \member{microsecond} is 0
- YYYY-MM-DDTHH:MM:SS+HH:MM
-
- The optional argument \var{sep} (default \code{'T'}) is a
- one-character separator, placed between the date and time portions
- of the result. For example,
-
-\begin{verbatim}
->>> 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'
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}{__str__}{}
- For a \class{datetime} instance \var{d}, \code{str(\var{d})} is
- equivalent to \code{\var{d}.isoformat(' ')}.
-\end{methoddesc}
-
-\begin{methoddesc}{ctime}{}
- Return a string representing the date and time, for example
- \code{datetime(2002, 12, 4, 20, 30, 40).ctime() ==
- 'Wed Dec 4 20:30:40 2002'}.
- \code{d.ctime()} is equivalent to
- \code{time.ctime(time.mktime(d.timetuple()))} on platforms where
- the native C \cfunction{ctime()} function (which
- \function{time.ctime()} invokes, but which
- \method{datetime.ctime()} does not invoke) conforms to the C
- standard.
-\end{methoddesc}
-
-\begin{methoddesc}{strftime}{format}
- Return a string representing the date and time, controlled by an
- explicit format string. See section~\ref{strftime-behavior} --
- \method{strftime()} behavior.
-\end{methoddesc}
-
-
-\subsection{\class{time} Objects \label{datetime-time}}
-
-A time object represents a (local) time of day, independent of any
-particular day, and subject to adjustment via a \class{tzinfo} object.
-
-\begin{classdesc}{time}{hour\optional{, minute\optional{, second\optional{,
- microsecond\optional{, tzinfo}}}}}
- All arguments are optional. \var{tzinfo} may be \code{None}, or
- an instance of a \class{tzinfo} subclass. The remaining arguments
- may be ints or longs, in the following ranges:
-
- \begin{itemize}
- \item \code{0 <= \var{hour} < 24}
- \item \code{0 <= \var{minute} < 60}
- \item \code{0 <= \var{second} < 60}
- \item \code{0 <= \var{microsecond} < 1000000}.
- \end{itemize}
-
- If an argument outside those ranges is given,
- \exception{ValueError} is raised. All default to \code{0} except
- \var{tzinfo}, which defaults to \constant{None}.
-\end{classdesc}
-
-Class attributes:
-
-\begin{memberdesc}{min}
- The earliest representable \class{time}, \code{time(0, 0, 0, 0)}.
-\end{memberdesc}
-
-\begin{memberdesc}{max}
- The latest representable \class{time}, \code{time(23, 59, 59, 999999)}.
-\end{memberdesc}
-
-\begin{memberdesc}{resolution}
- The smallest possible difference between non-equal \class{time}
- objects, \code{timedelta(microseconds=1)}, although note that
- arithmetic on \class{time} objects is not supported.
-\end{memberdesc}
-
-Instance attributes (read-only):
-
-\begin{memberdesc}{hour}
- In \code{range(24)}.
-\end{memberdesc}
-
-\begin{memberdesc}{minute}
- In \code{range(60)}.
-\end{memberdesc}
-
-\begin{memberdesc}{second}
- In \code{range(60)}.
-\end{memberdesc}
-
-\begin{memberdesc}{microsecond}
- In \code{range(1000000)}.
-\end{memberdesc}
-
-\begin{memberdesc}{tzinfo}
- The object passed as the tzinfo argument to the \class{time}
- constructor, or \code{None} if none was passed.
-\end{memberdesc}
-
-Supported operations:
-
-\begin{itemize}
- \item
- comparison of \class{time} to \class{time},
- where \var{a} is considered less than \var{b} when \var{a} precedes
- \var{b} in time. If one comparand is naive and the other is aware,
- \exception{TypeError} is raised. If both comparands are aware, and
- have the same \member{tzinfo} member, the common \member{tzinfo}
- member is ignored and the base times are compared. If both
- comparands are aware and have different \member{tzinfo} members,
- the comparands are first adjusted by subtracting their UTC offsets
- (obtained from \code{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, \exception{TypeError} is
- raised unless the comparison is \code{==} or \code{!=}. The latter
- cases return \constant{False} or \constant{True}, respectively.
-
- \item
- hash, use as dict key
-
- \item
- efficient pickling
-
- \item
- in Boolean contexts, a \class{time} object is considered to be
- true if and only if, after converting it to minutes and
- subtracting \method{utcoffset()} (or \code{0} if that's
- \code{None}), the result is non-zero.
-\end{itemize}
-
-Instance methods:
-
-\begin{methoddesc}{replace}{\optional{hour\optional{, minute\optional{,
- second\optional{, microsecond\optional{,
- tzinfo}}}}}}
- Return a \class{time} with the same value, except for those members given
- new values by whichever keyword arguments are specified. Note that
- \code{tzinfo=None} can be specified to create a naive \class{time} from
- an aware \class{time}, without conversion of the time members.
-\end{methoddesc}
-
-\begin{methoddesc}{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 \method{utcoffset()} does not return \code{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
-\end{methoddesc}
-
-\begin{methoddesc}{__str__}{}
- For a time \var{t}, \code{str(\var{t})} is equivalent to
- \code{\var{t}.isoformat()}.
-\end{methoddesc}
-
-\begin{methoddesc}{strftime}{format}
- Return a string representing the time, controlled by an explicit
- format string. See section~\ref{strftime-behavior} --
- \method{strftime()} behavior.
-\end{methoddesc}
-
-\begin{methoddesc}{utcoffset}{}
- If \member{tzinfo} is \code{None}, returns \code{None}, else
- returns \code{\var{self}.tzinfo.utcoffset(None)}, and
- raises an exception if the latter doesn't return \code{None} or
- a \class{timedelta} object representing a whole number of minutes
- with magnitude less than one day.
-\end{methoddesc}
-
-\begin{methoddesc}{dst}{}
- If \member{tzinfo} is \code{None}, returns \code{None}, else
- returns \code{\var{self}.tzinfo.dst(None)}, and
- raises an exception if the latter doesn't return \code{None}, or
- a \class{timedelta} object representing a whole number of minutes
- with magnitude less than one day.
-\end{methoddesc}
-
-\begin{methoddesc}{tzname}{}
- If \member{tzinfo} is \code{None}, returns \code{None}, else
- returns \code{\var{self}.tzinfo.tzname(None)}, or
- raises an exception if the latter doesn't return \code{None} or
- a string object.
-\end{methoddesc}
-
-
-\subsection{\class{tzinfo} Objects \label{datetime-tzinfo}}
-
-\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 \module{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
-\method{__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 \module{datetime} objects. If in doubt, simply
-implement all of them.
-
-\begin{methoddesc}[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,
- \method{utcoffset()} should return their sum. If the UTC offset
- isn't known, return \code{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
- \method{utcoffset()} will probably look like one of these two:
-
-\begin{verbatim}
- return CONSTANT # fixed-offset class
- return CONSTANT + self.dst(dt) # daylight-aware class
-\end{verbatim}
-
- If \method{utcoffset()} does not return \code{None},
- \method{dst()} should not return \code{None} either.
-
- The default implementation of \method{utcoffset()} raises
- \exception{NotImplementedError}.
-\end{methoddesc}
-
-\begin{methoddesc}[tzinfo]{dst}{self, dt}
- Return the daylight saving time (DST) adjustment, in minutes east of
- UTC, or \code{None} if DST information isn't known. Return
- \code{timedelta(0)} if DST is not in effect.
- If DST is in effect, return the offset as a
- \class{timedelta} object (see \method{utcoffset()} for details).
- Note that DST offset, if applicable, has
- already been added to the UTC offset returned by
- \method{utcoffset()}, so there's no need to consult \method{dst()}
- unless you're interested in obtaining DST info separately. For
- example, \method{datetime.timetuple()} calls its \member{tzinfo}
- member's \method{dst()} method to determine how the
- \member{tm_isdst} flag should be set, and
- \method{tzinfo.fromutc()} calls \method{dst()} to account for
- DST changes when crossing time zones.
-
- An instance \var{tz} of a \class{tzinfo} subclass that models both
- standard and daylight times must be consistent in this sense:
-
- \code{\var{tz}.utcoffset(\var{dt}) - \var{tz}.dst(\var{dt})}
-
- must return the same result for every \class{datetime} \var{dt}
- with \code{\var{dt}.tzinfo == \var{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 \method{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 \method{tzinfo.fromutc()} to work correctly with \method{astimezone()}
- regardless.
-
- Most implementations of \method{dst()} will probably look like one
- of these two:
-
-\begin{verbatim}
- def dst(self):
- # a fixed-offset class: doesn't account for DST
- return timedelta(0)
-\end{verbatim}
-
- or
-
-\begin{verbatim}
- 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)
-\end{verbatim}
-
- The default implementation of \method{dst()} raises
- \exception{NotImplementedError}.
-\end{methoddesc}
-
-\begin{methoddesc}[tzinfo]{tzname}{self, dt}
- Return the time zone name corresponding to the \class{datetime}
- object \var{dt}, as a string.
- Nothing about string names is defined by the
- \module{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
- \code{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 \var{dt} passed, especially if the \class{tzinfo} class is
- accounting for daylight time.
-
- The default implementation of \method{tzname()} raises
- \exception{NotImplementedError}.
-\end{methoddesc}
-
-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
-\code{None} as the argument. A \class{tzinfo} subclass's methods should
-therefore be prepared to accept a \var{dt} argument of \code{None}, or of
-class \class{datetime}.
-
-When \code{None} is passed, it's up to the class designer to decide the
-best response. For example, returning \code{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 \code{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, \code{dt.tzinfo} is the same object as
-\var{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 \var{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:
-
-\begin{methoddesc}[tzinfo]{fromutc}{self, dt}
- This is called from the default \class{datetime.astimezone()}
- implementation. When called from that, \code{\var{dt}.tzinfo} is
- \var{self}, and \var{dt}'s date and time members are to be viewed as
- expressing a UTC time. The purpose of \method{fromutc()} is to
- adjust the date and time members, returning an equivalent datetime in
- \var{self}'s local time.
-
- Most \class{tzinfo} subclasses should be able to inherit the default
- \method{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
- \method{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 \method{astimezone()} and
- \method{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 \method{fromutc()}
- implementation acts like:
-
- \begin{verbatim}
- 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
- \end{verbatim}
-\end{methoddesc}
-
-Example \class{tzinfo} classes:
-
-\verbatiminput{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:
-
-\begin{verbatim}
- 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
-\end{verbatim}
-
-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 \code{astimezone(Eastern)} won't deliver a result with
-\code{hour == 2} on the
-day DST begins. In order for \method{astimezone()} to make this
-guarantee, the \method{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. \method{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
-\method{astimezone()} to make this guarantee, the \method{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)).
-
-
-\subsection{\method{strftime()} Behavior\label{strftime-behavior}}
-
-\class{date}, \class{datetime}, and \class{time}
-objects all support a \code{strftime(\var{format})}
-method, to create a string representing the time under the control of
-an explicit format string. Broadly speaking,
-\code{d.strftime(fmt)}
-acts like the \refmodule{time} module's
-\code{time.strftime(fmt, d.timetuple())}
-although not all objects support a \method{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, \code{1900} is substituted for the
-year, and \code{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, \code{0} is substituted for them.
-
-For a naive object, the \code{\%z} and \code{\%Z} format codes are
-replaced by empty strings.
-
-For an aware object:
-
-\begin{itemize}
- \item[\code{\%z}]
- \method{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
- \method{utcoffset()} returns \code{timedelta(hours=-3, minutes=-30)},
- \code{\%z} is replaced with the string \code{'-0330'}.
-
- \item[\code{\%Z}]
- If \method{tzname()} returns \code{None}, \code{\%Z} is replaced
- by an empty string. Otherwise \code{\%Z} is replaced by the returned
- value, which must be a string.
-\end{itemize}
-
-The full set of format codes supported varies across platforms,
-because Python calls the platform C library's \function{strftime()}
-function, and platform variations are common. The documentation for
-Python's \refmodule{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 \method{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}
-%
diff --git a/Doc/lib/libdbhash.tex b/Doc/lib/libdbhash.tex
deleted file mode 100644
index 5852b73..0000000
--- a/Doc/lib/libdbhash.tex
+++ /dev/null
@@ -1,88 +0,0 @@
-\section{\module{dbhash} ---
- DBM-style interface to the BSD database library}
-
-\declaremodule{standard}{dbhash}
-\modulesynopsis{DBM-style interface to the BSD database library.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-The \module{dbhash} module provides a function to open databases using
-the BSD \code{db} library. This module mirrors the interface of the
-other Python database modules that provide access to DBM-style
-databases. The \refmodule{bsddb}\refbimodindex{bsddb} module is required
-to use \module{dbhash}.
-
-This module provides an exception and a function:
-
-
-\begin{excdesc}{error}
- Exception raised on database errors other than
- \exception{KeyError}. It is a synonym for \exception{bsddb.error}.
-\end{excdesc}
-
-\begin{funcdesc}{open}{path\optional{, flag\optional{, mode}}}
- Open a \code{db} database and return the database object. The
- \var{path} argument is the name of the database file.
-
- The \var{flag} argument can be
- \code{'r'} (the default), \code{'w'},
- \code{'c'} (which creates the database if it doesn't exist), or
- \code{'n'} (which always creates a new empty database).
- For platforms on which the BSD \code{db} library supports locking,
- an \character{l} can be appended to indicate that locking should be
- used.
-
- The optional \var{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.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
- \seemodule{bsddb}{Lower-level interface to the BSD \code{db} library.}
- \seemodule{whichdb}{Utility module used to determine the type of an
- existing database.}
-\end{seealso}
-
-
-\subsection{Database Objects \label{dbhash-objects}}
-
-The database objects returned by \function{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.
-
-\begin{methoddesc}[dbhash]{first}{}
- It's possible to loop over every key/value pair in the database using
- this method and the \method{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.
-\end{methoddesc}
-
-\begin{methoddesc}[dbhash]{last}{}
- Return the last key/value pair in a database traversal. This may be used to
- begin a reverse-order traversal; see \method{previous()}.
-\end{methoddesc}
-
-\begin{methoddesc}[dbhash]{next}{}
- Returns the key next key/value pair in a database traversal. The
- following code prints every key in the database \code{db}, without
- having to create a list in memory that contains them all:
-
-\begin{verbatim}
-print db.first()
-for i in range(1, len(db)):
- print db.next()
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[dbhash]{previous}{}
- Returns the previous key/value pair in a forward-traversal of the database.
- In conjunction with \method{last()}, this may be used to implement
- a reverse-order traversal.
-\end{methoddesc}
-
-\begin{methoddesc}[dbhash]{sync}{}
- This method forces any unwritten data to be written to the disk.
-\end{methoddesc}
diff --git a/Doc/lib/libdbm.tex b/Doc/lib/libdbm.tex
deleted file mode 100644
index e08af99..0000000
--- a/Doc/lib/libdbm.tex
+++ /dev/null
@@ -1,61 +0,0 @@
-\section{\module{dbm} ---
- Simple ``database'' interface}
-
-\declaremodule{builtin}{dbm}
- \platform{Unix}
-\modulesynopsis{The standard ``database'' interface, based on ndbm.}
-
-
-The \module{dbm} module provides an interface to the \UNIX{}
-(\code{n})\code{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
-\method{items()} and \method{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:
-
-\begin{excdesc}{error}
-Raised on dbm-specific errors, such as I/O errors.
-\exception{KeyError} is raised for general mapping errors like
-specifying an incorrect key.
-\end{excdesc}
-
-\begin{datadesc}{library}
-Name of the \code{ndbm} implementation library used.
-\end{datadesc}
-
-\begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}}
-Open a dbm database and return a dbm object. The \var{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 \var{flag} argument must be one of these values:
-
-\begin{tableii}{c|l}{code}{Value}{Meaning}
- \lineii{'r'}{Open existing database for reading only (default)}
- \lineii{'w'}{Open existing database for reading and writing}
- \lineii{'c'}{Open database for reading and writing, creating it if
- it doesn't exist}
- \lineii{'n'}{Always create a new, empty database, open for reading
- and writing}
-\end{tableii}
-
-The optional \var{mode} argument is the \UNIX{} mode of the file, used
-only when the database has to be created. It defaults to octal
-\code{0666}.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
- \seemodule{gdbm}{Similar interface to the GNU GDBM library.}
- \seemodule{whichdb}{Utility module used to determine the type of an
- existing database.}
-\end{seealso}
diff --git a/Doc/lib/libdecimal.tex b/Doc/lib/libdecimal.tex
deleted file mode 100644
index 8c665da..0000000
--- a/Doc/lib/libdecimal.tex
+++ /dev/null
@@ -1,1313 +0,0 @@
-\section{\module{decimal} ---
- Decimal floating point arithmetic}
-
-\declaremodule{standard}{decimal}
-\modulesynopsis{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 \module{decimal} module provides support for decimal floating point
-arithmetic. It offers several advantages over the \class{float()} datatype:
-
-\begin{itemize}
-
-\item Decimal numbers can be represented exactly. In contrast, numbers like
-\constant{1.1} do not have an exact representation in binary floating point.
-End users typically would not expect \constant{1.1} to display as
-\constant{1.1000000000000001} as it does with binary floating point.
-
-\item The exactness carries over into arithmetic. In decimal floating point,
-\samp{0.1 + 0.1 + 0.1 - 0.3} is exactly equal to zero. In binary floating
-point, result is \constant{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.
-
-\item The decimal module incorporates a notion of significant places so that
-\samp{1.30 + 1.20} is \constant{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, \samp{1.3 * 1.2} gives \constant{1.56} while
-\samp{1.30 * 1.20} gives \constant{1.5600}.
-
-\item 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:
-
-\begin{verbatim}
->>> getcontext().prec = 6
->>> Decimal(1) / Decimal(7)
-Decimal("0.142857")
->>> getcontext().prec = 28
->>> Decimal(1) / Decimal(7)
-Decimal("0.1428571428571428571428571429")
-\end{verbatim}
-
-\item 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.
-
-\end{itemize}
-
-
-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
-\constant{Infinity}, \constant{-Infinity}, and \constant{NaN}. The standard
-also differentiates \constant{-0} from \constant{+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 \constant{ROUND_CEILING},
-\constant{ROUND_DOWN}, \constant{ROUND_FLOOR}, \constant{ROUND_HALF_DOWN},
-\constant{ROUND_HALF_EVEN}, \constant{ROUND_HALF_UP}, and \constant{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: \constant{Clamped}, \constant{InvalidOperation},
-\constant{DivisionByZero}, \constant{Inexact}, \constant{Rounded},
-\constant{Subnormal}, \constant{Overflow}, and \constant{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.
-
-
-\begin{seealso}
- \seetext{IBM's General Decimal Arithmetic Specification,
- \citetitle[http://www2.hursley.ibm.com/decimal/decarith.html]
- {The General Decimal Arithmetic Specification}.}
-
- \seetext{IEEE standard 854-1987,
- \citetitle[http://www.cs.berkeley.edu/\textasciitilde ejr/projects/754/private/drafts/854-1987/dir.html]
- {Unofficial IEEE 854 Text}.}
-\end{seealso}
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Quick-start Tutorial \label{decimal-tutorial}}
-
-The usual start to using decimals is importing the module, viewing the current
-context with \function{getcontext()} and, if necessary, setting new values
-for precision, rounding, or enabled traps:
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
-
-
-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
-\constant{NaN} which stands for ``Not a number'', positive and negative
-\constant{Infinity}, and \constant{-0}.
-
-\begin{verbatim}
->>> 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")
-\end{verbatim}
-
-
-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.
-
-\begin{verbatim}
->>> 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")
-\end{verbatim}
-
-
-Decimals interact well with much of the rest of Python. Here is a small
-decimal floating point flying circus:
-
-\begin{verbatim}
->>> 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")
-\end{verbatim}
-
-The \method{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:
-
-\begin{verbatim}
->>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
-Decimal("7.32")
->>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
-Decimal("8")
-\end{verbatim}
-
-As shown above, the \function{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
-\function{setcontext()} function.
-
-In accordance with the standard, the \module{Decimal} module provides two
-ready to use standard contexts, \constant{BasicContext} and
-\constant{ExtendedContext}. The former is especially useful for debugging
-because many of the traps are enabled:
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
-
-
-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 \method{clear_flags()} method.
-
-\begin{verbatim}
->>> 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=[])
-\end{verbatim}
-
-The \var{flags} entry shows that the rational approximation to \constant{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 \member{traps}
-field of a context:
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
-
-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.
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Decimal objects \label{decimal-decimal}}
-
-\begin{classdesc}{Decimal}{\optional{value \optional{, context}}}
- Constructs a new \class{Decimal} object based from \var{value}.
-
- \var{value} can be an integer, string, tuple, or another \class{Decimal}
- object. If no \var{value} is given, returns \code{Decimal("0")}. If
- \var{value} is a string, it should conform to the decimal numeric string
- syntax:
-
- \begin{verbatim}
- 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
- \end{verbatim}
-
- If \var{value} is a \class{tuple}, it should have three components,
- a sign (\constant{0} for positive or \constant{1} for negative),
- a \class{tuple} of digits, and an integer exponent. For example,
- \samp{Decimal((0, (1, 4, 1, 4), -3))} returns \code{Decimal("1.414")}.
-
- The \var{context} precision does not affect how many digits are stored.
- That is determined exclusively by the number of digits in \var{value}. For
- example, \samp{Decimal("3.00000")} records all five zeroes even if the
- context precision is only three.
-
- The purpose of the \var{context} argument is determining what to do if
- \var{value} is a malformed string. If the context traps
- \constant{InvalidOperation}, an exception is raised; otherwise, the
- constructor returns a new Decimal with the value of \constant{NaN}.
-
- Once constructed, \class{Decimal} objects are immutable.
-\end{classdesc}
-
-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:
-
-\begin{methoddesc}{adjusted}{}
- Return the adjusted exponent after shifting out the coefficient's rightmost
- digits until only the lead digit remains: \code{Decimal("321e+5").adjusted()}
- returns seven. Used for determining the position of the most significant
- digit with respect to the decimal point.
-\end{methoddesc}
-
-\begin{methoddesc}{as_tuple}{}
- Returns a tuple representation of the number:
- \samp{(sign, digittuple, exponent)}.
-\end{methoddesc}
-
-\begin{methoddesc}{compare}{other\optional{, context}}
- Compares like \method{__cmp__()} but returns a decimal instance:
- \begin{verbatim}
- a or b is a NaN ==> Decimal("NaN")
- a < b ==> Decimal("-1")
- a == b ==> Decimal("0")
- a > b ==> Decimal("1")
- \end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}{max}{other\optional{, context}}
- Like \samp{max(self, other)} except that the context rounding rule
- is applied before returning and that \constant{NaN} values are
- either signalled or ignored (depending on the context and whether
- they are signaling or quiet).
-\end{methoddesc}
-
-\begin{methoddesc}{min}{other\optional{, context}}
- Like \samp{min(self, other)} except that the context rounding rule
- is applied before returning and that \constant{NaN} values are
- either signalled or ignored (depending on the context and whether
- they are signaling or quiet).
-\end{methoddesc}
-
-\begin{methoddesc}{normalize}{\optional{context}}
- Normalize the number by stripping the rightmost trailing zeroes and
- converting any result equal to \constant{Decimal("0")} to
- \constant{Decimal("0e0")}. Used for producing canonical values for members
- of an equivalence class. For example, \code{Decimal("32.100")} and
- \code{Decimal("0.321000e+2")} both normalize to the equivalent value
- \code{Decimal("32.1")}.
-\end{methoddesc}
-
-\begin{methoddesc}{quantize}
- {exp \optional{, rounding\optional{, context\optional{, watchexp}}}}
- Quantize makes the exponent the same as \var{exp}. Searches for a
- rounding method in \var{rounding}, then in \var{context}, and then
- in the current context.
-
- If \var{watchexp} is set (default), then an error is returned whenever
- the resulting exponent is greater than \member{Emax} or less than
- \member{Etiny}.
-\end{methoddesc}
-
-\begin{methoddesc}{remainder_near}{other\optional{, context}}
- Computes the modulo as either a positive or negative value depending
- on which is closest to zero. For instance,
- \samp{Decimal(10).remainder_near(6)} returns \code{Decimal("-2")}
- which is closer to zero than \code{Decimal("4")}.
-
- If both are equally close, the one chosen will have the same sign
- as \var{self}.
-\end{methoddesc}
-
-\begin{methoddesc}{same_quantum}{other\optional{, context}}
- Test whether self and other have the same exponent or whether both
- are \constant{NaN}.
-\end{methoddesc}
-
-\begin{methoddesc}{sqrt}{\optional{context}}
- Return the square root to full precision.
-\end{methoddesc}
-
-\begin{methoddesc}{to_eng_string}{\optional{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
- \code{Decimal('123E+1')} to \code{Decimal("1.23E+3")}
-\end{methoddesc}
-
-\begin{methoddesc}{to_integral}{\optional{rounding\optional{, context}}}
- Rounds to the nearest integer without signaling \constant{Inexact}
- or \constant{Rounded}. If given, applies \var{rounding}; otherwise,
- uses the rounding method in either the supplied \var{context} or the
- current context.
-\end{methoddesc}
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Context objects \label{decimal-context}}
-
-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 \function{getcontext()} and \function{setcontext()} functions:
-
-\begin{funcdesc}{getcontext}{}
- Return the current context for the active thread.
-\end{funcdesc}
-
-\begin{funcdesc}{setcontext}{c}
- Set the current context for the active thread to \var{c}.
-\end{funcdesc}
-
-Beginning with Python 2.5, you can also use the \keyword{with} statement
-and the \function{localcontext()} function to temporarily change the
-active context.
-
-\begin{funcdesc}{localcontext}{\optional{c}}
- Return a context manager that will set the current context for
- the active thread to a copy of \var{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:
-\begin{verbatim}
- 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
-\end{verbatim}
-\end{funcdesc}
-
-New contexts can also be created using the \class{Context} constructor
-described below. In addition, the module provides three pre-made
-contexts:
-
-\begin{classdesc*}{BasicContext}
- This is a standard context defined by the General Decimal Arithmetic
- Specification. Precision is set to nine. Rounding is set to
- \constant{ROUND_HALF_UP}. All flags are cleared. All traps are enabled
- (treated as exceptions) except \constant{Inexact}, \constant{Rounded}, and
- \constant{Subnormal}.
-
- Because many of the traps are enabled, this context is useful for debugging.
-\end{classdesc*}
-
-\begin{classdesc*}{ExtendedContext}
- This is a standard context defined by the General Decimal Arithmetic
- Specification. Precision is set to nine. Rounding is set to
- \constant{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 \constant{NaN} or \constant{Infinity}
- instead of raising exceptions. This allows an application to complete a
- run in the presence of conditions that would otherwise halt the program.
-\end{classdesc*}
-
-\begin{classdesc*}{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.
-\end{classdesc*}
-
-
-In addition to the three supplied contexts, new contexts can be created
-with the \class{Context} constructor.
-
-\begin{classdesc}{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 \constant{None},
- the default values are copied from the \constant{DefaultContext}. If the
- \var{flags} field is not specified or is \constant{None}, all flags are
- cleared.
-
- The \var{prec} field is a positive integer that sets the precision for
- arithmetic operations in the context.
-
- The \var{rounding} option is one of:
- \begin{itemize}
- \item \constant{ROUND_CEILING} (towards \constant{Infinity}),
- \item \constant{ROUND_DOWN} (towards zero),
- \item \constant{ROUND_FLOOR} (towards \constant{-Infinity}),
- \item \constant{ROUND_HALF_DOWN} (to nearest with ties going towards zero),
- \item \constant{ROUND_HALF_EVEN} (to nearest with ties going to nearest even integer),
- \item \constant{ROUND_HALF_UP} (to nearest with ties going away from zero), or
- \item \constant{ROUND_UP} (away from zero).
- \end{itemize}
-
- The \var{traps} and \var{flags} fields list any signals to be set.
- Generally, new contexts should only set traps and leave the flags clear.
-
- The \var{Emin} and \var{Emax} fields are integers specifying the outer
- limits allowable for exponents.
-
- The \var{capitals} field is either \constant{0} or \constant{1} (the
- default). If set to \constant{1}, exponents are printed with a capital
- \constant{E}; otherwise, a lowercase \constant{e} is used:
- \constant{Decimal('6.02e+23')}.
-\end{classdesc}
-
-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.
-
-\begin{methoddesc}{clear_flags}{}
- Resets all of the flags to \constant{0}.
-\end{methoddesc}
-
-\begin{methoddesc}{copy}{}
- Return a duplicate of the context.
-\end{methoddesc}
-
-\begin{methoddesc}{create_decimal}{num}
- Creates a new Decimal instance from \var{num} but using \var{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:
-
- \begin{verbatim}
- >>> getcontext().prec = 3
- >>> Decimal("3.4445") + Decimal("1.0023")
- Decimal("4.45")
- >>> Decimal("3.4445") + Decimal(0) + Decimal("1.0023")
- Decimal("4.44")
- \end{verbatim}
-
-\end{methoddesc}
-
-\begin{methoddesc}{Etiny}{}
- Returns a value equal to \samp{Emin - prec + 1} which is the minimum
- exponent value for subnormal results. When underflow occurs, the
- exponent is set to \constant{Etiny}.
-\end{methoddesc}
-
-\begin{methoddesc}{Etop}{}
- Returns a value equal to \samp{Emax - prec + 1}.
-\end{methoddesc}
-
-
-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.
-
-\begin{methoddesc}{abs}{x}
- Returns the absolute value of \var{x}.
-\end{methoddesc}
-
-\begin{methoddesc}{add}{x, y}
- Return the sum of \var{x} and \var{y}.
-\end{methoddesc}
-
-\begin{methoddesc}{compare}{x, y}
- Compares values numerically.
-
- Like \method{__cmp__()} but returns a decimal instance:
- \begin{verbatim}
- a or b is a NaN ==> Decimal("NaN")
- a < b ==> Decimal("-1")
- a == b ==> Decimal("0")
- a > b ==> Decimal("1")
- \end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}{divide}{x, y}
- Return \var{x} divided by \var{y}.
-\end{methoddesc}
-
-\begin{methoddesc}{divmod}{x, y}
- Divides two numbers and returns the integer part of the result.
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-\end{methoddesc}
-
-\begin{methoddesc}{minus}{x}
- Minus corresponds to the unary prefix minus operator in Python.
-\end{methoddesc}
-
-\begin{methoddesc}{multiply}{x, y}
- Return the product of \var{x} and \var{y}.
-\end{methoddesc}
-
-\begin{methoddesc}{normalize}{x}
- Normalize reduces an operand to its simplest form.
-
- Essentially a \method{plus} operation with all trailing zeros removed from
- the result.
-\end{methoddesc}
-
-\begin{methoddesc}{plus}{x}
- Plus corresponds to the unary prefix plus operator in Python. This
- operation applies the context precision and rounding, so it is
- \emph{not} an identity operation.
-\end{methoddesc}
-
-\begin{methoddesc}{power}{x, y\optional{, modulo}}
- Return \samp{x ** y} to the \var{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 \constant{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.
-\end{methoddesc}
-
-\begin{methoddesc}{quantize}{x, y}
- Returns a value equal to \var{x} after rounding and having the exponent of
- \var{y}.
-
- Unlike other operations, if the length of the coefficient after the quantize
- operation would be greater than precision, then an
- \constant{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.
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-\end{methoddesc}
-
-\begin{methoddesc}{remainder_near}{x, y}
- Computed the modulo as either a positive or negative value depending
- on which is closest to zero. For instance,
- \samp{Decimal(10).remainder_near(6)} returns \code{Decimal("-2")}
- which is closer to zero than \code{Decimal("4")}.
-
- If both are equally close, the one chosen will have the same sign
- as \var{self}.
-\end{methoddesc}
-
-\begin{methoddesc}{same_quantum}{x, y}
- Test whether \var{x} and \var{y} have the same exponent or whether both are
- \constant{NaN}.
-\end{methoddesc}
-
-\begin{methoddesc}{sqrt}{x}
- Return the square root of \var{x} to full precision.
-\end{methoddesc}
-
-\begin{methoddesc}{subtract}{x, y}
- Return the difference between \var{x} and \var{y}.
-\end{methoddesc}
-
-\begin{methoddesc}{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
- \code{Decimal('123E+1')} to \code{Decimal("1.23E+3")}
-\end{methoddesc}
-
-\begin{methoddesc}{to_integral}{x}
- Rounds to the nearest integer without signaling \constant{Inexact}
- or \constant{Rounded}.
-\end{methoddesc}
-
-\begin{methoddesc}{to_sci_string}{x}
- Converts a number to a string using scientific notation.
-\end{methoddesc}
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Signals \label{decimal-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 \exception{DivisionByZero}
-exception is raised upon encountering the condition.
-
-
-\begin{classdesc*}{Clamped}
- Altered an exponent to fit representation constraints.
-
- Typically, clamping occurs when an exponent falls outside the context's
- \member{Emin} and \member{Emax} limits. If possible, the exponent is
- reduced to fit by adding zeroes to the coefficient.
-\end{classdesc*}
-
-\begin{classdesc*}{DecimalException}
- Base class for other signals and a subclass of
- \exception{ArithmeticError}.
-\end{classdesc*}
-
-\begin{classdesc*}{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
- \constant{Infinity} or \constant{-Infinity} with the sign determined by
- the inputs to the calculation.
-\end{classdesc*}
-
-\begin{classdesc*}{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.
-\end{classdesc*}
-
-\begin{classdesc*}{InvalidOperation}
- An invalid operation was performed.
-
- Indicates that an operation was requested that does not make sense.
- If not trapped, returns \constant{NaN}. Possible causes include:
-
- \begin{verbatim}
- 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
- \end{verbatim}
-\end{classdesc*}
-
-\begin{classdesc*}{Overflow}
- Numerical overflow.
-
- Indicates the exponent is larger than \member{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 \constant{Infinity}. In either case, \class{Inexact} and
- \class{Rounded} are also signaled.
-\end{classdesc*}
-
-\begin{classdesc*}{Rounded}
- Rounding occurred though possibly no information was lost.
-
- Signaled whenever rounding discards digits; even if those digits are
- zero (such as rounding \constant{5.00} to \constant{5.0}). If not
- trapped, returns the result unchanged. This signal is used to detect
- loss of significant digits.
-\end{classdesc*}
-
-\begin{classdesc*}{Subnormal}
- Exponent was lower than \member{Emin} prior to rounding.
-
- Occurs when an operation result is subnormal (the exponent is too small).
- If not trapped, returns the result unchanged.
-\end{classdesc*}
-
-\begin{classdesc*}{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.
-\end{classdesc*}
-
-The following table summarizes the hierarchy of signals:
-
-\begin{verbatim}
- exceptions.ArithmeticError(exceptions.Exception)
- DecimalException
- Clamped
- DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
- Inexact
- Overflow(Inexact, Rounded)
- Underflow(Inexact, Rounded, Subnormal)
- InvalidOperation
- Rounded
- Subnormal
-\end{verbatim}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Floating Point Notes \label{decimal-notes}}
-
-\subsubsection{Mitigating round-off error with increased precision}
-
-The use of decimal floating point eliminates decimal representation error
-(making it possible to represent \constant{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:
-
-\begin{verbatim}
-# 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")
-\end{verbatim}
-
-The \module{decimal} module makes it possible to restore the identities
-by expanding the precision sufficiently to avoid loss of significance:
-
-\begin{verbatim}
->>> 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")
-\end{verbatim}
-
-\subsubsection{Special values}
-
-The number system for the \module{decimal} module provides special
-values including \constant{NaN}, \constant{sNaN}, \constant{-Infinity},
-\constant{Infinity}, and two zeroes, \constant{+0} and \constant{-0}.
-
-Infinities can be constructed directly with: \code{Decimal('Infinity')}. Also,
-they can arise from dividing by zero when the \exception{DivisionByZero}
-signal is not trapped. Likewise, when the \exception{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 \constant{NaN}, or if the
-\exception{InvalidOperation} signal is trapped, raise an exception. For
-example, \code{0/0} returns \constant{NaN} which means ``not a number''. This
-variety of \constant{NaN} is quiet and, once created, will flow through other
-computations always resulting in another \constant{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 \constant{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:
-
-\begin{verbatim}
->>> 1 / Decimal('Infinity')
-Decimal("0E-1000000026")
-\end{verbatim}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Working with threads \label{decimal-threads}}
-
-The \function{getcontext()} function accesses a different \class{Context}
-object for each thread. Having separate thread contexts means that threads
-may make changes (such as \code{getcontext.prec=10}) without interfering with
-other threads.
-
-Likewise, the \function{setcontext()} function automatically assigns its target
-to the current thread.
-
-If \function{setcontext()} has not been called before \function{getcontext()},
-then \function{getcontext()} will automatically create a new context for use
-in the current thread.
-
-The new context is copied from a prototype context called
-\var{DefaultContext}. To control the defaults so that each thread will use the
-same values throughout the application, directly modify the
-\var{DefaultContext} object. This should be done \emph{before} any threads are
-started so that there won't be a race condition between threads calling
-\function{getcontext()}. For example:
-
-\begin{verbatim}
-# 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()
- . . .
-\end{verbatim}
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Recipes \label{decimal-recipes}}
-
-Here are a few recipes that serve as utility functions and that demonstrate
-ways to work with the \class{Decimal} class:
-
-\begin{verbatim}
-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
-
-\end{verbatim}
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Decimal FAQ \label{decimal-faq}}
-
-Q. It is cumbersome to type \code{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:
-
-\begin{verbatim}
->>> D = decimal.Decimal
->>> D('1.23') + D('3.45')
-Decimal("4.68")
-\end{verbatim}
-
-
-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 \method{quantize()} method rounds to a fixed number of decimal places.
-If the \constant{Inexact} trap is set, it is also useful for validation:
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
-
-
-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 \method{quantize()} step.
-
-
-Q. There are many ways to express the same value. The numbers
-\constant{200}, \constant{200.000}, \constant{2E2}, and \constant{.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 \method{normalize()} method maps all equivalent values to a single
-representative:
-
-\begin{verbatim}
->>> 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")]
-\end{verbatim}
-
-
-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 \constant{5.0E+3} as \constant{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 \constant{Inexact} will signal a need for more precision:
-
-\begin{verbatim}
-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)
-\end{verbatim}
-
-
-Q. Why isn't the \function{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:
-
-\begin{verbatim}
->>> floatToDecimal(1.1)
-Decimal("1.100000000000000088817841970012523233890533447265625")
-\end{verbatim}
-
-
-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:
-
-\begin{verbatim}
->>> getcontext().prec = 3
->>> Decimal('3.104') + D('2.104')
-Decimal("5.21")
->>> Decimal('3.104') + D('0.000') + D('2.104')
-Decimal("5.20")
-\end{verbatim}
-
-The solution is either to increase precision or to force rounding of inputs
-using the unary plus operation:
-
-\begin{verbatim}
->>> getcontext().prec = 3
->>> +Decimal('1.23456789') # unary plus triggers rounding
-Decimal("1.23")
-\end{verbatim}
-
-Alternatively, inputs can be rounded upon creation using the
-\method{Context.create_decimal()} method:
-
-\begin{verbatim}
->>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
-Decimal("1.2345")
-\end{verbatim}
diff --git a/Doc/lib/libdifflib.tex b/Doc/lib/libdifflib.tex
deleted file mode 100644
index 7fb8e92..0000000
--- a/Doc/lib/libdifflib.tex
+++ /dev/null
@@ -1,704 +0,0 @@
-\section{\module{difflib} ---
- Helpers for computing deltas}
-
-\declaremodule{standard}{difflib}
-\modulesynopsis{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}
-
-
-\begin{classdesc*}{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.
-
- \strong{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.
-\end{classdesc*}
-
-\begin{classdesc*}{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:
-
-\begin{tableii}{l|l}{code}{Code}{Meaning}
- \lineii{'- '}{line unique to sequence 1}
- \lineii{'+ '}{line unique to sequence 2}
- \lineii{' '}{line common to both sequences}
- \lineii{'? '}{line not present in either input sequence}
-\end{tableii}
-
- Lines beginning with `\code{?~}' 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.
-\end{classdesc*}
-
-\begin{classdesc*}{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:
-
- \begin{funcdesc}{__init__}{\optional{tabsize}\optional{,
- wrapcolumn}\optional{, linejunk}\optional{, charjunk}}
-
- Initializes instance of \class{HtmlDiff}.
-
- \var{tabsize} is an optional keyword argument to specify tab stop spacing
- and defaults to \code{8}.
-
- \var{wrapcolumn} is an optional keyword to specify column number where
- lines are broken and wrapped, defaults to \code{None} where lines are not
- wrapped.
-
- \var{linejunk} and \var{charjunk} are optional keyword arguments passed
- into \code{ndiff()} (used by \class{HtmlDiff} to generate the
- side by side HTML differences). See \code{ndiff()} documentation for
- argument default values and descriptions.
-
- \end{funcdesc}
-
- The following methods are public:
-
- \begin{funcdesc}{make_file}{fromlines, tolines
- \optional{, fromdesc}\optional{, todesc}\optional{, context}\optional{,
- numlines}}
- Compares \var{fromlines} and \var{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.
-
- \var{fromdesc} and \var{todesc} are optional keyword arguments to specify
- from/to file column header strings (both default to an empty string).
-
- \var{context} and \var{numlines} are both optional keyword arguments.
- Set \var{context} to \code{True} when contextual differences are to be
- shown, else the default is \code{False} to show the full files.
- \var{numlines} defaults to \code{5}. When \var{context} is \code{True}
- \var{numlines} controls the number of context lines which surround the
- difference highlights. When \var{context} is \code{False} \var{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).
- \end{funcdesc}
-
- \begin{funcdesc}{make_table}{fromlines, tolines
- \optional{, fromdesc}\optional{, todesc}\optional{, context}\optional{,
- numlines}}
- Compares \var{fromlines} and \var{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
- \method{make_file()} method.
- \end{funcdesc}
-
- \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}
-\end{classdesc*}
-
-\begin{funcdesc}{context_diff}{a, b\optional{, fromfile}\optional{,
- tofile}\optional{, fromfiledate}\optional{, tofiledate}\optional{,
- n}\optional{, lineterm}}
- Compare \var{a} and \var{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 \var{n}
- which defaults to three.
-
- By default, the diff control lines (those with \code{***} or \code{---})
- are created with a trailing newline. This is helpful so that inputs created
- from \function{file.readlines()} result in diffs that are suitable for use
- with \function{file.writelines()} since both the inputs and outputs have
- trailing newlines.
-
- For inputs that do not have trailing newlines, set the \var{lineterm}
- argument to \code{""} 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
- \var{fromfile}, \var{tofile}, \var{fromfiledate}, and \var{tofiledate}.
- The modification times are normally expressed in the format returned by
- \function{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}
-\end{funcdesc}
-
-\begin{funcdesc}{get_close_matches}{word, possibilities\optional{,
- n}\optional{, cutoff}}
- Return a list of the best ``good enough'' matches. \var{word} is a
- sequence for which close matches are desired (typically a string),
- and \var{possibilities} is a list of sequences against which to
- match \var{word} (typically a list of strings).
-
- Optional argument \var{n} (default \code{3}) is the maximum number
- of close matches to return; \var{n} must be greater than \code{0}.
-
- Optional argument \var{cutoff} (default \code{0.6}) is a float in
- the range [0, 1]. Possibilities that don't score at least that
- similar to \var{word} are ignored.
-
- The best (no more than \var{n}) matches among the possibilities are
- returned in a list, sorted by similarity score, most similar first.
-
-\begin{verbatim}
->>> 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']
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{ndiff}{a, b\optional{, linejunk}\optional{, charjunk}}
- Compare \var{a} and \var{b} (lists of strings); return a
- \class{Differ}-style delta (a generator generating the delta lines).
-
- Optional keyword parameters \var{linejunk} and \var{charjunk} are
- for filter functions (or \code{None}):
-
- \var{linejunk}: A function that accepts a single string
- argument, and returns true if the string is junk, or false if not.
- The default is (\code{None}), starting with Python 2.3. Before then,
- the default was the module-level function
- \function{IS_LINE_JUNK()}, which filters out lines without visible
- characters, except for at most one pound character (\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.
-
- \var{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 \function{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.
-
-\begin{verbatim}
->>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
-... 'ore\ntree\nemu\n'.splitlines(1))
->>> print ''.join(diff),
-- one
-? ^
-+ ore
-? ^
-- two
-- three
-? -
-+ tree
-+ emu
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{restore}{sequence, which}
- Return one of the two sequences that generated a delta.
-
- Given a \var{sequence} produced by \method{Differ.compare()} or
- \function{ndiff()}, extract lines originating from file 1 or 2
- (parameter \var{which}), stripping off line prefixes.
-
- Example:
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
-
-\end{funcdesc}
-
-\begin{funcdesc}{unified_diff}{a, b\optional{, fromfile}\optional{,
- tofile}\optional{, fromfiledate}\optional{, tofiledate}\optional{,
- n}\optional{, lineterm}}
- Compare \var{a} and \var{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 \var{n} which defaults to three.
-
- By default, the diff control lines (those with \code{---}, \code{+++},
- or \code{@@}) are created with a trailing newline. This is helpful so
- that inputs created from \function{file.readlines()} result in diffs
- that are suitable for use with \function{file.writelines()} since both
- the inputs and outputs have trailing newlines.
-
- For inputs that do not have trailing newlines, set the \var{lineterm}
- argument to \code{""} 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
- \var{fromfile}, \var{tofile}, \var{fromfiledate}, and \var{tofiledate}.
- The modification times are normally expressed in the format returned by
- \function{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}
-\end{funcdesc}
-
-\begin{funcdesc}{IS_LINE_JUNK}{line}
- Return true for ignorable lines. The line \var{line} is ignorable
- if \var{line} is blank or contains a single \character{\#},
- otherwise it is not ignorable. Used as a default for parameter
- \var{linejunk} in \function{ndiff()} before Python 2.3.
-\end{funcdesc}
-
-
-\begin{funcdesc}{IS_CHARACTER_JUNK}{ch}
- Return true for ignorable characters. The character \var{ch} is
- ignorable if \var{ch} is a space or tab, otherwise it is not
- ignorable. Used as a default for parameter \var{charjunk} in
- \function{ndiff()}.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seetitle[http://www.ddj.com/184407970?pgno=5]
- {Pattern Matching: The Gestalt Approach}{Discussion of a
- similar algorithm by John W. Ratcliff and D. E. Metzener.
- This was published in
- \citetitle[http://www.ddj.com/]{Dr. Dobb's Journal} in
- July, 1988.}
-\end{seealso}
-
-
-\subsection{SequenceMatcher Objects \label{sequence-matcher}}
-
-The \class{SequenceMatcher} class has this constructor:
-
-\begin{classdesc}{SequenceMatcher}{\optional{isjunk\optional{,
- a\optional{, b}}}}
- Optional argument \var{isjunk} must be \code{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 \code{None} for \var{isjunk} is equivalent to passing
- \code{lambda x: 0}; in other words, no elements are ignored. For
- example, pass:
-
-\begin{verbatim}
-lambda x: x in " \t"
-\end{verbatim}
-
- if you're comparing lines as sequences of characters, and don't want
- to synch up on blanks or hard tabs.
-
- The optional arguments \var{a} and \var{b} are sequences to be
- compared; both default to empty strings. The elements of both
- sequences must be hashable.
-\end{classdesc}
-
-
-\class{SequenceMatcher} objects have the following methods:
-
-\begin{methoddesc}{set_seqs}{a, b}
- Set the two sequences to be compared.
-\end{methoddesc}
-
-\class{SequenceMatcher} computes and caches detailed information about
-the second sequence, so if you want to compare one sequence against
-many sequences, use \method{set_seq2()} to set the commonly used
-sequence once and call \method{set_seq1()} repeatedly, once for each
-of the other sequences.
-
-\begin{methoddesc}{set_seq1}{a}
- Set the first sequence to be compared. The second sequence to be
- compared is not changed.
-\end{methoddesc}
-
-\begin{methoddesc}{set_seq2}{b}
- Set the second sequence to be compared. The first sequence to be
- compared is not changed.
-\end{methoddesc}
-
-\begin{methoddesc}{find_longest_match}{alo, ahi, blo, bhi}
- Find longest matching block in \code{\var{a}[\var{alo}:\var{ahi}]}
- and \code{\var{b}[\var{blo}:\var{bhi}]}.
-
- If \var{isjunk} was omitted or \code{None},
- \method{get_longest_match()} returns \code{(\var{i}, \var{j},
- \var{k})} such that \code{\var{a}[\var{i}:\var{i}+\var{k}]} is equal
- to \code{\var{b}[\var{j}:\var{j}+\var{k}]}, where
- \code{\var{alo} <= \var{i} <= \var{i}+\var{k} <= \var{ahi}} and
- \code{\var{blo} <= \var{j} <= \var{j}+\var{k} <= \var{bhi}}.
- For all \code{(\var{i'}, \var{j'}, \var{k'})} meeting those
- conditions, the additional conditions
- \code{\var{k} >= \var{k'}},
- \code{\var{i} <= \var{i'}},
- and if \code{\var{i} == \var{i'}}, \code{\var{j} <= \var{j'}}
- are also met.
- In other words, of all maximal matching blocks, return one that
- starts earliest in \var{a}, and of all those maximal matching blocks
- that start earliest in \var{a}, return the one that starts earliest
- in \var{b}.
-
-\begin{verbatim}
->>> s = SequenceMatcher(None, " abcd", "abcd abcd")
->>> s.find_longest_match(0, 5, 0, 9)
-(0, 4, 5)
-\end{verbatim}
-
- If \var{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 \code{' abcd'} from matching the \code{' abcd'} at the
- tail end of the second sequence directly. Instead only the
- \code{'abcd'} can match, and matches the leftmost \code{'abcd'} in
- the second sequence:
-
-\begin{verbatim}
->>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
->>> s.find_longest_match(0, 5, 0, 9)
-(1, 0, 4)
-\end{verbatim}
-
- If no blocks match, this returns \code{(\var{alo}, \var{blo}, 0)}.
-\end{methoddesc}
-
-\begin{methoddesc}{get_matching_blocks}{}
- Return list of triples describing matching subsequences.
- Each triple is of the form \code{(\var{i}, \var{j}, \var{n})}, and
- means that \code{\var{a}[\var{i}:\var{i}+\var{n}] ==
- \var{b}[\var{j}:\var{j}+\var{n}]}. The triples are monotonically
- increasing in \var{i} and \var{j}.
-
- The last triple is a dummy, and has the value \code{(len(\var{a}),
- len(\var{b}), 0)}. It is the only triple with \code{\var{n} == 0}.
- % Explain why a dummy is used!
-
- If
- \code{(\var{i}, \var{j}, \var{n})} and
- \code{(\var{i'}, \var{j'}, \var{n'})} are adjacent triples in the list,
- and the second is not the last triple in the list, then
- \code{\var{i}+\var{n} != \var{i'}} or
- \code{\var{j}+\var{n} != \var{j'}}; in other words, adjacent triples
- always describe non-adjacent equal blocks.
- \versionchanged[The guarantee that adjacent triples always describe
- non-adjacent blocks was implemented]{2.5}
-
-\begin{verbatim}
->>> s = SequenceMatcher(None, "abxcd", "abcd")
->>> s.get_matching_blocks()
-[(0, 0, 2), (3, 2, 2), (5, 4, 0)]
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}{get_opcodes}{}
- Return list of 5-tuples describing how to turn \var{a} into \var{b}.
- Each tuple is of the form \code{(\var{tag}, \var{i1}, \var{i2},
- \var{j1}, \var{j2})}. The first tuple has \code{\var{i1} ==
- \var{j1} == 0}, and remaining tuples have \var{i1} equal to the
- \var{i2} from the preceding tuple, and, likewise, \var{j1} equal to
- the previous \var{j2}.
-
- The \var{tag} values are strings, with these meanings:
-
-\begin{tableii}{l|l}{code}{Value}{Meaning}
- \lineii{'replace'}{\code{\var{a}[\var{i1}:\var{i2}]} should be
- replaced by \code{\var{b}[\var{j1}:\var{j2}]}.}
- \lineii{'delete'}{\code{\var{a}[\var{i1}:\var{i2}]} should be
- deleted. Note that \code{\var{j1} == \var{j2}} in
- this case.}
- \lineii{'insert'}{\code{\var{b}[\var{j1}:\var{j2}]} should be
- inserted at \code{\var{a}[\var{i1}:\var{i1}]}.
- Note that \code{\var{i1} == \var{i2}} in this
- case.}
- \lineii{'equal'}{\code{\var{a}[\var{i1}:\var{i2}] ==
- \var{b}[\var{j1}:\var{j2}]} (the sub-sequences are
- equal).}
-\end{tableii}
-
-For example:
-
-\begin{verbatim}
->>> 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)
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}{get_grouped_opcodes}{\optional{n}}
- Return a generator of groups with up to \var{n} lines of context.
-
- Starting with the groups returned by \method{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 \method{get_opcodes()}.
- \versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}{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
- \code{1.0} if the sequences are identical, and \code{0.0} if they
- have nothing in common.
-
- This is expensive to compute if \method{get_matching_blocks()} or
- \method{get_opcodes()} hasn't already been called, in which case you
- may want to try \method{quick_ratio()} or
- \method{real_quick_ratio()} first to get an upper bound.
-\end{methoddesc}
-
-\begin{methoddesc}{quick_ratio}{}
- Return an upper bound on \method{ratio()} relatively quickly.
-
- This isn't defined beyond that it is an upper bound on
- \method{ratio()}, and is faster to compute.
-\end{methoddesc}
-
-\begin{methoddesc}{real_quick_ratio}{}
- Return an upper bound on \method{ratio()} very quickly.
-
- This isn't defined beyond that it is an upper bound on
- \method{ratio()}, and is faster to compute than either
- \method{ratio()} or \method{quick_ratio()}.
-\end{methoddesc}
-
-The three methods that return the ratio of matching to total characters
-can give different results due to differing levels of approximation,
-although \method{quick_ratio()} and \method{real_quick_ratio()} are always
-at least as large as \method{ratio()}:
-
-\begin{verbatim}
->>> s = SequenceMatcher(None, "abcd", "bcde")
->>> s.ratio()
-0.75
->>> s.quick_ratio()
-0.75
->>> s.real_quick_ratio()
-1.0
-\end{verbatim}
-
-
-\subsection{SequenceMatcher Examples \label{sequencematcher-examples}}
-
-
-This example compares two strings, considering blanks to be ``junk:''
-
-\begin{verbatim}
->>> s = SequenceMatcher(lambda x: x == " ",
-... "private Thread currentThread;",
-... "private volatile Thread currentThread;")
-\end{verbatim}
-
-\method{ratio()} returns a float in [0, 1], measuring the similarity
-of the sequences. As a rule of thumb, a \method{ratio()} value over
-0.6 means the sequences are close matches:
-
-\begin{verbatim}
->>> print round(s.ratio(), 3)
-0.866
-\end{verbatim}
-
-If you're only interested in where the sequences match,
-\method{get_matching_blocks()} is handy:
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
-
-Note that the last tuple returned by \method{get_matching_blocks()} is
-always a dummy, \code{(len(\var{a}), len(\var{b}), 0)}, and this is
-the only case in which the last tuple element (number of elements
-matched) is \code{0}.
-
-If you want to know how to change the first sequence into the second,
-use \method{get_opcodes()}:
-
-\begin{verbatim}
->>> 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]
-\end{verbatim}
-
-See also the function \function{get_close_matches()} in this module,
-which shows how simple code building on \class{SequenceMatcher} can be
-used to do useful work.
-
-
-\subsection{Differ Objects \label{differ-objects}}
-
-Note that \class{Differ}-generated deltas make no claim to be
-\strong{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:
-
-\begin{classdesc}{Differ}{\optional{linejunk\optional{, charjunk}}}
- Optional keyword parameters \var{linejunk} and \var{charjunk} are
- for filter functions (or \code{None}):
-
- \var{linejunk}: A function that accepts a single string
- argument, and returns true if the string is junk. The default is
- \code{None}, meaning that no line is considered junk.
-
- \var{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 \code{None}, meaning that no character is
- considered junk.
-\end{classdesc}
-
-\class{Differ} objects are used (deltas generated) via a single
-method:
-
-\begin{methoddesc}{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
- \method{readlines()} method of file-like objects. The delta generated
- also consists of newline-terminated strings, ready to be printed as-is
- via the \method{writelines()} method of a file-like object.
-\end{methoddesc}
-
-
-\subsection{Differ Example \label{differ-examples}}
-
-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 \method{readlines()} method of file-like
-objects):
-
-\begin{verbatim}
->>> 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)
-\end{verbatim}
-
-Next we instantiate a Differ object:
-
-\begin{verbatim}
->>> d = Differ()
-\end{verbatim}
-
-Note that when instantiating a \class{Differ} object we may pass
-functions to filter out line and character ``junk.'' See the
-\method{Differ()} constructor for details.
-
-Finally, we compare the two:
-
-\begin{verbatim}
->>> result = list(d.compare(text1, text2))
-\end{verbatim}
-
-\code{result} is a list of strings, so let's pretty-print it:
-
-\begin{verbatim}
->>> 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']
-\end{verbatim}
-
-As a single multi-line string it looks like this:
-
-\begin{verbatim}
->>> 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.
-\end{verbatim}
diff --git a/Doc/lib/libdircache.tex b/Doc/lib/libdircache.tex
deleted file mode 100644
index 5884549..0000000
--- a/Doc/lib/libdircache.tex
+++ /dev/null
@@ -1,49 +0,0 @@
-\section{\module{dircache} ---
- Cached directory listings}
-
-\declaremodule{standard}{dircache}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Return directory listing, with cache mechanism.}
-
-The \module{dircache} module defines a function for reading directory listing
-using a cache, and cache invalidation using the \var{mtime} of the directory.
-Additionally, it defines a function to annotate directories by appending
-a slash.
-
-The \module{dircache} module defines the following functions:
-
-\begin{funcdesc}{reset}{}
-Resets the directory cache.
-\end{funcdesc}
-
-\begin{funcdesc}{listdir}{path}
-Return a directory listing of \var{path}, as gotten from
-\function{os.listdir()}. Note that unless \var{path} changes, further call
-to \function{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?)
-\end{funcdesc}
-
-\begin{funcdesc}{opendir}{path}
-Same as \function{listdir()}. Defined for backwards compatibility.
-\end{funcdesc}
-
-\begin{funcdesc}{annotate}{head, list}
-Assume \var{list} is a list of paths relative to \var{head}, and append,
-in place, a \character{/} to each path which points to a directory.
-\end{funcdesc}
-
-\begin{verbatim}
->>> 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']
-\end{verbatim}
diff --git a/Doc/lib/libdis.tex b/Doc/lib/libdis.tex
deleted file mode 100644
index 2d78d9a..0000000
--- a/Doc/lib/libdis.tex
+++ /dev/null
@@ -1,674 +0,0 @@
-\section{\module{dis} ---
- Disassembler for Python byte code}
-
-\declaremodule{standard}{dis}
-\modulesynopsis{Disassembler for Python byte code.}
-
-
-The \module{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 \function{myfunc}:
-
-\begin{verbatim}
-def myfunc(alist):
- return len(alist)
-\end{verbatim}
-
-the following command can be used to get the disassembly of
-\function{myfunc()}:
-
-\begin{verbatim}
->>> dis.dis(myfunc)
- 2 0 LOAD_GLOBAL 0 (len)
- 3 LOAD_FAST 0 (alist)
- 6 CALL_FUNCTION 1
- 9 RETURN_VALUE
-\end{verbatim}
-
-(The ``2'' is a line number).
-
-The \module{dis} module defines the following functions and constants:
-
-\begin{funcdesc}{dis}{\optional{bytesource}}
-Disassemble the \var{bytesource} object. \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{distb}{\optional{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.
-\end{funcdesc}
-
-\begin{funcdesc}{disassemble}{code\optional{, lasti}}
-Disassembles a code object, indicating the last instruction if \var{lasti}
-was provided. The output is divided in the following columns:
-
-\begin{enumerate}
-\item the line number, for the first instruction of each line
-\item the current instruction, indicated as \samp{-->},
-\item a labelled instruction, indicated with \samp{>>},
-\item the address of the instruction,
-\item the operation code name,
-\item operation parameters, and
-\item interpretation of the parameters in parentheses.
-\end{enumerate}
-
-The parameter interpretation recognizes local and global
-variable names, constant values, branch targets, and compare
-operators.
-\end{funcdesc}
-
-\begin{funcdesc}{disco}{code\optional{, lasti}}
-A synonym for disassemble. It is more convenient to type, and kept
-for compatibility with earlier Python releases.
-\end{funcdesc}
-
-\begin{datadesc}{opname}
-Sequence of operation names, indexable using the byte code.
-\end{datadesc}
-
-\begin{datadesc}{opmap}
-Dictionary mapping byte codes to operation names.
-\end{datadesc}
-
-\begin{datadesc}{cmp_op}
-Sequence of all compare operation names.
-\end{datadesc}
-
-\begin{datadesc}{hasconst}
-Sequence of byte codes that have a constant parameter.
-\end{datadesc}
-
-\begin{datadesc}{hasfree}
-Sequence of byte codes that access a free variable.
-\end{datadesc}
-
-\begin{datadesc}{hasname}
-Sequence of byte codes that access an attribute by name.
-\end{datadesc}
-
-\begin{datadesc}{hasjrel}
-Sequence of byte codes that have a relative jump target.
-\end{datadesc}
-
-\begin{datadesc}{hasjabs}
-Sequence of byte codes that have an absolute jump target.
-\end{datadesc}
-
-\begin{datadesc}{haslocal}
-Sequence of byte codes that access a local variable.
-\end{datadesc}
-
-\begin{datadesc}{hascompare}
-Sequence of byte codes of Boolean operations.
-\end{datadesc}
-
-\subsection{Python Byte Code Instructions}
-\label{bytecodes}
-
-The Python compiler currently generates the following byte code
-instructions.
-
-\setindexsubitem{(byte code insns)}
-
-\begin{opcodedesc}{STOP_CODE}{}
-Indicates end-of-code to the compiler, not used by the interpreter.
-\end{opcodedesc}
-
-\begin{opcodedesc}{NOP}{}
-Do nothing code. Used as a placeholder by the bytecode optimizer.
-\end{opcodedesc}
-
-\begin{opcodedesc}{POP_TOP}{}
-Removes the top-of-stack (TOS) item.
-\end{opcodedesc}
-
-\begin{opcodedesc}{ROT_TWO}{}
-Swaps the two top-most stack items.
-\end{opcodedesc}
-
-\begin{opcodedesc}{ROT_THREE}{}
-Lifts second and third stack item one position up, moves top down
-to position three.
-\end{opcodedesc}
-
-\begin{opcodedesc}{ROT_FOUR}{}
-Lifts second, third and forth stack item one position up, moves top down to
-position four.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DUP_TOP}{}
-Duplicates the reference on top of the stack.
-\end{opcodedesc}
-
-Unary Operations take the top of the stack, apply the operation, and
-push the result back on the stack.
-
-\begin{opcodedesc}{UNARY_POSITIVE}{}
-Implements \code{TOS = +TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{UNARY_NEGATIVE}{}
-Implements \code{TOS = -TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{UNARY_NOT}{}
-Implements \code{TOS = not TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{UNARY_INVERT}{}
-Implements \code{TOS = \~{}TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{GET_ITER}{}
-Implements \code{TOS = iter(TOS)}.
-\end{opcodedesc}
-
-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.
-
-\begin{opcodedesc}{BINARY_POWER}{}
-Implements \code{TOS = TOS1 ** TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_MULTIPLY}{}
-Implements \code{TOS = TOS1 * TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_FLOOR_DIVIDE}{}
-Implements \code{TOS = TOS1 // TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_TRUE_DIVIDE}{}
-Implements \code{TOS = TOS1 / TOS} when
-\code{from __future__ import division} is in effect.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_MODULO}{}
-Implements \code{TOS = TOS1 \%{} TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_ADD}{}
-Implements \code{TOS = TOS1 + TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_SUBTRACT}{}
-Implements \code{TOS = TOS1 - TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_SUBSCR}{}
-Implements \code{TOS = TOS1[TOS]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_LSHIFT}{}
-Implements \code{TOS = TOS1 <\code{}< TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_RSHIFT}{}
-Implements \code{TOS = TOS1 >\code{}> TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_AND}{}
-Implements \code{TOS = TOS1 \&\ TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_XOR}{}
-Implements \code{TOS = TOS1 \^\ TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_OR}{}
-Implements \code{TOS = TOS1 | TOS}.
-\end{opcodedesc}
-
-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.
-
-\begin{opcodedesc}{INPLACE_POWER}{}
-Implements in-place \code{TOS = TOS1 ** TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_MULTIPLY}{}
-Implements in-place \code{TOS = TOS1 * TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_FLOOR_DIVIDE}{}
-Implements in-place \code{TOS = TOS1 // TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_TRUE_DIVIDE}{}
-Implements in-place \code{TOS = TOS1 / TOS} when
-\code{from __future__ import division} is in effect.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_MODULO}{}
-Implements in-place \code{TOS = TOS1 \%{} TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_ADD}{}
-Implements in-place \code{TOS = TOS1 + TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_SUBTRACT}{}
-Implements in-place \code{TOS = TOS1 - TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_LSHIFT}{}
-Implements in-place \code{TOS = TOS1 <\code{}< TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_RSHIFT}{}
-Implements in-place \code{TOS = TOS1 >\code{}> TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_AND}{}
-Implements in-place \code{TOS = TOS1 \&\ TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_XOR}{}
-Implements in-place \code{TOS = TOS1 \^\ TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_OR}{}
-Implements in-place \code{TOS = TOS1 | TOS}.
-\end{opcodedesc}
-
-The slice opcodes take up to three parameters.
-
-\begin{opcodedesc}{SLICE+0}{}
-Implements \code{TOS = TOS[:]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{SLICE+1}{}
-Implements \code{TOS = TOS1[TOS:]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{SLICE+2}{}
-Implements \code{TOS = TOS1[:TOS]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{SLICE+3}{}
-Implements \code{TOS = TOS2[TOS1:TOS]}.
-\end{opcodedesc}
-
-Slice assignment needs even an additional parameter. As any statement,
-they put nothing on the stack.
-
-\begin{opcodedesc}{STORE_SLICE+0}{}
-Implements \code{TOS[:] = TOS1}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_SLICE+1}{}
-Implements \code{TOS1[TOS:] = TOS2}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_SLICE+2}{}
-Implements \code{TOS1[:TOS] = TOS2}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_SLICE+3}{}
-Implements \code{TOS2[TOS1:TOS] = TOS3}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_SLICE+0}{}
-Implements \code{del TOS[:]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_SLICE+1}{}
-Implements \code{del TOS1[TOS:]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_SLICE+2}{}
-Implements \code{del TOS1[:TOS]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_SLICE+3}{}
-Implements \code{del TOS2[TOS1:TOS]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_SUBSCR}{}
-Implements \code{TOS1[TOS] = TOS2}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_SUBSCR}{}
-Implements \code{del TOS1[TOS]}.
-\end{opcodedesc}
-
-Miscellaneous opcodes.
-
-\begin{opcodedesc}{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 \code{POP_STACK}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BREAK_LOOP}{}
-Terminates a loop due to a \keyword{break} statement.
-\end{opcodedesc}
-
-\begin{opcodedesc}{CONTINUE_LOOP}{target}
-Continues a loop due to a \keyword{continue} statement. \var{target}
-is the address to jump to (which should be a \code{FOR_ITER}
-instruction).
-\end{opcodedesc}
-
-\begin{opcodedesc}{SET_ADD}{}
-Calls \code{set.add(TOS1, TOS)}. Used to implement set comprehensions.
-\end{opcodedesc}
-
-\begin{opcodedesc}{LIST_APPEND}{}
-Calls \code{list.append(TOS1, TOS)}. Used to implement list comprehensions.
-\end{opcodedesc}
-
-\begin{opcodedesc}{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.
-\end{opcodedesc}
-
-\begin{opcodedesc}{RETURN_VALUE}{}
-Returns with TOS to the caller of the function.
-\end{opcodedesc}
-
-\begin{opcodedesc}{YIELD_VALUE}{}
-Pops \code{TOS} and yields it from a generator.
-\end{opcodedesc}
-
-\begin{opcodedesc}{IMPORT_STAR}{}
-Loads all symbols not starting with \character{_} directly from the module TOS
-to the local namespace. The module is popped after loading all names.
-This opcode implements \code{from module import *}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{POP_BLOCK}{}
-Removes one block from the block stack. Per frame, there is a
-stack of blocks, denoting nested loops, try statements, and such.
-\end{opcodedesc}
-
-\begin{opcodedesc}{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.
-\end{opcodedesc}
-
-\begin{opcodedesc}{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.
-\end{opcodedesc}
-
-All of the following opcodes expect arguments. An argument is two
-bytes, with the more significant byte last.
-
-\begin{opcodedesc}{STORE_NAME}{namei}
-Implements \code{name = TOS}. \var{namei} is the index of \var{name}
-in the attribute \member{co_names} of the code object.
-The compiler tries to use \code{STORE_LOCAL} or \code{STORE_GLOBAL}
-if possible.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_NAME}{namei}
-Implements \code{del name}, where \var{namei} is the index into
-\member{co_names} attribute of the code object.
-\end{opcodedesc}
-
-\begin{opcodedesc}{UNPACK_SEQUENCE}{count}
-Unpacks TOS into \var{count} individual values, which are put onto
-the stack right-to-left.
-\end{opcodedesc}
-
-%\begin{opcodedesc}{UNPACK_LIST}{count}
-%This opcode is obsolete.
-%\end{opcodedesc}
-
-%\begin{opcodedesc}{UNPACK_ARG}{count}
-%This opcode is obsolete.
-%\end{opcodedesc}
-
-\begin{opcodedesc}{DUP_TOPX}{count}
-Duplicate \var{count} items, keeping them in the same order. Due to
-implementation limits, \var{count} should be between 1 and 5 inclusive.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_ATTR}{namei}
-Implements \code{TOS.name = TOS1}, where \var{namei} is the index
-of name in \member{co_names}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_ATTR}{namei}
-Implements \code{del TOS.name}, using \var{namei} as index into
-\member{co_names}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_GLOBAL}{namei}
-Works as \code{STORE_NAME}, but stores the name as a global.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_GLOBAL}{namei}
-Works as \code{DELETE_NAME}, but deletes a global name.
-\end{opcodedesc}
-
-%\begin{opcodedesc}{UNPACK_VARARG}{argc}
-%This opcode is obsolete.
-%\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_CONST}{consti}
-Pushes \samp{co_consts[\var{consti}]} onto the stack.
-\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_NAME}{namei}
-Pushes the value associated with \samp{co_names[\var{namei}]} onto the stack.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BUILD_TUPLE}{count}
-Creates a tuple consuming \var{count} items from the stack, and pushes
-the resulting tuple onto the stack.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BUILD_LIST}{count}
-Works as \code{BUILD_TUPLE}, but creates a list.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BUILD_SET}{count}
-Works as \code{BUILD_TUPLE}, but creates a set.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BUILD_MAP}{zero}
-Pushes a new empty dictionary object onto the stack. The argument is
-ignored and set to zero by the compiler.
-\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_ATTR}{namei}
-Replaces TOS with \code{getattr(TOS, co_names[\var{namei}])}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{COMPARE_OP}{opname}
-Performs a Boolean operation. The operation name can be found
-in \code{cmp_op[\var{opname}]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{IMPORT_NAME}{namei}
-Imports the module \code{co_names[\var{namei}]}. The module object is
-pushed onto the stack. The current namespace is not affected: for a
-proper import statement, a subsequent \code{STORE_FAST} instruction
-modifies the namespace.
-\end{opcodedesc}
-
-\begin{opcodedesc}{IMPORT_FROM}{namei}
-Loads the attribute \code{co_names[\var{namei}]} from the module found in
-TOS. The resulting object is pushed onto the stack, to be subsequently
-stored by a \code{STORE_FAST} instruction.
-\end{opcodedesc}
-
-\begin{opcodedesc}{JUMP_FORWARD}{delta}
-Increments byte code counter by \var{delta}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{JUMP_IF_TRUE}{delta}
-If TOS is true, increment the byte code counter by \var{delta}. TOS is
-left on the stack.
-\end{opcodedesc}
-
-\begin{opcodedesc}{JUMP_IF_FALSE}{delta}
-If TOS is false, increment the byte code counter by \var{delta}. TOS
-is not changed.
-\end{opcodedesc}
-
-\begin{opcodedesc}{JUMP_ABSOLUTE}{target}
-Set byte code counter to \var{target}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{FOR_ITER}{delta}
- \code{TOS} is an iterator. Call its \method{__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 \code{TOS} is popped, and the byte code
- counter is incremented by \var{delta}.
-\end{opcodedesc}
-
-%\begin{opcodedesc}{FOR_LOOP}{delta}
-%This opcode is obsolete.
-%\end{opcodedesc}
-
-%\begin{opcodedesc}{LOAD_LOCAL}{namei}
-%This opcode is obsolete.
-%\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_GLOBAL}{namei}
-Loads the global named \code{co_names[\var{namei}]} onto the stack.
-\end{opcodedesc}
-
-%\begin{opcodedesc}{SET_FUNC_ARGS}{argc}
-%This opcode is obsolete.
-%\end{opcodedesc}
-
-\begin{opcodedesc}{SETUP_LOOP}{delta}
-Pushes a block for a loop onto the block stack. The block spans
-from the current instruction with a size of \var{delta} bytes.
-\end{opcodedesc}
-
-\begin{opcodedesc}{SETUP_EXCEPT}{delta}
-Pushes a try block from a try-except clause onto the block stack.
-\var{delta} points to the first except block.
-\end{opcodedesc}
-
-\begin{opcodedesc}{SETUP_FINALLY}{delta}
-Pushes a try block from a try-except clause onto the block stack.
-\var{delta} points to the finally block.
-\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_FAST}{var_num}
-Pushes a reference to the local \code{co_varnames[\var{var_num}]} onto
-the stack.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_FAST}{var_num}
-Stores TOS into the local \code{co_varnames[\var{var_num}]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_FAST}{var_num}
-Deletes local \code{co_varnames[\var{var_num}]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_CLOSURE}{i}
-Pushes a reference to the cell contained in slot \var{i} of the
-cell and free variable storage. The name of the variable is
-\code{co_cellvars[\var{i}]} if \var{i} is less than the length of
-\var{co_cellvars}. Otherwise it is
-\code{co_freevars[\var{i} - len(co_cellvars)]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_DEREF}{i}
-Loads the cell contained in slot \var{i} of the cell and free variable
-storage. Pushes a reference to the object the cell contains on the
-stack.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_DEREF}{i}
-Stores TOS into the cell contained in slot \var{i} of the cell and
-free variable storage.
-\end{opcodedesc}
-
-\begin{opcodedesc}{SET_LINENO}{lineno}
-This opcode is obsolete.
-\end{opcodedesc}
-
-\begin{opcodedesc}{RAISE_VARARGS}{argc}
-Raises an exception. \var{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.
-\end{opcodedesc}
-
-\begin{opcodedesc}{CALL_FUNCTION}{argc}
-Calls a function. The low byte of \var{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.
-\end{opcodedesc}
-
-\begin{opcodedesc}{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 \var{argc}
-default parameters, which are found below TOS.
-\end{opcodedesc}
-
-\begin{opcodedesc}{MAKE_CLOSURE}{argc}
-Creates a new function object, sets its \var{__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 \var{argc}
-default parameters, where are found before the cells.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BUILD_SLICE}{argc}
-Pushes a slice object on the stack. \var{argc} must be 2 or 3. If it
-is 2, \code{slice(TOS1, TOS)} is pushed; if it is 3,
-\code{slice(TOS2, TOS1, TOS)} is pushed.
-See the \code{slice()}\bifuncindex{slice} built-in function for more
-information.
-\end{opcodedesc}
-
-\begin{opcodedesc}{EXTENDED_ARG}{ext}
-Prefixes any opcode which has an argument too big to fit into the
-default two bytes. \var{ext} holds two additional bytes which, taken
-together with the subsequent opcode's argument, comprise a four-byte
-argument, \var{ext} being the two most-significant bytes.
-\end{opcodedesc}
-
-\begin{opcodedesc}{CALL_FUNCTION_VAR}{argc}
-Calls a function. \var{argc} is interpreted as in \code{CALL_FUNCTION}.
-The top element on the stack contains the variable argument list, followed
-by keyword and positional arguments.
-\end{opcodedesc}
-
-\begin{opcodedesc}{CALL_FUNCTION_KW}{argc}
-Calls a function. \var{argc} is interpreted as in \code{CALL_FUNCTION}.
-The top element on the stack contains the keyword arguments dictionary,
-followed by explicit keyword and positional arguments.
-\end{opcodedesc}
-
-\begin{opcodedesc}{CALL_FUNCTION_VAR_KW}{argc}
-Calls a function. \var{argc} is interpreted as in
-\code{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.
-\end{opcodedesc}
-
-\begin{opcodedesc}{HAVE_ARGUMENT}{}
-This is not really an opcode. It identifies the dividing line between
-opcodes which don't take arguments \code{< HAVE_ARGUMENT} and those which do
-\code{>= HAVE_ARGUMENT}.
-\end{opcodedesc}
diff --git a/Doc/lib/libdl.tex b/Doc/lib/libdl.tex
deleted file mode 100644
index d4a799e..0000000
--- a/Doc/lib/libdl.tex
+++ /dev/null
@@ -1,101 +0,0 @@
-\section{\module{dl} ---
- Call C functions in shared objects}
-\declaremodule{extension}{dl}
- \platform{Unix} %?????????? Anyone????????????
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Call C functions in shared objects.}
-
-The \module{dl} module defines an interface to the
-\cfunction{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 \module{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
-\code{sizeof(int) == sizeof(long) == sizeof(char *)}
-If this is not the case, \exception{SystemError} will be raised on
-import.}
-
-The \module{dl} module defines the following function:
-
-\begin{funcdesc}{open}{name\optional{, mode\code{ = RTLD_LAZY}}}
-Open a shared object file, and return a handle. Mode
-signifies late binding (\constant{RTLD_LAZY}) or immediate binding
-(\constant{RTLD_NOW}). Default is \constant{RTLD_LAZY}. Note that some
-systems do not support \constant{RTLD_NOW}.
-
-Return value is a \class{dlobject}.
-\end{funcdesc}
-
-The \module{dl} module defines the following constants:
-
-\begin{datadesc}{RTLD_LAZY}
-Useful as an argument to \function{open()}.
-\end{datadesc}
-
-\begin{datadesc}{RTLD_NOW}
-Useful as an argument to \function{open()}. Note that on systems
-which do not support immediate binding, this constant will not appear
-in the module. For maximum portability, use \function{hasattr()} to
-determine if the system supports immediate binding.
-\end{datadesc}
-
-The \module{dl} module defines the following exception:
-
-\begin{excdesc}{error}
-Exception raised when an error has occurred inside the dynamic loading
-and linking routines.
-\end{excdesc}
-
-Example:
-
-\begin{verbatim}
->>> import dl, time
->>> a=dl.open('/lib/libc.so.6')
->>> a.call('time'), time.time()
-(929723914, 929723914.498)
-\end{verbatim}
-
-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.
-
-\subsection{Dl Objects \label{dl-objects}}
-
-Dl objects, as returned by \function{open()} above, have the
-following methods:
-
-\begin{methoddesc}[dl]{close}{}
-Free all resources, except the memory.
-\end{methoddesc}
-
-\begin{methoddesc}[dl]{sym}{name}
-Return the pointer for the function named \var{name}, as a number, if
-it exists in the referenced shared object, otherwise \code{None}. This
-is useful in code like:
-
-\begin{verbatim}
->>> if a.sym('time'):
-... a.call('time')
-... else:
-... time.time()
-\end{verbatim}
-
-(Note that this function will return a non-zero number, as zero is the
-\NULL{} pointer)
-\end{methoddesc}
-
-\begin{methoddesc}[dl]{call}{name\optional{, arg1\optional{, arg2\ldots}}}
-Call the function named \var{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 \code{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 \code{None}. The function's return value must be a C
-\ctype{long}, which is a Python integer.
-\end{methoddesc}
diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex
deleted file mode 100644
index 9143b84..0000000
--- a/Doc/lib/libdoctest.tex
+++ /dev/null
@@ -1,1974 +0,0 @@
-\section{\module{doctest} ---
- Test interactive Python examples}
-
-\declaremodule{standard}{doctest}
-\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}
-
-\modulesynopsis{A framework for verifying interactive Python examples.}
-
-The \refmodule{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:
-
-\begin{itemize}
-\item To check that a module's docstrings are up-to-date by verifying
- that all interactive examples still work as documented.
-\item To perform regression testing by verifying that interactive
- examples from a test file or a test object work as expected.
-\item 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".
-\end{itemize}
-
-Here's a complete but small example module:
-
-\begin{verbatim}
-"""
-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
- """
-
-\end{verbatim}
-% allow LaTeX to break here.
-\begin{verbatim}
-
- 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()
-\end{verbatim}
-
-If you run \file{example.py} directly from the command line,
-\refmodule{doctest} works its magic:
-
-\begin{verbatim}
-$ python example.py
-$
-\end{verbatim}
-
-There's no output! That's normal, and it means all the examples
-worked. Pass \programopt{-v} to the script, and \refmodule{doctest}
-prints a detailed log of what it's trying, and prints a summary at the
-end:
-
-\begin{verbatim}
-$ 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
-\end{verbatim}
-
-And so on, eventually ending with:
-
-\begin{verbatim}
-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.
-$
-\end{verbatim}
-
-That's all you need to know to start making productive use of
-\refmodule{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}.
-
-\subsection{Simple Usage: Checking Examples in
- Docstrings\label{doctest-simple-testmod}}
-
-The simplest way to start using doctest (but not necessarily the way
-you'll continue to do it) is to end each module \module{M} with:
-
-\begin{verbatim}
-def _test():
- import doctest
- doctest.testmod()
-
-if __name__ == "__main__":
- _test()
-\end{verbatim}
-
-\refmodule{doctest} then examines docstrings in module \module{M}.
-
-Running the module as a script causes the examples in the docstrings
-to get executed and verified:
-
-\begin{verbatim}
-python M.py
-\end{verbatim}
-
-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
-\samp{***Test Failed*** \var{N} failures.}, where \var{N} is the
-number of examples that failed.
-
-Run it with the \programopt{-v} switch instead:
-
-\begin{verbatim}
-python M.py -v
-\end{verbatim}
-
-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 \code{verbose=True} to
-\function{testmod()}, or
-prohibit it by passing \code{verbose=False}. In either of those cases,
-\code{sys.argv} is not examined by \function{testmod()} (so passing
-\programopt{-v} or not has no effect).
-
-Since Python 2.6, there is also a command line shortcut for running
-\function{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:
-
-\begin{verbatim}
-python -m doctest -v example.py
-\end{verbatim}
-
-This will import \file{example.py} as a standalone module and run
-\function{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 \function{testmod()}, see
-section~\ref{doctest-basic-api}.
-
-\subsection{Simple Usage: Checking Examples in a Text
- File\label{doctest-simple-testfile}}
-
-Another simple application of doctest is testing interactive examples
-in a text file. This can be done with the \function{testfile()}
-function:
-
-\begin{verbatim}
-import doctest
-doctest.testfile("example.txt")
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-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
-\end{verbatim}
-
-Running \code{doctest.testfile("example.txt")} then finds the error
-in this documentation:
-
-\begin{verbatim}
-File "./example.txt", line 14, in example.txt
-Failed example:
- factorial(6)
-Expected:
- 120
-Got:
- 720
-\end{verbatim}
-
-As with \function{testmod()}, \function{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 \function{testmod()}.
-
-By default, \function{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 \function{testmod()}, \function{testfile()}'s verbosity can be
-set with the \programopt{-v} command-line switch or with the optional
-keyword argument \var{verbose}.
-
-Since Python 2.6, there is also a command line shortcut for running
-\function{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:
-
-\begin{verbatim}
-python -m doctest -v example.txt
-\end{verbatim}
-
-Because the file name does not end with \file{.py}, \module{doctest} infers
-that it must be run with \function{testfile()}, not \function{testmod()}.
-
-For more information on \function{testfile()}, see
-section~\ref{doctest-basic-api}.
-
-\subsection{How It Works\label{doctest-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.
-
-\subsubsection{Which Docstrings Are Examined?\label{doctest-which-docstrings}}
-
-The module docstring, and all function, class and method docstrings are
-searched. Objects imported into the module are not searched.
-
-In addition, if \code{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
-\code{M.__test__} are searched, and strings are treated as if they
-were docstrings. In output, a key \code{K} in \code{M.__test__} appears
-with name
-
-\begin{verbatim}
-<name of M>.__test__.K
-\end{verbatim}
-
-Any classes found are recursively searched similarly, to test docstrings in
-their contained methods and nested classes.
-
-\versionchanged[A "private name" concept is deprecated and no longer
- documented]{2.4}
-
-\subsubsection{How are Docstring Examples
- Recognized?\label{doctest-finding-examples}}
-
-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[Expanding tabs to spaces is new; previous versions
- tried to preserve hard tabs, with confusing results]{2.4}
-
-\begin{verbatim}
->>> # comments are ignored
->>> x = 12
->>> x
-12
->>> if x == 13:
-... print "yes"
-... else:
-... print "no"
-... print "NO"
-... print "NO!!!"
-...
-no
-NO
-NO!!!
->>>
-\end{verbatim}
-
-Any expected output must immediately follow the final
-\code{'>>>~'} or \code{'...~'} line containing the code, and
-the expected output (if any) extends to the next \code{'>>>~'}
-or all-whitespace line.
-
-The fine print:
-
-\begin{itemize}
-
-\item 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 \code{<BLANKLINE>} in your
- doctest example each place a blank line is expected.
- \versionchanged[\code{<BLANKLINE>} was added; there was no way to
- use expected output containing empty lines in
- previous versions]{2.4}
-
-\item Output to stdout is captured, but not output to stderr (exception
- tracebacks are captured via a different means).
-
-\item 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:
-
-\begin{verbatim}
->>> def f(x):
-... r'''Backslashes in a raw docstring: m\n'''
->>> print f.__doc__
-Backslashes in a raw docstring: m\n
-\end{verbatim}
-
- Otherwise, the backslash will be interpreted as part of the string.
- For example, the "{\textbackslash}" above would be interpreted as a
- newline character. Alternatively, you can double each backslash in the
- doctest version (and not use a raw string):
-
-\begin{verbatim}
->>> def f(x):
-... '''Backslashes in a raw docstring: m\\n'''
->>> print f.__doc__
-Backslashes in a raw docstring: m\n
-\end{verbatim}
-
-\item The starting column doesn't matter:
-
-\begin{verbatim}
- >>> assert "Easy!"
- >>> import math
- >>> math.floor(1.9)
- 1.0
-\end{verbatim}
-
-and as many leading whitespace characters are stripped from the
-expected output as appeared in the initial \code{'>>>~'} line
-that started the example.
-\end{itemize}
-
-\subsubsection{What's the Execution Context?\label{doctest-execution-context}}
-
-By default, each time \refmodule{doctest} finds a docstring to test, it
-uses a \emph{shallow copy} of \module{M}'s globals, so that running tests
-doesn't change the module's real globals, and so that one test in
-\module{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 \module{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
-\code{globs=your_dict} to \function{testmod()} or
-\function{testfile()} instead.
-
-\subsubsection{What About Exceptions?\label{doctest-exceptions}}
-
-No problem, provided that the traceback is the only output produced by
-the example: just paste in the traceback.\footnote{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.}
-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:
-
-\begin{verbatim}
->>> [1, 2, 3].remove(42)
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ValueError: list.remove(x): x not in list
-\end{verbatim}
-
-That doctest succeeds if \exception{ValueError} is raised, with the
-\samp{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:
-
-\begin{verbatim}
-Traceback (most recent call last):
-Traceback (innermost last):
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
->>> raise ValueError('multi\n line\ndetail')
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ValueError: multi
- line
-detail
-\end{verbatim}
-
-The last three lines (starting with \exception{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:
-
-\begin{verbatim}
->>> raise ValueError('multi\n line\ndetail')
-Traceback (most recent call last):
- ...
-ValueError: multi
- line
-detail
-\end{verbatim}
-
-Note that tracebacks are treated very specially. In particular, in the
-rewritten example, the use of \samp{...} is independent of doctest's
-\constant{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:
-
-\begin{itemize}
-
-\item Doctest can't guess whether your expected output came from an
- exception traceback or from ordinary printing. So, e.g., an example
- that expects \samp{ValueError: 42 is prime} will pass whether
- \exception{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.
-
-\item Each line of the traceback stack (if present) must be indented
- further than the first line of the example, \emph{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.
-
-\item When the \constant{IGNORE_EXCEPTION_DETAIL} doctest option is
- is specified, everything following the leftmost colon is ignored.
-
-\item The interactive shell omits the traceback header line for some
- \exception{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 \exception{SyntaxError} that omits the
- traceback header, you will need to manually add the traceback header
- line to your test example.
-
-\item For some \exception{SyntaxError}s, Python displays the character
- position of the syntax error, using a \code{\^} marker:
-
-\begin{verbatim}
->>> 1 1
- File "<stdin>", line 1
- 1 1
- ^
-SyntaxError: invalid syntax
-\end{verbatim}
-
- 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
- \code{\^} marker in the wrong location:
-
-\begin{verbatim}
->>> 1 1
-Traceback (most recent call last):
- File "<stdin>", line 1
- 1 1
- ^
-SyntaxError: invalid syntax
-\end{verbatim}
-
-\end{itemize}
-
-\versionchanged[The ability to handle a multi-line exception detail,
- and the \constant{IGNORE_EXCEPTION_DETAIL} doctest option,
- were added]{2.4}
-
-\subsubsection{Option Flags and Directives\label{doctest-options}}
-
-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:
-
-\begin{datadesc}{DONT_ACCEPT_TRUE_FOR_1}
- By default, if an expected output block contains just \code{1},
- an actual output block containing just \code{1} or just
- \code{True} is considered to be a match, and similarly for \code{0}
- versus \code{False}. When \constant{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.
-\end{datadesc}
-
-\begin{datadesc}{DONT_ACCEPT_BLANKLINE}
- By default, if an expected output block contains a line
- containing only the string \code{<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
- \constant{DONT_ACCEPT_BLANKLINE} is specified, this substitution
- is not allowed.
-\end{datadesc}
-
-\begin{datadesc}{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.
- \constant{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.
-\end{datadesc}
-
-\begin{datadesc}{ELLIPSIS}
- When specified, an ellipsis marker (\code{...}) 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 \regexp{.*}
- is prone to in regular expressions.
-\end{datadesc}
-
-\begin{datadesc}{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
- \samp{ValueError: 42} will pass if the actual exception raised is
- \samp{ValueError: 3*14}, but will fail, e.g., if
- \exception{TypeError} is raised.
-
- Note that a similar effect can be obtained using \constant{ELLIPSIS},
- and \constant{IGNORE_EXCEPTION_DETAIL} may go away when Python releases
- prior to 2.4 become uninteresting. Until then,
- \constant{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,
-
-\begin{verbatim}
->>> (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
-\end{verbatim}
-
- passes under Python 2.4 and Python 2.3. The detail changed in 2.4,
- to say "does not" instead of "doesn't".
-
-\end{datadesc}
-
-\begin{datadesc}{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.
-
-\end{datadesc}
-
-\begin{datadesc}{COMPARISON_FLAGS}
- A bitmask or'ing together all the comparison flags above.
-\end{datadesc}
-
-The second group of options controls how test failures are reported:
-
-\begin{datadesc}{REPORT_UDIFF}
- When specified, failures that involve multi-line expected and
- actual outputs are displayed using a unified diff.
-\end{datadesc}
-
-\begin{datadesc}{REPORT_CDIFF}
- When specified, failures that involve multi-line expected and
- actual outputs will be displayed using a context diff.
-\end{datadesc}
-
-\begin{datadesc}{REPORT_NDIFF}
- When specified, differences are computed by \code{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 \code{1} where actual output contains letter \code{l},
- a line is inserted with a caret marking the mismatching column
- positions.
-\end{datadesc}
-
-\begin{datadesc}{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
- \constant{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.
-\end{datadesc}
-
-\begin{datadesc}{REPORTING_FLAGS}
- A bitmask or'ing together all the reporting flags above.
-\end{datadesc}
-
-"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:
-
-\begin{productionlist}[doctest]
- \production{directive}
- {"\#" "doctest:" \token{directive_options}}
- \production{directive_options}
- {\token{directive_option} ("," \token{directive_option})*}
- \production{directive_option}
- {\token{on_or_off} \token{directive_option_name}}
- \production{on_or_off}
- {"+" | "-"}
- \production{directive_option_name}
- {"DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ...}
-\end{productionlist}
-
-Whitespace is not allowed between the \code{+} or \code{-} 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 \code{+} to enable the named behavior, or
-\code{-} to disable it.
-
-For example, this test passes:
-
-\begin{verbatim}
->>> 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]
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
->>> print range(20) # doctest:+ELLIPSIS
-[0, 1, ..., 18, 19]
-\end{verbatim}
-
-Multiple directives can be used on a single physical line, separated
-by commas:
-
-\begin{verbatim}
->>> print range(20) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
-[0, 1, ..., 18, 19]
-\end{verbatim}
-
-If multiple directive comments are used for a single example, then
-they are combined:
-
-\begin{verbatim}
->>> print range(20) # doctest: +ELLIPSIS
-... # doctest: +NORMALIZE_WHITESPACE
-[0, 1, ..., 18, 19]
-\end{verbatim}
-
-As the previous example shows, you can add \samp{...} 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:
-
-\begin{verbatim}
->>> print range(5) + range(10,20) + range(30,40) + range(50,60)
-... # doctest: +ELLIPSIS
-[0, ..., 4, 10, ..., 19, 30, ..., 39, 50, ..., 59]
-\end{verbatim}
-
-Note that since all options are disabled by default, and directives apply
-only to the example they appear in, enabling options (via \code{+} 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 \code{-} in a directive
-can be useful.
-
-\versionchanged[Constants \constant{DONT_ACCEPT_BLANKLINE},
- \constant{NORMALIZE_WHITESPACE}, \constant{ELLIPSIS},
- \constant{IGNORE_EXCEPTION_DETAIL},
- \constant{REPORT_UDIFF}, \constant{REPORT_CDIFF},
- \constant{REPORT_NDIFF}, \constant{REPORT_ONLY_FIRST_FAILURE},
- \constant{COMPARISON_FLAGS} and \constant{REPORTING_FLAGS}
- were added; by default \code{<BLANKLINE>} in expected output
- matches an empty line in actual output; and doctest directives
- were added]{2.4}
-\versionchanged[Constant \constant{SKIP} was added]{2.5}
-
-There's also a way to register new option flag names, although this
-isn't useful unless you intend to extend \refmodule{doctest} internals
-via subclassing:
-
-\begin{funcdesc}{register_optionflag}{name}
- Create a new option flag with a given name, and return the new
- flag's integer value. \function{register_optionflag()} can be
- used when subclassing \class{OutputChecker} or
- \class{DocTestRunner} to create new options that are supported by
- your subclasses. \function{register_optionflag} should always be
- called using the following idiom:
-
-\begin{verbatim}
- MY_FLAG = register_optionflag('MY_FLAG')
-\end{verbatim}
-
- \versionadded{2.4}
-\end{funcdesc}
-
-\subsubsection{Warnings\label{doctest-warnings}}
-
-\refmodule{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!
-\begin{verbatim}
->>> foo()
-{"Hermione": "hippogryph", "Harry": "broomstick"}
-\end{verbatim}
-
-is vulnerable! One workaround is to do
-
-\begin{verbatim}
->>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
-True
-\end{verbatim}
-
-instead. Another is to do
-
-\begin{verbatim}
->>> d = foo().items()
->>> d.sort()
->>> d
-[('Harry', 'broomstick'), ('Hermione', 'hippogryph')]
-\end{verbatim}
-
-There are others, but you get the idea.
-
-Another bad idea is to print things that embed an object address, like
-
-\begin{verbatim}
->>> 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>
-\end{verbatim}
-
-The \constant{ELLIPSIS} directive gives a nice approach for the last
-example:
-
-\begin{verbatim}
->>> C() #doctest: +ELLIPSIS
-<__main__.C instance at 0x...>
-\end{verbatim}
-
-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.
-
-\begin{verbatim}
->>> 1./7 # risky
-0.14285714285714285
->>> print 1./7 # safer
-0.142857142857
->>> print round(1./7, 6) # much safer
-0.142857
-\end{verbatim}
-
-Numbers of the form \code{I/2.**J} are safe across all platforms, and I
-often contrive doctest examples to produce numbers of that form:
-
-\begin{verbatim}
->>> 3./4 # utterly safe
-0.75
-\end{verbatim}
-
-Simple fractions are also easier for people to understand, and that makes
-for better documentation.
-
-\subsection{Basic API\label{doctest-basic-api}}
-
-The functions \function{testmod()} and \function{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}.
-
-\begin{funcdesc}{testfile}{filename\optional{, module_relative}\optional{,
- name}\optional{, package}\optional{,
- globs}\optional{, verbose}\optional{,
- report}\optional{, optionflags}\optional{,
- extraglobs}\optional{, raise_on_error}\optional{,
- parser}\optional{, encoding}}
-
- All arguments except \var{filename} are optional, and should be
- specified in keyword form.
-
- Test examples in the file named \var{filename}. Return
- \samp{(\var{failure_count}, \var{test_count})}.
-
- Optional argument \var{module_relative} specifies how the filename
- should be interpreted:
-
- \begin{itemize}
- \item If \var{module_relative} is \code{True} (the default), then
- \var{filename} specifies an OS-independent module-relative
- path. By default, this path is relative to the calling
- module's directory; but if the \var{package} argument is
- specified, then it is relative to that package. To ensure
- OS-independence, \var{filename} should use \code{/} characters
- to separate path segments, and may not be an absolute path
- (i.e., it may not begin with \code{/}).
- \item If \var{module_relative} is \code{False}, then \var{filename}
- specifies an OS-specific path. The path may be absolute or
- relative; relative paths are resolved with respect to the
- current working directory.
- \end{itemize}
-
- Optional argument \var{name} gives the name of the test; by default,
- or if \code{None}, \code{os.path.basename(\var{filename})} is used.
-
- Optional argument \var{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 \var{package}
- if \var{module_relative} is \code{False}.
-
- Optional argument \var{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 \code{None}, a new empty dict is used.
-
- Optional argument \var{extraglobs} gives a dict merged into the
- globals used to execute examples. This works like
- \method{dict.update()}: if \var{globs} and \var{extraglobs} have a
- common key, the associated value in \var{extraglobs} appears in the
- combined dict. By default, or if \code{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 \var{extraglobs} dict mapping the generic
- name to the subclass to be tested.
-
- Optional argument \var{verbose} prints lots of stuff if true, and prints
- only failures if false; by default, or if \code{None}, it's true
- if and only if \code{'-v'} is in \code{sys.argv}.
-
- Optional argument \var{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 \var{optionflags} or's together option flags. See
- section~\ref{doctest-options}.
-
- Optional argument \var{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 \var{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., \code{\class{DocTestParser}()}).
-
- Optional argument \var{encoding} specifies an encoding that should
- be used to convert the file to unicode.
-
- \versionadded{2.4}
-
- \versionchanged[The parameter \var{encoding} was added]{2.5}
-
-\end{funcdesc}
-
-\begin{funcdesc}{testmod}{\optional{m}\optional{, name}\optional{,
- globs}\optional{, verbose}\optional{,
- report}\optional{,
- optionflags}\optional{, extraglobs}\optional{,
- raise_on_error}\optional{, exclude_empty}}
-
- All arguments are optional, and all except for \var{m} should be
- specified in keyword form.
-
- Test examples in docstrings in functions and classes reachable
- from module \var{m} (or module \module{__main__} if \var{m} is not
- supplied or is \code{None}), starting with \code{\var{m}.__doc__}.
-
- Also test examples reachable from dict \code{\var{m}.__test__}, if it
- exists and is not \code{None}. \code{\var{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 \var{m} are
- searched.
-
- Return \samp{(\var{failure_count}, \var{test_count})}.
-
- Optional argument \var{name} gives the name of the module; by default,
- or if \code{None}, \code{\var{m}.__name__} is used.
-
- Optional argument \var{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 \method{doctest.master.summarize()} in conjunction with
- \function{testmod()} continues to get output for objects with no tests.
- The \var{exclude_empty} argument to the newer \class{DocTestFinder}
- constructor defaults to true.
-
- Optional arguments \var{extraglobs}, \var{verbose}, \var{report},
- \var{optionflags}, \var{raise_on_error}, and \var{globs} are the same as
- for function \function{testfile()} above, except that \var{globs}
- defaults to \code{\var{m}.__dict__}.
-
- \versionchanged[The parameter \var{optionflags} was added]{2.3}
-
- \versionchanged[The parameters \var{extraglobs}, \var{raise_on_error}
- and \var{exclude_empty} were added]{2.4}
-
- \versionchanged[The optional argument \var{isprivate}, deprecated
- in 2.4, was removed]{2.5}
-
-\end{funcdesc}
-
-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:
-
-\begin{funcdesc}{run_docstring_examples}{f, globs\optional{,
- verbose}\optional{, name}\optional{,
- compileflags}\optional{, optionflags}}
-
- Test examples associated with object \var{f}; for example, \var{f} may
- be a module, function, or class object.
-
- A shallow copy of dictionary argument \var{globs} is used for the
- execution context.
-
- Optional argument \var{name} is used in failure messages, and defaults
- to \code{"NoName"}.
-
- If optional argument \var{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 \var{compileflags} gives the set of flags that should
- be used by the Python compiler when running the examples. By default, or
- if \code{None}, flags are deduced corresponding to the set of future
- features found in \var{globs}.
-
- Optional argument \var{optionflags} works as for function
- \function{testfile()} above.
-\end{funcdesc}
-
-\subsection{Unittest API\label{doctest-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, \refmodule{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
-\refmodule{unittest} module, which supplies many flexible ways to combine
-tests from multiple sources. So, in Python 2.4, \refmodule{doctest}'s
-\class{Tester} class is deprecated, and \refmodule{doctest} provides two
-functions that can be used to create \refmodule{unittest} test suites from
-modules and text files containing doctests. These test suites can then be
-run using \refmodule{unittest} test runners:
-
-\begin{verbatim}
-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)
-\end{verbatim}
-
-There are two main functions for creating \class{\refmodule{unittest}.TestSuite}
-instances from text files and modules with doctests:
-
-\begin{funcdesc}{DocFileSuite}{\optional{module_relative}\optional{,
- package}\optional{, setUp}\optional{,
- tearDown}\optional{, globs}\optional{,
- optionflags}\optional{, parser}\optional{,
- encoding}}
-
- Convert doctest tests from one or more text files to a
- \class{\refmodule{unittest}.TestSuite}.
-
- The returned \class{\refmodule{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
- \exception{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 \var{module_relative} specifies how
- the filenames in \var{paths} should be interpreted:
-
- \begin{itemize}
- \item If \var{module_relative} is \code{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 \var{package} argument is
- specified, then it is relative to that package. To ensure
- OS-independence, each filename should use \code{/} characters
- to separate path segments, and may not be an absolute path
- (i.e., it may not begin with \code{/}).
- \item If \var{module_relative} is \code{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.
- \end{itemize}
-
- Optional argument \var{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
- \var{package} if \var{module_relative} is \code{False}.
-
- Optional argument \var{setUp} specifies a set-up function for
- the test suite. This is called before running the tests in each
- file. The \var{setUp} function will be passed a \class{DocTest}
- object. The setUp function can access the test globals as the
- \var{globs} attribute of the test passed.
-
- Optional argument \var{tearDown} specifies a tear-down function
- for the test suite. This is called after running the tests in each
- file. The \var{tearDown} function will be passed a \class{DocTest}
- object. The setUp function can access the test globals as the
- \var{globs} attribute of the test passed.
-
- Optional argument \var{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, \var{globs} is
- a new empty dictionary.
-
- Optional argument \var{optionflags} specifies the default
- doctest options for the tests, created by or-ing together
- individual option flags. See section~\ref{doctest-options}.
- See function \function{set_unittest_reportflags()} below for
- a better way to set reporting options.
-
- Optional argument \var{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., \code{\class{DocTestParser}()}).
-
- Optional argument \var{encoding} specifies an encoding that should
- be used to convert the file to unicode.
-
- \versionadded{2.4}
-
- \versionchanged[The global \code{__file__} was added to the
- globals provided to doctests loaded from a text file using
- \function{DocFileSuite()}]{2.5}
-
- \versionchanged[The parameter \var{encoding} was added]{2.5}
-
-\end{funcdesc}
-
-\begin{funcdesc}{DocTestSuite}{\optional{module}\optional{,
- globs}\optional{, extraglobs}\optional{,
- test_finder}\optional{, setUp}\optional{,
- tearDown}\optional{, checker}}
- Convert doctest tests for a module to a
- \class{\refmodule{unittest}.TestSuite}.
-
- The returned \class{\refmodule{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
- \exception{failureException} exception is raised showing the name of the
- file containing the test and a (sometimes approximate) line number.
-
- Optional argument \var{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 \var{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, \var{globs} is
- a new empty dictionary.
-
- Optional argument \var{extraglobs} specifies an extra set of
- global variables, which is merged into \var{globs}. By default, no
- extra globals are used.
-
- Optional argument \var{test_finder} is the \class{DocTestFinder}
- object (or a drop-in replacement) that is used to extract doctests
- from the module.
-
- Optional arguments \var{setUp}, \var{tearDown}, and \var{optionflags}
- are the same as for function \function{DocFileSuite()} above.
-
- \versionadded{2.3}
-
- \versionchanged[The parameters \var{globs}, \var{extraglobs},
- \var{test_finder}, \var{setUp}, \var{tearDown}, and
- \var{optionflags} were added; this function now uses the same search
- technique as \function{testmod()}]{2.4}
-\end{funcdesc}
-
-Under the covers, \function{DocTestSuite()} creates a
-\class{\refmodule{unittest}.TestSuite} out of \class{doctest.DocTestCase}
-instances, and \class{DocTestCase} is a subclass of
-\class{\refmodule{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 \refmodule{unittest} integration.
-
-Similarly, \function{DocFileSuite()} creates a
-\class{\refmodule{unittest}.TestSuite} out of \class{doctest.DocFileCase}
-instances, and \class{DocFileCase} is a subclass of \class{DocTestCase}.
-
-So both ways of creating a \class{\refmodule{unittest}.TestSuite} run
-instances of \class{DocTestCase}. This is important for a subtle reason:
-when you run \refmodule{doctest} functions yourself, you can control the
-\refmodule{doctest} options in use directly, by passing option flags to
-\refmodule{doctest} functions. However, if you're writing a
-\refmodule{unittest} framework, \refmodule{unittest} ultimately controls
-when and how tests get run. The framework author typically wants to
-control \refmodule{doctest} reporting options (perhaps, e.g., specified by
-command line options), but there's no way to pass options through
-\refmodule{unittest} to \refmodule{doctest} test runners.
-
-For this reason, \refmodule{doctest} also supports a notion of
-\refmodule{doctest} reporting flags specific to \refmodule{unittest}
-support, via this function:
-
-\begin{funcdesc}{set_unittest_reportflags}{flags}
- Set the \refmodule{doctest} reporting flags to use.
-
- Argument \var{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 \refmodule{unittest}: the \method{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),
- \refmodule{doctest}'s \refmodule{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, \refmodule{doctest}'s \refmodule{unittest} reporting flags
- are ignored.
-
- The value of the \refmodule{unittest} reporting flags in effect before the
- function was called is returned by the function.
-
- \versionadded{2.4}
-\end{funcdesc}
-
-
-\subsection{Advanced API\label{doctest-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:
-
-\begin{itemize}
-\item \class{Example}: A single python statement, paired with its
- expected output.
-\item \class{DocTest}: A collection of \class{Example}s, typically
- extracted from a single docstring or text file.
-\end{itemize}
-
-Additional processing classes are defined to find, parse, and run, and
-check doctest examples:
-
-\begin{itemize}
-\item \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.
-\item \class{DocTestParser}: Creates a \class{DocTest} object from
- a string (such as an object's docstring).
-\item \class{DocTestRunner}: Executes the examples in a
- \class{DocTest}, and uses an \class{OutputChecker} to verify
- their output.
-\item \class{OutputChecker}: Compares the actual output from a
- doctest example with the expected output, and decides whether
- they match.
-\end{itemize}
-
-The relationships among these processing classes are summarized in the
-following diagram:
-
-\begin{verbatim}
- list of:
-+------+ +---------+
-|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
-+------+ | ^ +---------+ | ^ (printed)
- | | | Example | | |
- v | | ... | v |
- DocTestParser | Example | OutputChecker
- +---------+
-\end{verbatim}
-
-\subsubsection{DocTest Objects\label{doctest-DocTest}}
-\begin{classdesc}{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}
-\end{classdesc}
-
-\class{DocTest} defines the following member variables. They are
-initialized by the constructor, and should not be modified directly.
-
-\begin{memberdesc}{examples}
- A list of \class{Example} objects encoding the individual
- interactive Python examples that should be run by this test.
-\end{memberdesc}
-
-\begin{memberdesc}{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 \member{globs} after the test is run.
-\end{memberdesc}
-
-\begin{memberdesc}{name}
- A string name identifying the \class{DocTest}. Typically, this is
- the name of the object or file that the test was extracted from.
-\end{memberdesc}
-
-\begin{memberdesc}{filename}
- The name of the file that this \class{DocTest} was extracted from;
- or \code{None} if the filename is unknown, or if the
- \class{DocTest} was not extracted from a file.
-\end{memberdesc}
-
-\begin{memberdesc}{lineno}
- The line number within \member{filename} where this
- \class{DocTest} begins, or \code{None} if the line number is
- unavailable. This line number is zero-based with respect to the
- beginning of the file.
-\end{memberdesc}
-
-\begin{memberdesc}{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.
-\end{memberdesc}
-
-\subsubsection{Example Objects\label{doctest-Example}}
-\begin{classdesc}{Example}{source, want\optional{,
- exc_msg}\optional{, lineno}\optional{,
- indent}\optional{, 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}
-\end{classdesc}
-
-\class{Example} defines the following member variables. They are
-initialized by the constructor, and should not be modified directly.
-
-\begin{memberdesc}{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.
-\end{memberdesc}
-
-\begin{memberdesc}{want}
- The expected output from running the example's source code (either
- from stdout, or a traceback in case of exception). \member{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.
-\end{memberdesc}
-
-\begin{memberdesc}{exc_msg}
- The exception message generated by the example, if the example is
- expected to generate an exception; or \code{None} if it is not
- expected to generate an exception. This exception message is
- compared against the return value of
- \function{traceback.format_exception_only()}. \member{exc_msg}
- ends with a newline unless it's \code{None}. The constructor adds
- a newline if needed.
-\end{memberdesc}
-
-\begin{memberdesc}{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.
-\end{memberdesc}
-
-\begin{memberdesc}{indent}
- The example's indentation in the containing string, i.e., the
- number of space characters that precede the example's first
- prompt.
-\end{memberdesc}
-
-\begin{memberdesc}{options}
- A dictionary mapping from option flags to \code{True} or
- \code{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 \member{optionflags}).
- By default, no options are set.
-\end{memberdesc}
-
-\subsubsection{DocTestFinder objects\label{doctest-DocTestFinder}}
-\begin{classdesc}{DocTestFinder}{\optional{verbose}\optional{,
- parser}\optional{, recurse}\optional{,
- 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 \var{verbose} can be used to display the
- objects searched by the finder. It defaults to \code{False} (no
- output).
-
- The optional argument \var{parser} specifies the
- \class{DocTestParser} object (or a drop-in replacement) that is
- used to extract doctests from docstrings.
-
- If the optional argument \var{recurse} is false, then
- \method{DocTestFinder.find()} will only examine the given object,
- and not any contained objects.
-
- If the optional argument \var{exclude_empty} is false, then
- \method{DocTestFinder.find()} will include tests for objects with
- empty docstrings.
-
- \versionadded{2.4}
-\end{classdesc}
-
-\class{DocTestFinder} defines the following method:
-
-\begin{methoddesc}{find}{obj\optional{, name}\optional{,
- module}\optional{, globs}\optional{, extraglobs}}
- Return a list of the \class{DocTest}s that are defined by
- \var{obj}'s docstring, or by any of its contained objects'
- docstrings.
-
- The optional argument \var{name} specifies the object's name; this
- name will be used to construct names for the returned
- \class{DocTest}s. If \var{name} is not specified, then
- \code{\var{obj}.__name__} is used.
-
- The optional parameter \var{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:
-
- \begin{itemize}
- \item As a default namespace, if \var{globs} is not specified.
- \item To prevent the DocTestFinder from extracting DocTests
- from objects that are imported from other modules. (Contained
- objects with modules other than \var{module} are ignored.)
- \item To find the name of the file containing the object.
- \item To help find the line number of the object within its file.
- \end{itemize}
-
- If \var{module} is \code{False}, no attempt to find the module
- will be made. This is obscure, of use mostly in testing doctest
- itself: if \var{module} is \code{False}, or is \code{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
- \var{globs} and \var{extraglobs} (bindings in \var{extraglobs}
- override bindings in \var{globs}). A new shallow copy of the globals
- dictionary is created for each \class{DocTest}. If \var{globs} is
- not specified, then it defaults to the module's \var{__dict__}, if
- specified, or \code{\{\}} otherwise. If \var{extraglobs} is not
- specified, then it defaults to \code{\{\}}.
-\end{methoddesc}
-
-\subsubsection{DocTestParser objects\label{doctest-DocTestParser}}
-\begin{classdesc}{DocTestParser}{}
- A processing class used to extract interactive examples from a
- string, and use them to create a \class{DocTest} object.
- \versionadded{2.4}
-\end{classdesc}
-
-\class{DocTestParser} defines the following methods:
-
-\begin{methoddesc}{get_doctest}{string, globs, name, filename, lineno}
- Extract all doctest examples from the given string, and collect
- them into a \class{DocTest} object.
-
- \var{globs}, \var{name}, \var{filename}, and \var{lineno} are
- attributes for the new \class{DocTest} object. See the
- documentation for \class{DocTest} for more information.
-\end{methoddesc}
-
-\begin{methoddesc}{get_examples}{string\optional{, 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 \var{name} is a name identifying
- this string, and is only used for error messages.
-\end{methoddesc}
-
-\begin{methoddesc}{parse}{string\optional{, 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 \var{name} is a name identifying this string, and is only
- used for error messages.
-\end{methoddesc}
-
-\subsubsection{DocTestRunner objects\label{doctest-DocTestRunner}}
-\begin{classdesc}{DocTestRunner}{\optional{checker}\optional{,
- verbose}\optional{, 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
- \method{TestRunner.run()}; this function will be called with
- strings that should be displayed. It defaults to
- \code{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
- \method{report_start}, \method{report_success},
- \method{report_unexpected_exception}, and \method{report_failure}.
-
- The optional keyword argument \var{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 \var{verbose} controls the
- \class{DocTestRunner}'s verbosity. If \var{verbose} is
- \code{True}, then information is printed about each example, as it
- is run. If \var{verbose} is \code{False}, then only failures are
- printed. If \var{verbose} is unspecified, or \code{None}, then
- verbose output is used iff the command-line switch \programopt{-v}
- is used.
-
- The optional keyword argument \var{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}
-\end{classdesc}
-
-\class{DocTestParser} defines the following methods:
-
-\begin{methoddesc}{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.
-
- \var{example} is the example about to be processed. \var{test} is
- the test containing \var{example}. \var{out} is the output
- function that was passed to \method{DocTestRunner.run()}.
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-
- \var{example} is the example about to be processed. \var{got} is
- the actual output from the example. \var{test} is the test
- containing \var{example}. \var{out} is the output function that
- was passed to \method{DocTestRunner.run()}.
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-
- \var{example} is the example about to be processed. \var{got} is
- the actual output from the example. \var{test} is the test
- containing \var{example}. \var{out} is the output function that
- was passed to \method{DocTestRunner.run()}.
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-
- \var{example} is the example about to be processed.
- \var{exc_info} is a tuple containing information about the
- unexpected exception (as returned by \function{sys.exc_info()}).
- \var{test} is the test containing \var{example}. \var{out} is the
- output function that was passed to \method{DocTestRunner.run()}.
-\end{methoddesc}
-
-\begin{methoddesc}{run}{test\optional{, compileflags}\optional{,
- out}\optional{, clear_globs}}
- Run the examples in \var{test} (a \class{DocTest} object), and
- display the results using the writer function \var{out}.
-
- The examples are run in the namespace \code{test.globs}. If
- \var{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 \var{clear_globs=False}.
-
- \var{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 \var{globs}.
-
- The output of each example is checked using the
- \class{DocTestRunner}'s output checker, and the results are
- formatted by the \method{DocTestRunner.report_*} methods.
-\end{methoddesc}
-
-\begin{methoddesc}{summarize}{\optional{verbose}}
- Print a summary of all the test cases that have been run by this
- DocTestRunner, and return a tuple \samp{(\var{failure_count},
- \var{test_count})}.
-
- The optional \var{verbose} argument controls how detailed the
- summary is. If the verbosity is not specified, then the
- \class{DocTestRunner}'s verbosity is used.
-\end{methoddesc}
-
-\subsubsection{OutputChecker objects\label{doctest-OutputChecker}}
-
-\begin{classdesc}{OutputChecker}{}
- A class used to check the whether the actual output from a doctest
- example matches the expected output. \class{OutputChecker}
- defines two methods: \method{check_output}, which compares a given
- pair of outputs, and returns true if they match; and
- \method{output_difference}, which returns a string describing the
- differences between two outputs.
- \versionadded{2.4}
-\end{classdesc}
-
-\class{OutputChecker} defines the following methods:
-
-\begin{methoddesc}{check_output}{want, got, optionflags}
- Return \code{True} iff the actual output from an example
- (\var{got}) matches the expected output (\var{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.
-\end{methoddesc}
-
-\begin{methoddesc}{output_difference}{example, got, optionflags}
- Return a string describing the differences between the expected
- output for a given example (\var{example}) and the actual output
- (\var{got}). \var{optionflags} is the set of option flags used to
- compare \var{want} and \var{got}.
-\end{methoddesc}
-
-\subsection{Debugging\label{doctest-debugging}}
-
-Doctest provides several mechanisms for debugging doctest examples:
-
-\begin{itemize}
-\item Several functions convert doctests to executable Python
- programs, which can be run under the Python debugger, \refmodule{pdb}.
-\item 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.
-\item The \refmodule{unittest} cases generated by \function{DocTestSuite()}
- support the \method{debug()} method defined by
- \class{\refmodule{unittest}.TestCase}.
-\item You can add a call to \function{\refmodule{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:
-
-\begin{verbatim}
-"""
->>> def f(x):
-... g(x*2)
->>> def g(x):
-... print x+3
-... import pdb; pdb.set_trace()
->>> f(3)
-9
-"""
-\end{verbatim}
-
- Then an interactive Python session may look like this:
-
-\begin{verbatim}
->>> 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)
->>>
-\end{verbatim}
-
- \versionchanged[The ability to use \function{\refmodule{pdb}.set_trace()}
- usefully inside doctests was added]{2.4}
-\end{itemize}
-
-Functions that convert doctests to Python code, and possibly run
-the synthesized code under the debugger:
-
-\begin{funcdesc}{script_from_examples}{s}
- Convert text with examples to a script.
-
- Argument \var{s} is a string containing doctest examples. The string
- is converted to a Python script, where doctest examples in \var{s}
- are converted to regular code, and everything else is converted to
- Python comments. The generated script is returned as a string.
- For example,
-
- \begin{verbatim}
- 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
- """)
- \end{verbatim}
-
- displays:
-
- \begin{verbatim}
- # Set x and y to 1 and 2.
- x, y = 1, 2
- #
- # Print their sum:
- print x+y
- # Expected:
- ## 3
- \end{verbatim}
-
- 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}
-\end{funcdesc}
-
-\begin{funcdesc}{testsource}{module, name}
- Convert the doctest for an object to a script.
-
- Argument \var{module} is a module object, or dotted name of a module,
- containing the object whose doctests are of interest. Argument
- \var{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
- \function{script_from_examples()} above. For example, if module
- \file{a.py} contains a top-level function \function{f()}, then
-
-\begin{verbatim}
-import a, doctest
-print doctest.testsource(a, "a.f")
-\end{verbatim}
-
- prints a script version of function \function{f()}'s docstring,
- with doctests converted to code, and the rest placed in comments.
-
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{debug}{module, name\optional{, pm}}
- Debug the doctests for an object.
-
- The \var{module} and \var{name} arguments are the same as for function
- \function{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, \refmodule{pdb}.
-
- A shallow copy of \code{\var{module}.__dict__} is used for both local
- and global execution context.
-
- Optional argument \var{pm} controls whether post-mortem debugging is
- used. If \var{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 \function{\refmodule{pdb}.post_mortem()}, passing the traceback object
- from the unhandled exception. If \var{pm} is not specified, or is false,
- the script is run under the debugger from the start, via passing an
- appropriate \function{exec()} call to \function{\refmodule{pdb}.run()}.
-
- \versionadded{2.3}
-
- \versionchanged[The \var{pm} argument was added]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{debug_src}{src\optional{, pm}\optional{, globs}}
- Debug the doctests in a string.
-
- This is like function \function{debug()} above, except that
- a string containing doctest examples is specified directly, via
- the \var{src} argument.
-
- Optional argument \var{pm} has the same meaning as in function
- \function{debug()} above.
-
- Optional argument \var{globs} gives a dictionary to use as both
- local and global execution context. If not specified, or \code{None},
- an empty dictionary is used. If specified, a shallow copy of the
- dictionary is used.
-
- \versionadded{2.4}
-\end{funcdesc}
-
-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:
-
-\begin{classdesc}{DebugRunner}{\optional{checker}\optional{,
- verbose}\optional{, optionflags}}
-
- A subclass of \class{DocTestRunner} that raises an exception as
- soon as a failure is encountered. If an unexpected exception
- occurs, an \exception{UnexpectedException} exception is raised,
- containing the test, the example, and the original exception. If
- the output doesn't match, then a \exception{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}.
-\end{classdesc}
-
-There are two exceptions that may be raised by \class{DebugRunner}
-instances:
-
-\begin{excclassdesc}{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.
-\end{excclassdesc}
-\exception{DocTestFailure} defines the following member variables:
-\begin{memberdesc}{test}
- The \class{DocTest} object that was being run when the example failed.
-\end{memberdesc}
-\begin{memberdesc}{example}
- The \class{Example} that failed.
-\end{memberdesc}
-\begin{memberdesc}{got}
- The example's actual output.
-\end{memberdesc}
-
-\begin{excclassdesc}{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.
-\end{excclassdesc}
-\exception{UnexpectedException} defines the following member variables:
-\begin{memberdesc}{test}
- The \class{DocTest} object that was being run when the example failed.
-\end{memberdesc}
-\begin{memberdesc}{example}
- The \class{Example} that failed.
-\end{memberdesc}
-\begin{memberdesc}{exc_info}
- A tuple containing information about the unexpected exception, as
- returned by \function{sys.exc_info()}.
-\end{memberdesc}
-
-\subsection{Soapbox\label{doctest-soapbox}}
-
-As mentioned in the introduction, \refmodule{doctest} has grown to have
-three primary uses:
-
-\begin{enumerate}
-\item Checking examples in docstrings.
-\item Regression testing.
-\item Executable documentation / literate testing.
-\end{enumerate}
-
-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 \refmodule{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:
-
-\begin{itemize}
-\item Write text files containing test cases as interactive examples,
- and test the files using \function{testfile()} or
- \function{DocFileSuite()}. This is recommended, although is
- easiest to do for new projects, designed from the start to use
- doctest.
-\item Define functions named \code{_regrtest_\textit{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.
-\item Define a \code{__test__} dictionary mapping from regression test
- topics to docstrings containing test cases.
-\end{itemize}
diff --git a/Doc/lib/libdocxmlrpc.tex b/Doc/lib/libdocxmlrpc.tex
deleted file mode 100644
index f93b3b2..0000000
--- a/Doc/lib/libdocxmlrpc.tex
+++ /dev/null
@@ -1,109 +0,0 @@
-\section{\module{DocXMLRPCServer} ---
- Self-documenting XML-RPC server}
-
-\declaremodule{standard}{DocXMLRPCServer}
-\modulesynopsis{Self-documenting XML-RPC server implementation.}
-\moduleauthor{Brian Quinlan}{brianq@activestate.com}
-\sectionauthor{Brian Quinlan}{brianq@activestate.com}
-
-\versionadded{2.3}
-
-The \module{DocXMLRPCServer} module extends the classes found in
-\module{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}.
-
-\begin{classdesc}{DocXMLRPCServer}{addr\optional{,
- requestHandler\optional{,
- logRequests\optional{,
- allow_none\optional{,
- encoding\optional{,
- bind_and_activate}}}}}}
-
-Create a new server instance. All parameters have the same meaning as
-for \class{SimpleXMLRPCServer.SimpleXMLRPCServer};
-\var{requestHandler} defaults to \class{DocXMLRPCRequestHandler}.
-
-\end{classdesc}
-
-\begin{classdesc}{DocCGIXMLRPCRequestHandler}{}
-
-Create a new instance to handle XML-RPC requests in a CGI environment.
-
-\end{classdesc}
-
-\begin{classdesc}{DocXMLRPCRequestHandler}{}
-
-Create a new request handler instance. This request handler supports
-XML-RPC POST requests, documentation GET requests, and modifies
-logging so that the \var{logRequests} parameter to the
-\class{DocXMLRPCServer} constructor parameter is honored.
-
-\end{classdesc}
-
-\subsection{DocXMLRPCServer Objects \label{doc-xmlrpc-servers}}
-
-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.
-
-\begin{methoddesc}[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.
-
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-
-\end{methoddesc}
-
-
-\begin{methoddesc}[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.
-
-\end{methoddesc}
-
-\subsection{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.
-
-\begin{methoddesc}[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.
-
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-
-\end{methoddesc}
-
-
-\begin{methoddesc}[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.
-
-\end{methoddesc}
diff --git a/Doc/lib/libdumbdbm.tex b/Doc/lib/libdumbdbm.tex
deleted file mode 100644
index d0917be..0000000
--- a/Doc/lib/libdumbdbm.tex
+++ /dev/null
@@ -1,63 +0,0 @@
-\section{\module{dumbdbm} ---
- Portable DBM implementation}
-
-\declaremodule{standard}{dumbdbm}
-\modulesynopsis{Portable implementation of the simple DBM interface.}
-
-\index{databases}
-
-\begin{notice}
-The \module{dumbdbm} module is intended as a last resort fallback for
-the \refmodule{anydbm} module when no more robust module is available.
-The \module{dumbdbm} module is not written for speed and is not nearly as
-heavily used as the other database modules.
-\end{notice}
-
-The \module{dumbdbm} module provides a persistent dictionary-like interface
-which is written entirely in Python. Unlike other modules such as
-\refmodule{gdbm} and \refmodule{bsddb}, no external library is required. As
-with other persistent mappings, the keys and values must always be strings.
-
-The module defines the following:
-
-\begin{excdesc}{error}
-Raised on dumbdbm-specific errors, such as I/O errors. \exception{KeyError}
-is raised for general mapping errors like specifying an incorrect key.
-\end{excdesc}
-
-\begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}}
-Open a dumbdbm database and return a dumbdbm object. The \var{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 \var{flag} argument is currently ignored; the database is
-always opened for update, and will be created if it does not exist.
-
-The optional \var{mode} argument is the \UNIX{} mode of the file, used
-only when the database has to be created. It defaults to octal
-\code{0666} (and will be modified by the prevailing umask).
-\versionchanged[The \var{mode} argument was ignored in earlier
- versions]{2.2}
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
- \seemodule{dbm}{Similar interface to the DBM/NDBM library.}
- \seemodule{gdbm}{Similar interface to the GNU GDBM library.}
- \seemodule{shelve}{Persistence module which stores non-string data.}
- \seemodule{whichdb}{Utility module used to determine the type of an
- existing database.}
-\end{seealso}
-
-
-\subsection{Dumbdbm Objects \label{dumbdbm-objects}}
-
-In addition to the methods provided by the \class{UserDict.DictMixin} class,
-\class{dumbdbm} objects provide the following methods.
-
-\begin{methoddesc}[dumbdbm]{sync}{}
-Synchronize the on-disk directory and data files. This method is called by
-the \method{sync} method of \class{Shelve} objects.
-\end{methoddesc}
diff --git a/Doc/lib/libdummythread.tex b/Doc/lib/libdummythread.tex
deleted file mode 100644
index f6b4c56..0000000
--- a/Doc/lib/libdummythread.tex
+++ /dev/null
@@ -1,22 +0,0 @@
-\section{\module{dummy_thread} ---
- Drop-in replacement for the \module{thread} module}
-
-\declaremodule[dummythread]{standard}{dummy_thread}
-\modulesynopsis{Drop-in replacement for the \refmodule{thread} module.}
-
-This module provides a duplicate interface to the \refmodule{thread}
-module. It is meant to be imported when the \refmodule{thread} module
-is not provided on a platform.
-
-Suggested usage is:
-
-\begin{verbatim}
-try:
- import thread as _thread
-except ImportError:
- import dummy_thread as _thread
-\end{verbatim}
-
-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.
diff --git a/Doc/lib/libdummythreading.tex b/Doc/lib/libdummythreading.tex
deleted file mode 100644
index 874f596..0000000
--- a/Doc/lib/libdummythreading.tex
+++ /dev/null
@@ -1,22 +0,0 @@
-\section{\module{dummy_threading} ---
- Drop-in replacement for the \module{threading} module}
-
-\declaremodule[dummythreading]{standard}{dummy_threading}
-\modulesynopsis{Drop-in replacement for the \refmodule{threading} module.}
-
-This module provides a duplicate interface to the
-\refmodule{threading} module. It is meant to be imported when the
-\refmodule{thread} module is not provided on a platform.
-
-Suggested usage is:
-
-\begin{verbatim}
-try:
- import threading as _threading
-except ImportError:
- import dummy_threading as _threading
-\end{verbatim}
-
-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.
diff --git a/Doc/lib/liberrno.tex b/Doc/lib/liberrno.tex
deleted file mode 100644
index c0ce6e8..0000000
--- a/Doc/lib/liberrno.tex
+++ /dev/null
@@ -1,149 +0,0 @@
-\section{\module{errno} ---
- Standard errno system symbols}
-
-\declaremodule{standard}{errno}
-\modulesynopsis{Standard errno system symbols.}
-
-
-This module makes available standard \code{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.
-
-\begin{datadesc}{errorcode}
- Dictionary providing a mapping from the errno value to the string
- name in the underlying system. For instance,
- \code{errno.errorcode[errno.EPERM]} maps to \code{'EPERM'}.
-\end{datadesc}
-
-To translate a numeric error code to an error message, use
-\function{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 \code{errno.errorcode.keys()}. Symbols
-available can include:
-
-\begin{datadesc}{EPERM} Operation not permitted \end{datadesc}
-\begin{datadesc}{ENOENT} No such file or directory \end{datadesc}
-\begin{datadesc}{ESRCH} No such process \end{datadesc}
-\begin{datadesc}{EINTR} Interrupted system call \end{datadesc}
-\begin{datadesc}{EIO} I/O error \end{datadesc}
-\begin{datadesc}{ENXIO} No such device or address \end{datadesc}
-\begin{datadesc}{E2BIG} Arg list too long \end{datadesc}
-\begin{datadesc}{ENOEXEC} Exec format error \end{datadesc}
-\begin{datadesc}{EBADF} Bad file number \end{datadesc}
-\begin{datadesc}{ECHILD} No child processes \end{datadesc}
-\begin{datadesc}{EAGAIN} Try again \end{datadesc}
-\begin{datadesc}{ENOMEM} Out of memory \end{datadesc}
-\begin{datadesc}{EACCES} Permission denied \end{datadesc}
-\begin{datadesc}{EFAULT} Bad address \end{datadesc}
-\begin{datadesc}{ENOTBLK} Block device required \end{datadesc}
-\begin{datadesc}{EBUSY} Device or resource busy \end{datadesc}
-\begin{datadesc}{EEXIST} File exists \end{datadesc}
-\begin{datadesc}{EXDEV} Cross-device link \end{datadesc}
-\begin{datadesc}{ENODEV} No such device \end{datadesc}
-\begin{datadesc}{ENOTDIR} Not a directory \end{datadesc}
-\begin{datadesc}{EISDIR} Is a directory \end{datadesc}
-\begin{datadesc}{EINVAL} Invalid argument \end{datadesc}
-\begin{datadesc}{ENFILE} File table overflow \end{datadesc}
-\begin{datadesc}{EMFILE} Too many open files \end{datadesc}
-\begin{datadesc}{ENOTTY} Not a typewriter \end{datadesc}
-\begin{datadesc}{ETXTBSY} Text file busy \end{datadesc}
-\begin{datadesc}{EFBIG} File too large \end{datadesc}
-\begin{datadesc}{ENOSPC} No space left on device \end{datadesc}
-\begin{datadesc}{ESPIPE} Illegal seek \end{datadesc}
-\begin{datadesc}{EROFS} Read-only file system \end{datadesc}
-\begin{datadesc}{EMLINK} Too many links \end{datadesc}
-\begin{datadesc}{EPIPE} Broken pipe \end{datadesc}
-\begin{datadesc}{EDOM} Math argument out of domain of func \end{datadesc}
-\begin{datadesc}{ERANGE} Math result not representable \end{datadesc}
-\begin{datadesc}{EDEADLK} Resource deadlock would occur \end{datadesc}
-\begin{datadesc}{ENAMETOOLONG} File name too long \end{datadesc}
-\begin{datadesc}{ENOLCK} No record locks available \end{datadesc}
-\begin{datadesc}{ENOSYS} Function not implemented \end{datadesc}
-\begin{datadesc}{ENOTEMPTY} Directory not empty \end{datadesc}
-\begin{datadesc}{ELOOP} Too many symbolic links encountered \end{datadesc}
-\begin{datadesc}{EWOULDBLOCK} Operation would block \end{datadesc}
-\begin{datadesc}{ENOMSG} No message of desired type \end{datadesc}
-\begin{datadesc}{EIDRM} Identifier removed \end{datadesc}
-\begin{datadesc}{ECHRNG} Channel number out of range \end{datadesc}
-\begin{datadesc}{EL2NSYNC} Level 2 not synchronized \end{datadesc}
-\begin{datadesc}{EL3HLT} Level 3 halted \end{datadesc}
-\begin{datadesc}{EL3RST} Level 3 reset \end{datadesc}
-\begin{datadesc}{ELNRNG} Link number out of range \end{datadesc}
-\begin{datadesc}{EUNATCH} Protocol driver not attached \end{datadesc}
-\begin{datadesc}{ENOCSI} No CSI structure available \end{datadesc}
-\begin{datadesc}{EL2HLT} Level 2 halted \end{datadesc}
-\begin{datadesc}{EBADE} Invalid exchange \end{datadesc}
-\begin{datadesc}{EBADR} Invalid request descriptor \end{datadesc}
-\begin{datadesc}{EXFULL} Exchange full \end{datadesc}
-\begin{datadesc}{ENOANO} No anode \end{datadesc}
-\begin{datadesc}{EBADRQC} Invalid request code \end{datadesc}
-\begin{datadesc}{EBADSLT} Invalid slot \end{datadesc}
-\begin{datadesc}{EDEADLOCK} File locking deadlock error \end{datadesc}
-\begin{datadesc}{EBFONT} Bad font file format \end{datadesc}
-\begin{datadesc}{ENOSTR} Device not a stream \end{datadesc}
-\begin{datadesc}{ENODATA} No data available \end{datadesc}
-\begin{datadesc}{ETIME} Timer expired \end{datadesc}
-\begin{datadesc}{ENOSR} Out of streams resources \end{datadesc}
-\begin{datadesc}{ENONET} Machine is not on the network \end{datadesc}
-\begin{datadesc}{ENOPKG} Package not installed \end{datadesc}
-\begin{datadesc}{EREMOTE} Object is remote \end{datadesc}
-\begin{datadesc}{ENOLINK} Link has been severed \end{datadesc}
-\begin{datadesc}{EADV} Advertise error \end{datadesc}
-\begin{datadesc}{ESRMNT} Srmount error \end{datadesc}
-\begin{datadesc}{ECOMM} Communication error on send \end{datadesc}
-\begin{datadesc}{EPROTO} Protocol error \end{datadesc}
-\begin{datadesc}{EMULTIHOP} Multihop attempted \end{datadesc}
-\begin{datadesc}{EDOTDOT} RFS specific error \end{datadesc}
-\begin{datadesc}{EBADMSG} Not a data message \end{datadesc}
-\begin{datadesc}{EOVERFLOW} Value too large for defined data type \end{datadesc}
-\begin{datadesc}{ENOTUNIQ} Name not unique on network \end{datadesc}
-\begin{datadesc}{EBADFD} File descriptor in bad state \end{datadesc}
-\begin{datadesc}{EREMCHG} Remote address changed \end{datadesc}
-\begin{datadesc}{ELIBACC} Can not access a needed shared library \end{datadesc}
-\begin{datadesc}{ELIBBAD} Accessing a corrupted shared library \end{datadesc}
-\begin{datadesc}{ELIBSCN} .lib section in a.out corrupted \end{datadesc}
-\begin{datadesc}{ELIBMAX} Attempting to link in too many shared libraries \end{datadesc}
-\begin{datadesc}{ELIBEXEC} Cannot exec a shared library directly \end{datadesc}
-\begin{datadesc}{EILSEQ} Illegal byte sequence \end{datadesc}
-\begin{datadesc}{ERESTART} Interrupted system call should be restarted \end{datadesc}
-\begin{datadesc}{ESTRPIPE} Streams pipe error \end{datadesc}
-\begin{datadesc}{EUSERS} Too many users \end{datadesc}
-\begin{datadesc}{ENOTSOCK} Socket operation on non-socket \end{datadesc}
-\begin{datadesc}{EDESTADDRREQ} Destination address required \end{datadesc}
-\begin{datadesc}{EMSGSIZE} Message too long \end{datadesc}
-\begin{datadesc}{EPROTOTYPE} Protocol wrong type for socket \end{datadesc}
-\begin{datadesc}{ENOPROTOOPT} Protocol not available \end{datadesc}
-\begin{datadesc}{EPROTONOSUPPORT} Protocol not supported \end{datadesc}
-\begin{datadesc}{ESOCKTNOSUPPORT} Socket type not supported \end{datadesc}
-\begin{datadesc}{EOPNOTSUPP} Operation not supported on transport endpoint \end{datadesc}
-\begin{datadesc}{EPFNOSUPPORT} Protocol family not supported \end{datadesc}
-\begin{datadesc}{EAFNOSUPPORT} Address family not supported by protocol \end{datadesc}
-\begin{datadesc}{EADDRINUSE} Address already in use \end{datadesc}
-\begin{datadesc}{EADDRNOTAVAIL} Cannot assign requested address \end{datadesc}
-\begin{datadesc}{ENETDOWN} Network is down \end{datadesc}
-\begin{datadesc}{ENETUNREACH} Network is unreachable \end{datadesc}
-\begin{datadesc}{ENETRESET} Network dropped connection because of reset \end{datadesc}
-\begin{datadesc}{ECONNABORTED} Software caused connection abort \end{datadesc}
-\begin{datadesc}{ECONNRESET} Connection reset by peer \end{datadesc}
-\begin{datadesc}{ENOBUFS} No buffer space available \end{datadesc}
-\begin{datadesc}{EISCONN} Transport endpoint is already connected \end{datadesc}
-\begin{datadesc}{ENOTCONN} Transport endpoint is not connected \end{datadesc}
-\begin{datadesc}{ESHUTDOWN} Cannot send after transport endpoint shutdown \end{datadesc}
-\begin{datadesc}{ETOOMANYREFS} Too many references: cannot splice \end{datadesc}
-\begin{datadesc}{ETIMEDOUT} Connection timed out \end{datadesc}
-\begin{datadesc}{ECONNREFUSED} Connection refused \end{datadesc}
-\begin{datadesc}{EHOSTDOWN} Host is down \end{datadesc}
-\begin{datadesc}{EHOSTUNREACH} No route to host \end{datadesc}
-\begin{datadesc}{EALREADY} Operation already in progress \end{datadesc}
-\begin{datadesc}{EINPROGRESS} Operation now in progress \end{datadesc}
-\begin{datadesc}{ESTALE} Stale NFS file handle \end{datadesc}
-\begin{datadesc}{EUCLEAN} Structure needs cleaning \end{datadesc}
-\begin{datadesc}{ENOTNAM} Not a XENIX named type file \end{datadesc}
-\begin{datadesc}{ENAVAIL} No XENIX semaphores available \end{datadesc}
-\begin{datadesc}{EISNAM} Is a named type file \end{datadesc}
-\begin{datadesc}{EREMOTEIO} Remote I/O error \end{datadesc}
-\begin{datadesc}{EDQUOT} Quota exceeded \end{datadesc}
-
diff --git a/Doc/lib/libetree.tex b/Doc/lib/libetree.tex
deleted file mode 100644
index 6f20ee3..0000000
--- a/Doc/lib/libetree.tex
+++ /dev/null
@@ -1,426 +0,0 @@
-\section{\module{xml.etree.ElementTree} --- The ElementTree XML API}
-\declaremodule{standard}{xml.etree.ElementTree}
-\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com}
-\modulesynopsis{Implementation of the ElementTree API.}
-
-\versionadded{2.5}
-
-The Element type is a flexible container object, designed to store
-hierarchical data structures in memory. The type can be described as a
-cross between a list and a dictionary.
-
-Each element has a number of properties associated with it:
-
-\begin{itemize}
- \item a tag which is a string identifying what kind of data
- this element represents (the element type, in other words).
- \item a number of attributes, stored in a Python dictionary.
- \item a text string.
- \item an optional tail string.
- \item a number of child elements, stored in a Python sequence
-\end{itemize}
-
-To create an element instance, use the Element or SubElement factory
-functions.
-
-The \class{ElementTree} class can be used to wrap an element
-structure, and convert it from and to XML.
-
-A C implementation of this API is available as
-\module{xml.etree.cElementTree}.
-
-
-\subsection{Functions\label{elementtree-functions}}
-
-\begin{funcdesc}{Comment}{\optional{text}}
-Comment element factory. This factory function creates a special
-element that will be serialized as an XML comment.
-The comment string can be either an 8-bit ASCII string or a Unicode
-string.
-\var{text} is a string containing the comment string.
-Returns an element instance representing a comment.
-\end{funcdesc}
-
-\begin{funcdesc}{dump}{elem}
-Writes an element tree or element structure to sys.stdout. This
-function should be used for debugging only.
-
-The exact output format is implementation dependent. In this
-version, it's written as an ordinary XML file.
-
-\var{elem} is an element tree or an individual element.
-\end{funcdesc}
-
-\begin{funcdesc}{Element}{tag\optional{, attrib}\optional{, **extra}}
-Element factory. This function returns an object implementing the
-standard Element interface. The exact class or type of that object
-is implementation dependent, but it will always be compatible with
-the {\_}ElementInterface class in this module.
-
-The element name, attribute names, and attribute values can be
-either 8-bit ASCII strings or Unicode strings.
-\var{tag} is the element name.
-\var{attrib} is an optional dictionary, containing element attributes.
-\var{extra} contains additional attributes, given as keyword arguments.
-Returns an element instance.
-\end{funcdesc}
-
-\begin{funcdesc}{fromstring}{text}
-Parses an XML section from a string constant. Same as XML.
-\var{text} is a string containing XML data.
-Returns an Element instance.
-\end{funcdesc}
-
-\begin{funcdesc}{iselement}{element}
-Checks if an object appears to be a valid element object.
-\var{element} is an element instance.
-Returns a true value if this is an element object.
-\end{funcdesc}
-
-\begin{funcdesc}{iterparse}{source\optional{, events}}
-Parses an XML section into an element tree incrementally, and reports
-what's going on to the user.
-\var{source} is a filename or file object containing XML data.
-\var{events} is a list of events to report back. If omitted, only ``end''
-events are reported.
-Returns an iterator providing \code{(\var{event}, \var{elem})} pairs.
-\end{funcdesc}
-
-\begin{funcdesc}{parse}{source\optional{, parser}}
-Parses an XML section into an element tree.
-\var{source} is a filename or file object containing XML data.
-\var{parser} is an optional parser instance. If not given, the
-standard XMLTreeBuilder parser is used.
-Returns an ElementTree instance.
-\end{funcdesc}
-
-\begin{funcdesc}{ProcessingInstruction}{target\optional{, text}}
-PI element factory. This factory function creates a special element
-that will be serialized as an XML processing instruction.
-\var{target} is a string containing the PI target.
-\var{text} is a string containing the PI contents, if given.
-Returns an element instance, representing a processing instruction.
-\end{funcdesc}
-
-\begin{funcdesc}{SubElement}{parent, tag\optional{,
- attrib\optional{, **extra}}}
-Subelement factory. This function creates an element instance, and
-appends it to an existing element.
-
-The element name, attribute names, and attribute values can be
-either 8-bit ASCII strings or Unicode strings.
-\var{parent} is the parent element.
-\var{tag} is the subelement name.
-\var{attrib} is an optional dictionary, containing element attributes.
-\var{extra} contains additional attributes, given as keyword arguments.
-Returns an element instance.
-\end{funcdesc}
-
-\begin{funcdesc}{tostring}{element\optional{, encoding}}
-Generates a string representation of an XML element, including all
-subelements.
-\var{element} is an Element instance.
-\var{encoding} is the output encoding (default is US-ASCII).
-Returns an encoded string containing the XML data.
-\end{funcdesc}
-
-\begin{funcdesc}{XML}{text}
-Parses an XML section from a string constant. This function can
-be used to embed ``XML literals'' in Python code.
-\var{text} is a string containing XML data.
-Returns an Element instance.
-\end{funcdesc}
-
-\begin{funcdesc}{XMLID}{text}
-Parses an XML section from a string constant, and also returns
-a dictionary which maps from element id:s to elements.
-\var{text} is a string containing XML data.
-Returns a tuple containing an Element instance and a dictionary.
-\end{funcdesc}
-
-
-\subsection{The Element Interface\label{elementtree-element-interface}}
-
-Element objects returned by Element or SubElement have the
-following methods and attributes.
-
-\begin{memberdesc}[Element]{tag}
-A string identifying what kind of data this element represents
-(the element type, in other words).
-\end{memberdesc}
-
-\begin{memberdesc}[Element]{text}
-The \var{text} attribute can be used to hold additional data
-associated with the element.
-As the name implies this attribute is usually a string but may be any
-application-specific object.
-If the element is created from an XML file the attribute will contain
-any text found between the element tags.
-\end{memberdesc}
-
-\begin{memberdesc}[Element]{tail}
-The \var{tail} attribute can be used to hold additional data
-associated with the element.
-This attribute is usually a string but may be any application-specific object.
-If the element is created from an XML file the attribute will contain
-any text found after the element's end tag and before the next tag.
-\end{memberdesc}
-
-\begin{memberdesc}[Element]{attrib}
-A dictionary containing the element's attributes.
-Note that while the \var{attrib} value is always a real mutable Python
-dictionary, an ElementTree implementation may choose to use another
-internal representation, and create the dictionary only if someone
-asks for it. To take advantage of such implementations, use the
-dictionary methods below whenever possible.
-\end{memberdesc}
-
-The following dictionary-like methods work on the element attributes.
-
-\begin{methoddesc}[Element]{clear}{}
-Resets an element. This function removes all subelements, clears
-all attributes, and sets the text and tail attributes to None.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{get}{key\optional{, default=None}}
-Gets the element attribute named \var{key}.
-
-Returns the attribute value, or \var{default} if the
-attribute was not found.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{items}{}
-Returns the element attributes as a sequence of (name, value) pairs.
-The attributes are returned in an arbitrary order.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{keys}{}
-Returns the elements attribute names as a list.
-The names are returned in an arbitrary order.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{set}{key, value}
-Set the attribute \var{key} on the element to \var{value}.
-\end{methoddesc}
-
-The following methods work on the element's children (subelements).
-
-\begin{methoddesc}[Element]{append}{subelement}
-Adds the element \var{subelement} to the end of this elements internal list
-of subelements.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{find}{match}
-Finds the first subelement matching \var{match}.
-\var{match} may be a tag name or path.
-Returns an element instance or \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{findall}{match}
-Finds all subelements matching \var{match}.
-\var{match} may be a tag name or path.
-Returns an iterable yielding all matching elements in document order.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{findtext}{condition\optional{, default=None}}
-Finds text for the first subelement matching \var{condition}.
-\var{condition} may be a tag name or path.
-Returns the text content of the first matching element, or
-\var{default} if no element was found. Note that if the
-matching element has no text content an empty string is returned.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{getchildren}{}
-Returns all subelements. The elements are returned in document order.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{getiterator}{\optional{tag=None}}
-Creates a tree iterator with the current element as the root.
-The iterator iterates over this element and all elements below it
-that match the given tag. If tag
-is \code{None} or \code{'*'} then all elements are iterated over.
-Returns an iterable that provides element objects in document (depth first)
-order.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{insert}{index, element}
-Inserts a subelement at the given position in this element.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{makeelement}{tag, attrib}
-Creates a new element object of the same type as this element.
-Do not call this method, use the SubElement factory function instead.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{remove}{subelement}
-Removes \var{subelement} from the element.
-Unlike the findXXX methods this method compares elements based on
-the instance identity, not on tag value or contents.
-\end{methoddesc}
-
-Element objects also support the following sequence type methods for
-working with subelements: \method{__delitem__()},
-\method{__getitem__()}, \method{__setitem__()}, \method{__len__()}.
-
-Caution: Because Element objects do not define a
-\method{__nonzero__()} method, elements with no subelements will test
-as \code{False}.
-
-\begin{verbatim}
-element = root.find('foo')
-
-if not element: # careful!
- print "element not found, or element has no subelements"
-
-if element is None:
- print "element not found"
-\end{verbatim}
-
-
-\subsection{ElementTree Objects\label{elementtree-elementtree-objects}}
-
-\begin{classdesc}{ElementTree}{\optional{element,} \optional{file}}
-ElementTree wrapper class. This class represents an entire element
-hierarchy, and adds some extra support for serialization to and from
-standard XML.
-
-\var{element} is the root element.
-The tree is initialized with the contents of the XML \var{file} if given.
-\end{classdesc}
-
-\begin{methoddesc}{_setroot}{element}
-Replaces the root element for this tree. This discards the
-current contents of the tree, and replaces it with the given
-element. Use with care.
-\var{element} is an element instance.
-\end{methoddesc}
-
-\begin{methoddesc}{find}{path}
-Finds the first toplevel element with given tag.
-Same as getroot().find(path).
-\var{path} is the element to look for.
-Returns the first matching element, or \code{None} if no element was found.
-\end{methoddesc}
-
-\begin{methoddesc}{findall}{path}
-Finds all toplevel elements with the given tag.
-Same as getroot().findall(path).
-\var{path} is the element to look for.
-Returns a list or iterator containing all matching elements,
-in document order.
-\end{methoddesc}
-
-\begin{methoddesc}{findtext}{path\optional{, default}}
-Finds the element text for the first toplevel element with given
-tag. Same as getroot().findtext(path).
-\var{path} is the toplevel element to look for.
-\var{default} is the value to return if the element was not found.
-Returns the text content of the first matching element, or the
-default value no element was found. Note that if the element
-has is found, but has no text content, this method returns an
-empty string.
-\end{methoddesc}
-
-\begin{methoddesc}{getiterator}{\optional{tag}}
-Creates and returns a tree iterator for the root element. The iterator loops
-over all elements in this tree, in section order.
-\var{tag} is the tag to look for (default is to return all elements)
-\end{methoddesc}
-
-\begin{methoddesc}{getroot}{}
-Returns the root element for this tree.
-\end{methoddesc}
-
-\begin{methoddesc}{parse}{source\optional{, parser}}
-Loads an external XML section into this element tree.
-\var{source} is a file name or file object.
-\var{parser} is an optional parser instance. If not given, the
-standard XMLTreeBuilder parser is used.
-Returns the section root element.
-\end{methoddesc}
-
-\begin{methoddesc}{write}{file\optional{, encoding}}
-Writes the element tree to a file, as XML.
-\var{file} is a file name, or a file object opened for writing.
-\var{encoding} is the output encoding (default is US-ASCII).
-\end{methoddesc}
-
-
-\subsection{QName Objects\label{elementtree-qname-objects}}
-
-\begin{classdesc}{QName}{text_or_uri\optional{, tag}}
-QName wrapper. This can be used to wrap a QName attribute value, in
-order to get proper namespace handling on output.
-\var{text_or_uri} is a string containing the QName value,
-in the form {\{}uri{\}}local, or, if the tag argument is given,
-the URI part of a QName.
-If \var{tag} is given, the first argument is interpreted as
-an URI, and this argument is interpreted as a local name.
-\class{QName} instances are opaque.
-\end{classdesc}
-
-
-\subsection{TreeBuilder Objects\label{elementtree-treebuilder-objects}}
-
-\begin{classdesc}{TreeBuilder}{\optional{element_factory}}
-Generic element structure builder. This builder converts a sequence
-of start, data, and end method calls to a well-formed element structure.
-You can use this class to build an element structure using a custom XML
-parser, or a parser for some other XML-like format.
-The \var{element_factory} is called to create new Element instances when
-given.
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
-Flushes the parser buffers, and returns the toplevel documen
-element.
-Returns an Element instance.
-\end{methoddesc}
-
-\begin{methoddesc}{data}{data}
-Adds text to the current element.
-\var{data} is a string. This should be either an 8-bit string
-containing ASCII text, or a Unicode string.
-\end{methoddesc}
-
-\begin{methoddesc}{end}{tag}
-Closes the current element.
-\var{tag} is the element name.
-Returns the closed element.
-\end{methoddesc}
-
-\begin{methoddesc}{start}{tag, attrs}
-Opens a new element.
-\var{tag} is the element name.
-\var{attrs} is a dictionary containing element attributes.
-Returns the opened element.
-\end{methoddesc}
-
-
-\subsection{XMLTreeBuilder Objects\label{elementtree-xmltreebuilder-objects}}
-
-\begin{classdesc}{XMLTreeBuilder}{\optional{html,} \optional{target}}
-Element structure builder for XML source data, based on the
-expat parser.
-\var{html} are predefined HTML entities. This flag is not supported
-by the current implementation.
-\var{target} is the target object. If omitted, the builder uses an
-instance of the standard TreeBuilder class.
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
-Finishes feeding data to the parser.
-Returns an element structure.
-\end{methoddesc}
-
-\begin{methoddesc}{doctype}{name, pubid, system}
-Handles a doctype declaration.
-\var{name} is the doctype name.
-\var{pubid} is the public identifier.
-\var{system} is the system identifier.
-\end{methoddesc}
-
-\begin{methoddesc}{feed}{data}
-Feeds data to the parser.
-\var{data} is encoded data.
-\end{methoddesc}
diff --git a/Doc/lib/libexcs.tex b/Doc/lib/libexcs.tex
deleted file mode 100644
index 74531d3..0000000
--- a/Doc/lib/libexcs.tex
+++ /dev/null
@@ -1,427 +0,0 @@
-\section{Built-in Exceptions}
-
-\declaremodule{standard}{exceptions}
-\modulesynopsis{Standard exception classes.}
-
-
-Exceptions should be class objects.
-The exceptions are defined in the module \module{exceptions}. This
-module never needs to be imported explicitly: the exceptions are
-provided in the built-in namespace as well as the \module{exceptions}
-module.
-
-For class exceptions, in a \keyword{try}\stindex{try} statement with
-an \keyword{except}\stindex{except} clause that mentions a particular
-class, that clause also handles any exception classes derived from
-that class (but not exception classes from which \emph{it} is
-derived). Two exception classes that are not related via subclassing
-are never equivalent, even if they have the same name.
-
-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}\stindex{raise} statement. If the exception class is
-derived from the standard root class \exception{BaseException}, the
-associated value is present as the exception instance's \member{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 \exception{Exception} class and not
-\exception{BaseException}. More
-information on defining exceptions is available in the
-\citetitle[../tut/tut.html]{Python Tutorial} under the heading
-``User-defined Exceptions.''
-
-\setindexsubitem{(built-in exception base class)}
-
-The following exceptions are only used as base classes for other
-exceptions.
-
-\begin{excdesc}{BaseException}
-The base class for all built-in exceptions. It is not meant to be directly
-inherited by user-defined classes (for that use \exception{Exception}). If
-\function{str()} or \function{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 \member{args} as a tuple.
-\versionadded{2.5}
-\end{excdesc}
-
-\begin{excdesc}{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[Changed to inherit from \exception{BaseException}]{2.5}
-\end{excdesc}
-
-\begin{excdesc}{ArithmeticError}
-The base class for those built-in exceptions that are raised for
-various arithmetic errors: \exception{OverflowError},
-\exception{ZeroDivisionError}, \exception{FloatingPointError}.
-\end{excdesc}
-
-\begin{excdesc}{LookupError}
-The base class for the exceptions that are raised when a key or
-index used on a mapping or sequence is invalid: \exception{IndexError},
-\exception{KeyError}. This can be raised directly by
-\function{sys.setdefaultencoding()}.
-\end{excdesc}
-
-\begin{excdesc}{EnvironmentError}
-The base class for exceptions that
-can occur outside the Python system: \exception{IOError},
-\exception{OSError}. When exceptions of this type are created with a
-2-tuple, the first item is available on the instance's \member{errno}
-attribute (it is assumed to be an error number), and the second item
-is available on the \member{strerror} attribute (it is usually the
-associated error message). The tuple itself is also available on the
-\member{args} attribute.
-\versionadded{1.5.2}
-
-When an \exception{EnvironmentError} exception is instantiated with a
-3-tuple, the first two items are available as above, while the third
-item is available on the \member{filename} attribute. However, for
-backwards compatibility, the \member{args} attribute contains only a
-2-tuple of the first two constructor arguments.
-
-The \member{filename} attribute is \code{None} when this exception is
-created with other than 3 arguments. The \member{errno} and
-\member{strerror} attributes are also \code{None} when the instance was
-created with other than 2 or 3 arguments. In this last case,
-\member{args} contains the verbatim constructor arguments as a tuple.
-\end{excdesc}
-
-
-\setindexsubitem{(built-in exception)}
-
-The following exceptions are the exceptions that are actually raised.
-
-\begin{excdesc}{AssertionError}
-\stindex{assert}
-Raised when an \keyword{assert} statement fails.
-\end{excdesc}
-
-\begin{excdesc}{AttributeError}
-% xref to attribute reference?
- Raised when an attribute reference or assignment fails. (When an
- object does not support attribute references or attribute assignments
- at all, \exception{TypeError} is raised.)
-\end{excdesc}
-
-\begin{excdesc}{EOFError}
-% XXXJH xrefs here
- Raised when attempting to read beyond the end of a file.
-% XXXJH xrefs here
- (N.B.: the \method{read()} and \method{readline()} methods of file
- objects return an empty string when they hit \EOF.)
-\end{excdesc}
-
-\begin{excdesc}{FloatingPointError}
- Raised when a floating point operation fails. This exception is
- always defined, but can only be raised when Python is configured
- with the \longprogramopt{with-fpectl} option, or the
- \constant{WANT_SIGFPE_HANDLER} symbol is defined in the
- \file{pyconfig.h} file.
-\end{excdesc}
-
-\begin{excdesc}{GeneratorExit}
- Raise when a generator's \method{close()} method is called.
- \versionadded{2.5}
- \versionchanged[Changed to inherit from Exception instead of
- StandardError]{3.0}
-\end{excdesc}
-
-\begin{excdesc}{IOError}
-% XXXJH xrefs here
- Raised when an I/O operation (such as a \keyword{print} statement,
- the built-in \function{open()} function or a method of a file
- object) fails for an I/O-related reason, e.g., ``file not found'' or
- ``disk full''.
-
- This class is derived from \exception{EnvironmentError}. See the
- discussion above for more information on exception instance
- attributes.
-\end{excdesc}
-
-\begin{excdesc}{ImportError}
-% XXXJH xref to import statement?
- Raised when an \keyword{import} statement fails to find the module
- definition or when a \code{from \textrm{\ldots} import} fails to find a
- name that is to be imported.
-\end{excdesc}
-
-\begin{excdesc}{IndexError}
-% XXXJH xref to sequences
- 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, \exception{TypeError} is raised.)
-\end{excdesc}
-
-\begin{excdesc}{KeyError}
-% XXXJH xref to mapping objects?
- Raised when a mapping (dictionary) key is not found in the set of
- existing keys.
-\end{excdesc}
-
-\begin{excdesc}{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.
-% XXX(hylton) xrefs here
- The exception inherits from \exception{BaseException} so as to not be
- accidentally caught by code that catches \exception{Exception} and thus
- prevent the interpreter from exiting.
- \versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
-\end{excdesc}
-
-\begin{excdesc}{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 \cfunction{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.
-\end{excdesc}
-
-\begin{excdesc}{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.
-\end{excdesc}
-
-\begin{excdesc}{NotImplementedError}
- This exception is derived from \exception{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}
-\end{excdesc}
-
-\begin{excdesc}{OSError}
- %xref for os module
- This class is derived from \exception{EnvironmentError} and is used
- primarily as the \refmodule{os} module's \code{os.error} exception.
- See \exception{EnvironmentError} above for a description of the
- possible associated values.
- \versionadded{1.5.2}
-\end{excdesc}
-
-\begin{excdesc}{OverflowError}
-% XXXJH reference to long's and/or int's?
- Raised when the result of an arithmetic operation is too large to be
- represented. This cannot occur for long integers (which would rather
- raise \exception{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.
-\end{excdesc}
-
-\begin{excdesc}{ReferenceError}
- This exception is raised when a weak reference proxy, created by the
- \function{\refmodule{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 \refmodule{weakref}
- module.
- \versionadded[Previously known as the
- \exception{\refmodule{weakref}.ReferenceError}
- exception]{2.2}
-\end{excdesc}
-
-\begin{excdesc}{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.)
-\end{excdesc}
-
-\begin{excdesc}{StopIteration}
- Raised by builtin \function{next()} and an iterator's \method{__next__()}
- method to signal that there are no further values.
- \versionadded{2.2}
- \versionchanged[Changed to inherit from Exception instead of
- StandardError]{3.0}
-\end{excdesc}
-
-
-\begin{excdesc}{SyntaxError}
-% XXXJH xref to these functions?
- Raised when the parser encounters a syntax error. This may occur in
- an \keyword{import} statement, in a call to the built-in functions
- \function{exec()}, \function{eval()} or
- \function{input()}, or when reading the initial script or standard
- input (also interactively).
-
- Instances of this class have attributes \member{filename},
- \member{lineno}, \member{offset} and \member{text} for easier access
- to the details. \function{str()} of the exception instance returns
- only the message.
-\end{excdesc}
-
-\begin{excdesc}{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 (\code{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.
-\end{excdesc}
-
-\begin{excdesc}{SystemExit}
-% XXX(hylton) xref to module sys?
- This exception is raised by the \function{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 \cfunction{exit()} function); if it is
- \code{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.
-
- Instances have an attribute \member{code} which is set to the
- proposed exit status or error message (defaulting to \code{None}).
- Also, this exception derives directly from \exception{BaseException} and
- not \exception{Exception}, since it is not technically an error.
-
- A call to \function{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 \function{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
- \function{fork()}).
-
- The exception inherits from \exception{BaseException} instead of
- \exception{Exception} so that it is not
- accidentally caught by code that catches \exception{Exception}. This allows
- the exception to properly propagate up and cause the interpreter to exit.
- \versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
-\end{excdesc}
-
-\begin{excdesc}{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.
-\end{excdesc}
-
-\begin{excdesc}{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 \exception{NameError}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{UnicodeError}
- Raised when a Unicode-related encoding or decoding error occurs. It
- is a subclass of \exception{ValueError}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{UnicodeEncodeError}
- Raised when a Unicode-related error occurs during encoding. It
- is a subclass of \exception{UnicodeError}.
-\versionadded{2.3}
-\end{excdesc}
-
-\begin{excdesc}{UnicodeDecodeError}
- Raised when a Unicode-related error occurs during decoding. It
- is a subclass of \exception{UnicodeError}.
-\versionadded{2.3}
-\end{excdesc}
-
-\begin{excdesc}{UnicodeTranslateError}
- Raised when a Unicode-related error occurs during translating. It
- is a subclass of \exception{UnicodeError}.
-\versionadded{2.3}
-\end{excdesc}
-
-\begin{excdesc}{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
- \exception{IndexError}.
-\end{excdesc}
-
-\begin{excdesc}{WindowsError}
- Raised when a Windows-specific error occurs or when the error number
- does not correspond to an \cdata{errno} value. The
- \member{winerror} and \member{strerror} values are created from the
- return values of the \cfunction{GetLastError()} and
- \cfunction{FormatMessage()} functions from the Windows Platform API.
- The \member{errno} value maps the \member{winerror} value to
- corresponding \code{errno.h} values.
- This is a subclass of \exception{OSError}.
-\versionadded{2.0}
-\versionchanged[Previous versions put the \cfunction{GetLastError()}
-codes into \member{errno}]{2.5}
-\end{excdesc}
-
-\begin{excdesc}{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.
-\end{excdesc}
-
-
-\setindexsubitem{(built-in warning)}
-
-The following exceptions are used as warning categories; see the
-\refmodule{warnings} module for more information.
-
-\begin{excdesc}{Warning}
-Base class for warning categories.
-\end{excdesc}
-
-\begin{excdesc}{UserWarning}
-Base class for warnings generated by user code.
-\end{excdesc}
-
-\begin{excdesc}{DeprecationWarning}
-Base class for warnings about deprecated features.
-\end{excdesc}
-
-\begin{excdesc}{PendingDeprecationWarning}
-Base class for warnings about features which will be deprecated in the future.
-\end{excdesc}
-
-\begin{excdesc}{SyntaxWarning}
-Base class for warnings about dubious syntax
-\end{excdesc}
-
-\begin{excdesc}{RuntimeWarning}
-Base class for warnings about dubious runtime behavior.
-\end{excdesc}
-
-\begin{excdesc}{FutureWarning}
-Base class for warnings about constructs that will change semantically
-in the future.
-\end{excdesc}
-
-\begin{excdesc}{ImportWarning}
-Base class for warnings about probable mistakes in module imports.
-\versionadded{2.5}
-\end{excdesc}
-
-\begin{excdesc}{UnicodeWarning}
-Base class for warnings related to Unicode.
-\versionadded{2.5}
-\end{excdesc}
-
-The class hierarchy for built-in exceptions is:
-
-\verbatiminput{../../Lib/test/exception_hierarchy.txt}
diff --git a/Doc/lib/libfcntl.tex b/Doc/lib/libfcntl.tex
deleted file mode 100644
index dc76da3..0000000
--- a/Doc/lib/libfcntl.tex
+++ /dev/null
@@ -1,174 +0,0 @@
-\section{\module{fcntl} ---
- The \function{fcntl()} and \function{ioctl()} system calls}
-
-\declaremodule{builtin}{fcntl}
- \platform{Unix}
-\modulesynopsis{The \function{fcntl()} and \function{ioctl()} system calls.}
-\sectionauthor{Jaap Vermeulen}{}
-
-\indexii{UNIX@\UNIX}{file control}
-\indexii{UNIX@\UNIX}{I/O control}
-
-This module performs file control and I/O control on file descriptors.
-It is an interface to the \cfunction{fcntl()} and \cfunction{ioctl()}
-\UNIX{} routines.
-
-All functions in this module take a file descriptor \var{fd} as their
-first argument. This can be an integer file descriptor, such as
-returned by \code{sys.stdin.fileno()}, or a file object, such as
-\code{sys.stdin} itself, which provides a \method{fileno()} which
-returns a genuine file descriptor.
-
-The module defines the following functions:
-
-
-\begin{funcdesc}{fcntl}{fd, op\optional{, arg}}
- Perform the requested operation on file descriptor \var{fd} (file
- objects providing a \method{fileno()} method are accepted as well).
- The operation is defined by \var{op} and is operating system
- dependent. These codes are also found in the \module{fcntl}
- module. The argument \var{arg} is optional, and defaults to the
- integer value \code{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 \cfunction{fcntl()} call. When the argument is a string it
- represents a binary structure, e.g.\ created by
- \function{\refmodule{struct}.pack()}. The binary data is copied to a buffer
- whose address is passed to the C \cfunction{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 \var{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 \cfunction{fcntl()} fails, an \exception{IOError} is
- raised.
-\end{funcdesc}
-
-\begin{funcdesc}{ioctl}{fd, op\optional{, arg\optional{, mutate_flag}}}
- This function is identical to the \function{fcntl()} function,
- except that the operations are typically defined in the library
- module \refmodule{termios} and the argument handling is even more
- complicated.
-
- The parameter \var{arg} can be one of an integer, absent (treated
- identically to the integer \code{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 \function{fcntl()}
- function.
-
- If a mutable buffer is passed, then the behaviour is determined by
- the value of the \var{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 \var{mutate_flag} is true, then the buffer is (in effect) passed
- to the underlying \function{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 \function{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 \function{ioctl()} and copied back into
- the supplied buffer.
-
- If \var{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:
-
-\begin{verbatim}
->>> 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])
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{flock}{fd, op}
-Perform the lock operation \var{op} on file descriptor \var{fd} (file
- objects providing a \method{fileno()} method are accepted as well).
-See the \UNIX{} manual \manpage{flock}{3} for details. (On some
-systems, this function is emulated using \cfunction{fcntl()}.)
-\end{funcdesc}
-
-\begin{funcdesc}{lockf}{fd, operation,
- \optional{length, \optional{start, \optional{whence}}}}
-This is essentially a wrapper around the \function{fcntl()} locking
-calls. \var{fd} is the file descriptor of the file to lock or unlock,
-and \var{operation} is one of the following values:
-
-\begin{itemize}
-\item \constant{LOCK_UN} -- unlock
-\item \constant{LOCK_SH} -- acquire a shared lock
-\item \constant{LOCK_EX} -- acquire an exclusive lock
-\end{itemize}
-
-When \var{operation} is \constant{LOCK_SH} or \constant{LOCK_EX}, it
-can also be bit-wise OR'd with \constant{LOCK_NB} to avoid blocking on
-lock acquisition. If \constant{LOCK_NB} is used and the lock cannot
-be acquired, an \exception{IOError} will be raised and the exception
-will have an \var{errno} attribute set to \constant{EACCES} or
-\constant{EAGAIN} (depending on the operating system; for portability,
-check for both values). On at least some systems, \constant{LOCK_EX}
-can only be used if the file descriptor refers to a file opened for
-writing.
-
-\var{length} is the number of bytes to lock, \var{start} is the byte
-offset at which the lock starts, relative to \var{whence}, and
-\var{whence} is as with \function{fileobj.seek()}, specifically:
-
-\begin{itemize}
-\item \constant{0} -- relative to the start of the file
- (\constant{SEEK_SET})
-\item \constant{1} -- relative to the current buffer position
- (\constant{SEEK_CUR})
-\item \constant{2} -- relative to the end of the file
- (\constant{SEEK_END})
-\end{itemize}
-
-The default for \var{start} is 0, which means to start at the
-beginning of the file. The default for \var{length} is 0 which means
-to lock to the end of the file. The default for \var{whence} is also
-0.
-\end{funcdesc}
-
-Examples (all on a SVR4 compliant system):
-
-\begin{verbatim}
-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)
-\end{verbatim}
-
-Note that in the first example the return value variable \var{rv} will
-hold an integer value; in the second example it will hold a string
-value. The structure lay-out for the \var{lockdata} variable is
-system dependent --- therefore using the \function{flock()} call may be
-better.
-
-\begin{seealso}
- \seemodule{os}{If the locking flags \constant{O_SHLOCK} and
- \constant{O_EXLOCK} are present in the \module{os} module,
- the \function{os.open()} function provides a more
- platform-independent alternative to the \function{lockf()}
- and \function{flock()} functions.}
-\end{seealso}
diff --git a/Doc/lib/libfilecmp.tex b/Doc/lib/libfilecmp.tex
deleted file mode 100644
index 42b4b8c..0000000
--- a/Doc/lib/libfilecmp.tex
+++ /dev/null
@@ -1,142 +0,0 @@
-\section{\module{filecmp} ---
- File and Directory Comparisons}
-
-\declaremodule{standard}{filecmp}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Compare files efficiently.}
-
-
-The \module{filecmp} module defines functions to compare files and
-directories, with various optional time/correctness trade-offs.
-
-The \module{filecmp} module defines the following functions:
-
-\begin{funcdesc}{cmp}{f1, f2\optional{, shallow}}
-Compare the files named \var{f1} and \var{f2}, returning \code{True} if
-they seem equal, \code{False} otherwise.
-
-Unless \var{shallow} is given and is false, files with identical
-\function{os.stat()} signatures are taken to be equal.
-
-Files that were compared using this function will not be compared again
-unless their \function{os.stat()} signature changes.
-
-Note that no external programs are called from this function, giving it
-portability and efficiency.
-\end{funcdesc}
-
-\begin{funcdesc}{cmpfiles}{dir1, dir2, common\optional{,
- shallow}}
-Returns three lists of file names: \var{match}, \var{mismatch},
-\var{errors}. \var{match} contains the list of files match in both
-directories, \var{mismatch} includes the names of those that don't,
-and \var{errros} lists the names of files which could not be
-compared. Files may be listed in \var{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 \var{common} parameter is a list of file names found in both directories.
-The \var{shallow} parameter has the same
-meaning and default value as for \function{filecmp.cmp()}.
-\end{funcdesc}
-
-Example:
-
-\begin{verbatim}
->>> import filecmp
->>> filecmp.cmp('libundoc.tex', 'libundoc.tex')
-True
->>> filecmp.cmp('libundoc.tex', 'lib.tex')
-False
-\end{verbatim}
-
-
-\subsection{The \protect\class{dircmp} class \label{dircmp-objects}}
-
-\class{dircmp} instances are built using this constructor:
-
-\begin{classdesc}{dircmp}{a, b\optional{, ignore\optional{, hide}}}
-Construct a new directory comparison object, to compare the
-directories \var{a} and \var{b}. \var{ignore} is a list of names to
-ignore, and defaults to \code{['RCS', 'CVS', 'tags']}. \var{hide} is a
-list of names to hide, and defaults to \code{[os.curdir, os.pardir]}.
-\end{classdesc}
-
-The \class{dircmp} class provides the following methods:
-
-\begin{methoddesc}[dircmp]{report}{}
-Print (to \code{sys.stdout}) a comparison between \var{a} and \var{b}.
-\end{methoddesc}
-
-\begin{methoddesc}[dircmp]{report_partial_closure}{}
-Print a comparison between \var{a} and \var{b} and common immediate
-subdirectories.
-\end{methoddesc}
-
-\begin{methoddesc}[dircmp]{report_full_closure}{}
-Print a comparison between \var{a} and \var{b} and common
-subdirectories (recursively).
-\end{methoddesc}
-
-
-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 \method{__getattr__()} hooks, all attributes are
-computed lazily, so there is no speed penalty if only those
-attributes which are lightweight to compute are used.
-
-\begin{memberdesc}[dircmp]{left_list}
-Files and subdirectories in \var{a}, filtered by \var{hide} and
-\var{ignore}.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{right_list}
-Files and subdirectories in \var{b}, filtered by \var{hide} and
-\var{ignore}.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{common}
-Files and subdirectories in both \var{a} and \var{b}.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{left_only}
-Files and subdirectories only in \var{a}.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{right_only}
-Files and subdirectories only in \var{b}.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{common_dirs}
-Subdirectories in both \var{a} and \var{b}.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{common_files}
-Files in both \var{a} and \var{b}
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{common_funny}
-Names in both \var{a} and \var{b}, such that the type differs between
-the directories, or names for which \function{os.stat()} reports an
-error.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{same_files}
-Files which are identical in both \var{a} and \var{b}.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{diff_files}
-Files which are in both \var{a} and \var{b}, whose contents differ.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{funny_files}
-Files which are in both \var{a} and \var{b}, but could not be
-compared.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{subdirs}
-A dictionary mapping names in \member{common_dirs} to
-\class{dircmp} objects.
-\end{memberdesc}
diff --git a/Doc/lib/libfileinput.tex b/Doc/lib/libfileinput.tex
deleted file mode 100644
index 3cfb7bc..0000000
--- a/Doc/lib/libfileinput.tex
+++ /dev/null
@@ -1,192 +0,0 @@
-\section{\module{fileinput} ---
- Iterate over lines from multiple input streams}
-\declaremodule{standard}{fileinput}
-\moduleauthor{Guido van Rossum}{guido@python.org}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-\modulesynopsis{Perl-like iteration over lines from multiple input
-streams, with ``save in place'' capability.}
-
-
-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:
-
-\begin{verbatim}
-import fileinput
-for line in fileinput.input():
- process(line)
-\end{verbatim}
-
-This iterates over the lines of all files listed in
-\code{sys.argv[1:]}, defaulting to \code{sys.stdin} if the list is
-empty. If a filename is \code{'-'}, it is also replaced by
-\code{sys.stdin}. To specify an alternative list of filenames, pass
-it as the first argument to \function{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 \var{mode} parameter in the call to \function{input()}
-or \class{FileInput()}. If an I/O error occurs during opening or reading
-a file, \exception{IOError} is raised.
-
-If \code{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 \code{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.
-
-It is possible that the last line of a file does not end in a newline
-character; lines are returned including the trailing newline when it
-is present.
-
-You can control how files are opened by providing an opening hook via the
-\var{openhook} parameter to \function{input()} or \class{FileInput()}.
-The hook must be a function that takes two arguments, \var{filename}
-and \var{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:
-
-\begin{funcdesc}{input}{\optional{files\optional{, inplace\optional{,
- backup\optional{, mode\optional{, 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[Added the \var{mode} and \var{openhook} parameters]{2.5}
-\end{funcdesc}
-
-
-The following functions use the global state created by
-\function{input()}; if there is no active state,
-\exception{RuntimeError} is raised.
-
-\begin{funcdesc}{filename}{}
- Return the name of the file currently being read. Before the first
- line has been read, returns \code{None}.
-\end{funcdesc}
-
-\begin{funcdesc}{fileno}{}
- Return the integer ``file descriptor'' for the current file. When no
- file is opened (before the first line and between files), returns
- \code{-1}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{lineno}{}
- Return the cumulative line number of the line that has just been
- read. Before the first line has been read, returns \code{0}. After
- the last line of the last file has been read, returns the line
- number of that line.
-\end{funcdesc}
-
-\begin{funcdesc}{filelineno}{}
- Return the line number in the current file. Before the first line
- has been read, returns \code{0}. After the last line of the last
- file has been read, returns the line number of that line within the
- file.
-\end{funcdesc}
-
-\begin{funcdesc}{isfirstline}{}
- Returns true if the line just read is the first line of its file,
- otherwise returns false.
-\end{funcdesc}
-
-\begin{funcdesc}{isstdin}{}
- Returns true if the last line was read from \code{sys.stdin},
- otherwise returns false.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{close}{}
- Close the sequence.
-\end{funcdesc}
-
-
-The class which implements the sequence behavior provided by the
-module is available for subclassing as well:
-
-\begin{classdesc}{FileInput}{\optional{files\optional{,
- inplace\optional{, backup\optional{,
- mode\optional{, openhook}}}}}}
- Class \class{FileInput} is the implementation; its methods
- \method{filename()}, \method{fileno()}, \method{lineno()},
- \method{fileline()}, \method{isfirstline()}, \method{isstdin()},
- \method{nextfile()} and \method{close()} correspond to the functions
- of the same name in the module.
- In addition it has a \method{readline()} method which
- returns the next input line, and a \method{__getitem__()} method
- which implements the sequence behavior. The sequence must be
- accessed in strictly sequential order; random access and
- \method{readline()} cannot be mixed.
-
- With \var{mode} you can specify which file mode will be passed to
- \function{open()}. It must be one of \code{'r'}, \code{'rU'},
- \code{'U'} and \code{'rb'}.
-
- The \var{openhook}, when given, must be a function that takes two arguments,
- \var{filename} and \var{mode}, and returns an accordingly opened
- file-like object.
- You cannot use \var{inplace} and \var{openhook} together.
-
- \versionchanged[Added the \var{mode} and \var{openhook} parameters]{2.5}
-\end{classdesc}
-
-\strong{Optional in-place filtering:} if the keyword argument
-\code{\var{inplace}=1} is passed to \function{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 keyword argument \code{\var{backup}='.<some
-extension>'} is also given, it specifies the extension for the backup
-file, and the backup file remains around; by default, the extension is
-\code{'.bak'} and it is deleted when the output file is closed. In-place
-filtering is disabled when standard input is read.
-
-\strong{Caveat:} The current implementation does not work for MS-DOS
-8+3 filesystems.
-
-
-The two following opening hooks are provided by this module:
-
-\begin{funcdesc}{hook_compressed}{filename, mode}
- Transparently opens files compressed with gzip and bzip2 (recognized
- by the extensions \code{'.gz'} and \code{'.bz2'}) using the \module{gzip}
- and \module{bz2} modules. If the filename extension is not \code{'.gz'}
- or \code{'.bz2'}, the file is opened normally (ie,
- using \function{open()} without any decompression).
-
- Usage example:
- \samp{fi = fileinput.FileInput(openhook=fileinput.hook_compressed)}
-
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{hook_encoded}{encoding}
- Returns a hook which opens each file with \function{codecs.open()},
- using the given \var{encoding} to read the file.
-
- Usage example:
- \samp{fi = fileinput.FileInput(openhook=fileinput.hook_encoded("iso-8859-1"))}
-
- \note{With this hook, \class{FileInput} might return Unicode strings
- depending on the specified \var{encoding}.}
- \versionadded{2.5}
-\end{funcdesc}
-
diff --git a/Doc/lib/libfnmatch.tex b/Doc/lib/libfnmatch.tex
deleted file mode 100644
index 1ac46bd..0000000
--- a/Doc/lib/libfnmatch.tex
+++ /dev/null
@@ -1,86 +0,0 @@
-\section{\module{fnmatch} ---
- \UNIX{} filename pattern matching}
-
-\declaremodule{standard}{fnmatch}
-\modulesynopsis{\UNIX\ shell style filename pattern matching.}
-
-
-\index{filenames!wildcard expansion}
-
-This module provides support for \UNIX{} shell-style wildcards, which
-are \emph{not} the same as regular expressions (which are documented
-in the \refmodule{re}\refstmodindex{re} module). The special
-characters used in shell-style wildcards are:
-
-\begin{tableii}{c|l}{code}{Pattern}{Meaning}
- \lineii{*}{matches everything}
- \lineii{?}{matches any single character}
- \lineii{[\var{seq}]}{matches any character in \var{seq}}
- \lineii{[!\var{seq}]}{matches any character not in \var{seq}}
-\end{tableii}
-
-Note that the filename separator (\code{'/'} on \UNIX) is \emph{not}
-special to this module. See module
-\refmodule{glob}\refstmodindex{glob} for pathname expansion
-(\refmodule{glob} uses \function{fnmatch()} to match pathname
-segments). Similarly, filenames starting with a period are
-not special for this module, and are matched by the \code{*} and
-\code{?} patterns.
-
-
-\begin{funcdesc}{fnmatch}{filename, pattern}
-Test whether the \var{filename} string matches the \var{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 \function{fnmatchcase()}
-instead.
-
-This example will print all file names in the current directory with the
-extension \code{.txt}:
-
-\begin{verbatim}
-import fnmatch
-import os
-
-for file in os.listdir('.'):
- if fnmatch.fnmatch(file, '*.txt'):
- print file
-\end{verbatim}
-
-\end{funcdesc}
-
-\begin{funcdesc}{fnmatchcase}{filename, pattern}
-Test whether \var{filename} matches \var{pattern}, returning true or
-false; the comparison is case-sensitive.
-\end{funcdesc}
-
-\begin{funcdesc}{filter}{names, pattern}
-Return the subset of the list of \var{names} that match \var{pattern}.
-It is the same as \code{[n for n in names if fnmatch(n, pattern)]}, but
-implemented more efficiently.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{translate}{pattern}
-Return the shell-style \var{pattern} converted to a regular
-expression.
-
-Example:
-
-\begin{verbatim}
->>> import fnmatch, re
->>>
->>> regex = fnmatch.translate('*.txt')
->>> regex
-'.*\\.txt$'
->>> reobj = re.compile(regex)
->>> print reobj.match('foobar.txt')
-<_sre.SRE_Match object at 0x...>
-\end{verbatim}
-\end{funcdesc}
-
-\begin{seealso}
- \seemodule{glob}{\UNIX{} shell-style path expansion.}
-\end{seealso}
diff --git a/Doc/lib/libformatter.tex b/Doc/lib/libformatter.tex
deleted file mode 100644
index d7c5a6b..0000000
--- a/Doc/lib/libformatter.tex
+++ /dev/null
@@ -1,329 +0,0 @@
-\section{\module{formatter} ---
- Generic output formatting}
-
-\declaremodule{standard}{formatter}
-\modulesynopsis{Generic output formatter and device interface.}
-
-
-
-This module supports two interface definitions, each with multiple
-implementations. The \emph{formatter} interface is used by the
-\class{HTMLParser} class of the \refmodule{htmllib} module, and the
-\emph{writer} interface is required by the formatter interface.
-\withsubitem{(class in htmllib)}{\ttindex{HTMLParser}}
-
-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.
-
-
-\subsection{The Formatter Interface \label{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:
-
-
-\begin{datadesc}{AS_IS}
-Value which can be used in the font specification passed to the
-\code{push_font()} method described below, or as the new value to any
-other \code{push_\var{property}()} method. Pushing the \code{AS_IS}
-value allows the corresponding \code{pop_\var{property}()} method to
-be called without having to track whether the property was changed.
-\end{datadesc}
-
-The following attributes are defined for formatter instance objects:
-
-
-\begin{memberdesc}[formatter]{writer}
-The writer instance with which the formatter interacts.
-\end{memberdesc}
-
-
-\begin{methoddesc}[formatter]{end_paragraph}{blanklines}
-Close any open paragraphs and insert at least \var{blanklines}
-before the next paragraph.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{add_line_break}{}
-Add a hard line break if one does not already exist. This does not
-break the logical paragraph.
-\end{methoddesc}
-
-\begin{methoddesc}[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
-\method{send_line_break()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{add_flowing_data}{data}
-Provide data which should be formatted with collapsed whitespace.
-Whitespace from preceding and successive calls to
-\method{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.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \var{data}.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \var{format} value is a string, it is interpreted as a
-format specification for \var{counter}, which should be an integer.
-The result of this formatting becomes the value of the label; if
-\var{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
-\method{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 \character{1} represents the counter value formatter as an
-Arabic number, the characters \character{A} and \character{a}
-represent alphabetic representations of the counter value in upper and
-lower case, respectively, and \character{I} and \character{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.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{flush_softspace}{}
-Send any pending whitespace buffered from a previous call to
-\method{add_flowing_data()} to the associated writer object. This
-should be called before any direct manipulation of the writer object.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{push_alignment}{align}
-Push a new alignment setting onto the alignment stack. This may be
-\constant{AS_IS} if no change is desired. If the alignment value is
-changed from the previous setting, the writer's \method{new_alignment()}
-method is called with the \var{align} value.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{pop_alignment}{}
-Restore the previous alignment.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{push_font}{\code{(}size, italic, bold, teletype\code{)}}
-Change some or all font properties of the writer object. Properties
-which are not set to \constant{AS_IS} are set to the values passed in
-while others are maintained at their current settings. The writer's
-\method{new_font()} method is called with the fully resolved font
-specification.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{pop_font}{}
-Restore the previous font.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{push_margin}{margin}
-Increase the number of left margin indentations by one, associating
-the logical tag \var{margin} with the new indentation. The initial
-margin level is \code{0}. Changed values of the logical tag must be
-true values; false values other than \constant{AS_IS} are not
-sufficient to change the margin.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{pop_margin}{}
-Restore the previous margin.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \constant{AS_IS} values, is passed to the
-writer's \method{new_styles()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{pop_style}{\optional{n\code{ = 1}}}
-Pop the last \var{n} style specifications passed to
-\method{push_style()}. A tuple representing the revised stack,
-including \constant{AS_IS} values, is passed to the writer's
-\method{new_styles()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{set_spacing}{spacing}
-Set the spacing style for the writer.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{assert_line_data}{\optional{flag\code{ = 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 \var{flag} argument can be set to false if
-the writer manipulations produced a hard line break at the end of the
-output.
-\end{methoddesc}
-
-
-\subsection{Formatter Implementations \label{formatter-impls}}
-
-Two implementations of formatter objects are provided by this module.
-Most applications may use one of these classes without modification or
-subclassing.
-
-\begin{classdesc}{NullFormatter}{\optional{writer}}
-A formatter which does nothing. If \var{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.
-\end{classdesc}
-
-\begin{classdesc}{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.
-\end{classdesc}
-
-
-
-\subsection{The Writer Interface \label{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.
-
-
-\begin{methoddesc}[writer]{flush}{}
-Flush any buffered output or device control events.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{new_alignment}{align}
-Set the alignment style. The \var{align} value can be any object,
-but by convention is a string or \code{None}, where \code{None}
-indicates that the writer's ``preferred'' alignment should be used.
-Conventional \var{align} values are \code{'left'}, \code{'center'},
-\code{'right'}, and \code{'justify'}.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{new_font}{font}
-Set the font style. The value of \var{font} will be \code{None},
-indicating that the device's default font should be used, or a tuple
-of the form \code{(}\var{size}, \var{italic}, \var{bold},
-\var{teletype}\code{)}. 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 \var{italic}, \var{bold}, and
-\var{teletype} values are Boolean values specifying which of those
-font attributes should be used.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{new_margin}{margin, level}
-Set the margin level to the integer \var{level} and the logical tag
-to \var{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
-\var{level}.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{new_spacing}{spacing}
-Set the spacing style to \var{spacing}.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{new_styles}{styles}
-Set additional styles. The \var{styles} value is a tuple of
-arbitrary values; the value \constant{AS_IS} should be ignored. The
-\var{styles} tuple may be interpreted either as a set or as a stack
-depending on the requirements of the application and writer
-implementation.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{send_line_break}{}
-Break the current line.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{send_paragraph}{blankline}
-Produce a paragraph separation of at least \var{blankline} blank
-lines, or the equivalent. The \var{blankline} value will be an
-integer. Note that the implementation will receive a call to
-\method{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.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \method{send_line_break()}.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{methoddesc}[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
-\method{send_formatted_data()} interface.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{send_label_data}{data}
-Set \var{data} to the left of the current left margin, if possible.
-The value of \var{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.
-\end{methoddesc}
-
-
-\subsection{Writer Implementations \label{writer-impls}}
-
-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.
-
-\begin{classdesc}{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.
-\end{classdesc}
-
-\begin{classdesc}{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.
-\end{classdesc}
-
-\begin{classdesc}{DumbWriter}{\optional{file\optional{, maxcol\code{ = 72}}}}
-Simple writer class which writes output on the file object passed in
-as \var{file} or, if \var{file} is omitted, on standard output. The
-output is simply word-wrapped to the number of columns specified by
-\var{maxcol}. This class is suitable for reflowing a sequence of
-paragraphs.
-\end{classdesc}
diff --git a/Doc/lib/libfpectl.tex b/Doc/lib/libfpectl.tex
deleted file mode 100644
index cca2314..0000000
--- a/Doc/lib/libfpectl.tex
+++ /dev/null
@@ -1,127 +0,0 @@
-\section{\module{fpectl} ---
- Floating point exception control}
-
-\declaremodule{extension}{fpectl}
- \platform{Unix}
-\moduleauthor{Lee Busby}{busby1@llnl.gov}
-\sectionauthor{Lee Busby}{busby1@llnl.gov}
-\modulesynopsis{Provide control for floating point exception handling.}
-
-\note{The \module{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.}
-
-Most computers carry out floating point operations\index{IEEE-754}
-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
-
-\begin{verbatim}
->>> import math
->>> math.exp(1000)
-inf
->>> math.exp(1000) / math.exp(1000)
-nan
-\end{verbatim}
-
-(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 \module{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 \constant{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,
-\constant{SIGFPE} is trapped and converted into the Python
-\exception{FloatingPointError} exception.
-
-The \module{fpectl} module defines the following functions and
-may raise the given exception:
-
-\begin{funcdesc}{turnon_sigfpe}{}
-Turn on the generation of \constant{SIGFPE},
-and set up an appropriate signal handler.
-\end{funcdesc}
-
-\begin{funcdesc}{turnoff_sigfpe}{}
-Reset default handling of floating point exceptions.
-\end{funcdesc}
-
-\begin{excdesc}{FloatingPointError}
-After \function{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.
-\end{excdesc}
-
-
-\subsection{Example \label{fpectl-example}}
-
-The following example demonstrates how to start up and test operation of
-the \module{fpectl} module.
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
-
-
-\subsection{Limitations and other considerations \label{fpectl-limitations}}
-
-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 \module{fpectl} to control your particular hardware.
-
-Conversion of an IEEE-754 exception to a Python exception requires
-that the wrapper macros \code{PyFPE_START_PROTECT} and
-\code{PyFPE_END_PROTECT} be inserted into your code in an appropriate
-fashion. Python itself has been modified to support the
-\module{fpectl} module, but many other codes of interest to numerical
-analysts have not.
-
-The \module{fpectl} module is not thread-safe.
-
-\begin{seealso}
- \seetext{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}.}
-\end{seealso}
diff --git a/Doc/lib/libfpformat.tex b/Doc/lib/libfpformat.tex
deleted file mode 100644
index a3a6282..0000000
--- a/Doc/lib/libfpformat.tex
+++ /dev/null
@@ -1,54 +0,0 @@
-\section{\module{fpformat} ---
- Floating point conversions}
-
-\declaremodule{standard}{fpformat}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{General floating point formatting functions.}
-
-
-The \module{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 \code{\%} string interpolation operator.}
-
-The \module{fpformat} module defines the following functions and an
-exception:
-
-
-\begin{funcdesc}{fix}{x, digs}
-Format \var{x} as \code{[-]ddd.ddd} with \var{digs} digits after the
-point and at least one digit before.
-If \code{\var{digs} <= 0}, the decimal point is suppressed.
-
-\var{x} can be either a number or a string that looks like
-one. \var{digs} is an integer.
-
-Return value is a string.
-\end{funcdesc}
-
-\begin{funcdesc}{sci}{x, digs}
-Format \var{x} as \code{[-]d.dddE[+-]ddd} with \var{digs} digits after the
-point and exactly one digit before.
-If \code{\var{digs} <= 0}, one digit is kept and the point is suppressed.
-
-\var{x} can be either a real number, or a string that looks like
-one. \var{digs} is an integer.
-
-Return value is a string.
-\end{funcdesc}
-
-\begin{excdesc}{NotANumber}
-Exception raised when a string passed to \function{fix()} or
-\function{sci()} as the \var{x} parameter does not look like a number.
-This is a subclass of \exception{ValueError} when the standard
-exceptions are strings. The exception value is the improperly
-formatted string that caused the exception to be raised.
-\end{excdesc}
-
-Example:
-
-\begin{verbatim}
->>> import fpformat
->>> fpformat.fix(1.23, 1)
-'1.2'
-\end{verbatim}
diff --git a/Doc/lib/libftplib.tex b/Doc/lib/libftplib.tex
deleted file mode 100644
index 1ce5f9b..0000000
--- a/Doc/lib/libftplib.tex
+++ /dev/null
@@ -1,300 +0,0 @@
-\section{\module{ftplib} ---
- FTP protocol client}
-
-\declaremodule{standard}{ftplib}
-\modulesynopsis{FTP protocol client (requires sockets).}
-
-\indexii{FTP}{protocol}
-\index{FTP!\module{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
-\refmodule{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 \module{ftplib} module:
-
-\begin{verbatim}
->>> 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()
-\end{verbatim}
-
-The module defines the following items:
-
-\begin{classdesc}{FTP}{\optional{host\optional{, user\optional{,
- passwd\optional{, acct\optional{, timeout}}}}}}
-Return a new instance of the \class{FTP} class. When
-\var{host} is given, the method call \code{connect(\var{host})} is
-made. When \var{user} is given, additionally the method call
-\code{login(\var{user}, \var{passwd}, \var{acct})} is made (where
-\var{passwd} and \var{acct} default to the empty string when not given).
-The optional \var{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[\var{timeout} was added]{2.6}
-\end{classdesc}
-
-\begin{datadesc}{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
-\exception{socket.error} and \exception{IOError}.
-\end{datadesc}
-
-\begin{excdesc}{error_reply}
-Exception raised when an unexpected reply is received from the server.
-\end{excdesc}
-
-\begin{excdesc}{error_temp}
-Exception raised when an error code in the range 400--499 is received.
-\end{excdesc}
-
-\begin{excdesc}{error_perm}
-Exception raised when an error code in the range 500--599 is received.
-\end{excdesc}
-
-\begin{excdesc}{error_proto}
-Exception raised when a reply is received from the server that does
-not begin with a digit in the range 1--5.
-\end{excdesc}
-
-
-\begin{seealso}
- \seemodule{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.}
- \seetext{The file \file{Tools/scripts/ftpmirror.py}\index{ftpmirror.py}
- in the Python source distribution is a script that can mirror
- FTP sites, or portions thereof, using the \module{ftplib} module.
- It can be used as an extended example that applies this module.}
-\end{seealso}
-
-
-\subsection{FTP Objects \label{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 \samp{lines} for the text version or
-\samp{binary} for the binary version.
-
-\class{FTP} instances have the following methods:
-
-\begin{methoddesc}[FTP]{set_debuglevel}{level}
-Set the instance's debugging level. This controls the amount of
-debugging output printed. The default, \code{0}, produces no
-debugging output. A value of \code{1} produces a moderate amount of
-debugging output, generally a single line per request. A value of
-\code{2} or higher produces the maximum amount of debugging output,
-logging each line sent and received on the control connection.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{connect}{host\optional{, port\optional{, timeout}}}
-Connect to the given host and port. The default port number is \code{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 \var{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[\var{timeout} was added]{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}[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.)
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{login}{\optional{user\optional{, passwd\optional{, acct}}}}
-Log in as the given \var{user}. The \var{passwd} and \var{acct}
-parameters are optional and default to the empty string. If no
-\var{user} is specified, it defaults to \code{'anonymous'}. If
-\var{user} is \code{'anonymous'}, the default \var{passwd} is
-\code{'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.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{abort}{}
-Abort a file transfer that is in progress. Using this does not always
-work, but it's worth a try.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{sendcmd}{command}
-Send a simple command string to the server and return the response
-string.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{retrbinary}{command,
- callback\optional{, maxblocksize\optional{, rest}}}
-Retrieve a file in binary transfer mode. \var{command} should be an
-appropriate \samp{RETR} command: \code{'RETR \var{filename}'}.
-The \var{callback} function is called for each block of data received,
-with a single string argument giving the data block.
-The optional \var{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
-\var{callback}). A reasonable default is chosen. \var{rest} means the
-same thing as in the \method{transfercmd()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{retrlines}{command\optional{, callback}}
-Retrieve a file or directory listing in \ASCII{} transfer mode.
-\var{command} should be an appropriate \samp{RETR} command (see
-\method{retrbinary()}) or a \samp{LIST} command (usually just the string
-\code{'LIST'}). The \var{callback} function is called for each line,
-with the trailing CRLF stripped. The default \var{callback} prints
-the line to \code{sys.stdout}.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{set_pasv}{boolean}
-Enable ``passive'' mode if \var{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.)
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{storbinary}{command, file\optional{, blocksize}}
-Store a file in binary transfer mode. \var{command} should be an
-appropriate \samp{STOR} command: \code{"STOR \var{filename}"}.
-\var{file} is an open file object which is read until \EOF{} using its
-\method{read()} method in blocks of size \var{blocksize} to provide the
-data to be stored. The \var{blocksize} argument defaults to 8192.
-\versionchanged[default for \var{blocksize} added]{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{storlines}{command, file}
-Store a file in \ASCII{} transfer mode. \var{command} should be an
-appropriate \samp{STOR} command (see \method{storbinary()}). Lines are
-read until \EOF{} from the open file object \var{file} using its
-\method{readline()} method to provide the data to be stored.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{transfercmd}{cmd\optional{, rest}}
-Initiate a transfer over the data connection. If the transfer is
-active, send a \samp{EPRT} or \samp{PORT} command and the transfer command specified
-by \var{cmd}, and accept the connection. If the server is passive,
-send a \samp{EPSV} or \samp{PASV} command, connect to it, and start the transfer
-command. Either way, return the socket for the connection.
-
-If optional \var{rest} is given, a \samp{REST} command is
-sent to the server, passing \var{rest} as an argument. \var{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 \var{rest} be a string containing characters
-in the printable range from ASCII code 33 to ASCII code 126. The
-\method{transfercmd()} method, therefore, converts
-\var{rest} to a string, but no check is
-performed on the string's contents. If the server does
-not recognize the \samp{REST} command, an
-\exception{error_reply} exception will be raised. If this happens,
-simply call \method{transfercmd()} without a \var{rest} argument.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{ntransfercmd}{cmd\optional{, rest}}
-Like \method{transfercmd()}, but returns a tuple of the data
-connection and the expected size of the data. If the expected size
-could not be computed, \code{None} will be returned as the expected
-size. \var{cmd} and \var{rest} means the same thing as in
-\method{transfercmd()}.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{nlst}{argument\optional{, \ldots}}
-Return a list of files as returned by the \samp{NLST} command. The
-optional \var{argument} is a directory to list (default is the current
-server directory). Multiple arguments can be used to pass
-non-standard options to the \samp{NLST} command.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{dir}{argument\optional{, \ldots}}
-Produce a directory listing as returned by the \samp{LIST} command,
-printing it to standard output. The optional \var{argument} is a
-directory to list (default is the current server directory). Multiple
-arguments can be used to pass non-standard options to the \samp{LIST}
-command. If the last argument is a function, it is used as a
-\var{callback} function as for \method{retrlines()}; the default
-prints to \code{sys.stdout}. This method returns \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{rename}{fromname, toname}
-Rename file \var{fromname} on the server to \var{toname}.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{delete}{filename}
-Remove the file named \var{filename} from the server. If successful,
-returns the text of the response, otherwise raises
-\exception{error_perm} on permission errors or
-\exception{error_reply} on other errors.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{cwd}{pathname}
-Set the current directory on the server.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{mkd}{pathname}
-Create a new directory on the server.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{pwd}{}
-Return the pathname of the current directory on the server.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{rmd}{dirname}
-Remove the directory named \var{dirname} on the server.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{size}{filename}
-Request the size of the file named \var{filename} on the server. On
-success, the size of the file is returned as an integer, otherwise
-\code{None} is returned. Note that the \samp{SIZE} command is not
-standardized, but is supported by many common server implementations.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{quit}{}
-Send a \samp{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
-\samp{QUIT} command. This implies a call to the \method{close()}
-method which renders the \class{FTP} instance useless for subsequent
-calls (see below).
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{close}{}
-Close the connection unilaterally. This should not be applied to an
-already closed connection such as after a successful call to
-\method{quit()}. After this call the \class{FTP} instance should not
-be used any more (after a call to \method{close()} or
-\method{quit()} you cannot reopen the connection by issuing another
-\method{login()} method).
-\end{methoddesc}
diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex
deleted file mode 100644
index 0fcc4f4..0000000
--- a/Doc/lib/libfuncs.tex
+++ /dev/null
@@ -1,1125 +0,0 @@
-\section{Built-in Functions \label{built-in-funcs}}
-
-The Python interpreter has a number of functions built into it that
-are always available. They are listed here in alphabetical order.
-
-
-\setindexsubitem{(built-in function)}
-
-\begin{funcdesc}{__import__}{name\optional{, globals\optional{, locals\optional{, fromlist\optional{, level}}}}}
- This function is invoked by the \keyword{import}\stindex{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
- \module{ihooks}\refstmodindex{ihooks} and
- \refmodule{rexec}\refstmodindex{rexec}. See also the built-in
- module \refmodule{imp}\refbimodindex{imp}, which defines some useful
- operations out of which you can build your own
- \function{__import__()} function.
-
- For example, the statement \samp{import spam} results in the
- following call: \code{__import__('spam',} \code{globals(),}
- \code{locals(), [], -1)}; the statement \samp{from spam.ham import eggs}
- results in \samp{__import__('spam.ham', globals(), locals(),
- ['eggs'], -1)}. Note that even though \code{locals()} and
- \code{['eggs']} are passed in as arguments, the
- \function{__import__()} function does not set the local variable
- named \code{eggs}; this is done by subsequent code that is generated
- for the import statement. (In fact, the standard implementation
- does not use its \var{locals} argument at all, and uses its
- \var{globals} only to determine the package context of the
- \keyword{import} statement.)
-
- When the \var{name} variable is of the form \code{package.module},
- normally, the top-level package (the name up till the first dot) is
- returned, \emph{not} the module named by \var{name}. However, when
- a non-empty \var{fromlist} argument is given, the module named by
- \var{name} is returned. This is done for compatibility with the
- bytecode generated for the different kinds of import statement; when
- using \samp{import spam.ham.eggs}, the top-level package \module{spam}
- must be placed in the importing namespace, but when using \samp{from
- spam.ham import eggs}, the \code{spam.ham} subpackage must be used
- to find the \code{eggs} variable. As a workaround for this
- behavior, use \function{getattr()} to extract the desired
- components. For example, you could define the following helper:
-
-\begin{verbatim}
-def my_import(name):
- mod = __import__(name)
- components = name.split('.')
- for comp in components[1:]:
- mod = getattr(mod, comp)
- return mod
-\end{verbatim}
-
- \var{level} specifies whether to use absolute or relative imports.
- The default is \code{-1} which indicates both absolute and relative
- imports will be attempted. \code{0} means only perform absolute imports.
- Positive values for \var{level} indicate the number of parent directories
- to search relative to the directory of the module calling
- \function{__import__}.
-\versionchanged[The level parameter was added]{2.5}
-\versionchanged[Keyword support for parameters was added]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{all}{iterable}
- Return True if all elements of the \var{iterable} are true.
- Equivalent to:
- \begin{verbatim}
- def all(iterable):
- for element in iterable:
- if not element:
- return False
- return True
- \end{verbatim}
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{any}{iterable}
- Return True if any element of the \var{iterable} is true.
- Equivalent to:
- \begin{verbatim}
- def any(iterable):
- for element in iterable:
- if element:
- return True
- return False
- \end{verbatim}
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{basestring}{}
- This abstract type is the superclass for \class{str}.
- It cannot be called or instantiated, but it can be used to test whether
- an object is an instance of \class{str}.
- \code{isinstance(obj, basestring)} is equivalent to
- \code{isinstance(obj, str)}.
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{bin}{x}
- Convert an integer number to a binary string.
- The result is a valid Python expression. If \var{x} is not a Python
- \class{int} object, it has to define an \method{__index__} method
- that returns an integer.
- \versionadded{3.0}
-\end{funcdesc}
-
-\begin{funcdesc}{bool}{\optional{x}}
- Convert a value to a Boolean, using the standard truth testing
- procedure. If \var{x} is false or omitted, this returns
- \constant{False}; otherwise it returns \constant{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 \constant{False} and \constant{True}.
-
- \indexii{Boolean}{type}
- \versionadded{2.2.1}
- \versionchanged[If no argument is given, this function returns
- \constant{False}]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{chr}{i}
- Return the Unicode string of one character whose Unicode code is the
- integer \var{i}. For example, \code{unichr(97)} returns the string
- \code{u'a'}. This is the inverse of \function{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].
- \exception{ValueError} is raised otherwise.
-\end{funcdesc}
-
-\begin{funcdesc}{classmethod}{function}
- Return a class method for \var{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:
-
-\begin{verbatim}
-class C:
- @classmethod
- def f(cls, arg1, arg2, ...): ...
-\end{verbatim}
-
- The \code{@classmethod} form is a function decorator -- see the description
- of function definitions in chapter 7 of the
- \citetitle[../ref/ref.html]{Python Reference Manual} for details.
-
- It can be called either on the class (such as \code{C.f()}) or on an
- instance (such as \code{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 \Cpp{} or Java static methods.
- If you want those, see \function{staticmethod()} in this section.
-
- For more information on class methods, consult the documentation on the
- standard type hierarchy in chapter 3 of the
- \citetitle[../ref/types.html]{Python Reference Manual} (at the bottom).
- \versionadded{2.2}
- \versionchanged[Function decorator syntax added]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{cmp}{x, y}
- Compare the two objects \var{x} and \var{y} and return an integer
- according to the outcome. The return value is negative if \code{\var{x}
- < \var{y}}, zero if \code{\var{x} == \var{y}} and strictly positive if
- \code{\var{x} > \var{y}}.
-\end{funcdesc}
-
-\begin{funcdesc}{compile}{source, filename, mode\optional{,
- flags\optional{, dont_inherit}}}
- Compile the \var{source} into a code object. Code objects can be
- executed by a call to \function{exec()} or evaluated by a call to
- \function{eval()}. The \var{filename} argument should
- give the file from which the code was read; pass some recognizable value
- if it wasn't read from a file (\code{'<string>'} is commonly used).
- The \var{mode} argument specifies what kind of code must be
- compiled; it can be \code{'exec'} if \var{source} consists of a
- sequence of statements, \code{'eval'} if it consists of a single
- expression, or \code{'single'} if it consists of a single
- interactive statement (in the latter case, expression statements
- that evaluate to something else than \code{None} will be printed).
-
- When compiling multi-line statements, two caveats apply: line
- endings must be represented by a single newline character
- (\code{'\e n'}), and the input must be terminated by at least one
- newline character. If line endings are represented by
- \code{'\e r\e n'}, use the string \method{replace()} method to
- change them into \code{'\e n'}.
-
- The optional arguments \var{flags} and \var{dont_inherit}
- (which are new in Python 2.2) control which future statements (see
- \pep{236}) affect the compilation of \var{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 \var{flags} argument is given and \var{dont_inherit} is not
- (or is zero) then the future statements specified by the \var{flags}
- argument are used in addition to those that would be used anyway.
- If \var{dont_inherit} is a non-zero integer then the \var{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 \member{compiler_flag}
- attribute on the \class{_Feature} instance in the
- \module{__future__} module.
-\end{funcdesc}
-
-\begin{funcdesc}{complex}{\optional{real\optional{, imag}}}
- Create a complex number with the value \var{real} + \var{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 \var{imag} is omitted, it defaults to zero and the function
- serves as a numeric conversion function like \function{int()},
- \function{long()} and \function{float()}. If both arguments
- are omitted, returns \code{0j}.
-\end{funcdesc}
-
-\begin{funcdesc}{delattr}{object, name}
- This is a relative of \function{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,
- \code{delattr(\var{x}, '\var{foobar}')} is equivalent to
- \code{del \var{x}.\var{foobar}}.
-\end{funcdesc}
-
-\begin{funcdesc}{dict}{\optional{arg}}
- Return a new dictionary initialized from an optional positional
- argument or from a set of keyword arguments.
- If no arguments are given, return a new empty dictionary.
- If the positional argument \var{arg} is a mapping object, return a dictionary
- mapping the same keys to the same values as does the mapping object.
- Otherwise the positional argument must be a sequence, a container that
- supports iteration, or an iterator object. The elements of the argument
- must each also be of one of those kinds, and each must in turn contain
- exactly two objects. The first is used as a key in the new dictionary,
- and the second as the key's value. If a given key is seen more than
- once, the last value associated with it is retained in the new
- dictionary.
-
- If keyword arguments are given, the keywords themselves with their
- associated values are added as items to the dictionary. If a key
- is specified both in the positional argument and as a keyword argument,
- the value associated with the keyword is retained in the dictionary.
- For example, these all return a dictionary equal to
- \code{\{"one": 2, "two": 3\}}:
-
- \begin{itemize}
- \item \code{dict(\{'one': 2, 'two': 3\})}
- \item \code{dict(\{'one': 2, 'two': 3\}.items())}
- \item \code{dict(\{'one': 2, 'two': 3\}.iteritems())}
- \item \code{dict(zip(('one', 'two'), (2, 3)))}
- \item \code{dict([['two', 3], ['one', 2]])}
- \item \code{dict(one=2, two=3)}
- \item \code{dict([(['one', 'two'][i-2], i) for i in (2, 3)])}
- \end{itemize}
-
- \versionadded{2.2}
- \versionchanged[Support for building a dictionary from keyword
- arguments added]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{dir}{\optional{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 \method{__dir__()}, this method will be
- called and must return the list of attributes. This allows objects that
- implement a custom \function{__getattr__()} or \function{__getattribute__()}
- function to customize the way \function{dir()} reports their attributes.
-
- If the object does not provide \method{__dir__()}, the function tries its best
- to gather information from the object's \member{__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
- \function{__getattr__()}.
-
- The default \function{dir()} mechanism behaves differently with different
- types of objects, as it attempts to produce the most relevant, rather than
- complete, information:
- \begin{itemize}
- \item If the object is a module object, the list contains the names of the
- module's attributes.
- \item 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.
- \item 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.
- \end{itemize}
-
- The resulting list is sorted alphabetically. For example:
-
-\begin{verbatim}
->>> 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']
-\end{verbatim}
-
- \note{Because \function{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.}
-\end{funcdesc}
-
-\begin{funcdesc}{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
- \code{(\var{a} // \var{b}, \var{a} \%{} \var{b})}.
- For floating point numbers the result is \code{(\var{q}, \var{a} \%{}
- \var{b})}, where \var{q} is usually \code{math.floor(\var{a} /
- \var{b})} but may be 1 less than that. In any case \code{\var{q} *
- \var{b} + \var{a} \%{} \var{b}} is very close to \var{a}, if
- \code{\var{a} \%{} \var{b}} is non-zero it has the same sign as
- \var{b}, and \code{0 <= abs(\var{a} \%{} \var{b}) < abs(\var{b})}.
-
- \versionchanged[Using \function{divmod()} with complex numbers is
- deprecated]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{enumerate}{iterable}
- Return an enumerate object. \var{iterable} must be a sequence, an iterator, or
- some other object which supports iteration. The \method{__next__()} method of
- the iterator returned by \function{enumerate()} returns a tuple containing a
- count (from zero) and the corresponding value obtained from iterating over
- \var{iterable}. \function{enumerate()} is useful for obtaining an indexed
- series: \code{(0, seq[0])}, \code{(1, seq[1])}, \code{(2, seq[2])}, \ldots.
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{eval}{expression\optional{, globals\optional{, locals}}}
- The arguments are a string and optional globals and locals. If provided,
- \var{globals} must be a dictionary. If provided, \var{locals} can be
- any mapping object. \versionchanged[formerly \var{locals} was required
- to be a dictionary]{2.4}
-
- The \var{expression} argument is parsed and evaluated as a Python
- expression (technically speaking, a condition list) using the
- \var{globals} and \var{locals} dictionaries as global and local name
- space. If the \var{globals} dictionary is present and lacks
- '__builtins__', the current globals are copied into \var{globals} before
- \var{expression} is parsed. This means that \var{expression}
- normally has full access to the standard
- \refmodule[builtin]{__builtin__} module and restricted environments
- are propagated. If the \var{locals} dictionary is omitted it defaults to
- the \var{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:
-
-\begin{verbatim}
->>> x = 1
->>> print eval('x+1')
-2
-\end{verbatim}
-
- This function can also be used to execute arbitrary code objects
- (such as those created by \function{compile()}). In this case pass
- a code object instead of a string. The code object must have been
- compiled passing \code{'eval'} as the \var{kind} argument.
-
- Hints: dynamic execution of statements is supported by the
- \function{exec()} function. The
- \function{globals()} and \function{locals()} functions returns the
- current global and local dictionary, respectively, which may be
- useful to pass around for use by \function{eval()} or
- \function{exec()}.
-\end{funcdesc}
-
-\begin{funcdesc}{exec}{object\optional{, globals\optional{, locals}}}
- This function supports dynamic execution of Python code.
- \var{object} must be either a string, an open file object, or
- a code object. If it is a string, the string is parsed as a suite of
- Python statements which is then executed (unless a syntax error
- occurs). If it is an open file, the file is parsed until \EOF{} and
- executed. If it is a code object, it is simply executed. In all
- cases, the code that's executed is expected to be valid as file
- input (see the section ``File input'' in the Reference Manual).
- Be aware that the \keyword{return} and \keyword{yield} statements may
- not be used outside of function definitions even within the context of
- code passed to the \function{exec()} function.
- The return value is \code{None}.
-
- In all cases, if the optional parts are omitted, the code is executed
- in the current scope. If only \var{globals} is provided, it must be
- a dictionary, which will be used for both the global and the local
- variables. If \var{globals} and \var{locals} are given, they are used
- for the global and local variables, respectively. If provided,
- \var{locals} can be any mapping object.
-
- If the \var{globals} dictionary does not contain a value for the
- key \code{__builtins__}, a reference to the dictionary of the built-in
- module \module{__builtin__} is inserted under that key. That way you
- can control what builtins are available to the executed code by
- inserting your own \code{__builtins__} dictionary into \var{globals}
- before passing it to \function{exec()}.
-
- \note{The built-in functions \function{globals()} and \function{locals()}
- return the current global and local dictionary, respectively, which
- may be useful to pass around for use as the second and third
- argument to \function{exec()}.}
-\end{funcdesc}
-
-\begin{funcdesc}{filter}{function, iterable}
- Construct a list from those elements of \var{iterable} for which
- \var{function} returns true. \var{iterable} may be either a sequence, a
- container which supports iteration, or an iterator, If \var{iterable}
- is a string or a tuple, the result
- also has that type; otherwise it is always a list. If \var{function} is
- \code{None}, the identity function is assumed, that is, all elements of
- \var{iterable} that are false are removed.
-
- Note that \code{filter(function, \var{iterable})} is equivalent to
- \code{[item for item in \var{iterable} if function(item)]} if function is
- not \code{None} and \code{[item for item in \var{iterable} if item]} if
- function is \code{None}.
-\end{funcdesc}
-
-\begin{funcdesc}{float}{\optional{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 \code{0.0}.
-
- \note{When passing in a string, values for NaN\index{NaN}
- and Infinity\index{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.}
-\end{funcdesc}
-
-\begin{funcdesc}{frozenset}{\optional{iterable}}
- Return a frozenset object whose elements are taken from \var{iterable}.
- Frozensets are sets that have no update methods but can be hashed and
- used as members of other sets or as dictionary keys. The elements of
- a frozenset must be immutable themselves. To represent sets of sets,
- the inner sets should also be \class{frozenset} objects. If
- \var{iterable} is not specified, returns a new empty set,
- \code{frozenset([])}.
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{getattr}{object, name\optional{, default}}
- Return the value of the named attributed of \var{object}. \var{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,
- \code{getattr(x, 'foobar')} is equivalent to \code{x.foobar}. If the
- named attribute does not exist, \var{default} is returned if provided,
- otherwise \exception{AttributeError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{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).
-\end{funcdesc}
-
-\begin{funcdesc}{hasattr}{object, name}
- The arguments are an object and a string. The result is \code{True} if the
- string is the name of one of the object's attributes, \code{False} if not.
- (This is implemented by calling \code{getattr(\var{object},
- \var{name})} and seeing whether it raises an exception or not.)
-\end{funcdesc}
-
-\begin{funcdesc}{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).
-\end{funcdesc}
-
-\begin{funcdesc}{help}{\optional{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}
-\end{funcdesc}
-
-\begin{funcdesc}{hex}{x}
- Convert an integer number to a hexadecimal string.
- The result is a valid Python expression. If \var{x} is not a Python
- \class{int} object, it has to define an \method{__index__} method
- that returns an integer.
- \versionchanged[Formerly only returned an unsigned literal]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{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 \function{id()} value. (Implementation
- note: this is the address of the object.)
-\end{funcdesc}
-
-\begin{funcdesc}{int}{\optional{x\optional{, 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
- \var{radix} argument is interpreted in the same way as for
- \function{int()}, and may only be given when \var{x} is a string.
- Otherwise, the argument may be another
- integer or a floating point number, and an integer with
- the same value is returned. Conversion of floating
- point numbers to integers truncates (towards zero). If no arguments
- are given, returns \code{0}.
-\end{funcdesc}
-
-\begin{funcdesc}{isinstance}{object, classinfo}
- Return true if the \var{object} argument is an instance of the
- \var{classinfo} argument, or of a (direct or indirect) subclass
- thereof. Also return true if \var{classinfo} is a type object
- (new-style class) and \var{object} is an object of that type or of a
- (direct or indirect) subclass thereof. If \var{object} is not a
- class instance or an object of the given type, the function always
- returns false. If \var{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 \var{classinfo} is not a class, type, or tuple of
- classes, types, and such tuples, a \exception{TypeError} exception
- is raised.
- \versionchanged[Support for a tuple of type information was added]{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{issubclass}{class, classinfo}
- Return true if \var{class} is a subclass (direct or indirect) of
- \var{classinfo}. A class is considered a subclass of itself.
- \var{classinfo} may be a tuple of class objects, in which case every
- entry in \var{classinfo} will be checked. In any other case, a
- \exception{TypeError} exception is raised.
- \versionchanged[Support for a tuple of type information was added]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{iter}{o\optional{, sentinel}}
- Return an iterator object. The first argument is interpreted very
- differently depending on the presence of the second argument.
- Without a second argument, \var{o} must be a collection object which
- supports the iteration protocol (the \method{__iter__()} method), or
- it must support the sequence protocol (the \method{__getitem__()}
- method with integer arguments starting at \code{0}). If it does not
- support either of those protocols, \exception{TypeError} is raised.
- If the second argument, \var{sentinel}, is given, then \var{o} must
- be a callable object. The iterator created in this case will call
- \var{o} with no arguments for each call to its \method{__next__()}
- method; if the value returned is equal to \var{sentinel},
- \exception{StopIteration} will be raised, otherwise the value will
- be returned.
- \versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{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).
-\end{funcdesc}
-
-\begin{funcdesc}{list}{\optional{iterable}}
- Return a list whose items are the same and in the same order as
- \var{iterable}'s items. \var{iterable} may be either a sequence, a
- container that supports iteration, or an iterator object. If
- \var{iterable} is already a list, a copy is made and returned,
- similar to \code{\var{iterable}[:]}. For instance,
- \code{list('abc')} returns \code{['a', 'b', 'c']} and \code{list(
- (1, 2, 3) )} returns \code{[1, 2, 3]}. If no argument is given,
- returns a new empty list, \code{[]}.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{map}{function, iterable, ...}
- Apply \var{function} to every item of \var{iterable} and return a list
- of the results. If additional \var{iterable} arguments are passed,
- \var{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 \code{None} items. If \var{function}
- is \code{None}, the identity function is assumed; if there are
- multiple arguments, \function{map()} returns a list consisting
- of tuples containing the corresponding items from all iterables (a kind
- of transpose operation). The \var{iterable} arguments may be a sequence
- or any iterable object; the result is always a list.
-\end{funcdesc}
-
-\begin{funcdesc}{max}{iterable\optional{, args...}\optional{key}}
- With a single argument \var{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 \var{key} argument specifies a one-argument ordering
- function like that used for \method{list.sort()}. The \var{key}
- argument, if supplied, must be in keyword form (for example,
- \samp{max(a,b,c,key=func)}).
- \versionchanged[Added support for the optional \var{key} argument]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{min}{iterable\optional{, args...}\optional{key}}
- With a single argument \var{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 \var{key} argument specifies a one-argument ordering
- function like that used for \method{list.sort()}. The \var{key}
- argument, if supplied, must be in keyword form (for example,
- \samp{min(a,b,c,key=func)}).
- \versionchanged[Added support for the optional \var{key} argument]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{next}{iterator\optional{, default}}
- Retrieve the next item from the \var{iterable} by calling its
- \method{__next__()} method. If \var{default} is given, it is returned if the
- iterator is exhausted, otherwise \exception{StopIteration} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{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[This function does not accept any arguments.
- Formerly, it accepted arguments but ignored them]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{oct}{x}
- Convert an integer number to an octal string. The
- result is a valid Python expression. If \var{x} is not a Python
- \class{int} object, it has to define an \method{__index__} method
- that returns an integer.
- \versionchanged[Formerly only returned an unsigned literal]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{open}{filename\optional{, mode\optional{, bufsize}}}
- Open a file, returning an object of the \class{file} type described
- in section~\ref{bltin-file-objects}, ``\ulink{File
- Objects}{bltin-file-objects.html}''. If the file cannot be opened,
- \exception{IOError} is raised. When opening a file, it's
- preferable to use \function{open()} instead of invoking the
- \class{file} constructor directly.
-
- The first two arguments are the same as for \code{stdio}'s
- \cfunction{fopen()}: \var{filename} is the file name to be opened,
- and \var{mode} is a string indicating how the file is to be opened.
-
- The most commonly-used values of \var{mode} are \code{'r'} for
- reading, \code{'w'} for writing (truncating the file if it already
- exists), and \code{'a'} for appending (which on \emph{some} \UNIX{}
- systems means that \emph{all} writes append to the end of the file
- regardless of the current seek position). If \var{mode} is omitted,
- it defaults to \code{'r'}. When opening a binary file, you should
- append \code{'b'} to the \var{mode} value to open the file in binary
- mode, which will improve portability. (Appending \code{'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 \var{mode}.
-
- \index{line-buffered I/O}\index{unbuffered I/O}\index{buffer size, I/O}
- \index{I/O control!buffering}
- The optional \var{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 \var{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.\footnote{
- Specifying a buffer size currently has no effect on systems that
- don't have \cfunction{setvbuf()}. The interface to specify the
- buffer size is not done using a method that calls
- \cfunction{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.}
-
- Modes \code{'r+'}, \code{'w+'} and \code{'a+'} open the file for
- updating (note that \code{'w+'} truncates the file). Append
- \code{'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 \code{'b'} has no effect.
-
- In addition to the standard \cfunction{fopen()} values \var{mode}
- may be \code{'U'} or \code{'rU'}. Python is usually built with universal
- newline support; supplying \code{'U'} opens the file as a text file, but
- lines may be terminated by any of the following: the \UNIX{} end-of-line
- convention \code{'\e n'},
- the Macintosh convention \code{'\e r'}, or the Windows
- convention \code{'\e r\e n'}. All of these external representations are seen as
- \code{'\e n'}
- by the Python program. If Python is built without universal newline support
- a \var{mode} with \code{'U'} is the same as normal text mode. Note that
- file objects so opened also have an attribute called
- \member{newlines} which has a value of \code{None} (if no newlines
- have yet been seen), \code{'\e n'}, \code{'\e r'}, \code{'\e r\e n'},
- or a tuple containing all the newline types seen.
-
- Python enforces that the mode, after stripping \code{'U'}, begins with
- \code{'r'}, \code{'w'} or \code{'a'}.
-
- \versionchanged[Restriction on first letter of mode string
- introduced]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{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, \code{ord('a')} returns the integer \code{97},
- \code{ord(u'\e u2020')} returns \code{8224}. This is the inverse of
- \function{chr()} for strings.
- If 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
- \exception{TypeError} will be raised.
-\end{funcdesc}
-
-\begin{funcdesc}{pow}{x, y\optional{, z}}
- Return \var{x} to the power \var{y}; if \var{z} is present, return
- \var{x} to the power \var{y}, modulo \var{z} (computed more
- efficiently than \code{pow(\var{x}, \var{y}) \%\ \var{z}}).
- The two-argument form \code{pow(\var{x}, \var{y})} is equivalent to using
- the power operator: \code{\var{x}**\var{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, \code{10**2} returns \code{100}, but
- \code{10**-2} returns \code{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 \var{z} is present, \var{x} and \var{y} must be of integer types,
- and \var{y} must be non-negative. (This restriction was added in
- Python 2.2. In Python 2.1 and before, floating 3-argument \code{pow()}
- returned platform-dependent results depending on floating-point
- rounding accidents.)
-\end{funcdesc}
-
-\begin{funcdesc}{property}{\optional{fget\optional{, fset\optional{,
- fdel\optional{, doc}}}}}
- Return a property attribute for new-style classes (classes that
- derive from \class{object}).
-
- \var{fget} is a function for getting an attribute value, likewise
- \var{fset} is a function for setting, and \var{fdel} a function
- for del'ing, an attribute. Typical use is to define a managed attribute x:
-
-\begin{verbatim}
-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.")
-\end{verbatim}
-
- If given, \var{doc} will be the docstring of the property attribute.
- Otherwise, the property will copy \var{fget}'s docstring (if it
- exists). This makes it possible to create read-only properties
- easily using \function{property()} as a decorator:
-
-\begin{verbatim}
-class Parrot(object):
- def __init__(self):
- self._voltage = 100000
-
- @property
- def voltage(self):
- """Get the current voltage."""
- return self._voltage
-\end{verbatim}
-
- turns the \method{voltage()} method into a ``getter'' for a read-only
- attribute with the same name.
-
- \versionadded{2.2}
- \versionchanged[Use \var{fget}'s docstring if no \var{doc} given]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{range}{\optional{start,} stop\optional{, step}}
- This is a versatile function to create sequences containing arithmetic
- progressions. It is most often used in \keyword{for} loops. The
- arguments must be plain integers. If the \var{step} argument is
- omitted, it defaults to \code{1}. If the \var{start} argument is
- omitted, it defaults to \code{0}. The full form returns a list of
- plain integers \code{[\var{start}, \var{start} + \var{step},
- \var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive,
- the last element is the largest \code{\var{start} + \var{i} *
- \var{step}} less than \var{stop}; if \var{step} is negative, the last
- element is the smallest \code{\var{start} + \var{i} * \var{step}}
- greater than \var{stop}. \var{step} must not be zero (or else
- \exception{ValueError} is raised). Example:
-
-\begin{verbatim}
->>> list(range(10))
-[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
->>> list(range(1, 11))
-[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
->>> list(range(0, 30, 5))
-[0, 5, 10, 15, 20, 25]
->>> list(range(0, 10, 3))
-[0, 3, 6, 9]
->>> list(range(0, -10, -1))
-[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
->>> list(range(0))
-[]
->>> list(range(1, 0))
-[]
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{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 \function{eval()}.
-\end{funcdesc}
-
-\begin{funcdesc}{reversed}{seq}
- Return a reverse iterator. \var{seq} must be an object which
- supports the sequence protocol (the \method{__len__()} method and the
- \method{__getitem__()} method with integer arguments starting at
- \code{0}).
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{round}{x\optional{, n}}
- Return the floating point value \var{x} rounded to \var{n} digits
- after the decimal point. If \var{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 \var{n}; if two multiples
- are equally close, rounding is done away from 0 (so. for example,
- \code{round(0.5)} is \code{1.0} and \code{round(-0.5)} is \code{-1.0}).
-\end{funcdesc}
-
-\begin{funcdesc}{set}{\optional{iterable}}
- Return a set whose elements are taken from \var{iterable}. The elements
- must be immutable. To represent sets of sets, the inner sets should
- be \class{frozenset} objects. If \var{iterable} is not specified,
- returns a new empty set, \code{set([])}.
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{setattr}{object, name, value}
- This is the counterpart of \function{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,
- \code{setattr(\var{x}, '\var{foobar}', 123)} is equivalent to
- \code{\var{x}.\var{foobar} = 123}.
-\end{funcdesc}
-
-\begin{funcdesc}{slice}{\optional{start,} stop\optional{, step}}
- Return a slice object representing the set of indices specified by
- \code{range(\var{start}, \var{stop}, \var{step})}. The \var{start}
- and \var{step} arguments default to \code{None}. Slice objects have
- read-only data attributes \member{start}, \member{stop} and
- \member{step} which merely return the argument values (or their
- default). They have no other explicit functionality; however they
- are used by Numerical Python\index{Numerical Python} and other third
- party extensions. Slice objects are also generated when extended
- indexing syntax is used. For example: \samp{a[start:stop:step]} or
- \samp{a[start:stop, i]}.
-\end{funcdesc}
-
-\begin{funcdesc}{sorted}{iterable\optional{, cmp\optional{,
- key\optional{, reverse}}}}
- Return a new sorted list from the items in \var{iterable}.
-
- The optional arguments \var{cmp}, \var{key}, and \var{reverse} have
- the same meaning as those for the \method{list.sort()} method
- (described in section~\ref{typesseq-mutable}).
-
- \var{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:
- \samp{\var{cmp}=\keyword{lambda} \var{x},\var{y}:
- \function{cmp}(x.lower(), y.lower())}
-
- \var{key} specifies a function of one argument that is used to
- extract a comparison key from each list element:
- \samp{\var{key}=\function{str.lower}}
-
- \var{reverse} is a boolean value. If set to \code{True}, then the
- list elements are sorted as if each comparison were reversed.
-
- In general, the \var{key} and \var{reverse} conversion processes are
- much faster than specifying an equivalent \var{cmp} function. This is
- because \var{cmp} is called multiple times for each list element while
- \var{key} and \var{reverse} touch each element only once.
-
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{staticmethod}{function}
- Return a static method for \var{function}.
-
- A static method does not receive an implicit first argument.
- To declare a static method, use this idiom:
-
-\begin{verbatim}
-class C:
- @staticmethod
- def f(arg1, arg2, ...): ...
-\end{verbatim}
-
- The \code{@staticmethod} form is a function decorator -- see the description
- of function definitions in chapter 7 of the
- \citetitle[../ref/function.html]{Python Reference Manual} for details.
-
- It can be called either on the class (such as \code{C.f()}) or on an
- instance (such as \code{C().f()}). The instance is ignored except
- for its class.
-
- Static methods in Python are similar to those found in Java or \Cpp.
- For a more advanced concept, see \function{classmethod()} in this
- section.
-
- For more information on static methods, consult the documentation on the
- standard type hierarchy in chapter 3 of the
- \citetitle[../ref/types.html]{Python Reference Manual} (at the bottom).
- \versionadded{2.2}
- \versionchanged[Function decorator syntax added]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{str}{\optional{object\optional{, encoding
- \optional{, errors}}}}
- Return the Unicode string version of \var{object} using one of the
- following modes:
-
- If \var{encoding} and/or \var{errors} are given, \code{unicode()}
- will decode the object which can either be an 8-bit string or a
- character buffer using the codec for \var{encoding}. The
- \var{encoding} parameter is a string giving the name of an encoding;
- if the encoding is not known, \exception{LookupError} is raised.
- Error handling is done according to \var{errors}; this specifies the
- treatment of characters which are invalid in the input encoding. If
- \var{errors} is \code{'strict'} (the default), a
- \exception{ValueError} is raised on errors, while a value of
- \code{'ignore'} causes errors to be silently ignored, and a value of
- \code{'replace'} causes the official Unicode replacement character,
- \code{U+FFFD}, to be used to replace input characters which cannot
- be decoded. See also the \refmodule{codecs} module.
-
- If no optional parameters are given, \code{unicode()} will mimic the
- behaviour of \code{str()} except that it returns Unicode strings
- instead of 8-bit strings. More precisely, if \var{object} is a
- Unicode string or subclass it will return that Unicode string without
- any additional decoding applied.
-
- For objects which provide a \method{__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 \code{'strict'} mode.
-
- \versionadded{2.0}
- \versionchanged[Support for \method{__unicode__()} added]{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{sum}{iterable\optional{, start}}
- Sums \var{start} and the items of an \var{iterable} from left to
- right and returns the total. \var{start} defaults to \code{0}.
- The \var{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 \code{''.join(\var{sequence})}.
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{super}{type\optional{, object-or-type}}
- Return the superclass of \var{type}. If the second argument is omitted
- the super object returned is unbound. If the second argument is an
- object, \code{isinstance(\var{obj}, \var{type})} must be true. If
- the second argument is a type, \code{issubclass(\var{type2},
- \var{type})} must be true.
- \function{super()} only works for new-style classes.
-
- A typical use for calling a cooperative superclass method is:
-\begin{verbatim}
-class C(B):
- def meth(self, arg):
- super(C, self).meth(arg)
-\end{verbatim}
-
- Note that \function{super} is implemented as part of the binding process for
- explicit dotted attribute lookups such as
- \samp{super(C, self).__getitem__(name)}. Accordingly, \function{super} is
- undefined for implicit lookups using statements or operators such as
- \samp{super(C, self)[name]}.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{tuple}{\optional{iterable}}
- Return a tuple whose items are the same and in the same order as
- \var{iterable}'s items. \var{iterable} may be a sequence, a
- container that supports iteration, or an iterator object.
- If \var{iterable} is already a tuple, it
- is returned unchanged. For instance, \code{tuple('abc')} returns
- \code{('a', 'b', 'c')} and \code{tuple([1, 2, 3])} returns
- \code{(1, 2, 3)}. If no argument is given, returns a new empty
- tuple, \code{()}.
-\end{funcdesc}
-
-\begin{funcdesc}{type}{object}
- Return the type of an \var{object}. The return value is a
- type\obindex{type} object. The \function{isinstance()} built-in
- function is recommended for testing the type of an object.
-
- With three arguments, \function{type} functions as a constructor
- as detailed below.
-\end{funcdesc}
-
-\begin{funcdescni}{type}{name, bases, dict}
- Return a new type object. This is essentially a dynamic form of the
- \keyword{class} statement. The \var{name} string is the class name
- and becomes the \member{__name__} attribute; the \var{bases} tuple
- itemizes the base classes and becomes the \member{__bases__}
- attribute; and the \var{dict} dictionary is the namespace containing
- definitions for class body and becomes the \member{__dict__}
- attribute. For example, the following two statements create
- identical \class{type} objects:
-
-\begin{verbatim}
- >>> class X(object):
- ... a = 1
- ...
- >>> X = type('X', (object,), dict(a=1))
-\end{verbatim}
-\versionadded{2.2}
-\end{funcdescni}
-
-\begin{funcdesc}{vars}{\optional{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 \member{__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.\footnote{
- 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.}
-\end{funcdesc}
-
-\begin{funcdesc}{zip}{\optional{iterable, \moreargs}}
- This function returns a list of tuples, where the \var{i}-th tuple contains
- the \var{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, \function{zip()} is
- similar to \function{map()} with an initial argument of \code{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[Formerly, \function{zip()} required at least one argument
- and \code{zip()} raised a \exception{TypeError} instead of returning
- an empty list]{2.4}
-\end{funcdesc}
-
-
-% ---------------------------------------------------------------------------
-
-
-\section{Non-essential Built-in Functions \label{non-essential-built-in-funcs}}
-
-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.
-
-
-\setindexsubitem{(non-essential built-in functions)}
-
-\begin{funcdesc}{buffer}{object\optional{, offset\optional{, size}}}
- The \var{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 \var{object} argument.
- The buffer object will be a slice from the beginning of \var{object}
- (or from the specified \var{offset}). The slice will extend to the
- end of \var{object} (or will have a length given by the \var{size}
- argument).
-\end{funcdesc}
-
diff --git a/Doc/lib/libfunctools.tex b/Doc/lib/libfunctools.tex
deleted file mode 100644
index 654a5b1..0000000
--- a/Doc/lib/libfunctools.tex
+++ /dev/null
@@ -1,145 +0,0 @@
-\section{\module{functools} ---
- Higher order functions and operations on callable objects.}
-
-\declaremodule{standard}{functools} % standard library, in Python
-
-\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}
-
-\modulesynopsis{Higher-order functions and operations on callable objects.}
-
-\versionadded{2.5}
-
-The \module{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 \module{functools} module defines the following function:
-
-\begin{funcdesc}{partial}{func\optional{,*args}\optional{, **keywords}}
-Return a new \class{partial} object which when called will behave like
-\var{func} called with the positional arguments \var{args} and keyword
-arguments \var{keywords}. If more arguments are supplied to the call, they
-are appended to \var{args}. If additional keyword arguments are supplied,
-they extend and override \var{keywords}. Roughly equivalent to:
- \begin{verbatim}
- 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
- \end{verbatim}
-
-The \function{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,
-\function{partial} can be used to create a callable that behaves like
-the \function{int} function where the \var{base} argument defaults to
-two:
- \begin{verbatim}
- >>> basetwo = partial(int, base=2)
- >>> basetwo.__doc__ = 'Convert base 2 string to an int.'
- >>> basetwo('10010')
- 18
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{reduce}{function, sequence\optional{, initializer}}
- Apply \var{function} of two arguments cumulatively to the items of
- \var{sequence}, from left to right, so as to reduce the sequence to
- a single value. For example, \code{reduce(lambda x, y: x+y, [1, 2,
- 3, 4, 5])} calculates \code{((((1+2)+3)+4)+5)}. The left argument,
- \var{x}, is the accumulated value and the right argument, \var{y},
- is the update value from the \var{sequence}. If the optional
- \var{initializer} is present, it is placed before the items of the
- sequence in the calculation, and serves as a default when the
- sequence is empty. If \var{initializer} is not given and
- \var{sequence} contains only one item, the first item is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{update_wrapper}
-{wrapper, wrapped\optional{, assigned}\optional{, updated}}
-Update a \var{wrapper} function to look like the \var{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
-\var{WRAPPER_ASSIGNMENTS} (which assigns to the wrapper function's
-\var{__name__}, \var{__module__} and \var{__doc__}, the documentation string)
-and \var{WRAPPER_UPDATES} (which updates the wrapper function's \var{__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.
-\end{funcdesc}
-
-\begin{funcdesc}{wraps}
-{wrapped\optional{, assigned}\optional{, updated}}
-This is a convenience function for invoking
-\code{partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)}
-as a function decorator when defining a wrapper function. For example:
- \begin{verbatim}
- >>> 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'
- \end{verbatim}
-Without the use of this decorator factory, the name of the example
-function would have been \code{'wrapper'}, and the docstring of the
-original \function{example()} would have been lost.
-\end{funcdesc}
-
-
-\subsection{\class{partial} Objects \label{partial-objects}}
-
-
-\class{partial} objects are callable objects created by \function{partial()}.
-They have three read-only attributes:
-
-\begin{memberdesc}[callable]{func}{}
-A callable object or function. Calls to the \class{partial} object will
-be forwarded to \member{func} with new arguments and keywords.
-\end{memberdesc}
-
-\begin{memberdesc}[tuple]{args}{}
-The leftmost positional arguments that will be prepended to the
-positional arguments provided to a \class{partial} object call.
-\end{memberdesc}
-
-\begin{memberdesc}[dict]{keywords}{}
-The keyword arguments that will be supplied when the \class{partial} object
-is called.
-\end{memberdesc}
-
-\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 \member{__name__} and
-\member{__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.
diff --git a/Doc/lib/libfuture.tex b/Doc/lib/libfuture.tex
deleted file mode 100644
index f1ba064..0000000
--- a/Doc/lib/libfuture.tex
+++ /dev/null
@@ -1,69 +0,0 @@
-\section{\module{__future__} ---
- Future statement definitions}
-
-\declaremodule[future]{standard}{__future__}
-\modulesynopsis{Future statement definitions}
-
-\module{__future__} is a real module, and serves three purposes:
-
-\begin{itemize}
-
-\item To avoid confusing existing tools that analyze import statements
- and expect to find the modules they're importing.
-
-\item To ensure that future_statements run under releases prior to 2.1
- at least yield runtime exceptions (the import of
- \module{__future__} will fail, because there was no module of
- that name prior to 2.1).
-
-\item 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
- \module{__future__} and examining its contents.
-
-\end{itemize}
-
-Each statement in \file{__future__.py} is of the form:
-
-\begin{alltt}
-FeatureName = "_Feature(" \var{OptionalRelease} "," \var{MandatoryRelease} ","
- \var{CompilerFlag} ")"
-\end{alltt}
-
-where, normally, \var{OptionalRelease} is less than
-\var{MandatoryRelease}, and both are 5-tuples of the same form as
-\code{sys.version_info}:
-
-\begin{verbatim}
- (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
- )
-\end{verbatim}
-
-\var{OptionalRelease} records the first release in which the feature
-was accepted.
-
-In the case of a \var{MandatoryRelease} that has not yet occurred,
-\var{MandatoryRelease} predicts the release in which the feature will
-become part of the language.
-
-Else \var{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.
-
-\var{MandatoryRelease} may also be \code{None}, meaning that a planned
-feature got dropped.
-
-Instances of class \class{_Feature} have two corresponding methods,
-\method{getOptionalRelease()} and \method{getMandatoryRelease()}.
-
-\var{CompilerFlag} is the (bitfield) flag that should be passed in the
-fourth argument to the builtin function \function{compile()} to enable
-the feature in dynamically compiled code. This flag is stored in the
-\member{compiler_flag} attribute on \class{_Feature} instances.
-
-No feature description will ever be deleted from \module{__future__}.
diff --git a/Doc/lib/libgc.tex b/Doc/lib/libgc.tex
deleted file mode 100644
index 0d3408b..0000000
--- a/Doc/lib/libgc.tex
+++ /dev/null
@@ -1,196 +0,0 @@
-\section{\module{gc} ---
- Garbage Collector interface}
-
-\declaremodule{extension}{gc}
-\modulesynopsis{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
-\code{gc.disable()}. To debug a leaking program call
-\code{gc.set_debug(gc.DEBUG_LEAK)}. Notice that this includes
-\code{gc.DEBUG_SAVEALL}, causing garbage-collected objects to be
-saved in gc.garbage for inspection.
-
-The \module{gc} module provides the following functions:
-
-\begin{funcdesc}{enable}{}
-Enable automatic garbage collection.
-\end{funcdesc}
-
-\begin{funcdesc}{disable}{}
-Disable automatic garbage collection.
-\end{funcdesc}
-
-\begin{funcdesc}{isenabled}{}
-Returns true if automatic collection is enabled.
-\end{funcdesc}
-
-\begin{funcdesc}{collect}{\optional{generation}}
-With no arguments, run a full collection. The optional argument
-\var{generation} may be an integer specifying which generation to collect
-(from 0 to 2). A \exception{ValueError} is raised if the generation number
-is invalid.
-The number of unreachable objects found is returned.
-
-\versionchanged[The optional \var{generation} argument was added]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{set_debug}{flags}
-Set the garbage collection debugging flags.
-Debugging information will be written to \code{sys.stderr}. See below
-for a list of debugging flags which can be combined using bit
-operations to control debugging.
-\end{funcdesc}
-
-\begin{funcdesc}{get_debug}{}
-Return the debugging flags currently set.
-\end{funcdesc}
-
-\begin{funcdesc}{get_objects}{}
-Returns a list of all objects tracked by the collector, excluding the
-list returned.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{set_threshold}{threshold0\optional{,
- threshold1\optional{, threshold2}}}
-Set the garbage collection thresholds (the collection frequency).
-Setting \var{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 \code{0}). If an object survives a
-collection it is moved into the next older generation. Since
-generation \code{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
-\var{threshold0}, collection starts. Initially only generation
-\code{0} is examined. If generation \code{0} has been examined more
-than \var{threshold1} times since generation \code{1} has been
-examined, then generation \code{1} is examined as well. Similarly,
-\var{threshold2} controls the number of collections of generation
-\code{1} before collecting generation \code{2}.
-\end{funcdesc}
-
-\begin{funcdesc}{get_count}{}
-Return the current collection counts as a tuple of
-\code{(\var{count0}, \var{count1}, \var{count2})}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{get_threshold}{}
-Return the current collection thresholds as a tuple of
-\code{(\var{threshold0}, \var{threshold1}, \var{threshold2})}.
-\end{funcdesc}
-
-\begin{funcdesc}{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 \function{collect()} before calling
-\function{get_referrers()}.
-
-Care must be taken when using objects returned by
-\function{get_referrers()} because some of them could still be under
-construction and hence in a temporarily invalid state. Avoid using
-\function{get_referrers()} for any purpose other than debugging.
-
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{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 \member{tp_traverse} methods (if any), and may not be all
-objects actually directly reachable. \member{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}
-\end{funcdesc}
-
-The following variable is provided for read-only access (you can
-mutate its value but should not rebind it):
-
-\begin{datadesc}{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 \method{__del__()} methods.\footnote{Prior to
- Python 2.2, the list contained all instance objects in unreachable
- cycles, not only those with \method{__del__()} methods.}
-Objects that have
-\method{__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 \method{__del__()}
-methods. If you know a safe order, you can force the issue by examining
-the \var{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 \var{garbage} list, so they should be
-removed from \var{garbage} too. For example, after breaking cycles, do
-\code{del gc.garbage[:]} to empty the list. It's generally better
-to avoid the issue by not creating cycles containing objects with
-\method{__del__()} methods, and \var{garbage} can be examined in that
-case to verify that no such cycles are being created.
-
-If \constant{DEBUG_SAVEALL} is set, then all unreachable objects will
-be added to this list rather than freed.
-\end{datadesc}
-
-
-The following constants are provided for use with
-\function{set_debug()}:
-
-\begin{datadesc}{DEBUG_STATS}
-Print statistics during collection. This information can
-be useful when tuning the collection frequency.
-\end{datadesc}
-
-\begin{datadesc}{DEBUG_COLLECTABLE}
-Print information on collectable objects found.
-\end{datadesc}
-
-\begin{datadesc}{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 \code{garbage} list.
-\end{datadesc}
-
-\begin{datadesc}{DEBUG_INSTANCES}
-When \constant{DEBUG_COLLECTABLE} or \constant{DEBUG_UNCOLLECTABLE} is
-set, print information about instance objects found.
-\end{datadesc}
-
-\begin{datadesc}{DEBUG_OBJECTS}
-When \constant{DEBUG_COLLECTABLE} or \constant{DEBUG_UNCOLLECTABLE} is
-set, print information about objects other than instance objects found.
-\end{datadesc}
-
-\begin{datadesc}{DEBUG_SAVEALL}
-When set, all unreachable objects found will be appended to
-\var{garbage} rather than being freed. This can be useful for debugging
-a leaking program.
-\end{datadesc}
-
-\begin{datadesc}{DEBUG_LEAK}
-The debugging flags necessary for the collector to print
-information about a leaking program (equal to \code{DEBUG_COLLECTABLE |
-DEBUG_UNCOLLECTABLE | DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALL}).
-\end{datadesc}
diff --git a/Doc/lib/libgdbm.tex b/Doc/lib/libgdbm.tex
deleted file mode 100644
index 0c36677..0000000
--- a/Doc/lib/libgdbm.tex
+++ /dev/null
@@ -1,100 +0,0 @@
-\section{\module{gdbm} ---
- GNU's reinterpretation of dbm}
-
-\declaremodule{builtin}{gdbm}
- \platform{Unix}
-\modulesynopsis{GNU's reinterpretation of dbm.}
-
-
-This module is quite similar to the \refmodule{dbm}\refbimodindex{dbm}
-module, but uses \code{gdbm} instead to provide some additional
-functionality. Please note that the file formats created by
-\code{gdbm} and \code{dbm} are incompatible.
-
-The \module{gdbm} module provides an interface to the GNU DBM
-library. \code{gdbm} objects behave like mappings
-(dictionaries), except that keys and values are always strings.
-Printing a \code{gdbm} object doesn't print the keys and values, and
-the \method{items()} and \method{values()} methods are not supported.
-
-The module defines the following constant and functions:
-
-\begin{excdesc}{error}
-Raised on \code{gdbm}-specific errors, such as I/O errors.
-\exception{KeyError} is raised for general mapping errors like
-specifying an incorrect key.
-\end{excdesc}
-
-\begin{funcdesc}{open}{filename, \optional{flag, \optional{mode}}}
-Open a \code{gdbm} database and return a \code{gdbm} object. The
-\var{filename} argument is the name of the database file.
-
-The optional \var{flag} argument can be
-\code{'r'} (to open an existing database for reading only --- default),
-\code{'w'} (to open an existing database for reading and writing),
-\code{'c'} (which creates the database if it doesn't exist), or
-\code{'n'} (which always creates a new empty database).
-
-The following additional characters may be appended to the flag to
-control how the database is opened:
-
-\begin{itemize}
-\item \code{'f'} --- Open the database in fast mode. Writes to the database
- will not be synchronized.
-\item \code{'s'} --- Synchronized mode. This will cause changes to the database
- will be immediately written to the file.
-\item \code{'u'} --- Do not lock database.
-\end{itemize}
-
-Not all flags are valid for all versions of \code{gdbm}. The
-module constant \code{open_flags} is a string of supported flag
-characters. The exception \exception{error} is raised if an invalid
-flag is specified.
-
-The optional \var{mode} argument is the \UNIX{} mode of the file, used
-only when the database has to be created. It defaults to octal
-\code{0666}.
-\end{funcdesc}
-
-In addition to the dictionary-like methods, \code{gdbm} objects have the
-following methods:
-
-\begin{funcdesc}{firstkey}{}
-It's possible to loop over every key in the database using this method
-and the \method{nextkey()} method. The traversal is ordered by
-\code{gdbm}'s internal hash values, and won't be sorted by the key
-values. This method returns the starting key.
-\end{funcdesc}
-
-\begin{funcdesc}{nextkey}{key}
-Returns the key that follows \var{key} in the traversal. The
-following code prints every key in the database \code{db}, without
-having to create a list in memory that contains them all:
-
-\begin{verbatim}
-k = db.firstkey()
-while k != None:
- print k
- k = db.nextkey(k)
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{reorganize}{}
-If you have carried out a lot of deletions and would like to shrink
-the space used by the \code{gdbm} file, this routine will reorganize
-the database. \code{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.
-\end{funcdesc}
-
-\begin{funcdesc}{sync}{}
-When the database has been opened in fast mode, this method forces any
-unwritten data to be written to the disk.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
- \seemodule{whichdb}{Utility module used to determine the type of an
- existing database.}
-\end{seealso}
diff --git a/Doc/lib/libgetopt.tex b/Doc/lib/libgetopt.tex
deleted file mode 100644
index 7930acd..0000000
--- a/Doc/lib/libgetopt.tex
+++ /dev/null
@@ -1,154 +0,0 @@
-\section{\module{getopt} ---
- Parser for command line options}
-
-\declaremodule{standard}{getopt}
-\modulesynopsis{Portable parser for command line options; support both
- short and long option names.}
-
-
-This module helps scripts to parse the command line arguments in
-\code{sys.argv}.
-It supports the same conventions as the \UNIX{} \cfunction{getopt()}
-function (including the special meanings of arguments of the form
-`\code{-}' and `\code{-}\code{-}').
-% That's to fool latex2html into leaving the two hyphens alone!
-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:
-
-\begin{funcdesc}{getopt}{args, options\optional{, long_options}}
-Parses command line options and parameter list. \var{args} is the
-argument list to be parsed, without the leading reference to the
-running program. Typically, this means \samp{sys.argv[1:]}.
-\var{options} is the string of option letters that the script wants to
-recognize, with options that require an argument followed by a colon
-(\character{:}; i.e., the same format that \UNIX{}
-\cfunction{getopt()} uses).
-
-\note{Unlike GNU \cfunction{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.}
-
-\var{long_options}, if specified, must be a list of strings with the
-names of the long options which should be supported. The leading
-\code{'-}\code{-'} characters should not be included in the option
-name. Long options which require an argument should be followed by an
-equal sign (\character{=}). To accept only long options,
-\var{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 \var{long_options} is \code{['foo', 'frob']}, the option
-\longprogramopt{fo} will match as \longprogramopt{foo}, but
-\longprogramopt{f} will not match uniquely, so \exception{GetoptError}
-will be raised.
-
-The return value consists of two elements: the first is a list of
-\code{(\var{option}, \var{value})} pairs; the second is the list of
-program arguments left after the option list was stripped (this is a
-trailing slice of \var{args}). Each option-and-value pair returned
-has the option as its first element, prefixed with a hyphen for short
-options (e.g., \code{'-x'}) or two hyphens for long options (e.g.,
-\code{'-}\code{-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.
-\end{funcdesc}
-
-\begin{funcdesc}{gnu_getopt}{args, options\optional{, long_options}}
-This function works like \function{getopt()}, except that GNU style
-scanning mode is used by default. This means that option and
-non-option arguments may be intermixed. The \function{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}
-\end{funcdesc}
-
-\begin{excdesc}{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 \member{msg} and \member{opt} give the error message and
-related option; if there is no specific option to which the exception
-relates, \member{opt} is an empty string.
-
-\versionchanged[Introduced \exception{GetoptError} as a synonym for
- \exception{error}]{1.6}
-\end{excdesc}
-
-\begin{excdesc}{error}
-Alias for \exception{GetoptError}; for backward compatibility.
-\end{excdesc}
-
-
-An example using only \UNIX{} style options:
-
-\begin{verbatim}
->>> 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']
-\end{verbatim}
-
-Using long option names is equally easy:
-
-\begin{verbatim}
->>> 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']
-\end{verbatim}
-
-In a script, typical usage is something like this:
-
-\begin{verbatim}
-import getopt, sys
-
-def main():
- try:
- opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
- except getopt.GetoptError as 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()
-\end{verbatim}
-
-\begin{seealso}
- \seemodule{optparse}{More object-oriented command line option parsing.}
-\end{seealso}
diff --git a/Doc/lib/libgetpass.tex b/Doc/lib/libgetpass.tex
deleted file mode 100644
index a742439..0000000
--- a/Doc/lib/libgetpass.tex
+++ /dev/null
@@ -1,36 +0,0 @@
-\section{\module{getpass}
- --- Portable password input}
-
-\declaremodule{standard}{getpass}
-\modulesynopsis{Portable reading of passwords and retrieval of the userid.}
-\moduleauthor{Piers Lauder}{piers@cs.su.oz.au}
-% Windows (& Mac?) support by Guido van Rossum.
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-The \module{getpass} module provides two functions:
-
-
-\begin{funcdesc}{getpass}{\optional{prompt\optional{, stream}}}
- Prompt the user for a password without echoing. The user is
- prompted using the string \var{prompt}, which defaults to
- \code{'Password: '}. On \UNIX, the prompt is written to the
- file-like object \var{stream}, which defaults to
- \code{sys.stdout} (this argument is ignored on Windows).
-
- Availability: Macintosh, \UNIX, Windows.
- \versionchanged[The \var{stream} parameter was added]{2.5}
-\end{funcdesc}
-
-
-\begin{funcdesc}{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 \refmodule{pwd} module,
- otherwise, an exception is raised.
-\end{funcdesc}
diff --git a/Doc/lib/libgettext.tex b/Doc/lib/libgettext.tex
deleted file mode 100644
index 6aee255..0000000
--- a/Doc/lib/libgettext.tex
+++ /dev/null
@@ -1,773 +0,0 @@
-\section{\module{gettext} ---
- Multilingual internationalization services}
-
-\declaremodule{standard}{gettext}
-\modulesynopsis{Multilingual internationalization services.}
-\moduleauthor{Barry A. Warsaw}{barry@zope.com}
-\sectionauthor{Barry A. Warsaw}{barry@zope.com}
-
-
-The \module{gettext} module provides internationalization (I18N) and
-localization (L10N) services for your Python modules and applications.
-It supports both the GNU \code{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.
-
-\subsection{GNU \program{gettext} API}
-
-The \module{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.
-
-\begin{funcdesc}{bindtextdomain}{domain\optional{, localedir}}
-Bind the \var{domain} to the locale directory
-\var{localedir}. More concretely, \module{gettext} will look for
-binary \file{.mo} files for the given domain using the path (on \UNIX):
-\file{\var{localedir}/\var{language}/LC_MESSAGES/\var{domain}.mo},
-where \var{languages} is searched for in the environment variables
-\envvar{LANGUAGE}, \envvar{LC_ALL}, \envvar{LC_MESSAGES}, and
-\envvar{LANG} respectively.
-
-If \var{localedir} is omitted or \code{None}, then the current binding
-for \var{domain} is returned.\footnote{
- 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 \module{gettext} module
- does not try to support these system dependent defaults;
- instead its default is \file{\code{sys.prefix}/share/locale}.
- For this reason, it is always best to call
- \function{bindtextdomain()} with an explicit absolute path at
- the start of your application.}
-\end{funcdesc}
-
-\begin{funcdesc}{bind_textdomain_codeset}{domain\optional{, codeset}}
-Bind the \var{domain} to \var{codeset}, changing the encoding of
-strings returned by the \function{gettext()} family of functions.
-If \var{codeset} is omitted, then the current binding is returned.
-
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{textdomain}{\optional{domain}}
-Change or query the current global domain. If \var{domain} is
-\code{None}, then the current global domain is returned, otherwise the
-global domain is set to \var{domain}, which is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{gettext}{message}
-Return the localized translation of \var{message}, based on the
-current global domain, language, and locale directory. This function
-is usually aliased as \function{_} in the local namespace (see
-examples below).
-\end{funcdesc}
-
-\begin{funcdesc}{lgettext}{message}
-Equivalent to \function{gettext()}, but the translation is returned
-in the preferred system encoding, if no other encoding was explicitly
-set with \function{bind_textdomain_codeset()}.
-
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{dgettext}{domain, message}
-Like \function{gettext()}, but look the message up in the specified
-\var{domain}.
-\end{funcdesc}
-
-\begin{funcdesc}{ldgettext}{domain, message}
-Equivalent to \function{dgettext()}, but the translation is returned
-in the preferred system encoding, if no other encoding was explicitly
-set with \function{bind_textdomain_codeset()}.
-
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{ngettext}{singular, plural, n}
-
-Like \function{gettext()}, but consider plural forms. If a translation
-is found, apply the plural formula to \var{n}, and return the
-resulting message (some languages have more than two plural forms).
-If no translation is found, return \var{singular} if \var{n} is 1;
-return \var{plural} otherwise.
-
-The Plural formula is taken from the catalog header. It is a C or
-Python expression that has a free variable \var{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}
-
-\end{funcdesc}
-
-\begin{funcdesc}{lngettext}{singular, plural, n}
-Equivalent to \function{ngettext()}, but the translation is returned
-in the preferred system encoding, if no other encoding was explicitly
-set with \function{bind_textdomain_codeset()}.
-
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{dngettext}{domain, singular, plural, n}
-Like \function{ngettext()}, but look the message up in the specified
-\var{domain}.
-
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{ldngettext}{domain, singular, plural, n}
-Equivalent to \function{dngettext()}, but the translation is returned
-in the preferred system encoding, if no other encoding was explicitly
-set with \function{bind_textdomain_codeset()}.
-
-\versionadded{2.4}
-\end{funcdesc}
-
-
-
-Note that GNU \program{gettext} also defines a \function{dcgettext()}
-method, but this was deemed not useful and so it is currently
-unimplemented.
-
-Here's an example of typical usage for this API:
-
-\begin{verbatim}
-import gettext
-gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
-gettext.textdomain('myapplication')
-_ = gettext.gettext
-# ...
-print _('This is a translatable string.')
-\end{verbatim}
-
-\subsection{Class-based API}
-
-The class-based API of the \module{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. \module{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 \function{_()}.
-
-\begin{funcdesc}{find}{domain\optional{, localedir\optional{,
- languages\optional{, all}}}}
-This function implements the standard \file{.mo} file search
-algorithm. It takes a \var{domain}, identical to what
-\function{textdomain()} takes. Optional \var{localedir} is as in
-\function{bindtextdomain()} Optional \var{languages} is a list of
-strings, where each string is a language code.
-
-If \var{localedir} is not given, then the default system locale
-directory is used.\footnote{See the footnote for
-\function{bindtextdomain()} above.} If \var{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 \var{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.
-
-\function{find()} then expands and normalizes the languages, and then
-iterates through them, searching for an existing file built of these
-components:
-
-\file{\var{localedir}/\var{language}/LC_MESSAGES/\var{domain}.mo}
-
-The first such file name that exists is returned by \function{find()}.
-If no such file is found, then \code{None} is returned. If \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{translation}{domain\optional{, localedir\optional{,
- languages\optional{, class_\optional{,
- fallback\optional{, codeset}}}}}}
-Return a \class{Translations} instance based on the \var{domain},
-\var{localedir}, and \var{languages}, which are first passed to
-\function{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 \var{class_} if provided, otherwise
-\class{GNUTranslations}. The class's constructor must take a single
-file object argument. If provided, \var{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, \function{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
-\exception{IOError} if \var{fallback} is false (which is the default),
-and returns a \class{NullTranslations} instance if \var{fallback} is
-true.
-
-\versionchanged[Added the \var{codeset} parameter]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{install}{domain\optional{, localedir\optional{, unicode
- \optional{, codeset\optional{, names}}}}}
-This installs the function \function{_} in Python's builtin namespace,
-based on \var{domain}, \var{localedir}, and \var{codeset} which are
-passed to the function \function{translation()}. The \var{unicode}
-flag is passed to the resulting translation object's \method{install}
-method.
-
-For the \var{names} parameter, please see the description of the
-translation object's \method{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
-\function{_()} function, like this:
-
-\begin{verbatim}
-print _('This string will be translated.')
-\end{verbatim}
-
-For convenience, you want the \function{_()} function to be installed in
-Python's builtin namespace, so it is easily accessible in all modules
-of your application.
-
-\versionchanged[Added the \var{codeset} parameter]{2.4}
-\versionchanged[Added the \var{names} parameter]{2.5}
-\end{funcdesc}
-
-\subsubsection{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}:
-
-\begin{methoddesc}[NullTranslations]{__init__}{\optional{fp}}
-Takes an optional file object \var{fp}, which is ignored by the base
-class. Initializes ``protected'' instance variables \var{_info} and
-\var{_charset} which are set by derived classes, as well as \var{_fallback},
-which is set through \method{add_fallback}. It then calls
-\code{self._parse(fp)} if \var{fp} is not \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{_parse}{fp}
-No-op'd in the base class, this method takes file object \var{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.
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{add_fallback}{fallback}
-Add \var{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.
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{gettext}{message}
-If a fallback has been set, forward \method{gettext()} to the fallback.
-Otherwise, return the translated message. Overridden in derived classes.
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{lgettext}{message}
-If a fallback has been set, forward \method{lgettext()} to the fallback.
-Otherwise, return the translated message. Overridden in derived classes.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{ugettext}{message}
-If a fallback has been set, forward \method{ugettext()} to the fallback.
-Otherwise, return the translated message as a Unicode string.
-Overridden in derived classes.
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{ngettext}{singular, plural, n}
-If a fallback has been set, forward \method{ngettext()} to the fallback.
-Otherwise, return the translated message. Overridden in derived classes.
-
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{lngettext}{singular, plural, n}
-If a fallback has been set, forward \method{ngettext()} to the fallback.
-Otherwise, return the translated message. Overridden in derived classes.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{ungettext}{singular, plural, n}
-If a fallback has been set, forward \method{ungettext()} to the fallback.
-Otherwise, return the translated message as a Unicode string.
-Overridden in derived classes.
-
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{info}{}
-Return the ``protected'' \member{_info} variable.
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{charset}{}
-Return the ``protected'' \member{_charset} variable.
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{output_charset}{}
-Return the ``protected'' \member{_output_charset} variable, which
-defines the encoding used to return translated messages.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{set_output_charset}{charset}
-Change the ``protected'' \member{_output_charset} variable, which
-defines the encoding used to return translated messages.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{install}{\optional{unicode
- \optional{, names}}}
-If the \var{unicode} flag is false, this method installs
-\method{self.gettext()} into the built-in namespace, binding it to
-\samp{_}. If \var{unicode} is true, it binds \method{self.ugettext()}
-instead. By default, \var{unicode} is false.
-
-If the \var{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 \function{_()}. Supported names are \code{'gettext'} (bound
-to \method{self.gettext()} or \method{self.ugettext()} according to the
-\var{unicode} flag), \code{'ngettext'} (bound to \method{self.ngettext()}
-or \method{self.ungettext()} according to the \var{unicode} flag),
-\code{'lgettext'} and \code{'lngettext'}.
-
-Note that this is only one way, albeit the most convenient way, to
-make the \function{_} function available to your application. Because it
-affects the entire application globally, and specifically the built-in
-namespace, localized modules should never install \function{_}.
-Instead, they should use this code to make \function{_} available to
-their module:
-
-\begin{verbatim}
-import gettext
-t = gettext.translation('mymodule', ...)
-_ = t.gettext
-\end{verbatim}
-
-This puts \function{_} only in the module's global namespace and so
-only affects calls within this module.
-
-\versionchanged[Added the \var{names} parameter]{2.5}
-\end{methoddesc}
-
-\subsubsection{The \class{GNUTranslations} class}
-
-The \module{gettext} module provides one additional class derived from
-\class{NullTranslations}: \class{GNUTranslations}. This class
-overrides \method{_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 \code{key: value} pairs, and should
-contain the \code{Project-Id-Version} key. If the key
-\code{Content-Type} is found, then the \code{charset} property is used
-to initialize the ``protected'' \member{_charset} instance variable,
-defaulting to \code{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
-\method{ugettext()} method always returns a Unicode, while the
-\method{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. \method{ugettext()} and
-\method{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'' \member{_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 \exception{IOError}.
-
-The following methods are overridden from the base class implementation:
-
-\begin{methoddesc}[GNUTranslations]{gettext}{message}
-Look up the \var{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 \var{message} id, and a fallback has been set, the
-look up is forwarded to the fallback's \method{gettext()} method.
-Otherwise, the \var{message} id is returned.
-\end{methoddesc}
-
-\begin{methoddesc}[GNUTranslations]{lgettext}{message}
-Equivalent to \method{gettext()}, but the translation is returned
-in the preferred system encoding, if no other encoding was explicitly
-set with \method{set_output_charset()}.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[GNUTranslations]{ugettext}{message}
-Look up the \var{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 \var{message} id, and a fallback has been
-set, the look up is forwarded to the fallback's \method{ugettext()}
-method. Otherwise, the \var{message} id is returned.
-\end{methoddesc}
-
-\begin{methoddesc}[GNUTranslations]{ngettext}{singular, plural, n}
-Do a plural-forms lookup of a message id. \var{singular} is used as
-the message id for purposes of lookup in the catalog, while \var{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
-\method{ngettext()} method. Otherwise, when \var{n} is 1 \var{singular} is
-returned, and \var{plural} is returned in all other cases.
-
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[GNUTranslations]{lngettext}{singular, plural, n}
-Equivalent to \method{gettext()}, but the translation is returned
-in the preferred system encoding, if no other encoding was explicitly
-set with \method{set_output_charset()}.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[GNUTranslations]{ungettext}{singular, plural, n}
-Do a plural-forms lookup of a message id. \var{singular} is used as
-the message id for purposes of lookup in the catalog, while \var{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
-\method{ungettext()} method. Otherwise, when \var{n} is 1 \var{singular} is
-returned, and \var{plural} is returned in all other cases.
-
-Here is an example:
-
-\begin{verbatim}
-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}
-\end{verbatim}
-
-\versionadded{2.3}
-\end{methoddesc}
-
-\subsubsection{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.
-
-\subsubsection{The Catalog constructor}
-
-GNOME\index{GNOME} uses a version of the \module{gettext} module by
-James Henstridge, but this version has a slightly different API. Its
-documented usage was:
-
-\begin{verbatim}
-import gettext
-cat = gettext.Catalog(domain, localedir)
-_ = cat.gettext
-print _('hello world')
-\end{verbatim}
-
-For compatibility with this older module, the function
-\function{Catalog()} is an alias for the \function{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.
-
-\subsection{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:
-
-\begin{enumerate}
- \item prepare your program or module by specially marking
- translatable strings
- \item run a suite of tools over your marked files to generate raw
- messages catalogs
- \item create language specific translations of the message catalogs
- \item use the \module{gettext} module so that message strings are
- properly translated
-\end{enumerate}
-
-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 \code{_('...')} --- that is, a call
-to the function \function{_()}. For example:
-
-\begin{verbatim}
-filename = 'mylog.txt'
-message = _('writing a log message')
-fp = open(filename, 'w')
-fp.write(message)
-fp.close()
-\end{verbatim}
-
-In this example, the string \code{'writing a log message'} is marked as
-a candidate for translation, while the strings \code{'mylog.txt'} and
-\code{'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}\footnote{Fran\c cois 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
-\url{http://po-utils.progiciels-bpi.ca/}.} 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 \Cpp
-source code. You don't need GNU \code{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:
-
-\begin{verbatim}
-pygettext.py --help
-\end{verbatim}
-
-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}\footnote{\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.} 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 \module{gettext} module uses for the actual
-translation processing during run-time.
-
-How you use the \module{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.
-
-\subsubsection{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 \code{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:
-
-\begin{verbatim}
-import gettext
-t = gettext.translation('spam', '/usr/share/locale')
-_ = t.lgettext
-\end{verbatim}
-
-If your translators were providing you with Unicode strings in their
-\file{.po} files, you'd instead do:
-
-\begin{verbatim}
-import gettext
-t = gettext.translation('spam', '/usr/share/locale')
-_ = t.ugettext
-\end{verbatim}
-
-\subsubsection{Localizing your application}
-
-If you are localizing your application, you can install the \function{_()}
-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 \code{_('...')} 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:
-
-\begin{verbatim}
-import gettext
-gettext.install('myapplication')
-\end{verbatim}
-
-If you need to set the locale directory or the \var{unicode} flag,
-you can pass these into the \function{install()} function:
-
-\begin{verbatim}
-import gettext
-gettext.install('myapplication', '/usr/share/locale', unicode=1)
-\end{verbatim}
-
-\subsubsection{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:
-
-\begin{verbatim}
-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()
-\end{verbatim}
-
-\subsubsection{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:
-
-\begin{verbatim}
-animals = ['mollusk',
- 'albatross',
- 'rat',
- 'penguin',
- 'python',
- ]
-# ...
-for a in animals:
- print a
-\end{verbatim}
-
-Here, you want to mark the strings in the \code{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:
-
-\begin{verbatim}
-def _(message): return message
-
-animals = [_('mollusk'),
- _('albatross'),
- _('rat'),
- _('penguin'),
- _('python'),
- ]
-
-del _
-
-# ...
-for a in animals:
- print _(a)
-\end{verbatim}
-
-This works because the dummy definition of \function{_()} simply returns
-the string unchanged. And this dummy definition will temporarily
-override any definition of \function{_()} in the built-in namespace
-(until the \keyword{del} command).
-Take care, though if you have a previous definition of \function{_} in
-the local namespace.
-
-Note that the second use of \function{_()} 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:
-
-\begin{verbatim}
-def N_(message): return message
-
-animals = [N_('mollusk'),
- N_('albatross'),
- N_('rat'),
- N_('penguin'),
- N_('python'),
- ]
-
-# ...
-for a in animals:
- print _(a)
-\end{verbatim}
-
-In this case, you are marking translatable strings with the function
-\function{N_()},\footnote{The choice of \function{N_()} here is totally
-arbitrary; it could have just as easily been
-\function{MarkThisStringForTranslation()}.
-} which won't conflict with any definition of
-\function{_()}. However, you will need to teach your message extraction
-program to look for translatable strings marked with \function{N_()}.
-\program{pygettext} and \program{xpot} both support this through the
-use of command line switches.
-
-\subsubsection{\function{gettext()} vs. \function{lgettext()}}
-In Python 2.4 the \function{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 \function{gettext()}, which
-returns strings encoded with the same codeset used in the
-translation file, \function{lgettext()} will return strings
-encoded with the preferred system encoding, as returned by
-\function{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 \function{lgettext()} will return translated strings in
-the requested codeset, as would be expected in the GNU gettext
-implementation.
-
-\subsection{Acknowledgements}
-
-The following people contributed code, feedback, design suggestions,
-previous implementations, and valuable experience to the creation of
-this module:
-
-\begin{itemize}
- \item Peter Funk
- \item James Henstridge
- \item Juan David Ib\'a\~nez Palomar
- \item Marc-Andr\'e Lemburg
- \item Martin von L\"owis
- \item Fran\c cois Pinard
- \item Barry Warsaw
- \item Gustavo Niemeyer
-\end{itemize}
diff --git a/Doc/lib/libglob.tex b/Doc/lib/libglob.tex
deleted file mode 100644
index f3f4fb7..0000000
--- a/Doc/lib/libglob.tex
+++ /dev/null
@@ -1,51 +0,0 @@
-\section{\module{glob} ---
- \UNIX{} style pathname pattern expansion}
-
-\declaremodule{standard}{glob}
-\modulesynopsis{\UNIX\ shell style pathname pattern expansion.}
-
-
-The \module{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 \code{*}, \code{?}, and character ranges
-expressed with \code{[]} will be correctly matched. This is done by
-using the \function{os.listdir()} and \function{fnmatch.fnmatch()}
-functions in concert, and not by actually invoking a subshell. (For
-tilde and shell variable expansion, use \function{os.path.expanduser()}
-and \function{os.path.expandvars()}.)
-\index{filenames!pathname expansion}
-
-\begin{funcdesc}{glob}{pathname}
-Return a possibly-empty list of path names that match \var{pathname},
-which must be a string containing a path specification.
-\var{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).
-\end{funcdesc}
-
-\begin{funcdesc}{iglob}{pathname}
-Return an iterator which yields the same values as \function{glob()}
-without actually storing them all simultaneously.
-\versionadded{2.5}
-\end{funcdesc}
-
-For example, consider a directory containing only the following files:
-\file{1.gif}, \file{2.txt}, and \file{card.gif}. \function{glob()}
-will produce the following results. Notice how any leading components
-of the path are preserved.
-
-\begin{verbatim}
->>> import glob
->>> glob.glob('./[0-9].*')
-['./1.gif', './2.txt']
->>> glob.glob('*.gif')
-['1.gif', 'card.gif']
->>> glob.glob('?.gif')
-['1.gif']
-\end{verbatim}
-
-
-\begin{seealso}
- \seemodule{fnmatch}{Shell-style filename (not path) expansion}
-\end{seealso}
diff --git a/Doc/lib/libgrp.tex b/Doc/lib/libgrp.tex
deleted file mode 100644
index 3eed7d0..0000000
--- a/Doc/lib/libgrp.tex
+++ /dev/null
@@ -1,49 +0,0 @@
-\section{\module{grp} ---
- The group database}
-
-\declaremodule{builtin}{grp}
- \platform{Unix}
-\modulesynopsis{The group database (\function{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 \code{group} structure
-(Attribute field below, see \code{<pwd.h>}):
-
-\begin{tableiii}{r|l|l}{textrm}{Index}{Attribute}{Meaning}
- \lineiii{0}{gr_name}{the name of the group}
- \lineiii{1}{gr_passwd}{the (encrypted) group password; often empty}
- \lineiii{2}{gr_gid}{the numerical group ID}
- \lineiii{3}{gr_mem}{all the group member's user names}
-\end{tableiii}
-
-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:
-
-\begin{funcdesc}{getgrgid}{gid}
-Return the group database entry for the given numeric group ID.
-\exception{KeyError} is raised if the entry asked for cannot be found.
-\end{funcdesc}
-
-\begin{funcdesc}{getgrnam}{name}
-Return the group database entry for the given group name.
-\exception{KeyError} is raised if the entry asked for cannot be found.
-\end{funcdesc}
-
-\begin{funcdesc}{getgrall}{}
-Return a list of all available group entries, in arbitrary order.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{pwd}{An interface to the user database, similar to this.}
- \seemodule{spwd}{An interface to the shadow password database, similar to this.}
-\end{seealso}
diff --git a/Doc/lib/libgzip.tex b/Doc/lib/libgzip.tex
deleted file mode 100644
index b4cc659..0000000
--- a/Doc/lib/libgzip.tex
+++ /dev/null
@@ -1,70 +0,0 @@
-\section{\module{gzip} ---
- Support for \program{gzip} files}
-
-\declaremodule{standard}{gzip}
-\modulesynopsis{Interfaces for \program{gzip} compression and
-decompression using file objects.}
-
-
-The data compression provided by the \code{zlib} module is compatible
-with that used by the GNU compression program \program{gzip}.
-Accordingly, the \module{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:
-
-\begin{classdesc}{GzipFile}{\optional{filename\optional{, mode\optional{,
- compresslevel\optional{, fileobj}}}}}
-Constructor for the \class{GzipFile} class, which simulates most of
-the methods of a file object, with the exception of the \method{readinto()}
-and \method{truncate()} methods. At least one of
-\var{fileobj} and \var{filename} must be given a non-trivial value.
-
-The new class instance is based on \var{fileobj}, which can be a
-regular file, a \class{StringIO} object, or any other object which
-simulates a file. It defaults to \code{None}, in which case
-\var{filename} is opened to provide a file object.
-
-When \var{fileobj} is not \code{None}, the \var{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 \var{fileobj}, if discernible; otherwise, it
-defaults to the empty string, and in this case the original filename
-is not included in the header.
-
-The \var{mode} argument can be any of \code{'r'}, \code{'rb'},
-\code{'a'}, \code{'ab'}, \code{'w'}, or \code{'wb'}, depending on
-whether the file will be read or written. The default is the mode of
-\var{fileobj} if discernible; otherwise, the default is \code{'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 \var{compresslevel} argument is an integer from \code{1} to
-\code{9} controlling the level of compression; \code{1} is fastest and
-produces the least compression, and \code{9} is slowest and produces
-the most compression. The default is \code{9}.
-
-Calling a \class{GzipFile} object's \method{close()} method does not
-close \var{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 \var{fileobj}, and
-retrieve the resulting memory buffer using the \class{StringIO}
-object's \method{getvalue()} method.
-\end{classdesc}
-
-\begin{funcdesc}{open}{filename\optional{, mode\optional{, compresslevel}}}
-This is a shorthand for \code{GzipFile(\var{filename},}
-\code{\var{mode},} \code{\var{compresslevel})}. The \var{filename}
-argument is required; \var{mode} defaults to \code{'rb'} and
-\var{compresslevel} defaults to \code{9}.
-\end{funcdesc}
-
-\begin{seealso}
- \seemodule{zlib}{The basic data compression module needed to support
- the \program{gzip} file format.}
-\end{seealso}
diff --git a/Doc/lib/libhashlib.tex b/Doc/lib/libhashlib.tex
deleted file mode 100644
index 17f5179..0000000
--- a/Doc/lib/libhashlib.tex
+++ /dev/null
@@ -1,114 +0,0 @@
-\section{\module{hashlib} ---
- Secure hashes and message digests}
-
-\declaremodule{builtin}{hashlib}
-\modulesynopsis{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{message digest, MD5}
-\index{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 \function{sha1()} to create a SHA1 hash object.
-You can now feed this object with arbitrary strings using the \method{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 \method{digest()} or
-\method{hexdigest()} methods.
-
-Constructors for hash algorithms that are always present in this module are
-\function{md5()}, \function{sha1()}, \function{sha224()}, \function{sha256()},
-\function{sha384()}, and \function{sha512()}. Additional algorithms may also
-be available depending upon the OpenSSL library that Python uses on your platform.
-\index{OpenSSL}
-
-For example, to obtain the digest of the string \code{'Nobody inspects
-the spammish repetition'}:
-
-\begin{verbatim}
->>> 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'
-\end{verbatim}
-
-More condensed:
-
-\begin{verbatim}
->>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
-'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
-\end{verbatim}
-
-A generic \function{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 \function{new()} and
-should be preferred.
-
-Using \function{new()} with an algorithm provided by OpenSSL:
-
-\begin{verbatim}
->>> h = hashlib.new('ripemd160')
->>> h.update("Nobody inspects the spammish repetition")
->>> h.hexdigest()
-'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
-\end{verbatim}
-
-The following values are provided as constant attributes of the hash objects
-returned by the constructors:
-
-\begin{datadesc}{digest_size}
- The size of the resulting digest in bytes.
-\end{datadesc}
-
-A hash object has the following methods:
-
-\begin{methoddesc}[hash]{update}{arg}
-Update the hash object with the string \var{arg}. Repeated calls are
-equivalent to a single call with the concatenation of all the
-arguments: \code{m.update(a); m.update(b)} is equivalent to
-\code{m.update(a+b)}.
-\end{methoddesc}
-
-\begin{methoddesc}[hash]{digest}{}
-Return the digest of the strings passed to the \method{update()}
-method so far. This is a string of \member{digest_size} bytes which may
-contain non-\ASCII{} characters, including null bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[hash]{hexdigest}{}
-Like \method{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.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{seealso}
- \seemodule{hmac}{A module to generate message authentication codes using hashes.}
- \seemodule{base64}{Another way to encode binary hashes for non-binary environments.}
- \seeurl{http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf}
- {The FIPS 180-2 publication on Secure Hash Algorithms.}
- \seeurl{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.}
-\end{seealso}
diff --git a/Doc/lib/libheapq.tex b/Doc/lib/libheapq.tex
deleted file mode 100644
index e403a3a..0000000
--- a/Doc/lib/libheapq.tex
+++ /dev/null
@@ -1,225 +0,0 @@
-\section{\module{heapq} ---
- Heap queue algorithm}
-
-\declaremodule{standard}{heapq}
-\modulesynopsis{Heap queue algorithm (a.k.a. priority queue).}
-\moduleauthor{Kevin O'Connor}{}
-\sectionauthor{Guido van Rossum}{guido@python.org}
-% Theoretical explanation:
-\sectionauthor{Fran\c cois Pinard}{}
-\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
-\code{\var{heap}[\var{k}] <= \var{heap}[2*\var{k}+1]} and
-\code{\var{heap}[\var{k}] <= \var{heap}[2*\var{k}+2]}
-for all \var{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 \code{\var{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: \code{\var{heap}[0]} is the smallest item, and
-\code{\var{heap}.sort()} maintains the heap invariant!
-
-To create a heap, use a list initialized to \code{[]}, or you can
-transform a populated list into a heap via function \function{heapify()}.
-
-The following functions are provided:
-
-\begin{funcdesc}{heappush}{heap, item}
-Push the value \var{item} onto the \var{heap}, maintaining the
-heap invariant.
-\end{funcdesc}
-
-\begin{funcdesc}{heappop}{heap}
-Pop and return the smallest item from the \var{heap}, maintaining the
-heap invariant. If the heap is empty, \exception{IndexError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{heapify}{x}
-Transform list \var{x} into a heap, in-place, in linear time.
-\end{funcdesc}
-
-\begin{funcdesc}{heapreplace}{heap, item}
-Pop and return the smallest item from the \var{heap}, and also push
-the new \var{item}. The heap size doesn't change.
-If the heap is empty, \exception{IndexError} is raised.
-This is more efficient than \function{heappop()} followed
-by \function{heappush()}, and can be more appropriate when using
-a fixed-size heap. Note that the value returned may be larger
-than \var{item}! That constrains reasonable uses of this routine
-unless written as part of a conditional replacement:
-\begin{verbatim}
- if item > heap[0]:
- item = heapreplace(heap, item)
-\end{verbatim}
-\end{funcdesc}
-
-Example of use:
-
-\begin{verbatim}
->>> 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
->>>
-\end{verbatim}
-
-The module also offers three general purpose functions based on heaps.
-
-\begin{funcdesc}{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 \code{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}
-\end{funcdesc}
-
-\begin{funcdesc}{nlargest}{n, iterable\optional{, key}}
-Return a list with the \var{n} largest elements from the dataset defined
-by \var{iterable}. \var{key}, if provided, specifies a function of one
-argument that is used to extract a comparison key from each element
-in the iterable: \samp{\var{key}=\function{str.lower}}
-Equivalent to: \samp{sorted(iterable, key=key, reverse=True)[:n]}
-\versionadded{2.4}
-\versionchanged[Added the optional \var{key} argument]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{nsmallest}{n, iterable\optional{, key}}
-Return a list with the \var{n} smallest elements from the dataset defined
-by \var{iterable}. \var{key}, if provided, specifies a function of one
-argument that is used to extract a comparison key from each element
-in the iterable: \samp{\var{key}=\function{str.lower}}
-Equivalent to: \samp{sorted(iterable, key=key)[:n]}
-\versionadded{2.4}
-\versionchanged[Added the optional \var{key} argument]{2.5}
-\end{funcdesc}
-
-The latter two functions perform best for smaller values of \var{n}. For larger
-values, it is more efficient to use the \function{sorted()} function. Also,
-when \code{n==1}, it is more efficient to use the builtin \function{min()}
-and \function{max()} functions.
-
-
-\subsection{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 \code{a[\var{k}] <= a[2*\var{k}+1]} and
-\code{a[\var{k}] <= a[2*\var{k}+2]}
-for all \var{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 \code{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 \var{k}, not
-\code{a[\var{k}]}:
-
-\begin{verbatim}
- 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
-\end{verbatim}
-
-In the tree above, each cell \var{k} is topping \code{2*\var{k}+1} and
-\code{2*\var{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\footnote{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! :-)}.
-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. :-)
diff --git a/Doc/lib/libhmac.tex b/Doc/lib/libhmac.tex
deleted file mode 100644
index 5329cb5..0000000
--- a/Doc/lib/libhmac.tex
+++ /dev/null
@@ -1,54 +0,0 @@
-\section{\module{hmac} ---
- Keyed-Hashing for Message Authentication}
-
-\declaremodule{standard}{hmac}
-\modulesynopsis{Keyed-Hashing for Message Authentication (HMAC)
- implementation for Python.}
-\moduleauthor{Gerhard H{\"a}ring}{ghaering@users.sourceforge.net}
-\sectionauthor{Gerhard H{\"a}ring}{ghaering@users.sourceforge.net}
-
-\versionadded{2.2}
-
-This module implements the HMAC algorithm as described by \rfc{2104}.
-
-\begin{funcdesc}{new}{key\optional{, msg\optional{, digestmod}}}
- Return a new hmac object. If \var{msg} is present, the method call
- \code{update(\var{msg})} is made. \var{digestmod} is the digest
- constructor or module for the HMAC object to use. It defaults to
- the \function{\refmodule{hashlib}.md5} constructor. \note{The md5 hash
- has known weaknesses but remains the default for backwards compatibility.
- Choose a better one for your application.}
-\end{funcdesc}
-
-An HMAC object has the following methods:
-
-\begin{methoddesc}[hmac]{update}{msg}
- Update the hmac object with the string \var{msg}. Repeated calls
- are equivalent to a single call with the concatenation of all the
- arguments: \code{m.update(a); m.update(b)} is equivalent to
- \code{m.update(a + b)}.
-\end{methoddesc}
-
-\begin{methoddesc}[hmac]{digest}{}
- Return the digest of the strings passed to the \method{update()}
- method so far. This string will be the same length as the
- \var{digest_size} of the digest given to the constructor. It
- may contain non-\ASCII{} characters, including NUL bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[hmac]{hexdigest}{}
- Like \method{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.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{seealso}
- \seemodule{hashlib}{The python module providing secure hash functions.}
-\end{seealso}
diff --git a/Doc/lib/libhotshot.tex b/Doc/lib/libhotshot.tex
deleted file mode 100644
index 0004e37..0000000
--- a/Doc/lib/libhotshot.tex
+++ /dev/null
@@ -1,137 +0,0 @@
-\section{\module{hotshot} ---
- High performance logging profiler}
-
-\declaremodule{standard}{hotshot}
-\modulesynopsis{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 \module{_hotshot} C module.
-Hotshot is a replacement for the existing \refmodule{profile} module. As it's
-written mostly in C, it should result in a much smaller performance impact
-than the existing \refmodule{profile} module.
-
-\begin{notice}[note]
- The \module{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 \module{cProfile} instead.
- \module{hotshot} is not maintained and might be removed from the
- standard library in the future.
-\end{notice}
-
-\versionchanged[the results should be more meaningful than in the
-past: the timing core contained a critical bug]{2.5}
-
-\begin{notice}[warning]
- The \module{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.
-\end{notice}
-
-
-\begin{classdesc}{Profile}{logfile\optional{, lineevents\optional{,
- linetimings}}}
-The profiler object. The argument \var{logfile} is the name of a log
-file to use for logged profile data. The argument \var{lineevents}
-specifies whether to generate events for every source line, or just on
-function call/return. It defaults to \code{0} (only log function
-call/return). The argument \var{linetimings} specifies whether to
-record timing information. It defaults to \code{1} (store timing
-information).
-\end{classdesc}
-
-
-\subsection{Profile Objects \label{hotshot-objects}}
-
-Profile objects have the following methods:
-
-\begin{methoddesc}[Profile]{addinfo}{key, value}
-Add an arbitrary labelled value to the profile output.
-\end{methoddesc}
-
-\begin{methoddesc}[Profile]{close}{}
-Close the logfile and terminate the profiler.
-\end{methoddesc}
-
-\begin{methoddesc}[Profile]{fileno}{}
-Return the file descriptor of the profiler's log file.
-\end{methoddesc}
-
-\begin{methoddesc}[Profile]{run}{cmd}
-Profile an \function{exec()}-compatible string in the script environment.
-The globals from the \refmodule[main]{__main__} module are used as
-both the globals and locals for the script.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-
-\begin{methoddesc}[Profile]{runctx}{cmd, globals, locals}
-Profile an \function{exec()}-compatible string in a specific environment.
-The string is compiled before profiling begins.
-\end{methoddesc}
-
-\begin{methoddesc}[Profile]{start}{}
-Start the profiler.
-\end{methoddesc}
-
-\begin{methoddesc}[Profile]{stop}{}
-Stop the profiler.
-\end{methoddesc}
-
-
-\subsection{Using hotshot data}
-
-\declaremodule{standard}{hotshot.stats}
-\modulesynopsis{Statistical analysis for Hotshot}
-
-\versionadded{2.2}
-
-This module loads hotshot profiling data into the standard \module{pstats}
-Stats objects.
-
-\begin{funcdesc}{load}{filename}
-Load hotshot data from \var{filename}. Returns an instance
-of the \class{pstats.Stats} class.
-\end{funcdesc}
-
-\begin{seealso}
- \seemodule{profile}{The \module{profile} module's \class{Stats} class}
-\end{seealso}
-
-
-\subsection{Example Usage \label{hotshot-example}}
-
-Note that this example runs the python ``benchmark'' pystones. It can
-take some time to run, and will produce large output files.
-
-\begin{verbatim}
->>> 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)
- .
- .
- .
-\end{verbatim}
diff --git a/Doc/lib/libhtmllib.tex b/Doc/lib/libhtmllib.tex
deleted file mode 100644
index e51dfcb..0000000
--- a/Doc/lib/libhtmllib.tex
+++ /dev/null
@@ -1,181 +0,0 @@
-\section{\module{htmllib} ---
- A parser for HTML documents}
-
-\declaremodule{standard}{htmllib}
-\modulesynopsis{A parser for HTML documents.}
-
-\index{HTML}
-\index{hypertext}
-
-
-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
-\refmodule{sgmllib}\refstmodindex{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 \refmodule{formatter}\refstmodindex{formatter}\ module; refer to the
-documentation for that module for information on the formatter
-interface.
-\withsubitem{(in module sgmllib)}{\ttindex{SGMLParser}}
-
-The following is a summary of the interface defined by
-\class{sgmllib.SGMLParser}:
-
-\begin{itemize}
-
-\item
-The interface to feed data to an instance is through the \method{feed()}
-method, which takes a string argument. This can be called with as
-little or as much text at a time as desired; \samp{p.feed(a);
-p.feed(b)} has the same effect as \samp{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 \method{close()} method.
-
-For example, to parse the entire contents of a file, use:
-\begin{verbatim}
-parser.feed(open('myfile.html').read())
-parser.close()
-\end{verbatim}
-
-\item
-The interface to define semantics for HTML tags is very simple: derive
-a class and define methods called \method{start_\var{tag}()},
-\method{end_\var{tag}()}, or \method{do_\var{tag}()}. The parser will
-call these at appropriate moments: \method{start_\var{tag}} or
-\method{do_\var{tag}()} is called when an opening tag of the form
-\code{<\var{tag} ...>} is encountered; \method{end_\var{tag}()} is called
-when a closing tag of the form \code{<\var{tag}>} is encountered. If
-an opening tag requires a corresponding closing tag, like \code{<H1>}
-... \code{</H1>}, the class should define the \method{start_\var{tag}()}
-method; if a tag requires no closing tag, like \code{<P>}, the class
-should define the \method{do_\var{tag}()} method.
-
-\end{itemize}
-
-The module defines a parser class and an exception:
-
-\begin{classdesc}{HTMLParser}{formatter}
-This is the basic HTML parser class. It supports all entity names
-required by the XHTML 1.0 Recommendation (\url{http://www.w3.org/TR/xhtml1}).
-It also defines handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements.
-\end{classdesc}
-
-\begin{excdesc}{HTMLParseError}
-Exception raised by the \class{HTMLParser} class when it encounters an
-error while parsing.
-\versionadded{2.4}
-\end{excdesc}
-
-
-\begin{seealso}
- \seemodule{formatter}{Interface definition for transforming an
- abstract flow of formatting events into
- specific output events on writer objects.}
- \seemodule{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.}
- \seemodule{htmlentitydefs}{Definition of replacement text for XHTML 1.0
- entities.}
- \seemodule{sgmllib}{Base class for \class{HTMLParser}.}
-\end{seealso}
-
-
-\subsection{HTMLParser Objects \label{html-parser-objects}}
-
-In addition to tag methods, the \class{HTMLParser} class provides some
-additional methods and instance variables for use within tag methods.
-
-\begin{memberdesc}[HTMLParser]{formatter}
-This is the formatter instance associated with the parser.
-\end{memberdesc}
-
-\begin{memberdesc}[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 \code{<PRE>} element. The default value is false. This
-affects the operation of \method{handle_data()} and \method{save_end()}.
-\end{memberdesc}
-
-
-\begin{methoddesc}[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 \code{<A>} tag with the same
-names. The default implementation maintains a list of hyperlinks
-(defined by the \code{HREF} attribute for \code{<A>} tags) within the
-document. The list of hyperlinks is available as the data attribute
-\member{anchorlist}.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \method{anchor_bgn()}.
-\end{methoddesc}
-
-\begin{methoddesc}[HTMLParser]{handle_image}{source, alt\optional{, ismap\optional{,
- align\optional{, width\optional{, height}}}}}
-This method is called to handle images. The default implementation
-simply passes the \var{alt} value to the \method{handle_data()}
-method.
-\end{methoddesc}
-
-\begin{methoddesc}[HTMLParser]{save_bgn}{}
-Begins saving character data in a buffer instead of sending it to the
-formatter object. Retrieve the stored data via \method{save_end()}.
-Use of the \method{save_bgn()} / \method{save_end()} pair may not be
-nested.
-\end{methoddesc}
-
-\begin{methoddesc}[HTMLParser]{save_end}{}
-Ends buffering character data and returns all data saved since the
-preceding call to \method{save_bgn()}. If the \member{nofill} flag is
-false, whitespace is collapsed to single spaces. A call to this
-method without a preceding call to \method{save_bgn()} will raise a
-\exception{TypeError} exception.
-\end{methoddesc}
-
-
-
-\section{\module{htmlentitydefs} ---
- Definitions of HTML general entities}
-
-\declaremodule{standard}{htmlentitydefs}
-\modulesynopsis{Definitions of HTML general entities.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-This module defines three dictionaries, \code{name2codepoint},
-\code{codepoint2name}, and \code{entitydefs}. \code{entitydefs} is
-used by the \refmodule{htmllib} module to provide the
-\member{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).
-
-
-\begin{datadesc}{entitydefs}
- A dictionary mapping XHTML 1.0 entity definitions to their
- replacement text in ISO Latin-1.
-
-\end{datadesc}
-
-\begin{datadesc}{name2codepoint}
- A dictionary that maps HTML entity names to the Unicode codepoints.
- \versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{codepoint2name}
- A dictionary that maps Unicode codepoints to HTML entity names.
- \versionadded{2.3}
-\end{datadesc}
diff --git a/Doc/lib/libhtmlparser.tex b/Doc/lib/libhtmlparser.tex
deleted file mode 100644
index 5e99f27..0000000
--- a/Doc/lib/libhtmlparser.tex
+++ /dev/null
@@ -1,173 +0,0 @@
-\section{\module{HTMLParser} ---
- Simple HTML and XHTML parser}
-
-\declaremodule{standard}{HTMLParser}
-\modulesynopsis{A simple parser that can handle HTML and XHTML.}
-
-\versionadded{2.2}
-
-This module defines a class \class{HTMLParser} which serves as the
-basis for parsing text files formatted in HTML\index{HTML} (HyperText
-Mark-up Language) and XHTML.\index{XHTML} Unlike the parser in
-\refmodule{htmllib}, this parser is not based on the SGML parser in
-\refmodule{sgmllib}.
-
-
-\begin{classdesc}{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 \refmodule{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.
-\end{classdesc}
-
-An exception is defined as well:
-
-\begin{excdesc}{HTMLParseError}
-Exception raised by the \class{HTMLParser} class when it encounters an
-error while parsing. This exception provides three attributes:
-\member{msg} is a brief message explaining the error, \member{lineno}
-is the number of the line on which the broken construct was detected,
-and \member{offset} is the number of characters into the line at which
-the construct starts.
-\end{excdesc}
-
-
-\class{HTMLParser} instances have the following methods:
-
-\begin{methoddesc}{reset}{}
-Reset the instance. Loses all unprocessed data. This is called
-implicitly at instantiation time.
-\end{methoddesc}
-
-\begin{methoddesc}{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 \method{close()} is called.
-\end{methoddesc}
-
-\begin{methoddesc}{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 \method{close()}.
-\end{methoddesc}
-
-\begin{methoddesc}{getpos}{}
-Return current line number and offset.
-\end{methoddesc}
-
-\begin{methoddesc}{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.).
-\end{methoddesc}
-
-\begin{methoddesc}{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 \var{tag} argument is the name of the tag converted to lower case.
-The \var{attrs} argument is a list of \code{(\var{name}, \var{value})}
-pairs containing the attributes found inside the tag's \code{<>}
-brackets. The \var{name} will be translated to lower case, and quotes
-in the \var{value} have been removed, and character and entity
-references have been replaced. For instance, for the tag \code{<A
- HREF="http://www.cwi.nl/">}, this method would be called as
-\samp{handle_starttag('a', [('href', 'http://www.cwi.nl/')])}.
-
-\versionchanged[All entity references from htmlentitydefs are now
-replaced in the attribute values]{2.6}
-
-\end{methoddesc}
-
-\begin{methoddesc}{handle_startendtag}{tag, attrs}
-Similar to \method{handle_starttag()}, but called when the parser
-encounters an XHTML-style empty tag (\code{<a .../>}). This method
-may be overridden by subclasses which require this particular lexical
-information; the default implementation simple calls
-\method{handle_starttag()} and \method{handle_endtag()}.
-\end{methoddesc}
-
-\begin{methoddesc}{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 \var{tag} argument is the name of
-the tag converted to lower case.
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_charref}{name} This method is called to
-process a character reference of the form \samp{\&\#\var{ref};}. It
-is intended to be overridden by a derived class; the base class
-implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_entityref}{name}
-This method is called to process a general entity reference of the
-form \samp{\&\var{name};} where \var{name} is an general entity
-reference. It is intended to be overridden by a derived class; the
-base class implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_comment}{data}
-This method is called when a comment is encountered. The
-\var{comment} argument is a string containing the text between the
-\samp{--} and \samp{--} delimiters, but not the delimiters
-themselves. For example, the comment \samp{<!--text-->} will
-cause this method to be called with the argument \code{'text'}. It is
-intended to be overridden by a derived class; the base class
-implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_decl}{decl}
-Method called when an SGML declaration is read by the parser. The
-\var{decl} parameter will be the entire contents of the declaration
-inside the \code{<!}...\code{>} markup. It is intended to be overridden
-by a derived class; the base class implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_pi}{data}
-Method called when a processing instruction is encountered. The
-\var{data} parameter will contain the entire processing instruction.
-For example, for the processing instruction \code{<?proc color='red'>},
-this method would be called as \code{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 \character{?} will cause the \character{?} to be included in
-\var{data}.}
-\end{methoddesc}
-
-
-\subsection{Example HTML Parser Application \label{htmlparser-example}}
-
-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:
-
-\begin{verbatim}
-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
-\end{verbatim}
diff --git a/Doc/lib/libhttplib.tex b/Doc/lib/libhttplib.tex
deleted file mode 100644
index 37a442d..0000000
--- a/Doc/lib/libhttplib.tex
+++ /dev/null
@@ -1,452 +0,0 @@
-\section{\module{httplib} ---
- HTTP protocol client}
-
-\declaremodule{standard}{httplib}
-\modulesynopsis{HTTP and HTTPS protocol client (requires sockets).}
-
-\indexii{HTTP}{protocol}
-\index{HTTP!\module{httplib} (standard module)}
-
-This module defines classes which implement the client side of the
-HTTP and HTTPS protocols. It is normally not used directly --- the
-module \refmodule{urllib}\refstmodindex{urllib} uses it to handle URLs
-that use HTTP and HTTPS.
-
-\begin{notice}
- HTTPS support is only available if the \refmodule{socket} module was
- compiled with SSL support.
-\end{notice}
-
-\begin{notice}
- 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.
-\end{notice}
-
-The module provides the following classes:
-
-\begin{classdesc}{HTTPConnection}{host\optional{, port\optional{,
- strict\optional{, 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 \code{\var{host}:\var{port}}, else the default HTTP port (80) is
-used. When True, the optional parameter \var{strict}
-causes \code{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 \var{timeout}
-parameter is given, connection attempts will timeout after that many
-seconds (if it is not given or \code{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:
-
-\begin{verbatim}
->>> 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)
-\end{verbatim}
-\versionadded{2.0}
-\versionchanged[\var{timeout} was added]{2.6}
-\end{classdesc}
-
-\begin{classdesc}{HTTPSConnection}{host\optional{, port\optional{,
- key_file\optional{, cert_file\optional{,
- strict\optional{, timeout}}}}}}
-A subclass of \class{HTTPConnection} that uses SSL for communication with
-secure servers. Default port is \code{443}.
-\var{key_file} is
-the name of a PEM formatted file that contains your private
-key. \var{cert_file} is a PEM formatted certificate chain file.
-
-\warning{This does not do any certificate verification!}
-
-\versionadded{2.0}
-\versionchanged[\var{timeout} was added]{2.6}
-\end{classdesc}
-
-\begin{classdesc}{HTTPResponse}{sock\optional{, debuglevel=0}\optional{, strict=0}}
-Class whose instances are returned upon successful connection. Not
-instantiated directly by user.
-\versionadded{2.0}
-\end{classdesc}
-
-The following exceptions are raised as appropriate:
-
-\begin{excdesc}{HTTPException}
-The base class of the other exceptions in this module. It is a
-subclass of \exception{Exception}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{NotConnected}
-A subclass of \exception{HTTPException}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{InvalidURL}
-A subclass of \exception{HTTPException}, raised if a port is given and is
-either non-numeric or empty.
-\versionadded{2.3}
-\end{excdesc}
-
-\begin{excdesc}{UnknownProtocol}
-A subclass of \exception{HTTPException}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{UnknownTransferEncoding}
-A subclass of \exception{HTTPException}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{UnimplementedFileMode}
-A subclass of \exception{HTTPException}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{IncompleteRead}
-A subclass of \exception{HTTPException}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{ImproperConnectionState}
-A subclass of \exception{HTTPException}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{CannotSendRequest}
-A subclass of \exception{ImproperConnectionState}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{CannotSendHeader}
-A subclass of \exception{ImproperConnectionState}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{ResponseNotReady}
-A subclass of \exception{ImproperConnectionState}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{BadStatusLine}
-A subclass of \exception{HTTPException}. Raised if a server responds with a
-HTTP status code that we don't understand.
-\versionadded{2.0}
-\end{excdesc}
-
-The constants defined in this module are:
-
-\begin{datadesc}{HTTP_PORT}
- The default port for the HTTP protocol (always \code{80}).
-\end{datadesc}
-
-\begin{datadesc}{HTTPS_PORT}
- The default port for the HTTPS protocol (always \code{443}).
-\end{datadesc}
-
-and also the following constants for integer status codes:
-
-\begin{tableiii}{l|c|l}{constant}{Constant}{Value}{Definition}
- \lineiii{CONTINUE}{\code{100}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.1.1}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.1}}
- \lineiii{SWITCHING_PROTOCOLS}{\code{101}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.1.2}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.2}}
- \lineiii{PROCESSING}{\code{102}}
- {WEBDAV, \ulink{RFC 2518, Section 10.1}
- {http://www.webdav.org/specs/rfc2518.html#STATUS_102}}
-
- \lineiii{OK}{\code{200}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.2.1}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1}}
- \lineiii{CREATED}{\code{201}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.2.2}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2}}
- \lineiii{ACCEPTED}{\code{202}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.2.3}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3}}
- \lineiii{NON_AUTHORITATIVE_INFORMATION}{\code{203}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.2.4}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.4}}
- \lineiii{NO_CONTENT}{\code{204}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.2.5}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5}}
- \lineiii{RESET_CONTENT}{\code{205}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.2.6}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.6}}
- \lineiii{PARTIAL_CONTENT}{\code{206}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.2.7}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.7}}
- \lineiii{MULTI_STATUS}{\code{207}}
- {WEBDAV \ulink{RFC 2518, Section 10.2}
- {http://www.webdav.org/specs/rfc2518.html#STATUS_207}}
- \lineiii{IM_USED}{\code{226}}
- {Delta encoding in HTTP, \rfc{3229}, Section 10.4.1}
-
- \lineiii{MULTIPLE_CHOICES}{\code{300}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.3.1}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.1}}
- \lineiii{MOVED_PERMANENTLY}{\code{301}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.3.2}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2}}
- \lineiii{FOUND}{\code{302}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.3.3}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3}}
- \lineiii{SEE_OTHER}{\code{303}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.3.4}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.4}}
- \lineiii{NOT_MODIFIED}{\code{304}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.3.5}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.5}}
- \lineiii{USE_PROXY}{\code{305}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.3.6}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.6}}
- \lineiii{TEMPORARY_REDIRECT}{\code{307}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.3.8}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.8}}
-
- \lineiii{BAD_REQUEST}{\code{400}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.1}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1}}
- \lineiii{UNAUTHORIZED}{\code{401}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.2}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2}}
- \lineiii{PAYMENT_REQUIRED}{\code{402}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.3}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.3}}
- \lineiii{FORBIDDEN}{\code{403}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.4}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4}}
- \lineiii{NOT_FOUND}{\code{404}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.5}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5}}
- \lineiii{METHOD_NOT_ALLOWED}{\code{405}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.6}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6}}
- \lineiii{NOT_ACCEPTABLE}{\code{406}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.7}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7}}
- \lineiii{PROXY_AUTHENTICATION_REQUIRED}
- {\code{407}}{HTTP/1.1, \ulink{RFC 2616, Section 10.4.8}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.8}}
- \lineiii{REQUEST_TIMEOUT}{\code{408}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.9}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.9}}
- \lineiii{CONFLICT}{\code{409}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.10}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10}}
- \lineiii{GONE}{\code{410}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.11}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.11}}
- \lineiii{LENGTH_REQUIRED}{\code{411}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.12}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.12}}
- \lineiii{PRECONDITION_FAILED}{\code{412}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.13}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.13}}
- \lineiii{REQUEST_ENTITY_TOO_LARGE}
- {\code{413}}{HTTP/1.1, \ulink{RFC 2616, Section 10.4.14}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.14}}
- \lineiii{REQUEST_URI_TOO_LONG}{\code{414}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.15}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.15}}
- \lineiii{UNSUPPORTED_MEDIA_TYPE}{\code{415}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.16}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16}}
- \lineiii{REQUESTED_RANGE_NOT_SATISFIABLE}{\code{416}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.17}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.17}}
- \lineiii{EXPECTATION_FAILED}{\code{417}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.18}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.18}}
- \lineiii{UNPROCESSABLE_ENTITY}{\code{422}}
- {WEBDAV, \ulink{RFC 2518, Section 10.3}
- {http://www.webdav.org/specs/rfc2518.html#STATUS_422}}
- \lineiii{LOCKED}{\code{423}}
- {WEBDAV \ulink{RFC 2518, Section 10.4}
- {http://www.webdav.org/specs/rfc2518.html#STATUS_423}}
- \lineiii{FAILED_DEPENDENCY}{\code{424}}
- {WEBDAV, \ulink{RFC 2518, Section 10.5}
- {http://www.webdav.org/specs/rfc2518.html#STATUS_424}}
- \lineiii{UPGRADE_REQUIRED}{\code{426}}
- {HTTP Upgrade to TLS, \rfc{2817}, Section 6}
-
- \lineiii{INTERNAL_SERVER_ERROR}{\code{500}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.5.1}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1}}
- \lineiii{NOT_IMPLEMENTED}{\code{501}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.5.2}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2}}
- \lineiii{BAD_GATEWAY}{\code{502}}
- {HTTP/1.1 \ulink{RFC 2616, Section 10.5.3}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.3}}
- \lineiii{SERVICE_UNAVAILABLE}{\code{503}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.5.4}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4}}
- \lineiii{GATEWAY_TIMEOUT}{\code{504}}
- {HTTP/1.1 \ulink{RFC 2616, Section 10.5.5}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.5}}
- \lineiii{HTTP_VERSION_NOT_SUPPORTED}{\code{505}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.5.6}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.6}}
- \lineiii{INSUFFICIENT_STORAGE}{\code{507}}
- {WEBDAV, \ulink{RFC 2518, Section 10.6}
- {http://www.webdav.org/specs/rfc2518.html#STATUS_507}}
- \lineiii{NOT_EXTENDED}{\code{510}}
- {An HTTP Extension Framework, \rfc{2774}, Section 7}
-\end{tableiii}
-
-\begin{datadesc}{responses}
-This dictionary maps the HTTP 1.1 status codes to the W3C names.
-
-Example: \code{httplib.responses[httplib.NOT_FOUND]} is \code{'Not Found'}.
-\versionadded{2.5}
-\end{datadesc}
-
-
-\subsection{HTTPConnection Objects \label{httpconnection-objects}}
-
-\class{HTTPConnection} instances have the following methods:
-
-\begin{methoddesc}[HTTPConnection]{request}{method, url\optional{, body\optional{, headers}}}
-This will send a request to the server using the HTTP request method
-\var{method} and the selector \var{url}. If the \var{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
-\code{fileno()} and \code{read()} methods.
-The header Content-Length is automatically set to the correct value.
-The \var{headers} argument should be a mapping of extra HTTP headers to send
-with the request.
-
-\versionchanged[\var{body} can be a file object]{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}[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.}
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPConnection]{set_debuglevel}{level}
-Set the debugging level (the amount of debugging output printed).
-The default debug level is \code{0}, meaning no debugging output is
-printed.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPConnection]{connect}{}
-Connect to the server specified when the object was created.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPConnection]{close}{}
-Close the connection to the server.
-\end{methoddesc}
-
-As an alternative to using the \method{request()} method described above,
-you can also send your request step by step, by using the four functions
-below.
-
-\begin{methoddesc}[HTTPConnection]{putrequest}{request, selector\optional{,
-skip\_host\optional{, 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
-\var{request} string, the \var{selector} string, and the HTTP version
-(\code{HTTP/1.1}). To disable automatic sending of \code{Host:} or
-\code{Accept-Encoding:} headers (for example to accept additional
-content encodings), specify \var{skip_host} or \var{skip_accept_encoding}
-with non-False values.
-\versionchanged[\var{skip_accept_encoding} argument added]{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPConnection]{putheader}{header, argument\optional{, ...}}
-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.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPConnection]{endheaders}{}
-Send a blank line to the server, signalling the end of the headers.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPConnection]{send}{data}
-Send data to the server. This should be used directly only after the
-\method{endheaders()} method has been called and before
-\method{getresponse()} is called.
-\end{methoddesc}
-
-\subsection{HTTPResponse Objects \label{httpresponse-objects}}
-
-\class{HTTPResponse} instances have the following methods and attributes:
-
-\begin{methoddesc}[HTTPResponse]{read}{\optional{amt}}
-Reads and returns the response body, or up to the next \var{amt} bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPResponse]{getheader}{name\optional{, default}}
-Get the contents of the header \var{name}, or \var{default} if there is no
-matching header.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPResponse]{getheaders}{}
-Return a list of (header, value) tuples. \versionadded{2.4}
-\end{methoddesc}
-
-\begin{memberdesc}[HTTPResponse]{msg}
- A \class{mimetools.Message} instance containing the response headers.
-\end{memberdesc}
-
-\begin{memberdesc}[HTTPResponse]{version}
- HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1.
-\end{memberdesc}
-
-\begin{memberdesc}[HTTPResponse]{status}
- Status code returned by server.
-\end{memberdesc}
-
-\begin{memberdesc}[HTTPResponse]{reason}
- Reason phrase returned by server.
-\end{memberdesc}
-
-
-\subsection{Examples \label{httplib-examples}}
-
-Here is an example session that uses the \samp{GET} method:
-
-\begin{verbatim}
->>> 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()
-\end{verbatim}
-
-Here is an example session that shows how to \samp{POST} requests:
-
-\begin{verbatim}
->>> 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()
-\end{verbatim}
diff --git a/Doc/lib/libimaplib.tex b/Doc/lib/libimaplib.tex
deleted file mode 100644
index e34caaa..0000000
--- a/Doc/lib/libimaplib.tex
+++ /dev/null
@@ -1,507 +0,0 @@
-\section{\module{imaplib} ---
- IMAP4 protocol client}
-
-\declaremodule{standard}{imaplib}
-\modulesynopsis{IMAP4 protocol client (requires sockets).}
-\moduleauthor{Piers Lauder}{piers@communitysolutions.com.au}
-\sectionauthor{Piers Lauder}{piers@communitysolutions.com.au}
-
-% 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
-
-\indexii{IMAP4}{protocol}
-\indexii{IMAP4_SSL}{protocol}
-\indexii{IMAP4_stream}{protocol}
-
-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
-\samp{STATUS} command is not supported in IMAP4.
-
-Three classes are provided by the \module{imaplib} module,
-\class{IMAP4} is the base class:
-
-\begin{classdesc}{IMAP4}{\optional{host\optional{, 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 \var{host} is not specified, \code{''} (the local host) is used.
-If \var{port} is omitted, the standard IMAP4 port (143) is used.
-\end{classdesc}
-
-Three exceptions are defined as attributes of the \class{IMAP4} class:
-
-\begin{excdesc}{IMAP4.error}
-Exception raised on any errors. The reason for the exception is
-passed to the constructor as a string.
-\end{excdesc}
-
-\begin{excdesc}{IMAP4.abort}
-IMAP4 server errors cause this exception to be raised. This is a
-sub-class of \exception{IMAP4.error}. Note that closing the instance
-and instantiating a new one will usually allow recovery from this
-exception.
-\end{excdesc}
-
-\begin{excdesc}{IMAP4.readonly}
-This exception is raised when a writable mailbox has its status
-changed by the server. This is a sub-class of
-\exception{IMAP4.error}. Some other client now has write permission,
-and the mailbox will need to be re-opened to re-obtain write
-permission.
-\end{excdesc}
-
-There's also a subclass for secure connections:
-
-\begin{classdesc}{IMAP4_SSL}{\optional{host\optional{, port\optional{,
- keyfile\optional{, 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 \var{host} is not specified,
-\code{''} (the local host) is used. If \var{port} is omitted, the
-standard IMAP4-over-SSL port (993) is used. \var{keyfile} and
-\var{certfile} are also optional - they can contain a PEM formatted
-private key and certificate chain file for the SSL connection.
-\end{classdesc}
-
-The second subclass allows for connections created by a child process:
-
-\begin{classdesc}{IMAP4_stream}{command}
-This is a subclass derived from \class{IMAP4} that connects
-to the \code{stdin/stdout} file descriptors created by passing
-\var{command} to \code{os.popen2()}.
-\versionadded{2.3}
-\end{classdesc}
-
-The following utility functions are defined:
-
-\begin{funcdesc}{Internaldate2tuple}{datestr}
- Converts an IMAP4 INTERNALDATE string to Coordinated Universal
- Time. Returns a \refmodule{time} module tuple.
-\end{funcdesc}
-
-\begin{funcdesc}{Int2AP}{num}
- Converts an integer into a string representation using characters
- from the set [\code{A} .. \code{P}].
-\end{funcdesc}
-
-\begin{funcdesc}{ParseFlags}{flagstr}
- Converts an IMAP4 \samp{FLAGS} response to a tuple of individual
- flags.
-\end{funcdesc}
-
-\begin{funcdesc}{Time2Internaldate}{date_time}
- Converts a \refmodule{time} module tuple to an IMAP4
- \samp{INTERNALDATE} representation. Returns a string in the form:
- \code{"DD-Mmm-YYYY HH:MM:SS +HHMM"} (including double-quotes).
-\end{funcdesc}
-
-
-Note that IMAP4 message numbers change as the mailbox changes; in
-particular, after an \samp{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.
-
-\begin{seealso}
- \seetext{Documents describing the protocol, and sources and binaries
- for servers implementing it, can all be found at the
- University of Washington's \emph{IMAP Information Center}
- (\url{http://www.cac.washington.edu/imap/}).}
-\end{seealso}
-
-
-\subsection{IMAP4 Objects \label{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
-\samp{AUTHENTICATE}, and the last argument to \samp{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
-\var{password} argument to the \samp{LOGIN} command is always quoted.
-If you want to avoid having an argument string quoted
-(eg: the \var{flags} argument to \samp{STORE}) then enclose the string in
-parentheses (eg: \code{r'(\e Deleted)'}).
-
-Each command returns a tuple: \code{(\var{type}, [\var{data},
-...])} where \var{type} is usually \code{'OK'} or \code{'NO'},
-and \var{data} is either the text from the command response, or
-mandated results from the command. Each \var{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 \var{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
-(\code{'1'}), a range of message numbers (\code{'2:4'}), or a group of
-non-contiguous ranges separated by commas (\code{'1:3,6:9'}). A range
-can contain an asterisk to indicate an infinite upper bound
-(\code{'3:*'}).
-
-An \class{IMAP4} instance has the following methods:
-
-
-\begin{methoddesc}[IMAP4]{append}{mailbox, flags, date_time, message}
- Append \var{message} to named mailbox.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{authenticate}{mechanism, authobject}
- Authenticate command --- requires response processing.
-
- \var{mechanism} specifies which authentication mechanism is to be
- used - it should appear in the instance variable \code{capabilities}
- in the form \code{AUTH=mechanism}.
-
- \var{authobject} must be a callable object:
-
-\begin{verbatim}
-data = authobject(response)
-\end{verbatim}
-
- It will be called to process server continuation responses.
- It should return \code{data} that will be encoded and sent to server.
- It should return \code{None} if the client abort response \samp{*} should
- be sent instead.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{check}{}
- Checkpoint mailbox on server.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{close}{}
- Close currently selected mailbox. Deleted messages are removed from
- writable mailbox. This is the recommended command before
- \samp{LOGOUT}.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{copy}{message_set, new_mailbox}
- Copy \var{message_set} messages onto end of \var{new_mailbox}.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{create}{mailbox}
- Create new mailbox named \var{mailbox}.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{delete}{mailbox}
- Delete old mailbox named \var{mailbox}.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{deleteacl}{mailbox, who}
- Delete the ACLs (remove any rights) set for who on mailbox.
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{expunge}{}
- Permanently remove deleted items from selected mailbox. Generates an
- \samp{EXPUNGE} response for each deleted message. Returned data
- contains a list of \samp{EXPUNGE} message numbers in order
- received.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{fetch}{message_set, message_parts}
- Fetch (parts of) messages. \var{message_parts} should be
- a string of message part names enclosed within parentheses,
- eg: \samp{"(UID BODY[TEXT])"}. Returned data are tuples
- of message part envelope and data.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{getacl}{mailbox}
- Get the \samp{ACL}s for \var{mailbox}.
- The method is non-standard, but is supported by the \samp{Cyrus} server.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{getannotation}{mailbox, entry, attribute}
- Retrieve the specified \samp{ANNOTATION}s for \var{mailbox}.
- The method is non-standard, but is supported by the \samp{Cyrus} server.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{getquota}{root}
- Get the \samp{quota} \var{root}'s resource usage and limits.
- This method is part of the IMAP4 QUOTA extension defined in rfc2087.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{getquotaroot}{mailbox}
- Get the list of \samp{quota} \samp{roots} for the named \var{mailbox}.
- This method is part of the IMAP4 QUOTA extension defined in rfc2087.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{list}{\optional{directory\optional{, pattern}}}
- List mailbox names in \var{directory} matching
- \var{pattern}. \var{directory} defaults to the top-level mail
- folder, and \var{pattern} defaults to match anything. Returned data
- contains a list of \samp{LIST} responses.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{login}{user, password}
- Identify the client using a plaintext password.
- The \var{password} will be quoted.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{login_cram_md5}{user, password}
- Force use of \samp{CRAM-MD5} authentication when identifying the
- client to protect the password. Will only work if the server
- \samp{CAPABILITY} response includes the phrase \samp{AUTH=CRAM-MD5}.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{logout}{}
- Shutdown connection to server. Returns server \samp{BYE} response.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{lsub}{\optional{directory\optional{, pattern}}}
- List subscribed mailbox names in directory matching pattern.
- \var{directory} defaults to the top level directory and
- \var{pattern} defaults to match any mailbox.
- Returned data are tuples of message part envelope and data.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{myrights}{mailbox}
- Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{namespace}{}
- Returns IMAP namespaces as defined in RFC2342.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{noop}{}
- Send \samp{NOOP} to server.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{open}{host, port}
- Opens socket to \var{port} at \var{host}.
- The connection objects established by this method
- will be used in the \code{read}, \code{readline}, \code{send}, and
- \code{shutdown} methods.
- You may override this method.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{proxyauth}{user}
- Assume authentication as \var{user}.
- Allows an authorised administrator to proxy into any user's mailbox.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{read}{size}
- Reads \var{size} bytes from the remote server.
- You may override this method.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{readline}{}
- Reads one line from the remote server.
- You may override this method.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{recent}{}
- Prompt server for an update. Returned data is \code{None} if no new
- messages, else value of \samp{RECENT} response.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{rename}{oldmailbox, newmailbox}
- Rename mailbox named \var{oldmailbox} to \var{newmailbox}.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{response}{code}
- Return data for response \var{code} if received, or
- \code{None}. Returns the given code, instead of the usual type.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{search}{charset, criterion\optional{, ...}}
- Search mailbox for matching messages. \var{charset} may be
- \code{None}, in which case no \samp{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:
-
-\begin{verbatim}
-# M is a connected IMAP4 instance...
-typ, msgnums = M.search(None, 'FROM', '"LDJ"')
-
-# or:
-typ, msgnums = M.search(None, '(FROM "LDJ")')
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{select}{\optional{mailbox\optional{, readonly}}}
- Select a mailbox. Returned data is the count of messages in
- \var{mailbox} (\samp{EXISTS} response). The default \var{mailbox}
- is \code{'INBOX'}. If the \var{readonly} flag is set, modifications
- to the mailbox are not allowed.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{send}{data}
- Sends \code{data} to the remote server.
- You may override this method.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{setacl}{mailbox, who, what}
- Set an \samp{ACL} for \var{mailbox}.
- The method is non-standard, but is supported by the \samp{Cyrus} server.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{setannotation}{mailbox, entry, attribute\optional{, ...}}
- Set \samp{ANNOTATION}s for \var{mailbox}.
- The method is non-standard, but is supported by the \samp{Cyrus} server.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{setquota}{root, limits}
- Set the \samp{quota} \var{root}'s resource \var{limits}.
- This method is part of the IMAP4 QUOTA extension defined in rfc2087.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{shutdown}{}
- Close connection established in \code{open}.
- You may override this method.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{socket}{}
- Returns socket instance used to connect to server.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{sort}{sort_criteria, charset, search_criterion\optional{, ...}}
- The \code{sort} command is a variant of \code{search} with sorting
- semantics for the results. Returned data contains a space separated
- list of matching message numbers.
-
- Sort has two arguments before the \var{search_criterion}
- argument(s); a parenthesized list of \var{sort_criteria}, and the
- searching \var{charset}. Note that unlike \code{search}, the
- searching \var{charset} argument is mandatory. There is also a
- \code{uid sort} command which corresponds to \code{sort} the way
- that \code{uid search} corresponds to \code{search}. The
- \code{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 \samp{IMAP4rev1} extension command.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{status}{mailbox, names}
- Request named status conditions for \var{mailbox}.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{store}{message_set, command, flag_list}
- Alters flag dispositions for messages in mailbox. \var{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:
-
-\begin{verbatim}
-typ, data = M.search(None, 'ALL')
-for num in data[0].split():
- M.store(num, '+FLAGS', '\\Deleted')
-M.expunge()
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{subscribe}{mailbox}
- Subscribe to new mailbox.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{thread}{threading_algorithm, charset,
- search_criterion\optional{, ...}}
- The \code{thread} command is a variant of \code{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 \var{search_criterion}
- argument(s); a \var{threading_algorithm}, and the searching
- \var{charset}. Note that unlike \code{search}, the searching
- \var{charset} argument is mandatory. There is also a \code{uid
- thread} command which corresponds to \code{thread} the way that
- \code{uid search} corresponds to \code{search}. The \code{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 \samp{IMAP4rev1} extension command. \versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{uid}{command, arg\optional{, ...}}
- 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.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{unsubscribe}{mailbox}
- Unsubscribe from old mailbox.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{xatom}{name\optional{, arg\optional{, ...}}}
- Allow simple extension commands notified by server in
- \samp{CAPABILITY} response.
-\end{methoddesc}
-
-
-Instances of \class{IMAP4_SSL} have just one additional method:
-
-\begin{methoddesc}[IMAP4_SSL]{ssl}{}
- Returns SSLObject instance used for the secure connection with the server.
-\end{methoddesc}
-
-
-The following attributes are defined on instances of \class{IMAP4}:
-
-
-\begin{memberdesc}[IMAP4]{PROTOCOL_VERSION}
-The most recent supported protocol in the
-\samp{CAPABILITY} response from the server.
-\end{memberdesc}
-
-\begin{memberdesc}[IMAP4]{debug}
-Integer value to control debugging output. The initialize value is
-taken from the module variable \code{Debug}. Values greater than
-three trace each command.
-\end{memberdesc}
-
-
-\subsection{IMAP4 Example \label{imap4-example}}
-
-Here is a minimal example (without error checking) that opens a
-mailbox and retrieves and prints all messages:
-
-\begin{verbatim}
-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()
-\end{verbatim}
diff --git a/Doc/lib/libimghdr.tex b/Doc/lib/libimghdr.tex
deleted file mode 100644
index 4a4f368..0000000
--- a/Doc/lib/libimghdr.tex
+++ /dev/null
@@ -1,60 +0,0 @@
-\section{\module{imghdr} ---
- Determine the type of an image}
-
-\declaremodule{standard}{imghdr}
-\modulesynopsis{Determine the type of image contained in a file or
- byte stream.}
-
-
-The \module{imghdr} module determines the type of image contained in a
-file or byte stream.
-
-The \module{imghdr} module defines the following function:
-
-
-\begin{funcdesc}{what}{filename\optional{, h}}
-Tests the image data contained in the file named by \var{filename},
-and returns a string describing the image type. If optional \var{h}
-is provided, the \var{filename} is ignored and \var{h} is assumed to
-contain the byte stream to test.
-\end{funcdesc}
-
-The following image types are recognized, as listed below with the
-return value from \function{what()}:
-
-\begin{tableii}{l|l}{code}{Value}{Image format}
- \lineii{'rgb'}{SGI ImgLib Files}
- \lineii{'gif'}{GIF 87a and 89a Files}
- \lineii{'pbm'}{Portable Bitmap Files}
- \lineii{'pgm'}{Portable Graymap Files}
- \lineii{'ppm'}{Portable Pixmap Files}
- \lineii{'tiff'}{TIFF Files}
- \lineii{'rast'}{Sun Raster Files}
- \lineii{'xbm'}{X Bitmap Files}
- \lineii{'jpeg'}{JPEG data in JFIF or Exif formats}
- \lineii{'bmp'}{BMP files}
- \lineii{'png'}{Portable Network Graphics}
-\end{tableii}
-
-\versionadded[Exif detection]{2.5}
-
-You can extend the list of file types \module{imghdr} can recognize by
-appending to this variable:
-
-\begin{datadesc}{tests}
-A list of functions performing the individual tests. Each function
-takes two arguments: the byte-stream and an open file-like object.
-When \function{what()} is called with a byte-stream, the file-like
-object will be \code{None}.
-
-The test function should return a string describing the image type if
-the test succeeded, or \code{None} if it failed.
-\end{datadesc}
-
-Example:
-
-\begin{verbatim}
->>> import imghdr
->>> imghdr.what('/tmp/bass.gif')
-'gif'
-\end{verbatim}
diff --git a/Doc/lib/libimp.tex b/Doc/lib/libimp.tex
deleted file mode 100644
index 6396605..0000000
--- a/Doc/lib/libimp.tex
+++ /dev/null
@@ -1,291 +0,0 @@
-\section{\module{imp} ---
- Access the \keyword{import} internals}
-
-\declaremodule{builtin}{imp}
-\modulesynopsis{Access the implementation of the \keyword{import} statement.}
-
-
-This\stindex{import} module provides an interface to the mechanisms
-used to implement the \keyword{import} statement. It defines the
-following constants and functions:
-
-
-\begin{funcdesc}{get_magic}{}
-\indexii{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.)
-\end{funcdesc}
-
-\begin{funcdesc}{get_suffixes}{}
-Return a list of triples, each describing a particular type of module.
-Each triple has the form \code{(\var{suffix}, \var{mode},
-\var{type})}, where \var{suffix} is a string to be appended to the
-module name to form the filename to search for, \var{mode} is the mode
-string to pass to the built-in \function{open()} function to open the
-file (this can be \code{'r'} for text files or \code{'rb'} for binary
-files), and \var{type} is the file type, which has one of the values
-\constant{PY_SOURCE}, \constant{PY_COMPILED}, or
-\constant{C_EXTENSION}, described below.
-\end{funcdesc}
-
-\begin{funcdesc}{find_module}{name\optional{, path}}
-Try to find the module \var{name} on the search path \var{path}. If
-\var{path} is a list of directory names, each directory is searched
-for files with any of the suffixes returned by \function{get_suffixes()}
-above. Invalid names in the list are silently ignored (but all list
-items must be strings). If \var{path} is omitted or \code{None}, the
-list of directory names given by \code{sys.path} is searched, but
-first it searches a few special places: it tries to find a built-in
-module with the given name (\constant{C_BUILTIN}), then a frozen module
-(\constant{PY_FROZEN}), and on some systems some other places are looked
-in as well (on the Mac, it looks for a resource (\constant{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
-\code{(\var{file}, \var{pathname}, \var{description})} where
-\var{file} is an open file object positioned at the beginning,
-\var{pathname} is the pathname of the
-file found, and \var{description} is a triple as contained in the list
-returned by \function{get_suffixes()} describing the kind of module found.
-If the module does not live in a file, the returned \var{file} is
-\code{None}, \var{filename} is the empty string, and the
-\var{description} tuple contains empty strings for its suffix and
-mode; the module type is as indicate in parentheses above. If the
-search is unsuccessful, \exception{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 \var{P}.\var{M}, that is, submodule
-\var{M} of package \var{P}, use \function{find_module()} and
-\function{load_module()} to find and load package \var{P}, and then use
-\function{find_module()} with the \var{path} argument set to
-\code{\var{P}.__path__}. When \var{P} itself has a dotted name, apply
-this recipe recursively.
-\end{funcdesc}
-
-\begin{funcdesc}{load_module}{name, file, filename, description}
-Load a module that was previously found by \function{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 will reload the module! The \var{name} argument
-indicates the full module name (including the package name, if this is
-a submodule of a package). The \var{file} argument is an open file,
-and \var{filename} is the corresponding file name; these can be
-\code{None} and \code{''}, respectively, when the module is not being
-loaded from a file. The \var{description} argument is a tuple, as
-would be returned by \function{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 \exception{ImportError}) is raised.
-
-\strong{Important:} the caller is responsible for closing the
-\var{file} argument, if it was not \code{None}, even when an exception
-is raised. This is best done using a \keyword{try}
-... \keyword{finally} statement.
-\end{funcdesc}
-
-\begin{funcdesc}{new_module}{name}
-Return a new empty module object called \var{name}. This object is
-\emph{not} inserted in \code{sys.modules}.
-\end{funcdesc}
-
-\begin{funcdesc}{lock_held}{}
-Return \code{True} if the import lock is currently held, else \code{False}.
-On platforms without threads, always return \code{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).
-\end{funcdesc}
-
-\begin{funcdesc}{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}
-\end{funcdesc}
-
-\begin{funcdesc}{release_lock}{}
-Release the interpreter's import lock.
-On platforms without threads, this function does nothing.
-\versionadded{2.3}
-\end{funcdesc}
-
-The following constants with integer values, defined in this module,
-are used to indicate the search result of \function{find_module()}.
-
-\begin{datadesc}{PY_SOURCE}
-The module was found as a source file.
-\end{datadesc}
-
-\begin{datadesc}{PY_COMPILED}
-The module was found as a compiled code object file.
-\end{datadesc}
-
-\begin{datadesc}{C_EXTENSION}
-The module was found as dynamically loadable shared library.
-\end{datadesc}
-
-\begin{datadesc}{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.
-\end{datadesc}
-
-\begin{datadesc}{PKG_DIRECTORY}
-The module was found as a package directory.
-\end{datadesc}
-
-\begin{datadesc}{C_BUILTIN}
-The module was found as a built-in module.
-\end{datadesc}
-
-\begin{datadesc}{PY_FROZEN}
-The module was found as a frozen module (see \function{init_frozen()}).
-\end{datadesc}
-
-The following constant and functions are obsolete; their functionality
-is available through \function{find_module()} or \function{load_module()}.
-They are kept around for backward compatibility:
-
-\begin{datadesc}{SEARCH_ERROR}
-Unused.
-\end{datadesc}
-
-\begin{funcdesc}{init_builtin}{name}
-Initialize the built-in module called \var{name} and return its module
-object along with storing it in \code{sys.modules}. If the module was already
-initialized, it will be initialized \emph{again}. Re-initialization involves
-the copying of the built-in module's \code{__dict__} from the cached
-module over the module's entry in \code{sys.modules}. If there is no
-built-in module called \var{name}, \code{None} is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{init_frozen}{name}
-Initialize the frozen module called \var{name} and return its module
-object. If the module was already initialized, it will be initialized
-\emph{again}. If there is no frozen module called \var{name},
-\code{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.)
-\end{funcdesc}
-
-\begin{funcdesc}{is_builtin}{name}
-Return \code{1} if there is a built-in module called \var{name} which
-can be initialized again. Return \code{-1} if there is a built-in
-module called \var{name} which cannot be initialized again (see
-\function{init_builtin()}). Return \code{0} if there is no built-in
-module called \var{name}.
-\end{funcdesc}
-
-\begin{funcdesc}{is_frozen}{name}
-Return \code{True} if there is a frozen module (see
-\function{init_frozen()}) called \var{name}, or \code{False} if there is
-no such module.
-\end{funcdesc}
-
-\begin{funcdesc}{load_compiled}{name, pathname, \optional{file}}
-\indexii{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 \emph{again}. The \var{name} argument is used
-to create or access a module object. The \var{pathname} argument
-points to the byte-compiled code file. The \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{load_dynamic}{name, pathname\optional{, 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 \emph{again}.
-Re-initialization involves copying the \code{__dict__} attribute of the cached
-instance of the module over the value used in the module cached in
-\code{sys.modules}. The \var{pathname} argument must point to the shared
-library. The \var{name} argument is used to construct the name of the
-initialization function: an external C function called
-\samp{init\var{name}()} in the shared library is called. The optional
-\var{file} argument is ignored. (Note: using shared libraries is highly
-system dependent, and not all systems support it.)
-\end{funcdesc}
-
-\begin{funcdesc}{load_source}{name, pathname\optional{, 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 \emph{again}. The \var{name} argument is used to
-create or access a module object. The \var{pathname} argument points
-to the source file. The \var{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.
-\end{funcdesc}
-
-\begin{classdesc}{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
-\exception{ImportError}. Otherwise, a \class{NullImporter} instance is
-returned.
-
-Python adds instances of this type to \code{sys.path_importer_cache} for
-any path entries that are not directories and are not handled by any other
-path hooks on \code{sys.path_hooks}. Instances have only one method:
-
-\begin{methoddesc}{find_module}{fullname \optional{, path}}
-This method always returns \code{None}, indicating that the requested
-module could not be found.
-\end{methoddesc}
-
-\versionadded{2.5}
-\end{classdesc}
-
-\subsection{Examples}
-\label{examples-imp}
-
-The following function emulates what was the standard import statement
-up to Python 1.4 (no hierarchical module names). (This
-\emph{implementation} wouldn't work in that version, since
-\function{find_module()} has been extended and
-\function{load_module()} has been added in 1.4.)
-
-\begin{verbatim}
-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()
-\end{verbatim}
-
-A more complete example that implements hierarchical module names and
-includes a \function{reload()} function can be
-found in the module \module{knee}\refmodindex{knee}. The
-\module{knee} module can be found in \file{Demo/imputil/} in the
-Python source distribution.
diff --git a/Doc/lib/libinspect.tex b/Doc/lib/libinspect.tex
deleted file mode 100644
index c9a63fc..0000000
--- a/Doc/lib/libinspect.tex
+++ /dev/null
@@ -1,391 +0,0 @@
-\section{\module{inspect} ---
- Inspect live objects}
-
-\declaremodule{standard}{inspect}
-\modulesynopsis{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 \module{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.
-
-\subsection{Types and members
- \label{inspect-types}}
-
-The \function{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
-\function{getmembers()}. They also help you determine when
-you can expect to find the following special attributes:
-
-\begin{tableiv}{c|l|l|c}{}{Type}{Attribute}{Description}{Notes}
- \lineiv{module}{__doc__}{documentation string}{}
- \lineiv{}{__file__}{filename (missing for built-in modules)}{}
- \hline
- \lineiv{class}{__doc__}{documentation string}{}
- \lineiv{}{__module__}{name of module in which this class was defined}{}
- \hline
- \lineiv{method}{__doc__}{documentation string}{}
- \lineiv{}{__name__}{name with which this method was defined}{}
- \lineiv{}{im_class}{class object that asked for this method}{(1)}
- \lineiv{}{im_func}{function object containing implementation of method}{}
- \lineiv{}{im_self}{instance to which this method is bound, or \code{None}}{}
- \hline
- \lineiv{function}{__doc__}{documentation string}{}
- \lineiv{}{__name__}{name with which this function was defined}{}
- \lineiv{}{__code__}{code object containing compiled function bytecode}{}
- \lineiv{}{__defaults__}{tuple of any default values for arguments}{}
- \lineiv{}{__globals__}{global namespace in which this function was defined}{}
- \hline
- \lineiv{traceback}{tb_frame}{frame object at this level}{}
- \lineiv{}{tb_lasti}{index of last attempted instruction in bytecode}{}
- \lineiv{}{tb_lineno}{current line number in Python source code}{}
- \lineiv{}{tb_next}{next inner traceback object (called by this level)}{}
- \hline
- \lineiv{frame}{f_back}{next outer frame object (this frame's caller)}{}
- \lineiv{}{f_builtins}{built-in namespace seen by this frame}{}
- \lineiv{}{f_code}{code object being executed in this frame}{}
- \lineiv{}{f_exc_traceback}{traceback if raised in this frame, or \code{None}}{}
- \lineiv{}{f_exc_type}{exception type if raised in this frame, or \code{None}}{}
- \lineiv{}{f_exc_value}{exception value if raised in this frame, or \code{None}}{}
- \lineiv{}{f_globals}{global namespace seen by this frame}{}
- \lineiv{}{f_lasti}{index of last attempted instruction in bytecode}{}
- \lineiv{}{f_lineno}{current line number in Python source code}{}
- \lineiv{}{f_locals}{local namespace seen by this frame}{}
- \lineiv{}{f_restricted}{0 or 1 if frame is in restricted execution mode}{}
- \lineiv{}{f_trace}{tracing function for this frame, or \code{None}}{}
- \hline
- \lineiv{code}{co_argcount}{number of arguments (not including * or ** args)}{}
- \lineiv{}{co_code}{string of raw compiled bytecode}{}
- \lineiv{}{co_consts}{tuple of constants used in the bytecode}{}
- \lineiv{}{co_filename}{name of file in which this code object was created}{}
- \lineiv{}{co_firstlineno}{number of first line in Python source code}{}
- \lineiv{}{co_flags}{bitmap: 1=optimized \code{|} 2=newlocals \code{|} 4=*arg \code{|} 8=**arg}{}
- \lineiv{}{co_lnotab}{encoded mapping of line numbers to bytecode indices}{}
- \lineiv{}{co_name}{name with which this code object was defined}{}
- \lineiv{}{co_names}{tuple of names of local variables}{}
- \lineiv{}{co_nlocals}{number of local variables}{}
- \lineiv{}{co_stacksize}{virtual machine stack space required}{}
- \lineiv{}{co_varnames}{tuple of names of arguments and local variables}{}
- \hline
- \lineiv{builtin}{__doc__}{documentation string}{}
- \lineiv{}{__name__}{original name of this function or method}{}
- \lineiv{}{__self__}{instance to which a method is bound, or \code{None}}{}
-\end{tableiv}
-
-\noindent
-Note:
-\begin{description}
-\item[(1)]
-\versionchanged[\member{im_class} used to refer to the class that
- defined the method]{2.2}
-\end{description}
-
-
-\begin{funcdesc}{getmembers}{object\optional{, predicate}}
- Return all the members of an object in a list of (name, value) pairs
- sorted by name. If the optional \var{predicate} argument is supplied,
- only members for which the predicate returns a true value are included.
-\end{funcdesc}
-
-\begin{funcdesc}{getmoduleinfo}{path}
- Return a tuple of values that describe how Python will interpret the
- file identified by \var{path} if it is a module, or \code{None} if
- it would not be identified as a module. The return tuple is
- \code{(\var{name}, \var{suffix}, \var{mode}, \var{mtype})}, where
- \var{name} is the name of the module without the name of any
- enclosing package, \var{suffix} is the trailing part of the file
- name (which may not be a dot-delimited extension), \var{mode} is the
- \function{open()} mode that would be used (\code{'r'} or
- \code{'rb'}), and \var{mtype} is an integer giving the type of the
- module. \var{mtype} will have a value which can be compared to the
- constants defined in the \refmodule{imp} module; see the
- documentation for that module for more information on module types.
-\end{funcdesc}
-
-\begin{funcdesc}{getmodulename}{path}
- Return the name of the module named by the file \var{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,
- \code{None} is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{ismodule}{object}
- Return true if the object is a module.
-\end{funcdesc}
-
-\begin{funcdesc}{isclass}{object}
- Return true if the object is a class.
-\end{funcdesc}
-
-\begin{funcdesc}{ismethod}{object}
- Return true if the object is a method.
-\end{funcdesc}
-
-\begin{funcdesc}{isfunction}{object}
- Return true if the object is a Python function or unnamed (lambda) function.
-\end{funcdesc}
-
-\begin{funcdesc}{istraceback}{object}
- Return true if the object is a traceback.
-\end{funcdesc}
-
-\begin{funcdesc}{isframe}{object}
- Return true if the object is a frame.
-\end{funcdesc}
-
-\begin{funcdesc}{iscode}{object}
- Return true if the object is a code.
-\end{funcdesc}
-
-\begin{funcdesc}{isbuiltin}{object}
- Return true if the object is a built-in function.
-\end{funcdesc}
-
-\begin{funcdesc}{isroutine}{object}
- Return true if the object is a user-defined or built-in function or method.
-\end{funcdesc}
-
-\begin{funcdesc}{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().
-\end{funcdesc}
-
-\begin{funcdesc}{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}
-\end{funcdesc}
-
-\begin{funcdesc}{isgetsetdescriptor}{object}
- Return true if the object is a getset descriptor.
-
- getsets are attributes defined in extension modules via \code{PyGetSetDef}
- structures. For Python implementations without such types, this method will
- always return \code{False}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{ismemberdescriptor}{object}
- Return true if the object is a member descriptor.
-
- Member descriptors are attributes defined in extension modules via
- \code{PyMemberDef} structures. For Python implementations without such
- types, this method will always return \code{False}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\subsection{Retrieving source code
- \label{inspect-source}}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{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).
-\end{funcdesc}
-
-\begin{funcdesc}{getfile}{object}
- Return the name of the (text or binary) file in which an object was
- defined. This will fail with a \exception{TypeError} if the object
- is a built-in module, class, or function.
-\end{funcdesc}
-
-\begin{funcdesc}{getmodule}{object}
- Try to guess which module an object was defined in.
-\end{funcdesc}
-
-\begin{funcdesc}{getsourcefile}{object}
- Return the name of the Python source file in which an object was
- defined. This will fail with a \exception{TypeError} if the object
- is a built-in module, class, or function.
-\end{funcdesc}
-
-\begin{funcdesc}{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
- \exception{IOError} is raised if the source code cannot be retrieved.
-\end{funcdesc}
-
-\begin{funcdesc}{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
- \exception{IOError} is raised if the source code cannot be retrieved.
-\end{funcdesc}
-
-\subsection{Classes and functions
- \label{inspect-classes-functions}}
-
-\begin{funcdesc}{getclasstree}{classes\optional{, 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 \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{getargspec}{func}
- Get the names and default values of a function's arguments.
- A tuple of four things is returned: \code{(\var{args},
- \var{varargs}, \var{varkw}, \var{defaults})}.
- \var{args} is a list of the argument names (it may contain nested lists).
- \var{varargs} and \var{varkw} are the names of the \code{*} and
- \code{**} arguments or \code{None}.
- \var{defaults} is a tuple of default argument values or None if there are no
- default arguments; if this tuple has \var{n} elements, they correspond to
- the last \var{n} elements listed in \var{args}.
-\end{funcdesc}
-
-\begin{funcdesc}{getargvalues}{frame}
- Get information about arguments passed into a particular frame.
- A tuple of four things is returned: \code{(\var{args},
- \var{varargs}, \var{varkw}, \var{locals})}.
- \var{args} is a list of the argument names (it may contain nested
- lists).
- \var{varargs} and \var{varkw} are the names of the \code{*} and
- \code{**} arguments or \code{None}.
- \var{locals} is the locals dictionary of the given frame.
-\end{funcdesc}
-
-\begin{funcdesc}{formatargspec}{args\optional{, varargs, varkw, defaults,
- formatarg, formatvarargs, formatvarkw, formatvalue, join}}
-
- Format a pretty argument spec from the four values returned by
- \function{getargspec()}. The format* arguments are the
- corresponding optional formatting functions that are called to turn
- names and values into strings.
-\end{funcdesc}
-
-\begin{funcdesc}{formatargvalues}{args\optional{, varargs, varkw, locals,
- formatarg, formatvarargs, formatvarkw, formatvalue, join}}
- Format a pretty argument spec from the four values returned by
- \function{getargvalues()}. The format* arguments are the
- corresponding optional formatting functions that are called to turn
- names and values into strings.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\subsection{The interpreter stack
- \label{inspect-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.
-
-\begin{notice}[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
-\function{\refmodule{gc}.disable()}. For example:
-
-\begin{verbatim}
-def handle_stackframe_without_leak():
- frame = inspect.currentframe()
- try:
- # do something with the frame
- finally:
- del frame
-\end{verbatim}
-\end{notice}
-
-The optional \var{context} argument supported by most of these
-functions specifies the number of lines of context to return, which
-are centered around the current line.
-
-\begin{funcdesc}{getframeinfo}{frame\optional{, context}}
- Get information about a frame or traceback object. A 5-tuple
- is returned, the last five elements of the frame's frame record.
-\end{funcdesc}
-
-\begin{funcdesc}{getouterframes}{frame\optional{, 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 \var{frame}.
- The first entry in the returned list represents \var{frame}; the
- last entry represents the outermost call on \var{frame}'s stack.
-\end{funcdesc}
-
-\begin{funcdesc}{getinnerframes}{traceback\optional{, 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
- \var{frame}. The first entry in the list represents
- \var{traceback}; the last entry represents where the exception was
- raised.
-\end{funcdesc}
-
-\begin{funcdesc}{currentframe}{}
- Return the frame object for the caller's stack frame.
-\end{funcdesc}
-
-\begin{funcdesc}{stack}{\optional{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.
-\end{funcdesc}
-
-\begin{funcdesc}{trace}{\optional{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.
-\end{funcdesc}
diff --git a/Doc/lib/libintro.tex b/Doc/lib/libintro.tex
deleted file mode 100644
index 62434cd..0000000
--- a/Doc/lib/libintro.tex
+++ /dev/null
@@ -1,53 +0,0 @@
-\chapter{Introduction}
-\label{intro}
-
-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 \emph{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
-\refmodule{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}, ``Built-in Types, Exceptions and
-Functions,'' as the remainder of the manual assumes familiarity with
-this material.
-
-Let the show begin!
diff --git a/Doc/lib/libitertools.tex b/Doc/lib/libitertools.tex
deleted file mode 100644
index b4784a8..0000000
--- a/Doc/lib/libitertools.tex
+++ /dev/null
@@ -1,575 +0,0 @@
-\section{\module{itertools} ---
- Functions creating iterators for efficient looping}
-
-\declaremodule{standard}{itertools}
-\modulesynopsis{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: \code{tabulate(f)}
-which produces a sequence \code{f(0), f(1), ...}. This toolbox
-provides \function{imap()} and \function{count()} which can be combined
-to form \code{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 \refmodule{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.
-
-\begin{seealso}
- \seetext{The Standard ML Basis Library,
- \citetitle[http://www.standardml.org/Basis/]
- {The Standard ML Basis Library}.}
-
- \seetext{Haskell, A Purely Functional Language,
- \citetitle[http://www.haskell.org/definition/]
- {Definition of Haskell and the Standard Libraries}.}
-\end{seealso}
-
-
-\subsection{Itertool functions \label{itertools-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.
-
-\begin{funcdesc}{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:
-
- \begin{verbatim}
- def chain(*iterables):
- for it in iterables:
- for element in it:
- yield element
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{count}{\optional{n}}
- Make an iterator that returns consecutive integers starting with \var{n}.
- If not specified \var{n} defaults to zero.
- Does not currently support python long integers. Often used as an
- argument to \function{imap()} to generate consecutive data points.
- Also, used with \function{izip()} to add sequence numbers. Equivalent to:
-
- \begin{verbatim}
- def count(n=0):
- while True:
- yield n
- n += 1
- \end{verbatim}
-
- Note, \function{count()} does not check for overflow and will return
- negative numbers after exceeding \code{sys.maxint}. This behavior
- may change in the future.
-\end{funcdesc}
-
-\begin{funcdesc}{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:
-
- \begin{verbatim}
- def cycle(iterable):
- saved = []
- for element in iterable:
- yield element
- saved.append(element)
- while saved:
- for element in saved:
- yield element
- \end{verbatim}
-
- Note, this member of the toolkit may require significant
- auxiliary storage (depending on the length of the iterable).
-\end{funcdesc}
-
-\begin{funcdesc}{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 \emph{any} output until the predicate
- first becomes false, so it may have a lengthy start-up time. Equivalent to:
-
- \begin{verbatim}
- def dropwhile(predicate, iterable):
- iterable = iter(iterable)
- for x in iterable:
- if not predicate(x):
- yield x
- break
- for x in iterable:
- yield x
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{groupby}{iterable\optional{, key}}
- Make an iterator that returns consecutive keys and groups from the
- \var{iterable}. The \var{key} is a function computing a key value for each
- element. If not specified or is \code{None}, \var{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 \function{groupby()} is similar to the \code{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 \function{groupby()}. Because the source is shared, when
- the \function{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:
-
- \begin{verbatim}
- 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)
- \end{verbatim}
-
- \function{groupby()} is equivalent to:
-
- \begin{verbatim}
- 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 = []
- def __iter__(self):
- return self
- def __next__(self):
- while self.currkey == self.tgtkey:
- self.currvalue = next(self.it) # 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 = next(self.it) # Exit on StopIteration
- self.currkey = self.keyfunc(self.currvalue)
- \end{verbatim}
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{ifilter}{predicate, iterable}
- Make an iterator that filters elements from iterable returning only
- those for which the predicate is \code{True}.
- If \var{predicate} is \code{None}, return the items that are true.
- Equivalent to:
-
- \begin{verbatim}
- def ifilter(predicate, iterable):
- if predicate is None:
- predicate = bool
- for x in iterable:
- if predicate(x):
- yield x
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{ifilterfalse}{predicate, iterable}
- Make an iterator that filters elements from iterable returning only
- those for which the predicate is \code{False}.
- If \var{predicate} is \code{None}, return the items that are false.
- Equivalent to:
-
- \begin{verbatim}
- def ifilterfalse(predicate, iterable):
- if predicate is None:
- predicate = bool
- for x in iterable:
- if not predicate(x):
- yield x
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{imap}{function, *iterables}
- Make an iterator that computes the function using arguments from
- each of the iterables. If \var{function} is set to \code{None}, then
- \function{imap()} returns the arguments as a tuple. Like
- \function{map()} but stops when the shortest iterable is exhausted
- instead of filling in \code{None} for shorter iterables. The reason
- for the difference is that infinite iterator arguments are typically
- an error for \function{map()} (because the output is fully evaluated)
- but represent a common and useful way of supplying arguments to
- \function{imap()}.
- Equivalent to:
-
- \begin{verbatim}
- def imap(function, *iterables):
- iterables = map(iter, iterables)
- while True:
- args = [next(i) for i in iterables]
- if function is None:
- yield tuple(args)
- else:
- yield function(*args)
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{islice}{iterable, \optional{start,} stop \optional{, step}}
- Make an iterator that returns selected elements from the iterable.
- If \var{start} is non-zero, then elements from the iterable are skipped
- until start is reached. Afterward, elements are returned consecutively
- unless \var{step} is set higher than one which results in items being
- skipped. If \var{stop} is \code{None}, then iteration continues until
- the iterator is exhausted, if at all; otherwise, it stops at the specified
- position. Unlike regular slicing,
- \function{islice()} does not support negative values for \var{start},
- \var{stop}, or \var{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:
-
- \begin{verbatim}
- def islice(iterable, *args):
- s = slice(*args)
- it = iter(range(s.start or 0, s.stop or sys.maxint, s.step or 1))
- nexti = next(it)
- for i, element in enumerate(iterable):
- if i == nexti:
- yield element
- nexti = next(it)
- \end{verbatim}
-
- If \var{start} is \code{None}, then iteration starts at zero.
- If \var{step} is \code{None}, then the step defaults to one.
- \versionchanged[accept \code{None} values for default \var{start} and
- \var{step}]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{izip}{*iterables}
- Make an iterator that aggregates elements from each of the iterables.
- Like \function{zip()} except that it returns an iterator instead of
- a list. Used for lock-step iteration over several iterables at a
- time. Equivalent to:
-
- \begin{verbatim}
- def izip(*iterables):
- iterables = map(iter, iterables)
- while iterables:
- result = [next(it) for it in iterables]
- yield tuple(result)
- \end{verbatim}
-
- \versionchanged[When no iterables are specified, returns a zero length
- iterator instead of raising a \exception{TypeError}
- exception]{2.4}
-
- 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 \samp{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 \samp{izip(*[chain(s, [None]*(n-1))]*n)}.
-
- Note, when \function{izip()} is used with unequal length inputs, subsequent
- iteration over the longer iterables cannot reliably be continued after
- \function{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 \code{next(it)}). In general,
- \function{izip()} should only be used with unequal length inputs when you
- don't care about trailing, unmatched values from the longer iterables.
-\end{funcdesc}
-
-\begin{funcdesc}{izip_longest}{*iterables\optional{, 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 \var{fillvalue}. Iteration continues until the longest iterable
- is exhausted. Equivalent to:
-
- \begin{verbatim}
- 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
- \end{verbatim}
-
- If one of the iterables is potentially infinite, then the
- \function{izip_longest()} function should be wrapped with something
- that limits the number of calls (for example \function{islice()} or
- \function{take()}).
- \versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{repeat}{object\optional{, times}}
- Make an iterator that returns \var{object} over and over again.
- Runs indefinitely unless the \var{times} argument is specified.
- Used as argument to \function{imap()} for invariant parameters
- to the called function. Also used with \function{izip()} to create
- an invariant part of a tuple record. Equivalent to:
-
- \begin{verbatim}
- def repeat(object, times=None):
- if times is None:
- while True:
- yield object
- else:
- for i in range(times):
- yield object
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{starmap}{function, iterable}
- Make an iterator that computes the function using arguments tuples
- obtained from the iterable. Used instead of \function{imap()} when
- argument parameters are already grouped in tuples from a single iterable
- (the data has been ``pre-zipped''). The difference between
- \function{imap()} and \function{starmap()} parallels the distinction
- between \code{function(a,b)} and \code{function(*c)}.
- Equivalent to:
-
- \begin{verbatim}
- def starmap(function, iterable):
- iterable = iter(iterable)
- while True:
- yield function(*next(iterable))
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{takewhile}{predicate, iterable}
- Make an iterator that returns elements from the iterable as long as
- the predicate is true. Equivalent to:
-
- \begin{verbatim}
- def takewhile(predicate, iterable):
- for x in iterable:
- if predicate(x):
- yield x
- else:
- break
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{tee}{iterable\optional{, n=2}}
- Return \var{n} independent iterators from a single iterable.
- The case where \code{n==2} is equivalent to:
-
- \begin{verbatim}
- 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__))
- \end{verbatim}
-
- Note, once \function{tee()} has made a split, the original \var{iterable}
- should not be used anywhere else; otherwise, the \var{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 \function{list()} instead of
- \function{tee()}.
- \versionadded{2.4}
-\end{funcdesc}
-
-
-\subsection{Examples \label{itertools-example}}
-
-The following examples show common uses for each tool and
-demonstrate ways they can be combined.
-
-\begin{verbatim}
-
->>> 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, range(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 t:t[0]-t[1]):
-... print map(operator.itemgetter(1), g)
-...
-[1]
-[4, 5, 6]
-[10]
-[15, 16, 17, 18]
-[22]
-[25, 26, 27, 28]
-
-\end{verbatim}
-
-
-\subsection{Recipes \label{itertools-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.
-
-
-\begin{verbatim}
-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)
- next(b, None)
- 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)
-
-
-\end{verbatim}
diff --git a/Doc/lib/libkeyword.tex b/Doc/lib/libkeyword.tex
deleted file mode 100644
index 0c07cec..0000000
--- a/Doc/lib/libkeyword.tex
+++ /dev/null
@@ -1,20 +0,0 @@
-\section{\module{keyword} ---
- Testing for Python keywords}
-
-\declaremodule{standard}{keyword}
-\modulesynopsis{Test whether a string is a keyword in Python.}
-
-
-This module allows a Python program to determine if a string is a
-keyword.
-
-\begin{funcdesc}{iskeyword}{s}
-Return true if \var{s} is a Python keyword.
-\end{funcdesc}
-
-\begin{datadesc}{kwlist}
-Sequence containing all the keywords defined for the interpreter. If
-any keywords are defined to only be active when particular
-\module{__future__} statements are in effect, these will be included
-as well.
-\end{datadesc}
diff --git a/Doc/lib/liblinecache.tex b/Doc/lib/liblinecache.tex
deleted file mode 100644
index 72c7743..0000000
--- a/Doc/lib/liblinecache.tex
+++ /dev/null
@@ -1,50 +0,0 @@
-\section{\module{linecache} ---
- Random access to text lines}
-
-\declaremodule{standard}{linecache}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{This module provides random access to individual lines
- from text files.}
-
-
-The \module{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
-\refmodule{traceback} module to retrieve source lines for inclusion in
-the formatted traceback.
-
-The \module{linecache} module defines the following functions:
-
-\begin{funcdesc}{getline}{filename, lineno\optional{, module_globals}}
-Get line \var{lineno} from file named \var{filename}. This function
-will never throw an exception --- it will return \code{''} on errors
-(the terminating newline character will be included for lines that are
-found).
-
-If a file named \var{filename} is not found, the function will look
-for it in the module\indexiii{module}{search}{path} search path,
-\code{sys.path}, after first checking for a \pep{302} \code{__loader__}
-in \var{module_globals}, in case the module was imported from a zipfile
-or other non-filesystem import source.
-
-\versionadded[The \var{module_globals} parameter was added]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{clearcache}{}
-Clear the cache. Use this function if you no longer need lines from
-files previously read using \function{getline()}.
-\end{funcdesc}
-
-\begin{funcdesc}{checkcache}{\optional{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
-\var{filename} is omitted, it will check all the entries in the cache.
-\end{funcdesc}
-
-Example:
-
-\begin{verbatim}
->>> import linecache
->>> linecache.getline('/etc/passwd', 4)
-'sys:x:3:3:sys:/dev:/bin/sh\n'
-\end{verbatim}
diff --git a/Doc/lib/liblocale.tex b/Doc/lib/liblocale.tex
deleted file mode 100644
index 319d893..0000000
--- a/Doc/lib/liblocale.tex
+++ /dev/null
@@ -1,527 +0,0 @@
-\section{\module{locale} ---
- Internationalization services}
-
-\declaremodule{standard}{locale}
-\modulesynopsis{Internationalization services.}
-\moduleauthor{Martin von L\"owis}{martin@v.loewis.de}
-\sectionauthor{Martin von L\"owis}{martin@v.loewis.de}
-
-
-The \module{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.
-
-The \module{locale} module is implemented on top of the
-\module{_locale}\refbimodindex{_locale} module, which in turn uses an
-ANSI C locale implementation if available.
-
-The \module{locale} module defines the following exception and
-functions:
-
-
-\begin{excdesc}{Error}
- Exception raised when \function{setlocale()} fails.
-\end{excdesc}
-
-\begin{funcdesc}{setlocale}{category\optional{, locale}}
- If \var{locale} is specified, it may be a string, a tuple of the
- form \code{(\var{language code}, \var{encoding})}, or \code{None}.
- If it is a tuple, it is converted to a string using the locale
- aliasing engine. If \var{locale} is given and not \code{None},
- \function{setlocale()} modifies the locale setting for the
- \var{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 \exception{Error} is raised. If
- successful, the new locale setting is returned.
-
- If \var{locale} is omitted or \code{None}, the current setting for
- \var{category} is returned.
-
- \function{setlocale()} is not thread safe on most systems.
- Applications typically start with a call of
-
-\begin{verbatim}
-import locale
-locale.setlocale(locale.LC_ALL, '')
-\end{verbatim}
-
- 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[Added support for tuple values of the \var{locale}
- parameter]{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{localeconv}{}
- Returns the database of the local conventions as a dictionary.
- This dictionary has the following strings as keys:
-
- \begin{tableiii}{l|l|p{3in}}{constant}{Category}{Key}{Meaning}
- \lineiii{LC_NUMERIC}{\code{'decimal_point'}}
- {Decimal point character.}
- \lineiii{}{\code{'grouping'}}
- {Sequence of numbers specifying which relative positions
- the \code{'thousands_sep'} is expected. If the sequence is
- terminated with \constant{CHAR_MAX}, no further grouping
- is performed. If the sequence terminates with a \code{0},
- the last group size is repeatedly used.}
- \lineiii{}{\code{'thousands_sep'}}
- {Character used between groups.}\hline
- \lineiii{LC_MONETARY}{\code{'int_curr_symbol'}}
- {International currency symbol.}
- \lineiii{}{\code{'currency_symbol'}}
- {Local currency symbol.}
- \lineiii{}{\code{'p_cs_precedes/n_cs_precedes'}}
- {Whether the currency symbol precedes the value (for positive resp.
- negative values).}
- \lineiii{}{\code{'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).}
- \lineiii{}{\code{'mon_decimal_point'}}
- {Decimal point used for monetary values.}
- \lineiii{}{\code{'frac_digits'}}
- {Number of fractional digits used in local formatting
- of monetary values.}
- \lineiii{}{\code{'int_frac_digits'}}
- {Number of fractional digits used in international
- formatting of monetary values.}
- \lineiii{}{\code{'mon_thousands_sep'}}
- {Group separator used for monetary values.}
- \lineiii{}{\code{'mon_grouping'}}
- {Equivalent to \code{'grouping'}, used for monetary
- values.}
- \lineiii{}{\code{'positive_sign'}}
- {Symbol used to annotate a positive monetary value.}
- \lineiii{}{\code{'negative_sign'}}
- {Symbol used to annotate a negative monetary value.}
- \lineiii{}{\code{'p_sign_posn/n_sign_posn'}}
- {The position of the sign (for positive resp. negative values), see below.}
- \end{tableiii}
-
- All numeric values can be set to \constant{CHAR_MAX} to indicate that
- there is no value specified in this locale.
-
- The possible values for \code{'p_sign_posn'} and
- \code{'n_sign_posn'} are given below.
-
- \begin{tableii}{c|l}{code}{Value}{Explanation}
- \lineii{0}{Currency and value are surrounded by parentheses.}
- \lineii{1}{The sign should precede the value and currency symbol.}
- \lineii{2}{The sign should follow the value and currency symbol.}
- \lineii{3}{The sign should immediately precede the value.}
- \lineii{4}{The sign should immediately follow the value.}
- \lineii{\constant{CHAR_MAX}}{Nothing is specified in this locale.}
- \end{tableii}
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-
-\end{funcdesc}
-
-\begin{funcdesc}{getdefaultlocale}{\optional{envvars}}
- Tries to determine the default locale settings and returns
- them as a tuple of the form \code{(\var{language code},
- \var{encoding})}.
-
- According to \POSIX, a program which has not called
- \code{setlocale(LC_ALL, '')} runs using the portable \code{'C'}
- locale. Calling \code{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. \var{envvars} defaults to the search path used in GNU gettext;
- it must always contain the variable name \samp{LANG}. The GNU
- gettext search path contains \code{'LANGUAGE'}, \code{'LC_ALL'},
- \code{'LC_CTYPE'}, and \code{'LANG'}, in that order.
-
- Except for the code \code{'C'}, the language code corresponds to
- \rfc{1766}. \var{language code} and \var{encoding} may be
- \code{None} if their values cannot be determined.
- \versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{getlocale}{\optional{category}}
- Returns the current setting for the given locale category as
- sequence containing \var{language code}, \var{encoding}.
- \var{category} may be one of the \constant{LC_*} values except
- \constant{LC_ALL}. It defaults to \constant{LC_CTYPE}.
-
- Except for the code \code{'C'}, the language code corresponds to
- \rfc{1766}. \var{language code} and \var{encoding} may be
- \code{None} if their values cannot be determined.
- \versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{getpreferredencoding}{\optional{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 \function{setlocale}
- to obtain the user preferences, so this function is not thread-safe.
- If invoking setlocale is not necessary or desired, \var{do_setlocale}
- should be set to \code{False}.
-
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{normalize}{localename}
- Returns a normalized locale code for the given locale name. The
- returned locale code is formatted for use with
- \function{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
- \function{setlocale()}.
- \versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{resetlocale}{\optional{category}}
- Sets the locale for \var{category} to the default setting.
-
- The default setting is determined by calling
- \function{getdefaultlocale()}. \var{category} defaults to
- \constant{LC_ALL}.
- \versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{strcoll}{string1, string2}
- Compares two strings according to the current
- \constant{LC_COLLATE} setting. As any other compare function,
- returns a negative, or a positive value, or \code{0}, depending on
- whether \var{string1} collates before or after \var{string2} or is
- equal to it.
-\end{funcdesc}
-
-\begin{funcdesc}{strxfrm}{string}
- Transforms a string to one that can be used for the built-in
- function \function{cmp()}\bifuncindex{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.
-\end{funcdesc}
-
-\begin{funcdesc}{format}{format, val\optional{, grouping\optional{, monetary}}}
- Formats a number \var{val} according to the current
- \constant{LC_NUMERIC} setting. The format follows the conventions
- of the \code{\%} operator. For floating point values, the decimal
- point is modified if appropriate. If \var{grouping} is true, also
- takes the grouping into account.
-
- If \var{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 \function{format_string()}.
-
- \versionchanged[Added the \var{monetary} parameter]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{format_string}{format, val\optional{, grouping}}
- Processes formatting specifiers as in \code{format \% val},
- but takes the current locale settings into account.
-
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{currency}{val\optional{, symbol\optional{, grouping\optional{, international}}}}
- Formats a number \var{val} according to the current \constant{LC_MONETARY}
- settings.
-
- The returned string includes the currency symbol if \var{symbol} is true,
- which is the default.
- If \var{grouping} is true (which is not the default), grouping is done with
- the value.
- If \var{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 \function{setlocale()} first.
-
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{str}{float}
- Formats a floating point number using the same format as the
- built-in function \code{str(\var{float})}, but takes the decimal
- point into account.
-\end{funcdesc}
-
-\begin{funcdesc}{atof}{string}
- Converts a string to a floating point number, following the
- \constant{LC_NUMERIC} settings.
-\end{funcdesc}
-
-\begin{funcdesc}{atoi}{string}
- Converts a string to an integer, following the
- \constant{LC_NUMERIC} conventions.
-\end{funcdesc}
-
-\begin{datadesc}{LC_CTYPE}
-\refstmodindex{string}
- Locale category for the character type functions. Depending on the
- settings of this category, the functions of module
- \refmodule{string} dealing with case change their behaviour.
-\end{datadesc}
-
-\begin{datadesc}{LC_COLLATE}
- Locale category for sorting strings. The functions
- \function{strcoll()} and \function{strxfrm()} of the
- \module{locale} module are affected.
-\end{datadesc}
-
-\begin{datadesc}{LC_TIME}
- Locale category for the formatting of time. The function
- \function{time.strftime()} follows these conventions.
-\end{datadesc}
-
-\begin{datadesc}{LC_MONETARY}
- Locale category for formatting of monetary values. The available
- options are available from the \function{localeconv()} function.
-\end{datadesc}
-
-\begin{datadesc}{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
- \function{os.strerror()} might be affected by this category.
-\end{datadesc}
-
-\begin{datadesc}{LC_NUMERIC}
- Locale category for formatting numbers. The functions
- \function{format()}, \function{atoi()}, \function{atof()} and
- \function{str()} of the \module{locale} module are affected by that
- category. All other numeric formatting operations are not
- affected.
-\end{datadesc}
-
-\begin{datadesc}{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.
-\end{datadesc}
-
-\begin{datadesc}{CHAR_MAX}
- This is a symbolic constant used for different values returned by
- \function{localeconv()}.
-\end{datadesc}
-
-The \function{nl_langinfo} function accepts one of the following keys.
-Most descriptions are taken from the corresponding description in the
-GNU C library.
-
-\begin{datadesc}{CODESET}
-Return a string with the name of the character encoding used in the
-selected locale.
-\end{datadesc}
-
-\begin{datadesc}{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.
-\end{datadesc}
-
-\begin{datadesc}{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.
-\end{datadesc}
-
-\begin{datadesc}{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.
-\end{datadesc}
-
-\begin{datadesc}{T_FMT_AMPM}
-The return value can be used as a format string for `strftime' to
-represent time in the am/pm format.
-\end{datadesc}
-
-\begin{datadesc}{DAY_1 ... DAY_7}
-Return name of the n-th day of the week. \warning{This
-follows the US convention of \constant{DAY_1} being Sunday, not the
-international convention (ISO 8601) that Monday is the first day of
-the week.}
-\end{datadesc}
-
-\begin{datadesc}{ABDAY_1 ... ABDAY_7}
-Return abbreviated name of the n-th day of the week.
-\end{datadesc}
-
-\begin{datadesc}{MON_1 ... MON_12}
-Return name of the n-th month.
-\end{datadesc}
-
-\begin{datadesc}{ABMON_1 ... ABMON_12}
-Return abbreviated name of the n-th month.
-\end{datadesc}
-
-\begin{datadesc}{RADIXCHAR}
-Return radix character (decimal dot, decimal comma, etc.)
-\end{datadesc}
-
-\begin{datadesc}{THOUSEP}
-Return separator character for thousands (groups of three digits).
-\end{datadesc}
-
-\begin{datadesc}{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
-\cfunction{regex()} function from the C library, which might differ
-from the syntax used in \refmodule{re}.}
-\end{datadesc}
-
-\begin{datadesc}{NOEXPR}
-Return a regular expression that can be used with the regex(3)
-function to recognize a negative response to a yes/no question.
-\end{datadesc}
-
-\begin{datadesc}{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.
-\end{datadesc}
-
-\begin{datadesc}{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 \code{E} modifier in their format strings causes the
-\function{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.
-\end{datadesc}
-
-\begin{datadesc}{ERA_YEAR}
-The return value gives the year in the relevant era of the locale.
-\end{datadesc}
-
-\begin{datadesc}{ERA_D_T_FMT}
-This return value can be used as a format string for
-\function{strftime} to represent dates and times in a locale-specific
-era-based way.
-\end{datadesc}
-
-\begin{datadesc}{ERA_D_FMT}
-This return value can be used as a format string for
-\function{strftime} to represent time in a locale-specific era-based
-way.
-\end{datadesc}
-
-\begin{datadesc}{ALT_DIGITS}
-The return value is a representation of up to 100 values used to
-represent the values 0 to 99.
-\end{datadesc}
-
-Example:
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
-
-
-\subsection{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 \samp{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 \code{setlocale(LC_ALL, '')}.
-
-It is generally a bad idea to call \function{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 \function{string.lower()}, or certain formats used with
-\function{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-\samp{C} locale settings.
-
-The case conversion functions in the
-\refmodule{string}\refstmodindex{string} module are affected by the
-locale settings. When a call to the \function{setlocale()} function
-changes the \constant{LC_CTYPE} settings, the variables
-\code{string.lowercase}, \code{string.uppercase} and
-\code{string.letters} are recalculated. Note that code that uses
-these variable through `\keyword{from} ... \keyword{import} ...',
-e.g.\ \code{from string import letters}, is not affected by subsequent
-\function{setlocale()} calls.
-
-The only way to perform numeric operations according to the locale
-is to use the special functions defined by this module:
-\function{atof()}, \function{atoi()}, \function{format()},
-\function{str()}.
-
-\subsection{For extension writers and programs that embed Python
- \label{embedding-locale}}
-
-Extension modules should never call \function{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 \samp{C}).
-
-When Python code uses the \module{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
-\module{_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 \module{_locale} module is not accessible as a shared library.
-
-
-\subsection{Access to message catalogs \label{locale-gettext}}
-
-The locale module exposes the C library's gettext interface on systems
-that provide this interface. It consists of the functions
-\function{gettext()}, \function{dgettext()}, \function{dcgettext()},
-\function{textdomain()}, \function{bindtextdomain()}, and
-\function{bind_textdomain_codeset()}. These are similar to the same
-functions in the \refmodule{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 \refmodule{gettext} instead. A known
-exception to this rule are applications that link use additional C
-libraries which internally invoke \cfunction{gettext()} or
-\function{dcgettext()}. For these applications, it may be necessary to
-bind the text domain, so that the libraries can properly locate their
-message catalogs.
diff --git a/Doc/lib/liblogging.tex b/Doc/lib/liblogging.tex
deleted file mode 100644
index c5c3e4e..0000000
--- a/Doc/lib/liblogging.tex
+++ /dev/null
@@ -1,1768 +0,0 @@
-\section{\module{logging} ---
- Logging facility for Python}
-
-\declaremodule{standard}{logging}
-
-% These apply to all modules, and may be given more than once:
-
-\moduleauthor{Vinay Sajip}{vinay_sajip@red-dove.com}
-\sectionauthor{Vinay Sajip}{vinay_sajip@red-dove.com}
-
-\modulesynopsis{Logging module for Python based on \pep{282}.}
-
-\indexii{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 \constant{DEBUG}, \constant{INFO},
-\constant{WARNING}, \constant{ERROR} and \constant{CRITICAL}. As a
-convenience, you indicate the importance of a logged message by calling
-an appropriate method of \class{Logger}. The methods are
-\method{debug()}, \method{info()}, \method{warning()}, \method{error()} and
-\method{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, \method{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.
-
-\begin{tableii}{l|l}{code}{Level}{Numeric value}
- \lineii{CRITICAL}{50}
- \lineii{ERROR}{40}
- \lineii{WARNING}{30}
- \lineii{INFO}{20}
- \lineii{DEBUG}{10}
- \lineii{NOTSET}{0}
-\end{tableii}
-
-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 \method{addHandler()} method of \class{Logger}).
-In addition to any handlers directly associated with a logger,
-\emph{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 \method{emit()} method
-is used to send the message to its destination. Most user-defined subclasses
-of \class{Handler} will need to override this \method{emit()}.
-
-In addition to the base \class{Handler} class, many useful subclasses
-are provided:
-
-\begin{enumerate}
-
-\item \class{StreamHandler} instances send error messages to
-streams (file-like objects).
-
-\item \class{FileHandler} instances send error messages to disk
-files.
-
-\item \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}.
-
-\item \class{RotatingFileHandler} instances send error messages to disk
-files, with support for maximum log file sizes and log file rotation.
-
-\item \class{TimedRotatingFileHandler} instances send error messages to
-disk files rotating the log file at certain timed intervals.
-
-\item \class{SocketHandler} instances send error messages to
-TCP/IP sockets.
-
-\item \class{DatagramHandler} instances send error messages to UDP
-sockets.
-
-\item \class{SMTPHandler} instances send error messages to a
-designated email address.
-
-\item \class{SysLogHandler} instances send error messages to a
-\UNIX{} syslog daemon, possibly on a remote machine.
-
-\item \class{NTEventLogHandler} instances send error messages to a
-Windows NT/2000/XP event log.
-
-\item \class{MemoryHandler} instances send error messages to a
-buffer in memory, which is flushed whenever specific criteria are
-met.
-
-\item \class{HTTPHandler} instances send error messages to an
-HTTP server using either \samp{GET} or \samp{POST} semantics.
-
-\end{enumerate}
-
-The \class{StreamHandler} and \class{FileHandler} classes are defined
-in the core logging package. The other handlers are defined in a sub-
-module, \module{logging.handlers}. (There is also another sub-module,
-\module{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 \method{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.
-
-\begin{funcdesc}{getLogger}{\optional{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 \var{"a"}, \var{"a.b"}
-or \var{"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.
-\end{funcdesc}
-
-\begin{funcdesc}{getLoggerClass}{}
-Return either the standard \class{Logger} class, or the last class passed to
-\function{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:
-
-\begin{verbatim}
- class MyLogger(logging.getLoggerClass()):
- # ... override behaviour here
-\end{verbatim}
-
-\end{funcdesc}
-
-\begin{funcdesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{DEBUG} on the root logger.
-The \var{msg} is the message format string, and the \var{args} are the
-arguments which are merged into \var{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 \var{kwargs} which are inspected:
-\var{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 \function{sys.exc_info()}) is provided, it is used;
-otherwise, \function{sys.exc_info()} is called to get the exception
-information.
-
-The other optional keyword argument is \var{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:
-
-\begin{verbatim}
- 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)
-\end{verbatim}
-
-would print something like
-\begin{verbatim}
-2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
-\end{verbatim}
-
-The keys in the dictionary passed in \var{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 \var{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[\var{extra} was added]{2.5}
-
-\end{funcdesc}
-
-\begin{funcdesc}{info}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{INFO} on the root logger.
-The arguments are interpreted as for \function{debug()}.
-\end{funcdesc}
-
-\begin{funcdesc}{warning}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{WARNING} on the root logger.
-The arguments are interpreted as for \function{debug()}.
-\end{funcdesc}
-
-\begin{funcdesc}{error}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{ERROR} on the root logger.
-The arguments are interpreted as for \function{debug()}.
-\end{funcdesc}
-
-\begin{funcdesc}{critical}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{CRITICAL} on the root logger.
-The arguments are interpreted as for \function{debug()}.
-\end{funcdesc}
-
-\begin{funcdesc}{exception}{msg\optional{, *args}}
-Logs a message with level \constant{ERROR} on the root logger.
-The arguments are interpreted as for \function{debug()}. Exception info
-is added to the logging message. This function should only be called
-from an exception handler.
-\end{funcdesc}
-
-\begin{funcdesc}{log}{level, msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \var{level} on the root logger.
-The other arguments are interpreted as for \function{debug()}.
-\end{funcdesc}
-
-\begin{funcdesc}{disable}{lvl}
-Provides an overriding level \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{addLevelName}{lvl, levelName}
-Associates level \var{lvl} with text \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{getLevelName}{lvl}
-Returns the textual representation of logging level \var{lvl}. If the
-level is one of the predefined levels \constant{CRITICAL},
-\constant{ERROR}, \constant{WARNING}, \constant{INFO} or \constant{DEBUG}
-then you get the corresponding string. If you have associated levels
-with names using \function{addLevelName()} then the name you have associated
-with \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{makeLogRecord}{attrdict}
-Creates and returns a new \class{LogRecord} instance whose attributes are
-defined by \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{basicConfig}{\optional{**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 \function{debug()}, \function{info()},
-\function{warning()}, \function{error()} and \function{critical()} will call
-\function{basicConfig()} automatically if no handlers are defined for the
-root logger.
-
-\versionchanged[Formerly, \function{basicConfig} did not take any keyword
-arguments]{2.4}
-
-The following keyword arguments are supported.
-
-\begin{tableii}{l|l}{code}{Format}{Description}
-\lineii{filename}{Specifies that a FileHandler be created, using the
-specified filename, rather than a StreamHandler.}
-\lineii{filemode}{Specifies the mode to open the file, if filename is
-specified (if filemode is unspecified, it defaults to 'a').}
-\lineii{format}{Use the specified format string for the handler.}
-\lineii{datefmt}{Use the specified date/time format.}
-\lineii{level}{Set the root logger level to the specified level.}
-\lineii{stream}{Use the specified stream to initialize the StreamHandler.
-Note that this argument is incompatible with 'filename' - if both
-are present, 'stream' is ignored.}
-\end{tableii}
-
-\end{funcdesc}
-
-\begin{funcdesc}{shutdown}{}
-Informs the logging system to perform an orderly shutdown by flushing and
-closing all handlers.
-\end{funcdesc}
-
-\begin{funcdesc}{setLoggerClass}{klass}
-Tells the logging system to use the class \var{klass} when instantiating a
-logger. The class should define \method{__init__()} such that only a name
-argument is required, and the \method{__init__()} should call
-\method{Logger.__init__()}. This function is typically called before any
-loggers are instantiated by applications which need to use custom logger
-behavior.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seepep{282}{A Logging System}
- {The proposal which described this feature for inclusion in
- the Python standard library.}
- \seelink{http://www.red-dove.com/python_logging.html}
- {Original Python \module{logging} package}
- {This is the original source for the \module{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 \module{logging} package in the standard
- library.}
-\end{seealso}
-
-
-\subsection{Logger Objects}
-
-Loggers have the following attributes and methods. Note that Loggers are
-never instantiated directly, but always through the module-level function
-\function{logging.getLogger(name)}.
-
-\begin{memberdesc}[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.
-\end{memberdesc}
-
-\begin{methoddesc}[Logger]{setLevel}{lvl}
-Sets the threshold for this logger to \var{lvl}. Logging messages
-which are less severe than \var{lvl} will be ignored. When a logger is
-created, the level is set to \constant{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 \constant{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.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{isEnabledFor}{lvl}
-Indicates if a message of severity \var{lvl} would be processed by
-this logger. This method checks first the module-level level set by
-\function{logging.disable(lvl)} and then the logger's effective level as
-determined by \method{getEffectiveLevel()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{getEffectiveLevel}{}
-Indicates the effective level for this logger. If a value other than
-\constant{NOTSET} has been set using \method{setLevel()}, it is returned.
-Otherwise, the hierarchy is traversed towards the root until a value
-other than \constant{NOTSET} is found, and that value is returned.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{debug}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{DEBUG} on this logger.
-The \var{msg} is the message format string, and the \var{args} are the
-arguments which are merged into \var{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 \var{kwargs} which are inspected:
-\var{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 \function{sys.exc_info()}) is provided, it is used;
-otherwise, \function{sys.exc_info()} is called to get the exception
-information.
-
-The other optional keyword argument is \var{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:
-
-\begin{verbatim}
- 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)
-\end{verbatim}
-
-would print something like
-\begin{verbatim}
-2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
-\end{verbatim}
-
-The keys in the dictionary passed in \var{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 \var{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[\var{extra} was added]{2.5}
-
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{info}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{INFO} on this logger.
-The arguments are interpreted as for \method{debug()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{warning}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{WARNING} on this logger.
-The arguments are interpreted as for \method{debug()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{error}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{ERROR} on this logger.
-The arguments are interpreted as for \method{debug()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{critical}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{CRITICAL} on this logger.
-The arguments are interpreted as for \method{debug()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{log}{lvl, msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with integer level \var{lvl} on this logger.
-The other arguments are interpreted as for \method{debug()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{exception}{msg\optional{, *args}}
-Logs a message with level \constant{ERROR} on this logger.
-The arguments are interpreted as for \method{debug()}. Exception info
-is added to the logging message. This method should only be called
-from an exception handler.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{addFilter}{filt}
-Adds the specified filter \var{filt} to this logger.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{removeFilter}{filt}
-Removes the specified filter \var{filt} from this logger.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{filter}{record}
-Applies this logger's filters to the record and returns a true value if
-the record is to be processed.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{addHandler}{hdlr}
-Adds the specified handler \var{hdlr} to this logger.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{removeHandler}{hdlr}
-Removes the specified handler \var{hdlr} from this logger.
-\end{methoddesc}
-
-\begin{methoddesc}[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[The function name was added. In earlier versions, the
-filename and line number were returned as a 2-element tuple.]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{handle}{record}
-Handles a record by passing it to all handlers associated with this logger
-and its ancestors (until a false value of \var{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
-\method{filter()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{makeRecord}{name, lvl, fn, lno, msg, args, exc_info
- \optional{, func, extra}}
-This is a factory method which can be overridden in subclasses to create
-specialized \class{LogRecord} instances.
-\versionchanged[\var{func} and \var{extra} were added]{2.5}
-\end{methoddesc}
-
-\subsection{Basic example \label{minimal-example}}
-
-\versionchanged[formerly \function{basicConfig} did not take any keyword
-arguments]{2.4}
-
-The \module{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:
-
-\begin{verbatim}
-import logging
-
-logging.debug('A debug message')
-logging.info('Some information')
-logging.warning('A shot across the bows')
-\end{verbatim}
-
-If you run the above script, you'll see this:
-\begin{verbatim}
-WARNING:root:A shot across the bows
-\end{verbatim}
-
-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 - \code{sys.stderr}. The severity level,
-the message format and destination can be easily changed, as shown in
-the example below:
-
-\begin{verbatim}
-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')
-\end{verbatim}
-
-The \method{basicConfig()} method is used to change the configuration
-defaults, which results in output (written to \code{/tmp/myapp.log})
-which should look something like the following:
-
-\begin{verbatim}
-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
-\end{verbatim}
-
-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{typesseq-strings}. The format string takes the following
-common specifiers. For a complete list of specifiers, consult the
-\class{Formatter} documentation.
-
-\begin{tableii}{l|l}{code}{Format}{Description}
-\lineii{\%(name)s} {Name of the logger (logging channel).}
-\lineii{\%(levelname)s}{Text logging level for the message
- (\code{'DEBUG'}, \code{'INFO'},
- \code{'WARNING'}, \code{'ERROR'},
- \code{'CRITICAL'}).}
-\lineii{\%(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).}
-\lineii{\%(message)s} {The logged message.}
-\end{tableii}
-
-To change the date/time format, you can pass an additional keyword parameter,
-\var{datefmt}, as in the following:
-
-\begin{verbatim}
-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')
-\end{verbatim}
-
-which would result in output like
-
-\begin{verbatim}
-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
-\end{verbatim}
-
-The date format string follows the requirements of \function{strftime()} -
-see the documentation for the \refmodule{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 \function{basicConfig()} using the \var{stream} keyword argument. Note
-that if both \var{stream} and \var{filename} keyword arguments are passed,
-the \var{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:
-
-\begin{verbatim}
-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')
-\end{verbatim}
-
-which would result in
-
-\begin{verbatim}
-Wed, 21 Jul 2004 15:35:16 ERROR Pack my box with 5 dozen liquor jugs
-\end{verbatim}
-
-\subsection{Logging to multiple destinations \label{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:
-
-\begin{verbatim}
-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.')
-\end{verbatim}
-
-When you run this, on the console you will see
-
-\begin{verbatim}
-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.
-\end{verbatim}
-
-and in the file you will see something like
-
-\begin{verbatim}
-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.
-\end{verbatim}
-
-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.
-
-\subsection{Sending and receiving logging events across a network
-\label{network-logging}}
-
-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:
-
-\begin{verbatim}
-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.')
-\end{verbatim}
-
-At the receiving end, you can set up a receiver using the
-\module{SocketServer} module. Here is a basic working example:
-
-\begin{verbatim}
-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()
-\end{verbatim}
-
-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:
-
-\begin{verbatim}
-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.
-\end{verbatim}
-
-\subsection{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 \method{__init__()}
-method in subclasses needs to call \method{Handler.__init__()}.
-
-\begin{methoddesc}[Handler]{__init__}{level=\constant{NOTSET}}
-Initializes the \class{Handler} instance by setting its level, setting
-the list of filters to the empty list and creating a lock (using
-\method{createLock()}) for serializing access to an I/O mechanism.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{createLock}{}
-Initializes a thread lock which can be used to serialize access to
-underlying I/O functionality which may not be threadsafe.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{acquire}{}
-Acquires the thread lock created with \method{createLock()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{release}{}
-Releases the thread lock acquired with \method{acquire()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{setLevel}{lvl}
-Sets the threshold for this handler to \var{lvl}. Logging messages which are
-less severe than \var{lvl} will be ignored. When a handler is created, the
-level is set to \constant{NOTSET} (which causes all messages to be processed).
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{setFormatter}{form}
-Sets the \class{Formatter} for this handler to \var{form}.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{addFilter}{filt}
-Adds the specified filter \var{filt} to this handler.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{removeFilter}{filt}
-Removes the specified filter \var{filt} from this handler.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{filter}{record}
-Applies this handler's filters to the record and returns a true value if
-the record is to be processed.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{flush}{}
-Ensure all logging output has been flushed. This version does
-nothing and is intended to be implemented by subclasses.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{close}{}
-Tidy up any resources used by the handler. This version does
-nothing and is intended to be implemented by subclasses.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{handleError}{record}
-This method should be called from handlers when an exception is
-encountered during an \method{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.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{format}{record}
-Do formatting for a record - if a formatter is set, use it.
-Otherwise, use the default formatter for the module.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \exception{NotImplementedError}.
-\end{methoddesc}
-
-\subsubsection{StreamHandler}
-
-The \class{StreamHandler} class, located in the core \module{logging}
-package, sends logging output to streams such as \var{sys.stdout},
-\var{sys.stderr} or any file-like object (or, more precisely, any
-object which supports \method{write()} and \method{flush()} methods).
-
-\begin{classdesc}{StreamHandler}{\optional{strm}}
-Returns a new instance of the \class{StreamHandler} class. If \var{strm} is
-specified, the instance will use it for logging output; otherwise,
-\var{sys.stderr} will be used.
-\end{classdesc}
-
-\begin{methoddesc}{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
-\function{traceback.print_exception()} and appended to the stream.
-\end{methoddesc}
-
-\begin{methoddesc}{flush}{}
-Flushes the stream by calling its \method{flush()} method. Note that
-the \method{close()} method is inherited from \class{Handler} and
-so does nothing, so an explicit \method{flush()} call may be needed
-at times.
-\end{methoddesc}
-
-\subsubsection{FileHandler}
-
-The \class{FileHandler} class, located in the core \module{logging}
-package, sends logging output to a disk file. It inherits the output
-functionality from \class{StreamHandler}.
-
-\begin{classdesc}{FileHandler}{filename\optional{, mode\optional{, encoding}}}
-Returns a new instance of the \class{FileHandler} class. The specified
-file is opened and used as the stream for logging. If \var{mode} is
-not specified, \constant{'a'} is used. If \var{encoding} is not \var{None},
-it is used to open the file with that encoding. By default, the file grows
-indefinitely.
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
-Closes the file.
-\end{methoddesc}
-
-\begin{methoddesc}{emit}{record}
-Outputs the record to the file.
-\end{methoddesc}
-
-\subsubsection{WatchedFileHandler}
-
-\versionadded{2.6}
-The \class{WatchedFileHandler} class, located in the \module{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 \var{newsyslog}
-and \var{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,
-\var{ST_INO} is not supported under Windows; \function{stat()} always returns
-zero for this value.
-
-\begin{classdesc}{WatchedFileHandler}{filename\optional{,mode\optional{,
- encoding}}}
-Returns a new instance of the \class{WatchedFileHandler} class. The specified
-file is opened and used as the stream for logging. If \var{mode} is
-not specified, \constant{'a'} is used. If \var{encoding} is not \var{None},
-it is used to open the file with that encoding. By default, the file grows
-indefinitely.
-\end{classdesc}
-
-\begin{methoddesc}{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.
-\end{methoddesc}
-
-\subsubsection{RotatingFileHandler}
-
-The \class{RotatingFileHandler} class, located in the \module{logging.handlers}
-module, supports rotation of disk log files.
-
-\begin{classdesc}{RotatingFileHandler}{filename\optional{, mode\optional{,
- maxBytes\optional{, backupCount}}}}
-Returns a new instance of the \class{RotatingFileHandler} class. The
-specified file is opened and used as the stream for logging. If
-\var{mode} is not specified, \code{'a'} is used. By default, the
-file grows indefinitely.
-
-You can use the \var{maxBytes} and
-\var{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 \var{maxBytes} in length; if
-\var{maxBytes} is zero, rollover never occurs. If \var{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 \var{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.
-\end{classdesc}
-
-\begin{methoddesc}{doRollover}{}
-Does a rollover, as described above.
-\end{methoddesc}
-
-\begin{methoddesc}{emit}{record}
-Outputs the record to the file, catering for rollover as described previously.
-\end{methoddesc}
-
-\subsubsection{TimedRotatingFileHandler}
-
-The \class{TimedRotatingFileHandler} class, located in the
-\module{logging.handlers} module, supports rotation of disk log files
-at certain timed intervals.
-
-\begin{classdesc}{TimedRotatingFileHandler}{filename
- \optional{,when
- \optional{,interval
- \optional{,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 \var{when} and \var{interval}.
-
-You can use the \var{when} to specify the type of \var{interval}. The
-list of possible values is, note that they are not case sensitive:
-
-\begin{tableii}{l|l}{}{Value}{Type of interval}
- \lineii{S}{Seconds}
- \lineii{M}{Minutes}
- \lineii{H}{Hours}
- \lineii{D}{Days}
- \lineii{W}{Week day (0=Monday)}
- \lineii{midnight}{Roll over at midnight}
-\end{tableii}
-
-If \var{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 \code{\%Y-\%m-\%d_\%H-\%M-\%S} or a leading
-portion thereof, depending on the rollover interval. At most \var{backupCount}
-files will be kept, and if more would be created when rollover occurs, the
-oldest one is deleted.
-\end{classdesc}
-
-\begin{methoddesc}{doRollover}{}
-Does a rollover, as described above.
-\end{methoddesc}
-
-\begin{methoddesc}{emit}{record}
-Outputs the record to the file, catering for rollover as described
-above.
-\end{methoddesc}
-
-\subsubsection{SocketHandler}
-
-The \class{SocketHandler} class, located in the
-\module{logging.handlers} module, sends logging output to a network
-socket. The base class uses a TCP socket.
-
-\begin{classdesc}{SocketHandler}{host, port}
-Returns a new instance of the \class{SocketHandler} class intended to
-communicate with a remote machine whose address is given by \var{host}
-and \var{port}.
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
-Closes the socket.
-\end{methoddesc}
-
-\begin{methoddesc}{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
-\function{makeLogRecord()} function.
-\end{methoddesc}
-
-\begin{methoddesc}{handleError}{}
-Handles an error which has occurred during \method{emit()}. The
-most likely cause is a lost connection. Closes the socket so that
-we can retry on the next event.
-\end{methoddesc}
-
-\begin{methoddesc}{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 (\constant{socket.SOCK_STREAM}).
-\end{methoddesc}
-
-\begin{methoddesc}{makePickle}{record}
-Pickles the record's attribute dictionary in binary format with a length
-prefix, and returns it ready for transmission across the socket.
-\end{methoddesc}
-
-\begin{methoddesc}{send}{packet}
-Send a pickled string \var{packet} to the socket. This function allows
-for partial sends which can happen when the network is busy.
-\end{methoddesc}
-
-\subsubsection{DatagramHandler}
-
-The \class{DatagramHandler} class, located in the
-\module{logging.handlers} module, inherits from \class{SocketHandler}
-to support sending logging messages over UDP sockets.
-
-\begin{classdesc}{DatagramHandler}{host, port}
-Returns a new instance of the \class{DatagramHandler} class intended to
-communicate with a remote machine whose address is given by \var{host}
-and \var{port}.
-\end{classdesc}
-
-\begin{methoddesc}{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
-\function{makeLogRecord()} function.
-\end{methoddesc}
-
-\begin{methoddesc}{makeSocket}{}
-The factory method of \class{SocketHandler} is here overridden to create
-a UDP socket (\constant{socket.SOCK_DGRAM}).
-\end{methoddesc}
-
-\begin{methoddesc}{send}{s}
-Send a pickled string to a socket.
-\end{methoddesc}
-
-\subsubsection{SysLogHandler}
-
-The \class{SysLogHandler} class, located in the
-\module{logging.handlers} module, supports sending logging messages to
-a remote or local \UNIX{} syslog.
-
-\begin{classdesc}{SysLogHandler}{\optional{address\optional{, facility}}}
-Returns a new instance of the \class{SysLogHandler} class intended to
-communicate with a remote \UNIX{} machine whose address is given by
-\var{address} in the form of a \code{(\var{host}, \var{port})}
-tuple. If \var{address} is not specified, \code{('localhost', 514)} is
-used. The address is used to open a UDP socket. An alternative to providing
-a \code{(\var{host}, \var{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 \var{facility} is not specified,
-\constant{LOG_USER} is used.
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
-Closes the socket to the remote host.
-\end{methoddesc}
-
-\begin{methoddesc}{emit}{record}
-The record is formatted, and then sent to the syslog server. If
-exception information is present, it is \emph{not} sent to the server.
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-\end{methoddesc}
-
-\subsubsection{NTEventLogHandler}
-
-The \class{NTEventLogHandler} class, located in the
-\module{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.
-
-\begin{classdesc}{NTEventLogHandler}{appname\optional{,
- dllname\optional{, logtype}}}
-Returns a new instance of the \class{NTEventLogHandler} class. The
-\var{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 \var{dllname} should give the fully qualified pathname of a .dll or .exe
-which contains message definitions to hold in the log (if not specified,
-\code{'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 \var{logtype} is one of
-\code{'Application'}, \code{'System'} or \code{'Security'}, and
-defaults to \code{'Application'}.
-\end{classdesc}
-
-\begin{methoddesc}{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).
-\end{methoddesc}
-
-\begin{methoddesc}{emit}{record}
-Determines the message ID, event category and event type, and then logs the
-message in the NT event log.
-\end{methoddesc}
-
-\begin{methoddesc}{getEventCategory}{record}
-Returns the event category for the record. Override this if you
-want to specify your own categories. This version returns 0.
-\end{methoddesc}
-
-\begin{methoddesc}{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 \method{__init__()}
-to a dictionary which contains mappings for \constant{DEBUG},
-\constant{INFO}, \constant{WARNING}, \constant{ERROR} and
-\constant{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 \var{typemap} attribute.
-\end{methoddesc}
-
-\begin{methoddesc}{getMessageID}{record}
-Returns the message ID for the record. If you are using your
-own messages, you could do this by having the \var{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}.
-\end{methoddesc}
-
-\subsubsection{SMTPHandler}
-
-The \class{SMTPHandler} class, located in the
-\module{logging.handlers} module, supports sending logging messages to
-an email address via SMTP.
-
-\begin{classdesc}{SMTPHandler}{mailhost, fromaddr, toaddrs, subject\optional{,
- 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 \var{toaddrs} should be a list of strings. To specify a
-non-standard SMTP port, use the (host, port) tuple format for the
-\var{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 \var{credentials} argument.
-\versionchanged[\var{credentials} was added]{2.6}
-\end{classdesc}
-
-\begin{methoddesc}{emit}{record}
-Formats the record and sends it to the specified addressees.
-\end{methoddesc}
-
-\begin{methoddesc}{getSubject}{record}
-If you want to specify a subject line which is record-dependent,
-override this method.
-\end{methoddesc}
-
-\subsubsection{MemoryHandler}
-
-The \class{MemoryHandler} class, located in the
-\module{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 \method{shouldFlush()} to see if the buffer
-should be flushed. If it should, then \method{flush()} is expected to
-do the needful.
-
-\begin{classdesc}{BufferingHandler}{capacity}
-Initializes the handler with a buffer of the specified capacity.
-\end{classdesc}
-
-\begin{methoddesc}{emit}{record}
-Appends the record to the buffer. If \method{shouldFlush()} returns true,
-calls \method{flush()} to process the buffer.
-\end{methoddesc}
-
-\begin{methoddesc}{flush}{}
-You can override this to implement custom flushing behavior. This version
-just zaps the buffer to empty.
-\end{methoddesc}
-
-\begin{methoddesc}{shouldFlush}{record}
-Returns true if the buffer is up to capacity. This method can be
-overridden to implement custom flushing strategies.
-\end{methoddesc}
-
-\begin{classdesc}{MemoryHandler}{capacity\optional{, flushLevel
-\optional{, target}}}
-Returns a new instance of the \class{MemoryHandler} class. The
-instance is initialized with a buffer size of \var{capacity}. If
-\var{flushLevel} is not specified, \constant{ERROR} is used. If no
-\var{target} is specified, the target will need to be set using
-\method{setTarget()} before this handler does anything useful.
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
-Calls \method{flush()}, sets the target to \constant{None} and
-clears the buffer.
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-\end{methoddesc}
-
-\begin{methoddesc}{setTarget}{target}
-Sets the target handler for this handler.
-\end{methoddesc}
-
-\begin{methoddesc}{shouldFlush}{record}
-Checks for buffer full or a record at the \var{flushLevel} or higher.
-\end{methoddesc}
-
-\subsubsection{HTTPHandler}
-
-The \class{HTTPHandler} class, located in the
-\module{logging.handlers} module, supports sending logging messages to
-a Web server, using either \samp{GET} or \samp{POST} semantics.
-
-\begin{classdesc}{HTTPHandler}{host, url\optional{, method}}
-Returns a new instance of the \class{HTTPHandler} class. The
-instance is initialized with a host address, url and HTTP method.
-The \var{host} can be of the form \code{host:port}, should you need to
-use a specific port number. If no \var{method} is specified, \samp{GET}
-is used.
-\end{classdesc}
-
-\begin{methoddesc}{emit}{record}
-Sends the record to the Web server as an URL-encoded dictionary.
-\end{methoddesc}
-
-\subsection{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 \code{'\%(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 \var{message}
-attribute. This format string contains standard python \%-style
-mapping keys. See section \ref{typesseq-strings}, ``String Formatting
-Operations,'' for more information on string formatting.
-
-Currently, the useful mapping keys in a \class{LogRecord} are:
-
-\begin{tableii}{l|l}{code}{Format}{Description}
-\lineii{\%(name)s} {Name of the logger (logging channel).}
-\lineii{\%(levelno)s} {Numeric logging level for the message
- (\constant{DEBUG}, \constant{INFO},
- \constant{WARNING}, \constant{ERROR},
- \constant{CRITICAL}).}
-\lineii{\%(levelname)s}{Text logging level for the message
- (\code{'DEBUG'}, \code{'INFO'},
- \code{'WARNING'}, \code{'ERROR'},
- \code{'CRITICAL'}).}
-\lineii{\%(pathname)s} {Full pathname of the source file where the logging
- call was issued (if available).}
-\lineii{\%(filename)s} {Filename portion of pathname.}
-\lineii{\%(module)s} {Module (name portion of filename).}
-\lineii{\%(funcName)s} {Name of function containing the logging call.}
-\lineii{\%(lineno)d} {Source line number where the logging call was issued
- (if available).}
-\lineii{\%(created)f} {Time when the \class{LogRecord} was created (as
- returned by \function{time.time()}).}
-\lineii{\%(relativeCreated)d} {Time in milliseconds when the LogRecord was
- created, relative to the time the logging module was
- loaded.}
-\lineii{\%(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).}
-\lineii{\%(msecs)d} {Millisecond portion of the time when the
- \class{LogRecord} was created.}
-\lineii{\%(thread)d} {Thread ID (if available).}
-\lineii{\%(threadName)s} {Thread name (if available).}
-\lineii{\%(process)d} {Process ID (if available).}
-\lineii{\%(message)s} {The logged message, computed as \code{msg \% args}.}
-\end{tableii}
-
-\versionchanged[\var{funcName} was added]{2.5}
-
-\begin{classdesc}{Formatter}{\optional{fmt\optional{, 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 \var{fmt} is specified, \code{'\%(message)s'} is used. If no \var{datefmt}
-is specified, the ISO8601 date format is used.
-\end{classdesc}
-
-\begin{methoddesc}{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 \var{message} attribute of the record is computed
-using \var{msg} \% \var{args}. If the formatting string contains
-\code{'(asctime)'}, \method{formatTime()} is called to format the
-event time. If there is exception information, it is formatted using
-\method{formatException()} and appended to the message.
-\end{methoddesc}
-
-\begin{methoddesc}{formatTime}{record\optional{, datefmt}}
-This method should be called from \method{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 \var{datefmt} (a string) is specified,
-it is used with \function{time.strftime()} to format the creation time of the
-record. Otherwise, the ISO8601 format is used. The resulting
-string is returned.
-\end{methoddesc}
-
-\begin{methoddesc}{formatException}{exc_info}
-Formats the specified exception information (a standard exception tuple
-as returned by \function{sys.exc_info()}) as a string. This default
-implementation just uses \function{traceback.print_exception()}.
-The resulting string is returned.
-\end{methoddesc}
-
-\subsection{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.
-
-\begin{classdesc}{Filter}{\optional{name}}
-Returns an instance of the \class{Filter} class. If \var{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.
-\end{classdesc}
-
-\begin{methoddesc}{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.
-\end{methoddesc}
-
-\subsection{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.
-
-\begin{classdesc}{LogRecord}{name, lvl, pathname, lineno, msg, args,
- exc_info \optional{, func}}
-Returns an instance of \class{LogRecord} initialized with interesting
-information. The \var{name} is the logger name; \var{lvl} is the
-numeric level; \var{pathname} is the absolute pathname of the source
-file in which the logging call was made; \var{lineno} is the line
-number in that file where the logging call is found; \var{msg} is the
-user-supplied message (a format string); \var{args} is the tuple
-which, together with \var{msg}, makes up the user message; and
-\var{exc_info} is the exception tuple obtained by calling
-\function{sys.exc_info() }(or \constant{None}, if no exception information
-is available). The \var{func} is the name of the function from which the
-logging call was made. If not specified, it defaults to \code{None}.
-\versionchanged[\var{func} was added]{2.5}
-\end{classdesc}
-
-\begin{methoddesc}{getMessage}{}
-Returns the message for this \class{LogRecord} instance after merging any
-user-supplied arguments with the message.
-\end{methoddesc}
-
-\subsection{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.
-
-\subsection{Configuration}
-
-
-\subsubsection{Configuration functions%
- \label{logging-config-api}}
-
-The following functions configure the logging module. They are located in the
-\module{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 \module{logging} itself) and defining handlers
-which are declared either in \module{logging} or
-\module{logging.handlers}.
-
-\begin{funcdesc}{fileConfig}{fname\optional{, defaults}}
-Reads the logging configuration from a ConfigParser-format file named
-\var{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 \var{defaults} argument.
-\end{funcdesc}
-
-\begin{funcdesc}{listen}{\optional{port}}
-Starts up a socket server on the specified port, and listens for new
-configurations. If no port is specified, the module's default
-\constant{DEFAULT_LOGGING_CONFIG_PORT} is used. Logging configurations
-will be sent as a file suitable for processing by \function{fileConfig()}.
-Returns a \class{Thread} instance on which you can call \method{start()}
-to start the server, and which you can \method{join()} when appropriate.
-To stop the server, call \function{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.\code{pack('>L', n)}.
-\end{funcdesc}
-
-\begin{funcdesc}{stopListening}{}
-Stops the listening server which was created with a call to
-\function{listen()}. This is typically called before calling \method{join()}
-on the return value from \function{listen()}.
-\end{funcdesc}
-
-\subsubsection{Configuration file format%
- \label{logging-config-fileformat}}
-
-The configuration file format understood by \function{fileConfig()} is
-based on ConfigParser functionality. The file must contain sections
-called \code{[loggers]}, \code{[handlers]} and \code{[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
-\code{log01} in the \code{[loggers]} section, the relevant
-configuration details are held in a section
-\code{[logger_log01]}. Similarly, a handler called \code{hand01} in
-the \code{[handlers]} section will have its configuration held in a
-section called \code{[handler_hand01]}, while a formatter called
-\code{form01} in the \code{[formatters]} section will have its
-configuration specified in a section called
-\code{[formatter_form01]}. The root logger configuration must be
-specified in a section called \code{[logger_root]}.
-
-Examples of these sections in the file are given below.
-
-\begin{verbatim}
-[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
-\end{verbatim}
-
-The root logger must specify a level and a list of handlers. An
-example of a root logger section is given below.
-
-\begin{verbatim}
-[logger_root]
-level=NOTSET
-handlers=hand01
-\end{verbatim}
-
-The \code{level} entry can be one of \code{DEBUG, INFO, WARNING,
-ERROR, CRITICAL} or \code{NOTSET}. For the root logger only,
-\code{NOTSET} means that all messages will be logged. Level values are
-\function{eval()}uated in the context of the \code{logging} package's
-namespace.
-
-The \code{handlers} entry is a comma-separated list of handler names,
-which must appear in the \code{[handlers]} section. These names must
-appear in the \code{[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.
-
-\begin{verbatim}
-[logger_parser]
-level=DEBUG
-handlers=hand01
-propagate=1
-qualname=compiler.parser
-\end{verbatim}
-
-The \code{level} and \code{handlers} entries are interpreted as for
-the root logger, except that if a non-root logger's level is specified
-as \code{NOTSET}, the system consults loggers higher up the hierarchy
-to determine the effective level of the logger. The \code{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 \strong{not} propagated to handlers up the hierarchy. The
-\code{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.
-
-\begin{verbatim}
-[handler_hand01]
-class=StreamHandler
-level=NOTSET
-formatter=form01
-args=(sys.stdout,)
-\end{verbatim}
-
-The \code{class} entry indicates the handler's class (as determined by
-\function{eval()} in the \code{logging} package's namespace). The
-\code{level} is interpreted as for loggers, and \code{NOTSET} is taken
-to mean "log everything".
-
-The \code{formatter} entry indicates the key name of the formatter for
-this handler. If blank, a default formatter
-(\code{logging._defaultFormatter}) is used. If a name is specified, it
-must appear in the \code{[formatters]} section and have a
-corresponding section in the configuration file.
-
-The \code{args} entry, when \function{eval()}uated in the context of
-the \code{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.
-
-\begin{verbatim}
-[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')
-\end{verbatim}
-
-Sections which specify formatter configuration are typified by the following.
-
-\begin{verbatim}
-[formatter_form01]
-format=F1 %(asctime)s %(levelname)s %(message)s
-datefmt=
-class=logging.Formatter
-\end{verbatim}
-
-The \code{format} entry is the overall format string, and the
-\code{datefmt} entry is the \function{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 "%Y-%m-%d %H:%M:%S".
-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 \code{2003-01-23 00:29:50,411}.
-
-The \code{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.
diff --git a/Doc/lib/libmailbox.tex b/Doc/lib/libmailbox.tex
deleted file mode 100644
index c3e7ffd..0000000
--- a/Doc/lib/libmailbox.tex
+++ /dev/null
@@ -1,1443 +0,0 @@
-\section{\module{mailbox} ---
- Manipulate mailboxes in various formats}
-
-\declaremodule{}{mailbox}
-\moduleauthor{Gregory K.~Johnson}{gkj@gregorykjohnson.com}
-\sectionauthor{Gregory K.~Johnson}{gkj@gregorykjohnson.com}
-\modulesynopsis{Manipulate mailboxes in various formats}
-
-
-This module defines two classes, \class{Mailbox} and \class{Message}, for
-accessing and manipulating on-disk mailboxes and the messages they contain.
-\class{Mailbox} offers a dictionary-like mapping from keys to messages.
-\class{Message} extends the \module{email.Message} module's \class{Message}
-class with format-specific state and behavior. Supported mailbox formats are
-Maildir, mbox, MH, Babyl, and MMDF.
-
-\begin{seealso}
- \seemodule{email}{Represent and manipulate messages.}
-\end{seealso}
-
-\subsection{\class{Mailbox} objects}
-\label{mailbox-objects}
-
-\begin{classdesc*}{Mailbox}
-A mailbox, which may be inspected and modified.
-\end{classdesc*}
-
-The \class{Mailbox} class defines an interface and
-is not intended to be instantiated. Instead, format-specific
-subclasses should inherit from \class{Mailbox} and your code
-should instantiate a particular subclass.
-
-The \class{Mailbox} interface is dictionary-like, with small keys
-corresponding to messages. Keys are issued by the \class{Mailbox}
-instance with which they will be used and are only meaningful to that
-\class{Mailbox} instance. A key continues to identify a message even
-if the corresponding message is modified, such as by replacing it with
-another message.
-
-Messages may be added to a \class{Mailbox} instance using the set-like
-method \method{add()} and removed using a \code{del} statement or the
-set-like methods \method{remove()} and \method{discard()}.
-
-\class{Mailbox} interface semantics differ from dictionary semantics in some
-noteworthy ways. Each time a message is requested, a new
-representation (typically a \class{Message} instance) is generated
-based upon the current state of the mailbox. Similarly, when a message
-is added to a \class{Mailbox} instance, the provided message
-representation's contents are copied. In neither case is a reference
-to the message representation kept by the \class{Mailbox} instance.
-
-The default \class{Mailbox} iterator iterates over message representations, not
-keys as the default dictionary iterator does. Moreover, modification of a
-mailbox during iteration is safe and well-defined. Messages added to the
-mailbox after an iterator is created will not be seen by the iterator. Messages
-removed from the mailbox before the iterator yields them will be silently
-skipped, though using a key from an iterator may result in a
-\exception{KeyError} exception if the corresponding message is subsequently
-removed.
-
-\begin{notice}[warning]
-Be very cautious when modifying mailboxes that might be
-simultaneously changed by some other process. The safest mailbox
-format to use for such tasks is Maildir; try to avoid using
-single-file formats such as mbox for concurrent writing. If you're
-modifying a mailbox, you
-\emph{must} lock it by calling the \method{lock()} and
-\method{unlock()} methods \emph{before} reading any messages in the file
-or making any changes by adding or deleting a message. Failing to
-lock the mailbox runs the risk of losing messages or corrupting the entire
-mailbox.
-\end{notice}
-
-\class{Mailbox} instances have the following methods:
-
-\begin{methoddesc}{add}{message}
-Add \var{message} to the mailbox and return the key that has been assigned to
-it.
-
-Parameter \var{message} may be a \class{Message} instance, an
-\class{email.Message.Message} instance, a string, or a file-like object (which
-should be open in text mode). If \var{message} is an instance of the
-appropriate format-specific \class{Message} subclass (e.g., if it's an
-\class{mboxMessage} instance and this is an \class{mbox} instance), its
-format-specific information is used. Otherwise, reasonable defaults for
-format-specific information are used.
-\end{methoddesc}
-
-\begin{methoddesc}{remove}{key}
-\methodline{__delitem__}{key}
-\methodline{discard}{key}
-Delete the message corresponding to \var{key} from the mailbox.
-
-If no such message exists, a \exception{KeyError} exception is raised if the
-method was called as \method{remove()} or \method{__delitem__()} but no
-exception is raised if the method was called as \method{discard()}. The
-behavior of \method{discard()} may be preferred if the underlying mailbox
-format supports concurrent modification by other processes.
-\end{methoddesc}
-
-\begin{methoddesc}{__setitem__}{key, message}
-Replace the message corresponding to \var{key} with \var{message}. Raise a
-\exception{KeyError} exception if no message already corresponds to \var{key}.
-
-As with \method{add()}, parameter \var{message} may be a \class{Message}
-instance, an \class{email.Message.Message} instance, a string, or a file-like
-object (which should be open in text mode). If \var{message} is an instance of
-the appropriate format-specific \class{Message} subclass (e.g., if it's an
-\class{mboxMessage} instance and this is an \class{mbox} instance), its
-format-specific information is used. Otherwise, the format-specific information
-of the message that currently corresponds to \var{key} is left unchanged.
-\end{methoddesc}
-
-\begin{methoddesc}{iterkeys}{}
-\methodline{keys}{}
-Return an iterator over all keys if called as \method{iterkeys()} or return a
-list of keys if called as \method{keys()}.
-\end{methoddesc}
-
-\begin{methoddesc}{itervalues}{}
-\methodline{__iter__}{}
-\methodline{values}{}
-Return an iterator over representations of all messages if called as
-\method{itervalues()} or \method{__iter__()} or return a list of such
-representations if called as \method{values()}. The messages are represented as
-instances of the appropriate format-specific \class{Message} subclass unless a
-custom message factory was specified when the \class{Mailbox} instance was
-initialized. \note{The behavior of \method{__iter__()} is unlike that of
-dictionaries, which iterate over keys.}
-\end{methoddesc}
-
-\begin{methoddesc}{iteritems}{}
-\methodline{items}{}
-Return an iterator over (\var{key}, \var{message}) pairs, where \var{key} is a
-key and \var{message} is a message representation, if called as
-\method{iteritems()} or return a list of such pairs if called as
-\method{items()}. The messages are represented as instances of the appropriate
-format-specific \class{Message} subclass unless a custom message factory was
-specified when the \class{Mailbox} instance was initialized.
-\end{methoddesc}
-
-\begin{methoddesc}{get}{key\optional{, default=None}}
-\methodline{__getitem__}{key}
-Return a representation of the message corresponding to \var{key}. If no such
-message exists, \var{default} is returned if the method was called as
-\method{get()} and a \exception{KeyError} exception is raised if the method was
-called as \method{__getitem__()}. The message is represented as an instance of
-the appropriate format-specific \class{Message} subclass unless a custom
-message factory was specified when the \class{Mailbox} instance was
-initialized.
-\end{methoddesc}
-
-\begin{methoddesc}{get_message}{key}
-Return a representation of the message corresponding to \var{key} as an
-instance of the appropriate format-specific \class{Message} subclass, or raise
-a \exception{KeyError} exception if no such message exists.
-\end{methoddesc}
-
-\begin{methoddesc}{get_string}{key}
-Return a string representation of the message corresponding to \var{key}, or
-raise a \exception{KeyError} exception if no such message exists.
-\end{methoddesc}
-
-\begin{methoddesc}{get_file}{key}
-Return a file-like representation of the message corresponding to \var{key},
-or raise a \exception{KeyError} exception if no such message exists. The
-file-like object behaves as if open in binary mode. This file should be closed
-once it is no longer needed.
-
-\note{Unlike other representations of messages, file-like representations are
-not necessarily independent of the \class{Mailbox} instance that created them
-or of the underlying mailbox. More specific documentation is provided by each
-subclass.}
-\end{methoddesc}
-
-\begin{methoddesc}{has_key}{key}
-\methodline{__contains__}{key}
-Return \code{True} if \var{key} corresponds to a message, \code{False}
-otherwise.
-\end{methoddesc}
-
-\begin{methoddesc}{__len__}{}
-Return a count of messages in the mailbox.
-\end{methoddesc}
-
-\begin{methoddesc}{clear}{}
-Delete all messages from the mailbox.
-\end{methoddesc}
-
-\begin{methoddesc}{pop}{key\optional{, default}}
-Return a representation of the message corresponding to \var{key} and delete
-the message. If no such message exists, return \var{default} if it was supplied
-or else raise a \exception{KeyError} exception. The message is represented as
-an instance of the appropriate format-specific \class{Message} subclass unless
-a custom message factory was specified when the \class{Mailbox} instance was
-initialized.
-\end{methoddesc}
-
-\begin{methoddesc}{popitem}{}
-Return an arbitrary (\var{key}, \var{message}) pair, where \var{key} is a key
-and \var{message} is a message representation, and delete the corresponding
-message. If the mailbox is empty, raise a \exception{KeyError} exception. The
-message is represented as an instance of the appropriate format-specific
-\class{Message} subclass unless a custom message factory was specified when the
-\class{Mailbox} instance was initialized.
-\end{methoddesc}
-
-\begin{methoddesc}{update}{arg}
-Parameter \var{arg} should be a \var{key}-to-\var{message} mapping or an
-iterable of (\var{key}, \var{message}) pairs. Updates the mailbox so that, for
-each given \var{key} and \var{message}, the message corresponding to \var{key}
-is set to \var{message} as if by using \method{__setitem__()}. As with
-\method{__setitem__()}, each \var{key} must already correspond to a message in
-the mailbox or else a \exception{KeyError} exception will be raised, so in
-general it is incorrect for \var{arg} to be a \class{Mailbox} instance.
-\note{Unlike with dictionaries, keyword arguments are not supported.}
-\end{methoddesc}
-
-\begin{methoddesc}{flush}{}
-Write any pending changes to the filesystem. For some \class{Mailbox}
-subclasses, changes are always written immediately and \method{flush()} does
-nothing, but you should still make a habit of calling this method.
-\end{methoddesc}
-
-\begin{methoddesc}{lock}{}
-Acquire an exclusive advisory lock on the mailbox so that other processes know
-not to modify it. An \exception{ExternalClashError} is raised if the lock is
-not available. The particular locking mechanisms used depend upon the mailbox
-format. You should \emph{always} lock the mailbox before making any
-modifications to its contents.
-\end{methoddesc}
-
-\begin{methoddesc}{unlock}{}
-Release the lock on the mailbox, if any.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
-Flush the mailbox, unlock it if necessary, and close any open files. For some
-\class{Mailbox} subclasses, this method does nothing.
-\end{methoddesc}
-
-
-\subsubsection{\class{Maildir}}
-\label{mailbox-maildir}
-
-\begin{classdesc}{Maildir}{dirname\optional{, factory=rfc822.Message\optional{,
-create=True}}}
-A subclass of \class{Mailbox} for mailboxes in Maildir format. Parameter
-\var{factory} is a callable object that accepts a file-like message
-representation (which behaves as if opened in binary mode) and returns a custom
-representation. If \var{factory} is \code{None}, \class{MaildirMessage} is used
-as the default message representation. If \var{create} is \code{True}, the
-mailbox is created if it does not exist.
-
-It is for historical reasons that \var{factory} defaults to
-\class{rfc822.Message} and that \var{dirname} is named as such rather than
-\var{path}. For a \class{Maildir} instance that behaves like instances of other
-\class{Mailbox} subclasses, set \var{factory} to \code{None}.
-\end{classdesc}
-
-Maildir is a directory-based mailbox format invented for the qmail mail
-transfer agent and now widely supported by other programs. Messages in a
-Maildir mailbox are stored in separate files within a common directory
-structure. This design allows Maildir mailboxes to be accessed and modified by
-multiple unrelated programs without data corruption, so file locking is
-unnecessary.
-
-Maildir mailboxes contain three subdirectories, namely: \file{tmp}, \file{new},
-and \file{cur}. Messages are created momentarily in the \file{tmp} subdirectory
-and then moved to the \file{new} subdirectory to finalize delivery. A mail user
-agent may subsequently move the message to the \file{cur} subdirectory and
-store information about the state of the message in a special "info" section
-appended to its file name.
-
-Folders of the style introduced by the Courier mail transfer agent are also
-supported. Any subdirectory of the main mailbox is considered a folder if
-\character{.} is the first character in its name. Folder names are represented
-by \class{Maildir} without the leading \character{.}. Each folder is itself a
-Maildir mailbox but should not contain other folders. Instead, a logical
-nesting is indicated using \character{.} to delimit levels, e.g.,
-"Archived.2005.07".
-
-\begin{notice}
-The Maildir specification requires the use of a colon (\character{:}) in
-certain message file names. However, some operating systems do not permit this
-character in file names, If you wish to use a Maildir-like format on such an
-operating system, you should specify another character to use instead. The
-exclamation point (\character{!}) is a popular choice. For example:
-\begin{verbatim}
-import mailbox
-mailbox.Maildir.colon = '!'
-\end{verbatim}
-The \member{colon} attribute may also be set on a per-instance basis.
-\end{notice}
-
-\class{Maildir} instances have all of the methods of \class{Mailbox} in
-addition to the following:
-
-\begin{methoddesc}{list_folders}{}
-Return a list of the names of all folders.
-\end{methoddesc}
-
-\begin{methoddesc}{get_folder}{folder}
-Return a \class{Maildir} instance representing the folder whose name is
-\var{folder}. A \exception{NoSuchMailboxError} exception is raised if the
-folder does not exist.
-\end{methoddesc}
-
-\begin{methoddesc}{add_folder}{folder}
-Create a folder whose name is \var{folder} and return a \class{Maildir}
-instance representing it.
-\end{methoddesc}
-
-\begin{methoddesc}{remove_folder}{folder}
-Delete the folder whose name is \var{folder}. If the folder contains any
-messages, a \exception{NotEmptyError} exception will be raised and the folder
-will not be deleted.
-\end{methoddesc}
-
-\begin{methoddesc}{clean}{}
-Delete temporary files from the mailbox that have not been accessed in the
-last 36 hours. The Maildir specification says that mail-reading programs
-should do this occasionally.
-\end{methoddesc}
-
-Some \class{Mailbox} methods implemented by \class{Maildir} deserve special
-remarks:
-
-\begin{methoddesc}{add}{message}
-\methodline[Maildir]{__setitem__}{key, message}
-\methodline[Maildir]{update}{arg}
-\warning{These methods generate unique file names based upon the current
-process ID. When using multiple threads, undetected name clashes may occur and
-cause corruption of the mailbox unless threads are coordinated to avoid using
-these methods to manipulate the same mailbox simultaneously.}
-\end{methoddesc}
-
-\begin{methoddesc}{flush}{}
-All changes to Maildir mailboxes are immediately applied, so this method does
-nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{lock}{}
-\methodline{unlock}{}
-Maildir mailboxes do not support (or require) locking, so these methods do
-nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
-\class{Maildir} instances do not keep any open files and the underlying
-mailboxes do not support locking, so this method does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{get_file}{key}
-Depending upon the host platform, it may not be possible to modify or remove
-the underlying message while the returned file remains open.
-\end{methoddesc}
-
-\begin{seealso}
- \seelink{http://www.qmail.org/man/man5/maildir.html}{maildir man page from
- qmail}{The original specification of the format.}
- \seelink{http://cr.yp.to/proto/maildir.html}{Using maildir format}{Notes
- on Maildir by its inventor. Includes an updated name-creation scheme and
- details on "info" semantics.}
- \seelink{http://www.courier-mta.org/?maildir.html}{maildir man page from
- Courier}{Another specification of the format. Describes a common extension
- for supporting folders.}
-\end{seealso}
-
-\subsubsection{\class{mbox}}
-\label{mailbox-mbox}
-
-\begin{classdesc}{mbox}{path\optional{, factory=None\optional{, create=True}}}
-A subclass of \class{Mailbox} for mailboxes in mbox format. Parameter
-\var{factory} is a callable object that accepts a file-like message
-representation (which behaves as if opened in binary mode) and returns a custom
-representation. If \var{factory} is \code{None}, \class{mboxMessage} is used as
-the default message representation. If \var{create} is \code{True}, the mailbox
-is created if it does not exist.
-\end{classdesc}
-
-The mbox format is the classic format for storing mail on \UNIX{} systems. All
-messages in an mbox mailbox are stored in a single file with the beginning of
-each message indicated by a line whose first five characters are "From~".
-
-Several variations of the mbox format exist to address perceived shortcomings
-in the original. In the interest of compatibility, \class{mbox} implements the
-original format, which is sometimes referred to as \dfn{mboxo}. This means that
-the \mailheader{Content-Length} header, if present, is ignored and that any
-occurrences of "From~" at the beginning of a line in a message body are
-transformed to ">From~" when storing the message, although occurences of
-">From~" are not transformed to "From~" when reading the message.
-
-Some \class{Mailbox} methods implemented by \class{mbox} deserve special
-remarks:
-
-\begin{methoddesc}{get_file}{key}
-Using the file after calling \method{flush()} or \method{close()} on the
-\class{mbox} instance may yield unpredictable results or raise an exception.
-\end{methoddesc}
-
-\begin{methoddesc}{lock}{}
-\methodline{unlock}{}
-Three locking mechanisms are used---dot locking and, if available, the
-\cfunction{flock()} and \cfunction{lockf()} system calls.
-\end{methoddesc}
-
-\begin{seealso}
- \seelink{http://www.qmail.org/man/man5/mbox.html}{mbox man page from
- qmail}{A specification of the format and its variations.}
- \seelink{http://www.tin.org/bin/man.cgi?section=5\&topic=mbox}{mbox man
- page from tin}{Another specification of the format, with details on
- locking.}
- \seelink{http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}
- {Configuring Netscape Mail on \UNIX{}: Why The Content-Length Format is
- Bad}{An argument for using the original mbox format rather than a
- variation.}
- \seelink{http://homepages.tesco.net./\tilde{}J.deBoynePollard/FGA/mail-mbox-formats.html}
- {"mbox" is a family of several mutually incompatible mailbox formats}{A
- history of mbox variations.}
-\end{seealso}
-
-\subsubsection{\class{MH}}
-\label{mailbox-mh}
-
-\begin{classdesc}{MH}{path\optional{, factory=None\optional{, create=True}}}
-A subclass of \class{Mailbox} for mailboxes in MH format. Parameter
-\var{factory} is a callable object that accepts a file-like message
-representation (which behaves as if opened in binary mode) and returns a custom
-representation. If \var{factory} is \code{None}, \class{MHMessage} is used as
-the default message representation. If \var{create} is \code{True}, the mailbox
-is created if it does not exist.
-\end{classdesc}
-
-MH is a directory-based mailbox format invented for the MH Message Handling
-System, a mail user agent. Each message in an MH mailbox resides in its own
-file. An MH mailbox may contain other MH mailboxes (called \dfn{folders}) in
-addition to messages. Folders may be nested indefinitely. MH mailboxes also
-support \dfn{sequences}, which are named lists used to logically group messages
-without moving them to sub-folders. Sequences are defined in a file called
-\file{.mh_sequences} in each folder.
-
-The \class{MH} class manipulates MH mailboxes, but it does not attempt to
-emulate all of \program{mh}'s behaviors. In particular, it does not modify and
-is not affected by the \file{context} or \file{.mh_profile} files that are used
-by \program{mh} to store its state and configuration.
-
-\class{MH} instances have all of the methods of \class{Mailbox} in addition to
-the following:
-
-\begin{methoddesc}{list_folders}{}
-Return a list of the names of all folders.
-\end{methoddesc}
-
-\begin{methoddesc}{get_folder}{folder}
-Return an \class{MH} instance representing the folder whose name is
-\var{folder}. A \exception{NoSuchMailboxError} exception is raised if the
-folder does not exist.
-\end{methoddesc}
-
-\begin{methoddesc}{add_folder}{folder}
-Create a folder whose name is \var{folder} and return an \class{MH} instance
-representing it.
-\end{methoddesc}
-
-\begin{methoddesc}{remove_folder}{folder}
-Delete the folder whose name is \var{folder}. If the folder contains any
-messages, a \exception{NotEmptyError} exception will be raised and the folder
-will not be deleted.
-\end{methoddesc}
-
-\begin{methoddesc}{get_sequences}{}
-Return a dictionary of sequence names mapped to key lists. If there are no
-sequences, the empty dictionary is returned.
-\end{methoddesc}
-
-\begin{methoddesc}{set_sequences}{sequences}
-Re-define the sequences that exist in the mailbox based upon \var{sequences}, a
-dictionary of names mapped to key lists, like returned by
-\method{get_sequences()}.
-\end{methoddesc}
-
-\begin{methoddesc}{pack}{}
-Rename messages in the mailbox as necessary to eliminate gaps in numbering.
-Entries in the sequences list are updated correspondingly. \note{Already-issued
-keys are invalidated by this operation and should not be subsequently used.}
-\end{methoddesc}
-
-Some \class{Mailbox} methods implemented by \class{MH} deserve special remarks:
-
-\begin{methoddesc}{remove}{key}
-\methodline{__delitem__}{key}
-\methodline{discard}{key}
-These methods immediately delete the message. The MH convention of marking a
-message for deletion by prepending a comma to its name is not used.
-\end{methoddesc}
-
-\begin{methoddesc}{lock}{}
-\methodline{unlock}{}
-Three locking mechanisms are used---dot locking and, if available, the
-\cfunction{flock()} and \cfunction{lockf()} system calls. For MH mailboxes,
-locking the mailbox means locking the \file{.mh_sequences} file and, only for
-the duration of any operations that affect them, locking individual message
-files.
-\end{methoddesc}
-
-\begin{methoddesc}{get_file}{key}
-Depending upon the host platform, it may not be possible to remove the
-underlying message while the returned file remains open.
-\end{methoddesc}
-
-\begin{methoddesc}{flush}{}
-All changes to MH mailboxes are immediately applied, so this method does
-nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
-\class{MH} instances do not keep any open files, so this method is equivelant
-to \method{unlock()}.
-\end{methoddesc}
-
-\begin{seealso}
-\seelink{http://www.nongnu.org/nmh/}{nmh - Message Handling System}{Home page
-of \program{nmh}, an updated version of the original \program{mh}.}
-\seelink{http://www.ics.uci.edu/\tilde{}mh/book/}{MH \& nmh: Email for Users \&
-Programmers}{A GPL-licensed book on \program{mh} and \program{nmh}, with some
-information on the mailbox format.}
-\end{seealso}
-
-\subsubsection{\class{Babyl}}
-\label{mailbox-babyl}
-
-\begin{classdesc}{Babyl}{path\optional{, factory=None\optional{, create=True}}}
-A subclass of \class{Mailbox} for mailboxes in Babyl format. Parameter
-\var{factory} is a callable object that accepts a file-like message
-representation (which behaves as if opened in binary mode) and returns a custom
-representation. If \var{factory} is \code{None}, \class{BabylMessage} is used
-as the default message representation. If \var{create} is \code{True}, the
-mailbox is created if it does not exist.
-\end{classdesc}
-
-Babyl is a single-file mailbox format used by the Rmail mail user agent
-included with Emacs. The beginning of a message is indicated by a line
-containing the two characters Control-Underscore
-(\character{\textbackslash037}) and Control-L (\character{\textbackslash014}).
-The end of a message is indicated by the start of the next message or, in the
-case of the last message, a line containing a Control-Underscore
-(\character{\textbackslash037}) character.
-
-Messages in a Babyl mailbox have two sets of headers, original headers and
-so-called visible headers. Visible headers are typically a subset of the
-original headers that have been reformatted or abridged to be more attractive.
-Each message in a Babyl mailbox also has an accompanying list of \dfn{labels},
-or short strings that record extra information about the message, and a list of
-all user-defined labels found in the mailbox is kept in the Babyl options
-section.
-
-\class{Babyl} instances have all of the methods of \class{Mailbox} in addition
-to the following:
-
-\begin{methoddesc}{get_labels}{}
-Return a list of the names of all user-defined labels used in the mailbox.
-\note{The actual messages are inspected to determine which labels exist in the
-mailbox rather than consulting the list of labels in the Babyl options section,
-but the Babyl section is updated whenever the mailbox is modified.}
-\end{methoddesc}
-
-Some \class{Mailbox} methods implemented by \class{Babyl} deserve special
-remarks:
-
-\begin{methoddesc}{get_file}{key}
-In Babyl mailboxes, the headers of a message are not stored contiguously with
-the body of the message. To generate a file-like representation, the headers
-and body are copied together into a \class{StringIO} instance (from the
-\module{StringIO} module), which has an API identical to that of a file. As a
-result, the file-like object is truly independent of the underlying mailbox but
-does not save memory compared to a string representation.
-\end{methoddesc}
-
-\begin{methoddesc}{lock}{}
-\methodline{unlock}{}
-Three locking mechanisms are used---dot locking and, if available, the
-\cfunction{flock()} and \cfunction{lockf()} system calls.
-\end{methoddesc}
-
-\begin{seealso}
-\seelink{http://quimby.gnus.org/notes/BABYL}{Format of Version 5 Babyl Files}{A
-specification of the Babyl format.}
-\seelink{http://www.gnu.org/software/emacs/manual/html_node/Rmail.html}{Reading
-Mail with Rmail}{The Rmail manual, with some information on Babyl semantics.}
-\end{seealso}
-
-\subsubsection{\class{MMDF}}
-\label{mailbox-mmdf}
-
-\begin{classdesc}{MMDF}{path\optional{, factory=None\optional{, create=True}}}
-A subclass of \class{Mailbox} for mailboxes in MMDF format. Parameter
-\var{factory} is a callable object that accepts a file-like message
-representation (which behaves as if opened in binary mode) and returns a custom
-representation. If \var{factory} is \code{None}, \class{MMDFMessage} is used as
-the default message representation. If \var{create} is \code{True}, the mailbox
-is created if it does not exist.
-\end{classdesc}
-
-MMDF is a single-file mailbox format invented for the Multichannel Memorandum
-Distribution Facility, a mail transfer agent. Each message is in the same form
-as an mbox message but is bracketed before and after by lines containing four
-Control-A (\character{\textbackslash001}) characters. As with the mbox format,
-the beginning of each message is indicated by a line whose first five
-characters are "From~", but additional occurrences of "From~" are not
-transformed to ">From~" when storing messages because the extra message
-separator lines prevent mistaking such occurrences for the starts of subsequent
-messages.
-
-Some \class{Mailbox} methods implemented by \class{MMDF} deserve special
-remarks:
-
-\begin{methoddesc}{get_file}{key}
-Using the file after calling \method{flush()} or \method{close()} on the
-\class{MMDF} instance may yield unpredictable results or raise an exception.
-\end{methoddesc}
-
-\begin{methoddesc}{lock}{}
-\methodline{unlock}{}
-Three locking mechanisms are used---dot locking and, if available, the
-\cfunction{flock()} and \cfunction{lockf()} system calls.
-\end{methoddesc}
-
-\begin{seealso}
-\seelink{http://www.tin.org/bin/man.cgi?section=5\&topic=mmdf}{mmdf man page
-from tin}{A specification of MMDF format from the documentation of tin, a
-newsreader.}
-\seelink{http://en.wikipedia.org/wiki/MMDF}{MMDF}{A Wikipedia article
-describing the Multichannel Memorandum Distribution Facility.}
-\end{seealso}
-
-\subsection{\class{Message} objects}
-\label{mailbox-message-objects}
-
-\begin{classdesc}{Message}{\optional{message}}
-A subclass of the \module{email.Message} module's \class{Message}. Subclasses
-of \class{mailbox.Message} add mailbox-format-specific state and behavior.
-
-If \var{message} is omitted, the new instance is created in a default, empty
-state. If \var{message} is an \class{email.Message.Message} instance, its
-contents are copied; furthermore, any format-specific information is converted
-insofar as possible if \var{message} is a \class{Message} instance. If
-\var{message} is a string or a file, it should contain an \rfc{2822}-compliant
-message, which is read and parsed.
-\end{classdesc}
-
-The format-specific state and behaviors offered by subclasses vary, but in
-general it is only the properties that are not specific to a particular mailbox
-that are supported (although presumably the properties are specific to a
-particular mailbox format). For example, file offsets for single-file mailbox
-formats and file names for directory-based mailbox formats are not retained,
-because they are only applicable to the original mailbox. But state such as
-whether a message has been read by the user or marked as important is retained,
-because it applies to the message itself.
-
-There is no requirement that \class{Message} instances be used to represent
-messages retrieved using \class{Mailbox} instances. In some situations, the
-time and memory required to generate \class{Message} representations might not
-not acceptable. For such situations, \class{Mailbox} instances also offer
-string and file-like representations, and a custom message factory may be
-specified when a \class{Mailbox} instance is initialized.
-
-\subsubsection{\class{MaildirMessage}}
-\label{mailbox-maildirmessage}
-
-\begin{classdesc}{MaildirMessage}{\optional{message}}
-A message with Maildir-specific behaviors. Parameter \var{message}
-has the same meaning as with the \class{Message} constructor.
-\end{classdesc}
-
-Typically, a mail user agent application moves all of the messages in the
-\file{new} subdirectory to the \file{cur} subdirectory after the first time the
-user opens and closes the mailbox, recording that the messages are old whether
-or not they've actually been read. Each message in \file{cur} has an "info"
-section added to its file name to store information about its state. (Some mail
-readers may also add an "info" section to messages in \file{new}.) The "info"
-section may take one of two forms: it may contain "2," followed by a list of
-standardized flags (e.g., "2,FR") or it may contain "1," followed by so-called
-experimental information. Standard flags for Maildir messages are as follows:
-
-\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation}
-\lineiii{D}{Draft}{Under composition}
-\lineiii{F}{Flagged}{Marked as important}
-\lineiii{P}{Passed}{Forwarded, resent, or bounced}
-\lineiii{R}{Replied}{Replied to}
-\lineiii{S}{Seen}{Read}
-\lineiii{T}{Trashed}{Marked for subsequent deletion}
-\end{tableiii}
-
-\class{MaildirMessage} instances offer the following methods:
-
-\begin{methoddesc}{get_subdir}{}
-Return either "new" (if the message should be stored in the \file{new}
-subdirectory) or "cur" (if the message should be stored in the \file{cur}
-subdirectory). \note{A message is typically moved from \file{new} to \file{cur}
-after its mailbox has been accessed, whether or not the message is has been
-read. A message \code{msg} has been read if \code{"S" not in msg.get_flags()}
-is \code{True}.}
-\end{methoddesc}
-
-\begin{methoddesc}{set_subdir}{subdir}
-Set the subdirectory the message should be stored in. Parameter \var{subdir}
-must be either "new" or "cur".
-\end{methoddesc}
-
-\begin{methoddesc}{get_flags}{}
-Return a string specifying the flags that are currently set. If the message
-complies with the standard Maildir format, the result is the concatenation in
-alphabetical order of zero or one occurrence of each of \character{D},
-\character{F}, \character{P}, \character{R}, \character{S}, and \character{T}.
-The empty string is returned if no flags are set or if "info" contains
-experimental semantics.
-\end{methoddesc}
-
-\begin{methoddesc}{set_flags}{flags}
-Set the flags specified by \var{flags} and unset all others.
-\end{methoddesc}
-
-\begin{methoddesc}{add_flag}{flag}
-Set the flag(s) specified by \var{flag} without changing other flags. To add
-more than one flag at a time, \var{flag} may be a string of more than one
-character. The current "info" is overwritten whether or not it contains
-experimental information rather than
-flags.
-\end{methoddesc}
-
-\begin{methoddesc}{remove_flag}{flag}
-Unset the flag(s) specified by \var{flag} without changing other flags. To
-remove more than one flag at a time, \var{flag} maybe a string of more than one
-character. If "info" contains experimental information rather than flags, the
-current "info" is not modified.
-\end{methoddesc}
-
-\begin{methoddesc}{get_date}{}
-Return the delivery date of the message as a floating-point number representing
-seconds since the epoch.
-\end{methoddesc}
-
-\begin{methoddesc}{set_date}{date}
-Set the delivery date of the message to \var{date}, a floating-point number
-representing seconds since the epoch.
-\end{methoddesc}
-
-\begin{methoddesc}{get_info}{}
-Return a string containing the "info" for a message. This is useful for
-accessing and modifying "info" that is experimental (i.e., not a list of
-flags).
-\end{methoddesc}
-
-\begin{methoddesc}{set_info}{info}
-Set "info" to \var{info}, which should be a string.
-\end{methoddesc}
-
-When a \class{MaildirMessage} instance is created based upon an
-\class{mboxMessage} or \class{MMDFMessage} instance, the \mailheader{Status}
-and \mailheader{X-Status} headers are omitted and the following conversions
-take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state}
-\lineii{"cur" subdirectory}{O flag}
-\lineii{F flag}{F flag}
-\lineii{R flag}{A flag}
-\lineii{S flag}{R flag}
-\lineii{T flag}{D flag}
-\end{tableii}
-
-When a \class{MaildirMessage} instance is created based upon an
-\class{MHMessage} instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MHMessage} state}
-\lineii{"cur" subdirectory}{"unseen" sequence}
-\lineii{"cur" subdirectory and S flag}{no "unseen" sequence}
-\lineii{F flag}{"flagged" sequence}
-\lineii{R flag}{"replied" sequence}
-\end{tableii}
-
-When a \class{MaildirMessage} instance is created based upon a
-\class{BabylMessage} instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{BabylMessage} state}
-\lineii{"cur" subdirectory}{"unseen" label}
-\lineii{"cur" subdirectory and S flag}{no "unseen" label}
-\lineii{P flag}{"forwarded" or "resent" label}
-\lineii{R flag}{"answered" label}
-\lineii{T flag}{"deleted" label}
-\end{tableii}
-
-\subsubsection{\class{mboxMessage}}
-\label{mailbox-mboxmessage}
-
-\begin{classdesc}{mboxMessage}{\optional{message}}
-A message with mbox-specific behaviors. Parameter \var{message} has the same
-meaning as with the \class{Message} constructor.
-\end{classdesc}
-
-Messages in an mbox mailbox are stored together in a single file. The sender's
-envelope address and the time of delivery are typically stored in a line
-beginning with "From~" that is used to indicate the start of a message, though
-there is considerable variation in the exact format of this data among mbox
-implementations. Flags that indicate the state of the message, such as whether
-it has been read or marked as important, are typically stored in
-\mailheader{Status} and \mailheader{X-Status} headers.
-
-Conventional flags for mbox messages are as follows:
-
-\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation}
-\lineiii{R}{Read}{Read}
-\lineiii{O}{Old}{Previously detected by MUA}
-\lineiii{D}{Deleted}{Marked for subsequent deletion}
-\lineiii{F}{Flagged}{Marked as important}
-\lineiii{A}{Answered}{Replied to}
-\end{tableiii}
-
-The "R" and "O" flags are stored in the \mailheader{Status} header, and the
-"D", "F", and "A" flags are stored in the \mailheader{X-Status} header. The
-flags and headers typically appear in the order mentioned.
-
-\class{mboxMessage} instances offer the following methods:
-
-\begin{methoddesc}{get_from}{}
-Return a string representing the "From~" line that marks the start of the
-message in an mbox mailbox. The leading "From~" and the trailing newline are
-excluded.
-\end{methoddesc}
-
-\begin{methoddesc}{set_from}{from_\optional{, time_=None}}
-Set the "From~" line to \var{from_}, which should be specified without a
-leading "From~" or trailing newline. For convenience, \var{time_} may be
-specified and will be formatted appropriately and appended to \var{from_}. If
-\var{time_} is specified, it should be a \class{struct_time} instance, a tuple
-suitable for passing to \method{time.strftime()}, or \code{True} (to use
-\method{time.gmtime()}).
-\end{methoddesc}
-
-\begin{methoddesc}{get_flags}{}
-Return a string specifying the flags that are currently set. If the message
-complies with the conventional format, the result is the concatenation in the
-following order of zero or one occurrence of each of \character{R},
-\character{O}, \character{D}, \character{F}, and \character{A}.
-\end{methoddesc}
-
-\begin{methoddesc}{set_flags}{flags}
-Set the flags specified by \var{flags} and unset all others. Parameter
-\var{flags} should be the concatenation in any order of zero or more
-occurrences of each of \character{R}, \character{O}, \character{D},
-\character{F}, and \character{A}.
-\end{methoddesc}
-
-\begin{methoddesc}{add_flag}{flag}
-Set the flag(s) specified by \var{flag} without changing other flags. To add
-more than one flag at a time, \var{flag} may be a string of more than one
-character.
-\end{methoddesc}
-
-\begin{methoddesc}{remove_flag}{flag}
-Unset the flag(s) specified by \var{flag} without changing other flags. To
-remove more than one flag at a time, \var{flag} maybe a string of more than one
-character.
-\end{methoddesc}
-
-When an \class{mboxMessage} instance is created based upon a
-\class{MaildirMessage} instance, a "From~" line is generated based upon the
-\class{MaildirMessage} instance's delivery date, and the following conversions
-take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MaildirMessage} state}
-\lineii{R flag}{S flag}
-\lineii{O flag}{"cur" subdirectory}
-\lineii{D flag}{T flag}
-\lineii{F flag}{F flag}
-\lineii{A flag}{R flag}
-\end{tableii}
-
-When an \class{mboxMessage} instance is created based upon an \class{MHMessage}
-instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MHMessage} state}
-\lineii{R flag and O flag}{no "unseen" sequence}
-\lineii{O flag}{"unseen" sequence}
-\lineii{F flag}{"flagged" sequence}
-\lineii{A flag}{"replied" sequence}
-\end{tableii}
-
-When an \class{mboxMessage} instance is created based upon a
-\class{BabylMessage} instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{BabylMessage} state}
-\lineii{R flag and O flag}{no "unseen" label}
-\lineii{O flag}{"unseen" label}
-\lineii{D flag}{"deleted" label}
-\lineii{A flag}{"answered" label}
-\end{tableii}
-
-When a \class{Message} instance is created based upon an \class{MMDFMessage}
-instance, the "From~" line is copied and all flags directly correspond:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MMDFMessage} state}
-\lineii{R flag}{R flag}
-\lineii{O flag}{O flag}
-\lineii{D flag}{D flag}
-\lineii{F flag}{F flag}
-\lineii{A flag}{A flag}
-\end{tableii}
-
-\subsubsection{\class{MHMessage}}
-\label{mailbox-mhmessage}
-
-\begin{classdesc}{MHMessage}{\optional{message}}
-A message with MH-specific behaviors. Parameter \var{message} has the same
-meaning as with the \class{Message} constructor.
-\end{classdesc}
-
-MH messages do not support marks or flags in the traditional sense, but they do
-support sequences, which are logical groupings of arbitrary messages. Some mail
-reading programs (although not the standard \program{mh} and \program{nmh}) use
-sequences in much the same way flags are used with other formats, as follows:
-
-\begin{tableii}{l|l}{textrm}{Sequence}{Explanation}
-\lineii{unseen}{Not read, but previously detected by MUA}
-\lineii{replied}{Replied to}
-\lineii{flagged}{Marked as important}
-\end{tableii}
-
-\class{MHMessage} instances offer the following methods:
-
-\begin{methoddesc}{get_sequences}{}
-Return a list of the names of sequences that include this message.
-\end{methoddesc}
-
-\begin{methoddesc}{set_sequences}{sequences}
-Set the list of sequences that include this message.
-\end{methoddesc}
-
-\begin{methoddesc}{add_sequence}{sequence}
-Add \var{sequence} to the list of sequences that include this message.
-\end{methoddesc}
-
-\begin{methoddesc}{remove_sequence}{sequence}
-Remove \var{sequence} from the list of sequences that include this message.
-\end{methoddesc}
-
-When an \class{MHMessage} instance is created based upon a
-\class{MaildirMessage} instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MaildirMessage} state}
-\lineii{"unseen" sequence}{no S flag}
-\lineii{"replied" sequence}{R flag}
-\lineii{"flagged" sequence}{F flag}
-\end{tableii}
-
-When an \class{MHMessage} instance is created based upon an \class{mboxMessage}
-or \class{MMDFMessage} instance, the \mailheader{Status} and
-\mailheader{X-Status} headers are omitted and the following conversions take
-place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state}
-\lineii{"unseen" sequence}{no R flag}
-\lineii{"replied" sequence}{A flag}
-\lineii{"flagged" sequence}{F flag}
-\end{tableii}
-
-When an \class{MHMessage} instance is created based upon a \class{BabylMessage}
-instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{BabylMessage} state}
-\lineii{"unseen" sequence}{"unseen" label}
-\lineii{"replied" sequence}{"answered" label}
-\end{tableii}
-
-\subsubsection{\class{BabylMessage}}
-\label{mailbox-babylmessage}
-
-\begin{classdesc}{BabylMessage}{\optional{message}}
-A message with Babyl-specific behaviors. Parameter \var{message} has the same
-meaning as with the \class{Message} constructor.
-\end{classdesc}
-
-Certain message labels, called \dfn{attributes}, are defined by convention to
-have special meanings. The attributes are as follows:
-
-\begin{tableii}{l|l}{textrm}{Label}{Explanation}
-\lineii{unseen}{Not read, but previously detected by MUA}
-\lineii{deleted}{Marked for subsequent deletion}
-\lineii{filed}{Copied to another file or mailbox}
-\lineii{answered}{Replied to}
-\lineii{forwarded}{Forwarded}
-\lineii{edited}{Modified by the user}
-\lineii{resent}{Resent}
-\end{tableii}
-
-By default, Rmail displays only
-visible headers. The \class{BabylMessage} class, though, uses the original
-headers because they are more complete. Visible headers may be accessed
-explicitly if desired.
-
-\class{BabylMessage} instances offer the following methods:
-
-\begin{methoddesc}{get_labels}{}
-Return a list of labels on the message.
-\end{methoddesc}
-
-\begin{methoddesc}{set_labels}{labels}
-Set the list of labels on the message to \var{labels}.
-\end{methoddesc}
-
-\begin{methoddesc}{add_label}{label}
-Add \var{label} to the list of labels on the message.
-\end{methoddesc}
-
-\begin{methoddesc}{remove_label}{label}
-Remove \var{label} from the list of labels on the message.
-\end{methoddesc}
-
-\begin{methoddesc}{get_visible}{}
-Return an \class{Message} instance whose headers are the message's visible
-headers and whose body is empty.
-\end{methoddesc}
-
-\begin{methoddesc}{set_visible}{visible}
-Set the message's visible headers to be the same as the headers in
-\var{message}. Parameter \var{visible} should be a \class{Message} instance, an
-\class{email.Message.Message} instance, a string, or a file-like object (which
-should be open in text mode).
-\end{methoddesc}
-
-\begin{methoddesc}{update_visible}{}
-When a \class{BabylMessage} instance's original headers are modified, the
-visible headers are not automatically modified to correspond. This method
-updates the visible headers as follows: each visible header with a
-corresponding original header is set to the value of the original header, each
-visible header without a corresponding original header is removed, and any of
-\mailheader{Date}, \mailheader{From}, \mailheader{Reply-To}, \mailheader{To},
-\mailheader{CC}, and \mailheader{Subject} that are present in the original
-headers but not the visible headers are added to the visible headers.
-\end{methoddesc}
-
-When a \class{BabylMessage} instance is created based upon a
-\class{MaildirMessage} instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MaildirMessage} state}
-\lineii{"unseen" label}{no S flag}
-\lineii{"deleted" label}{T flag}
-\lineii{"answered" label}{R flag}
-\lineii{"forwarded" label}{P flag}
-\end{tableii}
-
-When a \class{BabylMessage} instance is created based upon an
-\class{mboxMessage} or \class{MMDFMessage} instance, the \mailheader{Status}
-and \mailheader{X-Status} headers are omitted and the following conversions
-take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state}
-\lineii{"unseen" label}{no R flag}
-\lineii{"deleted" label}{D flag}
-\lineii{"answered" label}{A flag}
-\end{tableii}
-
-When a \class{BabylMessage} instance is created based upon an \class{MHMessage}
-instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MHMessage} state}
-\lineii{"unseen" label}{"unseen" sequence}
-\lineii{"answered" label}{"replied" sequence}
-\end{tableii}
-
-\subsubsection{\class{MMDFMessage}}
-\label{mailbox-mmdfmessage}
-
-\begin{classdesc}{MMDFMessage}{\optional{message}}
-A message with MMDF-specific behaviors. Parameter \var{message} has the same
-meaning as with the \class{Message} constructor.
-\end{classdesc}
-
-As with message in an mbox mailbox, MMDF messages are stored with the sender's
-address and the delivery date in an initial line beginning with "From ".
-Likewise, flags that indicate the state of the message are typically stored in
-\mailheader{Status} and \mailheader{X-Status} headers.
-
-Conventional flags for MMDF messages are identical to those of mbox message and
-are as follows:
-
-\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation}
-\lineiii{R}{Read}{Read}
-\lineiii{O}{Old}{Previously detected by MUA}
-\lineiii{D}{Deleted}{Marked for subsequent deletion}
-\lineiii{F}{Flagged}{Marked as important}
-\lineiii{A}{Answered}{Replied to}
-\end{tableiii}
-
-The "R" and "O" flags are stored in the \mailheader{Status} header, and the
-"D", "F", and "A" flags are stored in the \mailheader{X-Status} header. The
-flags and headers typically appear in the order mentioned.
-
-\class{MMDFMessage} instances offer the following methods, which are identical
-to those offered by \class{mboxMessage}:
-
-\begin{methoddesc}{get_from}{}
-Return a string representing the "From~" line that marks the start of the
-message in an mbox mailbox. The leading "From~" and the trailing newline are
-excluded.
-\end{methoddesc}
-
-\begin{methoddesc}{set_from}{from_\optional{, time_=None}}
-Set the "From~" line to \var{from_}, which should be specified without a
-leading "From~" or trailing newline. For convenience, \var{time_} may be
-specified and will be formatted appropriately and appended to \var{from_}. If
-\var{time_} is specified, it should be a \class{struct_time} instance, a tuple
-suitable for passing to \method{time.strftime()}, or \code{True} (to use
-\method{time.gmtime()}).
-\end{methoddesc}
-
-\begin{methoddesc}{get_flags}{}
-Return a string specifying the flags that are currently set. If the message
-complies with the conventional format, the result is the concatenation in the
-following order of zero or one occurrence of each of \character{R},
-\character{O}, \character{D}, \character{F}, and \character{A}.
-\end{methoddesc}
-
-\begin{methoddesc}{set_flags}{flags}
-Set the flags specified by \var{flags} and unset all others. Parameter
-\var{flags} should be the concatenation in any order of zero or more
-occurrences of each of \character{R}, \character{O}, \character{D},
-\character{F}, and \character{A}.
-\end{methoddesc}
-
-\begin{methoddesc}{add_flag}{flag}
-Set the flag(s) specified by \var{flag} without changing other flags. To add
-more than one flag at a time, \var{flag} may be a string of more than one
-character.
-\end{methoddesc}
-
-\begin{methoddesc}{remove_flag}{flag}
-Unset the flag(s) specified by \var{flag} without changing other flags. To
-remove more than one flag at a time, \var{flag} maybe a string of more than one
-character.
-\end{methoddesc}
-
-When an \class{MMDFMessage} instance is created based upon a
-\class{MaildirMessage} instance, a "From~" line is generated based upon the
-\class{MaildirMessage} instance's delivery date, and the following conversions
-take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MaildirMessage} state}
-\lineii{R flag}{S flag}
-\lineii{O flag}{"cur" subdirectory}
-\lineii{D flag}{T flag}
-\lineii{F flag}{F flag}
-\lineii{A flag}{R flag}
-\end{tableii}
-
-When an \class{MMDFMessage} instance is created based upon an \class{MHMessage}
-instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MHMessage} state}
-\lineii{R flag and O flag}{no "unseen" sequence}
-\lineii{O flag}{"unseen" sequence}
-\lineii{F flag}{"flagged" sequence}
-\lineii{A flag}{"replied" sequence}
-\end{tableii}
-
-When an \class{MMDFMessage} instance is created based upon a
-\class{BabylMessage} instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{BabylMessage} state}
-\lineii{R flag and O flag}{no "unseen" label}
-\lineii{O flag}{"unseen" label}
-\lineii{D flag}{"deleted" label}
-\lineii{A flag}{"answered" label}
-\end{tableii}
-
-When an \class{MMDFMessage} instance is created based upon an
-\class{mboxMessage} instance, the "From~" line is copied and all flags directly
-correspond:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{mboxMessage} state}
-\lineii{R flag}{R flag}
-\lineii{O flag}{O flag}
-\lineii{D flag}{D flag}
-\lineii{F flag}{F flag}
-\lineii{A flag}{A flag}
-\end{tableii}
-
-\subsection{Exceptions}
-
-The following exception classes are defined in the \module{mailbox} module:
-
-\begin{classdesc}{Error}{}
-The based class for all other module-specific exceptions.
-\end{classdesc}
-
-\begin{classdesc}{NoSuchMailboxError}{}
-Raised when a mailbox is expected but is not found, such as when instantiating
-a \class{Mailbox} subclass with a path that does not exist (and with the
-\var{create} parameter set to \code{False}), or when opening a folder that does
-not exist.
-\end{classdesc}
-
-\begin{classdesc}{NotEmptyErrorError}{}
-Raised when a mailbox is not empty but is expected to be, such as when deleting
-a folder that contains messages.
-\end{classdesc}
-
-\begin{classdesc}{ExternalClashError}{}
-Raised when some mailbox-related condition beyond the control of the program
-causes it to be unable to proceed, such as when failing to acquire a lock that
-another program already holds a lock, or when a uniquely-generated file name
-already exists.
-\end{classdesc}
-
-\begin{classdesc}{FormatError}{}
-Raised when the data in a file cannot be parsed, such as when an \class{MH}
-instance attempts to read a corrupted \file{.mh_sequences} file.
-\end{classdesc}
-
-\subsection{Deprecated classes and methods}
-\label{mailbox-deprecated}
-
-Older versions of the \module{mailbox} module do not support modification of
-mailboxes, such as adding or removing message, and do not provide classes to
-represent format-specific message properties. For backward compatibility, the
-older mailbox classes are still available, but the newer classes should be used
-in preference to them.
-
-Older mailbox objects support only iteration and provide a single public
-method:
-
-\begin{methoddesc}[oldmailbox]{next}{}
-Return the next message in the mailbox, created with the optional \var{factory}
-argument passed into the mailbox object's constructor. By default this is an
-\class{rfc822.Message} object (see the \refmodule{rfc822} module). Depending
-on the mailbox implementation the \var{fp} attribute of this object may be a
-true file object or a class instance simulating a file object, taking care of
-things like message boundaries if multiple mail messages are contained in a
-single file, etc. If no more messages are available, this method returns
-\code{None}.
-\end{methoddesc}
-
-Most of the older mailbox classes have names that differ from the current
-mailbox class names, except for \class{Maildir}. For this reason, the new
-\class{Maildir} class defines a \method{next()} method and its constructor
-differs slightly from those of the other new mailbox classes.
-
-The older mailbox classes whose names are not the same as their newer
-counterparts are as follows:
-
-\begin{classdesc}{UnixMailbox}{fp\optional{, factory}}
-Access to a classic \UNIX-style mailbox, where all messages are
-contained in a single file and separated by \samp{From }
-(a.k.a.\ \samp{From_}) lines. The file object \var{fp} points to the
-mailbox file. The optional \var{factory} parameter is a callable that
-should create new message objects. \var{factory} is called with one
-argument, \var{fp} by the \method{next()} method of the mailbox
-object. The default is the \class{rfc822.Message} class (see the
-\refmodule{rfc822} module -- and the note below).
-
-\begin{notice}
- For reasons of this module's internal implementation, you will
- probably want to open the \var{fp} object in binary mode. This is
- especially important on Windows.
-\end{notice}
-
-For maximum portability, messages in a \UNIX-style mailbox are
-separated by any line that begins exactly with the string \code{'From
-'} (note the trailing space) if preceded by exactly two newlines.
-Because of the wide-range of variations in practice, nothing else on
-the \samp{From_} line should be considered. However, the current
-implementation doesn't check for the leading two newlines. This is
-usually fine for most applications.
-
-The \class{UnixMailbox} class implements a more strict version of
-\samp{From_} line checking, using a regular expression that usually correctly
-matched \samp{From_} delimiters. It considers delimiter line to be separated
-by \samp{From \var{name} \var{time}} lines. For maximum portability,
-use the \class{PortableUnixMailbox} class instead. This class is
-identical to \class{UnixMailbox} except that individual messages are
-separated by only \samp{From } lines.
-
-For more information, see
-\citetitle[http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html]{Configuring
-Netscape Mail on \UNIX: Why the Content-Length Format is Bad}.
-\end{classdesc}
-
-\begin{classdesc}{PortableUnixMailbox}{fp\optional{, factory}}
-A less-strict version of \class{UnixMailbox}, which considers only the
-\samp{From } at the beginning of the line separating messages. The
-``\var{name} \var{time}'' portion of the From line is ignored, to
-protect against some variations that are observed in practice. This
-works since lines in the message which begin with \code{'From '} are
-quoted by mail handling software at delivery-time.
-\end{classdesc}
-
-\begin{classdesc}{MmdfMailbox}{fp\optional{, factory}}
-Access an MMDF-style mailbox, where all messages are contained
-in a single file and separated by lines consisting of 4 control-A
-characters. The file object \var{fp} points to the mailbox file.
-Optional \var{factory} is as with the \class{UnixMailbox} class.
-\end{classdesc}
-
-\begin{classdesc}{MHMailbox}{dirname\optional{, factory}}
-Access an MH mailbox, a directory with each message in a separate
-file with a numeric name.
-The name of the mailbox directory is passed in \var{dirname}.
-\var{factory} is as with the \class{UnixMailbox} class.
-\end{classdesc}
-
-\begin{classdesc}{BabylMailbox}{fp\optional{, factory}}
-Access a Babyl mailbox, which is similar to an MMDF mailbox. In
-Babyl format, each message has two sets of headers, the
-\emph{original} headers and the \emph{visible} headers. The original
-headers appear before a line containing only \code{'*** EOOH ***'}
-(End-Of-Original-Headers) and the visible headers appear after the
-\code{EOOH} line. Babyl-compliant mail readers will show you only the
-visible headers, and \class{BabylMailbox} objects will return messages
-containing only the visible headers. You'll have to do your own
-parsing of the mailbox file to get at the original headers. Mail
-messages start with the EOOH line and end with a line containing only
-\code{'\e{}037\e{}014'}. \var{factory} is as with the
-\class{UnixMailbox} class.
-\end{classdesc}
-
-If you wish to use the older mailbox classes with the \module{email} module
-rather than the deprecated \module{rfc822} module, you can do so as follows:
-
-\begin{verbatim}
-import email
-import email.Errors
-import mailbox
-
-def msgfactory(fp):
- try:
- return email.message_from_file(fp)
- except email.Errors.MessageParseError:
- # Don't return None since that will
- # stop the mailbox iterator
- return ''
-
-mbox = mailbox.UnixMailbox(fp, msgfactory)
-\end{verbatim}
-
-Alternatively, if you know your mailbox contains only well-formed MIME
-messages, you can simplify this to:
-
-\begin{verbatim}
-import email
-import mailbox
-
-mbox = mailbox.UnixMailbox(fp, email.message_from_file)
-\end{verbatim}
-
-\subsection{Examples}
-\label{mailbox-examples}
-
-A simple example of printing the subjects of all messages in a mailbox that
-seem interesting:
-
-\begin{verbatim}
-import mailbox
-for message in mailbox.mbox('~/mbox'):
- subject = message['subject'] # Could possibly be None.
- if subject and 'python' in subject.lower():
- print subject
-\end{verbatim}
-
-To copy all mail from a Babyl mailbox to an MH mailbox, converting all
-of the format-specific information that can be converted:
-
-\begin{verbatim}
-import mailbox
-destination = mailbox.MH('~/Mail')
-destination.lock()
-for message in mailbox.Babyl('~/RMAIL'):
- destination.add(MHMessage(message))
-destination.flush()
-destination.unlock()
-\end{verbatim}
-
-This example sorts mail from several mailing lists into different
-mailboxes, being careful to avoid mail corruption due to concurrent
-modification by other programs, mail loss due to interruption of the
-program, or premature termination due to malformed messages in the
-mailbox:
-
-\begin{verbatim}
-import mailbox
-import email.Errors
-
-list_names = ('python-list', 'python-dev', 'python-bugs')
-
-boxes = dict((name, mailbox.mbox('~/email/%s' % name)) for name in list_names)
-inbox = mailbox.Maildir('~/Maildir', factory=None)
-
-for key in inbox.iterkeys():
- try:
- message = inbox[key]
- except email.Errors.MessageParseError:
- continue # The message is malformed. Just leave it.
-
- for name in list_names:
- list_id = message['list-id']
- if list_id and name in list_id:
- # Get mailbox to use
- box = boxes[name]
-
- # Write copy to disk before removing original.
- # If there's a crash, you might duplicate a message, but
- # that's better than losing a message completely.
- box.lock()
- box.add(message)
- box.flush()
- box.unlock()
-
- # Remove original message
- inbox.lock()
- inbox.discard(key)
- inbox.flush()
- inbox.unlock()
- break # Found destination, so stop looking.
-
-for box in boxes.itervalues():
- box.close()
-\end{verbatim}
diff --git a/Doc/lib/libmailcap.tex b/Doc/lib/libmailcap.tex
deleted file mode 100644
index b221bb3..0000000
--- a/Doc/lib/libmailcap.tex
+++ /dev/null
@@ -1,82 +0,0 @@
-\section{\module{mailcap} ---
- Mailcap file handling.}
-\declaremodule{standard}{mailcap}
-
-\modulesynopsis{Mailcap file handling.}
-
-
-Mailcap files are used to configure how MIME-aware applications such
-as mail readers and Web browsers react to files with different MIME
-types. (The name ``mailcap'' is derived from the phrase ``mail
-capability''.) For example, a mailcap file might contain a line like
-\samp{video/mpeg; xmpeg \%s}. Then, if the user encounters an email
-message or Web document with the MIME type \mimetype{video/mpeg},
-\samp{\%s} will be replaced by a filename (usually one belonging to a
-temporary file) and the \program{xmpeg} program can be automatically
-started to view the file.
-
-The mailcap format is documented in \rfc{1524}, ``A User Agent
-Configuration Mechanism For Multimedia Mail Format Information,'' but
-is not an Internet standard. However, mailcap files are supported on
-most \UNIX{} systems.
-
-\begin{funcdesc}{findmatch}{caps, MIMEtype%
- \optional{, key\optional{,
- filename\optional{, plist}}}}
-Return a 2-tuple; the first element is a string containing the command
-line to be executed
-(which can be passed to \function{os.system()}), and the second element is
-the mailcap entry for a given MIME type. If no matching MIME
-type can be found, \code{(None, None)} is returned.
-
-\var{key} is the name of the field desired, which represents the type
-of activity to be performed; the default value is 'view', since in the
-most common case you simply want to view the body of the MIME-typed
-data. Other possible values might be 'compose' and 'edit', if you
-wanted to create a new body of the given MIME type or alter the
-existing body data. See \rfc{1524} for a complete list of these
-fields.
-
-\var{filename} is the filename to be substituted for \samp{\%s} in the
-command line; the default value is
-\code{'/dev/null'} which is almost certainly not what you want, so
-usually you'll override it by specifying a filename.
-
-\var{plist} can be a list containing named parameters; the default
-value is simply an empty list. Each entry in the list must be a
-string containing the parameter name, an equals sign (\character{=}),
-and the parameter's value. Mailcap entries can contain
-named parameters like \code{\%\{foo\}}, which will be replaced by the
-value of the parameter named 'foo'. For example, if the command line
-\samp{showpartial \%\{id\}\ \%\{number\}\ \%\{total\}}
-was in a mailcap file, and \var{plist} was set to \code{['id=1',
-'number=2', 'total=3']}, the resulting command line would be
-\code{'showpartial 1 2 3'}.
-
-In a mailcap file, the ``test'' field can optionally be specified to
-test some external condition (such as the machine architecture, or the
-window system in use) to determine whether or not the mailcap line
-applies. \function{findmatch()} will automatically check such
-conditions and skip the entry if the check fails.
-\end{funcdesc}
-
-\begin{funcdesc}{getcaps}{}
-Returns a dictionary mapping MIME types to a list of mailcap file
-entries. This dictionary must be passed to the \function{findmatch()}
-function. An entry is stored as a list of dictionaries, but it
-shouldn't be necessary to know the details of this representation.
-
-The information is derived from all of the mailcap files found on the
-system. Settings in the user's mailcap file \file{\$HOME/.mailcap}
-will override settings in the system mailcap files
-\file{/etc/mailcap}, \file{/usr/etc/mailcap}, and
-\file{/usr/local/etc/mailcap}.
-\end{funcdesc}
-
-An example usage:
-\begin{verbatim}
->>> import mailcap
->>> d=mailcap.getcaps()
->>> mailcap.findmatch(d, 'video/mpeg', filename='/tmp/tmp1223')
-('xmpeg /tmp/tmp1223', {'view': 'xmpeg %s'})
-\end{verbatim}
diff --git a/Doc/lib/libmain.tex b/Doc/lib/libmain.tex
deleted file mode 100644
index 00c7426..0000000
--- a/Doc/lib/libmain.tex
+++ /dev/null
@@ -1,16 +0,0 @@
-\section{\module{__main__} ---
- Top-level script environment}
-
-\declaremodule[main]{builtin}{__main__}
-\modulesynopsis{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:
-
-\begin{verbatim}
-if __name__ == "__main__":
- main()
-\end{verbatim}
diff --git a/Doc/lib/libmarshal.tex b/Doc/lib/libmarshal.tex
deleted file mode 100644
index 63ff392..0000000
--- a/Doc/lib/libmarshal.tex
+++ /dev/null
@@ -1,117 +0,0 @@
-\section{\module{marshal} ---
- Internal Python object serialization}
-
-\declaremodule{builtin}{marshal}
-\modulesynopsis{Convert Python objects to streams of bytes and back
- (with different constraints).}
-
-
-This module contains functions that can read and write Python
-values in a binary format. The format is specific to Python, but
-independent of machine architecture issues (e.g., you can write a
-Python value to a file on a PC, transport the file to a Sun, and read
-it back there). Details of the format are undocumented on purpose;
-it may change between Python versions (although it rarely
-does).\footnote{The name of this module stems from a bit of
- terminology used by the designers of Modula-3 (amongst others), who
- use the term ``marshalling'' for shipping of data around in a
- self-contained form. Strictly speaking, ``to marshal'' means to
- convert some data from internal to external form (in an RPC buffer for
- instance) and ``unmarshalling'' for the reverse process.}
-
-This is not a general ``persistence'' module. For general persistence
-and transfer of Python objects through RPC calls, see the modules
-\refmodule{pickle} and \refmodule{shelve}. The \module{marshal} module exists
-mainly to support reading and writing the ``pseudo-compiled'' code for
-Python modules of \file{.pyc} files. Therefore, the Python
-maintainers reserve the right to modify the marshal format in backward
-incompatible ways should the need arise. If you're serializing and
-de-serializing Python objects, use the \module{pickle} module instead.
-\refstmodindex{pickle}
-\refstmodindex{shelve}
-\obindex{code}
-
-\begin{notice}[warning]
-The \module{marshal} module is not intended to be secure against
-erroneous or maliciously constructed data. Never unmarshal data
-received from an untrusted or unauthenticated source.
-\end{notice}
-
-Not all Python object types are supported; in general, only objects
-whose value is independent from a particular invocation of Python can
-be written and read by this module. The following types are supported:
-\code{None}, integers, long integers, floating point numbers,
-strings, Unicode objects, tuples, lists, dictionaries, and code
-objects, where it should be understood that tuples, lists and
-dictionaries are only supported as long as the values contained
-therein are themselves supported; and recursive lists and dictionaries
-should not be written (they will cause infinite loops).
-
-\strong{Caveat:} On machines where C's \code{long int} type has more than
-32 bits (such as the DEC Alpha), it is possible to create plain Python
-integers that are longer than 32 bits.
-If such an integer is marshaled and read back in on a machine where
-C's \code{long int} type has only 32 bits, a Python long integer object
-is returned instead. While of a different type, the numeric value is
-the same. (This behavior is new in Python 2.2. In earlier versions,
-all but the least-significant 32 bits of the value were lost, and a
-warning message was printed.)
-
-There are functions that read/write files as well as functions
-operating on strings.
-
-The module defines these functions:
-
-\begin{funcdesc}{dump}{value, file\optional{, version}}
- Write the value on the open file. The value must be a supported
- type. The file must be an open file object such as
- \code{sys.stdout} or returned by \function{open()} or
- \function{posix.popen()}. It must be opened in binary mode
- (\code{'wb'} or \code{'w+b'}).
-
- If the value has (or contains an object that has) an unsupported type,
- a \exception{ValueError} exception is raised --- but garbage data
- will also be written to the file. The object will not be properly
- read back by \function{load()}.
-
- \versionadded[The \var{version} argument indicates the data
- format that \code{dump} should use (see below)]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{load}{file}
- Read one value from the open file and return it. If no valid value
- is read, raise \exception{EOFError}, \exception{ValueError} or
- \exception{TypeError}. The file must be an open file object opened
- in binary mode (\code{'rb'} or \code{'r+b'}).
-
- \warning{If an object containing an unsupported type was
- marshalled with \function{dump()}, \function{load()} will substitute
- \code{None} for the unmarshallable type.}
-\end{funcdesc}
-
-\begin{funcdesc}{dumps}{value\optional{, version}}
- Return the string that would be written to a file by
- \code{dump(\var{value}, \var{file})}. The value must be a supported
- type. Raise a \exception{ValueError} exception if value has (or
- contains an object that has) an unsupported type.
-
- \versionadded[The \var{version} argument indicates the data
- format that \code{dumps} should use (see below)]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{loads}{string}
- Convert the string to a value. If no valid value is found, raise
- \exception{EOFError}, \exception{ValueError} or
- \exception{TypeError}. Extra characters in the string are ignored.
-\end{funcdesc}
-
-In addition, the following constants are defined:
-
-\begin{datadesc}{version}
- Indicates the format that the module uses. Version 0 is the
- historical format, version 1 (added in Python 2.4) shares interned
- strings and version 2 (added in Python 2.5) uses a binary format for
- floating point numbers. The current version is 2.
-
- \versionadded{2.4}
-\end{datadesc}
diff --git a/Doc/lib/libmath.tex b/Doc/lib/libmath.tex
deleted file mode 100644
index e52f8f9..0000000
--- a/Doc/lib/libmath.tex
+++ /dev/null
@@ -1,209 +0,0 @@
-\section{\module{math} ---
- Mathematical functions}
-
-\declaremodule{builtin}{math}
-\modulesynopsis{Mathematical functions (\function{sin()} etc.).}
-
-This module is always available. It provides access to the
-mathematical functions defined by the C standard.
-
-These functions cannot be used with complex numbers; use the functions
-of the same name from the \refmodule{cmath} module if you require
-support for complex numbers. The distinction between functions which
-support complex numbers and those which don't is made since most users
-do not want to learn quite as much mathematics as required to
-understand complex numbers. Receiving an exception instead of a
-complex result allows earlier detection of the unexpected complex
-number used as a parameter, so that the programmer can determine how
-and why it was generated in the first place.
-
-The following functions are provided by this module. Except
-when explicitly noted otherwise, all return values are floats.
-
-Number-theoretic and representation functions:
-
-\begin{funcdesc}{ceil}{x}
-Return the ceiling of \var{x} as a float, the smallest integer value
-greater than or equal to \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{fabs}{x}
-Return the absolute value of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{floor}{x}
-Return the floor of \var{x} as a float, the largest integer value
-less than or equal to \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{fmod}{x, y}
-Return \code{fmod(\var{x}, \var{y})}, as defined by the platform C library.
-Note that the Python expression \code{\var{x} \%\ \var{y}} may not return
-the same result. The intent of the C standard is that
-\code{fmod(\var{x}, \var{y})} be exactly (mathematically; to infinite
-precision) equal to \code{\var{x} - \var{n}*\var{y}} for some integer
-\var{n} such that the result has the same sign as \var{x} and
-magnitude less than \code{abs(\var{y})}. Python's
-\code{\var{x} \%\ \var{y}} returns a result with the sign of
-\var{y} instead, and may not be exactly computable for float arguments.
-For example, \code{fmod(-1e-100, 1e100)} is \code{-1e-100}, but the
-result of Python's \code{-1e-100 \%\ 1e100} is \code{1e100-1e-100}, which
-cannot be represented exactly as a float, and rounds to the surprising
-\code{1e100}. For this reason, function \function{fmod()} is generally
-preferred when working with floats, while Python's
-\code{\var{x} \%\ \var{y}} is preferred when working with integers.
-\end{funcdesc}
-
-\begin{funcdesc}{frexp}{x}
-Return the mantissa and exponent of \var{x} as the pair
-\code{(\var{m}, \var{e})}. \var{m} is a float and \var{e} is an
-integer such that \code{\var{x} == \var{m} * 2**\var{e}} exactly.
-If \var{x} is zero, returns \code{(0.0, 0)}, otherwise
-\code{0.5 <= abs(\var{m}) < 1}. This is used to "pick apart" the
-internal representation of a float in a portable way.
-\end{funcdesc}
-
-\begin{funcdesc}{ldexp}{x, i}
-Return \code{\var{x} * (2**\var{i})}. This is essentially the inverse of
-function \function{frexp()}.
-\end{funcdesc}
-
-\begin{funcdesc}{modf}{x}
-Return the fractional and integer parts of \var{x}. Both results
-carry the sign of \var{x}, and both are floats.
-\end{funcdesc}
-
-Note that \function{frexp()} and \function{modf()} have a different
-call/return pattern than their C equivalents: they take a single
-argument and return a pair of values, rather than returning their
-second return value through an `output parameter' (there is no such
-thing in Python).
-
-For the \function{ceil()}, \function{floor()}, and \function{modf()}
-functions, note that \emph{all} floating-point numbers of sufficiently
-large magnitude are exact integers. Python floats typically carry no more
-than 53 bits of precision (the same as the platform C double type), in
-which case any float \var{x} with \code{abs(\var{x}) >= 2**52}
-necessarily has no fractional bits.
-
-
-Power and logarithmic functions:
-
-\begin{funcdesc}{exp}{x}
-Return \code{e**\var{x}}.
-\end{funcdesc}
-
-\begin{funcdesc}{log}{x\optional{, base}}
-Return the logarithm of \var{x} to the given \var{base}.
-If the \var{base} is not specified, return the natural logarithm of \var{x}
-(that is, the logarithm to base \emph{e}).
-\versionchanged[\var{base} argument added]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{log10}{x}
-Return the base-10 logarithm of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{pow}{x, y}
-Return \code{\var{x}**\var{y}}.
-\end{funcdesc}
-
-\begin{funcdesc}{sqrt}{x}
-Return the square root of \var{x}.
-\end{funcdesc}
-
-Trigonometric functions:
-
-\begin{funcdesc}{acos}{x}
-Return the arc cosine of \var{x}, in radians.
-\end{funcdesc}
-
-\begin{funcdesc}{asin}{x}
-Return the arc sine of \var{x}, in radians.
-\end{funcdesc}
-
-\begin{funcdesc}{atan}{x}
-Return the arc tangent of \var{x}, in radians.
-\end{funcdesc}
-
-\begin{funcdesc}{atan2}{y, x}
-Return \code{atan(\var{y} / \var{x})}, in radians.
-The result is between \code{-pi} and \code{pi}.
-The vector in the plane from the origin to point \code{(\var{x}, \var{y})}
-makes this angle with the positive X axis.
-The point of \function{atan2()} is that the signs of both inputs are
-known to it, so it can compute the correct quadrant for the angle.
-For example, \code{atan(1}) and \code{atan2(1, 1)} are both \code{pi/4},
-but \code{atan2(-1, -1)} is \code{-3*pi/4}.
-\end{funcdesc}
-
-\begin{funcdesc}{cos}{x}
-Return the cosine of \var{x} radians.
-\end{funcdesc}
-
-\begin{funcdesc}{hypot}{x, y}
-Return the Euclidean norm, \code{sqrt(\var{x}*\var{x} + \var{y}*\var{y})}.
-This is the length of the vector from the origin to point
-\code{(\var{x}, \var{y})}.
-\end{funcdesc}
-
-\begin{funcdesc}{sin}{x}
-Return the sine of \var{x} radians.
-\end{funcdesc}
-
-\begin{funcdesc}{tan}{x}
-Return the tangent of \var{x} radians.
-\end{funcdesc}
-
-Angular conversion:
-
-\begin{funcdesc}{degrees}{x}
-Converts angle \var{x} from radians to degrees.
-\end{funcdesc}
-
-\begin{funcdesc}{radians}{x}
-Converts angle \var{x} from degrees to radians.
-\end{funcdesc}
-
-Hyperbolic functions:
-
-\begin{funcdesc}{cosh}{x}
-Return the hyperbolic cosine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{sinh}{x}
-Return the hyperbolic sine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{tanh}{x}
-Return the hyperbolic tangent of \var{x}.
-\end{funcdesc}
-
-The module also defines two mathematical constants:
-
-\begin{datadesc}{pi}
-The mathematical constant \emph{pi}.
-\end{datadesc}
-
-\begin{datadesc}{e}
-The mathematical constant \emph{e}.
-\end{datadesc}
-
-\begin{notice}
- The \module{math} module consists mostly of thin wrappers around
- the platform C math library functions. Behavior in exceptional cases is
- loosely specified by the C standards, and Python inherits much of its
- math-function error-reporting behavior from the platform C
- implementation. As a result,
- the specific exceptions raised in error cases (and even whether some
- arguments are considered to be exceptional at all) are not defined in any
- useful cross-platform or cross-release way. For example, whether
- \code{math.log(0)} returns \code{-Inf} or raises \exception{ValueError} or
- \exception{OverflowError} isn't defined, and in
- cases where \code{math.log(0)} raises \exception{OverflowError},
- \code{math.log(0L)} may raise \exception{ValueError} instead.
-\end{notice}
-
-\begin{seealso}
- \seemodule{cmath}{Complex number versions of many of these functions.}
-\end{seealso}
diff --git a/Doc/lib/libmhlib.tex b/Doc/lib/libmhlib.tex
deleted file mode 100644
index 3e70663..0000000
--- a/Doc/lib/libmhlib.tex
+++ /dev/null
@@ -1,168 +0,0 @@
-\section{\module{mhlib} ---
- Access to MH mailboxes}
-
-% LaTeX'ized from the comments in the module by Skip Montanaro
-% <skip@mojam.com>.
-
-\declaremodule{standard}{mhlib}
-\modulesynopsis{Manipulate MH mailboxes from Python.}
-
-
-The \module{mhlib} module provides a Python interface to MH folders and
-their contents.
-
-The module contains three basic classes, \class{MH}, which represents a
-particular collection of folders, \class{Folder}, which represents a single
-folder, and \class{Message}, which represents a single message.
-
-
-\begin{classdesc}{MH}{\optional{path\optional{, profile}}}
-\class{MH} represents a collection of MH folders.
-\end{classdesc}
-
-\begin{classdesc}{Folder}{mh, name}
-The \class{Folder} class represents a single folder and its messages.
-\end{classdesc}
-
-\begin{classdesc}{Message}{folder, number\optional{, name}}
-\class{Message} objects represent individual messages in a folder. The
-Message class is derived from \class{mimetools.Message}.
-\end{classdesc}
-
-
-\subsection{MH Objects \label{mh-objects}}
-
-\class{MH} instances have the following methods:
-
-
-\begin{methoddesc}[MH]{error}{format\optional{, ...}}
-Print an error message -- can be overridden.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{getprofile}{key}
-Return a profile entry (\code{None} if not set).
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{getpath}{}
-Return the mailbox pathname.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{getcontext}{}
-Return the current folder name.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{setcontext}{name}
-Set the current folder name.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{listfolders}{}
-Return a list of top-level folders.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{listallfolders}{}
-Return a list of all folders.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{listsubfolders}{name}
-Return a list of direct subfolders of the given folder.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{listallsubfolders}{name}
-Return a list of all subfolders of the given folder.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{makefolder}{name}
-Create a new folder.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{deletefolder}{name}
-Delete a folder -- must have no subfolders.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{openfolder}{name}
-Return a new open folder object.
-\end{methoddesc}
-
-
-
-\subsection{Folder Objects \label{mh-folder-objects}}
-
-\class{Folder} instances represent open folders and have the following
-methods:
-
-
-\begin{methoddesc}[Folder]{error}{format\optional{, ...}}
-Print an error message -- can be overridden.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{getfullname}{}
-Return the folder's full pathname.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{getsequencesfilename}{}
-Return the full pathname of the folder's sequences file.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{getmessagefilename}{n}
-Return the full pathname of message \var{n} of the folder.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{listmessages}{}
-Return a list of messages in the folder (as numbers).
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{getcurrent}{}
-Return the current message number.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{setcurrent}{n}
-Set the current message number to \var{n}.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{parsesequence}{seq}
-Parse msgs syntax into list of messages.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{getlast}{}
-Get last message, or \code{0} if no messages are in the folder.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{setlast}{n}
-Set last message (internal use only).
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{getsequences}{}
-Return dictionary of sequences in folder. The sequence names are used
-as keys, and the values are the lists of message numbers in the
-sequences.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{putsequences}{dict}
-Return dictionary of sequences in folder {name: list}.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{removemessages}{list}
-Remove messages in list from folder.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{refilemessages}{list, tofolder}
-Move messages in list to other folder.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{movemessage}{n, tofolder, ton}
-Move one message to a given destination in another folder.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{copymessage}{n, tofolder, ton}
-Copy one message to a given destination in another folder.
-\end{methoddesc}
-
-
-\subsection{Message Objects \label{mh-message-objects}}
-
-The \class{Message} class adds one method to those of
-\class{mimetools.Message}:
-
-\begin{methoddesc}[Message]{openmessage}{n}
-Return a new open message object (costs a file descriptor).
-\end{methoddesc}
diff --git a/Doc/lib/libmimetools.tex b/Doc/lib/libmimetools.tex
deleted file mode 100644
index 3e4bd4b..0000000
--- a/Doc/lib/libmimetools.tex
+++ /dev/null
@@ -1,120 +0,0 @@
-\section{\module{mimetools} ---
- Tools for parsing MIME messages}
-
-\declaremodule{standard}{mimetools}
-\modulesynopsis{Tools for parsing MIME-style message bodies.}
-
-\deprecated{2.3}{The \refmodule{email} package should be used in
- preference to the \module{mimetools} module. This
- module is present only to maintain backward
- compatibility.}
-
-This module defines a subclass of the
-\refmodule{rfc822}\refstmodindex{rfc822} module's
-\class{Message} class and a number of utility functions that are
-useful for the manipulation for MIME multipart or encoded message.
-
-It defines the following items:
-
-\begin{classdesc}{Message}{fp\optional{, seekable}}
-Return a new instance of the \class{Message} class. This is a
-subclass of the \class{rfc822.Message} class, with some additional
-methods (see below). The \var{seekable} argument has the same meaning
-as for \class{rfc822.Message}.
-\end{classdesc}
-
-\begin{funcdesc}{choose_boundary}{}
-Return a unique string that has a high likelihood of being usable as a
-part boundary. The string has the form
-\code{'\var{hostipaddr}.\var{uid}.\var{pid}.\var{timestamp}.\var{random}'}.
-\end{funcdesc}
-
-\begin{funcdesc}{decode}{input, output, encoding}
-Read data encoded using the allowed MIME \var{encoding} from open file
-object \var{input} and write the decoded data to open file object
-\var{output}. Valid values for \var{encoding} include
-\code{'base64'}, \code{'quoted-printable'}, \code{'uuencode'},
-\code{'x-uuencode'}, \code{'uue'}, \code{'x-uue'}, \code{'7bit'}, and
-\code{'8bit'}. Decoding messages encoded in \code{'7bit'} or \code{'8bit'}
-has no effect. The input is simply copied to the output.
-\end{funcdesc}
-
-\begin{funcdesc}{encode}{input, output, encoding}
-Read data from open file object \var{input} and write it encoded using
-the allowed MIME \var{encoding} to open file object \var{output}.
-Valid values for \var{encoding} are the same as for \method{decode()}.
-\end{funcdesc}
-
-\begin{funcdesc}{copyliteral}{input, output}
-Read lines from open file \var{input} until \EOF{} and write them to
-open file \var{output}.
-\end{funcdesc}
-
-\begin{funcdesc}{copybinary}{input, output}
-Read blocks until \EOF{} from open file \var{input} and write them to
-open file \var{output}. The block size is currently fixed at 8192.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{email}{Comprehensive email handling package; supersedes
- the \module{mimetools} module.}
- \seemodule{rfc822}{Provides the base class for
- \class{mimetools.Message}.}
- \seemodule{multifile}{Support for reading files which contain
- distinct parts, such as MIME data.}
- \seeurl{http://www.cs.uu.nl/wais/html/na-dir/mail/mime-faq/.html}{
- The MIME Frequently Asked Questions document. For an
- overview of MIME, see the answer to question 1.1 in Part 1
- of this document.}
-\end{seealso}
-
-
-\subsection{Additional Methods of Message Objects
- \label{mimetools-message-objects}}
-
-The \class{Message} class defines the following methods in
-addition to the \class{rfc822.Message} methods:
-
-\begin{methoddesc}[Message]{getplist}{}
-Return the parameter list of the \mailheader{Content-Type} header.
-This is a list of strings. For parameters of the form
-\samp{\var{key}=\var{value}}, \var{key} is converted to lower case but
-\var{value} is not. For example, if the message contains the header
-\samp{Content-type: text/html; spam=1; Spam=2; Spam} then
-\method{getplist()} will return the Python list \code{['spam=1',
-'spam=2', 'Spam']}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getparam}{name}
-Return the \var{value} of the first parameter (as returned by
-\method{getplist()}) of the form \samp{\var{name}=\var{value}} for the
-given \var{name}. If \var{value} is surrounded by quotes of the form
-`\code{<}...\code{>}' or `\code{"}...\code{"}', these are removed.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getencoding}{}
-Return the encoding specified in the
-\mailheader{Content-Transfer-Encoding} message header. If no such
-header exists, return \code{'7bit'}. The encoding is converted to
-lower case.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{gettype}{}
-Return the message type (of the form \samp{\var{type}/\var{subtype}})
-as specified in the \mailheader{Content-Type} header. If no such
-header exists, return \code{'text/plain'}. The type is converted to
-lower case.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getmaintype}{}
-Return the main type as specified in the \mailheader{Content-Type}
-header. If no such header exists, return \code{'text'}. The main
-type is converted to lower case.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getsubtype}{}
-Return the subtype as specified in the \mailheader{Content-Type}
-header. If no such header exists, return \code{'plain'}. The subtype
-is converted to lower case.
-\end{methoddesc}
diff --git a/Doc/lib/libmimetypes.tex b/Doc/lib/libmimetypes.tex
deleted file mode 100644
index af99f08..0000000
--- a/Doc/lib/libmimetypes.tex
+++ /dev/null
@@ -1,226 +0,0 @@
-\section{\module{mimetypes} ---
- Map filenames to MIME types}
-
-\declaremodule{standard}{mimetypes}
-\modulesynopsis{Mapping of filename extensions to MIME types.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-\indexii{MIME}{content type}
-
-The \module{mimetypes} module converts between a filename or URL and
-the MIME type associated with the filename extension. Conversions are
-provided from filename to MIME type and from MIME type to filename
-extension; encodings are not supported for the latter conversion.
-
-The module provides one class and a number of convenience functions.
-The functions are the normal interface to this module, but some
-applications may be interested in the class as well.
-
-The functions described below provide the primary interface for this
-module. If the module has not been initialized, they will call
-\function{init()} if they rely on the information \function{init()}
-sets up.
-
-
-\begin{funcdesc}{guess_type}{filename\optional{, strict}}
-Guess the type of a file based on its filename or URL, given by
-\var{filename}. The return value is a tuple \code{(\var{type},
-\var{encoding})} where \var{type} is \code{None} if the type can't be
-guessed (missing or unknown suffix) or a string of the form
-\code{'\var{type}/\var{subtype}'}, usable for a MIME
-\mailheader{content-type} header\indexii{MIME}{headers}.
-
-\var{encoding} is \code{None} for no encoding or the name of the
-program used to encode (e.g. \program{compress} or \program{gzip}).
-The encoding is suitable for use as a \mailheader{Content-Encoding}
-header, \emph{not} as a \mailheader{Content-Transfer-Encoding} header.
-The mappings are table driven. Encoding suffixes are case sensitive;
-type suffixes are first tried case sensitively, then case
-insensitively.
-
-Optional \var{strict} is a flag specifying whether the list of known
-MIME types is limited to only the official types \ulink{registered
-with IANA}{http://www.isi.edu/in-notes/iana/assignments/media-types}
-are recognized. When \var{strict} is true (the default), only the
-IANA types are supported; when \var{strict} is false, some additional
-non-standard but commonly used MIME types are also recognized.
-\end{funcdesc}
-
-\begin{funcdesc}{guess_all_extensions}{type\optional{, strict}}
-Guess the extensions for a file based on its MIME type, given by
-\var{type}.
-The return value is a list of strings giving all possible filename extensions,
-including the leading dot (\character{.}). The extensions are not guaranteed
-to have been associated with any particular data stream, but would be mapped
-to the MIME type \var{type} by \function{guess_type()}.
-
-Optional \var{strict} has the same meaning as with the
-\function{guess_type()} function.
-\end{funcdesc}
-
-
-\begin{funcdesc}{guess_extension}{type\optional{, strict}}
-Guess the extension for a file based on its MIME type, given by
-\var{type}.
-The return value is a string giving a filename extension, including the
-leading dot (\character{.}). The extension is not guaranteed to have been
-associated with any particular data stream, but would be mapped to the
-MIME type \var{type} by \function{guess_type()}. If no extension can
-be guessed for \var{type}, \code{None} is returned.
-
-Optional \var{strict} has the same meaning as with the
-\function{guess_type()} function.
-\end{funcdesc}
-
-
-Some additional functions and data items are available for controlling
-the behavior of the module.
-
-
-\begin{funcdesc}{init}{\optional{files}}
-Initialize the internal data structures. If given, \var{files} must
-be a sequence of file names which should be used to augment the
-default type map. If omitted, the file names to use are taken from
-\constant{knownfiles}. Each file named in \var{files} or
-\constant{knownfiles} takes precedence over those named before it.
-Calling \function{init()} repeatedly is allowed.
-\end{funcdesc}
-
-\begin{funcdesc}{read_mime_types}{filename}
-Load the type map given in the file \var{filename}, if it exists. The
-type map is returned as a dictionary mapping filename extensions,
-including the leading dot (\character{.}), to strings of the form
-\code{'\var{type}/\var{subtype}'}. If the file \var{filename} does
-not exist or cannot be read, \code{None} is returned.
-\end{funcdesc}
-
-
-\begin{funcdesc}{add_type}{type, ext\optional{, strict}}
-Add a mapping from the mimetype \var{type} to the extension \var{ext}.
-When the extension is already known, the new type will replace the old
-one. When the type is already known the extension will be added
-to the list of known extensions.
-
-When \var{strict} is the mapping will added to the official
-MIME types, otherwise to the non-standard ones.
-\end{funcdesc}
-
-
-\begin{datadesc}{inited}
-Flag indicating whether or not the global data structures have been
-initialized. This is set to true by \function{init()}.
-\end{datadesc}
-
-\begin{datadesc}{knownfiles}
-List of type map file names commonly installed. These files are
-typically named \file{mime.types} and are installed in different
-locations by different packages.\index{file!mime.types}
-\end{datadesc}
-
-\begin{datadesc}{suffix_map}
-Dictionary mapping suffixes to suffixes. This is used to allow
-recognition of encoded files for which the encoding and the type are
-indicated by the same extension. For example, the \file{.tgz}
-extension is mapped to \file{.tar.gz} to allow the encoding and type
-to be recognized separately.
-\end{datadesc}
-
-\begin{datadesc}{encodings_map}
-Dictionary mapping filename extensions to encoding types.
-\end{datadesc}
-
-\begin{datadesc}{types_map}
-Dictionary mapping filename extensions to MIME types.
-\end{datadesc}
-
-\begin{datadesc}{common_types}
-Dictionary mapping filename extensions to non-standard, but commonly
-found MIME types.
-\end{datadesc}
-
-
-The \class{MimeTypes} class may be useful for applications which may
-want more than one MIME-type database:
-
-\begin{classdesc}{MimeTypes}{\optional{filenames}}
- This class represents a MIME-types database. By default, it
- provides access to the same database as the rest of this module.
- The initial database is a copy of that provided by the module, and
- may be extended by loading additional \file{mime.types}-style files
- into the database using the \method{read()} or \method{readfp()}
- methods. The mapping dictionaries may also be cleared before
- loading additional data if the default data is not desired.
-
- The optional \var{filenames} parameter can be used to cause
- additional files to be loaded ``on top'' of the default database.
-
- \versionadded{2.2}
-\end{classdesc}
-
-An example usage of the module:
-
-\begin{verbatim}
->>> import mimetypes
->>> mimetypes.init()
->>> mimetypes.knownfiles
-['/etc/mime.types', '/etc/httpd/mime.types', ... ]
->>> mimetypes.suffix_map['.tgz']
-'.tar.gz'
->>> mimetypes.encodings_map['.gz']
-'gzip'
->>> mimetypes.types_map['.tgz']
-'application/x-tar-gz'
-\end{verbatim}
-
-\subsection{MimeTypes Objects \label{mimetypes-objects}}
-
-\class{MimeTypes} instances provide an interface which is very like
-that of the \refmodule{mimetypes} module.
-
-\begin{memberdesc}[MimeTypes]{suffix_map}
- Dictionary mapping suffixes to suffixes. This is used to allow
- recognition of encoded files for which the encoding and the type are
- indicated by the same extension. For example, the \file{.tgz}
- extension is mapped to \file{.tar.gz} to allow the encoding and type
- to be recognized separately. This is initially a copy of the global
- \code{suffix_map} defined in the module.
-\end{memberdesc}
-
-\begin{memberdesc}[MimeTypes]{encodings_map}
- Dictionary mapping filename extensions to encoding types. This is
- initially a copy of the global \code{encodings_map} defined in the
- module.
-\end{memberdesc}
-
-\begin{memberdesc}[MimeTypes]{types_map}
- Dictionary mapping filename extensions to MIME types. This is
- initially a copy of the global \code{types_map} defined in the
- module.
-\end{memberdesc}
-
-\begin{memberdesc}[MimeTypes]{common_types}
- Dictionary mapping filename extensions to non-standard, but commonly
- found MIME types. This is initially a copy of the global
- \code{common_types} defined in the module.
-\end{memberdesc}
-
-\begin{methoddesc}[MimeTypes]{guess_extension}{type\optional{, strict}}
- Similar to the \function{guess_extension()} function, using the
- tables stored as part of the object.
-\end{methoddesc}
-
-\begin{methoddesc}[MimeTypes]{guess_type}{url\optional{, strict}}
- Similar to the \function{guess_type()} function, using the tables
- stored as part of the object.
-\end{methoddesc}
-
-\begin{methoddesc}[MimeTypes]{read}{path}
- Load MIME information from a file named \var{path}. This uses
- \method{readfp()} to parse the file.
-\end{methoddesc}
-
-\begin{methoddesc}[MimeTypes]{readfp}{file}
- Load MIME type information from an open file. The file must have
- the format of the standard \file{mime.types} files.
-\end{methoddesc}
diff --git a/Doc/lib/libmisc.tex b/Doc/lib/libmisc.tex
deleted file mode 100644
index 6f79eda..0000000
--- a/Doc/lib/libmisc.tex
+++ /dev/null
@@ -1,7 +0,0 @@
-\chapter{Miscellaneous Services}
-\label{misc}
-
-The modules described in this chapter provide miscellaneous services
-that are available in all Python versions. Here's an overview:
-
-\localmoduletable
diff --git a/Doc/lib/libmm.tex b/Doc/lib/libmm.tex
deleted file mode 100644
index 22c14b4..0000000
--- a/Doc/lib/libmm.tex
+++ /dev/null
@@ -1,8 +0,0 @@
-\chapter{Multimedia Services}
-\label{mmedia}
-
-The modules described in this chapter implement various algorithms or
-interfaces that are mainly useful for multimedia applications. They
-are available at the discretion of the installation. Here's an overview:
-
-\localmoduletable
diff --git a/Doc/lib/libmmap.tex b/Doc/lib/libmmap.tex
deleted file mode 100644
index 345aeea..0000000
--- a/Doc/lib/libmmap.tex
+++ /dev/null
@@ -1,171 +0,0 @@
-\section{\module{mmap} ---
-Memory-mapped file support}
-
-\declaremodule{builtin}{mmap}
-\modulesynopsis{Interface to memory-mapped files for \UNIX\ and Windows.}
-
-Memory-mapped file objects behave like both strings and like
-file objects. Unlike normal string objects, however, these are
-mutable. You can use mmap objects in most places where strings
-are expected; for example, you can use the \module{re} module to
-search through a memory-mapped file. Since they're mutable, you can
-change a single character by doing \code{obj[\var{index}] = 'a'}, or
-change a substring by assigning to a slice:
-\code{obj[\var{i1}:\var{i2}] = '...'}. You can also read and write
-data starting at the current file position, and \method{seek()}
-through the file to different positions.
-
-A memory-mapped file is created by the \function{mmap()} function,
-which is different on \UNIX{} and on Windows. In either case you must
-provide a file descriptor for a file opened for update.
-If you wish to map an existing Python file object, use its
-\method{fileno()} method to obtain the correct value for the
-\var{fileno} parameter. Otherwise, you can open the file using the
-\function{os.open()} function, which returns a file descriptor
-directly (the file still needs to be closed when done).
-
-For both the \UNIX{} and Windows versions of the function,
-\var{access} may be specified as an optional keyword parameter.
-\var{access} accepts one of three values: \constant{ACCESS_READ},
-\constant{ACCESS_WRITE}, or \constant{ACCESS_COPY} to specify
-readonly, write-through or copy-on-write memory respectively.
-\var{access} can be used on both \UNIX{} and Windows. If
-\var{access} is not specified, Windows mmap returns a write-through
-mapping. The initial memory values for all three access types are
-taken from the specified file. Assignment to an
-\constant{ACCESS_READ} memory map raises a \exception{TypeError}
-exception. Assignment to an \constant{ACCESS_WRITE} memory map
-affects both memory and the underlying file. Assignment to an
-\constant{ACCESS_COPY} memory map affects memory but does not update
-the underlying file. \versionchanged[To map anonymous memory,
--1 should be passed as the fileno along with the length]{2.5}
-
-\begin{funcdesc}{mmap}{fileno, length\optional{, tagname\optional{, access}}}
- \strong{(Windows version)} Maps \var{length} bytes from the file
- specified by the file handle \var{fileno}, and returns a mmap
- object. If \var{length} is larger than the current size of the file,
- the file is extended to contain \var{length} bytes. If \var{length}
- is \code{0}, the maximum length of the map is the current size
- of the file, except that if the file is empty Windows raises an
- exception (you cannot create an empty mapping on Windows).
-
- \var{tagname}, if specified and not \code{None}, is a string giving
- a tag name for the mapping. Windows allows you to have many
- different mappings against the same file. If you specify the name
- of an existing tag, that tag is opened, otherwise a new tag of this
- name is created. If this parameter is omitted or \code{None}, the
- mapping is created without a name. Avoiding the use of the tag
- parameter will assist in keeping your code portable between \UNIX{}
- and Windows.
-\end{funcdesc}
-
-\begin{funcdescni}{mmap}{fileno, length\optional{, flags\optional{,
- prot\optional{, access}}}}
- \strong{(\UNIX{} version)} Maps \var{length} bytes from the file
- specified by the file descriptor \var{fileno}, and returns a mmap
- object. If \var{length} is \code{0}, the maximum length of the map
- will be the current size of the file when \function{mmap()} is
- called.
-
- \var{flags} specifies the nature of the mapping.
- \constant{MAP_PRIVATE} creates a private copy-on-write mapping, so
- changes to the contents of the mmap object will be private to this
- process, and \constant{MAP_SHARED} creates a mapping that's shared
- with all other processes mapping the same areas of the file. The
- default value is \constant{MAP_SHARED}.
-
- \var{prot}, if specified, gives the desired memory protection; the
- two most useful values are \constant{PROT_READ} and
- \constant{PROT_WRITE}, to specify that the pages may be read or
- written. \var{prot} defaults to \constant{PROT_READ | PROT_WRITE}.
-
- \var{access} may be specified in lieu of \var{flags} and \var{prot}
- as an optional keyword parameter. It is an error to specify both
- \var{flags}, \var{prot} and \var{access}. See the description of
- \var{access} above for information on how to use this parameter.
-\end{funcdescni}
-
-
-Memory-mapped file objects support the following methods:
-
-
-\begin{methoddesc}[mmap]{close}{}
- Close the file. Subsequent calls to other methods of the object
- will result in an exception being raised.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{find}{string\optional{, start}}
- Returns the lowest index in the object where the substring
- \var{string} is found. Returns \code{-1} on failure. \var{start}
- is the index at which the search begins, and defaults to zero.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{flush}{\optional{offset, size}}
- Flushes changes made to the in-memory copy of a file back to disk.
- Without use of this call there is no guarantee that changes are
- written back before the object is destroyed. If \var{offset} and
- \var{size} are specified, only changes to the given range of bytes
- will be flushed to disk; otherwise, the whole extent of the mapping
- is flushed.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{move}{\var{dest}, \var{src}, \var{count}}
- Copy the \var{count} bytes starting at offset \var{src} to the
- destination index \var{dest}. If the mmap was created with
- \constant{ACCESS_READ}, then calls to move will throw a
- \exception{TypeError} exception.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{read}{\var{num}}
- Return a string containing up to \var{num} bytes starting from the
- current file position; the file position is updated to point after the
- bytes that were returned.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{read_byte}{}
- Returns a string of length 1 containing the character at the current
- file position, and advances the file position by 1.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{readline}{}
- Returns a single line, starting at the current file position and up to
- the next newline.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{resize}{\var{newsize}}
- Resizes the map and the underlying file, if any.
- If the mmap was created with \constant{ACCESS_READ} or
- \constant{ACCESS_COPY}, resizing the map will throw a \exception{TypeError} exception.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{seek}{pos\optional{, whence}}
- Set the file's current position. \var{whence} argument is optional
- and defaults to \code{os.SEEK_SET} or \code{0} (absolute file
- positioning); other values are \code{os.SEEK_CUR} or \code{1} (seek
- relative to the current position) and \code{os.SEEK_END} or \code{2}
- (seek relative to the file's end).
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{size}{}
- Return the length of the file, which can be larger than the size of
- the memory-mapped area.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{tell}{}
- Returns the current position of the file pointer.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{write}{\var{string}}
- Write the bytes in \var{string} into memory at the current position
- of the file pointer; the file position is updated to point after the
- bytes that were written. If the mmap was created with
- \constant{ACCESS_READ}, then writing to it will throw a
- \exception{TypeError} exception.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{write_byte}{\var{byte}}
- Write the single-character string \var{byte} into memory at the
- current position of the file pointer; the file position is advanced
- by \code{1}. If the mmap was created with \constant{ACCESS_READ},
- then writing to it will throw a \exception{TypeError} exception.
-\end{methoddesc}
diff --git a/Doc/lib/libmodulefinder.tex b/Doc/lib/libmodulefinder.tex
deleted file mode 100644
index 5fb9e8e..0000000
--- a/Doc/lib/libmodulefinder.tex
+++ /dev/null
@@ -1,51 +0,0 @@
-\section{\module{modulefinder} ---
- Find modules used by a script}
-\sectionauthor{A.M. Kuchling}{amk@amk.ca}
-
-\declaremodule{standard}{modulefinder}
-\modulesynopsis{Find modules used by a script.}
-
-\versionadded{2.3}
-
-This module provides a \class{ModuleFinder} class that can be used to
-determine the set of modules imported by a script.
-\code{modulefinder.py} can also be run as a script, giving the
-filename of a Python script as its argument, after which a report of
-the imported modules will be printed.
-
-\begin{funcdesc}{AddPackagePath}{pkg_name, path}
-Record that the package named \var{pkg_name} can be found in the specified \var{path}.
-\end{funcdesc}
-
-\begin{funcdesc}{ReplacePackage}{oldname, newname}
-Allows specifying that the module named \var{oldname} is in fact
-the package named \var{newname}. The most common usage would be
-to handle how the \module{_xmlplus} package replaces the \module{xml}
-package.
-\end{funcdesc}
-
-\begin{classdesc}{ModuleFinder}{\optional{path=None, debug=0, excludes=[], replace_paths=[]}}
-
-This class provides \method{run_script()} and \method{report()}
-methods to determine the set of modules imported by a script.
-\var{path} can be a list of directories to search for modules; if not
-specified, \code{sys.path} is used.
-\var{debug} sets the debugging level; higher values make the class print
-debugging messages about what it's doing.
-\var{excludes} is a list of module names to exclude from the analysis.
-\var{replace_paths} is a list of \code{(\var{oldpath}, \var{newpath})}
-tuples that will be replaced in module paths.
-\end{classdesc}
-
-\begin{methoddesc}[ModuleFinder]{report}{}
-Print a report to standard output that lists the modules imported by the script
-and their
-paths, as well as modules that are missing or seem to be missing.
-\end{methoddesc}
-
-\begin{methoddesc}[ModuleFinder]{run_script}{pathname}
-Analyze the contents of the \var{pathname} file, which must contain
-Python code.
-\end{methoddesc}
-
-
diff --git a/Doc/lib/libmsilib.tex b/Doc/lib/libmsilib.tex
deleted file mode 100644
index 075103a..0000000
--- a/Doc/lib/libmsilib.tex
+++ /dev/null
@@ -1,485 +0,0 @@
-\section{\module{msilib} ---
- Read and write Microsoft Installer files}
-
-\declaremodule{standard}{msilib}
- \platform{Windows}
-\modulesynopsis{Creation of Microsoft Installer files, and CAB files.}
-\moduleauthor{Martin v. L\"owis}{martin@v.loewis.de}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\index{msi}
-
-\versionadded{2.5}
-
-The \module{msilib} supports the creation of Microsoft Installer
-(\code{.msi}) files. Because these files often contain an embedded
-``cabinet'' file (\code{.cab}), it also exposes an API to create
-CAB files. Support for reading \code{.cab} files is currently not
-implemented; read support for the \code{.msi} database is possible.
-
-This package aims to provide complete access to all tables in an
-\code{.msi} file, therefore, it is a fairly low-level API. Two
-primary applications of this package are the \module{distutils}
-command \code{bdist_msi}, and the creation of Python installer
-package itself (although that currently uses a different version
-of \code{msilib}).
-
-The package contents can be roughly split into four parts:
-low-level CAB routines, low-level MSI routines, higher-level
-MSI routines, and standard table structures.
-
-\begin{funcdesc}{FCICreate}{cabname, files}
- Create a new CAB file named \var{cabname}. \var{files} must
- be a list of tuples, each containing the name of the file on
- disk, and the name of the file inside the CAB file.
-
- The files are added to the CAB file in the order they appear
- in the list. All files are added into a single CAB file,
- using the MSZIP compression algorithm.
-
- Callbacks to Python for the various steps of MSI creation
- are currently not exposed.
-\end{funcdesc}
-
-\begin{funcdesc}{UUIDCreate}{}
- Return the string representation of a new unique identifier.
- This wraps the Windows API functions \cfunction{UuidCreate} and
- \cfunction{UuidToString}.
-\end{funcdesc}
-
-\begin{funcdesc}{OpenDatabase}{path, persist}
- Return a new database object by calling MsiOpenDatabase.
- \var{path} is the file name of the
- MSI file; \var{persist} can be one of the constants
- \code{MSIDBOPEN_CREATEDIRECT}, \code{MSIDBOPEN_CREATE},
- \code{MSIDBOPEN_DIRECT}, \code{MSIDBOPEN_READONLY}, or
- \code{MSIDBOPEN_TRANSACT}, and may include the flag
- \code{MSIDBOPEN_PATCHFILE}. See the Microsoft documentation for
- the meaning of these flags; depending on the flags,
- an existing database is opened, or a new one created.
-\end{funcdesc}
-
-\begin{funcdesc}{CreateRecord}{count}
- Return a new record object by calling \cfunction{MSICreateRecord}.
- \var{count} is the number of fields of the record.
-\end{funcdesc}
-
-\begin{funcdesc}{init_database}{name, schema, ProductName, ProductCode, ProductVersion, Manufacturer}
- Create and return a new database \var{name}, initialize it
- with \var{schema}, and set the properties \var{ProductName},
- \var{ProductCode}, \var{ProductVersion}, and \var{Manufacturer}.
-
- \var{schema} must be a module object containing \code{tables} and
- \code{_Validation_records} attributes; typically,
- \module{msilib.schema} should be used.
-
- The database will contain just the schema and the validation
- records when this function returns.
-\end{funcdesc}
-
-\begin{funcdesc}{add_data}{database, records}
- Add all \var{records} to \var{database}. \var{records} should
- be a list of tuples, each one containing all fields of a record
- according to the schema of the table. For optional fields,
- \code{None} can be passed.
-
- Field values can be int or long numbers, strings, or instances
- of the Binary class.
-\end{funcdesc}
-
-\begin{classdesc}{Binary}{filename}
- Represents entries in the Binary table; inserting such
- an object using \function{add_data} reads the file named
- \var{filename} into the table.
-\end{classdesc}
-
-\begin{funcdesc}{add_tables}{database, module}
- Add all table content from \var{module} to \var{database}.
- \var{module} must contain an attribute \var{tables}
- listing all tables for which content should be added,
- and one attribute per table that has the actual content.
-
- This is typically used to install the sequence tables.
-\end{funcdesc}
-
-\begin{funcdesc}{add_stream}{database, name, path}
- Add the file \var{path} into the \code{_Stream} table
- of \var{database}, with the stream name \var{name}.
-\end{funcdesc}
-
-\begin{funcdesc}{gen_uuid}{}
- Return a new UUID, in the format that MSI typically
- requires (i.e. in curly braces, and with all hexdigits
- in upper-case).
-\end{funcdesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/devnotes/winprog/fcicreate.asp]{FCICreateFile}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rpc/rpc/uuidcreate.asp]{UuidCreate}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rpc/rpc/uuidtostring.asp]{UuidToString}{}
-\end{seealso}
-
-\subsection{Database Objects\label{database-objects}}
-
-\begin{methoddesc}[Database]{OpenView}{sql}
- Return a view object, by calling \cfunction{MSIDatabaseOpenView}.
- \var{sql} is the SQL statement to execute.
-\end{methoddesc}
-
-\begin{methoddesc}[Database]{Commit}{}
- Commit the changes pending in the current transaction,
- by calling \cfunction{MSIDatabaseCommit}.
-\end{methoddesc}
-
-\begin{methoddesc}[Database]{GetSummaryInformation}{count}
- Return a new summary information object, by calling
- \cfunction{MsiGetSummaryInformation}. \var{count} is the maximum number of
- updated values.
-\end{methoddesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiopenview.asp]{MSIOpenView}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msidatabasecommit.asp]{MSIDatabaseCommit}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msigetsummaryinformation.asp]{MSIGetSummaryInformation}{}
-\end{seealso}
-
-\subsection{View Objects\label{view-objects}}
-
-\begin{methoddesc}[View]{Execute}{\optional{params=None}}
- Execute the SQL query of the view, through \cfunction{MSIViewExecute}.
- \var{params} is an optional record describing actual values
- of the parameter tokens in the query.
-\end{methoddesc}
-
-\begin{methoddesc}[View]{GetColumnInfo}{kind}
- Return a record describing the columns of the view, through
- calling \cfunction{MsiViewGetColumnInfo}. \var{kind} can be either
- \code{MSICOLINFO_NAMES} or \code{MSICOLINFO_TYPES}.
-\end{methoddesc}
-
-\begin{methoddesc}[View]{Fetch}{}
- Return a result record of the query, through calling
- \cfunction{MsiViewFetch}.
-\end{methoddesc}
-
-\begin{methoddesc}[View]{Modify}{kind, data}
- Modify the view, by calling \cfunction{MsiViewModify}. \var{kind}
- can be one of \code{MSIMODIFY_SEEK}, \code{MSIMODIFY_REFRESH},
- \code{MSIMODIFY_INSERT}, \code{MSIMODIFY_UPDATE}, \code{MSIMODIFY_ASSIGN},
- \code{MSIMODIFY_REPLACE}, \code{MSIMODIFY_MERGE}, \code{MSIMODIFY_DELETE},
- \code{MSIMODIFY_INSERT_TEMPORARY}, \code{MSIMODIFY_VALIDATE},
- \code{MSIMODIFY_VALIDATE_NEW}, \code{MSIMODIFY_VALIDATE_FIELD}, or
- \code{MSIMODIFY_VALIDATE_DELETE}.
-
- \var{data} must be a record describing the new data.
-\end{methoddesc}
-
-\begin{methoddesc}[View]{Close}{}
- Close the view, through \cfunction{MsiViewClose}.
-\end{methoddesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewexecute.asp]{MsiViewExecute}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewgetcolumninfo.asp]{MSIViewGetColumnInfo}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewfetch.asp]{MsiViewFetch}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewmodify.asp]{MsiViewModify}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewclose.asp]{MsiViewClose}{}
-\end{seealso}
-
-\subsection{Summary Information Objects\label{summary-objects}}
-
-\begin{methoddesc}[SummaryInformation]{GetProperty}{field}
- Return a property of the summary, through \cfunction{MsiSummaryInfoGetProperty}.
- \var{field} is the name of the property, and can be one of the
- constants
- \code{PID_CODEPAGE}, \code{PID_TITLE}, \code{PID_SUBJECT},
- \code{PID_AUTHOR}, \code{PID_KEYWORDS}, \code{PID_COMMENTS},
- \code{PID_TEMPLATE}, \code{PID_LASTAUTHOR}, \code{PID_REVNUMBER},
- \code{PID_LASTPRINTED}, \code{PID_CREATE_DTM}, \code{PID_LASTSAVE_DTM},
- \code{PID_PAGECOUNT}, \code{PID_WORDCOUNT}, \code{PID_CHARCOUNT},
- \code{PID_APPNAME}, or \code{PID_SECURITY}.
-\end{methoddesc}
-
-\begin{methoddesc}[SummaryInformation]{GetPropertyCount}{}
- Return the number of summary properties, through
- \cfunction{MsiSummaryInfoGetPropertyCount}.
-\end{methoddesc}
-
-\begin{methoddesc}[SummaryInformation]{SetProperty}{field, value}
- Set a property through \cfunction{MsiSummaryInfoSetProperty}. \var{field}
- can have the same values as in \method{GetProperty}, \var{value}
- is the new value of the property. Possible value types are integer
- and string.
-\end{methoddesc}
-
-\begin{methoddesc}[SummaryInformation]{Persist}{}
- Write the modified properties to the summary information stream,
- using \cfunction{MsiSummaryInfoPersist}.
-\end{methoddesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfogetproperty.asp]{MsiSummaryInfoGetProperty}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfogetpropertycount.asp]{MsiSummaryInfoGetPropertyCount}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfosetproperty.asp]{MsiSummaryInfoSetProperty}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfopersist.asp]{MsiSummaryInfoPersist}{}
-\end{seealso}
-
-\subsection{Record Objects\label{record-objects}}
-
-\begin{methoddesc}[Record]{GetFieldCount}{}
- Return the number of fields of the record, through \cfunction{MsiRecordGetFieldCount}.
-\end{methoddesc}
-
-\begin{methoddesc}[Record]{SetString}{field, value}
- Set \var{field} to \var{value} through \cfunction{MsiRecordSetString}.
- \var{field} must be an integer; \var{value} a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Record]{SetStream}{field, value}
- Set \var{field} to the contents of the file named \var{value},
- through \cfunction{MsiRecordSetStream}.
- \var{field} must be an integer; \var{value} a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Record]{SetInteger}{field, value}
- Set \var{field} to \var{value} through \cfunction{MsiRecordSetInteger}.
- Both \var{field} and \var{value} must be an integer.
-\end{methoddesc}
-
-\begin{methoddesc}[Record]{ClearData}{}
- Set all fields of the record to 0, through \cfunction{MsiRecordClearData}.
-\end{methoddesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordgetfieldcount.asp]{MsiRecordGetFieldCount}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetstring.asp]{MsiRecordSetString}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetstream.asp]{MsiRecordSetStream}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetinteger.asp]{MsiRecordSetInteger}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordclear.asp]{MsiRecordClear}{}
-\end{seealso}
-
-\subsection{Errors\label{msi-errors}}
-
-All wrappers around MSI functions raise \exception{MsiError};
-the string inside the exception will contain more detail.
-
-\subsection{CAB Objects\label{cab}}
-
-\begin{classdesc}{CAB}{name}
- The class \class{CAB} represents a CAB file. During MSI construction,
- files will be added simultaneously to the \code{Files} table, and
- to a CAB file. Then, when all files have been added, the CAB file
- can be written, then added to the MSI file.
-
- \var{name} is the name of the CAB file in the MSI file.
-\end{classdesc}
-
-\begin{methoddesc}[CAB]{append}{full, file, logical}
- Add the file with the pathname \var{full} to the CAB file,
- under the name \var{logical}. If there is already a file
- named \var{logical}, a new file name is created.
-
- Return the index of the file in the CAB file, and the
- new name of the file inside the CAB file.
-\end{methoddesc}
-
-\begin{methoddesc}[CAB]{commit}{database}
- Generate a CAB file, add it as a stream to the MSI file,
- put it into the \code{Media} table, and remove the generated
- file from the disk.
-\end{methoddesc}
-
-\subsection{Directory Objects\label{msi-directory}}
-
-\begin{classdesc}{Directory}{database, cab, basedir, physical,
- logical, default, component, \optional{componentflags}}
- Create a new directory in the Directory table. There is a current
- component at each point in time for the directory, which is either
- explicitly created through \method{start_component}, or implicitly when files
- are added for the first time. Files are added into the current
- component, and into the cab file. To create a directory, a base
- directory object needs to be specified (can be \code{None}), the path to
- the physical directory, and a logical directory name. \var{default}
- specifies the DefaultDir slot in the directory table. \var{componentflags}
- specifies the default flags that new components get.
-\end{classdesc}
-
-\begin{methoddesc}[Directory]{start_component}{\optional{component\optional{,
- feature\optional{, flags\optional{, keyfile\optional{, uuid}}}}}}
- Add an entry to the Component table, and make this component the
- current component for this directory. If no component name is given, the
- directory name is used. If no \var{feature} is given, the current feature
- is used. If no \var{flags} are given, the directory's default flags are
- used. If no \var{keyfile} is given, the KeyPath is left null in the
- Component table.
-\end{methoddesc}
-
-\begin{methoddesc}[Directory]{add_file}{file\optional{, src\optional{,
- version\optional{, language}}}}
- Add a file to the current component of the directory, starting a new
- one if there is no current component. By default, the file name
- in the source and the file table will be identical. If the \var{src} file
- is specified, it is interpreted relative to the current
- directory. Optionally, a \var{version} and a \var{language} can be specified for
- the entry in the File table.
-\end{methoddesc}
-
-\begin{methoddesc}[Directory]{glob}{pattern\optional{, exclude}}
- Add a list of files to the current component as specified in the glob
- pattern. Individual files can be excluded in the \var{exclude} list.
-\end{methoddesc}
-
-\begin{methoddesc}[Directory]{remove_pyc}{}
- Remove \code{.pyc}/\code{.pyo} files on uninstall.
-\end{methoddesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/directory_table.asp]{Directory Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/file_table.asp]{File Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/component_table.asp]{Component Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/featurecomponents_table.asp]{FeatureComponents Table}{}
-\end{seealso}
-
-
-\subsection{Features\label{features}}
-
-\begin{classdesc}{Feature}{database, id, title, desc, display\optional{,
- level=1\optional{, parent\optional{, directory\optional{,
- attributes=0}}}}}
-
- Add a new record to the \code{Feature} table, using the values
- \var{id}, \var{parent.id}, \var{title}, \var{desc}, \var{display},
- \var{level}, \var{directory}, and \var{attributes}. The resulting
- feature object can be passed to the \method{start_component} method
- of \class{Directory}.
-\end{classdesc}
-
-\begin{methoddesc}[Feature]{set_current}{}
- Make this feature the current feature of \module{msilib}.
- New components are automatically added to the default feature,
- unless a feature is explicitly specified.
-\end{methoddesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/feature_table.asp]{Feature Table}{}
-\end{seealso}
-
-\subsection{GUI classes\label{msi-gui}}
-
-\module{msilib} provides several classes that wrap the GUI tables in
-an MSI database. However, no standard user interface is provided; use
-\module{bdist_msi} to create MSI files with a user-interface for
-installing Python packages.
-
-\begin{classdesc}{Control}{dlg, name}
- Base class of the dialog controls. \var{dlg} is the dialog object
- the control belongs to, and \var{name} is the control's name.
-\end{classdesc}
-
-\begin{methoddesc}[Control]{event}{event, argument\optional{,
- condition = ``1''\optional{, ordering}}}
-
- Make an entry into the \code{ControlEvent} table for this control.
-\end{methoddesc}
-
-\begin{methoddesc}[Control]{mapping}{event, attribute}
- Make an entry into the \code{EventMapping} table for this control.
-\end{methoddesc}
-
-\begin{methoddesc}[Control]{condition}{action, condition}
- Make an entry into the \code{ControlCondition} table for this control.
-\end{methoddesc}
-
-
-\begin{classdesc}{RadioButtonGroup}{dlg, name, property}
- Create a radio button control named \var{name}. \var{property}
- is the installer property that gets set when a radio button
- is selected.
-\end{classdesc}
-
-\begin{methoddesc}[RadioButtonGroup]{add}{name, x, y, width, height, text
- \optional{, value}}
- Add a radio button named \var{name} to the group, at the
- coordinates \var{x}, \var{y}, \var{width}, \var{height}, and
- with the label \var{text}. If \var{value} is omitted, it
- defaults to \var{name}.
-\end{methoddesc}
-
-\begin{classdesc}{Dialog}{db, name, x, y, w, h, attr, title, first,
- default, cancel}
- Return a new \class{Dialog} object. An entry in the \code{Dialog} table
- is made, with the specified coordinates, dialog attributes, title,
- name of the first, default, and cancel controls.
-\end{classdesc}
-
-\begin{methoddesc}[Dialog]{control}{name, type, x, y, width, height,
- attributes, property, text, control_next, help}
- Return a new \class{Control} object. An entry in the \code{Control} table
- is made with the specified parameters.
-
- This is a generic method; for specific types, specialized methods
- are provided.
-\end{methoddesc}
-
-
-\begin{methoddesc}[Dialog]{text}{name, x, y, width, height, attributes, text}
- Add and return a \code{Text} control.
-\end{methoddesc}
-
-\begin{methoddesc}[Dialog]{bitmap}{name, x, y, width, height, text}
- Add and return a \code{Bitmap} control.
-\end{methoddesc}
-
-\begin{methoddesc}[Dialog]{line}{name, x, y, width, height}
- Add and return a \code{Line} control.
-\end{methoddesc}
-
-\begin{methoddesc}[Dialog]{pushbutton}{name, x, y, width, height, attributes,
- text, next_control}
- Add and return a \code{PushButton} control.
-\end{methoddesc}
-
-\begin{methoddesc}[Dialog]{radiogroup}{name, x, y, width, height,
- attributes, property, text, next_control}
- Add and return a \code{RadioButtonGroup} control.
-\end{methoddesc}
-
-\begin{methoddesc}[Dialog]{checkbox}{name, x, y, width, height,
- attributes, property, text, next_control}
- Add and return a \code{CheckBox} control.
-\end{methoddesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/dialog_table.asp]{Dialog Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/control_table.asp]{Control Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controls.asp]{Control Types}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controlcondition_table.asp]{ControlCondition Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controlevent_table.asp]{ControlEvent Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/eventmapping_table.asp]{EventMapping Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/radiobutton_table.asp]{RadioButton Table}{}
-\end{seealso}
-
-\subsection{Precomputed tables\label{msi-tables}}
-
-\module{msilib} provides a few subpackages that contain
-only schema and table definitions. Currently, these definitions
-are based on MSI version 2.0.
-
-\begin{datadesc}{schema}
- This is the standard MSI schema for MSI 2.0, with the
- \var{tables} variable providing a list of table definitions,
- and \var{_Validation_records} providing the data for
- MSI validation.
-\end{datadesc}
-
-\begin{datadesc}{sequence}
- This module contains table contents for the standard sequence
- tables: \var{AdminExecuteSequence}, \var{AdminUISequence},
- \var{AdvtExecuteSequence}, \var{InstallExecuteSequence}, and
- \var{InstallUISequence}.
-\end{datadesc}
-
-\begin{datadesc}{text}
- This module contains definitions for the UIText and ActionText
- tables, for the standard installer actions.
-\end{datadesc}
diff --git a/Doc/lib/libmsvcrt.tex b/Doc/lib/libmsvcrt.tex
deleted file mode 100644
index 3e4ce5a..0000000
--- a/Doc/lib/libmsvcrt.tex
+++ /dev/null
@@ -1,109 +0,0 @@
-\section{\module{msvcrt} --
- Useful routines from the MS V\Cpp\ runtime}
-
-\declaremodule{builtin}{msvcrt}
- \platform{Windows}
-\modulesynopsis{Miscellaneous useful routines from the MS V\Cpp\ runtime.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-These functions provide access to some useful capabilities on Windows
-platforms. Some higher-level modules use these functions to build the
-Windows implementations of their services. For example, the
-\refmodule{getpass} module uses this in the implementation of the
-\function{getpass()} function.
-
-Further documentation on these functions can be found in the Platform
-API documentation.
-
-
-\subsection{File Operations \label{msvcrt-files}}
-
-\begin{funcdesc}{locking}{fd, mode, nbytes}
- Lock part of a file based on file descriptor \var{fd} from the C
- runtime. Raises \exception{IOError} on failure. The locked region
- of the file extends from the current file position for \var{nbytes}
- bytes, and may continue beyond the end of the file. \var{mode} must
- be one of the \constant{LK_\var{*}} constants listed below.
- Multiple regions in a file may be locked at the same time, but may
- not overlap. Adjacent regions are not merged; they must be unlocked
- individually.
-\end{funcdesc}
-
-\begin{datadesc}{LK_LOCK}
-\dataline{LK_RLCK}
- Locks the specified bytes. If the bytes cannot be locked, the
- program immediately tries again after 1 second. If, after 10
- attempts, the bytes cannot be locked, \exception{IOError} is
- raised.
-\end{datadesc}
-
-\begin{datadesc}{LK_NBLCK}
-\dataline{LK_NBRLCK}
- Locks the specified bytes. If the bytes cannot be locked,
- \exception{IOError} is raised.
-\end{datadesc}
-
-\begin{datadesc}{LK_UNLCK}
- Unlocks the specified bytes, which must have been previously locked.
-\end{datadesc}
-
-\begin{funcdesc}{setmode}{fd, flags}
- Set the line-end translation mode for the file descriptor \var{fd}.
- To set it to text mode, \var{flags} should be \constant{os.O_TEXT};
- for binary, it should be \constant{os.O_BINARY}.
-\end{funcdesc}
-
-\begin{funcdesc}{open_osfhandle}{handle, flags}
- Create a C runtime file descriptor from the file handle
- \var{handle}. The \var{flags} parameter should be a bit-wise OR of
- \constant{os.O_APPEND}, \constant{os.O_RDONLY}, and
- \constant{os.O_TEXT}. The returned file descriptor may be used as a
- parameter to \function{os.fdopen()} to create a file object.
-\end{funcdesc}
-
-\begin{funcdesc}{get_osfhandle}{fd}
- Return the file handle for the file descriptor \var{fd}. Raises
- \exception{IOError} if \var{fd} is not recognized.
-\end{funcdesc}
-
-
-\subsection{Console I/O \label{msvcrt-console}}
-
-\begin{funcdesc}{kbhit}{}
- Return true if a keypress is waiting to be read.
-\end{funcdesc}
-
-\begin{funcdesc}{getch}{}
- Read a keypress and return the resulting character. Nothing is
- echoed to the console. This call will block if a keypress is not
- already available, but will not wait for \kbd{Enter} to be pressed.
- If the pressed key was a special function key, this will return
- \code{'\e000'} or \code{'\e xe0'}; the next call will return the
- keycode. The \kbd{Control-C} keypress cannot be read with this
- function.
-\end{funcdesc}
-
-\begin{funcdesc}{getche}{}
- Similar to \function{getch()}, but the keypress will be echoed if it
- represents a printable character.
-\end{funcdesc}
-
-\begin{funcdesc}{putch}{char}
- Print the character \var{char} to the console without buffering.
-\end{funcdesc}
-
-\begin{funcdesc}{ungetch}{char}
- Cause the character \var{char} to be ``pushed back'' into the
- console buffer; it will be the next character read by
- \function{getch()} or \function{getche()}.
-\end{funcdesc}
-
-
-\subsection{Other Functions \label{msvcrt-other}}
-
-\begin{funcdesc}{heapmin}{}
- Force the \cfunction{malloc()} heap to clean itself up and return
- unused blocks to the operating system. This only works on Windows
- NT. On failure, this raises \exception{IOError}.
-\end{funcdesc}
diff --git a/Doc/lib/libmultifile.tex b/Doc/lib/libmultifile.tex
deleted file mode 100644
index f3f0af7..0000000
--- a/Doc/lib/libmultifile.tex
+++ /dev/null
@@ -1,175 +0,0 @@
-\section{\module{multifile} ---
- Support for files containing distinct parts}
-
-\declaremodule{standard}{multifile}
-\modulesynopsis{Support for reading files which contain distinct
- parts, such as some MIME data.}
-\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-
-\deprecated{2.5}{The \refmodule{email} package should be used in
- preference to the \module{multifile} module.
- This module is present only to maintain backward
- compatibility.}
-
-The \class{MultiFile} object enables you to treat sections of a text
-file as file-like input objects, with \code{''} being returned by
-\method{readline()} when a given delimiter pattern is encountered. The
-defaults of this class are designed to make it useful for parsing
-MIME multipart messages, but by subclassing it and overriding methods
-it can be easily adapted for more general use.
-
-\begin{classdesc}{MultiFile}{fp\optional{, seekable}}
-Create a multi-file. You must instantiate this class with an input
-object argument for the \class{MultiFile} instance to get lines from,
-such as a file object returned by \function{open()}.
-
-\class{MultiFile} only ever looks at the input object's
-\method{readline()}, \method{seek()} and \method{tell()} methods, and
-the latter two are only needed if you want random access to the
-individual MIME parts. To use \class{MultiFile} on a non-seekable
-stream object, set the optional \var{seekable} argument to false; this
-will prevent using the input object's \method{seek()} and
-\method{tell()} methods.
-\end{classdesc}
-
-It will be useful to know that in \class{MultiFile}'s view of the world, text
-is composed of three kinds of lines: data, section-dividers, and
-end-markers. MultiFile is designed to support parsing of
-messages that may have multiple nested message parts, each with its
-own pattern for section-divider and end-marker lines.
-
-\begin{seealso}
- \seemodule{email}{Comprehensive email handling package; supersedes
- the \module{multifile} module.}
-\end{seealso}
-
-
-\subsection{MultiFile Objects \label{MultiFile-objects}}
-
-A \class{MultiFile} instance has the following methods:
-
-\begin{methoddesc}[MultiFile]{readline}{str}
-Read a line. If the line is data (not a section-divider or end-marker
-or real EOF) return it. If the line matches the most-recently-stacked
-boundary, return \code{''} and set \code{self.last} to 1 or 0 according as
-the match is or is not an end-marker. If the line matches any other
-stacked boundary, raise an error. On encountering end-of-file on the
-underlying stream object, the method raises \exception{Error} unless
-all boundaries have been popped.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{readlines}{str}
-Return all lines remaining in this part as a list of strings.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{read}{}
-Read all lines, up to the next section. Return them as a single
-(multiline) string. Note that this doesn't take a size argument!
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{seek}{pos\optional{, whence}}
-Seek. Seek indices are relative to the start of the current section.
-The \var{pos} and \var{whence} arguments are interpreted as for a file
-seek.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{tell}{}
-Return the file position relative to the start of the current section.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{next}{}
-Skip lines to the next section (that is, read lines until a
-section-divider or end-marker has been consumed). Return true if
-there is such a section, false if an end-marker is seen. Re-enable
-the most-recently-pushed boundary.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{is_data}{str}
-Return true if \var{str} is data and false if it might be a section
-boundary. As written, it tests for a prefix other than \code{'-}\code{-'} at
-start of line (which all MIME boundaries have) but it is declared so
-it can be overridden in derived classes.
-
-Note that this test is used intended as a fast guard for the real
-boundary tests; if it always returns false it will merely slow
-processing, not cause it to fail.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{push}{str}
-Push a boundary string. When a decorated version of this boundary
-is found as an input line, it will be interpreted as a section-divider
-or end-marker (depending on the decoration, see \rfc{2045}). All subsequent
-reads will return the empty string to indicate end-of-file, until a
-call to \method{pop()} removes the boundary a or \method{next()} call
-reenables it.
-
-It is possible to push more than one boundary. Encountering the
-most-recently-pushed boundary will return EOF; encountering any other
-boundary will raise an error.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{pop}{}
-Pop a section boundary. This boundary will no longer be interpreted
-as EOF.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{section_divider}{str}
-Turn a boundary into a section-divider line. By default, this
-method prepends \code{'-}\code{-'} (which MIME section boundaries have) but
-it is declared so it can be overridden in derived classes. This
-method need not append LF or CR-LF, as comparison with the result
-ignores trailing whitespace.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{end_marker}{str}
-Turn a boundary string into an end-marker line. By default, this
-method prepends \code{'-}\code{-'} and appends \code{'-}\code{-'} (like a
-MIME-multipart end-of-message marker) but it is declared so it can be
-overridden in derived classes. This method need not append LF or
-CR-LF, as comparison with the result ignores trailing whitespace.
-\end{methoddesc}
-
-Finally, \class{MultiFile} instances have two public instance variables:
-
-\begin{memberdesc}[MultiFile]{level}
-Nesting depth of the current part.
-\end{memberdesc}
-
-\begin{memberdesc}[MultiFile]{last}
-True if the last end-of-file was for an end-of-message marker.
-\end{memberdesc}
-
-
-\subsection{\class{MultiFile} Example \label{multifile-example}}
-\sectionauthor{Skip Montanaro}{skip@mojam.com}
-
-\begin{verbatim}
-import mimetools
-import multifile
-import StringIO
-
-def extract_mime_part_matching(stream, mimetype):
- """Return the first element in a multipart MIME message on stream
- matching mimetype."""
-
- msg = mimetools.Message(stream)
- msgtype = msg.gettype()
- params = msg.getplist()
-
- data = StringIO.StringIO()
- if msgtype[:10] == "multipart/":
-
- file = multifile.MultiFile(stream)
- file.push(msg.getparam("boundary"))
- while file.next():
- submsg = mimetools.Message(file)
- try:
- data = StringIO.StringIO()
- mimetools.decode(file, data, submsg.getencoding())
- except ValueError:
- continue
- if submsg.gettype() == mimetype:
- break
- file.pop()
- return data.getvalue()
-\end{verbatim}
diff --git a/Doc/lib/libmutex.tex b/Doc/lib/libmutex.tex
deleted file mode 100644
index 8c35c96..0000000
--- a/Doc/lib/libmutex.tex
+++ /dev/null
@@ -1,57 +0,0 @@
-\section{\module{mutex} ---
- Mutual exclusion support}
-
-\declaremodule{standard}{mutex}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Lock and queue for mutual exclusion.}
-
-The \module{mutex} module defines a class that allows mutual-exclusion
-via acquiring and releasing locks. It does not require (or imply)
-threading or multi-tasking, though it could be useful for
-those purposes.
-
-The \module{mutex} module defines the following class:
-
-\begin{classdesc}{mutex}{}
-Create a new (unlocked) mutex.
-
-A mutex has two pieces of state --- a ``locked'' bit and a queue.
-When the mutex is not locked, the queue is empty.
-Otherwise, the queue contains zero or more
-\code{(\var{function}, \var{argument})} pairs
-representing functions (or methods) waiting to acquire the lock.
-When the mutex is unlocked while the queue is not empty,
-the first queue entry is removed and its
-\code{\var{function}(\var{argument})} pair called,
-implying it now has the lock.
-
-Of course, no multi-threading is implied -- hence the funny interface
-for \method{lock()}, where a function is called once the lock is
-acquired.
-\end{classdesc}
-
-
-\subsection{Mutex Objects \label{mutex-objects}}
-
-\class{mutex} objects have following methods:
-
-\begin{methoddesc}[mutex]{test}{}
-Check whether the mutex is locked.
-\end{methoddesc}
-
-\begin{methoddesc}[mutex]{testandset}{}
-``Atomic'' test-and-set, grab the lock if it is not set,
-and return \code{True}, otherwise, return \code{False}.
-\end{methoddesc}
-
-\begin{methoddesc}[mutex]{lock}{function, argument}
-Execute \code{\var{function}(\var{argument})}, unless the mutex is locked.
-In the case it is locked, place the function and argument on the queue.
-See \method{unlock} for explanation of when
-\code{\var{function}(\var{argument})} is executed in that case.
-\end{methoddesc}
-
-\begin{methoddesc}[mutex]{unlock}{}
-Unlock the mutex if queue is empty, otherwise execute the first element
-in the queue.
-\end{methoddesc}
diff --git a/Doc/lib/libnetrc.tex b/Doc/lib/libnetrc.tex
deleted file mode 100644
index f867b34..0000000
--- a/Doc/lib/libnetrc.tex
+++ /dev/null
@@ -1,68 +0,0 @@
-\section{\module{netrc} ---
- netrc file processing}
-
-\declaremodule{standard}{netrc}
-% Note the \protect needed for \file... ;-(
-\modulesynopsis{Loading of \protect\file{.netrc} files.}
-\moduleauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-
-
-\versionadded{1.5.2}
-
-The \class{netrc} class parses and encapsulates the netrc file format
-used by the \UNIX{} \program{ftp} program and other FTP clients.
-
-\begin{classdesc}{netrc}{\optional{file}}
-A \class{netrc} instance or subclass instance encapsulates data from
-a netrc file. The initialization argument, if present, specifies the
-file to parse. If no argument is given, the file \file{.netrc} in the
-user's home directory will be read. Parse errors will raise
-\exception{NetrcParseError} with diagnostic information including the
-file name, line number, and terminating token.
-\end{classdesc}
-
-\begin{excdesc}{NetrcParseError}
-Exception raised by the \class{netrc} class when syntactical errors
-are encountered in source text. Instances of this exception provide
-three interesting attributes: \member{msg} is a textual explanation
-of the error, \member{filename} is the name of the source file, and
-\member{lineno} gives the line number on which the error was found.
-\end{excdesc}
-
-
-\subsection{netrc Objects \label{netrc-objects}}
-
-A \class{netrc} instance has the following methods:
-
-\begin{methoddesc}[netrc]{authenticators}{host}
-Return a 3-tuple \code{(\var{login}, \var{account}, \var{password})}
-of authenticators for \var{host}. If the netrc file did not
-contain an entry for the given host, return the tuple associated with
-the `default' entry. If neither matching host nor default entry is
-available, return \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[netrc]{__repr__}{}
-Dump the class data as a string in the format of a netrc file.
-(This discards comments and may reorder the entries.)
-\end{methoddesc}
-
-Instances of \class{netrc} have public instance variables:
-
-\begin{memberdesc}[netrc]{hosts}
-Dictionary mapping host names to \code{(\var{login}, \var{account},
-\var{password})} tuples. The `default' entry, if any, is represented
-as a pseudo-host by that name.
-\end{memberdesc}
-
-\begin{memberdesc}[netrc]{macros}
-Dictionary mapping macro names to string lists.
-\end{memberdesc}
-
-\note{Passwords are limited to a subset of the ASCII character set.
-Versions of this module prior to 2.3 were extremely limited. Starting with
-2.3, all ASCII punctuation is allowed in passwords. However, note that
-whitespace and non-printable characters are not allowed in passwords. This
-is a limitation of the way the .netrc file is parsed and may be removed in
-the future.}
diff --git a/Doc/lib/libnew.tex b/Doc/lib/libnew.tex
deleted file mode 100644
index 18162dc..0000000
--- a/Doc/lib/libnew.tex
+++ /dev/null
@@ -1,55 +0,0 @@
-\section{\module{new} ---
- Creation of runtime internal objects}
-
-\declaremodule{builtin}{new}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Interface to the creation of runtime implementation objects.}
-
-
-The \module{new} module allows an interface to the interpreter object
-creation functions. This is for use primarily in marshal-type functions,
-when a new object needs to be created ``magically'' and not by using the
-regular creation functions. This module provides a low-level interface
-to the interpreter, so care must be exercised when using this module.
-It is possible to supply non-sensical arguments which crash the
-interpreter when the object is used.
-
-The \module{new} module defines the following functions:
-
-\begin{funcdesc}{instancemethod}{function, instance, class}
-This function will return a method object, bound to \var{instance}, or
-unbound if \var{instance} is \code{None}. \var{function} must be
-callable.
-\end{funcdesc}
-
-\begin{funcdesc}{function}{code, globals\optional{, name\optional{,
- argdefs\optional{, closure}}}}
-Returns a (Python) function with the given code and globals. If
-\var{name} is given, it must be a string or \code{None}. If it is a
-string, the function will have the given name, otherwise the function
-name will be taken from \code{\var{code}.co_name}. If
-\var{argdefs} is given, it must be a tuple and will be used to
-determine the default values of parameters. If \var{closure} is given,
-it must be \code{None} or a tuple of cell objects containing objects
-to bind to the names in \code{\var{code}.co_freevars}.
-\end{funcdesc}
-
-\begin{funcdesc}{code}{argcount, nlocals, stacksize, flags, codestring,
- constants, names, varnames, filename, name, firstlineno,
- lnotab}
-This function is an interface to the \cfunction{PyCode_New()} C
-function.
-%XXX This is still undocumented!!!!!!!!!!!
-\end{funcdesc}
-
-\begin{funcdesc}{module}{name[, doc]}
-This function returns a new module object with name \var{name}.
-\var{name} must be a string.
-The optional \var{doc} argument can have any type.
-\end{funcdesc}
-
-\begin{funcdesc}{classobj}{name, baseclasses, dict}
-This function returns a new class object, with name \var{name}, derived
-from \var{baseclasses} (which should be a tuple of classes) and with
-namespace \var{dict}.
-\end{funcdesc}
diff --git a/Doc/lib/libni.tex b/Doc/lib/libni.tex
deleted file mode 100644
index fa2b3ee..0000000
--- a/Doc/lib/libni.tex
+++ /dev/null
@@ -1,63 +0,0 @@
-\section{\module{ni} ---
- None}
-\declaremodule{standard}{ni}
-
-\modulesynopsis{None}
-
-
-\strong{Warning: This module is obsolete.} As of Python 1.5a4,
-package support (with different semantics for \code{__init__} and no
-support for \code{__domain__} or \code{__}) is built in the
-interpreter. The ni module is retained only for backward
-compatibility. As of Python 1.5b2, it has been renamed to \code{ni1};
-if you really need it, you can use \code{import ni1}, but the
-recommended approach is to rely on the built-in package support,
-converting existing packages if needed. Note that mixing \code{ni}
-and the built-in package support doesn't work: once you import
-\code{ni}, all packages use it.
-
-The \code{ni} module defines a new importing scheme, which supports
-packages containing several Python modules. To enable package
-support, execute \code{import ni} before importing any packages. Importing
-this module automatically installs the relevant import hooks. There
-are no publicly-usable functions or variables in the \code{ni} module.
-
-To create a package named \code{spam} containing sub-modules \code{ham}, \code{bacon} and
-\code{eggs}, create a directory \file{spam} somewhere on Python's module search
-path, as given in \code{sys.path}. Then, create files called \file{ham.py}, \file{bacon.py} and
-\file{eggs.py} inside \file{spam}.
-
-To import module \code{ham} from package \code{spam} and use function
-\code{hamneggs()} from that module, you can use any of the following
-possibilities:
-
-\begin{verbatim}
-import spam.ham # *not* "import spam" !!!
-spam.ham.hamneggs()
-\end{verbatim}
-%
-\begin{verbatim}
-from spam import ham
-ham.hamneggs()
-\end{verbatim}
-%
-\begin{verbatim}
-from spam.ham import hamneggs
-hamneggs()
-\end{verbatim}
-%
-\code{import spam} creates an
-empty package named \code{spam} if one does not already exist, but it does
-\emph{not} automatically import \code{spam}'s submodules.
-The only submodule that is guaranteed to be imported is
-\code{spam.__init__}, if it exists; it would be in a file named
-\file{__init__.py} in the \file{spam} directory. Note that
-\code{spam.__init__} is a submodule of package spam. It can refer to
-spam's namespace as \code{__} (two underscores):
-
-\begin{verbatim}
-__.spam_inited = 1 # Set a package-level variable
-\end{verbatim}
-%
-Additional initialization code (setting up variables, importing other
-submodules) can be performed in \file{spam/__init__.py}.
diff --git a/Doc/lib/libnis.tex b/Doc/lib/libnis.tex
deleted file mode 100644
index fe4acb5..0000000
--- a/Doc/lib/libnis.tex
+++ /dev/null
@@ -1,63 +0,0 @@
-\section{\module{nis} ---
- Interface to Sun's NIS (Yellow Pages)}
-
-\declaremodule{extension}{nis}
- \platform{Unix}
-\moduleauthor{Fred Gansevles}{Fred.Gansevles@cs.utwente.nl}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Interface to Sun's NIS (Yellow Pages) library.}
-
-The \module{nis} module gives a thin wrapper around the NIS library, useful
-for central administration of several hosts.
-
-Because NIS exists only on \UNIX{} systems, this module is
-only available for \UNIX.
-
-The \module{nis} module defines the following functions:
-
-\begin{funcdesc}{match}{key, mapname[, domain=default_domain]}
-Return the match for \var{key} in map \var{mapname}, or raise an
-error (\exception{nis.error}) if there is none.
-Both should be strings, \var{key} is 8-bit clean.
-Return value is an arbitrary array of bytes (may contain \code{NULL}
-and other joys).
-
-Note that \var{mapname} is first checked if it is an alias to another
-name.
-
-\versionchanged[The \var{domain} argument allows to override
-the NIS domain used for the lookup. If unspecified, lookup is in the
-default NIS domain]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{cat}{mapname[, domain=default_domain]}
-Return a dictionary mapping \var{key} to \var{value} such that
-\code{match(\var{key}, \var{mapname})==\var{value}}.
-Note that both keys and values of the dictionary are arbitrary
-arrays of bytes.
-
-Note that \var{mapname} is first checked if it is an alias to another
-name.
-
-\versionchanged[The \var{domain} argument allows to override
-the NIS domain used for the lookup. If unspecified, lookup is in the
-default NIS domain]{2.5}
-\end{funcdesc}
-
- \begin{funcdesc}{maps}{[domain=default_domain]}
-Return a list of all valid maps.
-
-\versionchanged[The \var{domain} argument allows to override
-the NIS domain used for the lookup. If unspecified, lookup is in the
-default NIS domain]{2.5}
-\end{funcdesc}
-
- \begin{funcdesc}{get_default_domain}{}
-Return the system default NIS domain. \versionadded{2.5}
-\end{funcdesc}
-
-The \module{nis} module defines the following exception:
-
-\begin{excdesc}{error}
-An error raised when a NIS function returns an error code.
-\end{excdesc}
diff --git a/Doc/lib/libnntplib.tex b/Doc/lib/libnntplib.tex
deleted file mode 100644
index 22236f4..0000000
--- a/Doc/lib/libnntplib.tex
+++ /dev/null
@@ -1,355 +0,0 @@
-\section{\module{nntplib} ---
- NNTP protocol client}
-
-\declaremodule{standard}{nntplib}
-\modulesynopsis{NNTP protocol client (requires sockets).}
-
-\indexii{NNTP}{protocol}
-\index{Network News Transfer Protocol}
-
-This module defines the class \class{NNTP} which implements the client
-side of the NNTP protocol. It can be used to implement a news reader
-or poster, or automated news processors. For more information on NNTP
-(Network News Transfer Protocol), see Internet \rfc{977}.
-
-Here are two small examples of how it can be used. To list some
-statistics about a newsgroup and print the subjects of the last 10
-articles:
-
-\begin{verbatim}
->>> s = NNTP('news.cwi.nl')
->>> resp, count, first, last, name = s.group('comp.lang.python')
->>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
-Group comp.lang.python has 59 articles, range 3742 to 3803
->>> resp, subs = s.xhdr('subject', first + '-' + last)
->>> for id, sub in subs[-10:]: print id, sub
-...
-3792 Re: Removing elements from a list while iterating...
-3793 Re: Who likes Info files?
-3794 Emacs and doc strings
-3795 a few questions about the Mac implementation
-3796 Re: executable python scripts
-3797 Re: executable python scripts
-3798 Re: a few questions about the Mac implementation
-3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules
-3802 Re: executable python scripts
-3803 Re: \POSIX{} wait and SIGCHLD
->>> s.quit()
-'205 news.cwi.nl closing connection. Goodbye.'
-\end{verbatim}
-
-To post an article from a file (this assumes that the article has
-valid headers):
-
-\begin{verbatim}
->>> s = NNTP('news.cwi.nl')
->>> f = open('/tmp/article')
->>> s.post(f)
-'240 Article posted successfully.'
->>> s.quit()
-'205 news.cwi.nl closing connection. Goodbye.'
-\end{verbatim}
-
-The module itself defines the following items:
-
-\begin{classdesc}{NNTP}{host\optional{, port
- \optional{, user\optional{, password
- \optional{, readermode}
- \optional{, usenetrc}}}}}
-Return a new instance of the \class{NNTP} class, representing a
-connection to the NNTP server running on host \var{host}, listening at
-port \var{port}. The default \var{port} is 119. If the optional
-\var{user} and \var{password} are provided,
-or if suitable credentials are present in \file{~/.netrc} and the
-optional flag \var{usenetrc} is true (the default),
-the \samp{AUTHINFO USER} and \samp{AUTHINFO PASS} commands are used to
-identify and authenticate the user to the server. If the optional
-flag \var{readermode} is true, then a \samp{mode reader} command is
-sent before authentication is performed. Reader mode is sometimes
-necessary if you are connecting to an NNTP server on the local machine
-and intend to call reader-specific commands, such as \samp{group}. If
-you get unexpected \exception{NNTPPermanentError}s, you might need to set
-\var{readermode}. \var{readermode} defaults to \code{None}.
-\var{usenetrc} defaults to \code{True}.
-
-\versionchanged[\var{usenetrc} argument added]{2.4}
-\end{classdesc}
-
-\begin{excdesc}{NNTPError}
-Derived from the standard exception \exception{Exception}, this is the
-base class for all exceptions raised by the \module{nntplib} module.
-\end{excdesc}
-
-\begin{excdesc}{NNTPReplyError}
-Exception raised when an unexpected reply is received from the
-server. For backwards compatibility, the exception \code{error_reply}
-is equivalent to this class.
-\end{excdesc}
-
-\begin{excdesc}{NNTPTemporaryError}
-Exception raised when an error code in the range 400--499 is
-received. For backwards compatibility, the exception
-\code{error_temp} is equivalent to this class.
-\end{excdesc}
-
-\begin{excdesc}{NNTPPermanentError}
-Exception raised when an error code in the range 500--599 is
-received. For backwards compatibility, the exception
-\code{error_perm} is equivalent to this class.
-\end{excdesc}
-
-\begin{excdesc}{NNTPProtocolError}
-Exception raised when a reply is received from the server that does
-not begin with a digit in the range 1--5. For backwards
-compatibility, the exception \code{error_proto} is equivalent to this
-class.
-\end{excdesc}
-
-\begin{excdesc}{NNTPDataError}
-Exception raised when there is some error in the response data. For
-backwards compatibility, the exception \code{error_data} is
-equivalent to this class.
-\end{excdesc}
-
-
-\subsection{NNTP Objects \label{nntp-objects}}
-
-NNTP instances have the following methods. The \var{response} that is
-returned as the first item in the return tuple of almost all methods
-is the server's response: a string beginning with a three-digit code.
-If the server's response indicates an error, the method raises one of
-the above exceptions.
-
-
-\begin{methoddesc}[NNTP]{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.)
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{set_debuglevel}{level}
-Set the instance's debugging level. This controls the amount of
-debugging output printed. The default, \code{0}, produces no debugging
-output. A value of \code{1} produces a moderate amount of debugging
-output, generally a single line per request or response. A value of
-\code{2} or higher produces the maximum amount of debugging output,
-logging each line sent and received on the connection (including
-message text).
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{newgroups}{date, time, \optional{file}}
-Send a \samp{NEWGROUPS} command. The \var{date} argument should be a
-string of the form \code{'\var{yy}\var{mm}\var{dd}'} indicating the
-date, and \var{time} should be a string of the form
-\code{'\var{hh}\var{mm}\var{ss}'} indicating the time. Return a pair
-\code{(\var{response}, \var{groups})} where \var{groups} is a list of
-group names that are new since the given date and time.
-If the \var{file} parameter is supplied, then the output of the
-\samp{NEWGROUPS} command is stored in a file. If \var{file} is a string,
-then the method will open a file object with that name, write to it
-then close it. If \var{file} is a file object, then it will start
-calling \method{write()} on it to store the lines of the command output.
-If \var{file} is supplied, then the returned \var{list} is an empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{newnews}{group, date, time, \optional{file}}
-Send a \samp{NEWNEWS} command. Here, \var{group} is a group name or
-\code{'*'}, and \var{date} and \var{time} have the same meaning as for
-\method{newgroups()}. Return a pair \code{(\var{response},
-\var{articles})} where \var{articles} is a list of message ids.
-If the \var{file} parameter is supplied, then the output of the
-\samp{NEWNEWS} command is stored in a file. If \var{file} is a string,
-then the method will open a file object with that name, write to it
-then close it. If \var{file} is a file object, then it will start
-calling \method{write()} on it to store the lines of the command output.
-If \var{file} is supplied, then the returned \var{list} is an empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{list}{\optional{file}}
-Send a \samp{LIST} command. Return a pair \code{(\var{response},
-\var{list})} where \var{list} is a list of tuples. Each tuple has the
-form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where
-\var{group} is a group name, \var{last} and \var{first} are the last
-and first article numbers (as strings), and \var{flag} is
-\code{'y'} if posting is allowed, \code{'n'} if not, and \code{'m'} if
-the newsgroup is moderated. (Note the ordering: \var{last},
-\var{first}.)
-If the \var{file} parameter is supplied, then the output of the
-\samp{LIST} command is stored in a file. If \var{file} is a string,
-then the method will open a file object with that name, write to it
-then close it. If \var{file} is a file object, then it will start
-calling \method{write()} on it to store the lines of the command output.
-If \var{file} is supplied, then the returned \var{list} is an empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{descriptions}{grouppattern}
-Send a \samp{LIST NEWSGROUPS} command, where \var{grouppattern} is a wildmat
-string as specified in RFC2980 (it's essentially the same as DOS or UNIX
-shell wildcard strings). Return a pair \code{(\var{response},
-\var{list})}, where \var{list} is a list of tuples containing
-\code{(\var{name}, \var{title})}.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{description}{group}
-Get a description for a single group \var{group}. If more than one group
-matches (if 'group' is a real wildmat string), return the first match.
-If no group matches, return an empty string.
-
-This elides the response code from the server. If the response code is
-needed, use \method{descriptions()}.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{group}{name}
-Send a \samp{GROUP} command, where \var{name} is the group name.
-Return a tuple \code{(\var{response}, \var{count}, \var{first},
-\var{last}, \var{name})} where \var{count} is the (estimated) number
-of articles in the group, \var{first} is the first article number in
-the group, \var{last} is the last article number in the group, and
-\var{name} is the group name. The numbers are returned as strings.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{help}{\optional{file}}
-Send a \samp{HELP} command. Return a pair \code{(\var{response},
-\var{list})} where \var{list} is a list of help strings.
-If the \var{file} parameter is supplied, then the output of the
-\samp{HELP} command is stored in a file. If \var{file} is a string,
-then the method will open a file object with that name, write to it
-then close it. If \var{file} is a file object, then it will start
-calling \method{write()} on it to store the lines of the command output.
-If \var{file} is supplied, then the returned \var{list} is an empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{stat}{id}
-Send a \samp{STAT} command, where \var{id} is the message id (enclosed
-in \character{<} and \character{>}) or an article number (as a string).
-Return a triple \code{(\var{response}, \var{number}, \var{id})} where
-\var{number} is the article number (as a string) and \var{id} is the
-message id (enclosed in \character{<} and \character{>}).
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{next}{}
-Send a \samp{NEXT} command. Return as for \method{stat()}.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{last}{}
-Send a \samp{LAST} command. Return as for \method{stat()}.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{head}{id}
-Send a \samp{HEAD} command, where \var{id} has the same meaning as for
-\method{stat()}. Return a tuple
-\code{(\var{response}, \var{number}, \var{id}, \var{list})}
-where the first three are the same as for \method{stat()},
-and \var{list} is a list of the article's headers (an uninterpreted
-list of lines, without trailing newlines).
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{body}{id,\optional{file}}
-Send a \samp{BODY} command, where \var{id} has the same meaning as for
-\method{stat()}. If the \var{file} parameter is supplied, then
-the body is stored in a file. If \var{file} is a string, then
-the method will open a file object with that name, write to it then close it.
-If \var{file} is a file object, then it will start calling
-\method{write()} on it to store the lines of the body.
-Return as for \method{head()}. If \var{file} is supplied, then
-the returned \var{list} is an empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{article}{id}
-Send an \samp{ARTICLE} command, where \var{id} has the same meaning as
-for \method{stat()}. Return as for \method{head()}.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{slave}{}
-Send a \samp{SLAVE} command. Return the server's \var{response}.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{xhdr}{header, string, \optional{file}}
-Send an \samp{XHDR} command. This command is not defined in the RFC
-but is a common extension. The \var{header} argument is a header
-keyword, e.g. \code{'subject'}. The \var{string} argument should have
-the form \code{'\var{first}-\var{last}'} where \var{first} and
-\var{last} are the first and last article numbers to search. Return a
-pair \code{(\var{response}, \var{list})}, where \var{list} is a list of
-pairs \code{(\var{id}, \var{text})}, where \var{id} is an article number
-(as a string) and \var{text} is the text of the requested header for
-that article.
-If the \var{file} parameter is supplied, then the output of the
-\samp{XHDR} command is stored in a file. If \var{file} is a string,
-then the method will open a file object with that name, write to it
-then close it. If \var{file} is a file object, then it will start
-calling \method{write()} on it to store the lines of the command output.
-If \var{file} is supplied, then the returned \var{list} is an empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{post}{file}
-Post an article using the \samp{POST} command. The \var{file}
-argument is an open file object which is read until EOF using its
-\method{readline()} method. It should be a well-formed news article,
-including the required headers. The \method{post()} method
-automatically escapes lines beginning with \samp{.}.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{ihave}{id, file}
-Send an \samp{IHAVE} command. \var{id} is a message id (enclosed in
-\character{<} and \character{>}).
-If the response is not an error, treat
-\var{file} exactly as for the \method{post()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{date}{}
-Return a triple \code{(\var{response}, \var{date}, \var{time})},
-containing the current date and time in a form suitable for the
-\method{newnews()} and \method{newgroups()} methods.
-This is an optional NNTP extension, and may not be supported by all
-servers.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{xgtitle}{name, \optional{file}}
-Process an \samp{XGTITLE} command, returning a pair \code{(\var{response},
-\var{list})}, where \var{list} is a list of tuples containing
-\code{(\var{name}, \var{title})}.
-% XXX huh? Should that be name, description?
-If the \var{file} parameter is supplied, then the output of the
-\samp{XGTITLE} command is stored in a file. If \var{file} is a string,
-then the method will open a file object with that name, write to it
-then close it. If \var{file} is a file object, then it will start
-calling \method{write()} on it to store the lines of the command output.
-If \var{file} is supplied, then the returned \var{list} is an empty list.
-This is an optional NNTP extension, and may not be supported by all
-servers.
-
-RFC2980 says ``It is suggested that this extension be deprecated''. Use
-\method{descriptions()} or \method{description()} instead.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{xover}{start, end, \optional{file}}
-Return a pair \code{(\var{resp}, \var{list})}. \var{list} is a list
-of tuples, one for each article in the range delimited by the \var{start}
-and \var{end} article numbers. Each tuple is of the form
-\code{(\var{article number}, \var{subject}, \var{poster}, \var{date},
-\var{id}, \var{references}, \var{size}, \var{lines})}.
-If the \var{file} parameter is supplied, then the output of the
-\samp{XOVER} command is stored in a file. If \var{file} is a string,
-then the method will open a file object with that name, write to it
-then close it. If \var{file} is a file object, then it will start
-calling \method{write()} on it to store the lines of the command output.
-If \var{file} is supplied, then the returned \var{list} is an empty list.
-This is an optional NNTP extension, and may not be supported by all
-servers.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{xpath}{id}
-Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is the
-directory path to the article with message ID \var{id}. This is an
-optional NNTP extension, and may not be supported by all servers.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{quit}{}
-Send a \samp{QUIT} command and close the connection. Once this method
-has been called, no other methods of the NNTP object should be called.
-\end{methoddesc}
diff --git a/Doc/lib/libobjs.tex b/Doc/lib/libobjs.tex
deleted file mode 100644
index 3c7d798..0000000
--- a/Doc/lib/libobjs.tex
+++ /dev/null
@@ -1,24 +0,0 @@
-\chapter{Built-in Objects \label{builtin}}
-
-Names for built-in exceptions and functions and a number of constants are
-found in a separate
-symbol table. This table is searched last when the interpreter looks
-up the meaning of a name, so local and global
-user-defined names can override built-in names. Built-in types are
-described together here for easy reference.\footnote{
- Most descriptions sorely lack explanations of the exceptions
- that may be raised --- this will be fixed in a future version of
- this manual.}
-\indexii{built-in}{types}
-\indexii{built-in}{exceptions}
-\indexii{built-in}{functions}
-\indexii{built-in}{constants}
-\index{symbol table}
-
-The tables in this chapter document the priorities of operators by
-listing them in order of ascending priority (within a table) and
-grouping operators that have the same priority in the same box.
-Binary operators of the same priority group from left to right.
-(Unary operators group from right to left, but there you have no real
-choice.) See chapter 5 of the \citetitle[../ref/ref.html]{Python
-Reference Manual} for the complete picture on operator priorities.
diff --git a/Doc/lib/liboperator.tex b/Doc/lib/liboperator.tex
deleted file mode 100644
index 867c2ab..0000000
--- a/Doc/lib/liboperator.tex
+++ /dev/null
@@ -1,530 +0,0 @@
-\section{\module{operator} ---
- Standard operators as functions.}
-\declaremodule{builtin}{operator}
-\sectionauthor{Skip Montanaro}{skip@automatrix.com}
-
-\modulesynopsis{All Python's standard operators as built-in functions.}
-
-
-The \module{operator} module exports a set of functions implemented in C
-corresponding to the intrinsic operators of Python. For example,
-\code{operator.add(x, y)} is equivalent to the expression \code{x+y}. The
-function names are those used for special class methods; variants without
-leading and trailing \samp{__} are also provided for convenience.
-
-The functions fall into categories that perform object comparisons,
-logical operations, mathematical operations, sequence operations, and
-abstract type tests.
-
-The object comparison functions are useful for all objects, and are
-named after the rich comparison operators they support:
-
-\begin{funcdesc}{lt}{a, b}
-\funcline{le}{a, b}
-\funcline{eq}{a, b}
-\funcline{ne}{a, b}
-\funcline{ge}{a, b}
-\funcline{gt}{a, b}
-\funcline{__lt__}{a, b}
-\funcline{__le__}{a, b}
-\funcline{__eq__}{a, b}
-\funcline{__ne__}{a, b}
-\funcline{__ge__}{a, b}
-\funcline{__gt__}{a, b}
-Perform ``rich comparisons'' between \var{a} and \var{b}. Specifically,
-\code{lt(\var{a}, \var{b})} is equivalent to \code{\var{a} < \var{b}},
-\code{le(\var{a}, \var{b})} is equivalent to \code{\var{a} <= \var{b}},
-\code{eq(\var{a}, \var{b})} is equivalent to \code{\var{a} == \var{b}},
-\code{ne(\var{a}, \var{b})} is equivalent to \code{\var{a} != \var{b}},
-\code{gt(\var{a}, \var{b})} is equivalent to \code{\var{a} > \var{b}}
-and
-\code{ge(\var{a}, \var{b})} is equivalent to \code{\var{a} >= \var{b}}.
-Note that unlike the built-in \function{cmp()}, these functions can
-return any value, which may or may not be interpretable as a Boolean
-value. See the \citetitle[../ref/ref.html]{Python Reference Manual}
-for more information about rich comparisons.
-\versionadded{2.2}
-\end{funcdesc}
-
-
-The logical operations are also generally applicable to all objects,
-and support truth tests, identity tests, and boolean operations:
-
-\begin{funcdesc}{not_}{o}
-\funcline{__not__}{o}
-Return the outcome of \keyword{not} \var{o}. (Note that there is no
-\method{__not__()} method for object instances; only the interpreter
-core defines this operation. The result is affected by the
-\method{__bool__()} and \method{__len__()} methods.)
-\end{funcdesc}
-
-\begin{funcdesc}{truth}{o}
-Return \constant{True} if \var{o} is true, and \constant{False}
-otherwise. This is equivalent to using the \class{bool}
-constructor.
-\end{funcdesc}
-
-\begin{funcdesc}{is_}{a, b}
-Return \code{\var{a} is \var{b}}. Tests object identity.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{is_not}{a, b}
-Return \code{\var{a} is not \var{b}}. Tests object identity.
-\versionadded{2.3}
-\end{funcdesc}
-
-
-The mathematical and bitwise operations are the most numerous:
-
-\begin{funcdesc}{abs}{o}
-\funcline{__abs__}{o}
-Return the absolute value of \var{o}.
-\end{funcdesc}
-
-\begin{funcdesc}{add}{a, b}
-\funcline{__add__}{a, b}
-Return \var{a} \code{+} \var{b}, for \var{a} and \var{b} numbers.
-\end{funcdesc}
-
-\begin{funcdesc}{and_}{a, b}
-\funcline{__and__}{a, b}
-Return the bitwise and of \var{a} and \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{div}{a, b}
-\funcline{__div__}{a, b}
-Return \var{a} \code{/} \var{b} when \code{__future__.division} is not
-in effect. This is also known as ``classic'' division.
-\end{funcdesc}
-
-\begin{funcdesc}{floordiv}{a, b}
-\funcline{__floordiv__}{a, b}
-Return \var{a} \code{//} \var{b}.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{inv}{o}
-\funcline{invert}{o}
-\funcline{__inv__}{o}
-\funcline{__invert__}{o}
-Return the bitwise inverse of the number \var{o}. This is equivalent
-to \code{\textasciitilde}\var{o}. The names \function{invert()} and
-\function{__invert__()} were added in Python 2.0.
-\end{funcdesc}
-
-\begin{funcdesc}{lshift}{a, b}
-\funcline{__lshift__}{a, b}
-Return \var{a} shifted left by \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{mod}{a, b}
-\funcline{__mod__}{a, b}
-Return \var{a} \code{\%} \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{mul}{a, b}
-\funcline{__mul__}{a, b}
-Return \var{a} \code{*} \var{b}, for \var{a} and \var{b} numbers.
-\end{funcdesc}
-
-\begin{funcdesc}{neg}{o}
-\funcline{__neg__}{o}
-Return \var{o} negated.
-\end{funcdesc}
-
-\begin{funcdesc}{or_}{a, b}
-\funcline{__or__}{a, b}
-Return the bitwise or of \var{a} and \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{pos}{o}
-\funcline{__pos__}{o}
-Return \var{o} positive.
-\end{funcdesc}
-
-\begin{funcdesc}{pow}{a, b}
-\funcline{__pow__}{a, b}
-Return \var{a} \code{**} \var{b}, for \var{a} and \var{b} numbers.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{rshift}{a, b}
-\funcline{__rshift__}{a, b}
-Return \var{a} shifted right by \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{sub}{a, b}
-\funcline{__sub__}{a, b}
-Return \var{a} \code{-} \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{truediv}{a, b}
-\funcline{__truediv__}{a, b}
-Return \var{a} \code{/} \var{b} when \code{__future__.division} is in
-effect. This is also known as ``true'' division.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{xor}{a, b}
-\funcline{__xor__}{a, b}
-Return the bitwise exclusive or of \var{a} and \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{index}{a}
-\funcline{__index__}{a}
-Return \var{a} converted to an integer. Equivalent to \var{a}\code{.__index__()}.
-\versionadded{2.5}
-\end{funcdesc}
-
-Operations which work with sequences include:
-
-\begin{funcdesc}{concat}{a, b}
-\funcline{__concat__}{a, b}
-Return \var{a} \code{+} \var{b} for \var{a} and \var{b} sequences.
-\end{funcdesc}
-
-\begin{funcdesc}{contains}{a, b}
-\funcline{__contains__}{a, b}
-Return the outcome of the test \var{b} \code{in} \var{a}.
-Note the reversed operands. The name \function{__contains__()} was
-added in Python 2.0.
-\end{funcdesc}
-
-\begin{funcdesc}{countOf}{a, b}
-Return the number of occurrences of \var{b} in \var{a}.
-\end{funcdesc}
-
-\begin{funcdesc}{delitem}{a, b}
-\funcline{__delitem__}{a, b}
-Remove the value of \var{a} at index \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{delslice}{a, b, c}
-\funcline{__delslice__}{a, b, c}
-Delete the slice of \var{a} from index \var{b} to index \var{c}\code{-1}.
-\end{funcdesc}
-
-\begin{funcdesc}{getitem}{a, b}
-\funcline{__getitem__}{a, b}
-Return the value of \var{a} at index \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{getslice}{a, b, c}
-\funcline{__getslice__}{a, b, c}
-Return the slice of \var{a} from index \var{b} to index \var{c}\code{-1}.
-\end{funcdesc}
-
-\begin{funcdesc}{indexOf}{a, b}
-Return the index of the first of occurrence of \var{b} in \var{a}.
-\end{funcdesc}
-
-\begin{funcdesc}{repeat}{a, b}
-\funcline{__repeat__}{a, b}
-Return \var{a} \code{*} \var{b} where \var{a} is a sequence and
-\var{b} is an integer.
-\end{funcdesc}
-
-\begin{funcdesc}{sequenceIncludes}{\unspecified}
-\deprecated{2.0}{Use \function{contains()} instead.}
-Alias for \function{contains()}.
-\end{funcdesc}
-
-\begin{funcdesc}{setitem}{a, b, c}
-\funcline{__setitem__}{a, b, c}
-Set the value of \var{a} at index \var{b} to \var{c}.
-\end{funcdesc}
-
-\begin{funcdesc}{setslice}{a, b, c, v}
-\funcline{__setslice__}{a, b, c, v}
-Set the slice of \var{a} from index \var{b} to index \var{c}\code{-1} to the
-sequence \var{v}.
-\end{funcdesc}
-
-
-Many operations have an ``in-place'' version. The following functions
-provide a more primitive access to in-place operators than the usual
-syntax does; for example, the statement \code{x += y} is equivalent to
-\code{x = operator.iadd(x, y)}. Another way to put it is to say that
-\code{z = operator.iadd(x, y)} is equivalent to the compound statement
-\code{z = x; z += y}.
-
-\begin{funcdesc}{iadd}{a, b}
-\funcline{__iadd__}{a, b}
-\code{a = iadd(a, b)} is equivalent to \code{a += b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{iand}{a, b}
-\funcline{__iand__}{a, b}
-\code{a = iand(a, b)} is equivalent to \code{a \&= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{iconcat}{a, b}
-\funcline{__iconcat__}{a, b}
-\code{a = iconcat(a, b)} is equivalent to \code{a += b} for \var{a}
-and \var{b} sequences.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{idiv}{a, b}
-\funcline{__idiv__}{a, b}
-\code{a = idiv(a, b)} is equivalent to \code{a /= b} when
-\code{__future__.division} is not in effect.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{ifloordiv}{a, b}
-\funcline{__ifloordiv__}{a, b}
-\code{a = ifloordiv(a, b)} is equivalent to \code{a //= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{ilshift}{a, b}
-\funcline{__ilshift__}{a, b}
-\code{a = ilshift(a, b)} is equivalent to \code{a <}\code{<= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{imod}{a, b}
-\funcline{__imod__}{a, b}
-\code{a = imod(a, b)} is equivalent to \code{a \%= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{imul}{a, b}
-\funcline{__imul__}{a, b}
-\code{a = imul(a, b)} is equivalent to \code{a *= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{ior}{a, b}
-\funcline{__ior__}{a, b}
-\code{a = ior(a, b)} is equivalent to \code{a |= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{ipow}{a, b}
-\funcline{__ipow__}{a, b}
-\code{a = ipow(a, b)} is equivalent to \code{a **= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{irepeat}{a, b}
-\funcline{__irepeat__}{a, b}
-\code{a = irepeat(a, b)} is equivalent to \code{a *= b} where
-\var{a} is a sequence and \var{b} is an integer.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{irshift}{a, b}
-\funcline{__irshift__}{a, b}
-\code{a = irshift(a, b)} is equivalent to \code{a >>= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{isub}{a, b}
-\funcline{__isub__}{a, b}
-\code{a = isub(a, b)} is equivalent to \code{a -= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{itruediv}{a, b}
-\funcline{__itruediv__}{a, b}
-\code{a = itruediv(a, b)} is equivalent to \code{a /= b} when
-\code{__future__.division} is in effect.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{ixor}{a, b}
-\funcline{__ixor__}{a, b}
-\code{a = ixor(a, b)} is equivalent to \code{a \textasciicircum= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-
-The \module{operator} module also defines a few predicates to test the
-type of objects. \note{Be careful not to misinterpret the
-results of these functions; only \function{isCallable()} has any
-measure of reliability with instance objects. For example:}
-
-\begin{verbatim}
->>> class C:
-... pass
-...
->>> import operator
->>> o = C()
->>> operator.isMappingType(o)
-True
-\end{verbatim}
-
-\begin{funcdesc}{isCallable}{o}
-\deprecated{2.0}{Use the \function{callable()} built-in function instead.}
-Returns true if the object \var{o} can be called like a function,
-otherwise it returns false. True is returned for functions, bound and
-unbound methods, class objects, and instance objects which support the
-\method{__call__()} method.
-\end{funcdesc}
-
-\begin{funcdesc}{isMappingType}{o}
-Returns true if the object \var{o} supports the mapping interface.
-This is true for dictionaries and all instance objects defining
-\method{__getitem__}.
-\warning{There is no reliable way to test if an instance
-supports the complete mapping protocol since the interface itself is
-ill-defined. This makes this test less useful than it otherwise might
-be.}
-\end{funcdesc}
-
-\begin{funcdesc}{isNumberType}{o}
-Returns true if the object \var{o} represents a number. This is true
-for all numeric types implemented in C.
-\warning{There is no reliable way to test if an instance
-supports the complete numeric interface since the interface itself is
-ill-defined. This makes this test less useful than it otherwise might
-be.}
-\end{funcdesc}
-
-\begin{funcdesc}{isSequenceType}{o}
-Returns true if the object \var{o} supports the sequence protocol.
-This returns true for all objects which define sequence methods in C,
-and for all instance objects defining \method{__getitem__}.
-\warning{There is no reliable
-way to test if an instance supports the complete sequence interface
-since the interface itself is ill-defined. This makes this test less
-useful than it otherwise might be.}
-\end{funcdesc}
-
-
-Example: Build a dictionary that maps the ordinals from \code{0} to
-\code{255} to their character equivalents.
-
-\begin{verbatim}
->>> import operator
->>> d = {}
->>> keys = range(256)
->>> vals = map(chr, keys)
->>> map(operator.setitem, [d]*len(keys), keys, vals)
-\end{verbatim}
-
-
-The \module{operator} module also defines tools for generalized attribute
-and item lookups. These are useful for making fast field extractors
-as arguments for \function{map()}, \function{sorted()},
-\method{itertools.groupby()}, or other functions that expect a
-function argument.
-
-\begin{funcdesc}{attrgetter}{attr\optional{, args...}}
-Return a callable object that fetches \var{attr} from its operand.
-If more than one attribute is requested, returns a tuple of attributes.
-After, \samp{f=attrgetter('name')}, the call \samp{f(b)} returns
-\samp{b.name}. After, \samp{f=attrgetter('name', 'date')}, the call
-\samp{f(b)} returns \samp{(b.name, b.date)}.
-\versionadded{2.4}
-\versionchanged[Added support for multiple attributes]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{itemgetter}{item\optional{, args...}}
-Return a callable object that fetches \var{item} from its operand.
-If more than one item is requested, returns a tuple of items.
-After, \samp{f=itemgetter(2)}, the call \samp{f(b)} returns
-\samp{b[2]}.
-After, \samp{f=itemgetter(2,5,3)}, the call \samp{f(b)} returns
-\samp{(b[2], b[5], b[3])}.
-\versionadded{2.4}
-\versionchanged[Added support for multiple item extraction]{2.5}
-\end{funcdesc}
-
-Examples:
-
-\begin{verbatim}
->>> from operator import itemgetter
->>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)]
->>> getcount = itemgetter(1)
->>> map(getcount, inventory)
-[3, 2, 5, 1]
->>> sorted(inventory, key=getcount)
-[('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)]
-\end{verbatim}
-
-
-\subsection{Mapping Operators to Functions \label{operator-map}}
-
-This table shows how abstract operations correspond to operator
-symbols in the Python syntax and the functions in the
-\refmodule{operator} module.
-
-
-\begin{tableiii}{l|c|l}{textrm}{Operation}{Syntax}{Function}
- \lineiii{Addition}{\code{\var{a} + \var{b}}}
- {\code{add(\var{a}, \var{b})}}
- \lineiii{Concatenation}{\code{\var{seq1} + \var{seq2}}}
- {\code{concat(\var{seq1}, \var{seq2})}}
- \lineiii{Containment Test}{\code{\var{o} in \var{seq}}}
- {\code{contains(\var{seq}, \var{o})}}
- \lineiii{Division}{\code{\var{a} / \var{b}}}
- {\code{div(\var{a}, \var{b}) \#} without \code{__future__.division}}
- \lineiii{Division}{\code{\var{a} / \var{b}}}
- {\code{truediv(\var{a}, \var{b}) \#} with \code{__future__.division}}
- \lineiii{Division}{\code{\var{a} // \var{b}}}
- {\code{floordiv(\var{a}, \var{b})}}
- \lineiii{Bitwise And}{\code{\var{a} \&\ \var{b}}}
- {\code{and_(\var{a}, \var{b})}}
- \lineiii{Bitwise Exclusive Or}{\code{\var{a} \^\ \var{b}}}
- {\code{xor(\var{a}, \var{b})}}
- \lineiii{Bitwise Inversion}{\code{\~{} \var{a}}}
- {\code{invert(\var{a})}}
- \lineiii{Bitwise Or}{\code{\var{a} | \var{b}}}
- {\code{or_(\var{a}, \var{b})}}
- \lineiii{Exponentiation}{\code{\var{a} ** \var{b}}}
- {\code{pow(\var{a}, \var{b})}}
- \lineiii{Identity}{\code{\var{a} is \var{b}}}
- {\code{is_(\var{a}, \var{b})}}
- \lineiii{Identity}{\code{\var{a} is not \var{b}}}
- {\code{is_not(\var{a}, \var{b})}}
- \lineiii{Indexed Assignment}{\code{\var{o}[\var{k}] = \var{v}}}
- {\code{setitem(\var{o}, \var{k}, \var{v})}}
- \lineiii{Indexed Deletion}{\code{del \var{o}[\var{k}]}}
- {\code{delitem(\var{o}, \var{k})}}
- \lineiii{Indexing}{\code{\var{o}[\var{k}]}}
- {\code{getitem(\var{o}, \var{k})}}
- \lineiii{Left Shift}{\code{\var{a} <\code{<} \var{b}}}
- {\code{lshift(\var{a}, \var{b})}}
- \lineiii{Modulo}{\code{\var{a} \%\ \var{b}}}
- {\code{mod(\var{a}, \var{b})}}
- \lineiii{Multiplication}{\code{\var{a} * \var{b}}}
- {\code{mul(\var{a}, \var{b})}}
- \lineiii{Negation (Arithmetic)}{\code{- \var{a}}}
- {\code{neg(\var{a})}}
- \lineiii{Negation (Logical)}{\code{not \var{a}}}
- {\code{not_(\var{a})}}
- \lineiii{Right Shift}{\code{\var{a} >> \var{b}}}
- {\code{rshift(\var{a}, \var{b})}}
- \lineiii{Sequence Repitition}{\code{\var{seq} * \var{i}}}
- {\code{repeat(\var{seq}, \var{i})}}
- \lineiii{Slice Assignment}{\code{\var{seq}[\var{i}:\var{j}]} = \var{values}}
- {\code{setslice(\var{seq}, \var{i}, \var{j}, \var{values})}}
- \lineiii{Slice Deletion}{\code{del \var{seq}[\var{i}:\var{j}]}}
- {\code{delslice(\var{seq}, \var{i}, \var{j})}}
- \lineiii{Slicing}{\code{\var{seq}[\var{i}:\var{j}]}}
- {\code{getslice(\var{seq}, \var{i}, \var{j})}}
- \lineiii{String Formatting}{\code{\var{s} \%\ \var{o}}}
- {\code{mod(\var{s}, \var{o})}}
- \lineiii{Subtraction}{\code{\var{a} - \var{b}}}
- {\code{sub(\var{a}, \var{b})}}
- \lineiii{Truth Test}{\code{\var{o}}}
- {\code{truth(\var{o})}}
- \lineiii{Ordering}{\code{\var{a} < \var{b}}}
- {\code{lt(\var{a}, \var{b})}}
- \lineiii{Ordering}{\code{\var{a} <= \var{b}}}
- {\code{le(\var{a}, \var{b})}}
- \lineiii{Equality}{\code{\var{a} == \var{b}}}
- {\code{eq(\var{a}, \var{b})}}
- \lineiii{Difference}{\code{\var{a} != \var{b}}}
- {\code{ne(\var{a}, \var{b})}}
- \lineiii{Ordering}{\code{\var{a} >= \var{b}}}
- {\code{ge(\var{a}, \var{b})}}
- \lineiii{Ordering}{\code{\var{a} > \var{b}}}
- {\code{gt(\var{a}, \var{b})}}
-\end{tableiii}
diff --git a/Doc/lib/liboptparse.tex b/Doc/lib/liboptparse.tex
deleted file mode 100644
index eb4919b..0000000
--- a/Doc/lib/liboptparse.tex
+++ /dev/null
@@ -1,1888 +0,0 @@
-% THIS FILE IS AUTO-GENERATED! DO NOT EDIT!
-% (Your changes will be lost the next time it is generated.)
-\section{\module{optparse} --- More powerful command line option parser}
-\declaremodule{standard}{optparse}
-\moduleauthor{Greg Ward}{gward@python.net}
-\modulesynopsis{More convenient, flexible, and powerful command-line parsing library.}
-\versionadded{2.3}
-\sectionauthor{Greg Ward}{gward@python.net}
-% An intro blurb used only when generating LaTeX docs for the Python
-% manual (based on README.txt).
-
-\code{optparse} is a more convenient, flexible, and powerful library for
-parsing command-line options than \code{getopt}. \code{optparse} uses a more
-declarative style of command-line parsing: you create an instance of
-\class{OptionParser}, populate it with options, and parse the command line.
-\code{optparse} allows users to specify options in the conventional GNU/POSIX
-syntax, and additionally generates usage and help messages for you.
-
-Here's an example of using \code{optparse} in a simple script:
-\begin{verbatim}
-from optparse import OptionParser
-[...]
-parser = OptionParser()
-parser.add_option("-f", "--file", dest="filename",
- help="write report to FILE", metavar="FILE")
-parser.add_option("-q", "--quiet",
- action="store_false", dest="verbose", default=True,
- help="don't print status messages to stdout")
-
-(options, args) = parser.parse_args()
-\end{verbatim}
-
-With these few lines of code, users of your script can now do the
-``usual thing'' on the command-line, for example:
-\begin{verbatim}
-<yourscript> --file=outfile -q
-\end{verbatim}
-
-As it parses the command line, \code{optparse} sets attributes of the
-\code{options} object returned by \method{parse{\_}args()} based on user-supplied
-command-line values. When \method{parse{\_}args()} returns from parsing this
-command line, \code{options.filename} will be \code{"outfile"} and
-\code{options.verbose} will be \code{False}. \code{optparse} supports both long
-and short options, allows short options to be merged together, and
-allows options to be associated with their arguments in a variety of
-ways. Thus, the following command lines are all equivalent to the above
-example:
-\begin{verbatim}
-<yourscript> -f outfile --quiet
-<yourscript> --quiet --file outfile
-<yourscript> -q -foutfile
-<yourscript> -qfoutfile
-\end{verbatim}
-
-Additionally, users can run one of
-\begin{verbatim}
-<yourscript> -h
-<yourscript> --help
-\end{verbatim}
-
-and \code{optparse} will print out a brief summary of your script's
-options:
-\begin{verbatim}
-usage: <yourscript> [options]
-
-options:
- -h, --help show this help message and exit
- -f FILE, --file=FILE write report to FILE
- -q, --quiet don't print status messages to stdout
-\end{verbatim}
-
-where the value of \emph{yourscript} is determined at runtime (normally
-from \code{sys.argv{[}0]}).
-% $Id: intro.txt 413 2004-09-28 00:59:13Z greg $
-
-
-\subsection{Background\label{optparse-background}}
-
-\module{optparse} was explicitly designed to encourage the creation of programs with
-straightforward, conventional command-line interfaces. To that end, it
-supports only the most common command-line syntax and semantics
-conventionally used under \UNIX{}. If you are unfamiliar with these
-conventions, read this section to acquaint yourself with them.
-
-
-\subsubsection{Terminology\label{optparse-terminology}}
-\begin{description}
-\item[argument]
-a string entered on the command-line, and passed by the shell to
-\code{execl()} or \code{execv()}. In Python, arguments are elements of
-\code{sys.argv{[}1:]} (\code{sys.argv{[}0]} is the name of the program being
-executed). \UNIX{} shells also use the term ``word''.
-
-It is occasionally desirable to substitute an argument list other
-than \code{sys.argv{[}1:]}, so you should read ``argument'' as ``an element of
-\code{sys.argv{[}1:]}, or of some other list provided as a substitute for
-\code{sys.argv{[}1:]}''.
-\item[option ]
-an argument used to supply extra information to guide or customize the
-execution of a program. There are many different syntaxes for
-options; the traditional \UNIX{} syntax is a hyphen (``-'') followed by a
-single letter, e.g. \code{"-x"} or \code{"-F"}. Also, traditional \UNIX{}
-syntax allows multiple options to be merged into a single argument,
-e.g. \code{"-x -F"} is equivalent to \code{"-xF"}. The GNU project
-introduced \code{"-{}-"} followed by a series of hyphen-separated words,
-e.g. \code{"-{}-file"} or \code{"-{}-dry-run"}. These are the only two option
-syntaxes provided by \module{optparse}.
-
-Some other option syntaxes that the world has seen include:
-\begin{itemize}
-\item {}
-a hyphen followed by a few letters, e.g. \code{"-pf"} (this is
-\emph{not} the same as multiple options merged into a single argument)
-
-\item {}
-a hyphen followed by a whole word, e.g. \code{"-file"} (this is
-technically equivalent to the previous syntax, but they aren't
-usually seen in the same program)
-
-\item {}
-a plus sign followed by a single letter, or a few letters,
-or a word, e.g. \code{"+f"}, \code{"+rgb"}
-
-\item {}
-a slash followed by a letter, or a few letters, or a word, e.g.
-\code{"/f"}, \code{"/file"}
-
-\end{itemize}
-
-These option syntaxes are not supported by \module{optparse}, and they never will
-be. This is deliberate: the first three are non-standard on any
-environment, and the last only makes sense if you're exclusively
-targeting VMS, MS-DOS, and/or Windows.
-\item[option argument]
-an argument that follows an option, is closely associated with that
-option, and is consumed from the argument list when that option is.
-With \module{optparse}, option arguments may either be in a separate argument
-from their option:
-\begin{verbatim}
--f foo
---file foo
-\end{verbatim}
-
-or included in the same argument:
-\begin{verbatim}
--ffoo
---file=foo
-\end{verbatim}
-
-Typically, a given option either takes an argument or it doesn't.
-Lots of people want an ``optional option arguments'' feature, meaning
-that some options will take an argument if they see it, and won't if
-they don't. This is somewhat controversial, because it makes parsing
-ambiguous: if \code{"-a"} takes an optional argument and \code{"-b"} is
-another option entirely, how do we interpret \code{"-ab"}? Because of
-this ambiguity, \module{optparse} does not support this feature.
-\item[positional argument]
-something leftover in the argument list after options have been
-parsed, i.e. after options and their arguments have been parsed and
-removed from the argument list.
-\item[required option]
-an option that must be supplied on the command-line; note that the
-phrase ``required option'' is self-contradictory in English. \module{optparse}
-doesn't prevent you from implementing required options, but doesn't
-give you much help at it either. See \code{examples/required{\_}1.py} and
-\code{examples/required{\_}2.py} in the \module{optparse} source distribution for two
-ways to implement required options with \module{optparse}.
-\end{description}
-
-For example, consider this hypothetical command-line:
-\begin{verbatim}
-prog -v --report /tmp/report.txt foo bar
-\end{verbatim}
-
-\code{"-v"} and \code{"-{}-report"} are both options. Assuming that
-\longprogramopt{report} takes one argument, \code{"/tmp/report.txt"} is an option
-argument. \code{"foo"} and \code{"bar"} are positional arguments.
-
-
-\subsubsection{What are options for?\label{optparse-what-options-for}}
-
-Options are used to provide extra information to tune or customize the
-execution of a program. In case it wasn't clear, options are usually
-\emph{optional}. A program should be able to run just fine with no options
-whatsoever. (Pick a random program from the \UNIX{} or GNU toolsets. Can
-it run without any options at all and still make sense? The main
-exceptions are \code{find}, \code{tar}, and \code{dd}{---}all of which are mutant
-oddballs that have been rightly criticized for their non-standard syntax
-and confusing interfaces.)
-
-Lots of people want their programs to have ``required options''. Think
-about it. If it's required, then it's \emph{not optional}! If there is a
-piece of information that your program absolutely requires in order to
-run successfully, that's what positional arguments are for.
-
-As an example of good command-line interface design, consider the humble
-\code{cp} utility, for copying files. It doesn't make much sense to try to
-copy files without supplying a destination and at least one source.
-Hence, \code{cp} fails if you run it with no arguments. However, it has a
-flexible, useful syntax that does not require any options at all:
-\begin{verbatim}
-cp SOURCE DEST
-cp SOURCE ... DEST-DIR
-\end{verbatim}
-
-You can get pretty far with just that. Most \code{cp} implementations
-provide a bunch of options to tweak exactly how the files are copied:
-you can preserve mode and modification time, avoid following symlinks,
-ask before clobbering existing files, etc. But none of this distracts
-from the core mission of \code{cp}, which is to copy either one file to
-another, or several files to another directory.
-
-
-\subsubsection{What are positional arguments for?\label{optparse-what-positional-arguments-for}}
-
-Positional arguments are for those pieces of information that your
-program absolutely, positively requires to run.
-
-A good user interface should have as few absolute requirements as
-possible. If your program requires 17 distinct pieces of information in
-order to run successfully, it doesn't much matter \emph{how} you get that
-information from the user{---}most people will give up and walk away
-before they successfully run the program. This applies whether the user
-interface is a command-line, a configuration file, or a GUI: if you make
-that many demands on your users, most of them will simply give up.
-
-In short, try to minimize the amount of information that users are
-absolutely required to supply{---}use sensible defaults whenever
-possible. Of course, you also want to make your programs reasonably
-flexible. That's what options are for. Again, it doesn't matter if
-they are entries in a config file, widgets in the ``Preferences'' dialog
-of a GUI, or command-line options{---}the more options you implement, the
-more flexible your program is, and the more complicated its
-implementation becomes. Too much flexibility has drawbacks as well, of
-course; too many options can overwhelm users and make your code much
-harder to maintain.
-% $Id: tao.txt 413 2004-09-28 00:59:13Z greg $
-
-
-\subsection{Tutorial\label{optparse-tutorial}}
-
-While \module{optparse} is quite flexible and powerful, it's also straightforward to
-use in most cases. This section covers the code patterns that are
-common to any \module{optparse}-based program.
-
-First, you need to import the OptionParser class; then, early in the
-main program, create an OptionParser instance:
-\begin{verbatim}
-from optparse import OptionParser
-[...]
-parser = OptionParser()
-\end{verbatim}
-
-Then you can start defining options. The basic syntax is:
-\begin{verbatim}
-parser.add_option(opt_str, ...,
- attr=value, ...)
-\end{verbatim}
-
-Each option has one or more option strings, such as \code{"-f"} or
-\code{"-{}-file"}, and several option attributes that tell \module{optparse} what to
-expect and what to do when it encounters that option on the command
-line.
-
-Typically, each option will have one short option string and one long
-option string, e.g.:
-\begin{verbatim}
-parser.add_option("-f", "--file", ...)
-\end{verbatim}
-
-You're free to define as many short option strings and as many long
-option strings as you like (including zero), as long as there is at
-least one option string overall.
-
-The option strings passed to \method{add{\_}option()} are effectively labels for
-the option defined by that call. For brevity, we will frequently refer
-to \emph{encountering an option} on the command line; in reality, \module{optparse}
-encounters \emph{option strings} and looks up options from them.
-
-Once all of your options are defined, instruct \module{optparse} to parse your
-program's command line:
-\begin{verbatim}
-(options, args) = parser.parse_args()
-\end{verbatim}
-
-(If you like, you can pass a custom argument list to \method{parse{\_}args()},
-but that's rarely necessary: by default it uses \code{sys.argv{[}1:]}.)
-
-\method{parse{\_}args()} returns two values:
-\begin{itemize}
-\item {}
-\code{options}, an object containing values for all of your options{---}e.g. if \code{"-{}-file"} takes a single string argument, then
-\code{options.file} will be the filename supplied by the user, or
-\code{None} if the user did not supply that option
-
-\item {}
-\code{args}, the list of positional arguments leftover after parsing
-options
-
-\end{itemize}
-
-This tutorial section only covers the four most important option
-attributes: \member{action}, \member{type}, \member{dest} (destination), and \member{help}.
-Of these, \member{action} is the most fundamental.
-
-
-\subsubsection{Understanding option actions\label{optparse-understanding-option-actions}}
-
-Actions tell \module{optparse} what to do when it encounters an option on the
-command line. There is a fixed set of actions hard-coded into \module{optparse};
-adding new actions is an advanced topic covered in section~\ref{optparse-extending-optparse}, Extending \module{optparse}.
-Most actions tell \module{optparse} to store a value in some variable{---}for
-example, take a string from the command line and store it in an
-attribute of \code{options}.
-
-If you don't specify an option action, \module{optparse} defaults to \code{store}.
-
-
-\subsubsection{The store action\label{optparse-store-action}}
-
-The most common option action is \code{store}, which tells \module{optparse} to take
-the next argument (or the remainder of the current argument), ensure
-that it is of the correct type, and store it to your chosen destination.
-
-For example:
-\begin{verbatim}
-parser.add_option("-f", "--file",
- action="store", type="string", dest="filename")
-\end{verbatim}
-
-Now let's make up a fake command line and ask \module{optparse} to parse it:
-\begin{verbatim}
-args = ["-f", "foo.txt"]
-(options, args) = parser.parse_args(args)
-\end{verbatim}
-
-When \module{optparse} sees the option string \code{"-f"}, it consumes the next
-argument, \code{"foo.txt"}, and stores it in \code{options.filename}. So,
-after this call to \method{parse{\_}args()}, \code{options.filename} is
-\code{"foo.txt"}.
-
-Some other option types supported by \module{optparse} are \code{int} and \code{float}.
-Here's an option that expects an integer argument:
-\begin{verbatim}
-parser.add_option("-n", type="int", dest="num")
-\end{verbatim}
-
-Note that this option has no long option string, which is perfectly
-acceptable. Also, there's no explicit action, since the default is
-\code{store}.
-
-Let's parse another fake command-line. This time, we'll jam the option
-argument right up against the option: since \code{"-n42"} (one argument) is
-equivalent to \code{"-n 42"} (two arguments), the code
-\begin{verbatim}
-(options, args) = parser.parse_args(["-n42"])
-print options.num
-\end{verbatim}
-
-will print \code{"42"}.
-
-If you don't specify a type, \module{optparse} assumes \code{string}. Combined with the
-fact that the default action is \code{store}, that means our first example
-can be a lot shorter:
-\begin{verbatim}
-parser.add_option("-f", "--file", dest="filename")
-\end{verbatim}
-
-If you don't supply a destination, \module{optparse} figures out a sensible default
-from the option strings: if the first long option string is
-\code{"-{}-foo-bar"}, then the default destination is \code{foo{\_}bar}. If there
-are no long option strings, \module{optparse} looks at the first short option
-string: the default destination for \code{"-f"} is \code{f}.
-
-\module{optparse} also includes built-in \code{long} and \code{complex} types. Adding
-types is covered in section~\ref{optparse-extending-optparse}, Extending \module{optparse}.
-
-
-\subsubsection{Handling boolean (flag) options\label{optparse-handling-boolean-options}}
-
-Flag options{---}set a variable to true or false when a particular option
-is seen{---}are quite common. \module{optparse} supports them with two separate
-actions, \code{store{\_}true} and \code{store{\_}false}. For example, you might have a
-\code{verbose} flag that is turned on with \code{"-v"} and off with \code{"-q"}:
-\begin{verbatim}
-parser.add_option("-v", action="store_true", dest="verbose")
-parser.add_option("-q", action="store_false", dest="verbose")
-\end{verbatim}
-
-Here we have two different options with the same destination, which is
-perfectly OK. (It just means you have to be a bit careful when setting
-default values{---}see below.)
-
-When \module{optparse} encounters \code{"-v"} on the command line, it sets
-\code{options.verbose} to \code{True}; when it encounters \code{"-q"},
-\code{options.verbose} is set to \code{False}.
-
-
-\subsubsection{Other actions\label{optparse-other-actions}}
-
-Some other actions supported by \module{optparse} are:
-\begin{description}
-\item[\code{store{\_}const}]
-store a constant value
-\item[\code{append}]
-append this option's argument to a list
-\item[\code{count}]
-increment a counter by one
-\item[\code{callback}]
-call a specified function
-\end{description}
-
-These are covered in section~\ref{optparse-reference-guide}, Reference Guide and section~\ref{optparse-option-callbacks}, Option Callbacks.
-
-
-\subsubsection{Default values\label{optparse-default-values}}
-
-All of the above examples involve setting some variable (the
-``destination'') when certain command-line options are seen. What happens
-if those options are never seen? Since we didn't supply any defaults,
-they are all set to \code{None}. This is usually fine, but sometimes you
-want more control. \module{optparse} lets you supply a default value for each
-destination, which is assigned before the command line is parsed.
-
-First, consider the verbose/quiet example. If we want \module{optparse} to set
-\code{verbose} to \code{True} unless \code{"-q"} is seen, then we can do this:
-\begin{verbatim}
-parser.add_option("-v", action="store_true", dest="verbose", default=True)
-parser.add_option("-q", action="store_false", dest="verbose")
-\end{verbatim}
-
-Since default values apply to the \emph{destination} rather than to any
-particular option, and these two options happen to have the same
-destination, this is exactly equivalent:
-\begin{verbatim}
-parser.add_option("-v", action="store_true", dest="verbose")
-parser.add_option("-q", action="store_false", dest="verbose", default=True)
-\end{verbatim}
-
-Consider this:
-\begin{verbatim}
-parser.add_option("-v", action="store_true", dest="verbose", default=False)
-parser.add_option("-q", action="store_false", dest="verbose", default=True)
-\end{verbatim}
-
-Again, the default value for \code{verbose} will be \code{True}: the last
-default value supplied for any particular destination is the one that
-counts.
-
-A clearer way to specify default values is the \method{set{\_}defaults()}
-method of OptionParser, which you can call at any time before calling
-\method{parse{\_}args()}:
-\begin{verbatim}
-parser.set_defaults(verbose=True)
-parser.add_option(...)
-(options, args) = parser.parse_args()
-\end{verbatim}
-
-As before, the last value specified for a given option destination is
-the one that counts. For clarity, try to use one method or the other of
-setting default values, not both.
-
-
-\subsubsection{Generating help\label{optparse-generating-help}}
-
-\module{optparse}'s ability to generate help and usage text automatically is useful
-for creating user-friendly command-line interfaces. All you have to do
-is supply a \member{help} value for each option, and optionally a short usage
-message for your whole program. Here's an OptionParser populated with
-user-friendly (documented) options:
-\begin{verbatim}
-usage = "usage: %prog [options] arg1 arg2"
-parser = OptionParser(usage=usage)
-parser.add_option("-v", "--verbose",
- action="store_true", dest="verbose", default=True,
- help="make lots of noise [default]")
-parser.add_option("-q", "--quiet",
- action="store_false", dest="verbose",
- help="be vewwy quiet (I'm hunting wabbits)")
-parser.add_option("-f", "--filename",
- metavar="FILE", help="write output to FILE"),
-parser.add_option("-m", "--mode",
- default="intermediate",
- help="interaction mode: novice, intermediate, "
- "or expert [default: %default]")
-\end{verbatim}
-
-If \module{optparse} encounters either \code{"-h"} or \code{"-{}-help"} on the command-line,
-or if you just call \method{parser.print{\_}help()}, it prints the following to
-standard output:
-\begin{verbatim}
-usage: <yourscript> [options] arg1 arg2
-
-options:
- -h, --help show this help message and exit
- -v, --verbose make lots of noise [default]
- -q, --quiet be vewwy quiet (I'm hunting wabbits)
- -f FILE, --filename=FILE
- write output to FILE
- -m MODE, --mode=MODE interaction mode: novice, intermediate, or
- expert [default: intermediate]
-\end{verbatim}
-
-(If the help output is triggered by a help option, \module{optparse} exits after
-printing the help text.)
-
-There's a lot going on here to help \module{optparse} generate the best possible
-help message:
-\begin{itemize}
-\item {}
-the script defines its own usage message:
-\begin{verbatim}
-usage = "usage: %prog [options] arg1 arg2"
-\end{verbatim}
-
-\module{optparse} expands \code{"{\%}prog"} in the usage string to the name of the current
-program, i.e. \code{os.path.basename(sys.argv{[}0])}. The expanded string
-is then printed before the detailed option help.
-
-If you don't supply a usage string, \module{optparse} uses a bland but sensible
-default: \code{"usage: {\%}prog {[}options]"}, which is fine if your script
-doesn't take any positional arguments.
-
-\item {}
-every option defines a help string, and doesn't worry about line-
-wrapping{---}\module{optparse} takes care of wrapping lines and making the
-help output look good.
-
-\item {}
-options that take a value indicate this fact in their
-automatically-generated help message, e.g. for the ``mode'' option:
-\begin{verbatim}
--m MODE, --mode=MODE
-\end{verbatim}
-
-Here, ``MODE'' is called the meta-variable: it stands for the argument
-that the user is expected to supply to \programopt{-m}/\longprogramopt{mode}. By default,
-\module{optparse} converts the destination variable name to uppercase and uses
-that for the meta-variable. Sometimes, that's not what you want{---}for example, the \longprogramopt{filename} option explicitly sets
-\code{metavar="FILE"}, resulting in this automatically-generated option
-description:
-\begin{verbatim}
--f FILE, --filename=FILE
-\end{verbatim}
-
-This is important for more than just saving space, though: the
-manually written help text uses the meta-variable ``FILE'' to clue the
-user in that there's a connection between the semi-formal syntax ``-f
-FILE'' and the informal semantic description ``write output to FILE''.
-This is a simple but effective way to make your help text a lot
-clearer and more useful for end users.
-
-\item {}
-options that have a default value can include \code{{\%}default} in
-the help string{---}\module{optparse} will replace it with \function{str()} of the
-option's default value. If an option has no default value (or the
-default value is \code{None}), \code{{\%}default} expands to \code{none}.
-
-\end{itemize}
-
-
-\subsubsection{Printing a version string\label{optparse-printing-version-string}}
-
-Similar to the brief usage string, \module{optparse} can also print a version string
-for your program. You have to supply the string as the \code{version}
-argument to OptionParser:
-\begin{verbatim}
-parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
-\end{verbatim}
-
-\code{"{\%}prog"} is expanded just like it is in \code{usage}. Apart
-from that, \code{version} can contain anything you like. When you supply
-it, \module{optparse} automatically adds a \code{"-{}-version"} option to your parser.
-If it encounters this option on the command line, it expands your
-\code{version} string (by replacing \code{"{\%}prog"}), prints it to stdout, and
-exits.
-
-For example, if your script is called \code{/usr/bin/foo}:
-\begin{verbatim}
-$ /usr/bin/foo --version
-foo 1.0
-\end{verbatim}
-
-
-\subsubsection{How \module{optparse} handles errors\label{optparse-how-optparse-handles-errors}}
-
-There are two broad classes of errors that \module{optparse} has to worry about:
-programmer errors and user errors. Programmer errors are usually
-erroneous calls to \code{parser.add{\_}option()}, e.g. invalid option strings,
-unknown option attributes, missing option attributes, etc. These are
-dealt with in the usual way: raise an exception (either
-\code{optparse.OptionError} or \code{TypeError}) and let the program crash.
-
-Handling user errors is much more important, since they are guaranteed
-to happen no matter how stable your code is. \module{optparse} can automatically
-detect some user errors, such as bad option arguments (passing \code{"-n
-4x"} where \programopt{-n} takes an integer argument), missing arguments
-(\code{"-n"} at the end of the command line, where \programopt{-n} takes an argument
-of any type). Also, you can call \code{parser.error()} to signal an
-application-defined error condition:
-\begin{verbatim}
-(options, args) = parser.parse_args()
-[...]
-if options.a and options.b:
- parser.error("options -a and -b are mutually exclusive")
-\end{verbatim}
-
-In either case, \module{optparse} handles the error the same way: it prints the
-program's usage message and an error message to standard error and
-exits with error status 2.
-
-Consider the first example above, where the user passes \code{"4x"} to an
-option that takes an integer:
-\begin{verbatim}
-$ /usr/bin/foo -n 4x
-usage: foo [options]
-
-foo: error: option -n: invalid integer value: '4x'
-\end{verbatim}
-
-Or, where the user fails to pass a value at all:
-\begin{verbatim}
-$ /usr/bin/foo -n
-usage: foo [options]
-
-foo: error: -n option requires an argument
-\end{verbatim}
-
-\module{optparse}-generated error messages take care always to mention the option
-involved in the error; be sure to do the same when calling
-\code{parser.error()} from your application code.
-
-If \module{optparse}'s default error-handling behaviour does not suite your needs,
-you'll need to subclass OptionParser and override \code{exit()} and/or
-\method{error()}.
-
-
-\subsubsection{Putting it all together\label{optparse-putting-it-all-together}}
-
-Here's what \module{optparse}-based scripts usually look like:
-\begin{verbatim}
-from optparse import OptionParser
-[...]
-def main():
- usage = "usage: %prog [options] arg"
- parser = OptionParser(usage)
- parser.add_option("-f", "--file", dest="filename",
- help="read data from FILENAME")
- parser.add_option("-v", "--verbose",
- action="store_true", dest="verbose")
- parser.add_option("-q", "--quiet",
- action="store_false", dest="verbose")
- [...]
- (options, args) = parser.parse_args()
- if len(args) != 1:
- parser.error("incorrect number of arguments")
- if options.verbose:
- print "reading %s..." % options.filename
- [...]
-
-if __name__ == "__main__":
- main()
-\end{verbatim}
-% $Id: tutorial.txt 515 2006-06-10 15:37:45Z gward $
-
-
-\subsection{Reference Guide\label{optparse-reference-guide}}
-
-
-\subsubsection{Creating the parser\label{optparse-creating-parser}}
-
-The first step in using \module{optparse} is to create an OptionParser instance:
-\begin{verbatim}
-parser = OptionParser(...)
-\end{verbatim}
-
-The OptionParser constructor has no required arguments, but a number of
-optional keyword arguments. You should always pass them as keyword
-arguments, i.e. do not rely on the order in which the arguments are
-declared.
-\begin{quote}
-\begin{description}
-\item[\code{usage} (default: \code{"{\%}prog {[}options]"})]
-The usage summary to print when your program is run incorrectly or
-with a help option. When \module{optparse} prints the usage string, it expands
-\code{{\%}prog} to \code{os.path.basename(sys.argv{[}0])} (or to \code{prog} if
-you passed that keyword argument). To suppress a usage message,
-pass the special value \code{optparse.SUPPRESS{\_}USAGE}.
-\item[\code{option{\_}list} (default: \code{{[}]})]
-A list of Option objects to populate the parser with. The options
-in \code{option{\_}list} are added after any options in
-\code{standard{\_}option{\_}list} (a class attribute that may be set by
-OptionParser subclasses), but before any version or help options.
-Deprecated; use \method{add{\_}option()} after creating the parser instead.
-\item[\code{option{\_}class} (default: optparse.Option)]
-Class to use when adding options to the parser in \method{add{\_}option()}.
-\item[\code{version} (default: \code{None})]
-A version string to print when the user supplies a version option.
-If you supply a true value for \code{version}, \module{optparse} automatically adds
-a version option with the single option string \code{"-{}-version"}. The
-substring \code{"{\%}prog"} is expanded the same as for \code{usage}.
-\item[\code{conflict{\_}handler} (default: \code{"error"})]
-Specifies what to do when options with conflicting option strings
-are added to the parser; see section~\ref{optparse-conflicts-between-options}, Conflicts between options.
-\item[\code{description} (default: \code{None})]
-A paragraph of text giving a brief overview of your program. \module{optparse}
-reformats this paragraph to fit the current terminal width and
-prints it when the user requests help (after \code{usage}, but before
-the list of options).
-\item[\code{formatter} (default: a new IndentedHelpFormatter)]
-An instance of optparse.HelpFormatter that will be used for
-printing help text. \module{optparse} provides two concrete classes for this
-purpose: IndentedHelpFormatter and TitledHelpFormatter.
-\item[\code{add{\_}help{\_}option} (default: \code{True})]
-If true, \module{optparse} will add a help option (with option strings \code{"-h"}
-and \code{"-{}-help"}) to the parser.
-\item[\code{prog}]
-The string to use when expanding \code{"{\%}prog"} in \code{usage} and
-\code{version} instead of \code{os.path.basename(sys.argv{[}0])}.
-\end{description}
-\end{quote}
-
-
-\subsubsection{Populating the parser\label{optparse-populating-parser}}
-
-There are several ways to populate the parser with options. The
-preferred way is by using \code{OptionParser.add{\_}option()}, as shown in
-section~\ref{optparse-tutorial}, the tutorial. \method{add{\_}option()} can be called in one of two
-ways:
-\begin{itemize}
-\item {}
-pass it an Option instance (as returned by \function{make{\_}option()})
-
-\item {}
-pass it any combination of positional and keyword arguments that are
-acceptable to \function{make{\_}option()} (i.e., to the Option constructor),
-and it will create the Option instance for you
-
-\end{itemize}
-
-The other alternative is to pass a list of pre-constructed Option
-instances to the OptionParser constructor, as in:
-\begin{verbatim}
-option_list = [
- make_option("-f", "--filename",
- action="store", type="string", dest="filename"),
- make_option("-q", "--quiet",
- action="store_false", dest="verbose"),
- ]
-parser = OptionParser(option_list=option_list)
-\end{verbatim}
-
-(\function{make{\_}option()} is a factory function for creating Option instances;
-currently it is an alias for the Option constructor. A future version
-of \module{optparse} may split Option into several classes, and \function{make{\_}option()}
-will pick the right class to instantiate. Do not instantiate Option
-directly.)
-
-
-\subsubsection{Defining options\label{optparse-defining-options}}
-
-Each Option instance represents a set of synonymous command-line option
-strings, e.g. \programopt{-f} and \longprogramopt{file}. You can
-specify any number of short or long option strings, but you must specify
-at least one overall option string.
-
-The canonical way to create an Option instance is with the
-\method{add{\_}option()} method of \class{OptionParser}:
-\begin{verbatim}
-parser.add_option(opt_str[, ...], attr=value, ...)
-\end{verbatim}
-
-To define an option with only a short option string:
-\begin{verbatim}
-parser.add_option("-f", attr=value, ...)
-\end{verbatim}
-
-And to define an option with only a long option string:
-\begin{verbatim}
-parser.add_option("--foo", attr=value, ...)
-\end{verbatim}
-
-The keyword arguments define attributes of the new Option object. The
-most important option attribute is \member{action}, and it largely determines
-which other attributes are relevant or required. If you pass irrelevant
-option attributes, or fail to pass required ones, \module{optparse} raises an
-OptionError exception explaining your mistake.
-
-An options's \emph{action} determines what \module{optparse} does when it encounters this
-option on the command-line. The standard option actions hard-coded into
-\module{optparse} are:
-\begin{description}
-\item[\code{store}]
-store this option's argument (default)
-\item[\code{store{\_}const}]
-store a constant value
-\item[\code{store{\_}true}]
-store a true value
-\item[\code{store{\_}false}]
-store a false value
-\item[\code{append}]
-append this option's argument to a list
-\item[\code{append{\_}const}]
-append a constant value to a list
-\item[\code{count}]
-increment a counter by one
-\item[\code{callback}]
-call a specified function
-\item[\member{help}]
-print a usage message including all options and the
-documentation for them
-\end{description}
-
-(If you don't supply an action, the default is \code{store}. For this
-action, you may also supply \member{type} and \member{dest} option attributes; see
-below.)
-
-As you can see, most actions involve storing or updating a value
-somewhere. \module{optparse} always creates a special object for this,
-conventionally called \code{options} (it happens to be an instance of
-\code{optparse.Values}). Option arguments (and various other values) are
-stored as attributes of this object, according to the \member{dest}
-(destination) option attribute.
-
-For example, when you call
-\begin{verbatim}
-parser.parse_args()
-\end{verbatim}
-
-one of the first things \module{optparse} does is create the \code{options} object:
-\begin{verbatim}
-options = Values()
-\end{verbatim}
-
-If one of the options in this parser is defined with
-\begin{verbatim}
-parser.add_option("-f", "--file", action="store", type="string", dest="filename")
-\end{verbatim}
-
-and the command-line being parsed includes any of the following:
-\begin{verbatim}
--ffoo
--f foo
---file=foo
---file foo
-\end{verbatim}
-
-then \module{optparse}, on seeing this option, will do the equivalent of
-\begin{verbatim}
-options.filename = "foo"
-\end{verbatim}
-
-The \member{type} and \member{dest} option attributes are almost as important as
-\member{action}, but \member{action} is the only one that makes sense for \emph{all}
-options.
-
-
-\subsubsection{Standard option actions\label{optparse-standard-option-actions}}
-
-The various option actions all have slightly different requirements and
-effects. Most actions have several relevant option attributes which you
-may specify to guide \module{optparse}'s behaviour; a few have required attributes,
-which you must specify for any option using that action.
-\begin{itemize}
-\item {}
-\code{store} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}]
-
-The option must be followed by an argument, which is
-converted to a value according to \member{type} and stored in
-\member{dest}. If \code{nargs} {\textgreater} 1, multiple arguments will be consumed
-from the command line; all will be converted according to
-\member{type} and stored to \member{dest} as a tuple. See the ``Option
-types'' section below.
-
-If \code{choices} is supplied (a list or tuple of strings), the type
-defaults to \code{choice}.
-
-If \member{type} is not supplied, it defaults to \code{string}.
-
-If \member{dest} is not supplied, \module{optparse} derives a destination from the
-first long option string (e.g., \code{"-{}-foo-bar"} implies \code{foo{\_}bar}).
-If there are no long option strings, \module{optparse} derives a destination from
-the first short option string (e.g., \code{"-f"} implies \code{f}).
-
-Example:
-\begin{verbatim}
-parser.add_option("-f")
-parser.add_option("-p", type="float", nargs=3, dest="point")
-\end{verbatim}
-
-As it parses the command line
-\begin{verbatim}
--f foo.txt -p 1 -3.5 4 -fbar.txt
-\end{verbatim}
-
-\module{optparse} will set
-\begin{verbatim}
-options.f = "foo.txt"
-options.point = (1.0, -3.5, 4.0)
-options.f = "bar.txt"
-\end{verbatim}
-
-\item {}
-\code{store{\_}const} {[}required: \code{const}; relevant: \member{dest}]
-
-The value \code{const} is stored in \member{dest}.
-
-Example:
-\begin{verbatim}
-parser.add_option("-q", "--quiet",
- action="store_const", const=0, dest="verbose")
-parser.add_option("-v", "--verbose",
- action="store_const", const=1, dest="verbose")
-parser.add_option("--noisy",
- action="store_const", const=2, dest="verbose")
-\end{verbatim}
-
-If \code{"-{}-noisy"} is seen, \module{optparse} will set
-\begin{verbatim}
-options.verbose = 2
-\end{verbatim}
-
-\item {}
-\code{store{\_}true} {[}relevant: \member{dest}]
-
-A special case of \code{store{\_}const} that stores a true value
-to \member{dest}.
-
-\item {}
-\code{store{\_}false} {[}relevant: \member{dest}]
-
-Like \code{store{\_}true}, but stores a false value.
-
-Example:
-\begin{verbatim}
-parser.add_option("--clobber", action="store_true", dest="clobber")
-parser.add_option("--no-clobber", action="store_false", dest="clobber")
-\end{verbatim}
-
-\item {}
-\code{append} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}]
-
-The option must be followed by an argument, which is appended to the
-list in \member{dest}. If no default value for \member{dest} is supplied, an
-empty list is automatically created when \module{optparse} first encounters this
-option on the command-line. If \code{nargs} {\textgreater} 1, multiple arguments are
-consumed, and a tuple of length \code{nargs} is appended to \member{dest}.
-
-The defaults for \member{type} and \member{dest} are the same as for the
-\code{store} action.
-
-Example:
-\begin{verbatim}
-parser.add_option("-t", "--tracks", action="append", type="int")
-\end{verbatim}
-
-If \code{"-t3"} is seen on the command-line, \module{optparse} does the equivalent of:
-\begin{verbatim}
-options.tracks = []
-options.tracks.append(int("3"))
-\end{verbatim}
-
-If, a little later on, \code{"-{}-tracks=4"} is seen, it does:
-\begin{verbatim}
-options.tracks.append(int("4"))
-\end{verbatim}
-
-\item {}
-\code{append{\_}const} {[}required: \code{const}; relevant: \member{dest}]
-
-Like \code{store{\_}const}, but the value \code{const} is appended to \member{dest};
-as with \code{append}, \member{dest} defaults to \code{None}, and an an empty list is
-automatically created the first time the option is encountered.
-
-\item {}
-\code{count} {[}relevant: \member{dest}]
-
-Increment the integer stored at \member{dest}. If no default value is
-supplied, \member{dest} is set to zero before being incremented the first
-time.
-
-Example:
-\begin{verbatim}
-parser.add_option("-v", action="count", dest="verbosity")
-\end{verbatim}
-
-The first time \code{"-v"} is seen on the command line, \module{optparse} does the
-equivalent of:
-\begin{verbatim}
-options.verbosity = 0
-options.verbosity += 1
-\end{verbatim}
-
-Every subsequent occurrence of \code{"-v"} results in
-\begin{verbatim}
-options.verbosity += 1
-\end{verbatim}
-
-\item {}
-\code{callback} {[}required: \code{callback};
-relevant: \member{type}, \code{nargs}, \code{callback{\_}args}, \code{callback{\_}kwargs}]
-
-Call the function specified by \code{callback}, which is called as
-\begin{verbatim}
-func(option, opt_str, value, parser, *args, **kwargs)
-\end{verbatim}
-
-See section~\ref{optparse-option-callbacks}, Option Callbacks for more detail.
-
-\item {}
-\member{help}
-
-Prints a complete help message for all the options in the
-current option parser. The help message is constructed from
-the \code{usage} string passed to OptionParser's constructor and
-the \member{help} string passed to every option.
-
-If no \member{help} string is supplied for an option, it will still be
-listed in the help message. To omit an option entirely, use
-the special value \code{optparse.SUPPRESS{\_}HELP}.
-
-\module{optparse} automatically adds a \member{help} option to all OptionParsers, so
-you do not normally need to create one.
-
-Example:
-\begin{verbatim}
-from optparse import OptionParser, SUPPRESS_HELP
-
-parser = OptionParser()
-parser.add_option("-h", "--help", action="help"),
-parser.add_option("-v", action="store_true", dest="verbose",
- help="Be moderately verbose")
-parser.add_option("--file", dest="filename",
- help="Input file to read data from"),
-parser.add_option("--secret", help=SUPPRESS_HELP)
-\end{verbatim}
-
-If \module{optparse} sees either \code{"-h"} or \code{"-{}-help"} on the command line, it
-will print something like the following help message to stdout
-(assuming \code{sys.argv{[}0]} is \code{"foo.py"}):
-\begin{verbatim}
-usage: foo.py [options]
-
-options:
- -h, --help Show this help message and exit
- -v Be moderately verbose
- --file=FILENAME Input file to read data from
-\end{verbatim}
-
-After printing the help message, \module{optparse} terminates your process
-with \code{sys.exit(0)}.
-
-\item {}
-\code{version}
-
-Prints the version number supplied to the OptionParser to stdout and
-exits. The version number is actually formatted and printed by the
-\code{print{\_}version()} method of OptionParser. Generally only relevant
-if the \code{version} argument is supplied to the OptionParser
-constructor. As with \member{help} options, you will rarely create
-\code{version} options, since \module{optparse} automatically adds them when needed.
-
-\end{itemize}
-
-
-\subsubsection{Option attributes\label{optparse-option-attributes}}
-
-The following option attributes may be passed as keyword arguments
-to \code{parser.add{\_}option()}. If you pass an option attribute
-that is not relevant to a particular option, or fail to pass a required
-option attribute, \module{optparse} raises OptionError.
-\begin{itemize}
-\item {}
-\member{action} (default: \code{"store"})
-
-Determines \module{optparse}'s behaviour when this option is seen on the command
-line; the available options are documented above.
-
-\item {}
-\member{type} (default: \code{"string"})
-
-The argument type expected by this option (e.g., \code{"string"} or
-\code{"int"}); the available option types are documented below.
-
-\item {}
-\member{dest} (default: derived from option strings)
-
-If the option's action implies writing or modifying a value somewhere,
-this tells \module{optparse} where to write it: \member{dest} names an attribute of the
-\code{options} object that \module{optparse} builds as it parses the command line.
-
-\item {}
-\code{default} (deprecated)
-
-The value to use for this option's destination if the option is not
-seen on the command line. Deprecated; use \code{parser.set{\_}defaults()}
-instead.
-
-\item {}
-\code{nargs} (default: 1)
-
-How many arguments of type \member{type} should be consumed when this
-option is seen. If {\textgreater} 1, \module{optparse} will store a tuple of values to
-\member{dest}.
-
-\item {}
-\code{const}
-
-For actions that store a constant value, the constant value to store.
-
-\item {}
-\code{choices}
-
-For options of type \code{"choice"}, the list of strings the user
-may choose from.
-
-\item {}
-\code{callback}
-
-For options with action \code{"callback"}, the callable to call when this
-option is seen. See section~\ref{optparse-option-callbacks}, Option Callbacks for detail on the arguments
-passed to \code{callable}.
-
-\item {}
-\code{callback{\_}args}, \code{callback{\_}kwargs}
-
-Additional positional and keyword arguments to pass to \code{callback}
-after the four standard callback arguments.
-
-\item {}
-\member{help}
-
-Help text to print for this option when listing all available options
-after the user supplies a \member{help} option (such as \code{"-{}-help"}).
-If no help text is supplied, the option will be listed without help
-text. To hide this option, use the special value \code{SUPPRESS{\_}HELP}.
-
-\item {}
-\code{metavar} (default: derived from option strings)
-
-Stand-in for the option argument(s) to use when printing help text.
-See section~\ref{optparse-tutorial}, the tutorial for an example.
-
-\end{itemize}
-
-
-\subsubsection{Standard option types\label{optparse-standard-option-types}}
-
-\module{optparse} has six built-in option types: \code{string}, \code{int}, \code{long},
-\code{choice}, \code{float} and \code{complex}. If you need to add new option
-types, see section~\ref{optparse-extending-optparse}, Extending \module{optparse}.
-
-Arguments to string options are not checked or converted in any way: the
-text on the command line is stored in the destination (or passed to the
-callback) as-is.
-
-Integer arguments (type \code{int} or \code{long}) are parsed as follows:
-\begin{quote}
-\begin{itemize}
-\item {}
-if the number starts with \code{0x}, it is parsed as a hexadecimal number
-
-\item {}
-if the number starts with \code{0}, it is parsed as an octal number
-
-\item {}
-if the number starts with \code{0b}, is is parsed as a binary number
-
-\item {}
-otherwise, the number is parsed as a decimal number
-
-\end{itemize}
-\end{quote}
-
-The conversion is done by calling either \code{int()} or \code{long()} with
-the appropriate base (2, 8, 10, or 16). If this fails, so will \module{optparse},
-although with a more useful error message.
-
-\code{float} and \code{complex} option arguments are converted directly with
-\code{float()} and \code{complex()}, with similar error-handling.
-
-\code{choice} options are a subtype of \code{string} options. The \code{choices}
-option attribute (a sequence of strings) defines the set of allowed
-option arguments. \code{optparse.check{\_}choice()} compares
-user-supplied option arguments against this master list and raises
-OptionValueError if an invalid string is given.
-
-
-\subsubsection{Parsing arguments\label{optparse-parsing-arguments}}
-
-The whole point of creating and populating an OptionParser is to call
-its \method{parse{\_}args()} method:
-\begin{verbatim}
-(options, args) = parser.parse_args(args=None, values=None)
-\end{verbatim}
-
-where the input parameters are
-\begin{description}
-\item[\code{args}]
-the list of arguments to process (default: \code{sys.argv{[}1:]})
-\item[\code{values}]
-object to store option arguments in (default: a new instance of
-optparse.Values)
-\end{description}
-
-and the return values are
-\begin{description}
-\item[\code{options}]
-the same object that was passed in as \code{options}, or the
-optparse.Values instance created by \module{optparse}
-\item[\code{args}]
-the leftover positional arguments after all options have been
-processed
-\end{description}
-
-The most common usage is to supply neither keyword argument. If you
-supply \code{options}, it will be modified with repeated \code{setattr()}
-calls (roughly one for every option argument stored to an option
-destination) and returned by \method{parse{\_}args()}.
-
-If \method{parse{\_}args()} encounters any errors in the argument list, it calls
-the OptionParser's \method{error()} method with an appropriate end-user error
-message. This ultimately terminates your process with an exit status of
-2 (the traditional \UNIX{} exit status for command-line errors).
-
-
-\subsubsection{Querying and manipulating your option parser\label{optparse-querying-manipulating-option-parser}}
-
-Sometimes, it's useful to poke around your option parser and see what's
-there. OptionParser provides a couple of methods to help you out:
-\begin{description}
-\item[\code{has{\_}option(opt{\_}str)}]
-Return true if the OptionParser has an option with
-option string \code{opt{\_}str} (e.g., \code{"-q"} or \code{"-{}-verbose"}).
-\item[\code{get{\_}option(opt{\_}str)}]
-Returns the Option instance with the option string \code{opt{\_}str}, or
-\code{None} if no options have that option string.
-\item[\code{remove{\_}option(opt{\_}str)}]
-If the OptionParser has an option corresponding to \code{opt{\_}str},
-that option is removed. If that option provided any other
-option strings, all of those option strings become invalid.
-If \code{opt{\_}str} does not occur in any option belonging to this
-OptionParser, raises ValueError.
-\end{description}
-
-
-\subsubsection{Conflicts between options\label{optparse-conflicts-between-options}}
-
-If you're not careful, it's easy to define options with conflicting
-option strings:
-\begin{verbatim}
-parser.add_option("-n", "--dry-run", ...)
-[...]
-parser.add_option("-n", "--noisy", ...)
-\end{verbatim}
-
-(This is particularly true if you've defined your own OptionParser
-subclass with some standard options.)
-
-Every time you add an option, \module{optparse} checks for conflicts with existing
-options. If it finds any, it invokes the current conflict-handling
-mechanism. You can set the conflict-handling mechanism either in the
-constructor:
-\begin{verbatim}
-parser = OptionParser(..., conflict_handler=handler)
-\end{verbatim}
-
-or with a separate call:
-\begin{verbatim}
-parser.set_conflict_handler(handler)
-\end{verbatim}
-
-The available conflict handlers are:
-\begin{quote}
-\begin{description}
-\item[\code{error} (default)]
-assume option conflicts are a programming error and raise
-OptionConflictError
-\item[\code{resolve}]
-resolve option conflicts intelligently (see below)
-\end{description}
-\end{quote}
-
-As an example, let's define an OptionParser that resolves conflicts
-intelligently and add conflicting options to it:
-\begin{verbatim}
-parser = OptionParser(conflict_handler="resolve")
-parser.add_option("-n", "--dry-run", ..., help="do no harm")
-parser.add_option("-n", "--noisy", ..., help="be noisy")
-\end{verbatim}
-
-At this point, \module{optparse} detects that a previously-added option is already
-using the \code{"-n"} option string. Since \code{conflict{\_}handler} is
-\code{"resolve"}, it resolves the situation by removing \code{"-n"} from the
-earlier option's list of option strings. Now \code{"-{}-dry-run"} is the
-only way for the user to activate that option. If the user asks for
-help, the help message will reflect that:
-\begin{verbatim}
-options:
- --dry-run do no harm
- [...]
- -n, --noisy be noisy
-\end{verbatim}
-
-It's possible to whittle away the option strings for a previously-added
-option until there are none left, and the user has no way of invoking
-that option from the command-line. In that case, \module{optparse} removes that
-option completely, so it doesn't show up in help text or anywhere else.
-Carrying on with our existing OptionParser:
-\begin{verbatim}
-parser.add_option("--dry-run", ..., help="new dry-run option")
-\end{verbatim}
-
-At this point, the original \programopt{-n/-{}-dry-run} option is no longer
-accessible, so \module{optparse} removes it, leaving this help text:
-\begin{verbatim}
-options:
- [...]
- -n, --noisy be noisy
- --dry-run new dry-run option
-\end{verbatim}
-
-
-\subsubsection{Cleanup\label{optparse-cleanup}}
-
-OptionParser instances have several cyclic references. This should not
-be a problem for Python's garbage collector, but you may wish to break
-the cyclic references explicitly by calling \code{destroy()} on your
-OptionParser once you are done with it. This is particularly useful in
-long-running applications where large object graphs are reachable from
-your OptionParser.
-
-
-\subsubsection{Other methods\label{optparse-other-methods}}
-
-OptionParser supports several other public methods:
-\begin{itemize}
-\item {}
-\code{set{\_}usage(usage)}
-
-Set the usage string according to the rules described above for the
-\code{usage} constructor keyword argument. Passing \code{None} sets the
-default usage string; use \code{SUPPRESS{\_}USAGE} to suppress a usage
-message.
-
-\item {}
-\code{enable{\_}interspersed{\_}args()}, \code{disable{\_}interspersed{\_}args()}
-
-Enable/disable positional arguments interspersed with options, similar
-to GNU getopt (enabled by default). For example, if \code{"-a"} and
-\code{"-b"} are both simple options that take no arguments, \module{optparse}
-normally accepts this syntax:
-\begin{verbatim}
-prog -a arg1 -b arg2
-\end{verbatim}
-
-and treats it as equivalent to
-\begin{verbatim}
-prog -a -b arg1 arg2
-\end{verbatim}
-
-To disable this feature, call \code{disable{\_}interspersed{\_}args()}. This
-restores traditional \UNIX{} syntax, where option parsing stops with the
-first non-option argument.
-
-\item {}
-\code{set{\_}defaults(dest=value, ...)}
-
-Set default values for several option destinations at once. Using
-\method{set{\_}defaults()} is the preferred way to set default values for
-options, since multiple options can share the same destination. For
-example, if several ``mode'' options all set the same destination, any
-one of them can set the default, and the last one wins:
-\begin{verbatim}
-parser.add_option("--advanced", action="store_const",
- dest="mode", const="advanced",
- default="novice") # overridden below
-parser.add_option("--novice", action="store_const",
- dest="mode", const="novice",
- default="advanced") # overrides above setting
-\end{verbatim}
-
-To avoid this confusion, use \method{set{\_}defaults()}:
-\begin{verbatim}
-parser.set_defaults(mode="advanced")
-parser.add_option("--advanced", action="store_const",
- dest="mode", const="advanced")
-parser.add_option("--novice", action="store_const",
- dest="mode", const="novice")
-\end{verbatim}
-
-\end{itemize}
-% $Id: reference.txt 519 2006-06-11 14:39:11Z gward $
-
-
-\subsection{Option Callbacks\label{optparse-option-callbacks}}
-
-When \module{optparse}'s built-in actions and types aren't quite enough for your
-needs, you have two choices: extend \module{optparse} or define a callback option.
-Extending \module{optparse} is more general, but overkill for a lot of simple
-cases. Quite often a simple callback is all you need.
-
-There are two steps to defining a callback option:
-\begin{itemize}
-\item {}
-define the option itself using the \code{callback} action
-
-\item {}
-write the callback; this is a function (or method) that
-takes at least four arguments, as described below
-
-\end{itemize}
-
-
-\subsubsection{Defining a callback option\label{optparse-defining-callback-option}}
-
-As always, the easiest way to define a callback option is by using the
-\code{parser.add{\_}option()} method. Apart from \member{action}, the only option
-attribute you must specify is \code{callback}, the function to call:
-\begin{verbatim}
-parser.add_option("-c", action="callback", callback=my_callback)
-\end{verbatim}
-
-\code{callback} is a function (or other callable object), so you must have
-already defined \code{my{\_}callback()} when you create this callback option.
-In this simple case, \module{optparse} doesn't even know if \programopt{-c} takes any
-arguments, which usually means that the option takes no arguments{---}the
-mere presence of \programopt{-c} on the command-line is all it needs to know. In
-some circumstances, though, you might want your callback to consume an
-arbitrary number of command-line arguments. This is where writing
-callbacks gets tricky; it's covered later in this section.
-
-\module{optparse} always passes four particular arguments to your callback, and it
-will only pass additional arguments if you specify them via
-\code{callback{\_}args} and \code{callback{\_}kwargs}. Thus, the minimal callback
-function signature is:
-\begin{verbatim}
-def my_callback(option, opt, value, parser):
-\end{verbatim}
-
-The four arguments to a callback are described below.
-
-There are several other option attributes that you can supply when you
-define a callback option:
-\begin{description}
-\item[\member{type}]
-has its usual meaning: as with the \code{store} or \code{append} actions,
-it instructs \module{optparse} to consume one argument and convert it to
-\member{type}. Rather than storing the converted value(s) anywhere,
-though, \module{optparse} passes it to your callback function.
-\item[\code{nargs}]
-also has its usual meaning: if it is supplied and {\textgreater} 1, \module{optparse} will
-consume \code{nargs} arguments, each of which must be convertible to
-\member{type}. It then passes a tuple of converted values to your
-callback.
-\item[\code{callback{\_}args}]
-a tuple of extra positional arguments to pass to the callback
-\item[\code{callback{\_}kwargs}]
-a dictionary of extra keyword arguments to pass to the callback
-\end{description}
-
-
-\subsubsection{How callbacks are called\label{optparse-how-callbacks-called}}
-
-All callbacks are called as follows:
-\begin{verbatim}
-func(option, opt_str, value, parser, *args, **kwargs)
-\end{verbatim}
-
-where
-\begin{description}
-\item[\code{option}]
-is the Option instance that's calling the callback
-\item[\code{opt{\_}str}]
-is the option string seen on the command-line that's triggering the
-callback. (If an abbreviated long option was used, \code{opt{\_}str} will
-be the full, canonical option string{---}e.g. if the user puts
-\code{"-{}-foo"} on the command-line as an abbreviation for
-\code{"-{}-foobar"}, then \code{opt{\_}str} will be \code{"-{}-foobar"}.)
-\item[\code{value}]
-is the argument to this option seen on the command-line. \module{optparse} will
-only expect an argument if \member{type} is set; the type of \code{value}
-will be the type implied by the option's type. If \member{type} for this
-option is \code{None} (no argument expected), then \code{value} will be
-\code{None}. If \code{nargs} {\textgreater} 1, \code{value} will be a tuple of values of
-the appropriate type.
-\item[\code{parser}]
-is the OptionParser instance driving the whole thing, mainly
-useful because you can access some other interesting data through
-its instance attributes:
-\begin{description}
-\item[\code{parser.largs}]
-the current list of leftover arguments, ie. arguments that have
-been consumed but are neither options nor option arguments.
-Feel free to modify \code{parser.largs}, e.g. by adding more
-arguments to it. (This list will become \code{args}, the second
-return value of \method{parse{\_}args()}.)
-\item[\code{parser.rargs}]
-the current list of remaining arguments, ie. with \code{opt{\_}str} and
-\code{value} (if applicable) removed, and only the arguments
-following them still there. Feel free to modify
-\code{parser.rargs}, e.g. by consuming more arguments.
-\item[\code{parser.values}]
-the object where option values are by default stored (an
-instance of optparse.OptionValues). This lets callbacks use the
-same mechanism as the rest of \module{optparse} for storing option values;
-you don't need to mess around with globals or closures. You can
-also access or modify the value(s) of any options already
-encountered on the command-line.
-\end{description}
-\item[\code{args}]
-is a tuple of arbitrary positional arguments supplied via the
-\code{callback{\_}args} option attribute.
-\item[\code{kwargs}]
-is a dictionary of arbitrary keyword arguments supplied via
-\code{callback{\_}kwargs}.
-\end{description}
-
-
-\subsubsection{Raising errors in a callback\label{optparse-raising-errors-in-callback}}
-
-The callback function should raise OptionValueError if there are any
-problems with the option or its argument(s). \module{optparse} catches this and
-terminates the program, printing the error message you supply to
-stderr. Your message should be clear, concise, accurate, and mention
-the option at fault. Otherwise, the user will have a hard time
-figuring out what he did wrong.
-
-
-\subsubsection{Callback example 1: trivial callback\label{optparse-callback-example-1}}
-
-Here's an example of a callback option that takes no arguments, and
-simply records that the option was seen:
-\begin{verbatim}
-def record_foo_seen(option, opt_str, value, parser):
- parser.saw_foo = True
-
-parser.add_option("--foo", action="callback", callback=record_foo_seen)
-\end{verbatim}
-
-Of course, you could do that with the \code{store{\_}true} action.
-
-
-\subsubsection{Callback example 2: check option order\label{optparse-callback-example-2}}
-
-Here's a slightly more interesting example: record the fact that
-\code{"-a"} is seen, but blow up if it comes after \code{"-b"} in the
-command-line.
-\begin{verbatim}
-def check_order(option, opt_str, value, parser):
- if parser.values.b:
- raise OptionValueError("can't use -a after -b")
- parser.values.a = 1
-[...]
-parser.add_option("-a", action="callback", callback=check_order)
-parser.add_option("-b", action="store_true", dest="b")
-\end{verbatim}
-
-
-\subsubsection{Callback example 3: check option order (generalized)\label{optparse-callback-example-3}}
-
-If you want to re-use this callback for several similar options (set a
-flag, but blow up if \code{"-b"} has already been seen), it needs a bit of
-work: the error message and the flag that it sets must be
-generalized.
-\begin{verbatim}
-def check_order(option, opt_str, value, parser):
- if parser.values.b:
- raise OptionValueError("can't use %s after -b" % opt_str)
- setattr(parser.values, option.dest, 1)
-[...]
-parser.add_option("-a", action="callback", callback=check_order, dest='a')
-parser.add_option("-b", action="store_true", dest="b")
-parser.add_option("-c", action="callback", callback=check_order, dest='c')
-\end{verbatim}
-
-
-\subsubsection{Callback example 4: check arbitrary condition\label{optparse-callback-example-4}}
-
-Of course, you could put any condition in there{---}you're not limited
-to checking the values of already-defined options. For example, if
-you have options that should not be called when the moon is full, all
-you have to do is this:
-\begin{verbatim}
-def check_moon(option, opt_str, value, parser):
- if is_moon_full():
- raise OptionValueError("%s option invalid when moon is full"
- % opt_str)
- setattr(parser.values, option.dest, 1)
-[...]
-parser.add_option("--foo",
- action="callback", callback=check_moon, dest="foo")
-\end{verbatim}
-
-(The definition of \code{is{\_}moon{\_}full()} is left as an exercise for the
-reader.)
-
-
-\subsubsection{Callback example 5: fixed arguments\label{optparse-callback-example-5}}
-
-Things get slightly more interesting when you define callback options
-that take a fixed number of arguments. Specifying that a callback
-option takes arguments is similar to defining a \code{store} or \code{append}
-option: if you define \member{type}, then the option takes one argument that
-must be convertible to that type; if you further define \code{nargs}, then
-the option takes \code{nargs} arguments.
-
-Here's an example that just emulates the standard \code{store} action:
-\begin{verbatim}
-def store_value(option, opt_str, value, parser):
- setattr(parser.values, option.dest, value)
-[...]
-parser.add_option("--foo",
- action="callback", callback=store_value,
- type="int", nargs=3, dest="foo")
-\end{verbatim}
-
-Note that \module{optparse} takes care of consuming 3 arguments and converting them
-to integers for you; all you have to do is store them. (Or whatever;
-obviously you don't need a callback for this example.)
-
-
-\subsubsection{Callback example 6: variable arguments\label{optparse-callback-example-6}}
-
-Things get hairy when you want an option to take a variable number of
-arguments. For this case, you must write a callback, as \module{optparse} doesn't
-provide any built-in capabilities for it. And you have to deal with
-certain intricacies of conventional \UNIX{} command-line parsing that \module{optparse}
-normally handles for you. In particular, callbacks should implement
-the conventional rules for bare \code{"-{}-"} and \code{"-"} arguments:
-\begin{itemize}
-\item {}
-either \code{"-{}-"} or \code{"-"} can be option arguments
-
-\item {}
-bare \code{"-{}-"} (if not the argument to some option): halt command-line
-processing and discard the \code{"-{}-"}
-
-\item {}
-bare \code{"-"} (if not the argument to some option): halt command-line
-processing but keep the \code{"-"} (append it to \code{parser.largs})
-
-\end{itemize}
-
-If you want an option that takes a variable number of arguments, there
-are several subtle, tricky issues to worry about. The exact
-implementation you choose will be based on which trade-offs you're
-willing to make for your application (which is why \module{optparse} doesn't support
-this sort of thing directly).
-
-Nevertheless, here's a stab at a callback for an option with variable
-arguments:
-\begin{verbatim}
-def vararg_callback(option, opt_str, value, parser):
- assert value is None
- done = 0
- value = []
- rargs = parser.rargs
- while rargs:
- arg = rargs[0]
-
- # Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f",
- # etc. Note that this also stops on "-3" or "-3.0", so if
- # your option takes numeric values, you will need to handle
- # this.
- if ((arg[:2] == "--" and len(arg) > 2) or
- (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")):
- break
- else:
- value.append(arg)
- del rargs[0]
-
- setattr(parser.values, option.dest, value)
-
-[...]
-parser.add_option("-c", "--callback",
- action="callback", callback=varargs)
-\end{verbatim}
-
-The main weakness with this particular implementation is that negative
-numbers in the arguments following \code{"-c"} will be interpreted as
-further options (probably causing an error), rather than as arguments to
-\code{"-c"}. Fixing this is left as an exercise for the reader.
-% $Id: callbacks.txt 415 2004-09-30 02:26:17Z greg $
-
-
-\subsection{Extending \module{optparse}\label{optparse-extending-optparse}}
-
-Since the two major controlling factors in how \module{optparse} interprets
-command-line options are the action and type of each option, the most
-likely direction of extension is to add new actions and new types.
-
-
-\subsubsection{Adding new types\label{optparse-adding-new-types}}
-
-To add new types, you need to define your own subclass of \module{optparse}'s Option
-class. This class has a couple of attributes that define \module{optparse}'s types:
-\member{TYPES} and \member{TYPE{\_}CHECKER}.
-
-\member{TYPES} is a tuple of type names; in your subclass, simply define a new
-tuple \member{TYPES} that builds on the standard one.
-
-\member{TYPE{\_}CHECKER} is a dictionary mapping type names to type-checking
-functions. A type-checking function has the following signature:
-\begin{verbatim}
-def check_mytype(option, opt, value)
-\end{verbatim}
-
-where \code{option} is an \class{Option} instance, \code{opt} is an option string
-(e.g., \code{"-f"}), and \code{value} is the string from the command line that
-must be checked and converted to your desired type. \code{check{\_}mytype()}
-should return an object of the hypothetical type \code{mytype}. The value
-returned by a type-checking function will wind up in the OptionValues
-instance returned by \method{OptionParser.parse{\_}args()}, or be passed to a
-callback as the \code{value} parameter.
-
-Your type-checking function should raise OptionValueError if it
-encounters any problems. OptionValueError takes a single string
-argument, which is passed as-is to OptionParser's \method{error()} method,
-which in turn prepends the program name and the string \code{"error:"} and
-prints everything to stderr before terminating the process.
-
-Here's a silly example that demonstrates adding a \code{complex} option
-type to parse Python-style complex numbers on the command line. (This
-is even sillier than it used to be, because \module{optparse} 1.3 added built-in
-support for complex numbers, but never mind.)
-
-First, the necessary imports:
-\begin{verbatim}
-from copy import copy
-from optparse import Option, OptionValueError
-\end{verbatim}
-
-You need to define your type-checker first, since it's referred to later
-(in the \member{TYPE{\_}CHECKER} class attribute of your Option subclass):
-\begin{verbatim}
-def check_complex(option, opt, value):
- try:
- return complex(value)
- except ValueError:
- raise OptionValueError(
- "option %s: invalid complex value: %r" % (opt, value))
-\end{verbatim}
-
-Finally, the Option subclass:
-\begin{verbatim}
-class MyOption (Option):
- TYPES = Option.TYPES + ("complex",)
- TYPE_CHECKER = copy(Option.TYPE_CHECKER)
- TYPE_CHECKER["complex"] = check_complex
-\end{verbatim}
-
-(If we didn't make a \function{copy()} of \member{Option.TYPE{\_}CHECKER}, we would end
-up modifying the \member{TYPE{\_}CHECKER} attribute of \module{optparse}'s Option class.
-This being Python, nothing stops you from doing that except good manners
-and common sense.)
-
-That's it! Now you can write a script that uses the new option type
-just like any other \module{optparse}-based script, except you have to instruct your
-OptionParser to use MyOption instead of Option:
-\begin{verbatim}
-parser = OptionParser(option_class=MyOption)
-parser.add_option("-c", type="complex")
-\end{verbatim}
-
-Alternately, you can build your own option list and pass it to
-OptionParser; if you don't use \method{add{\_}option()} in the above way, you
-don't need to tell OptionParser which option class to use:
-\begin{verbatim}
-option_list = [MyOption("-c", action="store", type="complex", dest="c")]
-parser = OptionParser(option_list=option_list)
-\end{verbatim}
-
-
-\subsubsection{Adding new actions\label{optparse-adding-new-actions}}
-
-Adding new actions is a bit trickier, because you have to understand
-that \module{optparse} has a couple of classifications for actions:
-\begin{description}
-\item[``store'' actions]
-actions that result in \module{optparse} storing a value to an attribute of the
-current OptionValues instance; these options require a \member{dest}
-attribute to be supplied to the Option constructor
-\item[``typed'' actions]
-actions that take a value from the command line and expect it to be
-of a certain type; or rather, a string that can be converted to a
-certain type. These options require a \member{type} attribute to the
-Option constructor.
-\end{description}
-
-These are overlapping sets: some default ``store'' actions are \code{store},
-\code{store{\_}const}, \code{append}, and \code{count}, while the default ``typed''
-actions are \code{store}, \code{append}, and \code{callback}.
-
-When you add an action, you need to categorize it by listing it in at
-least one of the following class attributes of Option (all are lists of
-strings):
-\begin{description}
-\item[\member{ACTIONS}]
-all actions must be listed in ACTIONS
-\item[\member{STORE{\_}ACTIONS}]
-``store'' actions are additionally listed here
-\item[\member{TYPED{\_}ACTIONS}]
-``typed'' actions are additionally listed here
-\item[\code{ALWAYS{\_}TYPED{\_}ACTIONS}]
-actions that always take a type (i.e. whose options always take a
-value) are additionally listed here. The only effect of this is
-that \module{optparse} assigns the default type, \code{string}, to options with no
-explicit type whose action is listed in \code{ALWAYS{\_}TYPED{\_}ACTIONS}.
-\end{description}
-
-In order to actually implement your new action, you must override
-Option's \method{take{\_}action()} method and add a case that recognizes your
-action.
-
-For example, let's add an \code{extend} action. This is similar to the
-standard \code{append} action, but instead of taking a single value from
-the command-line and appending it to an existing list, \code{extend} will
-take multiple values in a single comma-delimited string, and extend an
-existing list with them. That is, if \code{"-{}-names"} is an \code{extend}
-option of type \code{string}, the command line
-\begin{verbatim}
---names=foo,bar --names blah --names ding,dong
-\end{verbatim}
-
-would result in a list
-\begin{verbatim}
-["foo", "bar", "blah", "ding", "dong"]
-\end{verbatim}
-
-Again we define a subclass of Option:
-\begin{verbatim}
-class MyOption (Option):
-
- ACTIONS = Option.ACTIONS + ("extend",)
- STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
- TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
- ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)
-
- def take_action(self, action, dest, opt, value, values, parser):
- if action == "extend":
- lvalue = value.split(",")
- values.ensure_value(dest, []).extend(lvalue)
- else:
- Option.take_action(
- self, action, dest, opt, value, values, parser)
-\end{verbatim}
-
-Features of note:
-\begin{itemize}
-\item {}
-\code{extend} both expects a value on the command-line and stores that
-value somewhere, so it goes in both \member{STORE{\_}ACTIONS} and
-\member{TYPED{\_}ACTIONS}
-
-\item {}
-to ensure that \module{optparse} assigns the default type of \code{string} to
-\code{extend} actions, we put the \code{extend} action in
-\code{ALWAYS{\_}TYPED{\_}ACTIONS} as well
-
-\item {}
-\method{MyOption.take{\_}action()} implements just this one new action, and
-passes control back to \method{Option.take{\_}action()} for the standard
-\module{optparse} actions
-
-\item {}
-\code{values} is an instance of the optparse{\_}parser.Values class,
-which provides the very useful \method{ensure{\_}value()} method.
-\method{ensure{\_}value()} is essentially \function{getattr()} with a safety valve;
-it is called as
-\begin{verbatim}
-values.ensure_value(attr, value)
-\end{verbatim}
-
-If the \code{attr} attribute of \code{values} doesn't exist or is None, then
-ensure{\_}value() first sets it to \code{value}, and then returns 'value.
-This is very handy for actions like \code{extend}, \code{append}, and
-\code{count}, all of which accumulate data in a variable and expect that
-variable to be of a certain type (a list for the first two, an integer
-for the latter). Using \method{ensure{\_}value()} means that scripts using
-your action don't have to worry about setting a default value for the
-option destinations in question; they can just leave the default as
-None and \method{ensure{\_}value()} will take care of getting it right when
-it's needed.
-
-\end{itemize}
-% $Id: extending.txt 517 2006-06-10 16:18:11Z gward $
-
diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex
deleted file mode 100644
index 826e9fa..0000000
--- a/Doc/lib/libos.tex
+++ /dev/null
@@ -1,1980 +0,0 @@
-\section{\module{os} ---
- Miscellaneous operating system interfaces}
-
-\declaremodule{standard}{os}
-\modulesynopsis{Miscellaneous operating system interfaces.}
-
-
-This module provides a more portable way of using operating system
-dependent functionality than importing a operating system dependent
-built-in module like \refmodule{posix} or \module{nt}.
-
-This module searches for an operating system dependent built-in module like
-\module{mac} or \refmodule{posix} and exports the same functions and data
-as found there. The design of all Python's built-in operating system dependent
-modules is such that as long as the same functionality is available,
-it uses the same interface; for example, the function
-\code{os.stat(\var{path})} returns stat information about \var{path} in
-the same format (which happens to have originated with the
-\POSIX{} interface).
-
-Extensions peculiar to a particular operating system are also
-available through the \module{os} module, but using them is of course a
-threat to portability!
-
-Note that after the first time \module{os} is imported, there is
-\emph{no} performance penalty in using functions from \module{os}
-instead of directly from the operating system dependent built-in module,
-so there should be \emph{no} reason not to use \module{os}!
-
-
-% Frank Stajano <fstajano@uk.research.att.com> complained that it
-% wasn't clear that the entries described in the subsections were all
-% available at the module level (most uses of subsections are
-% different); I think this is only a problem for the HTML version,
-% where the relationship may not be as clear.
-%
-\ifhtml
-The \module{os} module contains many functions and data values.
-The items below and in the following sub-sections are all available
-directly from the \module{os} module.
-\fi
-
-
-\begin{excdesc}{error}
-This exception is raised when a function returns a system-related
-error (not for illegal argument types or other incidental errors).
-This is also known as the built-in exception \exception{OSError}. The
-accompanying value is a pair containing the numeric error code from
-\cdata{errno} and the corresponding string, as would be printed by the
-C function \cfunction{perror()}. See the module
-\refmodule{errno}\refbimodindex{errno}, which contains names for the
-error codes defined by the underlying operating system.
-
-When exceptions are classes, this exception carries two attributes,
-\member{errno} and \member{strerror}. The first holds the value of
-the C \cdata{errno} variable, and the latter holds the corresponding
-error message from \cfunction{strerror()}. For exceptions that
-involve a file system path (such as \function{chdir()} or
-\function{unlink()}), the exception instance will contain a third
-attribute, \member{filename}, which is the file name passed to the
-function.
-\end{excdesc}
-
-\begin{datadesc}{name}
-The name of the operating system dependent module imported. The
-following names have currently been registered: \code{'posix'},
-\code{'nt'}, \code{'mac'}, \code{'os2'}, \code{'ce'},
-\code{'java'}, \code{'riscos'}.
-\end{datadesc}
-
-\begin{datadesc}{path}
-The corresponding operating system dependent standard module for pathname
-operations, such as \module{posixpath} or \module{macpath}. Thus,
-given the proper imports, \code{os.path.split(\var{file})} is
-equivalent to but more portable than
-\code{posixpath.split(\var{file})}. Note that this is also an
-importable module: it may be imported directly as
-\refmodule{os.path}.
-\end{datadesc}
-
-
-
-\subsection{Process Parameters \label{os-procinfo}}
-
-These functions and data items provide information and operate on the
-current process and user.
-
-\begin{datadesc}{environ}
-A mapping object representing the string environment. For example,
-\code{environ['HOME']} is the pathname of your home directory (on some
-platforms), and is equivalent to \code{getenv("HOME")} in C.
-
-This mapping is captured the first time the \module{os} module is
-imported, typically during Python startup as part of processing
-\file{site.py}. Changes to the environment made after this time are
-not reflected in \code{os.environ}, except for changes made by modifying
-\code{os.environ} directly.
-
-If the platform supports the \function{putenv()} function, this
-mapping may be used to modify the environment as well as query the
-environment. \function{putenv()} will be called automatically when
-the mapping is modified.
-\note{Calling \function{putenv()} directly does not change
-\code{os.environ}, so it's better to modify \code{os.environ}.}
-\note{On some platforms, including FreeBSD and Mac OS X, setting
-\code{environ} may cause memory leaks. Refer to the system documentation
-for \cfunction{putenv()}.}
-
-If \function{putenv()} is not provided, a modified copy of this mapping
-may be passed to the appropriate process-creation functions to cause
-child processes to use a modified environment.
-
-If the platform supports the \function{unsetenv()} function, you can
-delete items in this mapping to unset environment variables.
-\function{unsetenv()} will be called automatically when an item is
-deleted from \code{os.environ}.
-
-\end{datadesc}
-
-\begin{funcdescni}{chdir}{path}
-\funclineni{fchdir}{fd}
-\funclineni{getcwd}{}
-These functions are described in ``Files and Directories'' (section
-\ref{os-file-dir}).
-\end{funcdescni}
-
-\begin{funcdesc}{ctermid}{}
-Return the filename corresponding to the controlling terminal of the
-process.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getegid}{}
-Return the effective group id of the current process. This
-corresponds to the `set id' bit on the file being executed in the
-current process.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{geteuid}{}
-\index{user!effective id}
-Return the current process' effective user id.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getgid}{}
-\index{process!group}
-Return the real group id of the current process.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getgroups}{}
-Return list of supplemental group ids associated with the current
-process.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getlogin}{}
-Return the name of the user logged in on the controlling terminal of
-the process. For most purposes, it is more useful to use the
-environment variable \envvar{LOGNAME} to find out who the user is,
-or \code{pwd.getpwuid(os.getuid())[0]} to get the login name
-of the currently effective user ID.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getpgid}{pid}
-Return the process group id of the process with process id \var{pid}.
-If \var{pid} is 0, the process group id of the current process is
-returned. Availability: \UNIX.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getpgrp}{}
-\index{process!group}
-Return the id of the current process group.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getpid}{}
-\index{process!id}
-Return the current process id.
-Availability: \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{getppid}{}
-\index{process!id of parent}
-Return the parent's process id.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getuid}{}
-\index{user!id}
-Return the current process' user id.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getenv}{varname\optional{, value}}
-Return the value of the environment variable \var{varname} if it
-exists, or \var{value} if it doesn't. \var{value} defaults to
-\code{None}.
-Availability: most flavors of \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{putenv}{varname, value}
-\index{environment variables!setting}
-Set the environment variable named \var{varname} to the string
-\var{value}. Such changes to the environment affect subprocesses
-started with \function{os.system()}, \function{popen()} or
-\function{fork()} and \function{execv()}.
-Availability: most flavors of \UNIX, Windows.
-
-\note{On some platforms, including FreeBSD and Mac OS X,
-setting \code{environ} may cause memory leaks.
-Refer to the system documentation for putenv.}
-
-When \function{putenv()} is
-supported, assignments to items in \code{os.environ} are automatically
-translated into corresponding calls to \function{putenv()}; however,
-calls to \function{putenv()} don't update \code{os.environ}, so it is
-actually preferable to assign to items of \code{os.environ}.
-\end{funcdesc}
-
-\begin{funcdesc}{setegid}{egid}
-Set the current process's effective group id.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{seteuid}{euid}
-Set the current process's effective user id.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{setgid}{gid}
-Set the current process' group id.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{setgroups}{groups}
-Set the list of supplemental group ids associated with the current
-process to \var{groups}. \var{groups} must be a sequence, and each
-element must be an integer identifying a group. This operation is
-typical available only to the superuser.
-Availability: \UNIX.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{setpgrp}{}
-Calls the system call \cfunction{setpgrp()} or \cfunction{setpgrp(0,
-0)} depending on which version is implemented (if any). See the
-\UNIX{} manual for the semantics.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{setpgid}{pid, pgrp} Calls the system call
-\cfunction{setpgid()} to set the process group id of the process with
-id \var{pid} to the process group with id \var{pgrp}. See the \UNIX{}
-manual for the semantics.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{setreuid}{ruid, euid}
-Set the current process's real and effective user ids.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{setregid}{rgid, egid}
-Set the current process's real and effective group ids.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getsid}{pid}
-Calls the system call \cfunction{getsid()}. See the \UNIX{} manual
-for the semantics.
-Availability: \UNIX. \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{setsid}{}
-Calls the system call \cfunction{setsid()}. See the \UNIX{} manual
-for the semantics.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{setuid}{uid}
-\index{user!id, setting}
-Set the current process' user id.
-Availability: \UNIX.
-\end{funcdesc}
-
-% placed in this section since it relates to errno.... a little weak
-\begin{funcdesc}{strerror}{code}
-Return the error message corresponding to the error code in
-\var{code}.
-Availability: \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{umask}{mask}
-Set the current numeric umask and returns the previous umask.
-Availability: \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{uname}{}
-Return a 5-tuple containing information identifying the current
-operating system. The tuple contains 5 strings:
-\code{(\var{sysname}, \var{nodename}, \var{release}, \var{version},
-\var{machine})}. Some systems truncate the nodename to 8
-characters or to the leading component; a better way to get the
-hostname is \function{socket.gethostname()}
-\withsubitem{(in module socket)}{\ttindex{gethostname()}}
-or even
-\withsubitem{(in module socket)}{\ttindex{gethostbyaddr()}}
-\code{socket.gethostbyaddr(socket.gethostname())}.
-Availability: recent flavors of \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{unsetenv}{varname}
-\index{environment variables!deleting}
-Unset (delete) the environment variable named \var{varname}. Such
-changes to the environment affect subprocesses started with
-\function{os.system()}, \function{popen()} or \function{fork()} and
-\function{execv()}. Availability: most flavors of \UNIX, Windows.
-
-When \function{unsetenv()} is
-supported, deletion of items in \code{os.environ} is automatically
-translated into a corresponding call to \function{unsetenv()}; however,
-calls to \function{unsetenv()} don't update \code{os.environ}, so it is
-actually preferable to delete items of \code{os.environ}.
-\end{funcdesc}
-
-\subsection{File Object Creation \label{os-newstreams}}
-
-These functions create new file objects.
-
-
-\begin{funcdesc}{fdopen}{fd\optional{, mode\optional{, bufsize}}}
-Return an open file object connected to the file descriptor \var{fd}.
-\index{I/O control!buffering}
-The \var{mode} and \var{bufsize} arguments have the same meaning as
-the corresponding arguments to the built-in \function{open()}
-function.
-Availability: Macintosh, \UNIX, Windows.
-
-\versionchanged[When specified, the \var{mode} argument must now start
- with one of the letters \character{r}, \character{w}, or \character{a},
- otherwise a \exception{ValueError} is raised]{2.3}
-\versionchanged[On \UNIX, when the \var{mode} argument starts with
- \character{a}, the \var{O_APPEND} flag is set on the file descriptor
- (which the \cfunction{fdopen()} implementation already does on most
- platforms)]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{popen}{command\optional{, mode\optional{, bufsize}}}
-Open a pipe to or from \var{command}. The return value is an open
-file object connected to the pipe, which can be read or written
-depending on whether \var{mode} is \code{'r'} (default) or \code{'w'}.
-The \var{bufsize} argument has the same meaning as the corresponding
-argument to the built-in \function{open()} function. The exit status of
-the command (encoded in the format specified for \function{wait()}) is
-available as the return value of the \method{close()} method of the file
-object, except that when the exit status is zero (termination without
-errors), \code{None} is returned.
-Availability: Macintosh, \UNIX, Windows.
-
-\deprecated{2.6}{This function is obsolete. Use the
- \module{subprocess} module.}
-
-\versionchanged[This function worked unreliably under Windows in
- earlier versions of Python. This was due to the use of the
- \cfunction{_popen()} function from the libraries provided with
- Windows. Newer versions of Python do not use the broken
- implementation from the Windows libraries]{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{tmpfile}{}
-Return a new file object opened in update mode (\samp{w+b}). The file
-has no directory entries associated with it and will be automatically
-deleted once there are no file descriptors for the file.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-
-\subsection{File Descriptor Operations \label{os-fd-ops}}
-
-These functions operate on I/O streams referenced using file
-descriptors.
-
-File descriptors are small integers corresponding to a file that has
-been opened by the current process. For example, standard input is
-usually file descriptor 0, standard output is 1, and standard error is
-2. Further files opened by a process will then be assigned 3, 4, 5,
-and so forth. The name ``file descriptor'' is slightly deceptive; on
-{\UNIX} platforms, sockets and pipes are also referenced by file descriptors.
-
-
-\begin{funcdesc}{close}{fd}
-Close file descriptor \var{fd}.
-Availability: Macintosh, \UNIX, Windows.
-
-\begin{notice}
-This function is intended for low-level I/O and must be applied
-to a file descriptor as returned by \function{open()} or
-\function{pipe()}. To close a ``file object'' returned by the
-built-in function \function{open()} or by \function{popen()} or
-\function{fdopen()}, use its \method{close()} method.
-\end{notice}
-\end{funcdesc}
-
-\begin{funcdesc}{dup}{fd}
-Return a duplicate of file descriptor \var{fd}.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{dup2}{fd, fd2}
-Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter
-first if necessary.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{fdatasync}{fd}
-Force write of file with filedescriptor \var{fd} to disk.
-Does not force update of metadata.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{fpathconf}{fd, name}
-Return system configuration information relevant to an open file.
-\var{name} specifies the configuration value to retrieve; it may be a
-string which is the name of a defined system value; these names are
-specified in a number of standards (\POSIX.1, \UNIX{} 95, \UNIX{} 98, and
-others). Some platforms define additional names as well. The names
-known to the host operating system are given in the
-\code{pathconf_names} dictionary. For configuration variables not
-included in that mapping, passing an integer for \var{name} is also
-accepted.
-Availability: Macintosh, \UNIX.
-
-If \var{name} is a string and is not known, \exception{ValueError} is
-raised. If a specific value for \var{name} is not supported by the
-host system, even if it is included in \code{pathconf_names}, an
-\exception{OSError} is raised with \constant{errno.EINVAL} for the
-error number.
-\end{funcdesc}
-
-\begin{funcdesc}{fstat}{fd}
-Return status for file descriptor \var{fd}, like \function{stat()}.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{fstatvfs}{fd}
-Return information about the filesystem containing the file associated
-with file descriptor \var{fd}, like \function{statvfs()}.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{fsync}{fd}
-Force write of file with filedescriptor \var{fd} to disk. On \UNIX,
-this calls the native \cfunction{fsync()} function; on Windows, the
-MS \cfunction{_commit()} function.
-
-If you're starting with a Python file object \var{f}, first do
-\code{\var{f}.flush()}, and then do \code{os.fsync(\var{f}.fileno())},
-to ensure that all internal buffers associated with \var{f} are written
-to disk.
-Availability: Macintosh, \UNIX, and Windows starting in 2.2.3.
-\end{funcdesc}
-
-\begin{funcdesc}{ftruncate}{fd, length}
-Truncate the file corresponding to file descriptor \var{fd},
-so that it is at most \var{length} bytes in size.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{isatty}{fd}
-Return \code{True} if the file descriptor \var{fd} is open and
-connected to a tty(-like) device, else \code{False}.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{lseek}{fd, pos, how}
-Set the current position of file descriptor \var{fd} to position
-\var{pos}, modified by \var{how}: \code{0} to set the position
-relative to the beginning of the file; \code{1} to set it relative to
-the current position; \code{2} to set it relative to the end of the
-file.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{open}{file, flags\optional{, mode}}
-Open the file \var{file} and set various flags according to
-\var{flags} and possibly its mode according to \var{mode}.
-The default \var{mode} is \code{0777} (octal), and the current umask
-value is first masked out. Return the file descriptor for the newly
-opened file.
-Availability: Macintosh, \UNIX, Windows.
-
-For a description of the flag and mode values, see the C run-time
-documentation; flag constants (like \constant{O_RDONLY} and
-\constant{O_WRONLY}) are defined in this module too (see below).
-
-\begin{notice}
-This function is intended for low-level I/O. For normal usage,
-use the built-in function \function{open()}, which returns a ``file
-object'' with \method{read()} and \method{write()} methods (and many
-more). To wrap a file descriptor in a ``file object'', use
-\function{fdopen()}.
-\end{notice}
-\end{funcdesc}
-
-\begin{funcdesc}{openpty}{}
-Open a new pseudo-terminal pair. Return a pair of file descriptors
-\code{(\var{master}, \var{slave})} for the pty and the tty,
-respectively. For a (slightly) more portable approach, use the
-\refmodule{pty}\refstmodindex{pty} module.
-Availability: Macintosh, Some flavors of \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{pipe}{}
-Create a pipe. Return a pair of file descriptors \code{(\var{r},
-\var{w})} usable for reading and writing, respectively.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{read}{fd, n}
-Read at most \var{n} bytes from file descriptor \var{fd}.
-Return a string containing the bytes read. If the end of the file
-referred to by \var{fd} has been reached, an empty string is
-returned.
-Availability: Macintosh, \UNIX, Windows.
-
-\begin{notice}
-This function is intended for low-level I/O and must be applied
-to a file descriptor as returned by \function{open()} or
-\function{pipe()}. To read a ``file object'' returned by the
-built-in function \function{open()} or by \function{popen()} or
-\function{fdopen()}, or \code{sys.stdin}, use its
-\method{read()} or \method{readline()} methods.
-\end{notice}
-\end{funcdesc}
-
-\begin{funcdesc}{tcgetpgrp}{fd}
-Return the process group associated with the terminal given by
-\var{fd} (an open file descriptor as returned by \function{open()}).
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{tcsetpgrp}{fd, pg}
-Set the process group associated with the terminal given by
-\var{fd} (an open file descriptor as returned by \function{open()})
-to \var{pg}.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{ttyname}{fd}
-Return a string which specifies the terminal device associated with
-file-descriptor \var{fd}. If \var{fd} is not associated with a terminal
-device, an exception is raised.
-Availability:Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{write}{fd, str}
-Write the string \var{str} to file descriptor \var{fd}.
-Return the number of bytes actually written.
-Availability: Macintosh, \UNIX, Windows.
-
-\begin{notice}
-This function is intended for low-level I/O and must be applied
-to a file descriptor as returned by \function{open()} or
-\function{pipe()}. To write a ``file object'' returned by the
-built-in function \function{open()} or by \function{popen()} or
-\function{fdopen()}, or \code{sys.stdout} or \code{sys.stderr}, use
-its \method{write()} method.
-\end{notice}
-\end{funcdesc}
-
-
-The following data items are available for use in constructing the
-\var{flags} parameter to the \function{open()} function. Some items will
-not be available on all platforms. For descriptions of their availability
-and use, consult \manpage{open}{2}.
-
-\begin{datadesc}{O_RDONLY}
-\dataline{O_WRONLY}
-\dataline{O_RDWR}
-\dataline{O_APPEND}
-\dataline{O_CREAT}
-\dataline{O_EXCL}
-\dataline{O_TRUNC}
-Options for the \var{flag} argument to the \function{open()} function.
-These can be bit-wise OR'd together.
-Availability: Macintosh, \UNIX, Windows.
-\end{datadesc}
-
-\begin{datadesc}{O_DSYNC}
-\dataline{O_RSYNC}
-\dataline{O_SYNC}
-\dataline{O_NDELAY}
-\dataline{O_NONBLOCK}
-\dataline{O_NOCTTY}
-\dataline{O_SHLOCK}
-\dataline{O_EXLOCK}
-More options for the \var{flag} argument to the \function{open()} function.
-Availability: Macintosh, \UNIX.
-\end{datadesc}
-
-\begin{datadesc}{O_BINARY}
-Option for the \var{flag} argument to the \function{open()} function.
-This can be bit-wise OR'd together with those listed above.
-Availability: Windows.
-% XXX need to check on the availability of this one.
-\end{datadesc}
-
-\begin{datadesc}{O_NOINHERIT}
-\dataline{O_SHORT_LIVED}
-\dataline{O_TEMPORARY}
-\dataline{O_RANDOM}
-\dataline{O_SEQUENTIAL}
-\dataline{O_TEXT}
-Options for the \var{flag} argument to the \function{open()} function.
-These can be bit-wise OR'd together.
-Availability: Windows.
-\end{datadesc}
-
-\begin{datadesc}{SEEK_SET}
-\dataline{SEEK_CUR}
-\dataline{SEEK_END}
-Parameters to the \function{lseek()} function.
-Their values are 0, 1, and 2, respectively.
-Availability: Windows, Macintosh, \UNIX.
-\versionadded{2.5}
-\end{datadesc}
-
-\subsection{Files and Directories \label{os-file-dir}}
-
-\begin{funcdesc}{access}{path, mode}
-Use the real uid/gid to test for access to \var{path}. Note that most
-operations will use the effective uid/gid, therefore this routine can
-be used in a suid/sgid environment to test if the invoking user has the
-specified access to \var{path}. \var{mode} should be \constant{F_OK}
-to test the existence of \var{path}, or it can be the inclusive OR of
-one or more of \constant{R_OK}, \constant{W_OK}, and \constant{X_OK} to
-test permissions. Return \constant{True} if access is allowed,
-\constant{False} if not.
-See the \UNIX{} man page \manpage{access}{2} for more information.
-Availability: Macintosh, \UNIX, Windows.
-
-\note{Using \function{access()} to check if a user is authorized to e.g.
-open a file before actually doing so using \function{open()} creates a
-security hole, because the user might exploit the short time interval
-between checking and opening the file to manipulate it.}
-
-\note{I/O operations may fail even when \function{access()}
-indicates that they would succeed, particularly for operations
-on network filesystems which may have permissions semantics
-beyond the usual \POSIX{} permission-bit model.}
-\end{funcdesc}
-
-\begin{datadesc}{F_OK}
- Value to pass as the \var{mode} parameter of \function{access()} to
- test the existence of \var{path}.
-\end{datadesc}
-
-\begin{datadesc}{R_OK}
- Value to include in the \var{mode} parameter of \function{access()}
- to test the readability of \var{path}.
-\end{datadesc}
-
-\begin{datadesc}{W_OK}
- Value to include in the \var{mode} parameter of \function{access()}
- to test the writability of \var{path}.
-\end{datadesc}
-
-\begin{datadesc}{X_OK}
- Value to include in the \var{mode} parameter of \function{access()}
- to determine if \var{path} can be executed.
-\end{datadesc}
-
-\begin{funcdesc}{chdir}{path}
-\index{directory!changing}
-Change the current working directory to \var{path}.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{fchdir}{fd}
-Change the current working directory to the directory represented by
-the file descriptor \var{fd}. The descriptor must refer to an opened
-directory, not an open file.
-Availability: \UNIX.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getcwd}{}
-Return a string representing the current working directory.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{getcwdu}{}
-Return a Unicode object representing the current working directory.
-Availability: Macintosh, \UNIX, Windows.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{chflags}{path, flags}
-Set the flags of \var{path} to the numeric \var{flags}.
-\var{flags} may take a combination (bitwise OR) of the following values
-(as defined in the \module{stat} module):
-\begin{itemize}
- \item \code{UF_NODUMP}
- \item \code{UF_IMMUTABLE}
- \item \code{UF_APPEND}
- \item \code{UF_OPAQUE}
- \item \code{UF_NOUNLINK}
- \item \code{SF_ARCHIVED}
- \item \code{SF_IMMUTABLE}
- \item \code{SF_APPEND}
- \item \code{SF_NOUNLINK}
- \item \code{SF_SNAPSHOT}
-\end{itemize}
-Availability: Macintosh, \UNIX.
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{chroot}{path}
-Change the root directory of the current process to \var{path}.
-Availability: Macintosh, \UNIX.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{chmod}{path, mode}
-Change the mode of \var{path} to the numeric \var{mode}.
-\var{mode} may take one of the following values
-(as defined in the \module{stat} module) or bitwise or-ed
-combinations of them:
-\begin{itemize}
- \item \code{S_ISUID}
- \item \code{S_ISGID}
- \item \code{S_ENFMT}
- \item \code{S_ISVTX}
- \item \code{S_IREAD}
- \item \code{S_IWRITE}
- \item \code{S_IEXEC}
- \item \code{S_IRWXU}
- \item \code{S_IRUSR}
- \item \code{S_IWUSR}
- \item \code{S_IXUSR}
- \item \code{S_IRWXG}
- \item \code{S_IRGRP}
- \item \code{S_IWGRP}
- \item \code{S_IXGRP}
- \item \code{S_IRWXO}
- \item \code{S_IROTH}
- \item \code{S_IWOTH}
- \item \code{S_IXOTH}
-\end{itemize}
-Availability: Macintosh, \UNIX, Windows.
-
-\note{Although Windows supports \function{chmod()}, you can only
-set the file's read-only flag with it (via the \code{S_IWRITE}
-and \code{S_IREAD} constants or a corresponding integer value).
-All other bits are ignored.}
-\end{funcdesc}
-
-\begin{funcdesc}{chown}{path, uid, gid}
-Change the owner and group id of \var{path} to the numeric \var{uid}
-and \var{gid}. To leave one of the ids unchanged, set it to -1.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{lchflags}{path, flags}
-Set the flags of \var{path} to the numeric \var{flags}, like
-\function{chflags()}, but do not follow symbolic links.
-Availability: \UNIX.
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{lchown}{path, uid, gid}
-Change the owner and group id of \var{path} to the numeric \var{uid}
-and gid. This function will not follow symbolic links.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{link}{src, dst}
-Create a hard link pointing to \var{src} named \var{dst}.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{listdir}{path}
-Return a list containing the names of the entries in the directory.
-The list is in arbitrary order. It does not include the special
-entries \code{'.'} and \code{'..'} even if they are present in the
-directory.
-Availability: Macintosh, \UNIX, Windows.
-
-\versionchanged[On Windows NT/2k/XP and \UNIX, if \var{path} is a Unicode
-object, the result will be a list of Unicode objects]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{lstat}{path}
-Like \function{stat()}, but do not follow symbolic links.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{mkfifo}{path\optional{, mode}}
-Create a FIFO (a named pipe) named \var{path} with numeric mode
-\var{mode}. The default \var{mode} is \code{0666} (octal). The current
-umask value is first masked out from the mode.
-Availability: Macintosh, \UNIX.
-
-FIFOs are pipes that can be accessed like regular files. FIFOs exist
-until they are deleted (for example with \function{os.unlink()}).
-Generally, FIFOs are used as rendezvous between ``client'' and
-``server'' type processes: the server opens the FIFO for reading, and
-the client opens it for writing. Note that \function{mkfifo()}
-doesn't open the FIFO --- it just creates the rendezvous point.
-\end{funcdesc}
-
-\begin{funcdesc}{mknod}{filename\optional{, mode=0600, device}}
-Create a filesystem node (file, device special file or named pipe)
-named \var{filename}. \var{mode} specifies both the permissions to use and
-the type of node to be created, being combined (bitwise OR) with one
-of S_IFREG, S_IFCHR, S_IFBLK, and S_IFIFO (those constants are
-available in \module{stat}). For S_IFCHR and S_IFBLK, \var{device}
-defines the newly created device special file (probably using
-\function{os.makedev()}), otherwise it is ignored.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{major}{device}
-Extracts the device major number from a raw device number (usually
-the \member{st_dev} or \member{st_rdev} field from \ctype{stat}).
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{minor}{device}
-Extracts the device minor number from a raw device number (usually
-the \member{st_dev} or \member{st_rdev} field from \ctype{stat}).
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{makedev}{major, minor}
-Composes a raw device number from the major and minor device numbers.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{mkdir}{path\optional{, mode}}
-Create a directory named \var{path} with numeric mode \var{mode}.
-The default \var{mode} is \code{0777} (octal). On some systems,
-\var{mode} is ignored. Where it is used, the current umask value is
-first masked out.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{makedirs}{path\optional{, mode}}
-Recursive directory creation function.\index{directory!creating}
-\index{UNC paths!and \function{os.makedirs()}}
-Like \function{mkdir()},
-but makes all intermediate-level directories needed to contain the
-leaf directory. Throws an \exception{error} exception if the leaf
-directory already exists or cannot be created. The default \var{mode}
-is \code{0777} (octal). On some systems, \var{mode} is ignored.
-Where it is used, the current umask value is first masked out.
-\note{\function{makedirs()} will become confused if the path elements
-to create include \var{os.pardir}.}
-\versionadded{1.5.2}
-\versionchanged[This function now handles UNC paths correctly]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{pathconf}{path, name}
-Return system configuration information relevant to a named file.
-\var{name} specifies the configuration value to retrieve; it may be a
-string which is the name of a defined system value; these names are
-specified in a number of standards (\POSIX.1, \UNIX{} 95, \UNIX{} 98, and
-others). Some platforms define additional names as well. The names
-known to the host operating system are given in the
-\code{pathconf_names} dictionary. For configuration variables not
-included in that mapping, passing an integer for \var{name} is also
-accepted.
-Availability: Macintosh, \UNIX.
-
-If \var{name} is a string and is not known, \exception{ValueError} is
-raised. If a specific value for \var{name} is not supported by the
-host system, even if it is included in \code{pathconf_names}, an
-\exception{OSError} is raised with \constant{errno.EINVAL} for the
-error number.
-\end{funcdesc}
-
-\begin{datadesc}{pathconf_names}
-Dictionary mapping names accepted by \function{pathconf()} and
-\function{fpathconf()} to the integer values defined for those names
-by the host operating system. This can be used to determine the set
-of names known to the system.
-Availability: Macintosh, \UNIX.
-\end{datadesc}
-
-\begin{funcdesc}{readlink}{path}
-Return a string representing the path to which the symbolic link
-points. The result may be either an absolute or relative pathname; if
-it is relative, it may be converted to an absolute pathname using
-\code{os.path.join(os.path.dirname(\var{path}), \var{result})}.
-\versionchanged [If the \var{path} is a Unicode object the result will also
-be a Unicode object]{2.6}
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{remove}{path}
-Remove the file \var{path}. If \var{path} is a directory,
-\exception{OSError} is raised; see \function{rmdir()} below to remove
-a directory. This is identical to the \function{unlink()} function
-documented below. On Windows, attempting to remove a file that is in
-use causes an exception to be raised; on \UNIX, the directory entry is
-removed but the storage allocated to the file is not made available
-until the original file is no longer in use.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{removedirs}{path}
-\index{directory!deleting}
-Removes directories recursively. Works like
-\function{rmdir()} except that, if the leaf directory is
-successfully removed, \function{removedirs()}
-tries to successively remove every parent directory mentioned in
-\var{path} until an error is raised (which is ignored, because
-it generally means that a parent directory is not empty).
-For example, \samp{os.removedirs('foo/bar/baz')} will first remove
-the directory \samp{'foo/bar/baz'}, and then remove \samp{'foo/bar'}
-and \samp{'foo'} if they are empty.
-Raises \exception{OSError} if the leaf directory could not be
-successfully removed.
-\versionadded{1.5.2}
-\end{funcdesc}
-
-\begin{funcdesc}{rename}{src, dst}
-Rename the file or directory \var{src} to \var{dst}. If \var{dst} is
-a directory, \exception{OSError} will be raised. On \UNIX, if
-\var{dst} exists and is a file, it will be removed silently if the
-user has permission. The operation may fail on some \UNIX{} flavors
-if \var{src} and \var{dst} are on different filesystems. If
-successful, the renaming will be an atomic operation (this is a
-\POSIX{} requirement). On Windows, if \var{dst} already exists,
-\exception{OSError} will be raised even if it is a file; there may be
-no way to implement an atomic rename when \var{dst} names an existing
-file.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{renames}{old, new}
-Recursive directory or file renaming function.
-Works like \function{rename()}, except creation of any intermediate
-directories needed to make the new pathname good is attempted first.
-After the rename, directories corresponding to rightmost path segments
-of the old name will be pruned away using \function{removedirs()}.
-\versionadded{1.5.2}
-
-\begin{notice}
-This function can fail with the new directory structure made if
-you lack permissions needed to remove the leaf directory or file.
-\end{notice}
-\end{funcdesc}
-
-\begin{funcdesc}{rmdir}{path}
-Remove the directory \var{path}.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{stat}{path}
-Perform a \cfunction{stat()} system call on the given path. The
-return value is an object whose attributes correspond to the members of
-the \ctype{stat} structure, namely:
-\member{st_mode} (protection bits),
-\member{st_ino} (inode number),
-\member{st_dev} (device),
-\member{st_nlink} (number of hard links),
-\member{st_uid} (user ID of owner),
-\member{st_gid} (group ID of owner),
-\member{st_size} (size of file, in bytes),
-\member{st_atime} (time of most recent access),
-\member{st_mtime} (time of most recent content modification),
-\member{st_ctime}
-(platform dependent; time of most recent metadata change on \UNIX, or
-the time of creation on Windows):
-
-\begin{verbatim}
->>> import os
->>> statinfo = os.stat('somefile.txt')
->>> statinfo
-(33188, 422511L, 769L, 1, 1032, 100, 926L, 1105022698,1105022732, 1105022732)
->>> statinfo.st_size
-926L
->>>
-\end{verbatim}
-
-\versionchanged [If \function{stat_float_times} returns true, the time
-values are floats, measuring seconds. Fractions of a second may be
-reported if the system supports that. On Mac OS, the times are always
-floats. See \function{stat_float_times} for further discussion]{2.3}
-
-On some \UNIX{} systems (such as Linux), the following attributes may
-also be available:
-\member{st_blocks} (number of blocks allocated for file),
-\member{st_blksize} (filesystem blocksize),
-\member{st_rdev} (type of device if an inode device).
-\member{st_flags} (user defined flags for file).
-
-On other \UNIX{} systems (such as FreeBSD), the following attributes
-may be available (but may be only filled out if root tries to
-use them):
-\member{st_gen} (file generation number),
-\member{st_birthtime} (time of file creation).
-
-On Mac OS systems, the following attributes may also be available:
-\member{st_rsize},
-\member{st_creator},
-\member{st_type}.
-
-On RISCOS systems, the following attributes are also available:
-\member{st_ftype} (file type),
-\member{st_attrs} (attributes),
-\member{st_obtype} (object type).
-
-For backward compatibility, the return value of \function{stat()} is
-also accessible as a tuple of at least 10 integers giving the most
-important (and portable) members of the \ctype{stat} structure, in the
-order
-\member{st_mode},
-\member{st_ino},
-\member{st_dev},
-\member{st_nlink},
-\member{st_uid},
-\member{st_gid},
-\member{st_size},
-\member{st_atime},
-\member{st_mtime},
-\member{st_ctime}.
-More items may be added at the end by some implementations.
-The standard module \refmodule{stat}\refstmodindex{stat} defines
-functions and constants that are useful for extracting information
-from a \ctype{stat} structure.
-(On Windows, some items are filled with dummy values.)
-
-\note{The exact meaning and resolution of the \member{st_atime},
- \member{st_mtime}, and \member{st_ctime} members depends on the
- operating system and the file system. For example, on Windows systems
- using the FAT or FAT32 file systems, \member{st_mtime} has 2-second
- resolution, and \member{st_atime} has only 1-day resolution. See
- your operating system documentation for details.}
-
-Availability: Macintosh, \UNIX, Windows.
-
-\versionchanged
-[Added access to values as attributes of the returned object]{2.2}
-\versionchanged[Added st_gen, st_birthtime]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{stat_float_times}{\optional{newvalue}}
-Determine whether \class{stat_result} represents time stamps as float
-objects. If \var{newvalue} is \code{True}, future calls to \function{stat()}
-return floats, if it is \code{False}, future calls return ints.
-If \var{newvalue} is omitted, return the current setting.
-
-For compatibility with older Python versions, accessing
-\class{stat_result} as a tuple always returns integers.
-
-\versionchanged[Python now returns float values by default. Applications
-which do not work correctly with floating point time stamps can use
-this function to restore the old behaviour]{2.5}
-
-The resolution of the timestamps (that is the smallest possible fraction)
-depends on the system. Some systems only support second resolution;
-on these systems, the fraction will always be zero.
-
-It is recommended that this setting is only changed at program startup
-time in the \var{__main__} module; libraries should never change this
-setting. If an application uses a library that works incorrectly if
-floating point time stamps are processed, this application should turn
-the feature off until the library has been corrected.
-
-\end{funcdesc}
-
-\begin{funcdesc}{statvfs}{path}
-Perform a \cfunction{statvfs()} system call on the given path. The
-return value is an object whose attributes describe the filesystem on
-the given path, and correspond to the members of the
-\ctype{statvfs} structure, namely:
-\member{f_bsize},
-\member{f_frsize},
-\member{f_blocks},
-\member{f_bfree},
-\member{f_bavail},
-\member{f_files},
-\member{f_ffree},
-\member{f_favail},
-\member{f_flag},
-\member{f_namemax}.
-Availability: \UNIX.
-
-For backward compatibility, the return value is also accessible as a
-tuple whose values correspond to the attributes, in the order given above.
-The standard module \refmodule{statvfs}\refstmodindex{statvfs}
-defines constants that are useful for extracting information
-from a \ctype{statvfs} structure when accessing it as a sequence; this
-remains useful when writing code that needs to work with versions of
-Python that don't support accessing the fields as attributes.
-
-\versionchanged
-[Added access to values as attributes of the returned object]{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{symlink}{src, dst}
-Create a symbolic link pointing to \var{src} named \var{dst}.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{tempnam}{\optional{dir\optional{, prefix}}}
-Return a unique path name that is reasonable for creating a temporary
-file. This will be an absolute path that names a potential directory
-entry in the directory \var{dir} or a common location for temporary
-files if \var{dir} is omitted or \code{None}. If given and not
-\code{None}, \var{prefix} is used to provide a short prefix to the
-filename. Applications are responsible for properly creating and
-managing files created using paths returned by \function{tempnam()};
-no automatic cleanup is provided.
-On \UNIX, the environment variable \envvar{TMPDIR} overrides
-\var{dir}, while on Windows the \envvar{TMP} is used. The specific
-behavior of this function depends on the C library implementation;
-some aspects are underspecified in system documentation.
-\warning{Use of \function{tempnam()} is vulnerable to symlink attacks;
-consider using \function{tmpfile()} (section \ref{os-newstreams})
-instead.} Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{tmpnam}{}
-Return a unique path name that is reasonable for creating a temporary
-file. This will be an absolute path that names a potential directory
-entry in a common location for temporary files. Applications are
-responsible for properly creating and managing files created using
-paths returned by \function{tmpnam()}; no automatic cleanup is
-provided.
-\warning{Use of \function{tmpnam()} is vulnerable to symlink attacks;
-consider using \function{tmpfile()} (section \ref{os-newstreams})
-instead.} Availability: \UNIX, Windows. This function probably
-shouldn't be used on Windows, though: Microsoft's implementation of
-\function{tmpnam()} always creates a name in the root directory of the
-current drive, and that's generally a poor location for a temp file
-(depending on privileges, you may not even be able to open a file
-using this name).
-\end{funcdesc}
-
-\begin{datadesc}{TMP_MAX}
-The maximum number of unique names that \function{tmpnam()} will
-generate before reusing names.
-\end{datadesc}
-
-\begin{funcdesc}{unlink}{path}
-Remove the file \var{path}. This is the same function as
-\function{remove()}; the \function{unlink()} name is its traditional
-\UNIX{} name.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{utime}{path, times}
-Set the access and modified times of the file specified by \var{path}.
-If \var{times} is \code{None}, then the file's access and modified
-times are set to the current time. Otherwise, \var{times} must be a
-2-tuple of numbers, of the form \code{(\var{atime}, \var{mtime})}
-which is used to set the access and modified times, respectively.
-Whether a directory can be given for \var{path} depends on whether the
-operating system implements directories as files (for example, Windows
-does not). Note that the exact times you set here may not be returned
-by a subsequent \function{stat()} call, depending on the resolution
-with which your operating system records access and modification times;
-see \function{stat()}.
-\versionchanged[Added support for \code{None} for \var{times}]{2.0}
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{walk}{top\optional{, topdown\code{=True}
- \optional{, onerror\code{=None}\optional{,
- followlinks\code{=False}}}}}
-\index{directory!walking}
-\index{directory!traversal}
-\function{walk()} generates the file names in a directory tree, by
-walking the tree either top down or bottom up.
-For each directory in the tree rooted at directory \var{top} (including
-\var{top} itself), it yields a 3-tuple
-\code{(\var{dirpath}, \var{dirnames}, \var{filenames})}.
-
-\var{dirpath} is a string, the path to the directory. \var{dirnames} is
-a list of the names of the subdirectories in \var{dirpath}
-(excluding \code{'.'} and \code{'..'}). \var{filenames} is a list of
-the names of the non-directory files in \var{dirpath}. Note that the
-names in the lists contain no path components. To get a full
-path (which begins with \var{top}) to a file or directory in
-\var{dirpath}, do \code{os.path.join(\var{dirpath}, \var{name})}.
-
-If optional argument \var{topdown} is true or not specified, the triple
-for a directory is generated before the triples for any of its
-subdirectories (directories are generated top down). If \var{topdown} is
-false, the triple for a directory is generated after the triples for all
-of its subdirectories (directories are generated bottom up).
-
-When \var{topdown} is true, the caller can modify the \var{dirnames} list
-in-place (perhaps using \keyword{del} or slice assignment), and
-\function{walk()} will only recurse into the subdirectories whose names
-remain in \var{dirnames}; this can be used to prune the search,
-impose a specific order of visiting, or even to inform \function{walk()}
-about directories the caller creates or renames before it resumes
-\function{walk()} again. Modifying \var{dirnames} when \var{topdown} is
-false is ineffective, because in bottom-up mode the directories in
-\var{dirnames} are generated before \var{dirpath} itself is generated.
-
-By default errors from the \code{os.listdir()} call are ignored. If
-optional argument \var{onerror} is specified, it should be a function;
-it will be called with one argument, an \exception{OSError} instance. It can
-report the error to continue with the walk, or raise the exception
-to abort the walk. Note that the filename is available as the
-\code{filename} attribute of the exception object.
-
-By default, \function{walk()} will not walk down into symbolic links that
-resolve to directories. Set \var{followlinks} to True to visit directories
-pointed to by symlinks, on systems that support them.
-
-\versionadded[The \var{followlinks} parameter]{2.6}
-
-\begin{notice}
-Be aware that setting \var{followlinks} to true can lead to infinite recursion
-if a link points to a parent directory of itself. \function{walk()} does not
-keep track of the directories it visited already.
-\end{notice}
-
-\begin{notice}
-If you pass a relative pathname, don't change the current working
-directory between resumptions of \function{walk()}. \function{walk()}
-never changes the current directory, and assumes that its caller
-doesn't either.
-\end{notice}
-
-This example displays the number of bytes taken by non-directory files
-in each directory under the starting directory, except that it doesn't
-look under any CVS subdirectory:
-
-\begin{verbatim}
-import os
-from os.path import join, getsize
-for root, dirs, files in os.walk('python/Lib/email'):
- print root, "consumes",
- print sum(getsize(join(root, name)) for name in files),
- print "bytes in", len(files), "non-directory files"
- if 'CVS' in dirs:
- dirs.remove('CVS') # don't visit CVS directories
-\end{verbatim}
-
-In the next example, walking the tree bottom up is essential:
-\function{rmdir()} doesn't allow deleting a directory before the
-directory is empty:
-
-\begin{verbatim}
-# Delete everything reachable from the directory named in 'top',
-# assuming there are no symbolic links.
-# CAUTION: This is dangerous! For example, if top == '/', it
-# could delete all your disk files.
-import os
-for root, dirs, files in os.walk(top, topdown=False):
- for name in files:
- os.remove(os.path.join(root, name))
- for name in dirs:
- os.rmdir(os.path.join(root, name))
-\end{verbatim}
-
-\versionadded{2.3}
-\end{funcdesc}
-
-\subsection{Process Management \label{os-process}}
-
-These functions may be used to create and manage processes.
-
-The various \function{exec*()} functions take a list of arguments for
-the new program loaded into the process. In each case, the first of
-these arguments is passed to the new program as its own name rather
-than as an argument a user may have typed on a command line. For the
-C programmer, this is the \code{argv[0]} passed to a program's
-\cfunction{main()}. For example, \samp{os.execv('/bin/echo', ['foo',
-'bar'])} will only print \samp{bar} on standard output; \samp{foo}
-will seem to be ignored.
-
-
-\begin{funcdesc}{abort}{}
-Generate a \constant{SIGABRT} signal to the current process. On
-\UNIX, the default behavior is to produce a core dump; on Windows, the
-process immediately returns an exit code of \code{3}. Be aware that
-programs which use \function{signal.signal()} to register a handler
-for \constant{SIGABRT} will behave differently.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{execl}{path, arg0, arg1, \moreargs}
-\funcline{execle}{path, arg0, arg1, \moreargs, env}
-\funcline{execlp}{file, arg0, arg1, \moreargs}
-\funcline{execlpe}{file, arg0, arg1, \moreargs, env}
-\funcline{execv}{path, args}
-\funcline{execve}{path, args, env}
-\funcline{execvp}{file, args}
-\funcline{execvpe}{file, args, env}
-These functions all execute a new program, replacing the current
-process; they do not return. On \UNIX, the new executable is loaded
-into the current process, and will have the same process ID as the
-caller. Errors will be reported as \exception{OSError} exceptions.
-
-The \character{l} and \character{v} variants of the
-\function{exec*()} functions differ in how command-line arguments are
-passed. The \character{l} variants are perhaps the easiest to work
-with if the number of parameters is fixed when the code is written;
-the individual parameters simply become additional parameters to the
-\function{execl*()} functions. The \character{v} variants are good
-when the number of parameters is variable, with the arguments being
-passed in a list or tuple as the \var{args} parameter. In either
-case, the arguments to the child process should start with the name of
-the command being run, but this is not enforced.
-
-The variants which include a \character{p} near the end
-(\function{execlp()}, \function{execlpe()}, \function{execvp()},
-and \function{execvpe()}) will use the \envvar{PATH} environment
-variable to locate the program \var{file}. When the environment is
-being replaced (using one of the \function{exec*e()} variants,
-discussed in the next paragraph), the
-new environment is used as the source of the \envvar{PATH} variable.
-The other variants, \function{execl()}, \function{execle()},
-\function{execv()}, and \function{execve()}, will not use the
-\envvar{PATH} variable to locate the executable; \var{path} must
-contain an appropriate absolute or relative path.
-
-For \function{execle()}, \function{execlpe()}, \function{execve()},
-and \function{execvpe()} (note that these all end in \character{e}),
-the \var{env} parameter must be a mapping which is used to define the
-environment variables for the new process; the \function{execl()},
-\function{execlp()}, \function{execv()}, and \function{execvp()}
-all cause the new process to inherit the environment of the current
-process.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{_exit}{n}
-Exit to the system with status \var{n}, without calling cleanup
-handlers, flushing stdio buffers, etc.
-Availability: Macintosh, \UNIX, Windows.
-
-\begin{notice}
-The standard way to exit is \code{sys.exit(\var{n})}.
-\function{_exit()} should normally only be used in the child process
-after a \function{fork()}.
-\end{notice}
-\end{funcdesc}
-
-The following exit codes are a defined, and can be used with
-\function{_exit()}, although they are not required. These are
-typically used for system programs written in Python, such as a
-mail server's external command delivery program.
-\note{Some of these may not be available on all \UNIX{} platforms,
-since there is some variation. These constants are defined where they
-are defined by the underlying platform.}
-
-\begin{datadesc}{EX_OK}
-Exit code that means no error occurred.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_USAGE}
-Exit code that means the command was used incorrectly, such as when
-the wrong number of arguments are given.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_DATAERR}
-Exit code that means the input data was incorrect.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_NOINPUT}
-Exit code that means an input file did not exist or was not readable.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_NOUSER}
-Exit code that means a specified user did not exist.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_NOHOST}
-Exit code that means a specified host did not exist.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_UNAVAILABLE}
-Exit code that means that a required service is unavailable.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_SOFTWARE}
-Exit code that means an internal software error was detected.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_OSERR}
-Exit code that means an operating system error was detected, such as
-the inability to fork or create a pipe.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_OSFILE}
-Exit code that means some system file did not exist, could not be
-opened, or had some other kind of error.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_CANTCREAT}
-Exit code that means a user specified output file could not be created.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_IOERR}
-Exit code that means that an error occurred while doing I/O on some file.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_TEMPFAIL}
-Exit code that means a temporary failure occurred. This indicates
-something that may not really be an error, such as a network
-connection that couldn't be made during a retryable operation.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_PROTOCOL}
-Exit code that means that a protocol exchange was illegal, invalid, or
-not understood.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_NOPERM}
-Exit code that means that there were insufficient permissions to
-perform the operation (but not intended for file system problems).
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_CONFIG}
-Exit code that means that some kind of configuration error occurred.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_NOTFOUND}
-Exit code that means something like ``an entry was not found''.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{funcdesc}{fork}{}
-Fork a child process. Return \code{0} in the child, the child's
-process id in the parent.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{forkpty}{}
-Fork a child process, using a new pseudo-terminal as the child's
-controlling terminal. Return a pair of \code{(\var{pid}, \var{fd})},
-where \var{pid} is \code{0} in the child, the new child's process id
-in the parent, and \var{fd} is the file descriptor of the master end
-of the pseudo-terminal. For a more portable approach, use the
-\refmodule{pty} module.
-Availability: Macintosh, Some flavors of \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{kill}{pid, sig}
-\index{process!killing}
-\index{process!signalling}
-Send signal \var{sig} to the process \var{pid}. Constants for the
-specific signals available on the host platform are defined in the
-\refmodule{signal} module.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{killpg}{pgid, sig}
-\index{process!killing}
-\index{process!signalling}
-Send the signal \var{sig} to the process group \var{pgid}.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{nice}{increment}
-Add \var{increment} to the process's ``niceness''. Return the new
-niceness.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{plock}{op}
-Lock program segments into memory. The value of \var{op}
-(defined in \code{<sys/lock.h>}) determines which segments are locked.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdescni}{popen}{\unspecified}
-Run child processes, returning opened pipes for communications. These
-functions are described in section \ref{os-newstreams}.
-\end{funcdescni}
-
-\begin{funcdesc}{spawnl}{mode, path, \moreargs}
-\funcline{spawnle}{mode, path, \moreargs, env}
-\funcline{spawnlp}{mode, file, \moreargs}
-\funcline{spawnlpe}{mode, file, \moreargs, env}
-\funcline{spawnv}{mode, path, args}
-\funcline{spawnve}{mode, path, args, env}
-\funcline{spawnvp}{mode, file, args}
-\funcline{spawnvpe}{mode, file, args, env}
-Execute the program \var{path} in a new process.
-
-(Note that the \module{subprocess} module provides more powerful
-facilities for spawning new processes and retrieving their results;
-using that module is preferable to using these functions.)
-
-If \var{mode} is
-\constant{P_NOWAIT}, this function returns the process ID of the new
-process; if \var{mode} is \constant{P_WAIT}, returns the process's
-exit code if it exits normally, or \code{-\var{signal}}, where
-\var{signal} is the signal that killed the process. On Windows, the
-process ID will actually be the process handle, so can be used with
-the \function{waitpid()} function.
-
-The \character{l} and \character{v} variants of the
-\function{spawn*()} functions differ in how command-line arguments are
-passed. The \character{l} variants are perhaps the easiest to work
-with if the number of parameters is fixed when the code is written;
-the individual parameters simply become additional parameters to the
-\function{spawnl*()} functions. The \character{v} variants are good
-when the number of parameters is variable, with the arguments being
-passed in a list or tuple as the \var{args} parameter. In either
-case, the arguments to the child process must start with the name of
-the command being run.
-
-The variants which include a second \character{p} near the end
-(\function{spawnlp()}, \function{spawnlpe()}, \function{spawnvp()},
-and \function{spawnvpe()}) will use the \envvar{PATH} environment
-variable to locate the program \var{file}. When the environment is
-being replaced (using one of the \function{spawn*e()} variants,
-discussed in the next paragraph), the new environment is used as the
-source of the \envvar{PATH} variable. The other variants,
-\function{spawnl()}, \function{spawnle()}, \function{spawnv()}, and
-\function{spawnve()}, will not use the \envvar{PATH} variable to
-locate the executable; \var{path} must contain an appropriate absolute
-or relative path.
-
-For \function{spawnle()}, \function{spawnlpe()}, \function{spawnve()},
-and \function{spawnvpe()} (note that these all end in \character{e}),
-the \var{env} parameter must be a mapping which is used to define the
-environment variables for the new process; the \function{spawnl()},
-\function{spawnlp()}, \function{spawnv()}, and \function{spawnvp()}
-all cause the new process to inherit the environment of the current
-process.
-
-As an example, the following calls to \function{spawnlp()} and
-\function{spawnvpe()} are equivalent:
-
-\begin{verbatim}
-import os
-os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')
-
-L = ['cp', 'index.html', '/dev/null']
-os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
-\end{verbatim}
-
-Availability: \UNIX, Windows. \function{spawnlp()},
-\function{spawnlpe()}, \function{spawnvp()} and \function{spawnvpe()}
-are not available on Windows.
-\versionadded{1.6}
-\end{funcdesc}
-
-\begin{datadesc}{P_NOWAIT}
-\dataline{P_NOWAITO}
-Possible values for the \var{mode} parameter to the \function{spawn*()}
-family of functions. If either of these values is given, the
-\function{spawn*()} functions will return as soon as the new process
-has been created, with the process ID as the return value.
-Availability: Macintosh, \UNIX, Windows.
-\versionadded{1.6}
-\end{datadesc}
-
-\begin{datadesc}{P_WAIT}
-Possible value for the \var{mode} parameter to the \function{spawn*()}
-family of functions. If this is given as \var{mode}, the
-\function{spawn*()} functions will not return until the new process
-has run to completion and will return the exit code of the process the
-run is successful, or \code{-\var{signal}} if a signal kills the
-process.
-Availability: Macintosh, \UNIX, Windows.
-\versionadded{1.6}
-\end{datadesc}
-
-\begin{datadesc}{P_DETACH}
-\dataline{P_OVERLAY}
-Possible values for the \var{mode} parameter to the
-\function{spawn*()} family of functions. These are less portable than
-those listed above.
-\constant{P_DETACH} is similar to \constant{P_NOWAIT}, but the new
-process is detached from the console of the calling process.
-If \constant{P_OVERLAY} is used, the current process will be replaced;
-the \function{spawn*()} function will not return.
-Availability: Windows.
-\versionadded{1.6}
-\end{datadesc}
-
-\begin{funcdesc}{startfile}{path\optional{, operation}}
-Start a file with its associated application.
-
-When \var{operation} is not specified or \code{'open'}, this acts like
-double-clicking the file in Windows Explorer, or giving the file name
-as an argument to the \program{start} command from the interactive
-command shell: the file is opened with whatever application (if any)
-its extension is associated.
-
-When another \var{operation} is given, it must be a ``command verb''
-that specifies what should be done with the file.
-Common verbs documented by Microsoft are \code{'print'} and
-\code{'edit'} (to be used on files) as well as \code{'explore'} and
-\code{'find'} (to be used on directories).
-
-\function{startfile()} returns as soon as the associated application
-is launched. There is no option to wait for the application to close,
-and no way to retrieve the application's exit status. The \var{path}
-parameter is relative to the current directory. If you want to use an
-absolute path, make sure the first character is not a slash
-(\character{/}); the underlying Win32 \cfunction{ShellExecute()}
-function doesn't work if it is. Use the \function{os.path.normpath()}
-function to ensure that the path is properly encoded for Win32.
-Availability: Windows.
-\versionadded{2.0}
-\versionadded[The \var{operation} parameter]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{system}{command}
-Execute the command (a string) in a subshell. This is implemented by
-calling the Standard C function \cfunction{system()}, and has the
-same limitations. Changes to \code{posix.environ}, \code{sys.stdin},
-etc.\ are not reflected in the environment of the executed command.
-
-On \UNIX, the return value is the exit status of the process encoded in the
-format specified for \function{wait()}. Note that \POSIX{} does not
-specify the meaning of the return value of the C \cfunction{system()}
-function, so the return value of the Python function is system-dependent.
-
-On Windows, the return value is that returned by the system shell after
-running \var{command}, given by the Windows environment variable
-\envvar{COMSPEC}: on \program{command.com} systems (Windows 95, 98 and ME)
-this is always \code{0}; on \program{cmd.exe} systems (Windows NT, 2000
-and XP) this is the exit status of the command run; on systems using
-a non-native shell, consult your shell documentation.
-
-Availability: Macintosh, \UNIX, Windows.
-
-The \module{subprocess} module provides more powerful facilities for
-spawning new processes and retrieving their results; using that module
-is preferable to using this function.
-\end{funcdesc}
-
-\begin{funcdesc}{times}{}
-Return a 5-tuple of floating point numbers indicating accumulated
-(processor or other)
-times, in seconds. The items are: user time, system time, children's
-user time, children's system time, and elapsed real time since a fixed
-point in the past, in that order. See the \UNIX{} manual page
-\manpage{times}{2} or the corresponding Windows Platform API
-documentation.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{wait}{}
-Wait for completion of a child process, and return a tuple containing
-its pid and exit status indication: a 16-bit number, whose low byte is
-the signal number that killed the process, and whose high byte is the
-exit status (if the signal number is zero); the high bit of the low
-byte is set if a core file was produced.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{waitpid}{pid, options}
-The details of this function differ on \UNIX{} and Windows.
-
-On \UNIX:
-Wait for completion of a child process given by process id \var{pid},
-and return a tuple containing its process id and exit status
-indication (encoded as for \function{wait()}). The semantics of the
-call are affected by the value of the integer \var{options}, which
-should be \code{0} for normal operation.
-
-If \var{pid} is greater than \code{0}, \function{waitpid()} requests
-status information for that specific process. If \var{pid} is
-\code{0}, the request is for the status of any child in the process
-group of the current process. If \var{pid} is \code{-1}, the request
-pertains to any child of the current process. If \var{pid} is less
-than \code{-1}, status is requested for any process in the process
-group \code{-\var{pid}} (the absolute value of \var{pid}).
-
-On Windows:
-Wait for completion of a process given by process handle \var{pid},
-and return a tuple containing \var{pid},
-and its exit status shifted left by 8 bits (shifting makes cross-platform
-use of the function easier).
-A \var{pid} less than or equal to \code{0} has no special meaning on
-Windows, and raises an exception.
-The value of integer \var{options} has no effect.
-\var{pid} can refer to any process whose id is known, not necessarily a
-child process.
-The \function{spawn()} functions called with \constant{P_NOWAIT}
-return suitable process handles.
-\end{funcdesc}
-
-\begin{funcdesc}{wait3}{\optional{options}}
-Similar to \function{waitpid()}, except no process id argument is given and
-a 3-element tuple containing the child's process id, exit status indication,
-and resource usage information is returned. Refer to
-\module{resource}.\function{getrusage()}
-for details on resource usage information. The option argument is the same
-as that provided to \function{waitpid()} and \function{wait4()}.
-Availability: \UNIX.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{wait4}{pid, options}
-Similar to \function{waitpid()}, except a 3-element tuple, containing the
-child's process id, exit status indication, and resource usage information
-is returned. Refer to \module{resource}.\function{getrusage()} for details
-on resource usage information. The arguments to \function{wait4()} are
-the same as those provided to \function{waitpid()}.
-Availability: \UNIX.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{datadesc}{WNOHANG}
-The option for \function{waitpid()} to return immediately if no child
-process status is available immediately. The function returns
-\code{(0, 0)} in this case.
-Availability: Macintosh, \UNIX.
-\end{datadesc}
-
-\begin{datadesc}{WCONTINUED}
-This option causes child processes to be reported if they have been
-continued from a job control stop since their status was last
-reported.
-Availability: Some \UNIX{} systems.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{WUNTRACED}
-This option causes child processes to be reported if they have been
-stopped but their current state has not been reported since they were
-stopped.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-The following functions take a process status code as returned by
-\function{system()}, \function{wait()}, or \function{waitpid()} as a
-parameter. They may be used to determine the disposition of a
-process.
-
-\begin{funcdesc}{WCOREDUMP}{status}
-Returns \code{True} if a core dump was generated for the process,
-otherwise it returns \code{False}.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{WIFCONTINUED}{status}
-Returns \code{True} if the process has been continued from a job
-control stop, otherwise it returns \code{False}.
-Availability: \UNIX.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{WIFSTOPPED}{status}
-Returns \code{True} if the process has been stopped, otherwise it
-returns \code{False}.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{WIFSIGNALED}{status}
-Returns \code{True} if the process exited due to a signal, otherwise
-it returns \code{False}.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{WIFEXITED}{status}
-Returns \code{True} if the process exited using the \manpage{exit}{2}
-system call, otherwise it returns \code{False}.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{WEXITSTATUS}{status}
-If \code{WIFEXITED(\var{status})} is true, return the integer
-parameter to the \manpage{exit}{2} system call. Otherwise, the return
-value is meaningless.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{WSTOPSIG}{status}
-Return the signal which caused the process to stop.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{WTERMSIG}{status}
-Return the signal which caused the process to exit.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-
-\subsection{Miscellaneous System Information \label{os-path}}
-
-
-\begin{funcdesc}{confstr}{name}
-Return string-valued system configuration values.
-\var{name} specifies the configuration value to retrieve; it may be a
-string which is the name of a defined system value; these names are
-specified in a number of standards (\POSIX, \UNIX{} 95, \UNIX{} 98, and
-others). Some platforms define additional names as well. The names
-known to the host operating system are given as the keys of the
-\code{confstr_names} dictionary. For configuration variables not
-included in that mapping, passing an integer for \var{name} is also
-accepted.
-Availability: Macintosh, \UNIX.
-
-If the configuration value specified by \var{name} isn't defined,
-\code{None} is returned.
-
-If \var{name} is a string and is not known, \exception{ValueError} is
-raised. If a specific value for \var{name} is not supported by the
-host system, even if it is included in \code{confstr_names}, an
-\exception{OSError} is raised with \constant{errno.EINVAL} for the
-error number.
-\end{funcdesc}
-
-\begin{datadesc}{confstr_names}
-Dictionary mapping names accepted by \function{confstr()} to the
-integer values defined for those names by the host operating system.
-This can be used to determine the set of names known to the system.
-Availability: Macintosh, \UNIX.
-\end{datadesc}
-
-\begin{funcdesc}{getloadavg}{}
-Return the number of processes in the system run queue averaged over
-the last 1, 5, and 15 minutes or raises \exception{OSError} if the load
-average was unobtainable.
-
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{sysconf}{name}
-Return integer-valued system configuration values.
-If the configuration value specified by \var{name} isn't defined,
-\code{-1} is returned. The comments regarding the \var{name}
-parameter for \function{confstr()} apply here as well; the dictionary
-that provides information on the known names is given by
-\code{sysconf_names}.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{datadesc}{sysconf_names}
-Dictionary mapping names accepted by \function{sysconf()} to the
-integer values defined for those names by the host operating system.
-This can be used to determine the set of names known to the system.
-Availability: Macintosh, \UNIX.
-\end{datadesc}
-
-
-The follow data values are used to support path manipulation
-operations. These are defined for all platforms.
-
-Higher-level operations on pathnames are defined in the
-\refmodule{os.path} module.
-
-
-\begin{datadesc}{curdir}
-The constant string used by the operating system to refer to the current
-directory.
-For example: \code{'.'} for \POSIX{} or \code{':'} for Mac OS 9.
-Also available via \module{os.path}.
-\end{datadesc}
-
-\begin{datadesc}{pardir}
-The constant string used by the operating system to refer to the parent
-directory.
-For example: \code{'..'} for \POSIX{} or \code{'::'} for Mac OS 9.
-Also available via \module{os.path}.
-\end{datadesc}
-
-\begin{datadesc}{sep}
-The character used by the operating system to separate pathname components,
-for example, \character{/} for \POSIX{} or \character{:} for
-Mac OS 9. Note that knowing this is not sufficient to be able to
-parse or concatenate pathnames --- use \function{os.path.split()} and
-\function{os.path.join()} --- but it is occasionally useful.
-Also available via \module{os.path}.
-\end{datadesc}
-
-\begin{datadesc}{altsep}
-An alternative character used by the operating system to separate pathname
-components, or \code{None} if only one separator character exists. This is
-set to \character{/} on Windows systems where \code{sep} is a
-backslash.
-Also available via \module{os.path}.
-\end{datadesc}
-
-\begin{datadesc}{extsep}
-The character which separates the base filename from the extension;
-for example, the \character{.} in \file{os.py}.
-Also available via \module{os.path}.
-\versionadded{2.2}
-\end{datadesc}
-
-\begin{datadesc}{pathsep}
-The character conventionally used by the operating system to separate
-search path components (as in \envvar{PATH}), such as \character{:} for
-\POSIX{} or \character{;} for Windows.
-Also available via \module{os.path}.
-\end{datadesc}
-
-\begin{datadesc}{defpath}
-The default search path used by \function{exec*p*()} and
-\function{spawn*p*()} if the environment doesn't have a \code{'PATH'}
-key.
-Also available via \module{os.path}.
-\end{datadesc}
-
-\begin{datadesc}{linesep}
-The string used to separate (or, rather, terminate) lines on the
-current platform. This may be a single character, such as
-\code{'\e n'} for \POSIX{} or \code{'\e r'} for Mac OS, or multiple
-characters, for example, \code{'\e r\e n'} for Windows.
-Do not use \var{os.linesep} as a line terminator when writing files
-opened in text mode (the default); use a single \code{'\e n'} instead,
-on all platforms.
-\end{datadesc}
-
-\begin{datadesc}{devnull}
-The file path of the null device.
-For example: \code{'/dev/null'} for \POSIX{} or \code{'Dev:Nul'} for
-Mac OS 9.
-Also available via \module{os.path}.
-\versionadded{2.4}
-\end{datadesc}
-
-
-\subsection{Miscellaneous Functions \label{os-miscfunc}}
-
-\begin{funcdesc}{urandom}{n}
-Return a string of \var{n} random bytes suitable for cryptographic use.
-
-This function returns random bytes from an OS-specific
-randomness source. The returned data should be unpredictable enough for
-cryptographic applications, though its exact quality depends on the OS
-implementation. On a UNIX-like system this will query /dev/urandom, and
-on Windows it will use CryptGenRandom. If a randomness source is not
-found, \exception{NotImplementedError} will be raised.
-\versionadded{2.4}
-\end{funcdesc}
-
-
-
-
diff --git a/Doc/lib/libossaudiodev.tex b/Doc/lib/libossaudiodev.tex
deleted file mode 100644
index 4c19aaf..0000000
--- a/Doc/lib/libossaudiodev.tex
+++ /dev/null
@@ -1,401 +0,0 @@
-\section{\module{ossaudiodev} ---
- Access to OSS-compatible audio devices}
-
-\declaremodule{builtin}{ossaudiodev}
-\platform{Linux, FreeBSD}
-\modulesynopsis{Access to OSS-compatible audio devices.}
-
-\versionadded{2.3}
-
-This module allows you to access the OSS (Open Sound System) audio
-interface. OSS is available for a wide range of open-source and
-commercial Unices, and is the standard audio interface for Linux and
-recent versions of FreeBSD.
-
-% Things will get more complicated for future Linux versions, since
-% ALSA is in the standard kernel as of 2.5.x. Presumably if you
-% use ALSA, you'll have to make sure its OSS compatibility layer
-% is active to use ossaudiodev, but you're gonna need it for the vast
-% majority of Linux audio apps anyways.
-%
-% Sounds like things are also complicated for other BSDs. In response
-% to my python-dev query, Thomas Wouters said:
-%
-% > Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial
-% > OSS installation manual tells you to remove references to OSS/Free from the
-% > kernel :)
-%
-% but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes
-% from its <soundcard.h>:
-% > * WARNING! WARNING!
-% > * This is an OSS (Linux) audio emulator.
-% > * Use the Native NetBSD API for developing new code, and this
-% > * only for compiling Linux programs.
-%
-% There's also an ossaudio manpage on OpenBSD that explains things
-% further. Presumably NetBSD and OpenBSD have a different standard
-% audio interface. That's the great thing about standards, there are so
-% many to choose from ... ;-)
-%
-% This probably all warrants a footnote or two, but I don't understand
-% things well enough right now to write it! --GPW
-
-\begin{seealso}
-\seetitle[http://www.opensound.com/pguide/oss.pdf]
- {Open Sound System Programmer's Guide} {the official
- documentation for the OSS C API}
-\seetext{The module defines a large number of constants supplied by
- the OSS device driver; see \code{<sys/soundcard.h>} on either
- Linux or FreeBSD for a listing .}
-\end{seealso}
-
-\module{ossaudiodev} defines the following variables and functions:
-
-\begin{excdesc}{OSSAudioError}
-This exception is raised on certain errors. The argument is a string
-describing what went wrong.
-
-(If \module{ossaudiodev} receives an error from a system call such as
-\cfunction{open()}, \cfunction{write()}, or \cfunction{ioctl()}, it
-raises \exception{IOError}. Errors detected directly by
-\module{ossaudiodev} result in \exception{OSSAudioError}.)
-
-(For backwards compatibility, the exception class is also available as
-\code{ossaudiodev.error}.)
-\end{excdesc}
-
-\begin{funcdesc}{open}{\optional{device, }mode}
-Open an audio device and return an OSS audio device object. This
-object supports many file-like methods, such as \method{read()},
-\method{write()}, and \method{fileno()} (although there are subtle
-differences between conventional \UNIX{} read/write semantics and those of
-OSS audio devices). It also supports a number of audio-specific
-methods; see below for the complete list of methods.
-
-\var{device} is the audio device filename to use. If it is not
-specified, this module first looks in the environment variable
-\envvar{AUDIODEV} for a device to use. If not found, it falls back to
-\file{/dev/dsp}.
-
-\var{mode} is one of \code{'r'} for read-only (record) access,
-\code{'w'} for write-only (playback) access and \code{'rw'} for both.
-Since many sound cards only allow one process to have the recorder or
-player open at a time, it is a good idea to open the device only for the
-activity needed. Further, some sound cards are half-duplex: they can be
-opened for reading or writing, but not both at once.
-
-Note the unusual calling syntax: the \emph{first} argument is optional,
-and the second is required. This is a historical artifact for
-compatibility with the older \module{linuxaudiodev} module which
-\module{ossaudiodev} supersedes. % XXX it might also be motivated
-% by my unfounded-but-still-possibly-true belief that the default
-% audio device varies unpredictably across operating systems. -GW
-\end{funcdesc}
-
-\begin{funcdesc}{openmixer}{\optional{device}}
-Open a mixer device and return an OSS mixer device object.
-\var{device} is the mixer device filename to use. If it is
-not specified, this module first looks in the environment variable
-\envvar{MIXERDEV} for a device to use. If not found, it falls back to
-\file{/dev/mixer}.
-
-\end{funcdesc}
-
-\subsection{Audio Device Objects \label{ossaudio-device-objects}}
-
-Before you can write to or read from an audio device, you must call
-three methods in the correct order:
-\begin{enumerate}
-\item \method{setfmt()} to set the output format
-\item \method{channels()} to set the number of channels
-\item \method{speed()} to set the sample rate
-\end{enumerate}
-Alternately, you can use the \method{setparameters()} method to set all
-three audio parameters at once. This is more convenient, but may not be
-as flexible in all cases.
-
-The audio device objects returned by \function{open()} define the
-following methods and (read-only) attributes:
-
-\begin{methoddesc}[audio device]{close}{}
-Explicitly close the audio device. When you are done writing to or
-reading from an audio device, you should explicitly close it. A closed
-device cannot be used again.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{fileno}{}
-Return the file descriptor associated with the device.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{read}{size}
-Read \var{size} bytes from the audio input and return them as a Python
-string. Unlike most \UNIX{} device drivers, OSS audio devices in
-blocking mode (the default) will block \function{read()} until the
-entire requested amount of data is available.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{write}{data}
-Write the Python string \var{data} to the audio device and return the
-number of bytes written. If the audio device is in blocking mode (the
-default), the entire string is always written (again, this is different
-from usual \UNIX{} device semantics). If the device is in non-blocking
-mode, some data may not be written---see \method{writeall()}.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{writeall}{data}
-Write the entire Python string \var{data} to the audio device: waits
-until the audio device is able to accept data, writes as much data as it
-will accept, and repeats until \var{data} has been completely written.
-If the device is in blocking mode (the default), this has the same
-effect as \method{write()}; \method{writeall()} is only useful in
-non-blocking mode. Has no return value, since the amount of data
-written is always equal to the amount of data supplied.
-\end{methoddesc}
-
-The following methods each map to exactly one
-\function{ioctl()} system call. The correspondence is obvious: for
-example, \method{setfmt()} corresponds to the \code{SNDCTL_DSP_SETFMT}
-ioctl, and \method{sync()} to \code{SNDCTL_DSP_SYNC} (this can be useful
-when consulting the OSS documentation). If the underlying
-\function{ioctl()} fails, they all raise \exception{IOError}.
-
-\begin{methoddesc}[audio device]{nonblock}{}
-Put the device into non-blocking mode. Once in non-blocking mode, there
-is no way to return it to blocking mode.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{getfmts}{}
-Return a bitmask of the audio output formats supported by the
-soundcard. Some of the formats supported by OSS are:
-
-\begin{tableii}{l|l}{constant}{Format}{Description}
-\lineii{AFMT_MU_LAW}
- {a logarithmic encoding (used by Sun \code{.au} files and
- \filenq{/dev/audio})}
-\lineii{AFMT_A_LAW}
- {a logarithmic encoding}
-\lineii{AFMT_IMA_ADPCM}
- {a 4:1 compressed format defined by the Interactive Multimedia
- Association}
-\lineii{AFMT_U8}
- {Unsigned, 8-bit audio}
-\lineii{AFMT_S16_LE}
- {Signed, 16-bit audio, little-endian byte order (as used by
- Intel processors)}
-\lineii{AFMT_S16_BE}
- {Signed, 16-bit audio, big-endian byte order (as used by 68k,
- PowerPC, Sparc)}
-\lineii{AFMT_S8}
- {Signed, 8 bit audio}
-\lineii{AFMT_U16_LE}
- {Unsigned, 16-bit little-endian audio}
-\lineii{AFMT_U16_BE}
- {Unsigned, 16-bit big-endian audio}
-\end{tableii}
-Consult the OSS documentation for a full list of audio formats, and note
-that most devices support only a subset of these formats. Some older
-devices only support \constant{AFMT_U8}; the most common format used
-today is \constant{AFMT_S16_LE}.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{setfmt}{format}
-Try to set the current audio format to \var{format}---see
-\method{getfmts()} for a list. Returns the audio format that the device
-was set to, which may not be the requested format. May also be used to
-return the current audio format---do this by passing an ``audio format''
-of
-\constant{AFMT_QUERY}.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{channels}{nchannels}
-Set the number of output channels to \var{nchannels}. A value of 1
-indicates monophonic sound, 2 stereophonic. Some devices may have more
-than 2 channels, and some high-end devices may not support mono.
-Returns the number of channels the device was set to.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{speed}{samplerate}
-Try to set the audio sampling rate to \var{samplerate} samples per
-second. Returns the rate actually set. Most sound devices don't
-support arbitrary sampling rates. Common rates are:
-\begin{tableii}{l|l}{textrm}{Rate}{Description}
-\lineii{8000}{default rate for \filenq{/dev/audio}}
-\lineii{11025}{speech recording}
-\lineii{22050}{}
-\lineii{44100}{CD quality audio (at 16 bits/sample and 2 channels)}
-\lineii{96000}{DVD quality audio (at 24 bits/sample)}
-\end{tableii}
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{sync}{}
-Wait until the sound device has played every byte in its buffer. (This
-happens implicitly when the device is closed.) The OSS documentation
-recommends closing and re-opening the device rather than using
-\method{sync()}.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{reset}{}
-Immediately stop playing or recording and return the device to a
-state where it can accept commands. The OSS documentation recommends
-closing and re-opening the device after calling \method{reset()}.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{post}{}
-Tell the driver that there is likely to be a pause in the output, making
-it possible for the device to handle the pause more intelligently. You
-might use this after playing a spot sound effect, before waiting for
-user input, or before doing disk I/O.
-\end{methoddesc}
-
-The following convenience methods combine several ioctls, or one ioctl
-and some simple calculations.
-
-\begin{methoddesc}[audio device]{setparameters}
- {format, nchannels, samplerate \optional{, strict=False}}
-
-Set the key audio sampling parameters---sample format, number of
-channels, and sampling rate---in one method call. \var{format},
-\var{nchannels}, and \var{samplerate} should be as specified in the
-\method{setfmt()}, \method{channels()}, and \method{speed()}
-methods. If \var{strict} is true, \method{setparameters()} checks to
-see if each parameter was actually set to the requested value, and
-raises \exception{OSSAudioError} if not. Returns a tuple (\var{format},
-\var{nchannels}, \var{samplerate}) indicating the parameter values that
-were actually set by the device driver (i.e., the same as the return
-values of \method{setfmt()}, \method{channels()}, and \method{speed()}).
-
-For example,
-\begin{verbatim}
- (fmt, channels, rate) = dsp.setparameters(fmt, channels, rate)
-\end{verbatim}
-is equivalent to
-\begin{verbatim}
- fmt = dsp.setfmt(fmt)
- channels = dsp.channels(channels)
- rate = dsp.rate(channels)
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{bufsize}{}
-Returns the size of the hardware buffer, in samples.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{obufcount}{}
-Returns the number of samples that are in the hardware buffer yet to be
-played.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{obuffree}{}
-Returns the number of samples that could be queued into the hardware
-buffer to be played without blocking.
-\end{methoddesc}
-
-Audio device objects also support several read-only attributes:
-
-\begin{memberdesc}[audio device]{closed}{}
-Boolean indicating whether the device has been closed.
-\end{memberdesc}
-
-\begin{memberdesc}[audio device]{name}{}
-String containing the name of the device file.
-\end{memberdesc}
-
-\begin{memberdesc}[audio device]{mode}{}
-The I/O mode for the file, either \code{"r"}, \code{"rw"}, or \code{"w"}.
-\end{memberdesc}
-
-
-\subsection{Mixer Device Objects \label{mixer-device-objects}}
-
-The mixer object provides two file-like methods:
-
-\begin{methoddesc}[mixer device]{close}{}
-This method closes the open mixer device file. Any further attempts to
-use the mixer after this file is closed will raise an \exception{IOError}.
-\end{methoddesc}
-
-\begin{methoddesc}[mixer device]{fileno}{}
-Returns the file handle number of the open mixer device file.
-\end{methoddesc}
-
-The remaining methods are specific to audio mixing:
-
-\begin{methoddesc}[mixer device]{controls}{}
-This method returns a bitmask specifying the available mixer controls
-(``Control'' being a specific mixable ``channel'', such as
-\constant{SOUND_MIXER_PCM} or \constant{SOUND_MIXER_SYNTH}). This
-bitmask indicates a subset of all available mixer controls---the
-\constant{SOUND_MIXER_*} constants defined at module level. To determine if,
-for example, the current mixer object supports a PCM mixer, use the
-following Python code:
-
-\begin{verbatim}
-mixer=ossaudiodev.openmixer()
-if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM):
- # PCM is supported
- ... code ...
-\end{verbatim}
-
-For most purposes, the \constant{SOUND_MIXER_VOLUME} (master volume) and
-\constant{SOUND_MIXER_PCM} controls should suffice---but code that uses the
-mixer should be flexible when it comes to choosing mixer controls. On
-the Gravis Ultrasound, for example, \constant{SOUND_MIXER_VOLUME} does not
-exist.
-\end{methoddesc}
-
-\begin{methoddesc}[mixer device]{stereocontrols}{}
-Returns a bitmask indicating stereo mixer controls. If a bit is set,
-the corresponding control is stereo; if it is unset, the control is
-either monophonic or not supported by the mixer (use in combination with
-\method{controls()} to determine which).
-
-See the code example for the \method{controls()} function for an example
-of getting data from a bitmask.
-\end{methoddesc}
-
-\begin{methoddesc}[mixer device]{reccontrols}{}
-Returns a bitmask specifying the mixer controls that may be used to
-record. See the code example for \method{controls()} for an example of
-reading from a bitmask.
-\end{methoddesc}
-
-\begin{methoddesc}[mixer device]{get}{control}
-Returns the volume of a given mixer control. The returned volume is a
-2-tuple \code{(left_volume,right_volume)}. Volumes are specified as
-numbers from 0 (silent) to 100 (full volume). If the control is
-monophonic, a 2-tuple is still returned, but both volumes are
-the same.
-
-Raises \exception{OSSAudioError} if an invalid control was is specified,
-or \exception{IOError} if an unsupported control is specified.
-\end{methoddesc}
-
-\begin{methoddesc}[mixer device]{set}{control, (left, right)}
-Sets the volume for a given mixer control to \code{(left,right)}.
-\code{left} and \code{right} must be ints and between 0 (silent) and 100
-(full volume). On success, the new volume is returned as a 2-tuple.
-Note that this may not be exactly the same as the volume specified,
-because of the limited resolution of some soundcard's mixers.
-
-Raises \exception{OSSAudioError} if an invalid mixer control was
-specified, or if the specified volumes were out-of-range.
-\end{methoddesc}
-
-\begin{methoddesc}[mixer device]{get_recsrc}{}
-This method returns a bitmask indicating which control(s) are
-currently being used as a recording source.
-\end{methoddesc}
-
-\begin{methoddesc}[mixer device]{set_recsrc}{bitmask}
-Call this function to specify a recording source. Returns a bitmask
-indicating the new recording source (or sources) if successful; raises
-\exception{IOError} if an invalid source was specified. To set the current
-recording source to the microphone input:
-
-\begin{verbatim}
-mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)
-\end{verbatim}
-\end{methoddesc}
-
-
-
diff --git a/Doc/lib/libparser.tex b/Doc/lib/libparser.tex
deleted file mode 100644
index a993624..0000000
--- a/Doc/lib/libparser.tex
+++ /dev/null
@@ -1,712 +0,0 @@
-\section{\module{parser} ---
- Access Python parse trees}
-
-% Copyright 1995 Virginia Polytechnic Institute and State University
-% and Fred L. Drake, Jr. This copyright notice must be distributed on
-% all copies, but this document otherwise may be distributed as part
-% of the Python distribution. No fee may be charged for this document
-% in any representation, either on paper or electronically. This
-% restriction does not affect other elements in a distributed package
-% in any way.
-
-\declaremodule{builtin}{parser}
-\modulesynopsis{Access parse trees for Python source code.}
-\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-\index{parsing!Python source code}
-
-The \module{parser} module provides an interface to Python's internal
-parser and byte-code compiler. The primary purpose for this interface
-is to allow Python code to edit the parse tree of a Python expression
-and create executable code from this. This is better than trying
-to parse and modify an arbitrary Python code fragment as a string
-because parsing is performed in a manner identical to the code
-forming the application. It is also faster.
-
-There are a few things to note about this module which are important
-to making use of the data structures created. This is not a tutorial
-on editing the parse trees for Python code, but some examples of using
-the \module{parser} module are presented.
-
-Most importantly, a good understanding of the Python grammar processed
-by the internal parser is required. For full information on the
-language syntax, refer to the \citetitle[../ref/ref.html]{Python
-Language Reference}. The parser itself is created from a grammar
-specification defined in the file \file{Grammar/Grammar} in the
-standard Python distribution. The parse trees stored in the AST
-objects created by this module are the actual output from the internal
-parser when created by the \function{expr()} or \function{suite()}
-functions, described below. The AST objects created by
-\function{sequence2ast()} faithfully simulate those structures. Be
-aware that the values of the sequences which are considered
-``correct'' will vary from one version of Python to another as the
-formal grammar for the language is revised. However, transporting
-code from one Python version to another as source text will always
-allow correct parse trees to be created in the target version, with
-the only restriction being that migrating to an older version of the
-interpreter will not support more recent language constructs. The
-parse trees are not typically compatible from one version to another,
-whereas source code has always been forward-compatible.
-
-Each element of the sequences returned by \function{ast2list()} or
-\function{ast2tuple()} has a simple form. Sequences representing
-non-terminal elements in the grammar always have a length greater than
-one. The first element is an integer which identifies a production in
-the grammar. These integers are given symbolic names in the C header
-file \file{Include/graminit.h} and the Python module
-\refmodule{symbol}. Each additional element of the sequence represents
-a component of the production as recognized in the input string: these
-are always sequences which have the same form as the parent. An
-important aspect of this structure which should be noted is that
-keywords used to identify the parent node type, such as the keyword
-\keyword{if} in an \constant{if_stmt}, are included in the node tree without
-any special treatment. For example, the \keyword{if} keyword is
-represented by the tuple \code{(1, 'if')}, where \code{1} is the
-numeric value associated with all \constant{NAME} tokens, including
-variable and function names defined by the user. In an alternate form
-returned when line number information is requested, the same token
-might be represented as \code{(1, 'if', 12)}, where the \code{12}
-represents the line number at which the terminal symbol was found.
-
-Terminal elements are represented in much the same way, but without
-any child elements and the addition of the source text which was
-identified. The example of the \keyword{if} keyword above is
-representative. The various types of terminal symbols are defined in
-the C header file \file{Include/token.h} and the Python module
-\refmodule{token}.
-
-The AST objects are not required to support the functionality of this
-module, but are provided for three purposes: to allow an application
-to amortize the cost of processing complex parse trees, to provide a
-parse tree representation which conserves memory space when compared
-to the Python list or tuple representation, and to ease the creation
-of additional modules in C which manipulate parse trees. A simple
-``wrapper'' class may be created in Python to hide the use of AST
-objects.
-
-The \module{parser} module defines functions for a few distinct
-purposes. The most important purposes are to create AST objects and
-to convert AST objects to other representations such as parse trees
-and compiled code objects, but there are also functions which serve to
-query the type of parse tree represented by an AST object.
-
-
-\begin{seealso}
- \seemodule{symbol}{Useful constants representing internal nodes of
- the parse tree.}
- \seemodule{token}{Useful constants representing leaf nodes of the
- parse tree and functions for testing node values.}
-\end{seealso}
-
-
-\subsection{Creating AST Objects \label{Creating ASTs}}
-
-AST objects may be created from source code or from a parse tree.
-When creating an AST object from source, different functions are used
-to create the \code{'eval'} and \code{'exec'} forms.
-
-\begin{funcdesc}{expr}{source}
-The \function{expr()} function parses the parameter \var{source}
-as if it were an input to \samp{compile(\var{source}, 'file.py',
-'eval')}. If the parse succeeds, an AST object is created to hold the
-internal parse tree representation, otherwise an appropriate exception
-is thrown.
-\end{funcdesc}
-
-\begin{funcdesc}{suite}{source}
-The \function{suite()} function parses the parameter \var{source}
-as if it were an input to \samp{compile(\var{source}, 'file.py',
-'exec')}. If the parse succeeds, an AST object is created to hold the
-internal parse tree representation, otherwise an appropriate exception
-is thrown.
-\end{funcdesc}
-
-\begin{funcdesc}{sequence2ast}{sequence}
-This function accepts a parse tree represented as a sequence and
-builds an internal representation if possible. If it can validate
-that the tree conforms to the Python grammar and all nodes are valid
-node types in the host version of Python, an AST object is created
-from the internal representation and returned to the called. If there
-is a problem creating the internal representation, or if the tree
-cannot be validated, a \exception{ParserError} exception is thrown. An AST
-object created this way should not be assumed to compile correctly;
-normal exceptions thrown by compilation may still be initiated when
-the AST object is passed to \function{compileast()}. This may indicate
-problems not related to syntax (such as a \exception{MemoryError}
-exception), but may also be due to constructs such as the result of
-parsing \code{del f(0)}, which escapes the Python parser but is
-checked by the bytecode compiler.
-
-Sequences representing terminal tokens may be represented as either
-two-element lists of the form \code{(1, 'name')} or as three-element
-lists of the form \code{(1, 'name', 56)}. If the third element is
-present, it is assumed to be a valid line number. The line number
-may be specified for any subset of the terminal symbols in the input
-tree.
-\end{funcdesc}
-
-\begin{funcdesc}{tuple2ast}{sequence}
-This is the same function as \function{sequence2ast()}. This entry point
-is maintained for backward compatibility.
-\end{funcdesc}
-
-
-\subsection{Converting AST Objects \label{Converting ASTs}}
-
-AST objects, regardless of the input used to create them, may be
-converted to parse trees represented as list- or tuple- trees, or may
-be compiled into executable code objects. Parse trees may be
-extracted with or without line numbering information.
-
-\begin{funcdesc}{ast2list}{ast\optional{, line_info}}
-This function accepts an AST object from the caller in
-\var{ast} and returns a Python list representing the
-equivalent parse tree. The resulting list representation can be used
-for inspection or the creation of a new parse tree in list form. This
-function does not fail so long as memory is available to build the
-list representation. If the parse tree will only be used for
-inspection, \function{ast2tuple()} should be used instead to reduce memory
-consumption and fragmentation. When the list representation is
-required, this function is significantly faster than retrieving a
-tuple representation and converting that to nested lists.
-
-If \var{line_info} is true, line number information will be
-included for all terminal tokens as a third element of the list
-representing the token. Note that the line number provided specifies
-the line on which the token \emph{ends}. This information is
-omitted if the flag is false or omitted.
-\end{funcdesc}
-
-\begin{funcdesc}{ast2tuple}{ast\optional{, line_info}}
-This function accepts an AST object from the caller in
-\var{ast} and returns a Python tuple representing the
-equivalent parse tree. Other than returning a tuple instead of a
-list, this function is identical to \function{ast2list()}.
-
-If \var{line_info} is true, line number information will be
-included for all terminal tokens as a third element of the list
-representing the token. This information is omitted if the flag is
-false or omitted.
-\end{funcdesc}
-
-\begin{funcdesc}{compileast}{ast\optional{, filename\code{ = '<ast>'}}}
-The Python byte compiler can be invoked on an AST object to produce
-code objects which can be used as part of a call to the built-in
-\function{exec()}\bifuncindex{exec} or \function{eval()}
-\bifuncindex{eval} functions.
-This function provides the interface to the compiler, passing the
-internal parse tree from \var{ast} to the parser, using the
-source file name specified by the \var{filename} parameter.
-The default value supplied for \var{filename} indicates that
-the source was an AST object.
-
-Compiling an AST object may result in exceptions related to
-compilation; an example would be a \exception{SyntaxError} caused by the
-parse tree for \code{del f(0)}: this statement is considered legal
-within the formal grammar for Python but is not a legal language
-construct. The \exception{SyntaxError} raised for this condition is
-actually generated by the Python byte-compiler normally, which is why
-it can be raised at this point by the \module{parser} module. Most
-causes of compilation failure can be diagnosed programmatically by
-inspection of the parse tree.
-\end{funcdesc}
-
-
-\subsection{Queries on AST Objects \label{Querying ASTs}}
-
-Two functions are provided which allow an application to determine if
-an AST was created as an expression or a suite. Neither of these
-functions can be used to determine if an AST was created from source
-code via \function{expr()} or \function{suite()} or from a parse tree
-via \function{sequence2ast()}.
-
-\begin{funcdesc}{isexpr}{ast}
-When \var{ast} represents an \code{'eval'} form, this function
-returns true, otherwise it returns false. This is useful, since code
-objects normally cannot be queried for this information using existing
-built-in functions. Note that the code objects created by
-\function{compileast()} cannot be queried like this either, and are
-identical to those created by the built-in
-\function{compile()}\bifuncindex{compile} function.
-\end{funcdesc}
-
-
-\begin{funcdesc}{issuite}{ast}
-This function mirrors \function{isexpr()} in that it reports whether an
-AST object represents an \code{'exec'} form, commonly known as a
-``suite.'' It is not safe to assume that this function is equivalent
-to \samp{not isexpr(\var{ast})}, as additional syntactic fragments may
-be supported in the future.
-\end{funcdesc}
-
-
-\subsection{Exceptions and Error Handling \label{AST Errors}}
-
-The parser module defines a single exception, but may also pass other
-built-in exceptions from other portions of the Python runtime
-environment. See each function for information about the exceptions
-it can raise.
-
-\begin{excdesc}{ParserError}
-Exception raised when a failure occurs within the parser module. This
-is generally produced for validation failures rather than the built in
-\exception{SyntaxError} thrown during normal parsing.
-The exception argument is either a string describing the reason of the
-failure or a tuple containing a sequence causing the failure from a parse
-tree passed to \function{sequence2ast()} and an explanatory string. Calls to
-\function{sequence2ast()} need to be able to handle either type of exception,
-while calls to other functions in the module will only need to be
-aware of the simple string values.
-\end{excdesc}
-
-Note that the functions \function{compileast()}, \function{expr()}, and
-\function{suite()} may throw exceptions which are normally thrown by the
-parsing and compilation process. These include the built in
-exceptions \exception{MemoryError}, \exception{OverflowError},
-\exception{SyntaxError}, and \exception{SystemError}. In these cases, these
-exceptions carry all the meaning normally associated with them. Refer
-to the descriptions of each function for detailed information.
-
-
-\subsection{AST Objects \label{AST Objects}}
-
-Ordered and equality comparisons are supported between AST objects.
-Pickling of AST objects (using the \refmodule{pickle} module) is also
-supported.
-
-\begin{datadesc}{ASTType}
-The type of the objects returned by \function{expr()},
-\function{suite()} and \function{sequence2ast()}.
-\end{datadesc}
-
-
-AST objects have the following methods:
-
-
-\begin{methoddesc}[AST]{compile}{\optional{filename}}
-Same as \code{compileast(\var{ast}, \var{filename})}.
-\end{methoddesc}
-
-\begin{methoddesc}[AST]{isexpr}{}
-Same as \code{isexpr(\var{ast})}.
-\end{methoddesc}
-
-\begin{methoddesc}[AST]{issuite}{}
-Same as \code{issuite(\var{ast})}.
-\end{methoddesc}
-
-\begin{methoddesc}[AST]{tolist}{\optional{line_info}}
-Same as \code{ast2list(\var{ast}, \var{line_info})}.
-\end{methoddesc}
-
-\begin{methoddesc}[AST]{totuple}{\optional{line_info}}
-Same as \code{ast2tuple(\var{ast}, \var{line_info})}.
-\end{methoddesc}
-
-
-\subsection{Examples \label{AST Examples}}
-
-The parser modules allows operations to be performed on the parse tree
-of Python source code before the bytecode is generated, and provides
-for inspection of the parse tree for information gathering purposes.
-Two examples are presented. The simple example demonstrates emulation
-of the \function{compile()}\bifuncindex{compile} built-in function and
-the complex example shows the use of a parse tree for information
-discovery.
-
-\subsubsection{Emulation of \function{compile()}}
-
-While many useful operations may take place between parsing and
-bytecode generation, the simplest operation is to do nothing. For
-this purpose, using the \module{parser} module to produce an
-intermediate data structure is equivalent to the code
-
-\begin{verbatim}
->>> code = compile('a + 5', 'file.py', 'eval')
->>> a = 5
->>> eval(code)
-10
-\end{verbatim}
-
-The equivalent operation using the \module{parser} module is somewhat
-longer, and allows the intermediate internal parse tree to be retained
-as an AST object:
-
-\begin{verbatim}
->>> import parser
->>> ast = parser.expr('a + 5')
->>> code = ast.compile('file.py')
->>> a = 5
->>> eval(code)
-10
-\end{verbatim}
-
-An application which needs both AST and code objects can package this
-code into readily available functions:
-
-\begin{verbatim}
-import parser
-
-def load_suite(source_string):
- ast = parser.suite(source_string)
- return ast, ast.compile()
-
-def load_expression(source_string):
- ast = parser.expr(source_string)
- return ast, ast.compile()
-\end{verbatim}
-
-\subsubsection{Information Discovery}
-
-Some applications benefit from direct access to the parse tree. The
-remainder of this section demonstrates how the parse tree provides
-access to module documentation defined in
-docstrings\index{string!documentation}\index{docstrings} without
-requiring that the code being examined be loaded into a running
-interpreter via \keyword{import}. This can be very useful for
-performing analyses of untrusted code.
-
-Generally, the example will demonstrate how the parse tree may be
-traversed to distill interesting information. Two functions and a set
-of classes are developed which provide programmatic access to high
-level function and class definitions provided by a module. The
-classes extract information from the parse tree and provide access to
-the information at a useful semantic level, one function provides a
-simple low-level pattern matching capability, and the other function
-defines a high-level interface to the classes by handling file
-operations on behalf of the caller. All source files mentioned here
-which are not part of the Python installation are located in the
-\file{Demo/parser/} directory of the distribution.
-
-The dynamic nature of Python allows the programmer a great deal of
-flexibility, but most modules need only a limited measure of this when
-defining classes, functions, and methods. In this example, the only
-definitions that will be considered are those which are defined in the
-top level of their context, e.g., a function defined by a \keyword{def}
-statement at column zero of a module, but not a function defined
-within a branch of an \keyword{if} ... \keyword{else} construct, though
-there are some good reasons for doing so in some situations. Nesting
-of definitions will be handled by the code developed in the example.
-
-To construct the upper-level extraction methods, we need to know what
-the parse tree structure looks like and how much of it we actually
-need to be concerned about. Python uses a moderately deep parse tree
-so there are a large number of intermediate nodes. It is important to
-read and understand the formal grammar used by Python. This is
-specified in the file \file{Grammar/Grammar} in the distribution.
-Consider the simplest case of interest when searching for docstrings:
-a module consisting of a docstring and nothing else. (See file
-\file{docstring.py}.)
-
-\begin{verbatim}
-"""Some documentation.
-"""
-\end{verbatim}
-
-Using the interpreter to take a look at the parse tree, we find a
-bewildering mass of numbers and parentheses, with the documentation
-buried deep in nested tuples.
-
-\begin{verbatim}
->>> import parser
->>> import pprint
->>> ast = parser.suite(open('docstring.py').read())
->>> tup = ast.totuple()
->>> pprint.pprint(tup)
-(257,
- (264,
- (265,
- (266,
- (267,
- (307,
- (287,
- (288,
- (289,
- (290,
- (292,
- (293,
- (294,
- (295,
- (296,
- (297,
- (298,
- (299,
- (300, (3, '"""Some documentation.\n"""'))))))))))))))))),
- (4, ''))),
- (4, ''),
- (0, ''))
-\end{verbatim}
-
-The numbers at the first element of each node in the tree are the node
-types; they map directly to terminal and non-terminal symbols in the
-grammar. Unfortunately, they are represented as integers in the
-internal representation, and the Python structures generated do not
-change that. However, the \refmodule{symbol} and \refmodule{token} modules
-provide symbolic names for the node types and dictionaries which map
-from the integers to the symbolic names for the node types.
-
-In the output presented above, the outermost tuple contains four
-elements: the integer \code{257} and three additional tuples. Node
-type \code{257} has the symbolic name \constant{file_input}. Each of
-these inner tuples contains an integer as the first element; these
-integers, \code{264}, \code{4}, and \code{0}, represent the node types
-\constant{stmt}, \constant{NEWLINE}, and \constant{ENDMARKER},
-respectively.
-Note that these values may change depending on the version of Python
-you are using; consult \file{symbol.py} and \file{token.py} for
-details of the mapping. It should be fairly clear that the outermost
-node is related primarily to the input source rather than the contents
-of the file, and may be disregarded for the moment. The \constant{stmt}
-node is much more interesting. In particular, all docstrings are
-found in subtrees which are formed exactly as this node is formed,
-with the only difference being the string itself. The association
-between the docstring in a similar tree and the defined entity (class,
-function, or module) which it describes is given by the position of
-the docstring subtree within the tree defining the described
-structure.
-
-By replacing the actual docstring with something to signify a variable
-component of the tree, we allow a simple pattern matching approach to
-check any given subtree for equivalence to the general pattern for
-docstrings. Since the example demonstrates information extraction, we
-can safely require that the tree be in tuple form rather than list
-form, allowing a simple variable representation to be
-\code{['variable_name']}. A simple recursive function can implement
-the pattern matching, returning a Boolean and a dictionary of variable
-name to value mappings. (See file \file{example.py}.)
-
-\begin{verbatim}
-from types import ListType, TupleType
-
-def match(pattern, data, vars=None):
- if vars is None:
- vars = {}
- if type(pattern) is ListType:
- vars[pattern[0]] = data
- return 1, vars
- if type(pattern) is not TupleType:
- return (pattern == data), vars
- if len(data) != len(pattern):
- return 0, vars
- for pattern, data in map(None, pattern, data):
- same, vars = match(pattern, data, vars)
- if not same:
- break
- return same, vars
-\end{verbatim}
-
-Using this simple representation for syntactic variables and the symbolic
-node types, the pattern for the candidate docstring subtrees becomes
-fairly readable. (See file \file{example.py}.)
-
-\begin{verbatim}
-import symbol
-import token
-
-DOCSTRING_STMT_PATTERN = (
- symbol.stmt,
- (symbol.simple_stmt,
- (symbol.small_stmt,
- (symbol.expr_stmt,
- (symbol.testlist,
- (symbol.test,
- (symbol.and_test,
- (symbol.not_test,
- (symbol.comparison,
- (symbol.expr,
- (symbol.xor_expr,
- (symbol.and_expr,
- (symbol.shift_expr,
- (symbol.arith_expr,
- (symbol.term,
- (symbol.factor,
- (symbol.power,
- (symbol.atom,
- (token.STRING, ['docstring'])
- )))))))))))))))),
- (token.NEWLINE, '')
- ))
-\end{verbatim}
-
-Using the \function{match()} function with this pattern, extracting the
-module docstring from the parse tree created previously is easy:
-
-\begin{verbatim}
->>> found, vars = match(DOCSTRING_STMT_PATTERN, tup[1])
->>> found
-1
->>> vars
-{'docstring': '"""Some documentation.\n"""'}
-\end{verbatim}
-
-Once specific data can be extracted from a location where it is
-expected, the question of where information can be expected
-needs to be answered. When dealing with docstrings, the answer is
-fairly simple: the docstring is the first \constant{stmt} node in a code
-block (\constant{file_input} or \constant{suite} node types). A module
-consists of a single \constant{file_input} node, and class and function
-definitions each contain exactly one \constant{suite} node. Classes and
-functions are readily identified as subtrees of code block nodes which
-start with \code{(stmt, (compound_stmt, (classdef, ...} or
-\code{(stmt, (compound_stmt, (funcdef, ...}. Note that these subtrees
-cannot be matched by \function{match()} since it does not support multiple
-sibling nodes to match without regard to number. A more elaborate
-matching function could be used to overcome this limitation, but this
-is sufficient for the example.
-
-Given the ability to determine whether a statement might be a
-docstring and extract the actual string from the statement, some work
-needs to be performed to walk the parse tree for an entire module and
-extract information about the names defined in each context of the
-module and associate any docstrings with the names. The code to
-perform this work is not complicated, but bears some explanation.
-
-The public interface to the classes is straightforward and should
-probably be somewhat more flexible. Each ``major'' block of the
-module is described by an object providing several methods for inquiry
-and a constructor which accepts at least the subtree of the complete
-parse tree which it represents. The \class{ModuleInfo} constructor
-accepts an optional \var{name} parameter since it cannot
-otherwise determine the name of the module.
-
-The public classes include \class{ClassInfo}, \class{FunctionInfo},
-and \class{ModuleInfo}. All objects provide the
-methods \method{get_name()}, \method{get_docstring()},
-\method{get_class_names()}, and \method{get_class_info()}. The
-\class{ClassInfo} objects support \method{get_method_names()} and
-\method{get_method_info()} while the other classes provide
-\method{get_function_names()} and \method{get_function_info()}.
-
-Within each of the forms of code block that the public classes
-represent, most of the required information is in the same form and is
-accessed in the same way, with classes having the distinction that
-functions defined at the top level are referred to as ``methods.''
-Since the difference in nomenclature reflects a real semantic
-distinction from functions defined outside of a class, the
-implementation needs to maintain the distinction.
-Hence, most of the functionality of the public classes can be
-implemented in a common base class, \class{SuiteInfoBase}, with the
-accessors for function and method information provided elsewhere.
-Note that there is only one class which represents function and method
-information; this parallels the use of the \keyword{def} statement to
-define both types of elements.
-
-Most of the accessor functions are declared in \class{SuiteInfoBase}
-and do not need to be overridden by subclasses. More importantly, the
-extraction of most information from a parse tree is handled through a
-method called by the \class{SuiteInfoBase} constructor. The example
-code for most of the classes is clear when read alongside the formal
-grammar, but the method which recursively creates new information
-objects requires further examination. Here is the relevant part of
-the \class{SuiteInfoBase} definition from \file{example.py}:
-
-\begin{verbatim}
-class SuiteInfoBase:
- _docstring = ''
- _name = ''
-
- def __init__(self, tree = None):
- self._class_info = {}
- self._function_info = {}
- if tree:
- self._extract_info(tree)
-
- def _extract_info(self, tree):
- # extract docstring
- if len(tree) == 2:
- found, vars = match(DOCSTRING_STMT_PATTERN[1], tree[1])
- else:
- found, vars = match(DOCSTRING_STMT_PATTERN, tree[3])
- if found:
- self._docstring = eval(vars['docstring'])
- # discover inner definitions
- for node in tree[1:]:
- found, vars = match(COMPOUND_STMT_PATTERN, node)
- if found:
- cstmt = vars['compound']
- if cstmt[0] == symbol.funcdef:
- name = cstmt[2][1]
- self._function_info[name] = FunctionInfo(cstmt)
- elif cstmt[0] == symbol.classdef:
- name = cstmt[2][1]
- self._class_info[name] = ClassInfo(cstmt)
-\end{verbatim}
-
-After initializing some internal state, the constructor calls the
-\method{_extract_info()} method. This method performs the bulk of the
-information extraction which takes place in the entire example. The
-extraction has two distinct phases: the location of the docstring for
-the parse tree passed in, and the discovery of additional definitions
-within the code block represented by the parse tree.
-
-The initial \keyword{if} test determines whether the nested suite is of
-the ``short form'' or the ``long form.'' The short form is used when
-the code block is on the same line as the definition of the code
-block, as in
-
-\begin{verbatim}
-def square(x): "Square an argument."; return x ** 2
-\end{verbatim}
-
-while the long form uses an indented block and allows nested
-definitions:
-
-\begin{verbatim}
-def make_power(exp):
- "Make a function that raises an argument to the exponent `exp'."
- def raiser(x, y=exp):
- return x ** y
- return raiser
-\end{verbatim}
-
-When the short form is used, the code block may contain a docstring as
-the first, and possibly only, \constant{small_stmt} element. The
-extraction of such a docstring is slightly different and requires only
-a portion of the complete pattern used in the more common case. As
-implemented, the docstring will only be found if there is only
-one \constant{small_stmt} node in the \constant{simple_stmt} node.
-Since most functions and methods which use the short form do not
-provide a docstring, this may be considered sufficient. The
-extraction of the docstring proceeds using the \function{match()} function
-as described above, and the value of the docstring is stored as an
-attribute of the \class{SuiteInfoBase} object.
-
-After docstring extraction, a simple definition discovery
-algorithm operates on the \constant{stmt} nodes of the
-\constant{suite} node. The special case of the short form is not
-tested; since there are no \constant{stmt} nodes in the short form,
-the algorithm will silently skip the single \constant{simple_stmt}
-node and correctly not discover any nested definitions.
-
-Each statement in the code block is categorized as
-a class definition, function or method definition, or
-something else. For the definition statements, the name of the
-element defined is extracted and a representation object
-appropriate to the definition is created with the defining subtree
-passed as an argument to the constructor. The representation objects
-are stored in instance variables and may be retrieved by name using
-the appropriate accessor methods.
-
-The public classes provide any accessors required which are more
-specific than those provided by the \class{SuiteInfoBase} class, but
-the real extraction algorithm remains common to all forms of code
-blocks. A high-level function can be used to extract the complete set
-of information from a source file. (See file \file{example.py}.)
-
-\begin{verbatim}
-def get_docs(fileName):
- import os
- import parser
-
- source = open(fileName).read()
- basename = os.path.basename(os.path.splitext(fileName)[0])
- ast = parser.suite(source)
- return ModuleInfo(ast.totuple(), basename)
-\end{verbatim}
-
-This provides an easy-to-use interface to the documentation of a
-module. If information is required which is not extracted by the code
-of this example, the code may be extended at clearly defined points to
-provide additional capabilities.
diff --git a/Doc/lib/libpdb.tex b/Doc/lib/libpdb.tex
deleted file mode 100644
index 45e778c..0000000
--- a/Doc/lib/libpdb.tex
+++ /dev/null
@@ -1,464 +0,0 @@
-\chapter{The Python Debugger \label{debugger}}
-
-\declaremodule{standard}{pdb}
-\modulesynopsis{The Python debugger for interactive interpreters.}
-
-
-The module \module{pdb} defines an interactive source code
-debugger\index{debugging} for Python programs. It supports setting
-(conditional) breakpoints and single stepping at the source line
-level, inspection of stack frames, source code listing, and evaluation
-of arbitrary Python code in the context of any stack frame. It also
-supports post-mortem debugging and can be called under program
-control.
-
-The debugger is extensible --- it is actually defined as the class
-\class{Pdb}\withsubitem{(class in pdb)}{\ttindex{Pdb}}.
-This is currently undocumented but easily understood by reading the
-source. The extension interface uses the modules
-\module{bdb}\refstmodindex{bdb} (undocumented) and
-\refmodule{cmd}\refstmodindex{cmd}.
-
-The debugger's prompt is \samp{(Pdb) }.
-Typical usage to run a program under control of the debugger is:
-
-\begin{verbatim}
->>> import pdb
->>> import mymodule
->>> pdb.run('mymodule.test()')
-> <string>(0)?()
-(Pdb) continue
-> <string>(1)?()
-(Pdb) continue
-NameError: 'spam'
-> <string>(1)?()
-(Pdb)
-\end{verbatim}
-
-\file{pdb.py} can also be invoked as
-a script to debug other scripts. For example:
-
-\begin{verbatim}
-python -m pdb myscript.py
-\end{verbatim}
-
-When invoked as a script, pdb will automatically enter post-mortem debugging
-if the program being debugged exits abnormally. After post-mortem debugging
-(or after normal exit of the program), pdb will restart the program.
-Automatic restarting preserves pdb's state (such as breakpoints) and in most
-cases is more useful than quitting the debugger upon program's exit.
-\versionadded[Restarting post-mortem behavior added]{2.4}
-
-Typical usage to inspect a crashed program is:
-
-\begin{verbatim}
->>> import pdb
->>> import mymodule
->>> mymodule.test()
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
- File "./mymodule.py", line 4, in test
- test2()
- File "./mymodule.py", line 3, in test2
- print spam
-NameError: spam
->>> pdb.pm()
-> ./mymodule.py(3)test2()
--> print spam
-(Pdb)
-\end{verbatim}
-
-The module defines the following functions; each enters the debugger
-in a slightly different way:
-
-\begin{funcdesc}{run}{statement\optional{, globals\optional{, locals}}}
-Execute the \var{statement} (given as a string) under debugger
-control. The debugger prompt appears before any code is executed; you
-can set breakpoints and type \samp{continue}, or you can step through
-the statement using \samp{step} or \samp{next} (all these commands are
-explained below). The optional \var{globals} and \var{locals}
-arguments specify the environment in which the code is executed; by
-default the dictionary of the module \refmodule[main]{__main__} is
-used. (See the explanation of the built-in \function{exec()} or
-\function{eval()} functions.)
-\end{funcdesc}
-
-\begin{funcdesc}{runeval}{expression\optional{, globals\optional{, locals}}}
-Evaluate the \var{expression} (given as a string) under debugger
-control. When \function{runeval()} returns, it returns the value of the
-expression. Otherwise this function is similar to
-\function{run()}.
-\end{funcdesc}
-
-\begin{funcdesc}{runcall}{function\optional{, argument, ...}}
-Call the \var{function} (a function or method object, not a string)
-with the given arguments. When \function{runcall()} returns, it returns
-whatever the function call returned. The debugger prompt appears as
-soon as the function is entered.
-\end{funcdesc}
-
-\begin{funcdesc}{set_trace}{}
-Enter the debugger at the calling stack frame. This is useful to
-hard-code a breakpoint at a given point in a program, even if the code
-is not otherwise being debugged (e.g. when an assertion fails).
-\end{funcdesc}
-
-\begin{funcdesc}{post_mortem}{traceback}
-Enter post-mortem debugging of the given \var{traceback} object.
-\end{funcdesc}
-
-\begin{funcdesc}{pm}{}
-Enter post-mortem debugging of the traceback found in
-\code{sys.last_traceback}.
-\end{funcdesc}
-
-
-\section{Debugger Commands \label{debugger-commands}}
-
-The debugger recognizes the following commands. Most commands can be
-abbreviated to one or two letters; e.g. \samp{h(elp)} means that
-either \samp{h} or \samp{help} can be used to enter the help
-command (but not \samp{he} or \samp{hel}, nor \samp{H} or
-\samp{Help} or \samp{HELP}). Arguments to commands must be
-separated by whitespace (spaces or tabs). Optional arguments are
-enclosed in square brackets (\samp{[]}) in the command syntax; the
-square brackets must not be typed. Alternatives in the command syntax
-are separated by a vertical bar (\samp{|}).
-
-Entering a blank line repeats the last command entered. Exception: if
-the last command was a \samp{list} command, the next 11 lines are
-listed.
-
-Commands that the debugger doesn't recognize are assumed to be Python
-statements and are executed in the context of the program being
-debugged. Python statements can also be prefixed with an exclamation
-point (\samp{!}). This is a powerful way to inspect the program
-being debugged; it is even possible to change a variable or call a
-function. When an
-exception occurs in such a statement, the exception name is printed
-but the debugger's state is not changed.
-
-Multiple commands may be entered on a single line, separated by
-\samp{;;}. (A single \samp{;} is not used as it is
-the separator for multiple commands in a line that is passed to
-the Python parser.)
-No intelligence is applied to separating the commands;
-the input is split at the first \samp{;;} pair, even if it is in
-the middle of a quoted string.
-
-The debugger supports aliases. Aliases can have parameters which
-allows one a certain level of adaptability to the context under
-examination.
-
-If a file \file{.pdbrc}
-\indexii{.pdbrc}{file}\indexiii{debugger}{configuration}{file}
-exists in the user's home directory or in the current directory, it is
-read in and executed as if it had been typed at the debugger prompt.
-This is particularly useful for aliases. If both files exist, the one
-in the home directory is read first and aliases defined there can be
-overridden by the local file.
-
-\begin{description}
-
-\item[h(elp) \optional{\var{command}}]
-
-Without argument, print the list of available commands. With a
-\var{command} as argument, print help about that command. \samp{help
-pdb} displays the full documentation file; if the environment variable
-\envvar{PAGER} is defined, the file is piped through that command
-instead. Since the \var{command} argument must be an identifier,
-\samp{help exec} must be entered to get help on the \samp{!} command.
-
-\item[w(here)]
-
-Print a stack trace, with the most recent frame at the bottom. An
-arrow indicates the current frame, which determines the context of
-most commands.
-
-\item[d(own)]
-
-Move the current frame one level down in the stack trace
-(to a newer frame).
-
-\item[u(p)]
-
-Move the current frame one level up in the stack trace
-(to an older frame).
-
-\item[b(reak) \optional{\optional{\var{filename}:}\var{lineno}\code{\Large{|}}\var{function}\optional{, \var{condition}}}]
-
-With a \var{lineno} argument, set a break there in the current
-file. With a \var{function} argument, set a break at the first
-executable statement within that function.
-The line number may be prefixed with a filename and a colon,
-to specify a breakpoint in another file (probably one that
-hasn't been loaded yet). The file is searched on \code{sys.path}.
-Note that each breakpoint is assigned a number to which all the other
-breakpoint commands refer.
-
-If a second argument is present, it is an expression which must
-evaluate to true before the breakpoint is honored.
-
-Without argument, list all breaks, including for each breakpoint,
-the number of times that breakpoint has been hit, the current
-ignore count, and the associated condition if any.
-
-\item[tbreak \optional{\optional{\var{filename}:}\var{lineno}\code{\Large{|}}\var{function}\optional{, \var{condition}}}]
-
-Temporary breakpoint, which is removed automatically when it is
-first hit. The arguments are the same as break.
-
-\item[cl(ear) \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}]
-
-With a space separated list of breakpoint numbers, clear those
-breakpoints. Without argument, clear all breaks (but first
-ask confirmation).
-
-\item[disable \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}]
-
-Disables the breakpoints given as a space separated list of
-breakpoint numbers. Disabling a breakpoint means it cannot cause
-the program to stop execution, but unlike clearing a breakpoint, it
-remains in the list of breakpoints and can be (re-)enabled.
-
-\item[enable \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}]
-
-Enables the breakpoints specified.
-
-\item[ignore \var{bpnumber} \optional{\var{count}}]
-
-Sets the ignore count for the given breakpoint number. If
-count is omitted, the ignore count is set to 0. A breakpoint
-becomes active when the ignore count is zero. When non-zero,
-the count is decremented each time the breakpoint is reached
-and the breakpoint is not disabled and any associated condition
-evaluates to true.
-
-\item[condition \var{bpnumber} \optional{\var{condition}}]
-
-Condition is an expression which must evaluate to true before
-the breakpoint is honored. If condition is absent, any existing
-condition is removed; i.e., the breakpoint is made unconditional.
-
-\item[commands \optional{\var{bpnumber}}]
-
-Specify a list of commands for breakpoint number \var{bpnumber}. The
-commands themselves appear on the following lines. Type a line
-containing just 'end' to terminate the commands. An example:
-
-\begin{verbatim}
-(Pdb) commands 1
-(com) print some_variable
-(com) end
-(Pdb)
-\end{verbatim}
-
-To remove all commands from a breakpoint, type commands and
-follow it immediately with end; that is, give no commands.
-
-With no \var{bpnumber} argument, commands refers to the last
-breakpoint set.
-
-You can use breakpoint commands to start your program up again.
-Simply use the continue command, or step, or any other
-command that resumes execution.
-
-Specifying any command resuming execution (currently continue,
-step, next, return, jump, quit and their abbreviations) terminates
-the command list (as if that command was immediately followed by end).
-This is because any time you resume execution
-(even with a simple next or step), you may encounter·
-another breakpoint--which could have its own command list, leading to
-ambiguities about which list to execute.
-
- If you use the 'silent' command in the command list, the
-usual message about stopping at a breakpoint is not printed. This may
-be desirable for breakpoints that are to print a specific message and
-then continue. If none of the other commands print anything, you
-see no sign that the breakpoint was reached.
-
-\versionadded{2.5}
-
-\item[s(tep)]
-
-Execute the current line, stop at the first possible occasion
-(either in a function that is called or on the next line in the
-current function).
-
-\item[n(ext)]
-
-Continue execution until the next line in the current function
-is reached or it returns. (The difference between \samp{next} and
-\samp{step} is that \samp{step} stops inside a called function, while
-\samp{next} executes called functions at (nearly) full speed, only
-stopping at the next line in the current function.)
-
-\item[r(eturn)]
-
-Continue execution until the current function returns.
-
-\item[c(ont(inue))]
-
-Continue execution, only stop when a breakpoint is encountered.
-
-\item[j(ump) \var{lineno}]
-
-Set the next line that will be executed. Only available in the
-bottom-most frame. This lets you jump back and execute code
-again, or jump forward to skip code that you don't want to run.
-
-It should be noted that not all jumps are allowed --- for instance it
-is not possible to jump into the middle of a \keyword{for} loop or out
-of a \keyword{finally} clause.
-
-\item[l(ist) \optional{\var{first}\optional{, \var{last}}}]
-
-List source code for the current file. Without arguments, list 11
-lines around the current line or continue the previous listing. With
-one argument, list 11 lines around at that line. With two arguments,
-list the given range; if the second argument is less than the first,
-it is interpreted as a count.
-
-\item[a(rgs)]
-
-Print the argument list of the current function.
-
-\item[p \var{expression}]
-
-Evaluate the \var{expression} in the current context and print its
-value. \note{\samp{print} can also be used, but is not a debugger
-command --- this executes the Python \keyword{print} statement.}
-
-\item[pp \var{expression}]
-
-Like the \samp{p} command, except the value of the expression is
-pretty-printed using the \module{pprint} module.
-
-\item[alias \optional{\var{name} \optional{command}}]
-
-Creates an alias called \var{name} that executes \var{command}. The
-command must \emph{not} be enclosed in quotes. Replaceable parameters
-can be indicated by \samp{\%1}, \samp{\%2}, and so on, while \samp{\%*} is
-replaced by all the parameters. If no command is given, the current
-alias for \var{name} is shown. If no arguments are given, all
-aliases are listed.
-
-Aliases may be nested and can contain anything that can be
-legally typed at the pdb prompt. Note that internal pdb commands
-\emph{can} be overridden by aliases. Such a command is
-then hidden until the alias is removed. Aliasing is recursively
-applied to the first word of the command line; all other words
-in the line are left alone.
-
-As an example, here are two useful aliases (especially when placed
-in the \file{.pdbrc} file):
-
-\begin{verbatim}
-#Print instance variables (usage "pi classInst")
-alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k]
-#Print instance variables in self
-alias ps pi self
-\end{verbatim}
-
-\item[unalias \var{name}]
-
-Deletes the specified alias.
-
-\item[\optional{!}\var{statement}]
-
-Execute the (one-line) \var{statement} in the context of
-the current stack frame.
-The exclamation point can be omitted unless the first word
-of the statement resembles a debugger command.
-To set a global variable, you can prefix the assignment
-command with a \samp{global} command on the same line, e.g.:
-
-\begin{verbatim}
-(Pdb) global list_options; list_options = ['-l']
-(Pdb)
-\end{verbatim}
-
-\item[run \optional{\var{args} ...}]
-Restart the debugged python program. If an argument is supplied, it is
-splitted with "shlex" and the result is used as the new sys.argv.
-History, breakpoints, actions and debugger options are preserved.
-"restart" is an alias for "run".
-
-\versionadded{2.6}
-
-\item[q(uit)]
-
-Quit from the debugger.
-The program being executed is aborted.
-
-\end{description}
-
-\section{How It Works \label{debugger-hooks}}
-
-Some changes were made to the interpreter:
-
-\begin{itemize}
-\item \code{sys.settrace(\var{func})} sets the global trace function
-\item there can also a local trace function (see later)
-\end{itemize}
-
-Trace functions have three arguments: \var{frame}, \var{event}, and
-\var{arg}. \var{frame} is the current stack frame. \var{event} is a
-string: \code{'call'}, \code{'line'}, \code{'return'}, \code{'exception'},
- \code{'c_call'}, \code{'c_return'}, or \code{'c_exception'}. \var{arg}
- depends on the event type.
-
-The global trace function is invoked (with \var{event} set to
-\code{'call'}) whenever a new local scope is entered; it should return
-a reference to the local trace function to be used that scope, or
-\code{None} if the scope shouldn't be traced.
-
-The local trace function should return a reference to itself (or to
-another function for further tracing in that scope), or \code{None} to
-turn off tracing in that scope.
-
-Instance methods are accepted (and very useful!) as trace functions.
-
-The events have the following meaning:
-
-\begin{description}
-
-\item[\code{'call'}]
-A function is called (or some other code block entered). The global
-trace function is called; \var{arg} is \code{None};
-the return value specifies the local trace function.
-
-\item[\code{'line'}]
-The interpreter is about to execute a new line of code (sometimes
-multiple line events on one line exist). The local trace function is
-called; \var{arg} is \code{None}; the return value specifies the new
-local trace function.
-
-\item[\code{'return'}]
-A function (or other code block) is about to return. The local trace
-function is called; \var{arg} is the value that will be returned. The
-trace function's return value is ignored.
-
-\item[\code{'exception'}]
-An exception has occurred. The local trace function is called;
-\var{arg} is a triple \code{(\var{exception}, \var{value},
-\var{traceback})}; the return value specifies the new local trace
-function.
-
-\item[\code{'c_call'}]
-A C function is about to be called. This may be an extension function
-or a builtin. \var{arg} is the C function object.
-
-\item[\code{'c_return'}]
-A C function has returned. \var{arg} is \code{None}.
-
-\item[\code{'c_exception'}]
-A C function has thrown an exception. \var{arg} is \code{None}.
-
-\end{description}
-
-Note that as an exception is propagated down the chain of callers, an
-\code{'exception'} event is generated at each level.
-
-For more information on code and frame objects, refer to the
-\citetitle[../ref/ref.html]{Python Reference Manual}.
diff --git a/Doc/lib/libpickle.tex b/Doc/lib/libpickle.tex
deleted file mode 100644
index 0c4cd98..0000000
--- a/Doc/lib/libpickle.tex
+++ /dev/null
@@ -1,888 +0,0 @@
-\section{\module{pickle} --- Python object serialization}
-
-\declaremodule{standard}{pickle}
-\modulesynopsis{Convert Python objects to streams of bytes and back.}
-% Substantial improvements by Jim Kerr <jbkerr@sr.hp.com>.
-% Rewritten by Barry Warsaw <barry@zope.com>
-
-\index{persistence}
-\indexii{persistent}{objects}
-\indexii{serializing}{objects}
-\indexii{marshalling}{objects}
-\indexii{flattening}{objects}
-\indexii{pickling}{objects}
-
-The \module{pickle} module implements a fundamental, but powerful
-algorithm for serializing and de-serializing a Python object
-structure. ``Pickling'' is the process whereby a Python object
-hierarchy is converted into a byte stream, and ``unpickling'' is the
-inverse operation, whereby a byte stream is converted back into an
-object hierarchy. Pickling (and unpickling) is alternatively known as
-``serialization'', ``marshalling,''\footnote{Don't confuse this with
-the \refmodule{marshal} module} or ``flattening'',
-however, to avoid confusion, the terms used here are ``pickling'' and
-``unpickling''.
-
-This documentation describes both the \module{pickle} module and the
-\refmodule{cPickle} module.
-
-\subsection{Relationship to other Python modules}
-
-The \module{pickle} module has an optimized cousin called the
-\module{cPickle} module. As its name implies, \module{cPickle} is
-written in C, so it can be up to 1000 times faster than
-\module{pickle}. However it does not support subclassing of the
-\function{Pickler()} and \function{Unpickler()} classes, because in
-\module{cPickle} these are functions, not classes. Most applications
-have no need for this functionality, and can benefit from the improved
-performance of \module{cPickle}. Other than that, the interfaces of
-the two modules are nearly identical; the common interface is
-described in this manual and differences are pointed out where
-necessary. In the following discussions, we use the term ``pickle''
-to collectively describe the \module{pickle} and
-\module{cPickle} modules.
-
-The data streams the two modules produce are guaranteed to be
-interchangeable.
-
-Python has a more primitive serialization module called
-\refmodule{marshal}, but in general
-\module{pickle} should always be the preferred way to serialize Python
-objects. \module{marshal} exists primarily to support Python's
-\file{.pyc} files.
-
-The \module{pickle} module differs from \refmodule{marshal} several
-significant ways:
-
-\begin{itemize}
-
-\item The \module{pickle} module keeps track of the objects it has
- already serialized, so that later references to the same object
- won't be serialized again. \module{marshal} doesn't do this.
-
- This has implications both for recursive objects and object
- sharing. Recursive objects are objects that contain references
- to themselves. These are not handled by marshal, and in fact,
- attempting to marshal recursive objects will crash your Python
- interpreter. Object sharing happens when there are multiple
- references to the same object in different places in the object
- hierarchy being serialized. \module{pickle} stores such objects
- only once, and ensures that all other references point to the
- master copy. Shared objects remain shared, which can be very
- important for mutable objects.
-
-\item \module{marshal} cannot be used to serialize user-defined
- classes and their instances. \module{pickle} can save and
- restore class instances transparently, however the class
- definition must be importable and live in the same module as
- when the object was stored.
-
-\item The \module{marshal} serialization format is not guaranteed to
- be portable across Python versions. Because its primary job in
- life is to support \file{.pyc} files, the Python implementers
- reserve the right to change the serialization format in
- non-backwards compatible ways should the need arise. The
- \module{pickle} serialization format is guaranteed to be
- backwards compatible across Python releases.
-
-\end{itemize}
-
-\begin{notice}[warning]
-The \module{pickle} module is not intended to be secure against
-erroneous or maliciously constructed data. Never unpickle data
-received from an untrusted or unauthenticated source.
-\end{notice}
-
-Note that serialization is a more primitive notion than persistence;
-although
-\module{pickle} reads and writes file objects, it does not handle the
-issue of naming persistent objects, nor the (even more complicated)
-issue of concurrent access to persistent objects. The \module{pickle}
-module can transform a complex object into a byte stream and it can
-transform the byte stream into an object with the same internal
-structure. Perhaps the most obvious thing to do with these byte
-streams is to write them onto a file, but it is also conceivable to
-send them across a network or store them in a database. The module
-\refmodule{shelve} provides a simple interface
-to pickle and unpickle objects on DBM-style database files.
-
-\subsection{Data stream format}
-
-The data format used by \module{pickle} is Python-specific. This has
-the advantage that there are no restrictions imposed by external
-standards such as XDR\index{XDR}\index{External Data Representation}
-(which can't represent pointer sharing); however it means that
-non-Python programs may not be able to reconstruct pickled Python
-objects.
-
-By default, the \module{pickle} data format uses a printable \ASCII{}
-representation. This is slightly more voluminous than a binary
-representation. The big advantage of using printable \ASCII{} (and of
-some other characteristics of \module{pickle}'s representation) is that
-for debugging or recovery purposes it is possible for a human to read
-the pickled file with a standard text editor.
-
-There are currently 3 different protocols which can be used for pickling.
-
-\begin{itemize}
-
-\item Protocol version 0 is the original ASCII protocol and is backwards
-compatible with earlier versions of Python.
-
-\item Protocol version 1 is the old binary format which is also compatible
-with earlier versions of Python.
-
-\item Protocol version 2 was introduced in Python 2.3. It provides
-much more efficient pickling of new-style classes.
-
-\end{itemize}
-
-Refer to PEP 307 for more information.
-
-If a \var{protocol} is not specified, protocol 0 is used.
-If \var{protocol} is specified as a negative value
-or \constant{HIGHEST_PROTOCOL},
-the highest protocol version available will be used.
-
-\versionchanged[Introduced the \var{protocol} parameter]{2.3}
-
-A binary format, which is slightly more efficient, can be chosen by
-specifying a \var{protocol} version >= 1.
-
-\subsection{Usage}
-
-To serialize an object hierarchy, you first create a pickler, then you
-call the pickler's \method{dump()} method. To de-serialize a data
-stream, you first create an unpickler, then you call the unpickler's
-\method{load()} method. The \module{pickle} module provides the
-following constant:
-
-\begin{datadesc}{HIGHEST_PROTOCOL}
-The highest protocol version available. This value can be passed
-as a \var{protocol} value.
-\versionadded{2.3}
-\end{datadesc}
-
-\note{Be sure to always open pickle files created with protocols >= 1 in
- binary mode. For the old ASCII-based pickle protocol 0 you can use
- either text mode or binary mode as long as you stay consistent.
-
- A pickle file written with protocol 0 in binary mode will contain
- lone linefeeds as line terminators and therefore will look ``funny''
- when viewed in Notepad or other editors which do not support this
- format.}
-
-The \module{pickle} module provides the
-following functions to make the pickling process more convenient:
-
-\begin{funcdesc}{dump}{obj, file\optional{, protocol}}
-Write a pickled representation of \var{obj} to the open file object
-\var{file}. This is equivalent to
-\code{Pickler(\var{file}, \var{protocol}).dump(\var{obj})}.
-
-If the \var{protocol} parameter is omitted, protocol 0 is used.
-If \var{protocol} is specified as a negative value
-or \constant{HIGHEST_PROTOCOL},
-the highest protocol version will be used.
-
-\versionchanged[Introduced the \var{protocol} parameter]{2.3}
-
-\var{file} must have a \method{write()} method that accepts a single
-string argument. It can thus be a file object opened for writing, a
-\refmodule{StringIO} object, or any other custom
-object that meets this interface.
-\end{funcdesc}
-
-\begin{funcdesc}{load}{file}
-Read a string from the open file object \var{file} and interpret it as
-a pickle data stream, reconstructing and returning the original object
-hierarchy. This is equivalent to \code{Unpickler(\var{file}).load()}.
-
-\var{file} must have two methods, a \method{read()} method that takes
-an integer argument, and a \method{readline()} method that requires no
-arguments. Both methods should return a string. Thus \var{file} can
-be a file object opened for reading, a
-\module{StringIO} object, or any other custom
-object that meets this interface.
-
-This function automatically determines whether the data stream was
-written in binary mode or not.
-\end{funcdesc}
-
-\begin{funcdesc}{dumps}{obj\optional{, protocol}}
-Return the pickled representation of the object as a string, instead
-of writing it to a file.
-
-If the \var{protocol} parameter is omitted, protocol 0 is used.
-If \var{protocol} is specified as a negative value
-or \constant{HIGHEST_PROTOCOL},
-the highest protocol version will be used.
-
-\versionchanged[The \var{protocol} parameter was added]{2.3}
-
-\end{funcdesc}
-
-\begin{funcdesc}{loads}{string}
-Read a pickled object hierarchy from a string. Characters in the
-string past the pickled object's representation are ignored.
-\end{funcdesc}
-
-The \module{pickle} module also defines three exceptions:
-
-\begin{excdesc}{PickleError}
-A common base class for the other exceptions defined below. This
-inherits from \exception{Exception}.
-\end{excdesc}
-
-\begin{excdesc}{PicklingError}
-This exception is raised when an unpicklable object is passed to
-the \method{dump()} method.
-\end{excdesc}
-
-\begin{excdesc}{UnpicklingError}
-This exception is raised when there is a problem unpickling an object.
-Note that other exceptions may also be raised during unpickling,
-including (but not necessarily limited to) \exception{AttributeError},
-\exception{EOFError}, \exception{ImportError}, and \exception{IndexError}.
-\end{excdesc}
-
-The \module{pickle} module also exports two callables\footnote{In the
-\module{pickle} module these callables are classes, which you could
-subclass to customize the behavior. However, in the \refmodule{cPickle}
-module these callables are factory functions and so cannot be
-subclassed. One common reason to subclass is to control what
-objects can actually be unpickled. See section~\ref{pickle-sub} for
-more details.}, \class{Pickler} and \class{Unpickler}:
-
-\begin{classdesc}{Pickler}{file\optional{, protocol}}
-This takes a file-like object to which it will write a pickle data
-stream.
-
-If the \var{protocol} parameter is omitted, protocol 0 is used.
-If \var{protocol} is specified as a negative value,
-the highest protocol version will be used.
-
-\versionchanged[Introduced the \var{protocol} parameter]{2.3}
-
-\var{file} must have a \method{write()} method that accepts a single
-string argument. It can thus be an open file object, a
-\module{StringIO} object, or any other custom
-object that meets this interface.
-\end{classdesc}
-
-\class{Pickler} objects define one (or two) public methods:
-
-\begin{methoddesc}[Pickler]{dump}{obj}
-Write a pickled representation of \var{obj} to the open file object
-given in the constructor. Either the binary or \ASCII{} format will
-be used, depending on the value of the \var{protocol} argument passed to the
-constructor.
-\end{methoddesc}
-
-\begin{methoddesc}[Pickler]{clear_memo}{}
-Clears the pickler's ``memo''. The memo is the data structure that
-remembers which objects the pickler has already seen, so that shared
-or recursive objects pickled by reference and not by value. This
-method is useful when re-using picklers.
-
-\begin{notice}
-Prior to Python 2.3, \method{clear_memo()} was only available on the
-picklers created by \refmodule{cPickle}. In the \module{pickle} module,
-picklers have an instance variable called \member{memo} which is a
-Python dictionary. So to clear the memo for a \module{pickle} module
-pickler, you could do the following:
-
-\begin{verbatim}
-mypickler.memo.clear()
-\end{verbatim}
-
-Code that does not need to support older versions of Python should
-simply use \method{clear_memo()}.
-\end{notice}
-\end{methoddesc}
-
-It is possible to make multiple calls to the \method{dump()} method of
-the same \class{Pickler} instance. These must then be matched to the
-same number of calls to the \method{load()} method of the
-corresponding \class{Unpickler} instance. If the same object is
-pickled by multiple \method{dump()} calls, the \method{load()} will
-all yield references to the same object.\footnote{\emph{Warning}: this
-is intended for pickling multiple objects without intervening
-modifications to the objects or their parts. If you modify an object
-and then pickle it again using the same \class{Pickler} instance, the
-object is not pickled again --- a reference to it is pickled and the
-\class{Unpickler} will return the old value, not the modified one.
-There are two problems here: (1) detecting changes, and (2)
-marshalling a minimal set of changes. Garbage Collection may also
-become a problem here.}
-
-\class{Unpickler} objects are defined as:
-
-\begin{classdesc}{Unpickler}{file}
-This takes a file-like object from which it will read a pickle data
-stream. This class automatically determines whether the data stream
-was written in binary mode or not, so it does not need a flag as in
-the \class{Pickler} factory.
-
-\var{file} must have two methods, a \method{read()} method that takes
-an integer argument, and a \method{readline()} method that requires no
-arguments. Both methods should return a string. Thus \var{file} can
-be a file object opened for reading, a
-\module{StringIO} object, or any other custom
-object that meets this interface.
-\end{classdesc}
-
-\class{Unpickler} objects have one (or two) public methods:
-
-\begin{methoddesc}[Unpickler]{load}{}
-Read a pickled object representation from the open file object given
-in the constructor, and return the reconstituted object hierarchy
-specified therein.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpickler]{noload}{}
-This is just like \method{load()} except that it doesn't actually
-create any objects. This is useful primarily for finding what's
-called ``persistent ids'' that may be referenced in a pickle data
-stream. See section~\ref{pickle-protocol} below for more details.
-
-\strong{Note:} the \method{noload()} method is currently only
-available on \class{Unpickler} objects created with the
-\module{cPickle} module. \module{pickle} module \class{Unpickler}s do
-not have the \method{noload()} method.
-\end{methoddesc}
-
-\subsection{What can be pickled and unpickled?}
-
-The following types can be pickled:
-
-\begin{itemize}
-
-\item \code{None}, \code{True}, and \code{False}
-
-\item integers, long integers, floating point numbers, complex numbers
-
-\item normal and Unicode strings
-
-\item tuples, lists, sets, and dictionaries containing only picklable objects
-
-\item functions defined at the top level of a module
-
-\item built-in functions defined at the top level of a module
-
-\item classes that are defined at the top level of a module
-
-\item instances of such classes whose \member{__dict__} or
-\method{__setstate__()} is picklable (see
-section~\ref{pickle-protocol} for details)
-
-\end{itemize}
-
-Attempts to pickle unpicklable objects will raise the
-\exception{PicklingError} exception; when this happens, an unspecified
-number of bytes may have already been written to the underlying file.
-Trying to pickle a highly recursive data structure may exceed the
-maximum recursion depth, a \exception{RuntimeError} will be raised
-in this case. You can carefully raise this limit with
-\function{sys.setrecursionlimit()}.
-
-Note that functions (built-in and user-defined) are pickled by ``fully
-qualified'' name reference, not by value. This means that only the
-function name is pickled, along with the name of module the function
-is defined in. Neither the function's code, nor any of its function
-attributes are pickled. Thus the defining module must be importable
-in the unpickling environment, and the module must contain the named
-object, otherwise an exception will be raised.\footnote{The exception
-raised will likely be an \exception{ImportError} or an
-\exception{AttributeError} but it could be something else.}
-
-Similarly, classes are pickled by named reference, so the same
-restrictions in the unpickling environment apply. Note that none of
-the class's code or data is pickled, so in the following example the
-class attribute \code{attr} is not restored in the unpickling
-environment:
-
-\begin{verbatim}
-class Foo:
- attr = 'a class attr'
-
-picklestring = pickle.dumps(Foo)
-\end{verbatim}
-
-These restrictions are why picklable functions and classes must be
-defined in the top level of a module.
-
-Similarly, when class instances are pickled, their class's code and
-data are not pickled along with them. Only the instance data are
-pickled. This is done on purpose, so you can fix bugs in a class or
-add methods to the class and still load objects that were created with
-an earlier version of the class. If you plan to have long-lived
-objects that will see many versions of a class, it may be worthwhile
-to put a version number in the objects so that suitable conversions
-can be made by the class's \method{__setstate__()} method.
-
-\subsection{The pickle protocol
-\label{pickle-protocol}}\setindexsubitem{(pickle protocol)}
-
-This section describes the ``pickling protocol'' that defines the
-interface between the pickler/unpickler and the objects that are being
-serialized. This protocol provides a standard way for you to define,
-customize, and control how your objects are serialized and
-de-serialized. The description in this section doesn't cover specific
-customizations that you can employ to make the unpickling environment
-slightly safer from untrusted pickle data streams; see section~\ref{pickle-sub}
-for more details.
-
-\subsubsection{Pickling and unpickling normal class
- instances\label{pickle-inst}}
-
-When a pickled class instance is unpickled, its \method{__init__()}
-method is normally \emph{not} invoked. If it is desirable that the
-\method{__init__()} method be called on unpickling, an old-style class
-can define a method \method{__getinitargs__()}, which should return a
-\emph{tuple} containing the arguments to be passed to the class
-constructor (\method{__init__()} for example). The
-\method{__getinitargs__()} method is called at
-pickle time; the tuple it returns is incorporated in the pickle for
-the instance.
-\withsubitem{(copy protocol)}{\ttindex{__getinitargs__()}}
-\withsubitem{(instance constructor)}{\ttindex{__init__()}}
-
-\withsubitem{(copy protocol)}{\ttindex{__getnewargs__()}}
-
-New-style types can provide a \method{__getnewargs__()} method that is
-used for protocol 2. Implementing this method is needed if the type
-establishes some internal invariants when the instance is created, or
-if the memory allocation is affected by the values passed to the
-\method{__new__()} method for the type (as it is for tuples and
-strings). Instances of a new-style type \class{C} are created using
-
-\begin{alltt}
-obj = C.__new__(C, *\var{args})
-\end{alltt}
-
-where \var{args} is the result of calling \method{__getnewargs__()} on
-the original object; if there is no \method{__getnewargs__()}, an
-empty tuple is assumed.
-
-\withsubitem{(copy protocol)}{
- \ttindex{__getstate__()}\ttindex{__setstate__()}}
-\withsubitem{(instance attribute)}{
- \ttindex{__dict__}}
-
-Classes can further influence how their instances are pickled; if the
-class defines the method \method{__getstate__()}, it is called and the
-return state is pickled as the contents for the instance, instead of
-the contents of the instance's dictionary. If there is no
-\method{__getstate__()} method, the instance's \member{__dict__} is
-pickled.
-
-Upon unpickling, if the class also defines the method
-\method{__setstate__()}, it is called with the unpickled
-state.\footnote{These methods can also be used to implement copying
-class instances.} If there is no \method{__setstate__()} method, the
-pickled state must be a dictionary and its items are assigned to the
-new instance's dictionary. If a class defines both
-\method{__getstate__()} and \method{__setstate__()}, the state object
-needn't be a dictionary and these methods can do what they
-want.\footnote{This protocol is also used by the shallow and deep
-copying operations defined in the
-\refmodule{copy} module.}
-
-\begin{notice}[warning]
- For new-style classes, if \method{__getstate__()} returns a false
- value, the \method{__setstate__()} method will not be called.
-\end{notice}
-
-
-\subsubsection{Pickling and unpickling extension types}
-
-When the \class{Pickler} encounters an object of a type it knows
-nothing about --- such as an extension type --- it looks in two places
-for a hint of how to pickle it. One alternative is for the object to
-implement a \method{__reduce__()} method. If provided, at pickling
-time \method{__reduce__()} will be called with no arguments, and it
-must return either a string or a tuple.
-
-If a string is returned, it names a global variable whose contents are
-pickled as normal. The string returned by \method{__reduce__} should
-be the object's local name relative to its module; the pickle module
-searches the module namespace to determine the object's module.
-
-When a tuple is returned, it must be between two and five elements
-long. Optional elements can either be omitted, or \code{None} can be provided
-as their value. The semantics of each element are:
-
-\begin{itemize}
-
-\item A callable object that will be called to create the initial
-version of the object. The next element of the tuple will provide
-arguments for this callable, and later elements provide additional
-state information that will subsequently be used to fully reconstruct
-the pickled data.
-
-In the unpickling environment this object must be either a class, a
-callable registered as a ``safe constructor'' (see below), or it must
-have an attribute \member{__safe_for_unpickling__} with a true value.
-Otherwise, an \exception{UnpicklingError} will be raised in the
-unpickling environment. Note that as usual, the callable itself is
-pickled by name.
-
-\item A tuple of arguments for the callable object.
-\versionchanged[Formerly, this argument could also be \code{None}]{2.5}
-
-\item Optionally, the object's state, which will be passed to
- the object's \method{__setstate__()} method as described in
- section~\ref{pickle-inst}. If the object has no
- \method{__setstate__()} method, then, as above, the value must
- be a dictionary and it will be added to the object's
- \member{__dict__}.
-
-\item Optionally, an iterator (and not a sequence) yielding successive
-list items. These list items will be pickled, and appended to the
-object using either \code{obj.append(\var{item})} or
-\code{obj.extend(\var{list_of_items})}. This is primarily used for
-list subclasses, but may be used by other classes as long as they have
-\method{append()} and \method{extend()} methods with the appropriate
-signature. (Whether \method{append()} or \method{extend()} is used
-depends on which pickle protocol version is used as well as the number
-of items to append, so both must be supported.)
-
-\item Optionally, an iterator (not a sequence)
-yielding successive dictionary items, which should be tuples of the
-form \code{(\var{key}, \var{value})}. These items will be pickled
-and stored to the object using \code{obj[\var{key}] = \var{value}}.
-This is primarily used for dictionary subclasses, but may be used by
-other classes as long as they implement \method{__setitem__}.
-
-\end{itemize}
-
-It is sometimes useful to know the protocol version when implementing
-\method{__reduce__}. This can be done by implementing a method named
-\method{__reduce_ex__} instead of \method{__reduce__}.
-\method{__reduce_ex__}, when it exists, is called in preference over
-\method{__reduce__} (you may still provide \method{__reduce__} for
-backwards compatibility). The \method{__reduce_ex__} method will be
-called with a single integer argument, the protocol version.
-
-The \class{object} class implements both \method{__reduce__} and
-\method{__reduce_ex__}; however, if a subclass overrides
-\method{__reduce__} but not \method{__reduce_ex__}, the
-\method{__reduce_ex__} implementation detects this and calls
-\method{__reduce__}.
-
-An alternative to implementing a \method{__reduce__()} method on the
-object to be pickled, is to register the callable with the
-\refmodule[copyreg]{copy_reg} module. This module provides a way
-for programs to register ``reduction functions'' and constructors for
-user-defined types. Reduction functions have the same semantics and
-interface as the \method{__reduce__()} method described above, except
-that they are called with a single argument, the object to be pickled.
-
-The registered constructor is deemed a ``safe constructor'' for purposes
-of unpickling as described above.
-
-
-\subsubsection{Pickling and unpickling external objects}
-
-For the benefit of object persistence, the \module{pickle} module
-supports the notion of a reference to an object outside the pickled
-data stream. Such objects are referenced by a ``persistent id'',
-which is just an arbitrary string of printable \ASCII{} characters.
-The resolution of such names is not defined by the \module{pickle}
-module; it will delegate this resolution to user defined functions on
-the pickler and unpickler.\footnote{The actual mechanism for
-associating these user defined functions is slightly different for
-\module{pickle} and \module{cPickle}. The description given here
-works the same for both implementations. Users of the \module{pickle}
-module could also use subclassing to effect the same results,
-overriding the \method{persistent_id()} and \method{persistent_load()}
-methods in the derived classes.}
-
-To define external persistent id resolution, you need to set the
-\member{persistent_id} attribute of the pickler object and the
-\member{persistent_load} attribute of the unpickler object.
-
-To pickle objects that have an external persistent id, the pickler
-must have a custom \function{persistent_id()} method that takes an
-object as an argument and returns either \code{None} or the persistent
-id for that object. When \code{None} is returned, the pickler simply
-pickles the object as normal. When a persistent id string is
-returned, the pickler will pickle that string, along with a marker
-so that the unpickler will recognize the string as a persistent id.
-
-To unpickle external objects, the unpickler must have a custom
-\function{persistent_load()} function that takes a persistent id
-string and returns the referenced object.
-
-Here's a silly example that \emph{might} shed more light:
-
-\begin{verbatim}
-import pickle
-from cStringIO import StringIO
-
-src = StringIO()
-p = pickle.Pickler(src)
-
-def persistent_id(obj):
- if hasattr(obj, 'x'):
- return 'the value %d' % obj.x
- else:
- return None
-
-p.persistent_id = persistent_id
-
-class Integer:
- def __init__(self, x):
- self.x = x
- def __str__(self):
- return 'My name is integer %d' % self.x
-
-i = Integer(7)
-print i
-p.dump(i)
-
-datastream = src.getvalue()
-print repr(datastream)
-dst = StringIO(datastream)
-
-up = pickle.Unpickler(dst)
-
-class FancyInteger(Integer):
- def __str__(self):
- return 'I am the integer %d' % self.x
-
-def persistent_load(persid):
- if persid.startswith('the value '):
- value = int(persid.split()[2])
- return FancyInteger(value)
- else:
- raise pickle.UnpicklingError, 'Invalid persistent id'
-
-up.persistent_load = persistent_load
-
-j = up.load()
-print j
-\end{verbatim}
-
-In the \module{cPickle} module, the unpickler's
-\member{persistent_load} attribute can also be set to a Python
-list, in which case, when the unpickler reaches a persistent id, the
-persistent id string will simply be appended to this list. This
-functionality exists so that a pickle data stream can be ``sniffed''
-for object references without actually instantiating all the objects
-in a pickle.\footnote{We'll leave you with the image of Guido and Jim
-sitting around sniffing pickles in their living rooms.} Setting
-\member{persistent_load} to a list is usually used in conjunction with
-the \method{noload()} method on the Unpickler.
-
-% BAW: Both pickle and cPickle support something called
-% inst_persistent_id() which appears to give unknown types a second
-% shot at producing a persistent id. Since Jim Fulton can't remember
-% why it was added or what it's for, I'm leaving it undocumented.
-
-\subsection{Subclassing Unpicklers \label{pickle-sub}}
-
-By default, unpickling will import any class that it finds in the
-pickle data. You can control exactly what gets unpickled and what
-gets called by customizing your unpickler. Unfortunately, exactly how
-you do this is different depending on whether you're using
-\module{pickle} or \module{cPickle}.\footnote{A word of caution: the
-mechanisms described here use internal attributes and methods, which
-are subject to change in future versions of Python. We intend to
-someday provide a common interface for controlling this behavior,
-which will work in either \module{pickle} or \module{cPickle}.}
-
-In the \module{pickle} module, you need to derive a subclass from
-\class{Unpickler}, overriding the \method{load_global()}
-method. \method{load_global()} should read two lines from the pickle
-data stream where the first line will the name of the module
-containing the class and the second line will be the name of the
-instance's class. It then looks up the class, possibly importing the
-module and digging out the attribute, then it appends what it finds to
-the unpickler's stack. Later on, this class will be assigned to the
-\member{__class__} attribute of an empty class, as a way of magically
-creating an instance without calling its class's \method{__init__()}.
-Your job (should you choose to accept it), would be to have
-\method{load_global()} push onto the unpickler's stack, a known safe
-version of any class you deem safe to unpickle. It is up to you to
-produce such a class. Or you could raise an error if you want to
-disallow all unpickling of instances. If this sounds like a hack,
-you're right. Refer to the source code to make this work.
-
-Things are a little cleaner with \module{cPickle}, but not by much.
-To control what gets unpickled, you can set the unpickler's
-\member{find_global} attribute to a function or \code{None}. If it is
-\code{None} then any attempts to unpickle instances will raise an
-\exception{UnpicklingError}. If it is a function,
-then it should accept a module name and a class name, and return the
-corresponding class object. It is responsible for looking up the
-class and performing any necessary imports, and it may raise an
-error to prevent instances of the class from being unpickled.
-
-The moral of the story is that you should be really careful about the
-source of the strings your application unpickles.
-
-\subsection{Example \label{pickle-example}}
-
-For the simplest code, use the \function{dump()} and \function{load()}
-functions. Note that a self-referencing list is pickled and restored
-correctly.
-
-\begin{verbatim}
-import pickle
-
-data1 = {'a': [1, 2.0, 3, 4+6j],
- 'b': ('string', u'Unicode string'),
- 'c': None}
-
-selfref_list = [1, 2, 3]
-selfref_list.append(selfref_list)
-
-output = open('data.pkl', 'wb')
-
-# Pickle dictionary using protocol 0.
-pickle.dump(data1, output)
-
-# Pickle the list using the highest protocol available.
-pickle.dump(selfref_list, output, -1)
-
-output.close()
-\end{verbatim}
-
-The following example reads the resulting pickled data. When reading
-a pickle-containing file, you should open the file in binary mode
-because you can't be sure if the ASCII or binary format was used.
-
-\begin{verbatim}
-import pprint, pickle
-
-pkl_file = open('data.pkl', 'rb')
-
-data1 = pickle.load(pkl_file)
-pprint.pprint(data1)
-
-data2 = pickle.load(pkl_file)
-pprint.pprint(data2)
-
-pkl_file.close()
-\end{verbatim}
-
-Here's a larger example that shows how to modify pickling behavior for a
-class. The \class{TextReader} class opens a text file, and returns
-the line number and line contents each time its \method{readline()}
-method is called. If a \class{TextReader} instance is pickled, all
-attributes \emph{except} the file object member are saved. When the
-instance is unpickled, the file is reopened, and reading resumes from
-the last location. The \method{__setstate__()} and
-\method{__getstate__()} methods are used to implement this behavior.
-
-\begin{verbatim}
-class TextReader:
- """Print and number lines in a text file."""
- def __init__(self, file):
- self.file = file
- self.fh = open(file)
- self.lineno = 0
-
- def readline(self):
- self.lineno = self.lineno + 1
- line = self.fh.readline()
- if not line:
- return None
- if line.endswith("\n"):
- line = line[:-1]
- return "%d: %s" % (self.lineno, line)
-
- def __getstate__(self):
- odict = self.__dict__.copy() # copy the dict since we change it
- del odict['fh'] # remove filehandle entry
- return odict
-
- def __setstate__(self, dict):
- fh = open(dict['file']) # reopen file
- count = dict['lineno'] # read from file...
- while count: # until line count is restored
- fh.readline()
- count = count - 1
- self.__dict__.update(dict) # update attributes
- self.fh = fh # save the file object
-\end{verbatim}
-
-A sample usage might be something like this:
-
-\begin{verbatim}
->>> import TextReader
->>> obj = TextReader.TextReader("TextReader.py")
->>> obj.readline()
-'1: #!/usr/local/bin/python'
->>> # (more invocations of obj.readline() here)
-... obj.readline()
-'7: class TextReader:'
->>> import pickle
->>> pickle.dump(obj,open('save.p', 'wb'))
-\end{verbatim}
-
-If you want to see that \refmodule{pickle} works across Python
-processes, start another Python session, before continuing. What
-follows can happen from either the same process or a new process.
-
-\begin{verbatim}
->>> import pickle
->>> reader = pickle.load(open('save.p', 'rb'))
->>> reader.readline()
-'8: "Print and number lines in a text file."'
-\end{verbatim}
-
-
-\begin{seealso}
- \seemodule[copyreg]{copy_reg}{Pickle interface constructor
- registration for extension types.}
-
- \seemodule{shelve}{Indexed databases of objects; uses \module{pickle}.}
-
- \seemodule{copy}{Shallow and deep object copying.}
-
- \seemodule{marshal}{High-performance serialization of built-in types.}
-\end{seealso}
-
-
-\section{\module{cPickle} --- A faster \module{pickle}}
-
-\declaremodule{builtin}{cPickle}
-\modulesynopsis{Faster version of \refmodule{pickle}, but not subclassable.}
-\moduleauthor{Jim Fulton}{jim@zope.com}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-The \module{cPickle} module supports serialization and
-de-serialization of Python objects, providing an interface and
-functionality nearly identical to the
-\refmodule{pickle}\refstmodindex{pickle} module. There are several
-differences, the most important being performance and subclassability.
-
-First, \module{cPickle} can be up to 1000 times faster than
-\module{pickle} because the former is implemented in C. Second, in
-the \module{cPickle} module the callables \function{Pickler()} and
-\function{Unpickler()} are functions, not classes. This means that
-you cannot use them to derive custom pickling and unpickling
-subclasses. Most applications have no need for this functionality and
-should benefit from the greatly improved performance of the
-\module{cPickle} module.
-
-The pickle data stream produced by \module{pickle} and
-\module{cPickle} are identical, so it is possible to use
-\module{pickle} and \module{cPickle} interchangeably with existing
-pickles.\footnote{Since the pickle data format is actually a tiny
-stack-oriented programming language, and some freedom is taken in the
-encodings of certain objects, it is possible that the two modules
-produce different data streams for the same input objects. However it
-is guaranteed that they will always be able to read each other's
-data streams.}
-
-There are additional minor differences in API between \module{cPickle}
-and \module{pickle}, however for most applications, they are
-interchangeable. More documentation is provided in the
-\module{pickle} module documentation, which
-includes a list of the documented differences.
-
-
diff --git a/Doc/lib/libpickletools.tex b/Doc/lib/libpickletools.tex
deleted file mode 100644
index 8f63626..0000000
--- a/Doc/lib/libpickletools.tex
+++ /dev/null
@@ -1,34 +0,0 @@
-\section{\module{pickletools} --- Tools for pickle developers.}
-
-\declaremodule{standard}{pickletools}
-\modulesynopsis{Contains extensive comments about the pickle protocols and pickle-machine opcodes, as well as some useful functions.}
-
-\versionadded{2.3}
-
-This module contains various constants relating to the intimate
-details of the \refmodule{pickle} module, some lengthy comments about
-the implementation, and a few useful functions for analyzing pickled
-data. The contents of this module are useful for Python core
-developers who are working on the \module{pickle} and \module{cPickle}
-implementations; ordinary users of the \module{pickle} module probably
-won't find the \module{pickletools} module relevant.
-
-\begin{funcdesc}{dis}{pickle\optional{, out=None, memo=None, indentlevel=4}}
-Outputs a symbolic disassembly of the pickle to the file-like object
-\var{out}, defaulting to \code{sys.stdout}. \var{pickle} can be a
-string or a file-like object. \var{memo} can be a Python dictionary
-that will be used as the pickle's memo; it can be used to perform
-disassemblies across multiple pickles created by the same pickler.
-Successive levels, indicated by \code{MARK} opcodes in the stream, are
-indented by \var{indentlevel} spaces.
-\end{funcdesc}
-
-\begin{funcdesc}{genops}{pickle}
-Provides an iterator over all of the opcodes in a pickle, returning a
-sequence of \code{(\var{opcode}, \var{arg}, \var{pos})} triples.
-\var{opcode} is an instance of an \class{OpcodeInfo} class; \var{arg}
-is the decoded value, as a Python object, of the opcode's argument;
-\var{pos} is the position at which this opcode is located.
-\var{pickle} can be a string or a file-like object.
-\end{funcdesc}
-
diff --git a/Doc/lib/libpipes.tex b/Doc/lib/libpipes.tex
deleted file mode 100644
index de25fb5..0000000
--- a/Doc/lib/libpipes.tex
+++ /dev/null
@@ -1,84 +0,0 @@
-\section{\module{pipes} ---
- Interface to shell pipelines}
-
-\declaremodule{standard}{pipes}
- \platform{Unix}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{A Python interface to \UNIX\ shell pipelines.}
-
-
-The \module{pipes} module defines a class to abstract the concept of
-a \emph{pipeline} --- a sequence of converters from one file to
-another.
-
-Because the module uses \program{/bin/sh} command lines, a \POSIX{} or
-compatible shell for \function{os.system()} and \function{os.popen()}
-is required.
-
-The \module{pipes} module defines the following class:
-
-\begin{classdesc}{Template}{}
-An abstraction of a pipeline.
-\end{classdesc}
-
-Example:
-
-\begin{verbatim}
->>> import pipes
->>> t=pipes.Template()
->>> t.append('tr a-z A-Z', '--')
->>> f=t.open('/tmp/1', 'w')
->>> f.write('hello world')
->>> f.close()
->>> open('/tmp/1').read()
-'HELLO WORLD'
-\end{verbatim}
-
-
-\subsection{Template Objects \label{template-objects}}
-
-Template objects following methods:
-
-\begin{methoddesc}[Template]{reset}{}
-Restore a pipeline template to its initial state.
-\end{methoddesc}
-
-\begin{methoddesc}[Template]{clone}{}
-Return a new, equivalent, pipeline template.
-\end{methoddesc}
-
-\begin{methoddesc}[Template]{debug}{flag}
-If \var{flag} is true, turn debugging on. Otherwise, turn debugging
-off. When debugging is on, commands to be executed are printed, and
-the shell is given \code{set -x} command to be more verbose.
-\end{methoddesc}
-
-\begin{methoddesc}[Template]{append}{cmd, kind}
-Append a new action at the end. The \var{cmd} variable must be a valid
-bourne shell command. The \var{kind} variable consists of two letters.
-
-The first letter can be either of \code{'-'} (which means the command
-reads its standard input), \code{'f'} (which means the commands reads
-a given file on the command line) or \code{'.'} (which means the commands
-reads no input, and hence must be first.)
-
-Similarly, the second letter can be either of \code{'-'} (which means
-the command writes to standard output), \code{'f'} (which means the
-command writes a file on the command line) or \code{'.'} (which means
-the command does not write anything, and hence must be last.)
-\end{methoddesc}
-
-\begin{methoddesc}[Template]{prepend}{cmd, kind}
-Add a new action at the beginning. See \method{append()} for explanations
-of the arguments.
-\end{methoddesc}
-
-\begin{methoddesc}[Template]{open}{file, mode}
-Return a file-like object, open to \var{file}, but read from or
-written to by the pipeline. Note that only one of \code{'r'},
-\code{'w'} may be given.
-\end{methoddesc}
-
-\begin{methoddesc}[Template]{copy}{infile, outfile}
-Copy \var{infile} to \var{outfile} through the pipe.
-\end{methoddesc}
diff --git a/Doc/lib/libpkgutil.tex b/Doc/lib/libpkgutil.tex
deleted file mode 100644
index a286f00..0000000
--- a/Doc/lib/libpkgutil.tex
+++ /dev/null
@@ -1,45 +0,0 @@
-\section{\module{pkgutil} ---
- Package extension utility}
-
-\declaremodule{standard}{pkgutil}
-\modulesynopsis{Utilities to support extension of packages.}
-
-\versionadded{2.3}
-
-This module provides a single function:
-
-\begin{funcdesc}{extend_path}{path, name}
- Extend the search path for the modules which comprise a package.
- Intended use is to place the following code in a package's
- \file{__init__.py}:
-
-\begin{verbatim}
-from pkgutil import extend_path
-__path__ = extend_path(__path__, __name__)
-\end{verbatim}
-
- This will add to the package's \code{__path__} all subdirectories of
- directories on \code{sys.path} named after the package. This is
- useful if one wants to distribute different parts of a single
- logical package as multiple directories.
-
- It also looks for \file{*.pkg} files beginning where \code{*}
- matches the \var{name} argument. This feature is similar to
- \file{*.pth} files (see the \refmodule{site} module for more
- information), except that it doesn't special-case lines starting
- with \code{import}. A \file{*.pkg} file is trusted at face value:
- apart from checking for duplicates, all entries found in a
- \file{*.pkg} file are added to the path, regardless of whether they
- exist on the filesystem. (This is a feature.)
-
- If the input path is not a list (as is the case for frozen
- packages) it is returned unchanged. The input path is not
- modified; an extended copy is returned. Items are only appended
- to the copy at the end.
-
- It is assumed that \code{sys.path} is a sequence. Items of
- \code{sys.path} that are not (Unicode or 8-bit) strings referring to
- existing directories are ignored. Unicode items on \code{sys.path}
- that cause errors when used as filenames may cause this function to
- raise an exception (in line with \function{os.path.isdir()} behavior).
-\end{funcdesc}
diff --git a/Doc/lib/libplatform.tex b/Doc/lib/libplatform.tex
deleted file mode 100644
index a2f1913..0000000
--- a/Doc/lib/libplatform.tex
+++ /dev/null
@@ -1,238 +0,0 @@
-\section{\module{platform} ---
- Access to underlying platform's identifying data.}
-
-\declaremodule{standard}{platform}
-\modulesynopsis{Retrieves as much platform identifying data as possible.}
-\moduleauthor{Marc-Andre Lemburg}{mal@egenix.com}
-\sectionauthor{Bjorn Pettersen}{bpettersen@corp.fairisaac.com}
-
-\versionadded{2.3}
-
-\begin{notice}
- Specific platforms listed alphabetically, with Linux included in the
- \UNIX{} section.
-\end{notice}
-
-\subsection{Cross Platform}
-
-\begin{funcdesc}{architecture}{executable=sys.executable, bits='', linkage=''}
- Queries the given executable (defaults to the Python interpreter
- binary) for various architecture information.
-
- Returns a tuple \code{(bits, linkage)} which contain information about
- the bit architecture and the linkage format used for the
- executable. Both values are returned as strings.
-
- Values that cannot be determined are returned as given by the
- parameter presets. If bits is given as \code{''}, the
- \cfunction{sizeof(pointer)}
- (or \cfunction{sizeof(long)} on Python version < 1.5.2) is used as
- indicator for the supported pointer size.
-
- The function relies on the system's \file{file} command to do the
- actual work. This is available on most if not all \UNIX{}
- platforms and some non-\UNIX{} platforms and then only if the
- executable points to the Python interpreter. Reasonable defaults
- are used when the above needs are not met.
-\end{funcdesc}
-
-\begin{funcdesc}{machine}{}
- Returns the machine type, e.g. \code{'i386'}.
- An empty string is returned if the value cannot be determined.
-\end{funcdesc}
-
-\begin{funcdesc}{node}{}
- Returns the computer's network name (may not be fully qualified!).
- An empty string is returned if the value cannot be determined.
-\end{funcdesc}
-
-\begin{funcdesc}{platform}{aliased=0, terse=0}
- Returns a single string identifying the underlying platform
- with as much useful information as possible.
-
- The output is intended to be \emph{human readable} rather than
- machine parseable. It may look different on different platforms and
- this is intended.
-
- If \var{aliased} is true, the function will use aliases for various
- platforms that report system names which differ from their common
- names, for example SunOS will be reported as Solaris. The
- \function{system_alias()} function is used to implement this.
-
- Setting \var{terse} to true causes the function to return only the
- absolute minimum information needed to identify the platform.
-\end{funcdesc}
-
-\begin{funcdesc}{processor}{}
- Returns the (real) processor name, e.g. \code{'amdk6'}.
-
- An empty string is returned if the value cannot be determined. Note
- that many platforms do not provide this information or simply return
- the same value as for \function{machine()}. NetBSD does this.
-\end{funcdesc}
-
-\begin{funcdesc}{python_build}{}
- Returns a tuple \code{(\var{buildno}, \var{builddate})} stating the
- Python build number and date as strings.
-\end{funcdesc}
-
-\begin{funcdesc}{python_compiler}{}
- Returns a string identifying the compiler used for compiling Python.
-\end{funcdesc}
-
-\begin{funcdesc}{python_branch}{}
- Returns a string identifying the Python implementation SCM branch.
- \versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{python_implementation}{}
- Returns a string identifying the Python implementation.
- Possible return values are: 'CPython', 'IronPython', 'Jython'
- \versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{python_revision}{}
- Returns a string identifying the Python implementation SCM revision.
- \versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{python_version}{}
- Returns the Python version as string \code{'major.minor.patchlevel'}
-
- Note that unlike the Python \code{sys.version}, the returned value
- will always include the patchlevel (it defaults to 0).
-\end{funcdesc}
-
-\begin{funcdesc}{python_version_tuple}{}
- Returns the Python version as tuple \code{(\var{major}, \var{minor},
- \var{patchlevel})} of strings.
-
- Note that unlike the Python \code{sys.version}, the returned value
- will always include the patchlevel (it defaults to \code{'0'}).
-\end{funcdesc}
-
-\begin{funcdesc}{release}{}
- Returns the system's release, e.g. \code{'2.2.0'} or \code{'NT'}
- An empty string is returned if the value cannot be determined.
-\end{funcdesc}
-
-\begin{funcdesc}{system}{}
- Returns the system/OS name, e.g. \code{'Linux'}, \code{'Windows'},
- or \code{'Java'}.
- An empty string is returned if the value cannot be determined.
-\end{funcdesc}
-
-\begin{funcdesc}{system_alias}{system, release, version}
- Returns \code{(\var{system}, \var{release}, \var{version})} aliased
- to common marketing names used for some systems. It also does some
- reordering of the information in some cases where it would otherwise
- cause confusion.
-\end{funcdesc}
-
-\begin{funcdesc}{version}{}
- Returns the system's release version, e.g. \code{'\#3 on degas'}.
- An empty string is returned if the value cannot be determined.
-\end{funcdesc}
-
-\begin{funcdesc}{uname}{}
- Fairly portable uname interface. Returns a tuple of strings
- \code{(\var{system}, \var{node}, \var{release}, \var{version},
- \var{machine}, \var{processor})} identifying the underlying
- platform.
-
- Note that unlike the \function{os.uname()} function this also returns
- possible processor information as additional tuple entry.
-
- Entries which cannot be determined are set to \code{''}.
-\end{funcdesc}
-
-
-\subsection{Java Platform}
-
-\begin{funcdesc}{java_ver}{release='', vendor='', vminfo=('','',''),
- osinfo=('','','')}
- Version interface for JPython.
-
- Returns a tuple \code{(\var{release}, \var{vendor}, \var{vminfo},
- \var{osinfo})} with \var{vminfo} being a tuple \code{(\var{vm_name},
- \var{vm_release}, \var{vm_vendor})} and \var{osinfo} being a tuple
- \code{(\var{os_name}, \var{os_version}, \var{os_arch})}.
- Values which cannot be determined are set to the defaults
- given as parameters (which all default to \code{''}).
-\end{funcdesc}
-
-
-\subsection{Windows Platform}
-
-\begin{funcdesc}{win32_ver}{release='', version='', csd='', ptype=''}
- Get additional version information from the Windows Registry
- and return a tuple \code{(\var{version}, \var{csd}, \var{ptype})}
- referring to version number, CSD level and OS type (multi/single
- processor).
-
- As a hint: \var{ptype} is \code{'Uniprocessor Free'} on single
- processor NT machines and \code{'Multiprocessor Free'} on multi
- processor machines. The \emph{'Free'} refers to the OS version being
- free of debugging code. It could also state \emph{'Checked'} which
- means the OS version uses debugging code, i.e. code that
- checks arguments, ranges, etc.
-
- \begin{notice}[note]
- This function only works if Mark Hammond's \module{win32all}
- package is installed and (obviously) only runs on Win32
- compatible platforms.
- \end{notice}
-\end{funcdesc}
-
-\subsubsection{Win95/98 specific}
-
-\begin{funcdesc}{popen}{cmd, mode='r', bufsize=None}
- Portable \function{popen()} interface. Find a working popen
- implementation preferring \function{win32pipe.popen()}. On Windows
- NT, \function{win32pipe.popen()} should work; on Windows 9x it hangs
- due to bugs in the MS C library.
- % This KnowledgeBase article appears to be missing...
- %See also \ulink{MS KnowledgeBase article Q150956}{}.
-\end{funcdesc}
-
-
-\subsection{Mac OS Platform}
-
-\begin{funcdesc}{mac_ver}{release='', versioninfo=('','',''), machine=''}
- Get Mac OS version information and return it as tuple
- \code{(\var{release}, \var{versioninfo}, \var{machine})} with
- \var{versioninfo} being a tuple \code{(\var{version},
- \var{dev_stage}, \var{non_release_version})}.
-
- Entries which cannot be determined are set to \code{''}. All tuple
- entries are strings.
-
- Documentation for the underlying \cfunction{gestalt()} API is
- available online at \url{http://www.rgaros.nl/gestalt/}.
-\end{funcdesc}
-
-
-\subsection{\UNIX{} Platforms}
-
-\begin{funcdesc}{dist}{distname='', version='', id='',
- supported_dists=('SuSE','debian','redhat','mandrake')}
- Tries to determine the name of the OS distribution name
- Returns a tuple \code{(\var{distname}, \var{version}, \var{id})}
- which defaults to the args given as parameters.
-\end{funcdesc}
-
-% Document linux_distribution()?
-
-\begin{funcdesc}{libc_ver}{executable=sys.executable, lib='',
- version='', chunksize=2048}
- Tries to determine the libc version against which the file
- executable (defaults to the Python interpreter) is linked. Returns
- a tuple of strings \code{(\var{lib}, \var{version})} which default
- to the given parameters in case the lookup fails.
-
- Note that this function has intimate knowledge of how different
- libc versions add symbols to the executable is probably only
- useable for executables compiled using \program{gcc}.
-
- The file is read and scanned in chunks of \var{chunksize} bytes.
-\end{funcdesc}
diff --git a/Doc/lib/libpoplib.tex b/Doc/lib/libpoplib.tex
deleted file mode 100644
index 9ca5bbd..0000000
--- a/Doc/lib/libpoplib.tex
+++ /dev/null
@@ -1,187 +0,0 @@
-\section{\module{poplib} ---
- POP3 protocol client}
-
-\declaremodule{standard}{poplib}
-\modulesynopsis{POP3 protocol client (requires sockets).}
-
-%By Andrew T. Csillag
-%Even though I put it into LaTeX, I cannot really claim that I wrote
-%it since I just stole most of it from the poplib.py source code and
-%the imaplib ``chapter''.
-%Revised by ESR, January 2000
-
-\indexii{POP3}{protocol}
-
-This module defines a class, \class{POP3}, which encapsulates a
-connection to a POP3 server and implements the protocol as defined in
-\rfc{1725}. The \class{POP3} class supports both the minimal and
-optional command sets. Additionally, this module provides a class
-\class{POP3_SSL}, which provides support for connecting to POP3
-servers that use SSL as an underlying protocol layer.
-
-
-Note that POP3, though widely supported, is obsolescent. The
-implementation quality of POP3 servers varies widely, and too many are
-quite poor. If your mailserver supports IMAP, you would be better off
-using the \class{\refmodule{imaplib}.IMAP4} class, as IMAP
-servers tend to be better implemented.
-
-A single class is provided by the \module{poplib} module:
-
-\begin{classdesc}{POP3}{host\optional{, port\optional{, timeout}}}
-This class implements the actual POP3 protocol. The connection is
-created when the instance is initialized.
-If \var{port} is omitted, the standard POP3 port (110) is used.
-The optional \var{timeout} parameter specifies a timeout in seconds for the
-connection attempt (if not specified, or passed as None, the global default
-timeout setting will be used).
-
-\versionchanged[\var{timeout} was added]{2.6}
-\end{classdesc}
-
-\begin{classdesc}{POP3_SSL}{host\optional{, port\optional{, keyfile\optional{, certfile}}}}
-This is a subclass of \class{POP3} that connects to the server over an
-SSL encrypted socket. If \var{port} is not specified, 995, the
-standard POP3-over-SSL port is used. \var{keyfile} and \var{certfile}
-are also optional - they can contain a PEM formatted private key and
-certificate chain file for the SSL connection.
-
-\versionadded{2.4}
-\end{classdesc}
-
-One exception is defined as an attribute of the \module{poplib} module:
-
-\begin{excdesc}{error_proto}
-Exception raised on any errors from this module (errors from
-\module{socket} module are not caught). The reason for the exception
-is passed to the constructor as a string.
-\end{excdesc}
-
-\begin{seealso}
- \seemodule{imaplib}{The standard Python IMAP module.}
- \seetitle[http://www.catb.org/\~{}esr/fetchmail/fetchmail-FAQ.html]
- {Frequently Asked Questions About Fetchmail}
- {The FAQ for the \program{fetchmail} POP/IMAP client collects
- information on POP3 server variations and RFC noncompliance
- that may be useful if you need to write an application based
- on the POP protocol.}
-\end{seealso}
-
-
-\subsection{POP3 Objects \label{pop3-objects}}
-
-All POP3 commands are represented by methods of the same name,
-in lower-case; most return the response text sent by the server.
-
-An \class{POP3} instance has the following methods:
-
-
-\begin{methoddesc}[POP3]{set_debuglevel}{level}
-Set the instance's debugging level. This controls the amount of
-debugging output printed. The default, \code{0}, produces no
-debugging output. A value of \code{1} produces a moderate amount of
-debugging output, generally a single line per request. A value of
-\code{2} or higher produces the maximum amount of debugging output,
-logging each line sent and received on the control connection.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{getwelcome}{}
-Returns the greeting string sent by the POP3 server.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{user}{username}
-Send user command, response should indicate that a password is required.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{pass_}{password}
-Send password, response includes message count and mailbox size.
-Note: the mailbox on the server is locked until \method{quit()} is
-called.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{apop}{user, secret}
-Use the more secure APOP authentication to log into the POP3 server.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{rpop}{user}
-Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{stat}{}
-Get mailbox status. The result is a tuple of 2 integers:
-\code{(\var{message count}, \var{mailbox size})}.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{list}{\optional{which}}
-Request message list, result is in the form
-\code{(\var{response}, ['mesg_num octets', ...], \var{octets})}.
-If \var{which} is set, it is the message to list.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{retr}{which}
-Retrieve whole message number \var{which}, and set its seen flag.
-Result is in form \code{(\var{response}, ['line', ...], \var{octets})}.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{dele}{which}
-Flag message number \var{which} for deletion. On most servers
-deletions are not actually performed until QUIT (the major exception is
-Eudora QPOP, which deliberately violates the RFCs by doing pending
-deletes on any disconnect).
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{rset}{}
-Remove any deletion marks for the mailbox.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{noop}{}
-Do nothing. Might be used as a keep-alive.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{quit}{}
-Signoff: commit changes, unlock mailbox, drop connection.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{top}{which, howmuch}
-Retrieves the message header plus \var{howmuch} lines of the message
-after the header of message number \var{which}. Result is in form
-\code{(\var{response}, ['line', ...], \var{octets})}.
-
-The POP3 TOP command this method uses, unlike the RETR command,
-doesn't set the message's seen flag; unfortunately, TOP is poorly
-specified in the RFCs and is frequently broken in off-brand servers.
-Test this method by hand against the POP3 servers you will use before
-trusting it.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{uidl}{\optional{which}}
-Return message digest (unique id) list.
-If \var{which} is specified, result contains the unique id for that
-message in the form \code{'\var{response}\ \var{mesgnum}\ \var{uid}},
-otherwise result is list \code{(\var{response}, ['mesgnum uid', ...],
-\var{octets})}.
-\end{methoddesc}
-
-Instances of \class{POP3_SSL} have no additional methods. The
-interface of this subclass is identical to its parent.
-
-
-\subsection{POP3 Example \label{pop3-example}}
-
-Here is a minimal example (without error checking) that opens a
-mailbox and retrieves and prints all messages:
-
-\begin{verbatim}
-import getpass, poplib
-
-M = poplib.POP3('localhost')
-M.user(getpass.getuser())
-M.pass_(getpass.getpass())
-numMessages = len(M.list()[1])
-for i in range(numMessages):
- for j in M.retr(i+1)[1]:
- print j
-\end{verbatim}
-
-At the end of the module, there is a test section that contains a more
-extensive example of usage.
diff --git a/Doc/lib/libposix.tex b/Doc/lib/libposix.tex
deleted file mode 100644
index aee6c0d..0000000
--- a/Doc/lib/libposix.tex
+++ /dev/null
@@ -1,97 +0,0 @@
-\section{\module{posix} ---
- The most common \POSIX{} system calls}
-
-\declaremodule{builtin}{posix}
- \platform{Unix}
-\modulesynopsis{The most common \POSIX\ system calls (normally used
- via module \refmodule{os}).}
-
-
-This module provides access to operating system functionality that is
-standardized by the C Standard and the \POSIX{} standard (a thinly
-disguised \UNIX{} interface).
-
-\strong{Do not import this module directly.} Instead, import the
-module \refmodule{os}, which provides a \emph{portable} version of this
-interface. On \UNIX, the \refmodule{os} module provides a superset of
-the \module{posix} interface. On non-\UNIX{} operating systems the
-\module{posix} module is not available, but a subset is always
-available through the \refmodule{os} interface. Once \refmodule{os} is
-imported, there is \emph{no} performance penalty in using it instead
-of \module{posix}. In addition, \refmodule{os}\refstmodindex{os}
-provides some additional functionality, such as automatically calling
-\function{putenv()} when an entry in \code{os.environ} is changed.
-
-The descriptions below are very terse; refer to the corresponding
-\UNIX{} manual (or \POSIX{} documentation) entry for more information.
-Arguments called \var{path} refer to a pathname given as a string.
-
-Errors are reported as exceptions; the usual exceptions are given for
-type errors, while errors reported by the system calls raise
-\exception{error} (a synonym for the standard exception
-\exception{OSError}), described below.
-
-
-\subsection{Large File Support \label{posix-large-files}}
-\sectionauthor{Steve Clift}{clift@mail.anacapa.net}
-\index{large files}
-\index{file!large files}
-
-
-Several operating systems (including AIX, HPUX, Irix and Solaris)
-provide support for files that are larger than 2 Gb from a C
-programming model where \ctype{int} and \ctype{long} are 32-bit
-values. This is typically accomplished by defining the relevant size
-and offset types as 64-bit values. Such files are sometimes referred
-to as \dfn{large files}.
-
-Large file support is enabled in Python when the size of an
-\ctype{off_t} is larger than a \ctype{long} and the \ctype{long long}
-type is available and is at least as large as an \ctype{off_t}. Python
-longs are then used to represent file sizes, offsets and other values
-that can exceed the range of a Python int. It may be necessary to
-configure and compile Python with certain compiler flags to enable
-this mode. For example, it is enabled by default with recent versions
-of Irix, but with Solaris 2.6 and 2.7 you need to do something like:
-
-\begin{verbatim}
-CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \
- ./configure
-\end{verbatim} % $ <-- bow to font-lock
-
-On large-file-capable Linux systems, this might work:
-
-\begin{verbatim}
-CFLAGS='-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64' OPT="-g -O2 $CFLAGS" \
- ./configure
-\end{verbatim} % $ <-- bow to font-lock
-
-
-\subsection{Module Contents \label{posix-contents}}
-
-
-Module \module{posix} defines the following data item:
-
-\begin{datadesc}{environ}
-A dictionary representing the string environment at the time the
-interpreter was started. For example, \code{environ['HOME']} is the
-pathname of your home directory, equivalent to
-\code{getenv("HOME")} in C.
-
-Modifying this dictionary does not affect the string environment
-passed on by \function{execv()}, \function{popen()} or
-\function{system()}; if you need to change the environment, pass
-\code{environ} to \function{execve()} or add variable assignments and
-export statements to the command string for \function{system()} or
-\function{popen()}.
-
-\note{The \refmodule{os} module provides an alternate
-implementation of \code{environ} which updates the environment on
-modification. Note also that updating \code{os.environ} will render
-this dictionary obsolete. Use of the \refmodule{os} module version of
-this is recommended over direct access to the \module{posix} module.}
-\end{datadesc}
-
-Additional contents of this module should only be accessed via the
-\refmodule{os} module; refer to the documentation for that module for
-further information.
diff --git a/Doc/lib/libposixpath.tex b/Doc/lib/libposixpath.tex
deleted file mode 100644
index 7684fa0..0000000
--- a/Doc/lib/libposixpath.tex
+++ /dev/null
@@ -1,300 +0,0 @@
-\section{\module{os.path} ---
- Common pathname manipulations}
-\declaremodule{standard}{os.path}
-
-\modulesynopsis{Common pathname manipulations.}
-
-This module implements some useful functions on pathnames.
-\index{path!operations}
-
-\warning{On Windows, many of these functions do not properly
-support UNC pathnames. \function{splitunc()} and \function{ismount()}
-do handle them correctly.}
-
-
-\begin{funcdesc}{abspath}{path}
-Return a normalized absolutized version of the pathname \var{path}.
-On most platforms, this is equivalent to
-\code{normpath(join(os.getcwd(), \var{path}))}.
-\versionadded{1.5.2}
-\end{funcdesc}
-
-\begin{funcdesc}{basename}{path}
-Return the base name of pathname \var{path}. This is the second half
-of the pair returned by \code{split(\var{path})}. Note that the
-result of this function is different from the
-\UNIX{} \program{basename} program; where \program{basename} for
-\code{'/foo/bar/'} returns \code{'bar'}, the \function{basename()}
-function returns an empty string (\code{''}).
-\end{funcdesc}
-
-\begin{funcdesc}{commonprefix}{list}
-Return the longest path prefix (taken character-by-character) that is a
-prefix of all paths in
-\var{list}. If \var{list} is empty, return the empty string
-(\code{''}). Note that this may return invalid paths because it works a
-character at a time.
-\end{funcdesc}
-
-\begin{funcdesc}{dirname}{path}
-Return the directory name of pathname \var{path}. This is the first
-half of the pair returned by \code{split(\var{path})}.
-\end{funcdesc}
-
-\begin{funcdesc}{exists}{path}
-Return \code{True} if \var{path} refers to an existing path. Returns
-\code{False} for broken symbolic links. On some platforms, this
-function may return \code{False} if permission is not granted to
-execute \function{os.stat()} on the requested file, even if the
-\var{path} physically exists.
-\end{funcdesc}
-
-\begin{funcdesc}{lexists}{path}
-Return \code{True} if \var{path} refers to an existing path.
-Returns \code{True} for broken symbolic links.
-Equivalent to \function{exists()} on platforms lacking
-\function{os.lstat()}.
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{expanduser}{path}
-On \UNIX{} and Windows, return the argument with an initial component of
-\samp{\~} or \samp{\~\var{user}} replaced by that \var{user}'s home directory.
-
-On \UNIX, an initial \samp{\~} is replaced by the environment variable
-\envvar{HOME} if it is set; otherwise the current user's home directory
-is looked up in the password directory through the built-in module
-\refmodule{pwd}\refbimodindex{pwd}.
-An initial \samp{\~\var{user}} is looked up directly in the
-password directory.
-
-On Windows, \envvar{HOME} and \envvar{USERPROFILE} will be used if set,
-otherwise a combination of \envvar{HOMEPATH} and \envvar{HOMEDRIVE} will be
-used. An initial \samp{\~\var{user}} is handled by stripping the last
-directory component from the created user path derived above.
-
-If the expansion fails or if the
-path does not begin with a tilde, the path is returned unchanged.
-\end{funcdesc}
-
-\begin{funcdesc}{expandvars}{path}
-Return the argument with environment variables expanded. Substrings
-of the form \samp{\$\var{name}} or \samp{\$\{\var{name}\}} are
-replaced by the value of environment variable \var{name}. Malformed
-variable names and references to non-existing variables are left
-unchanged.
-
-On Windows, \samp{\%\var{name}\%} expansions are supported in addition to
-\samp{\$\var{name}} and \samp{\$\{\var{name}\}}.
-\end{funcdesc}
-
-\begin{funcdesc}{getatime}{path}
-Return the time of last access of \var{path}. The return
-value is a number giving the number of seconds since the epoch (see the
-\refmodule{time} module). Raise \exception{os.error} if the file does
-not exist or is inaccessible.
-\versionadded{1.5.2}
-\versionchanged[If \function{os.stat_float_times()} returns True, the result is a floating point number]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getmtime}{path}
-Return the time of last modification of \var{path}. The return
-value is a number giving the number of seconds since the epoch (see the
-\refmodule{time} module). Raise \exception{os.error} if the file does
-not exist or is inaccessible.
-\versionadded{1.5.2}
-\versionchanged[If \function{os.stat_float_times()} returns True, the result is a floating point number]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getctime}{path}
-Return the system's ctime which, on some systems (like \UNIX) is the
-time of the last change, and, on others (like Windows), is the
-creation time for \var{path}. The return
-value is a number giving the number of seconds since the epoch (see the
-\refmodule{time} module). Raise \exception{os.error} if the file does
-not exist or is inaccessible.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getsize}{path}
-Return the size, in bytes, of \var{path}. Raise
-\exception{os.error} if the file does not exist or is inaccessible.
-\versionadded{1.5.2}
-\end{funcdesc}
-
-\begin{funcdesc}{isabs}{path}
-Return \code{True} if \var{path} is an absolute pathname (begins with a
-slash).
-\end{funcdesc}
-
-\begin{funcdesc}{isfile}{path}
-Return \code{True} if \var{path} is an existing regular file. This follows
-symbolic links, so both \function{islink()} and \function{isfile()}
-can be true for the same path.
-\end{funcdesc}
-
-\begin{funcdesc}{isdir}{path}
-Return \code{True} if \var{path} is an existing directory. This follows
-symbolic links, so both \function{islink()} and \function{isdir()} can
-be true for the same path.
-\end{funcdesc}
-
-\begin{funcdesc}{islink}{path}
-Return \code{True} if \var{path} refers to a directory entry that is a
-symbolic link. Always \code{False} if symbolic links are not supported.
-\end{funcdesc}
-
-\begin{funcdesc}{ismount}{path}
-Return \code{True} if pathname \var{path} is a \dfn{mount point}: a point in
-a file system where a different file system has been mounted. The
-function checks whether \var{path}'s parent, \file{\var{path}/..}, is
-on a different device than \var{path}, or whether \file{\var{path}/..}
-and \var{path} point to the same i-node on the same device --- this
-should detect mount points for all \UNIX{} and \POSIX{} variants.
-\end{funcdesc}
-
-\begin{funcdesc}{join}{path1\optional{, path2\optional{, ...}}}
-Join one or more path components intelligently. If any component is
-an absolute path, all previous components (on Windows, including the
-previous drive letter, if there was one) are thrown away, and joining
-continues. The return value is the concatenation of \var{path1}, and
-optionally \var{path2}, etc., with exactly one directory separator
-(\code{os.sep}) inserted between components, unless \var{path2} is
-empty. Note that on Windows, since there is a current directory for
-each drive, \function{os.path.join("c:", "foo")} represents a path
-relative to the current directory on drive \file{C:} (\file{c:foo}), not
-\file{c:\textbackslash\textbackslash foo}.
-\end{funcdesc}
-
-\begin{funcdesc}{normcase}{path}
-Normalize the case of a pathname. On \UNIX, this returns the path
-unchanged; on case-insensitive filesystems, it converts the path to
-lowercase. On Windows, it also converts forward slashes to backward
-slashes.
-\end{funcdesc}
-
-\begin{funcdesc}{normpath}{path}
-Normalize a pathname. This collapses redundant separators and
-up-level references so that \code{A//B}, \code{A/./B} and
-\code{A/foo/../B} all become \code{A/B}. It does not normalize the
-case (use \function{normcase()} for that). On Windows, it converts
-forward slashes to backward slashes. It should be understood that this may
-change the meaning of the path if it contains symbolic links!
-\end{funcdesc}
-
-\begin{funcdesc}{realpath}{path}
-Return the canonical path of the specified filename, eliminating any
-symbolic links encountered in the path (if they are supported by the
-operating system).
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{relpath}{path\optional{, start}}
-Return a relative filepath to \var{path} either from the current
-directory or from an optional \var{start} point.
-
-\var{start} defaults to \member{os.curdir}.
-Availability: Windows, \UNIX.
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{samefile}{path1, path2}
-Return \code{True} if both pathname arguments refer to the same file or
-directory (as indicated by device number and i-node number).
-Raise an exception if a \function{os.stat()} call on either pathname
-fails.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{sameopenfile}{fp1, fp2}
-Return \code{True} if the file descriptors \var{fp1} and \var{fp2} refer
-to the same file.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{samestat}{stat1, stat2}
-Return \code{True} if the stat tuples \var{stat1} and \var{stat2} refer to
-the same file. These structures may have been returned by
-\function{fstat()}, \function{lstat()}, or \function{stat()}. This
-function implements the underlying comparison used by
-\function{samefile()} and \function{sameopenfile()}.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{split}{path}
-Split the pathname \var{path} into a pair, \code{(\var{head},
-\var{tail})} where \var{tail} is the last pathname component and
-\var{head} is everything leading up to that. The \var{tail} part will
-never contain a slash; if \var{path} ends in a slash, \var{tail} will
-be empty. If there is no slash in \var{path}, \var{head} will be
-empty. If \var{path} is empty, both \var{head} and \var{tail} are
-empty. Trailing slashes are stripped from \var{head} unless it is the
-root (one or more slashes only). In nearly all cases,
-\code{join(\var{head}, \var{tail})} equals \var{path} (the only
-exception being when there were multiple slashes separating \var{head}
-from \var{tail}).
-\end{funcdesc}
-
-\begin{funcdesc}{splitdrive}{path}
-Split the pathname \var{path} into a pair \code{(\var{drive},
-\var{tail})} where \var{drive} is either a drive specification or the
-empty string. On systems which do not use drive specifications,
-\var{drive} will always be the empty string. In all cases,
-\code{\var{drive} + \var{tail}} will be the same as \var{path}.
-\versionadded{1.3}
-\end{funcdesc}
-
-\begin{funcdesc}{splitext}{path}
-Split the pathname \var{path} into a pair \code{(\var{root}, \var{ext})}
-such that \code{\var{root} + \var{ext} == \var{path}},
-and \var{ext} is empty or begins with a period and contains
-at most one period. Leading periods on the basename are
-ignored; \code{\var{splitext}.('.cshrc')} returns
-\code{('.cshrc', '')}.
-
-\versionchanged[Earlier versions could produce an empty root when
-the only period was the first character]{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{splitunc}{path}
-Split the pathname \var{path} into a pair \code{(\var{unc}, \var{rest})}
-so that \var{unc} is the UNC mount point (such as \code{r'\e\e host\e mount'}),
-if present, and \var{rest} the rest of the path (such as
-\code{r'\e path\e file.ext'}). For paths containing drive letters, \var{unc}
-will always be the empty string.
-Availability: Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{walk}{path, visit, arg}
-Calls the function \var{visit} with arguments
-\code{(\var{arg}, \var{dirname}, \var{names})} for each directory in the
-directory tree rooted at \var{path} (including \var{path} itself, if it
-is a directory). The argument \var{dirname} specifies the visited
-directory, the argument \var{names} lists the files in the directory
-(gotten from \code{os.listdir(\var{dirname})}).
-The \var{visit} function may modify \var{names} to
-influence the set of directories visited below \var{dirname}, e.g. to
-avoid visiting certain parts of the tree. (The object referred to by
-\var{names} must be modified in place, using \keyword{del} or slice
-assignment.)
-
-\begin{notice}
-Symbolic links to directories are not treated as subdirectories, and
-that \function{walk()} therefore will not visit them. To visit linked
-directories you must identify them with
-\code{os.path.islink(\var{file})} and
-\code{os.path.isdir(\var{file})}, and invoke \function{walk()} as
-necessary.
-\end{notice}
-
-\note{The newer \function{\refmodule{os}.walk()} generator supplies
- similar functionality and can be easier to use.}
-\end{funcdesc}
-
-\begin{datadesc}{supports_unicode_filenames}
-True if arbitrary Unicode strings can be used as file names (within
-limitations imposed by the file system), and if
-\function{os.listdir()} returns Unicode strings for a Unicode
-argument.
-\versionadded{2.3}
-\end{datadesc}
diff --git a/Doc/lib/libpprint.tex b/Doc/lib/libpprint.tex
deleted file mode 100644
index ce35b44..0000000
--- a/Doc/lib/libpprint.tex
+++ /dev/null
@@ -1,210 +0,0 @@
-\section{\module{pprint} ---
- Data pretty printer}
-
-\declaremodule{standard}{pprint}
-\modulesynopsis{Data pretty printer.}
-\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-The \module{pprint} module provides a capability to ``pretty-print''
-arbitrary Python data structures in a form which can be used as input
-to the interpreter. If the formatted structures include objects which
-are not fundamental Python types, the representation may not be
-loadable. This may be the case if objects such as files, sockets,
-classes, or instances are included, as well as many other builtin
-objects which are not representable as Python constants.
-
-The formatted representation keeps objects on a single line if it can,
-and breaks them onto multiple lines if they don't fit within the
-allowed width. Construct \class{PrettyPrinter} objects explicitly if
-you need to adjust the width constraint.
-
-\versionchanged[Dictionaries are sorted by key before the display is
-computed; before 2.5, a dictionary was sorted only if its display
-required more than one line, although that wasn't documented]{2.5}
-
-The \module{pprint} module defines one class:
-
-
-% First the implementation class:
-
-\begin{classdesc}{PrettyPrinter}{...}
-Construct a \class{PrettyPrinter} instance. This constructor
-understands several keyword parameters. An output stream may be set
-using the \var{stream} keyword; the only method used on the stream
-object is the file protocol's \method{write()} method. If not
-specified, the \class{PrettyPrinter} adopts \code{sys.stdout}. Three
-additional parameters may be used to control the formatted
-representation. The keywords are \var{indent}, \var{depth}, and
-\var{width}. The amount of indentation added for each recursive level
-is specified by \var{indent}; the default is one. Other values can
-cause output to look a little odd, but can make nesting easier to
-spot. The number of levels which may be printed is controlled by
-\var{depth}; if the data structure being printed is too deep, the next
-contained level is replaced by \samp{...}. By default, there is no
-constraint on the depth of the objects being formatted. The desired
-output width is constrained using the \var{width} parameter; the
-default is eighty characters. If a structure cannot be formatted
-within the constrained width, a best effort will be made.
-
-\begin{verbatim}
->>> import pprint, sys
->>> stuff = sys.path[:]
->>> stuff.insert(0, stuff[:])
->>> pp = pprint.PrettyPrinter(indent=4)
->>> pp.pprint(stuff)
-[ [ '',
- '/usr/local/lib/python1.5',
- '/usr/local/lib/python1.5/test',
- '/usr/local/lib/python1.5/sunos5',
- '/usr/local/lib/python1.5/sharedmodules',
- '/usr/local/lib/python1.5/tkinter'],
- '',
- '/usr/local/lib/python1.5',
- '/usr/local/lib/python1.5/test',
- '/usr/local/lib/python1.5/sunos5',
- '/usr/local/lib/python1.5/sharedmodules',
- '/usr/local/lib/python1.5/tkinter']
->>>
->>> import parser
->>> tup = parser.ast2tuple(
-... parser.suite(open('pprint.py').read()))[1][1][1]
->>> pp = pprint.PrettyPrinter(depth=6)
->>> pp.pprint(tup)
-(266, (267, (307, (287, (288, (...))))))
-\end{verbatim}
-\end{classdesc}
-
-
-% Now the derivative functions:
-
-The \class{PrettyPrinter} class supports several derivative functions:
-
-\begin{funcdesc}{pformat}{object\optional{, indent\optional{,
-width\optional{, depth}}}}
-Return the formatted representation of \var{object} as a string. \var{indent},
-\var{width} and \var{depth} will be passed to the \class{PrettyPrinter}
-constructor as formatting parameters.
-\versionchanged[The parameters \var{indent}, \var{width} and \var{depth}
-were added]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{pprint}{object\optional{, stream\optional{,
-indent\optional{, width\optional{, depth}}}}}
-Prints the formatted representation of \var{object} on \var{stream},
-followed by a newline. If \var{stream} is omitted, \code{sys.stdout}
-is used. This may be used in the interactive interpreter instead of a
-\keyword{print} statement for inspecting values. \var{indent},
-\var{width} and \var{depth} will be passed to the \class{PrettyPrinter}
-constructor as formatting parameters.
-
-\begin{verbatim}
->>> stuff = sys.path[:]
->>> stuff.insert(0, stuff)
->>> pprint.pprint(stuff)
-[<Recursion on list with id=869440>,
- '',
- '/usr/local/lib/python1.5',
- '/usr/local/lib/python1.5/test',
- '/usr/local/lib/python1.5/sunos5',
- '/usr/local/lib/python1.5/sharedmodules',
- '/usr/local/lib/python1.5/tkinter']
-\end{verbatim}
-\versionchanged[The parameters \var{indent}, \var{width} and \var{depth}
-were added]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{isreadable}{object}
-Determine if the formatted representation of \var{object} is
-``readable,'' or can be used to reconstruct the value using
-\function{eval()}\bifuncindex{eval}. This always returns \code{False} for
-recursive objects.
-
-\begin{verbatim}
->>> pprint.isreadable(stuff)
-False
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{isrecursive}{object}
-Determine if \var{object} requires a recursive representation.
-\end{funcdesc}
-
-
-One more support function is also defined:
-
-\begin{funcdesc}{saferepr}{object}
-Return a string representation of \var{object}, protected against
-recursive data structures. If the representation of \var{object}
-exposes a recursive entry, the recursive reference will be represented
-as \samp{<Recursion on \var{typename} with id=\var{number}>}. The
-representation is not otherwise formatted.
-\end{funcdesc}
-
-% This example is outside the {funcdesc} to keep it from running over
-% the right margin.
-\begin{verbatim}
->>> pprint.saferepr(stuff)
-"[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.5', '/usr/loca
-l/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python
-1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter']"
-\end{verbatim}
-
-
-\subsection{PrettyPrinter Objects}
-\label{PrettyPrinter Objects}
-
-\class{PrettyPrinter} instances have the following methods:
-
-
-\begin{methoddesc}[PrettyPrinter]{pformat}{object}
-Return the formatted representation of \var{object}. This takes into
-account the options passed to the \class{PrettyPrinter} constructor.
-\end{methoddesc}
-
-\begin{methoddesc}[PrettyPrinter]{pprint}{object}
-Print the formatted representation of \var{object} on the configured
-stream, followed by a newline.
-\end{methoddesc}
-
-The following methods provide the implementations for the
-corresponding functions of the same names. Using these methods on an
-instance is slightly more efficient since new \class{PrettyPrinter}
-objects don't need to be created.
-
-\begin{methoddesc}[PrettyPrinter]{isreadable}{object}
-Determine if the formatted representation of the object is
-``readable,'' or can be used to reconstruct the value using
-\function{eval()}\bifuncindex{eval}. Note that this returns \code{False} for
-recursive objects. If the \var{depth} parameter of the
-\class{PrettyPrinter} is set and the object is deeper than allowed,
-this returns \code{False}.
-\end{methoddesc}
-
-\begin{methoddesc}[PrettyPrinter]{isrecursive}{object}
-Determine if the object requires a recursive representation.
-\end{methoddesc}
-
-This method is provided as a hook to allow subclasses to modify the
-way objects are converted to strings. The default implementation uses
-the internals of the \function{saferepr()} implementation.
-
-\begin{methoddesc}[PrettyPrinter]{format}{object, context, maxlevels, level}
-Returns three values: the formatted version of \var{object} as a
-string, a flag indicating whether the result is readable, and a flag
-indicating whether recursion was detected. The first argument is the
-object to be presented. The second is a dictionary which contains the
-\function{id()} of objects that are part of the current presentation
-context (direct and indirect containers for \var{object} that are
-affecting the presentation) as the keys; if an object needs to be
-presented which is already represented in \var{context}, the third
-return value should be \code{True}. Recursive calls to the \method{format()}
-method should add additional entries for containers to this
-dictionary. The third argument, \var{maxlevels}, gives the requested
-limit to recursion; this will be \code{0} if there is no requested
-limit. This argument should be passed unmodified to recursive calls.
-The fourth argument, \var{level}, gives the current level; recursive
-calls should be passed a value less than that of the current call.
-\versionadded{2.3}
-\end{methoddesc}
diff --git a/Doc/lib/libprofile.tex b/Doc/lib/libprofile.tex
deleted file mode 100644
index 79a168c..0000000
--- a/Doc/lib/libprofile.tex
+++ /dev/null
@@ -1,722 +0,0 @@
-\chapter{The Python Profilers \label{profile}}
-
-\sectionauthor{James Roskind}{}
-
-Copyright \copyright{} 1994, by InfoSeek Corporation, all rights reserved.
-\index{InfoSeek Corporation}
-
-Written by James Roskind.\footnote{
- Updated and converted to \LaTeX\ by Guido van Rossum.
- Further updated by Armin Rigo to integrate the documentation for the new
- \module{cProfile} module of Python 2.5.}
-
-Permission to use, copy, modify, and distribute this Python software
-and its associated documentation for any purpose (subject to the
-restriction in the following sentence) without fee is hereby granted,
-provided that the above copyright notice appears in all copies, and
-that both that copyright notice and this permission notice appear in
-supporting documentation, and that the name of InfoSeek not be used in
-advertising or publicity pertaining to distribution of the software
-without specific, written prior permission. This permission is
-explicitly restricted to the copying and modification of the software
-to remain in Python, compiled Python, or other languages (such as C)
-wherein the modified or derived code is exclusively imported into a
-Python module.
-
-INFOSEEK CORPORATION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
-SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
-FITNESS. IN NO EVENT SHALL INFOSEEK CORPORATION BE LIABLE FOR ANY
-SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
-RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
-CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
-CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-
-
-The profiler was written after only programming in Python for 3 weeks.
-As a result, it is probably clumsy code, but I don't know for sure yet
-'cause I'm a beginner :-). I did work hard to make the code run fast,
-so that profiling would be a reasonable thing to do. I tried not to
-repeat code fragments, but I'm sure I did some stuff in really awkward
-ways at times. Please send suggestions for improvements to:
-\email{jar@netscape.com}. I won't promise \emph{any} support. ...but
-I'd appreciate the feedback.
-
-
-\section{Introduction to the profilers}
-\nodename{Profiler Introduction}
-
-A \dfn{profiler} is a program that describes the run time performance
-of a program, providing a variety of statistics. This documentation
-describes the profiler functionality provided in the modules
-\module{profile} and \module{pstats}. This profiler provides
-\dfn{deterministic profiling} of any Python programs. It also
-provides a series of report generation tools to allow users to rapidly
-examine the results of a profile operation.
-\index{deterministic profiling}
-\index{profiling, deterministic}
-
-The Python standard library provides three different profilers:
-
-\begin{enumerate}
-\item \module{profile}, a pure Python module, described in the sequel.
- Copyright \copyright{} 1994, by InfoSeek Corporation.
- \versionchanged[also reports the time spent in calls to built-in
- functions and methods]{2.4}
-
-\item \module{cProfile}, a module written in C, with a reasonable
- overhead that makes it suitable for profiling long-running programs.
- Based on \module{lsprof}, contributed by Brett Rosen and Ted Czotter.
- \versionadded{2.5}
-
-\item \module{hotshot}, a C module focusing on minimizing the overhead
- while profiling, at the expense of long data post-processing times.
- \versionchanged[the results should be more meaningful than in the
- past: the timing core contained a critical bug]{2.5}
-\end{enumerate}
-
-The \module{profile} and \module{cProfile} modules export the same
-interface, so they are mostly interchangeables; \module{cProfile} has a
-much lower overhead but is not so far as well-tested and might not be
-available on all systems. \module{cProfile} is really a compatibility
-layer on top of the internal \module{_lsprof} module. The
-\module{hotshot} module is reserved to specialized usages.
-
-%\section{How Is This Profiler Different From The Old Profiler?}
-%\nodename{Profiler Changes}
-%
-%(This section is of historical importance only; the old profiler
-%discussed here was last seen in Python 1.1.)
-%
-%The big changes from old profiling module are that you get more
-%information, and you pay less CPU time. It's not a trade-off, it's a
-%trade-up.
-%
-%To be specific:
-%
-%\begin{description}
-%
-%\item[Bugs removed:]
-%Local stack frame is no longer molested, execution time is now charged
-%to correct functions.
-%
-%\item[Accuracy increased:]
-%Profiler execution time is no longer charged to user's code,
-%calibration for platform is supported, file reads are not done \emph{by}
-%profiler \emph{during} profiling (and charged to user's code!).
-%
-%\item[Speed increased:]
-%Overhead CPU cost was reduced by more than a factor of two (perhaps a
-%factor of five), lightweight profiler module is all that must be
-%loaded, and the report generating module (\module{pstats}) is not needed
-%during profiling.
-%
-%\item[Recursive functions support:]
-%Cumulative times in recursive functions are correctly calculated;
-%recursive entries are counted.
-%
-%\item[Large growth in report generating UI:]
-%Distinct profiles runs can be added together forming a comprehensive
-%report; functions that import statistics take arbitrary lists of
-%files; sorting criteria is now based on keywords (instead of 4 integer
-%options); reports shows what functions were profiled as well as what
-%profile file was referenced; output format has been improved.
-%
-%\end{description}
-
-
-\section{Instant User's Manual \label{profile-instant}}
-
-This section is provided for users that ``don't want to read the
-manual.'' It provides a very brief overview, and allows a user to
-rapidly perform profiling on an existing application.
-
-To profile an application with a main entry point of \function{foo()},
-you would add the following to your module:
-
-\begin{verbatim}
-import cProfile
-cProfile.run('foo()')
-\end{verbatim}
-
-(Use \module{profile} instead of \module{cProfile} if the latter is not
-available on your system.)
-
-The above action would cause \function{foo()} to be run, and a series of
-informative lines (the profile) to be printed. The above approach is
-most useful when working with the interpreter. If you would like to
-save the results of a profile into a file for later examination, you
-can supply a file name as the second argument to the \function{run()}
-function:
-
-\begin{verbatim}
-import cProfile
-cProfile.run('foo()', 'fooprof')
-\end{verbatim}
-
-The file \file{cProfile.py} can also be invoked as
-a script to profile another script. For example:
-
-\begin{verbatim}
-python -m cProfile myscript.py
-\end{verbatim}
-
-\file{cProfile.py} accepts two optional arguments on the command line:
-
-\begin{verbatim}
-cProfile.py [-o output_file] [-s sort_order]
-\end{verbatim}
-
-\programopt{-s} only applies to standard output (\programopt{-o} is
-not supplied). Look in the \class{Stats} documentation for valid sort
-values.
-
-When you wish to review the profile, you should use the methods in the
-\module{pstats} module. Typically you would load the statistics data as
-follows:
-
-\begin{verbatim}
-import pstats
-p = pstats.Stats('fooprof')
-\end{verbatim}
-
-The class \class{Stats} (the above code just created an instance of
-this class) has a variety of methods for manipulating and printing the
-data that was just read into \code{p}. When you ran
-\function{cProfile.run()} above, what was printed was the result of three
-method calls:
-
-\begin{verbatim}
-p.strip_dirs().sort_stats(-1).print_stats()
-\end{verbatim}
-
-The first method removed the extraneous path from all the module
-names. The second method sorted all the entries according to the
-standard module/line/name string that is printed.
-%(this is to comply with the semantics of the old profiler).
-The third method printed out
-all the statistics. You might try the following sort calls:
-
-\begin{verbatim}
-p.sort_stats('name')
-p.print_stats()
-\end{verbatim}
-
-The first call will actually sort the list by function name, and the
-second call will print out the statistics. The following are some
-interesting calls to experiment with:
-
-\begin{verbatim}
-p.sort_stats('cumulative').print_stats(10)
-\end{verbatim}
-
-This sorts the profile by cumulative time in a function, and then only
-prints the ten most significant lines. If you want to understand what
-algorithms are taking time, the above line is what you would use.
-
-If you were looking to see what functions were looping a lot, and
-taking a lot of time, you would do:
-
-\begin{verbatim}
-p.sort_stats('time').print_stats(10)
-\end{verbatim}
-
-to sort according to time spent within each function, and then print
-the statistics for the top ten functions.
-
-You might also try:
-
-\begin{verbatim}
-p.sort_stats('file').print_stats('__init__')
-\end{verbatim}
-
-This will sort all the statistics by file name, and then print out
-statistics for only the class init methods (since they are spelled
-with \code{__init__} in them). As one final example, you could try:
-
-\begin{verbatim}
-p.sort_stats('time', 'cum').print_stats(.5, 'init')
-\end{verbatim}
-
-This line sorts statistics with a primary key of time, and a secondary
-key of cumulative time, and then prints out some of the statistics.
-To be specific, the list is first culled down to 50\% (re: \samp{.5})
-of its original size, then only lines containing \code{init} are
-maintained, and that sub-sub-list is printed.
-
-If you wondered what functions called the above functions, you could
-now (\code{p} is still sorted according to the last criteria) do:
-
-\begin{verbatim}
-p.print_callers(.5, 'init')
-\end{verbatim}
-
-and you would get a list of callers for each of the listed functions.
-
-If you want more functionality, you're going to have to read the
-manual, or guess what the following functions do:
-
-\begin{verbatim}
-p.print_callees()
-p.add('fooprof')
-\end{verbatim}
-
-Invoked as a script, the \module{pstats} module is a statistics
-browser for reading and examining profile dumps. It has a simple
-line-oriented interface (implemented using \refmodule{cmd}) and
-interactive help.
-
-\section{What Is Deterministic Profiling?}
-\nodename{Deterministic Profiling}
-
-\dfn{Deterministic profiling} is meant to reflect the fact that all
-\emph{function call}, \emph{function return}, and \emph{exception} events
-are monitored, and precise timings are made for the intervals between
-these events (during which time the user's code is executing). In
-contrast, \dfn{statistical profiling} (which is not done by this
-module) randomly samples the effective instruction pointer, and
-deduces where time is being spent. The latter technique traditionally
-involves less overhead (as the code does not need to be instrumented),
-but provides only relative indications of where time is being spent.
-
-In Python, since there is an interpreter active during execution, the
-presence of instrumented code is not required to do deterministic
-profiling. Python automatically provides a \dfn{hook} (optional
-callback) for each event. In addition, the interpreted nature of
-Python tends to add so much overhead to execution, that deterministic
-profiling tends to only add small processing overhead in typical
-applications. The result is that deterministic profiling is not that
-expensive, yet provides extensive run time statistics about the
-execution of a Python program.
-
-Call count statistics can be used to identify bugs in code (surprising
-counts), and to identify possible inline-expansion points (high call
-counts). Internal time statistics can be used to identify ``hot
-loops'' that should be carefully optimized. Cumulative time
-statistics should be used to identify high level errors in the
-selection of algorithms. Note that the unusual handling of cumulative
-times in this profiler allows statistics for recursive implementations
-of algorithms to be directly compared to iterative implementations.
-
-
-\section{Reference Manual -- \module{profile} and \module{cProfile}}
-
-\declaremodule{standard}{profile}
-\declaremodule{standard}{cProfile}
-\modulesynopsis{Python profiler}
-
-
-
-The primary entry point for the profiler is the global function
-\function{profile.run()} (resp. \function{cProfile.run()}).
-It is typically used to create any profile
-information. The reports are formatted and printed using methods of
-the class \class{pstats.Stats}. The following is a description of all
-of these standard entry points and functions. For a more in-depth
-view of some of the code, consider reading the later section on
-Profiler Extensions, which includes discussion of how to derive
-``better'' profilers from the classes presented, or reading the source
-code for these modules.
-
-\begin{funcdesc}{run}{command\optional{, filename}}
-
-This function takes a single argument that can be passed to the
-\function{exec()} function, and an optional file name. In all cases this
-routine attempts to \function{exec()} its first argument, and gather profiling
-statistics from the execution. If no file name is present, then this
-function automatically prints a simple profiling report, sorted by the
-standard name string (file/line/function-name) that is presented in
-each line. The following is a typical output from such a call:
-
-\begin{verbatim}
- 2706 function calls (2004 primitive calls) in 4.504 CPU seconds
-
-Ordered by: standard name
-
-ncalls tottime percall cumtime percall filename:lineno(function)
- 2 0.006 0.003 0.953 0.477 pobject.py:75(save_objects)
- 43/3 0.533 0.012 0.749 0.250 pobject.py:99(evaluate)
- ...
-\end{verbatim}
-
-The first line indicates that 2706 calls were
-monitored. Of those calls, 2004 were \dfn{primitive}. We define
-\dfn{primitive} to mean that the call was not induced via recursion.
-The next line: \code{Ordered by:\ standard name}, indicates that
-the text string in the far right column was used to sort the output.
-The column headings include:
-
-\begin{description}
-
-\item[ncalls ]
-for the number of calls,
-
-\item[tottime ]
-for the total time spent in the given function (and excluding time
-made in calls to sub-functions),
-
-\item[percall ]
-is the quotient of \code{tottime} divided by \code{ncalls}
-
-\item[cumtime ]
-is the total time spent in this and all subfunctions (from invocation
-till exit). This figure is accurate \emph{even} for recursive
-functions.
-
-\item[percall ]
-is the quotient of \code{cumtime} divided by primitive calls
-
-\item[filename:lineno(function) ]
-provides the respective data of each function
-
-\end{description}
-
-When there are two numbers in the first column (for example,
-\samp{43/3}), then the latter is the number of primitive calls, and
-the former is the actual number of calls. Note that when the function
-does not recurse, these two values are the same, and only the single
-figure is printed.
-
-\end{funcdesc}
-
-\begin{funcdesc}{runctx}{command, globals, locals\optional{, filename}}
-This function is similar to \function{run()}, with added
-arguments to supply the globals and locals dictionaries for the
-\var{command} string.
-\end{funcdesc}
-
-Analysis of the profiler data is done using the \class{Stats} class.
-
-\note{The \class{Stats} class is defined in the \module{pstats} module.}
-
-% now switch modules....
-% (This \stmodindex use may be hard to change ;-( )
-\stmodindex{pstats}
-
-\begin{classdesc}{Stats}{filename\optional{, stream=sys.stdout\optional{, \moreargs}}}
-This class constructor creates an instance of a ``statistics object''
-from a \var{filename} (or set of filenames). \class{Stats} objects are
-manipulated by methods, in order to print useful reports. You may specify
-an alternate output stream by giving the keyword argument, \code{stream}.
-
-The file selected by the above constructor must have been created by the
-corresponding version of \module{profile} or \module{cProfile}. To be
-specific, there is \emph{no} file compatibility guaranteed with future
-versions of this profiler, and there is no compatibility with files produced
-by other profilers.
-%(such as the old system profiler).
-
-If several files are provided, all the statistics for identical
-functions will be coalesced, so that an overall view of several
-processes can be considered in a single report. If additional files
-need to be combined with data in an existing \class{Stats} object, the
-\method{add()} method can be used.
-
-\versionchanged[The \var{stream} parameter was added]{2.5}
-\end{classdesc}
-
-
-\subsection{The \class{Stats} Class \label{profile-stats}}
-
-\class{Stats} objects have the following methods:
-
-\begin{methoddesc}[Stats]{strip_dirs}{}
-This method for the \class{Stats} class removes all leading path
-information from file names. It is very useful in reducing the size
-of the printout to fit within (close to) 80 columns. This method
-modifies the object, and the stripped information is lost. After
-performing a strip operation, the object is considered to have its
-entries in a ``random'' order, as it was just after object
-initialization and loading. If \method{strip_dirs()} causes two
-function names to be indistinguishable (they are on the same
-line of the same filename, and have the same function name), then the
-statistics for these two entries are accumulated into a single entry.
-\end{methoddesc}
-
-
-\begin{methoddesc}[Stats]{add}{filename\optional{, \moreargs}}
-This method of the \class{Stats} class accumulates additional
-profiling information into the current profiling object. Its
-arguments should refer to filenames created by the corresponding
-version of \function{profile.run()} or \function{cProfile.run()}.
-Statistics for identically named
-(re: file, line, name) functions are automatically accumulated into
-single function statistics.
-\end{methoddesc}
-
-\begin{methoddesc}[Stats]{dump_stats}{filename}
-Save the data loaded into the \class{Stats} object to a file named
-\var{filename}. The file is created if it does not exist, and is
-overwritten if it already exists. This is equivalent to the method of
-the same name on the \class{profile.Profile} and
-\class{cProfile.Profile} classes.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[Stats]{sort_stats}{key\optional{, \moreargs}}
-This method modifies the \class{Stats} object by sorting it according
-to the supplied criteria. The argument is typically a string
-identifying the basis of a sort (example: \code{'time'} or
-\code{'name'}).
-
-When more than one key is provided, then additional keys are used as
-secondary criteria when there is equality in all keys selected
-before them. For example, \code{sort_stats('name', 'file')} will sort
-all the entries according to their function name, and resolve all ties
-(identical function names) by sorting by file name.
-
-Abbreviations can be used for any key names, as long as the
-abbreviation is unambiguous. The following are the keys currently
-defined:
-
-\begin{tableii}{l|l}{code}{Valid Arg}{Meaning}
- \lineii{'calls'}{call count}
- \lineii{'cumulative'}{cumulative time}
- \lineii{'file'}{file name}
- \lineii{'module'}{file name}
- \lineii{'pcalls'}{primitive call count}
- \lineii{'line'}{line number}
- \lineii{'name'}{function name}
- \lineii{'nfl'}{name/file/line}
- \lineii{'stdname'}{standard name}
- \lineii{'time'}{internal time}
-\end{tableii}
-
-Note that all sorts on statistics are in descending order (placing
-most time consuming items first), where as name, file, and line number
-searches are in ascending order (alphabetical). The subtle
-distinction between \code{'nfl'} and \code{'stdname'} is that the
-standard name is a sort of the name as printed, which means that the
-embedded line numbers get compared in an odd way. For example, lines
-3, 20, and 40 would (if the file names were the same) appear in the
-string order 20, 3 and 40. In contrast, \code{'nfl'} does a numeric
-compare of the line numbers. In fact, \code{sort_stats('nfl')} is the
-same as \code{sort_stats('name', 'file', 'line')}.
-
-%For compatibility with the old profiler,
-For backward-compatibility reasons, the numeric arguments
-\code{-1}, \code{0}, \code{1}, and \code{2} are permitted. They are
-interpreted as \code{'stdname'}, \code{'calls'}, \code{'time'}, and
-\code{'cumulative'} respectively. If this old style format (numeric)
-is used, only one sort key (the numeric key) will be used, and
-additional arguments will be silently ignored.
-\end{methoddesc}
-
-
-\begin{methoddesc}[Stats]{reverse_order}{}
-This method for the \class{Stats} class reverses the ordering of the basic
-list within the object. %This method is provided primarily for
-%compatibility with the old profiler.
-Note that by default ascending vs descending order is properly selected
-based on the sort key of choice.
-\end{methoddesc}
-
-\begin{methoddesc}[Stats]{print_stats}{\optional{restriction, \moreargs}}
-This method for the \class{Stats} class prints out a report as described
-in the \function{profile.run()} definition.
-
-The order of the printing is based on the last \method{sort_stats()}
-operation done on the object (subject to caveats in \method{add()} and
-\method{strip_dirs()}).
-
-The arguments provided (if any) can be used to limit the list down to
-the significant entries. Initially, the list is taken to be the
-complete set of profiled functions. Each restriction is either an
-integer (to select a count of lines), or a decimal fraction between
-0.0 and 1.0 inclusive (to select a percentage of lines), or a regular
-expression (to pattern match the standard name that is printed; as of
-Python 1.5b1, this uses the Perl-style regular expression syntax
-defined by the \refmodule{re} module). If several restrictions are
-provided, then they are applied sequentially. For example:
-
-\begin{verbatim}
-print_stats(.1, 'foo:')
-\end{verbatim}
-
-would first limit the printing to first 10\% of list, and then only
-print functions that were part of filename \file{.*foo:}. In
-contrast, the command:
-
-\begin{verbatim}
-print_stats('foo:', .1)
-\end{verbatim}
-
-would limit the list to all functions having file names \file{.*foo:},
-and then proceed to only print the first 10\% of them.
-\end{methoddesc}
-
-
-\begin{methoddesc}[Stats]{print_callers}{\optional{restriction, \moreargs}}
-This method for the \class{Stats} class prints a list of all functions
-that called each function in the profiled database. The ordering is
-identical to that provided by \method{print_stats()}, and the definition
-of the restricting argument is also identical. Each caller is reported on
-its own line. The format differs slightly depending on the profiler that
-produced the stats:
-
-\begin{itemize}
-\item With \module{profile}, a number is shown in parentheses after each
- caller to show how many times this specific call was made. For
- convenience, a second non-parenthesized number repeats the cumulative
- time spent in the function at the right.
-
-\item With \module{cProfile}, each caller is preceeded by three numbers:
- the number of times this specific call was made, and the total and
- cumulative times spent in the current function while it was invoked by
- this specific caller.
-\end{itemize}
-\end{methoddesc}
-
-\begin{methoddesc}[Stats]{print_callees}{\optional{restriction, \moreargs}}
-This method for the \class{Stats} class prints a list of all function
-that were called by the indicated function. Aside from this reversal
-of direction of calls (re: called vs was called by), the arguments and
-ordering are identical to the \method{print_callers()} method.
-\end{methoddesc}
-
-
-\section{Limitations \label{profile-limits}}
-
-One limitation has to do with accuracy of timing information.
-There is a fundamental problem with deterministic profilers involving
-accuracy. The most obvious restriction is that the underlying ``clock''
-is only ticking at a rate (typically) of about .001 seconds. Hence no
-measurements will be more accurate than the underlying clock. If
-enough measurements are taken, then the ``error'' will tend to average
-out. Unfortunately, removing this first error induces a second source
-of error.
-
-The second problem is that it ``takes a while'' from when an event is
-dispatched until the profiler's call to get the time actually
-\emph{gets} the state of the clock. Similarly, there is a certain lag
-when exiting the profiler event handler from the time that the clock's
-value was obtained (and then squirreled away), until the user's code
-is once again executing. As a result, functions that are called many
-times, or call many functions, will typically accumulate this error.
-The error that accumulates in this fashion is typically less than the
-accuracy of the clock (less than one clock tick), but it
-\emph{can} accumulate and become very significant.
-
-The problem is more important with \module{profile} than with the
-lower-overhead \module{cProfile}. For this reason, \module{profile}
-provides a means of calibrating itself for a given platform so that
-this error can be probabilistically (on the average) removed.
-After the profiler is calibrated, it will be more accurate (in a least
-square sense), but it will sometimes produce negative numbers (when
-call counts are exceptionally low, and the gods of probability work
-against you :-). ) Do \emph{not} be alarmed by negative numbers in
-the profile. They should \emph{only} appear if you have calibrated
-your profiler, and the results are actually better than without
-calibration.
-
-
-\section{Calibration \label{profile-calibration}}
-
-The profiler of the \module{profile} module subtracts a constant from each
-event handling time to compensate for the overhead of calling the time
-function, and socking away the results. By default, the constant is 0.
-The following procedure can
-be used to obtain a better constant for a given platform (see discussion
-in section Limitations above).
-
-\begin{verbatim}
-import profile
-pr = profile.Profile()
-for i in range(5):
- print pr.calibrate(10000)
-\end{verbatim}
-
-The method executes the number of Python calls given by the argument,
-directly and again under the profiler, measuring the time for both.
-It then computes the hidden overhead per profiler event, and returns
-that as a float. For example, on an 800 MHz Pentium running
-Windows 2000, and using Python's time.clock() as the timer,
-the magical number is about 12.5e-6.
-
-The object of this exercise is to get a fairly consistent result.
-If your computer is \emph{very} fast, or your timer function has poor
-resolution, you might have to pass 100000, or even 1000000, to get
-consistent results.
-
-When you have a consistent answer,
-there are three ways you can use it:\footnote{Prior to Python 2.2, it
- was necessary to edit the profiler source code to embed the bias as
- a literal number. You still can, but that method is no longer
- described, because no longer needed.}
-
-\begin{verbatim}
-import profile
-
-# 1. Apply computed bias to all Profile instances created hereafter.
-profile.Profile.bias = your_computed_bias
-
-# 2. Apply computed bias to a specific Profile instance.
-pr = profile.Profile()
-pr.bias = your_computed_bias
-
-# 3. Specify computed bias in instance constructor.
-pr = profile.Profile(bias=your_computed_bias)
-\end{verbatim}
-
-If you have a choice, you are better off choosing a smaller constant, and
-then your results will ``less often'' show up as negative in profile
-statistics.
-
-
-\section{Extensions --- Deriving Better Profilers}
-\nodename{Profiler Extensions}
-
-The \class{Profile} class of both modules, \module{profile} and
-\module{cProfile}, were written so that
-derived classes could be developed to extend the profiler. The details
-are not described here, as doing this successfully requires an expert
-understanding of how the \class{Profile} class works internally. Study
-the source code of the module carefully if you want to
-pursue this.
-
-If all you want to do is change how current time is determined (for
-example, to force use of wall-clock time or elapsed process time),
-pass the timing function you want to the \class{Profile} class
-constructor:
-
-\begin{verbatim}
-pr = profile.Profile(your_time_func)
-\end{verbatim}
-
-The resulting profiler will then call \function{your_time_func()}.
-
-\begin{description}
-\item[\class{profile.Profile}]
-\function{your_time_func()} should return a single number, or a list of
-numbers whose sum is the current time (like what \function{os.times()}
-returns). If the function returns a single time number, or the list of
-returned numbers has length 2, then you will get an especially fast
-version of the dispatch routine.
-
-Be warned that you should calibrate the profiler class for the
-timer function that you choose. For most machines, a timer that
-returns a lone integer value will provide the best results in terms of
-low overhead during profiling. (\function{os.times()} is
-\emph{pretty} bad, as it returns a tuple of floating point values). If
-you want to substitute a better timer in the cleanest fashion,
-derive a class and hardwire a replacement dispatch method that best
-handles your timer call, along with the appropriate calibration
-constant.
-
-\item[\class{cProfile.Profile}]
-\function{your_time_func()} should return a single number. If it returns
-plain integers, you can also invoke the class constructor with a second
-argument specifying the real duration of one unit of time. For example,
-if \function{your_integer_time_func()} returns times measured in thousands
-of seconds, you would constuct the \class{Profile} instance as follows:
-
-\begin{verbatim}
-pr = profile.Profile(your_integer_time_func, 0.001)
-\end{verbatim}
-
-As the \module{cProfile.Profile} class cannot be calibrated, custom
-timer functions should be used with care and should be as fast as
-possible. For the best results with a custom timer, it might be
-necessary to hard-code it in the C source of the internal
-\module{_lsprof} module.
-
-\end{description}
diff --git a/Doc/lib/libpty.tex b/Doc/lib/libpty.tex
deleted file mode 100644
index 2db7503..0000000
--- a/Doc/lib/libpty.tex
+++ /dev/null
@@ -1,44 +0,0 @@
-\section{\module{pty} ---
- Pseudo-terminal utilities}
-\declaremodule{standard}{pty}
- \platform{IRIX, Linux}
-\modulesynopsis{Pseudo-Terminal Handling for SGI and Linux.}
-\moduleauthor{Steen Lumholt}{}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-
-
-The \module{pty} module defines operations for handling the
-pseudo-terminal concept: starting another process and being able to
-write to and read from its controlling terminal programmatically.
-
-Because pseudo-terminal handling is highly platform dependant, there
-is code to do it only for SGI and Linux. (The Linux code is supposed
-to work on other platforms, but hasn't been tested yet.)
-
-The \module{pty} module defines the following functions:
-
-\begin{funcdesc}{fork}{}
-Fork. Connect the child's controlling terminal to a pseudo-terminal.
-Return value is \code{(\var{pid}, \var{fd})}. Note that the child
-gets \var{pid} 0, and the \var{fd} is \emph{invalid}. The parent's
-return value is the \var{pid} of the child, and \var{fd} is a file
-descriptor connected to the child's controlling terminal (and also
-to the child's standard input and output).
-\end{funcdesc}
-
-\begin{funcdesc}{openpty}{}
-Open a new pseudo-terminal pair, using \function{os.openpty()} if
-possible, or emulation code for SGI and generic \UNIX{} systems.
-Return a pair of file descriptors \code{(\var{master}, \var{slave})},
-for the master and the slave end, respectively.
-\end{funcdesc}
-
-\begin{funcdesc}{spawn}{argv\optional{, master_read\optional{, stdin_read}}}
-Spawn a process, and connect its controlling terminal with the current
-process's standard io. This is often used to baffle programs which
-insist on reading from the controlling terminal.
-
-The functions \var{master_read} and \var{stdin_read} should be
-functions which read from a file-descriptor. The defaults try to read
-1024 bytes each time they are called.
-\end{funcdesc}
diff --git a/Doc/lib/libpwd.tex b/Doc/lib/libpwd.tex
deleted file mode 100644
index 0c74d26..0000000
--- a/Doc/lib/libpwd.tex
+++ /dev/null
@@ -1,57 +0,0 @@
-\section{\module{pwd} ---
- The password database}
-
-\declaremodule{builtin}{pwd}
- \platform{Unix}
-\modulesynopsis{The password database (\function{getpwnam()} and friends).}
-
-This module provides access to the \UNIX{} user account and password
-database. It is available on all \UNIX{} versions.
-
-Password database entries are reported as a tuple-like object, whose
-attributes correspond to the members of the \code{passwd} structure
-(Attribute field below, see \code{<pwd.h>}):
-
-\begin{tableiii}{r|l|l}{textrm}{Index}{Attribute}{Meaning}
- \lineiii{0}{\code{pw_name}}{Login name}
- \lineiii{1}{\code{pw_passwd}}{Optional encrypted password}
- \lineiii{2}{\code{pw_uid}}{Numerical user ID}
- \lineiii{3}{\code{pw_gid}}{Numerical group ID}
- \lineiii{4}{\code{pw_gecos}}{User name or comment field}
- \lineiii{5}{\code{pw_dir}}{User home directory}
- \lineiii{6}{\code{pw_shell}}{User command interpreter}
-\end{tableiii}
-
-The uid and gid items are integers, all others are strings.
-\exception{KeyError} is raised if the entry asked for cannot be found.
-
-\note{In traditional \UNIX{} the field \code{pw_passwd} usually
-contains a password encrypted with a DES derived algorithm (see module
-\refmodule{crypt}\refbimodindex{crypt}). However most modern unices
-use a so-called \emph{shadow password} system. On those unices the
-\var{pw_passwd} field only contains an asterisk (\code{'*'}) or the
-letter \character{x} where the encrypted password is stored in a file
-\file{/etc/shadow} which is not world readable. Whether the \var{pw_passwd}
-field contains anything useful is system-dependent. If available, the
-\module{spwd} module should be used where access to the encrypted password
-is required.}
-
-It defines the following items:
-
-\begin{funcdesc}{getpwuid}{uid}
-Return the password database entry for the given numeric user ID.
-\end{funcdesc}
-
-\begin{funcdesc}{getpwnam}{name}
-Return the password database entry for the given user name.
-\end{funcdesc}
-
-\begin{funcdesc}{getpwall}{}
-Return a list of all available password database entries, in arbitrary order.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{grp}{An interface to the group database, similar to this.}
- \seemodule{spwd}{An interface to the shadow password database, similar to this.}
-\end{seealso}
diff --git a/Doc/lib/libpyclbr.tex b/Doc/lib/libpyclbr.tex
deleted file mode 100644
index 0dedb9e..0000000
--- a/Doc/lib/libpyclbr.tex
+++ /dev/null
@@ -1,102 +0,0 @@
-\section{\module{pyclbr} ---
- Python class browser support}
-
-\declaremodule{standard}{pyclbr}
-\modulesynopsis{Supports information extraction for a Python class
- browser.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-The \module{pyclbr} can be used to determine some limited information
-about the classes, methods and top-level functions
-defined in a module. The information
-provided is sufficient to implement a traditional three-pane class
-browser. The information is extracted from the source code rather
-than by importing the module, so this module is safe to use with
-untrusted source code. This restriction makes it impossible to use
-this module with modules not implemented in Python, including many
-standard and optional extension modules.
-
-
-\begin{funcdesc}{readmodule}{module\optional{, path}}
- % The 'inpackage' parameter appears to be for internal use only....
- Read a module and return a dictionary mapping class names to class
- descriptor objects. The parameter \var{module} should be the name
- of a module as a string; it may be the name of a module within a
- package. The \var{path} parameter should be a sequence, and is used
- to augment the value of \code{sys.path}, which is used to locate
- module source code.
-\end{funcdesc}
-
-\begin{funcdesc}{readmodule_ex}{module\optional{, path}}
- % The 'inpackage' parameter appears to be for internal use only....
- Like \function{readmodule()}, but the returned dictionary, in addition
- to mapping class names to class descriptor objects, also maps
- top-level function names to function descriptor objects. Moreover, if
- the module being read is a package, the key \code{'__path__'} in the
- returned dictionary has as its value a list which contains the package
- search path.
-\end{funcdesc}
-
-
-\subsection{Class Descriptor Objects \label{pyclbr-class-objects}}
-
-The class descriptor objects used as values in the dictionary returned
-by \function{readmodule()} and \function{readmodule_ex()}
-provide the following data members:
-
-
-\begin{memberdesc}[class descriptor]{module}
- The name of the module defining the class described by the class
- descriptor.
-\end{memberdesc}
-
-\begin{memberdesc}[class descriptor]{name}
- The name of the class.
-\end{memberdesc}
-
-\begin{memberdesc}[class descriptor]{super}
- A list of class descriptors which describe the immediate base
- classes of the class being described. Classes which are named as
- superclasses but which are not discoverable by
- \function{readmodule()} are listed as a string with the class name
- instead of class descriptors.
-\end{memberdesc}
-
-\begin{memberdesc}[class descriptor]{methods}
- A dictionary mapping method names to line numbers.
-\end{memberdesc}
-
-\begin{memberdesc}[class descriptor]{file}
- Name of the file containing the \code{class} statement defining the class.
-\end{memberdesc}
-
-\begin{memberdesc}[class descriptor]{lineno}
- The line number of the \code{class} statement within the file named by
- \member{file}.
-\end{memberdesc}
-
-\subsection{Function Descriptor Objects \label{pyclbr-function-objects}}
-
-The function descriptor objects used as values in the dictionary returned
-by \function{readmodule_ex()} provide the following data members:
-
-
-\begin{memberdesc}[function descriptor]{module}
- The name of the module defining the function described by the function
- descriptor.
-\end{memberdesc}
-
-\begin{memberdesc}[function descriptor]{name}
- The name of the function.
-\end{memberdesc}
-
-\begin{memberdesc}[function descriptor]{file}
- Name of the file containing the \code{def} statement defining the function.
-\end{memberdesc}
-
-\begin{memberdesc}[function descriptor]{lineno}
- The line number of the \code{def} statement within the file named by
- \member{file}.
-\end{memberdesc}
-
diff --git a/Doc/lib/libpycompile.tex b/Doc/lib/libpycompile.tex
deleted file mode 100644
index 85f0aaa..0000000
--- a/Doc/lib/libpycompile.tex
+++ /dev/null
@@ -1,53 +0,0 @@
-\section{\module{py_compile} ---
- Compile Python source files}
-
-% Documentation based on module docstrings, by Fred L. Drake, Jr.
-% <fdrake@acm.org>
-
-\declaremodule[pycompile]{standard}{py_compile}
-
-\modulesynopsis{Compile Python source files to byte-code files.}
-
-
-\indexii{file}{byte-code}
-The \module{py_compile} module provides a function to generate a
-byte-code file from a source file, and another function used when the
-module source file is invoked as a script.
-
-Though not often needed, this function can be useful when installing
-modules for shared use, especially if some of the users may not have
-permission to write the byte-code cache files in the directory
-containing the source code.
-
-\begin{excdesc}{PyCompileError}
-Exception raised when an error occurs while attempting to compile the file.
-\end{excdesc}
-
-\begin{funcdesc}{compile}{file\optional{, cfile\optional{, dfile\optional{, doraise}}}}
- Compile a source file to byte-code and write out the byte-code cache
- file. The source code is loaded from the file name \var{file}. The
- byte-code is written to \var{cfile}, which defaults to \var{file}
- \code{+} \code{'c'} (\code{'o'} if optimization is enabled in the
- current interpreter). If \var{dfile} is specified, it is used as
- the name of the source file in error messages instead of \var{file}.
- If \var{doraise} is true, a \exception{PyCompileError} is raised when
- an error is encountered while compiling \var{file}. If \var{doraise}
- is false (the default), an error string is written to \code{sys.stderr},
- but no exception is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{main}{\optional{args}}
- Compile several source files. The files named in \var{args} (or on
- the command line, if \var{args} is not specified) are compiled and
- the resulting bytecode is cached in the normal manner. This
- function does not search a directory structure to locate source
- files; it only compiles files named explicitly.
-\end{funcdesc}
-
-When this module is run as a script, the \function{main()} is used to
-compile all the files named on the command line.
-
-\begin{seealso}
- \seemodule{compileall}{Utilities to compile all Python source files
- in a directory tree.}
-\end{seealso}
diff --git a/Doc/lib/libpydoc.tex b/Doc/lib/libpydoc.tex
deleted file mode 100644
index bb74df6..0000000
--- a/Doc/lib/libpydoc.tex
+++ /dev/null
@@ -1,67 +0,0 @@
-\section{\module{pydoc} ---
- Documentation generator and online help system}
-
-\declaremodule{standard}{pydoc}
-\modulesynopsis{Documentation generator and online help system.}
-\moduleauthor{Ka-Ping Yee}{ping@lfw.org}
-\sectionauthor{Ka-Ping Yee}{ping@lfw.org}
-
-\versionadded{2.1}
-\index{documentation!generation}
-\index{documentation!online}
-\index{help!online}
-
-The \module{pydoc} module automatically generates documentation from
-Python modules. The documentation can be presented as pages of text
-on the console, served to a Web browser, or saved to HTML files.
-
-The built-in function \function{help()} invokes the online help system
-in the interactive interpreter, which uses \module{pydoc} to generate
-its documentation as text on the console. The same text documentation
-can also be viewed from outside the Python interpreter by running
-\program{pydoc} as a script at the operating system's command prompt.
-For example, running
-
-\begin{verbatim}
-pydoc sys
-\end{verbatim}
-
-at a shell prompt will display documentation on the \refmodule{sys}
-module, in a style similar to the manual pages shown by the \UNIX{}
-\program{man} command. The argument to \program{pydoc} can be the name
-of a function, module, or package, or a dotted reference to a class,
-method, or function within a module or module in a package. If the
-argument to \program{pydoc} looks like a path (that is, it contains the
-path separator for your operating system, such as a slash in \UNIX),
-and refers to an existing Python source file, then documentation is
-produced for that file.
-
-Specifying a \programopt{-w} flag before the argument will cause HTML
-documentation to be written out to a file in the current directory,
-instead of displaying text on the console.
-
-Specifying a \programopt{-k} flag before the argument will search the
-synopsis lines of all available modules for the keyword given as the
-argument, again in a manner similar to the \UNIX{} \program{man}
-command. The synopsis line of a module is the first line of its
-documentation string.
-
-You can also use \program{pydoc} to start an HTTP server on the local
-machine that will serve documentation to visiting Web browsers.
-\program{pydoc} \programopt{-p 1234} will start a HTTP server on port
-1234, allowing you to browse the documentation at
-\code{http://localhost:1234/} in your preferred Web browser.
-\program{pydoc} \programopt{-g} will start the server and additionally
-bring up a small \refmodule{Tkinter}-based graphical interface to help
-you search for documentation pages.
-
-When \program{pydoc} generates documentation, it uses the current
-environment and path to locate modules. Thus, invoking
-\program{pydoc} \programopt{spam} documents precisely the version of
-the module you would get if you started the Python interpreter and
-typed \samp{import spam}.
-
-Module docs for core modules are assumed to reside in
-{}\url{http://www.python.org/doc/current/lib/}. This can be overridden by
-setting the \envvar{PYTHONDOCS} environment variable to a different URL or
-to a local directory containing the Library Reference Manual pages.
diff --git a/Doc/lib/libpyexpat.tex b/Doc/lib/libpyexpat.tex
deleted file mode 100644
index ed0bf6a..0000000
--- a/Doc/lib/libpyexpat.tex
+++ /dev/null
@@ -1,766 +0,0 @@
-\section{\module{xml.parsers.expat} ---
- Fast XML parsing using Expat}
-
-% Markup notes:
-%
-% Many of the attributes of the XMLParser objects are callbacks.
-% Since signature information must be presented, these are described
-% using the methoddesc environment. Since they are attributes which
-% are set by client code, in-text references to these attributes
-% should be marked using the \member macro and should not include the
-% parentheses used when marking functions and methods.
-
-\declaremodule{standard}{xml.parsers.expat}
-\modulesynopsis{An interface to the Expat non-validating XML parser.}
-\moduleauthor{Paul Prescod}{paul@prescod.net}
-
-\versionadded{2.0}
-
-The \module{xml.parsers.expat} module is a Python interface to the
-Expat\index{Expat} non-validating XML parser.
-The module provides a single extension type, \class{xmlparser}, that
-represents the current state of an XML parser. After an
-\class{xmlparser} object has been created, various attributes of the object
-can be set to handler functions. When an XML document is then fed to
-the parser, the handler functions are called for the character data
-and markup in the XML document.
-
-This module uses the \module{pyexpat}\refbimodindex{pyexpat} module to
-provide access to the Expat parser. Direct use of the
-\module{pyexpat} module is deprecated.
-
-This module provides one exception and one type object:
-
-\begin{excdesc}{ExpatError}
- The exception raised when Expat reports an error. See section
- \ref{expaterror-objects}, ``ExpatError Exceptions,'' for more
- information on interpreting Expat errors.
-\end{excdesc}
-
-\begin{excdesc}{error}
- Alias for \exception{ExpatError}.
-\end{excdesc}
-
-\begin{datadesc}{XMLParserType}
- The type of the return values from the \function{ParserCreate()}
- function.
-\end{datadesc}
-
-
-The \module{xml.parsers.expat} module contains two functions:
-
-\begin{funcdesc}{ErrorString}{errno}
-Returns an explanatory string for a given error number \var{errno}.
-\end{funcdesc}
-
-\begin{funcdesc}{ParserCreate}{\optional{encoding\optional{,
- namespace_separator}}}
-Creates and returns a new \class{xmlparser} object.
-\var{encoding}, if specified, must be a string naming the encoding
-used by the XML data. Expat doesn't support as many encodings as
-Python does, and its repertoire of encodings can't be extended; it
-supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII. If
-\var{encoding} is given it will override the implicit or explicit
-encoding of the document.
-
-Expat can optionally do XML namespace processing for you, enabled by
-providing a value for \var{namespace_separator}. The value must be a
-one-character string; a \exception{ValueError} will be raised if the
-string has an illegal length (\code{None} is considered the same as
-omission). When namespace processing is enabled, element type names
-and attribute names that belong to a namespace will be expanded. The
-element name passed to the element handlers
-\member{StartElementHandler} and \member{EndElementHandler}
-will be the concatenation of the namespace URI, the namespace
-separator character, and the local part of the name. If the namespace
-separator is a zero byte (\code{chr(0)}) then the namespace URI and
-the local part will be concatenated without any separator.
-
-For example, if \var{namespace_separator} is set to a space character
-(\character{ }) and the following document is parsed:
-
-\begin{verbatim}
-<?xml version="1.0"?>
-<root xmlns = "http://default-namespace.org/"
- xmlns:py = "http://www.python.org/ns/">
- <py:elem1 />
- <elem2 xmlns="" />
-</root>
-\end{verbatim}
-
-\member{StartElementHandler} will receive the following strings
-for each element:
-
-\begin{verbatim}
-http://default-namespace.org/ root
-http://www.python.org/ns/ elem1
-elem2
-\end{verbatim}
-\end{funcdesc}
-
-
-\begin{seealso}
- \seetitle[http://www.libexpat.org/]{The Expat XML Parser}
- {Home page of the Expat project.}
-\end{seealso}
-
-
-\subsection{XMLParser Objects \label{xmlparser-objects}}
-
-\class{xmlparser} objects have the following methods:
-
-\begin{methoddesc}[xmlparser]{Parse}{data\optional{, isfinal}}
-Parses the contents of the string \var{data}, calling the appropriate
-handler functions to process the parsed data. \var{isfinal} must be
-true on the final call to this method. \var{data} can be the empty
-string at any time.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{ParseFile}{file}
-Parse XML data reading from the object \var{file}. \var{file} only
-needs to provide the \method{read(\var{nbytes})} method, returning the
-empty string when there's no more data.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{SetBase}{base}
-Sets the base to be used for resolving relative URIs in system
-identifiers in declarations. Resolving relative identifiers is left
-to the application: this value will be passed through as the
-\var{base} argument to the \function{ExternalEntityRefHandler},
-\function{NotationDeclHandler}, and
-\function{UnparsedEntityDeclHandler} functions.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{GetBase}{}
-Returns a string containing the base set by a previous call to
-\method{SetBase()}, or \code{None} if
-\method{SetBase()} hasn't been called.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{GetInputContext}{}
-Returns the input data that generated the current event as a string.
-The data is in the encoding of the entity which contains the text.
-When called while an event handler is not active, the return value is
-\code{None}.
-\versionadded{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{ExternalEntityParserCreate}{context\optional{,
- encoding}}
-Create a ``child'' parser which can be used to parse an external
-parsed entity referred to by content parsed by the parent parser. The
-\var{context} parameter should be the string passed to the
-\method{ExternalEntityRefHandler()} handler function, described below.
-The child parser is created with the \member{ordered_attributes}
-and \member{specified_attributes} set to the
-values of this parser.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{UseForeignDTD}{\optional{flag}}
-Calling this with a true value for \var{flag} (the default) will cause
-Expat to call the \member{ExternalEntityRefHandler} with
-\constant{None} for all arguments to allow an alternate DTD to be
-loaded. If the document does not contain a document type declaration,
-the \member{ExternalEntityRefHandler} will still be called, but the
-\member{StartDoctypeDeclHandler} and \member{EndDoctypeDeclHandler}
-will not be called.
-
-Passing a false value for \var{flag} will cancel a previous call that
-passed a true value, but otherwise has no effect.
-
-This method can only be called before the \method{Parse()} or
-\method{ParseFile()} methods are called; calling it after either of
-those have been called causes \exception{ExpatError} to be raised with
-the \member{code} attribute set to
-\constant{errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING}.
-
-\versionadded{2.3}
-\end{methoddesc}
-
-
-\class{xmlparser} objects have the following attributes:
-
-\begin{memberdesc}[xmlparser]{buffer_size}
-The size of the buffer used when \member{buffer_text} is true. This
-value cannot be changed at this time.
-\versionadded{2.3}
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{buffer_text}
-Setting this to true causes the \class{xmlparser} object to buffer
-textual content returned by Expat to avoid multiple calls to the
-\method{CharacterDataHandler()} callback whenever possible. This can
-improve performance substantially since Expat normally breaks
-character data into chunks at every line ending. This attribute is
-false by default, and may be changed at any time.
-\versionadded{2.3}
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{buffer_used}
-If \member{buffer_text} is enabled, the number of bytes stored in the
-buffer. These bytes represent UTF-8 encoded text. This attribute has
-no meaningful interpretation when \member{buffer_text} is false.
-\versionadded{2.3}
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{ordered_attributes}
-Setting this attribute to a non-zero integer causes the attributes to
-be reported as a list rather than a dictionary. The attributes are
-presented in the order found in the document text. For each
-attribute, two list entries are presented: the attribute name and the
-attribute value. (Older versions of this module also used this
-format.) By default, this attribute is false; it may be changed at
-any time.
-\versionadded{2.1}
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{specified_attributes}
-If set to a non-zero integer, the parser will report only those
-attributes which were specified in the document instance and not those
-which were derived from attribute declarations. Applications which
-set this need to be especially careful to use what additional
-information is available from the declarations as needed to comply
-with the standards for the behavior of XML processors. By default,
-this attribute is false; it may be changed at any time.
-\versionadded{2.1}
-\end{memberdesc}
-
-The following attributes contain values relating to the most recent
-error encountered by an \class{xmlparser} object, and will only have
-correct values once a call to \method{Parse()} or \method{ParseFile()}
-has raised a \exception{xml.parsers.expat.ExpatError} exception.
-
-\begin{memberdesc}[xmlparser]{ErrorByteIndex}
-Byte index at which an error occurred.
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{ErrorCode}
-Numeric code specifying the problem. This value can be passed to the
-\function{ErrorString()} function, or compared to one of the constants
-defined in the \code{errors} object.
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{ErrorColumnNumber}
-Column number at which an error occurred.
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{ErrorLineNumber}
-Line number at which an error occurred.
-\end{memberdesc}
-
-The following attributes contain values relating to the current parse
-location in an \class{xmlparser} object. During a callback reporting
-a parse event they indicate the location of the first of the sequence
-of characters that generated the event. When called outside of a
-callback, the position indicated will be just past the last parse
-event (regardless of whether there was an associated callback).
-\versionadded{2.4}
-
-\begin{memberdesc}[xmlparser]{CurrentByteIndex}
-Current byte index in the parser input.
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{CurrentColumnNumber}
-Current column number in the parser input.
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{CurrentLineNumber}
-Current line number in the parser input.
-\end{memberdesc}
-
-Here is the list of handlers that can be set. To set a handler on an
-\class{xmlparser} object \var{o}, use
-\code{\var{o}.\var{handlername} = \var{func}}. \var{handlername} must
-be taken from the following list, and \var{func} must be a callable
-object accepting the correct number of arguments. The arguments are
-all strings, unless otherwise stated.
-
-\begin{methoddesc}[xmlparser]{XmlDeclHandler}{version, encoding, standalone}
-Called when the XML declaration is parsed. The XML declaration is the
-(optional) declaration of the applicable version of the XML
-recommendation, the encoding of the document text, and an optional
-``standalone'' declaration. \var{version} and \var{encoding} will be
-strings, and \var{standalone} will be \code{1} if the document is
-declared standalone, \code{0} if it is declared not to be standalone,
-or \code{-1} if the standalone clause was omitted.
-This is only available with Expat version 1.95.0 or newer.
-\versionadded{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{StartDoctypeDeclHandler}{doctypeName,
- systemId, publicId,
- has_internal_subset}
-Called when Expat begins parsing the document type declaration
-(\code{<!DOCTYPE \ldots}). The \var{doctypeName} is provided exactly
-as presented. The \var{systemId} and \var{publicId} parameters give
-the system and public identifiers if specified, or \code{None} if
-omitted. \var{has_internal_subset} will be true if the document
-contains and internal document declaration subset.
-This requires Expat version 1.2 or newer.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{EndDoctypeDeclHandler}{}
-Called when Expat is done parsing the document type declaration.
-This requires Expat version 1.2 or newer.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{ElementDeclHandler}{name, model}
-Called once for each element type declaration. \var{name} is the name
-of the element type, and \var{model} is a representation of the
-content model.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{AttlistDeclHandler}{elname, attname,
- type, default, required}
-Called for each declared attribute for an element type. If an
-attribute list declaration declares three attributes, this handler is
-called three times, once for each attribute. \var{elname} is the name
-of the element to which the declaration applies and \var{attname} is
-the name of the attribute declared. The attribute type is a string
-passed as \var{type}; the possible values are \code{'CDATA'},
-\code{'ID'}, \code{'IDREF'}, ...
-\var{default} gives the default value for the attribute used when the
-attribute is not specified by the document instance, or \code{None} if
-there is no default value (\code{\#IMPLIED} values). If the attribute
-is required to be given in the document instance, \var{required} will
-be true.
-This requires Expat version 1.95.0 or newer.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{StartElementHandler}{name, attributes}
-Called for the start of every element. \var{name} is a string
-containing the element name, and \var{attributes} is a dictionary
-mapping attribute names to their values.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{EndElementHandler}{name}
-Called for the end of every element.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{ProcessingInstructionHandler}{target, data}
-Called for every processing instruction.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{CharacterDataHandler}{data}
-Called for character data. This will be called for normal character
-data, CDATA marked content, and ignorable whitespace. Applications
-which must distinguish these cases can use the
-\member{StartCdataSectionHandler}, \member{EndCdataSectionHandler},
-and \member{ElementDeclHandler} callbacks to collect the required
-information.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{UnparsedEntityDeclHandler}{entityName, base,
- systemId, publicId,
- notationName}
-Called for unparsed (NDATA) entity declarations. This is only present
-for version 1.2 of the Expat library; for more recent versions, use
-\member{EntityDeclHandler} instead. (The underlying function in the
-Expat library has been declared obsolete.)
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{EntityDeclHandler}{entityName,
- is_parameter_entity, value,
- base, systemId,
- publicId,
- notationName}
-Called for all entity declarations. For parameter and internal
-entities, \var{value} will be a string giving the declared contents
-of the entity; this will be \code{None} for external entities. The
-\var{notationName} parameter will be \code{None} for parsed entities,
-and the name of the notation for unparsed entities.
-\var{is_parameter_entity} will be true if the entity is a parameter
-entity or false for general entities (most applications only need to
-be concerned with general entities).
-This is only available starting with version 1.95.0 of the Expat
-library.
-\versionadded{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{NotationDeclHandler}{notationName, base,
- systemId, publicId}
-Called for notation declarations. \var{notationName}, \var{base}, and
-\var{systemId}, and \var{publicId} are strings if given. If the
-public identifier is omitted, \var{publicId} will be \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{StartNamespaceDeclHandler}{prefix, uri}
-Called when an element contains a namespace declaration. Namespace
-declarations are processed before the \member{StartElementHandler} is
-called for the element on which declarations are placed.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{EndNamespaceDeclHandler}{prefix}
-Called when the closing tag is reached for an element
-that contained a namespace declaration. This is called once for each
-namespace declaration on the element in the reverse of the order for
-which the \member{StartNamespaceDeclHandler} was called to indicate
-the start of each namespace declaration's scope. Calls to this
-handler are made after the corresponding \member{EndElementHandler}
-for the end of the element.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{CommentHandler}{data}
-Called for comments. \var{data} is the text of the comment, excluding
-the leading `\code{<!-}\code{-}' and trailing `\code{-}\code{->}'.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{StartCdataSectionHandler}{}
-Called at the start of a CDATA section. This and
-\member{EndCdataSectionHandler} are needed to be able to identify
-the syntactical start and end for CDATA sections.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{EndCdataSectionHandler}{}
-Called at the end of a CDATA section.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{DefaultHandler}{data}
-Called for any characters in the XML document for
-which no applicable handler has been specified. This means
-characters that are part of a construct which could be reported, but
-for which no handler has been supplied.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{DefaultHandlerExpand}{data}
-This is the same as the \function{DefaultHandler},
-but doesn't inhibit expansion of internal entities.
-The entity reference will not be passed to the default handler.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{NotStandaloneHandler}{} Called if the
-XML document hasn't been declared as being a standalone document.
-This happens when there is an external subset or a reference to a
-parameter entity, but the XML declaration does not set standalone to
-\code{yes} in an XML declaration. If this handler returns \code{0},
-then the parser will throw an \constant{XML_ERROR_NOT_STANDALONE}
-error. If this handler is not set, no exception is raised by the
-parser for this condition.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{ExternalEntityRefHandler}{context, base,
- systemId, publicId}
-Called for references to external entities. \var{base} is the current
-base, as set by a previous call to \method{SetBase()}. The public and
-system identifiers, \var{systemId} and \var{publicId}, are strings if
-given; if the public identifier is not given, \var{publicId} will be
-\code{None}. The \var{context} value is opaque and should only be
-used as described below.
-
-For external entities to be parsed, this handler must be implemented.
-It is responsible for creating the sub-parser using
-\code{ExternalEntityParserCreate(\var{context})}, initializing it with
-the appropriate callbacks, and parsing the entity. This handler
-should return an integer; if it returns \code{0}, the parser will
-throw an \constant{XML_ERROR_EXTERNAL_ENTITY_HANDLING} error,
-otherwise parsing will continue.
-
-If this handler is not provided, external entities are reported by the
-\member{DefaultHandler} callback, if provided.
-\end{methoddesc}
-
-
-\subsection{ExpatError Exceptions \label{expaterror-objects}}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-\exception{ExpatError} exceptions have a number of interesting
-attributes:
-
-\begin{memberdesc}[ExpatError]{code}
- Expat's internal error number for the specific error. This will
- match one of the constants defined in the \code{errors} object from
- this module.
- \versionadded{2.1}
-\end{memberdesc}
-
-\begin{memberdesc}[ExpatError]{lineno}
- Line number on which the error was detected. The first line is
- numbered \code{1}.
- \versionadded{2.1}
-\end{memberdesc}
-
-\begin{memberdesc}[ExpatError]{offset}
- Character offset into the line where the error occurred. The first
- column is numbered \code{0}.
- \versionadded{2.1}
-\end{memberdesc}
-
-
-\subsection{Example \label{expat-example}}
-
-The following program defines three handlers that just print out their
-arguments.
-
-\begin{verbatim}
-import xml.parsers.expat
-
-# 3 handler functions
-def start_element(name, attrs):
- print 'Start element:', name, attrs
-def end_element(name):
- print 'End element:', name
-def char_data(data):
- print 'Character data:', repr(data)
-
-p = xml.parsers.expat.ParserCreate()
-
-p.StartElementHandler = start_element
-p.EndElementHandler = end_element
-p.CharacterDataHandler = char_data
-
-p.Parse("""<?xml version="1.0"?>
-<parent id="top"><child1 name="paul">Text goes here</child1>
-<child2 name="fred">More text</child2>
-</parent>""", 1)
-\end{verbatim}
-
-The output from this program is:
-
-\begin{verbatim}
-Start element: parent {'id': 'top'}
-Start element: child1 {'name': 'paul'}
-Character data: 'Text goes here'
-End element: child1
-Character data: '\n'
-Start element: child2 {'name': 'fred'}
-Character data: 'More text'
-End element: child2
-Character data: '\n'
-End element: parent
-\end{verbatim}
-
-
-\subsection{Content Model Descriptions \label{expat-content-models}}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-Content modules are described using nested tuples. Each tuple
-contains four values: the type, the quantifier, the name, and a tuple
-of children. Children are simply additional content module
-descriptions.
-
-The values of the first two fields are constants defined in the
-\code{model} object of the \module{xml.parsers.expat} module. These
-constants can be collected in two groups: the model type group and the
-quantifier group.
-
-The constants in the model type group are:
-
-\begin{datadescni}{XML_CTYPE_ANY}
-The element named by the model name was declared to have a content
-model of \code{ANY}.
-\end{datadescni}
-
-\begin{datadescni}{XML_CTYPE_CHOICE}
-The named element allows a choice from a number of options; this is
-used for content models such as \code{(A | B | C)}.
-\end{datadescni}
-
-\begin{datadescni}{XML_CTYPE_EMPTY}
-Elements which are declared to be \code{EMPTY} have this model type.
-\end{datadescni}
-
-\begin{datadescni}{XML_CTYPE_MIXED}
-\end{datadescni}
-
-\begin{datadescni}{XML_CTYPE_NAME}
-\end{datadescni}
-
-\begin{datadescni}{XML_CTYPE_SEQ}
-Models which represent a series of models which follow one after the
-other are indicated with this model type. This is used for models
-such as \code{(A, B, C)}.
-\end{datadescni}
-
-
-The constants in the quantifier group are:
-
-\begin{datadescni}{XML_CQUANT_NONE}
-No modifier is given, so it can appear exactly once, as for \code{A}.
-\end{datadescni}
-
-\begin{datadescni}{XML_CQUANT_OPT}
-The model is optional: it can appear once or not at all, as for
-\code{A?}.
-\end{datadescni}
-
-\begin{datadescni}{XML_CQUANT_PLUS}
-The model must occur one or more times (like \code{A+}).
-\end{datadescni}
-
-\begin{datadescni}{XML_CQUANT_REP}
-The model must occur zero or more times, as for \code{A*}.
-\end{datadescni}
-
-
-\subsection{Expat error constants \label{expat-errors}}
-
-The following constants are provided in the \code{errors} object of
-the \refmodule{xml.parsers.expat} module. These constants are useful
-in interpreting some of the attributes of the \exception{ExpatError}
-exception objects raised when an error has occurred.
-
-The \code{errors} object has the following attributes:
-
-\begin{datadescni}{XML_ERROR_ASYNC_ENTITY}
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF}
-An entity reference in an attribute value referred to an external
-entity instead of an internal entity.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_BAD_CHAR_REF}
-A character reference referred to a character which is illegal in XML
-(for example, character \code{0}, or `\code{\&\#0;}').
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_BINARY_ENTITY_REF}
-An entity reference referred to an entity which was declared with a
-notation, so cannot be parsed.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_DUPLICATE_ATTRIBUTE}
-An attribute was used more than once in a start tag.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_INCORRECT_ENCODING}
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_INVALID_TOKEN}
-Raised when an input byte could not properly be assigned to a
-character; for example, a NUL byte (value \code{0}) in a UTF-8 input
-stream.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_JUNK_AFTER_DOC_ELEMENT}
-Something other than whitespace occurred after the document element.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_MISPLACED_XML_PI}
-An XML declaration was found somewhere other than the start of the
-input data.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_NO_ELEMENTS}
-The document contains no elements (XML requires all documents to
-contain exactly one top-level element)..
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_NO_MEMORY}
-Expat was not able to allocate memory internally.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_PARAM_ENTITY_REF}
-A parameter entity reference was found where it was not allowed.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_PARTIAL_CHAR}
-An incomplete character was found in the input.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_RECURSIVE_ENTITY_REF}
-An entity reference contained another reference to the same entity;
-possibly via a different name, and possibly indirectly.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_SYNTAX}
-Some unspecified syntax error was encountered.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_TAG_MISMATCH}
-An end tag did not match the innermost open start tag.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_UNCLOSED_TOKEN}
-Some token (such as a start tag) was not closed before the end of the
-stream or the next token was encountered.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_UNDEFINED_ENTITY}
-A reference was made to a entity which was not defined.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_UNKNOWN_ENCODING}
-The document encoding is not supported by Expat.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_UNCLOSED_CDATA_SECTION}
-A CDATA marked section was not closed.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_EXTERNAL_ENTITY_HANDLING}
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_NOT_STANDALONE}
-The parser determined that the document was not ``standalone'' though
-it declared itself to be in the XML declaration, and the
-\member{NotStandaloneHandler} was set and returned \code{0}.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_UNEXPECTED_STATE}
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_ENTITY_DECLARED_IN_PE}
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_FEATURE_REQUIRES_XML_DTD}
-An operation was requested that requires DTD support to be compiled
-in, but Expat was configured without DTD support. This should never
-be reported by a standard build of the \module{xml.parsers.expat}
-module.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING}
-A behavioral change was requested after parsing started that can only
-be changed before parsing has started. This is (currently) only
-raised by \method{UseForeignDTD()}.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_UNBOUND_PREFIX}
-An undeclared prefix was found when namespace processing was enabled.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_UNDECLARING_PREFIX}
-The document attempted to remove the namespace declaration associated
-with a prefix.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_INCOMPLETE_PE}
-A parameter entity contained incomplete markup.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_XML_DECL}
-The document contained no document element at all.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_TEXT_DECL}
-There was an error parsing a text declaration in an external entity.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_PUBLICID}
-Characters were found in the public id that are not allowed.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_SUSPENDED}
-The requested operation was made on a suspended parser, but isn't
-allowed. This includes attempts to provide additional input or to
-stop the parser.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_NOT_SUSPENDED}
-An attempt to resume the parser was made when the parser had not been
-suspended.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_ABORTED}
-This should not be reported to Python applications.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_FINISHED}
-The requested operation was made on a parser which was finished
-parsing input, but isn't allowed. This includes attempts to provide
-additional input or to stop the parser.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_SUSPEND_PE}
-\end{datadescni}
diff --git a/Doc/lib/libpython.tex b/Doc/lib/libpython.tex
deleted file mode 100644
index c41c386..0000000
--- a/Doc/lib/libpython.tex
+++ /dev/null
@@ -1,8 +0,0 @@
-\chapter{Python Runtime Services
- \label{python}}
-
-The modules described in this chapter provide a wide range of services
-related to the Python interpreter and its interaction with its
-environment. Here's an overview:
-
-\localmoduletable
diff --git a/Doc/lib/libqueue.tex b/Doc/lib/libqueue.tex
deleted file mode 100644
index 591a910..0000000
--- a/Doc/lib/libqueue.tex
+++ /dev/null
@@ -1,145 +0,0 @@
-
-\section{\module{Queue} ---
- A synchronized queue class}
-
-\declaremodule{standard}{Queue}
-\modulesynopsis{A synchronized queue class.}
-
-
-The \module{Queue} module implements a multi-producer, multi-consumer
-FIFO queue. It is especially useful in threads programming when
-information must be exchanged safely between multiple threads. The
-\class{Queue} class in this module implements all the required locking
-semantics. It depends on the availability of thread support in
-Python.
-
-The \module{Queue} module defines the following class and exception:
-
-
-\begin{classdesc}{Queue}{maxsize}
-Constructor for the class. \var{maxsize} is an integer that sets the
-upperbound limit on the number of items that can be placed in the
-queue. Insertion will block once this size has been reached, until
-queue items are consumed. If \var{maxsize} is less than or equal to
-zero, the queue size is infinite.
-\end{classdesc}
-
-\begin{excdesc}{Empty}
-Exception raised when non-blocking \method{get()} (or
-\method{get_nowait()}) is called on a \class{Queue} object which is
-empty.
-\end{excdesc}
-
-\begin{excdesc}{Full}
-Exception raised when non-blocking \method{put()} (or
-\method{put_nowait()}) is called on a \class{Queue} object which is
-full.
-\end{excdesc}
-
-\subsection{Queue Objects}
-\label{QueueObjects}
-
-Class \class{Queue} implements queue objects and has the methods
-described below. This class can be derived from in order to implement
-other queue organizations (e.g. stack) but the inheritable interface
-is not described here. See the source code for details. The public
-methods are:
-
-\begin{methoddesc}[Queue]{qsize}{}
-Return the approximate size of the queue. Because of multithreading
-semantics, this number is not reliable.
-\end{methoddesc}
-
-\begin{methoddesc}[Queue]{empty}{}
-Return \code{True} if the queue is empty, \code{False} otherwise.
-Because of multithreading semantics, this is not reliable.
-\end{methoddesc}
-
-\begin{methoddesc}[Queue]{full}{}
-Return \code{True} if the queue is full, \code{False} otherwise.
-Because of multithreading semantics, this is not reliable.
-\end{methoddesc}
-
-\begin{methoddesc}[Queue]{put}{item\optional{, block\optional{, timeout}}}
-Put \var{item} into the queue. If optional args \var{block} is true
-and \var{timeout} is None (the default), block if necessary until a
-free slot is available. If \var{timeout} is a positive number, it
-blocks at most \var{timeout} seconds and raises the \exception{Full}
-exception if no free slot was available within that time.
-Otherwise (\var{block} is false), put an item on the queue if a free
-slot is immediately available, else raise the \exception{Full}
-exception (\var{timeout} is ignored in that case).
-
-\versionadded[the timeout parameter]{2.3}
-
-\end{methoddesc}
-
-\begin{methoddesc}[Queue]{put_nowait}{item}
-Equivalent to \code{put(\var{item}, False)}.
-\end{methoddesc}
-
-\begin{methoddesc}[Queue]{get}{\optional{block\optional{, timeout}}}
-Remove and return an item from the queue. If optional args
-\var{block} is true and \var{timeout} is None (the default),
-block if necessary until an item is available. If \var{timeout} is
-a positive number, it blocks at most \var{timeout} seconds and raises
-the \exception{Empty} exception if no item was available within that
-time. Otherwise (\var{block} is false), return an item if one is
-immediately available, else raise the \exception{Empty} exception
-(\var{timeout} is ignored in that case).
-
-\versionadded[the timeout parameter]{2.3}
-
-\end{methoddesc}
-
-\begin{methoddesc}[Queue]{get_nowait}{}
-Equivalent to \code{get(False)}.
-\end{methoddesc}
-
-Two methods are offered to support tracking whether enqueued tasks have
-been fully processed by daemon consumer threads.
-
-\begin{methoddesc}[Queue]{task_done}{}
-Indicate that a formerly enqueued task is complete. Used by queue consumer
-threads. For each \method{get()} used to fetch a task, a subsequent call to
-\method{task_done()} tells the queue that the processing on the task is complete.
-
-If a \method{join()} is currently blocking, it will resume when all items
-have been processed (meaning that a \method{task_done()} call was received
-for every item that had been \method{put()} into the queue).
-
-Raises a \exception{ValueError} if called more times than there were items
-placed in the queue.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[Queue]{join}{}
-Blocks until all items in the queue have been gotten and processed.
-
-The count of unfinished tasks goes up whenever an item is added to the
-queue. The count goes down whenever a consumer thread calls \method{task_done()}
-to indicate that the item was retrieved and all work on it is complete.
-When the count of unfinished tasks drops to zero, join() unblocks.
-\versionadded{2.5}
-\end{methoddesc}
-
-Example of how to wait for enqueued tasks to be completed:
-
-\begin{verbatim}
- def worker():
- while True:
- item = q.get()
- do_work(item)
- q.task_done()
-
- q = Queue()
- for i in range(num_worker_threads):
- t = Thread(target=worker)
- t.setDaemon(True)
- t.start()
-
- for item in source():
- q.put(item)
-
- q.join() # block until all tasks are done
-\end{verbatim}
diff --git a/Doc/lib/libquopri.tex b/Doc/lib/libquopri.tex
deleted file mode 100644
index 9e7895b..0000000
--- a/Doc/lib/libquopri.tex
+++ /dev/null
@@ -1,61 +0,0 @@
-\section{\module{quopri} ---
- Encode and decode MIME quoted-printable data}
-
-\declaremodule{standard}{quopri}
-\modulesynopsis{Encode and decode files using the MIME
- quoted-printable encoding.}
-
-
-This module performs quoted-printable transport encoding and decoding,
-as defined in \rfc{1521}: ``MIME (Multipurpose Internet Mail
-Extensions) Part One: Mechanisms for Specifying and Describing the
-Format of Internet Message Bodies''. The quoted-printable encoding is
-designed for data where there are relatively few nonprintable
-characters; the base64 encoding scheme available via the
-\refmodule{base64} module is more compact if there are many such
-characters, as when sending a graphics file.
-\indexii{quoted-printable}{encoding}
-\index{MIME!quoted-printable encoding}
-
-
-\begin{funcdesc}{decode}{input, output\optional{,header}}
-Decode the contents of the \var{input} file and write the resulting
-decoded binary data to the \var{output} file.
-\var{input} and \var{output} must either be file objects or objects that
-mimic the file object interface. \var{input} will be read until
-\code{\var{input}.readline()} returns an empty string.
-If the optional argument \var{header} is present and true, underscore
-will be decoded as space. This is used to decode
-``Q''-encoded headers as described in \rfc{1522}: ``MIME (Multipurpose Internet Mail Extensions)
-Part Two: Message Header Extensions for Non-ASCII Text''.
-\end{funcdesc}
-
-\begin{funcdesc}{encode}{input, output, quotetabs}
-Encode the contents of the \var{input} file and write the resulting
-quoted-printable data to the \var{output} file.
-\var{input} and \var{output} must either be file objects or objects that
-mimic the file object interface. \var{input} will be read until
-\code{\var{input}.readline()} returns an empty string.
-\var{quotetabs} is a flag which controls whether to encode embedded
-spaces and tabs; when true it encodes such embedded whitespace, and
-when false it leaves them unencoded. Note that spaces and tabs
-appearing at the end of lines are always encoded, as per \rfc{1521}.
-\end{funcdesc}
-
-\begin{funcdesc}{decodestring}{s\optional{,header}}
-Like \function{decode()}, except that it accepts a source string and
-returns the corresponding decoded string.
-\end{funcdesc}
-
-\begin{funcdesc}{encodestring}{s\optional{, quotetabs}}
-Like \function{encode()}, except that it accepts a source string and
-returns the corresponding encoded string. \var{quotetabs} is optional
-(defaulting to 0), and is passed straight through to
-\function{encode()}.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{mimify}{General utilities for processing of MIME messages.}
- \seemodule{base64}{Encode and decode MIME base64 data}
-\end{seealso}
diff --git a/Doc/lib/librandom.tex b/Doc/lib/librandom.tex
deleted file mode 100644
index a9bd5ac..0000000
--- a/Doc/lib/librandom.tex
+++ /dev/null
@@ -1,309 +0,0 @@
-\section{\module{random} ---
- Generate pseudo-random numbers}
-
-\declaremodule{standard}{random}
-\modulesynopsis{Generate pseudo-random numbers with various common
- distributions.}
-
-
-This module implements pseudo-random number generators for various
-distributions.
-
-For integers, uniform selection from a range.
-For sequences, uniform selection of a random element, a function to
-generate a random permutation of a list in-place, and a function for
-random sampling without replacement.
-
-On the real line, there are functions to compute uniform, normal (Gaussian),
-lognormal, negative exponential, gamma, and beta distributions.
-For generating distributions of angles, the von Mises distribution
-is available.
-
-Almost all module functions depend on the basic function
-\function{random()}, which generates a random float uniformly in
-the semi-open range [0.0, 1.0). Python uses the Mersenne Twister as
-the core generator. It produces 53-bit precision floats and has a
-period of 2**19937-1. The underlying implementation in C
-is both fast and threadsafe. The Mersenne Twister is one of the most
-extensively tested random number generators in existence. However, being
-completely deterministic, it is not suitable for all purposes, and is
-completely unsuitable for cryptographic purposes.
-
-The functions supplied by this module are actually bound methods of a
-hidden instance of the \class{random.Random} class. You can
-instantiate your own instances of \class{Random} to get generators
-that don't share state. This is especially useful for multi-threaded
-programs, creating a different instance of \class{Random} for each
-thread, and using the \method{jumpahead()} method to make it likely that the
-generated sequences seen by each thread don't overlap.
-
-Class \class{Random} can also be subclassed if you want to use a
-different basic generator of your own devising: in that case, override
-the \method{random()}, \method{seed()}, \method{getstate()},
-\method{setstate()} and \method{jumpahead()} methods.
-Optionally, a new generator can supply a \method{getrandombits()}
-method --- this allows \method{randrange()} to produce selections
-over an arbitrarily large range.
-\versionadded[the \method{getrandombits()} method]{2.4}
-
-As an example of subclassing, the \module{random} module provides
-the \class{WichmannHill} class that implements an alternative generator
-in pure Python. The class provides a backward compatible way to
-reproduce results from earlier versions of Python, which used the
-Wichmann-Hill algorithm as the core generator. Note that this Wichmann-Hill
-generator can no longer be recommended: its period is too short by
-contemporary standards, and the sequence generated is known to fail some
-stringent randomness tests. See the references below for a recent
-variant that repairs these flaws.
-\versionchanged[Substituted MersenneTwister for Wichmann-Hill]{2.3}
-
-
-Bookkeeping functions:
-
-\begin{funcdesc}{seed}{\optional{x}}
- Initialize the basic random number generator.
- Optional argument \var{x} can be any hashable object.
- If \var{x} is omitted or \code{None}, current system time is used;
- current system time is also used to initialize the generator when the
- module is first imported. If randomness sources are provided by the
- operating system, they are used instead of the system time (see the
- \function{os.urandom()}
- function for details on availability). \versionchanged[formerly,
- operating system resources were not used]{2.4}
- If \var{x} is not \code{None} or an int or long,
- \code{hash(\var{x})} is used instead.
- If \var{x} is an int or long, \var{x} is used directly.
-\end{funcdesc}
-
-\begin{funcdesc}{getstate}{}
- Return an object capturing the current internal state of the
- generator. This object can be passed to \function{setstate()} to
- restore the state.
- \versionadded{2.1}
-\end{funcdesc}
-
-\begin{funcdesc}{setstate}{state}
- \var{state} should have been obtained from a previous call to
- \function{getstate()}, and \function{setstate()} restores the
- internal state of the generator to what it was at the time
- \function{setstate()} was called.
- \versionadded{2.1}
-\end{funcdesc}
-
-\begin{funcdesc}{jumpahead}{n}
- Change the internal state to one different from and likely far away from
- the current state. \var{n} is a non-negative integer which is used to
- scramble the current state vector. This is most useful in multi-threaded
- programs, in conjuction with multiple instances of the \class{Random}
- class: \method{setstate()} or \method{seed()} can be used to force all
- instances into the same internal state, and then \method{jumpahead()}
- can be used to force the instances' states far apart.
- \versionadded{2.1}
- \versionchanged[Instead of jumping to a specific state, \var{n} steps
- ahead, \method{jumpahead(\var{n})} jumps to another state likely to be
- separated by many steps]{2.3}
- \end{funcdesc}
-
-\begin{funcdesc}{getrandbits}{k}
- Returns a python \class{long} int with \var{k} random bits.
- This method is supplied with the MersenneTwister generator and some
- other generators may also provide it as an optional part of the API.
- When available, \method{getrandbits()} enables \method{randrange()}
- to handle arbitrarily large ranges.
- \versionadded{2.4}
-\end{funcdesc}
-
-Functions for integers:
-
-\begin{funcdesc}{randrange}{\optional{start,} stop\optional{, step}}
- Return a randomly selected element from \code{range(\var{start},
- \var{stop}, \var{step})}. This is equivalent to
- \code{choice(range(\var{start}, \var{stop}, \var{step}))},
- but doesn't actually build a range object.
- \versionadded{1.5.2}
-\end{funcdesc}
-
-\begin{funcdesc}{randint}{a, b}
- Return a random integer \var{N} such that
- \code{\var{a} <= \var{N} <= \var{b}}.
-\end{funcdesc}
-
-
-Functions for sequences:
-
-\begin{funcdesc}{choice}{seq}
- Return a random element from the non-empty sequence \var{seq}.
- If \var{seq} is empty, raises \exception{IndexError}.
-\end{funcdesc}
-
-\begin{funcdesc}{shuffle}{x\optional{, random}}
- Shuffle the sequence \var{x} in place.
- The optional argument \var{random} is a 0-argument function
- returning a random float in [0.0, 1.0); by default, this is the
- function \function{random()}.
-
- Note that for even rather small \code{len(\var{x})}, the total
- number of permutations of \var{x} is larger than the period of most
- random number generators; this implies that most permutations of a
- long sequence can never be generated.
-\end{funcdesc}
-
-\begin{funcdesc}{sample}{population, k}
- Return a \var{k} length list of unique elements chosen from the
- population sequence. Used for random sampling without replacement.
- \versionadded{2.3}
-
- Returns a new list containing elements from the population while
- leaving the original population unchanged. The resulting list is
- in selection order so that all sub-slices will also be valid random
- samples. This allows raffle winners (the sample) to be partitioned
- into grand prize and second place winners (the subslices).
-
- Members of the population need not be hashable or unique. If the
- population contains repeats, then each occurrence is a possible
- selection in the sample.
-
- To choose a sample from a range of integers, use an \function{range()}
- object as an argument. This is especially fast and space efficient for
- sampling from a large population: \code{sample(range(10000000), 60)}.
-\end{funcdesc}
-
-
-The following functions generate specific real-valued distributions.
-Function parameters are named after the corresponding variables in the
-distribution's equation, as used in common mathematical practice; most of
-these equations can be found in any statistics text.
-
-\begin{funcdesc}{random}{}
- Return the next random floating point number in the range [0.0, 1.0).
-\end{funcdesc}
-
-\begin{funcdesc}{uniform}{a, b}
- Return a random real number \var{N} such that
- \code{\var{a} <= \var{N} < \var{b}}.
-\end{funcdesc}
-
-\begin{funcdesc}{betavariate}{alpha, beta}
- Beta distribution. Conditions on the parameters are
- \code{\var{alpha} > 0} and \code{\var{beta} > 0}.
- Returned values range between 0 and 1.
-\end{funcdesc}
-
-\begin{funcdesc}{expovariate}{lambd}
- Exponential distribution. \var{lambd} is 1.0 divided by the desired
- mean. (The parameter would be called ``lambda'', but that is a
- reserved word in Python.) Returned values range from 0 to
- positive infinity.
-\end{funcdesc}
-
-\begin{funcdesc}{gammavariate}{alpha, beta}
- Gamma distribution. (\emph{Not} the gamma function!) Conditions on
- the parameters are \code{\var{alpha} > 0} and \code{\var{beta} > 0}.
-\end{funcdesc}
-
-\begin{funcdesc}{gauss}{mu, sigma}
- Gaussian distribution. \var{mu} is the mean, and \var{sigma} is the
- standard deviation. This is slightly faster than the
- \function{normalvariate()} function defined below.
-\end{funcdesc}
-
-\begin{funcdesc}{lognormvariate}{mu, sigma}
- Log normal distribution. If you take the natural logarithm of this
- distribution, you'll get a normal distribution with mean \var{mu}
- and standard deviation \var{sigma}. \var{mu} can have any value,
- and \var{sigma} must be greater than zero.
-\end{funcdesc}
-
-\begin{funcdesc}{normalvariate}{mu, sigma}
- Normal distribution. \var{mu} is the mean, and \var{sigma} is the
- standard deviation.
-\end{funcdesc}
-
-\begin{funcdesc}{vonmisesvariate}{mu, kappa}
- \var{mu} is the mean angle, expressed in radians between 0 and
- 2*\emph{pi}, and \var{kappa} is the concentration parameter, which
- must be greater than or equal to zero. If \var{kappa} is equal to
- zero, this distribution reduces to a uniform random angle over the
- range 0 to 2*\emph{pi}.
-\end{funcdesc}
-
-\begin{funcdesc}{paretovariate}{alpha}
- Pareto distribution. \var{alpha} is the shape parameter.
-\end{funcdesc}
-
-\begin{funcdesc}{weibullvariate}{alpha, beta}
- Weibull distribution. \var{alpha} is the scale parameter and
- \var{beta} is the shape parameter.
-\end{funcdesc}
-
-Alternative Generators:
-
-\begin{classdesc}{WichmannHill}{\optional{seed}}
-Class that implements the Wichmann-Hill algorithm as the core generator.
-Has all of the same methods as \class{Random} plus the \method{whseed()}
-method described below. Because this class is implemented in pure
-Python, it is not threadsafe and may require locks between calls. The
-period of the generator is 6,953,607,871,644 which is small enough to
-require care that two independent random sequences do not overlap.
-\end{classdesc}
-
-\begin{funcdesc}{whseed}{\optional{x}}
- This is obsolete, supplied for bit-level compatibility with versions
- of Python prior to 2.1.
- See \function{seed()} for details. \function{whseed()} does not guarantee
- that distinct integer arguments yield distinct internal states, and can
- yield no more than about 2**24 distinct internal states in all.
-\end{funcdesc}
-
-\begin{classdesc}{SystemRandom}{\optional{seed}}
-Class that uses the \function{os.urandom()} function for generating
-random numbers from sources provided by the operating system.
-Not available on all systems.
-Does not rely on software state and sequences are not reproducible.
-Accordingly, the \method{seed()} and \method{jumpahead()} methods
-have no effect and are ignored. The \method{getstate()} and
-\method{setstate()} methods raise \exception{NotImplementedError} if
-called.
-\versionadded{2.4}
-\end{classdesc}
-
-Examples of basic usage:
-
-\begin{verbatim}
->>> random.random() # Random float x, 0.0 <= x < 1.0
-0.37444887175646646
->>> random.uniform(1, 10) # Random float x, 1.0 <= x < 10.0
-1.1800146073117523
->>> random.randint(1, 10) # Integer from 1 to 10, endpoints included
-7
->>> random.randrange(0, 101, 2) # Even integer from 0 to 100
-26
->>> random.choice('abcdefghij') # Choose a random element
-'c'
-
->>> items = [1, 2, 3, 4, 5, 6, 7]
->>> random.shuffle(items)
->>> items
-[7, 3, 2, 5, 6, 4, 1]
-
->>> random.sample([1, 2, 3, 4, 5], 3) # Choose 3 elements
-[4, 1, 5]
-
-\end{verbatim}
-
-\begin{seealso}
- \seetext{M. Matsumoto and T. Nishimura, ``Mersenne Twister: A
- 623-dimensionally equidistributed uniform pseudorandom
- number generator'',
- \citetitle{ACM Transactions on Modeling and Computer Simulation}
- Vol. 8, No. 1, January pp.3-30 1998.}
-
- \seetext{Wichmann, B. A. \& Hill, I. D., ``Algorithm AS 183:
- An efficient and portable pseudo-random number generator'',
- \citetitle{Applied Statistics} 31 (1982) 188-190.}
-
- \seeurl{http://www.npl.co.uk/ssfm/download/abstracts.html\#196}{A modern
- variation of the Wichmann-Hill generator that greatly increases
- the period, and passes now-standard statistical tests that the
- original generator failed.}
-\end{seealso}
diff --git a/Doc/lib/libre.tex b/Doc/lib/libre.tex
deleted file mode 100644
index a0b8b51..0000000
--- a/Doc/lib/libre.tex
+++ /dev/null
@@ -1,954 +0,0 @@
-\section{\module{re} ---
- Regular expression operations}
-\declaremodule{standard}{re}
-\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com}
-\sectionauthor{Andrew M. Kuchling}{amk@amk.ca}
-
-
-\modulesynopsis{Regular expression search and match operations with a
- Perl-style expression syntax.}
-
-
-This module provides regular expression matching operations similar to
-those found in Perl. Regular expression pattern strings may not
-contain null bytes, but can specify the null byte using the
-\code{\e\var{number}} notation. Both patterns and strings to be
-searched can be Unicode strings as well as 8-bit strings. The
-\module{re} module is always available.
-
-Regular expressions use the backslash character (\character{\e}) to
-indicate special forms or to allow special characters to be used
-without invoking their special meaning. This collides with Python's
-usage of the same character for the same purpose in string literals;
-for example, to match a literal backslash, one might have to write
-\code{'\e\e\e\e'} as the pattern string, because the regular expression
-must be \samp{\e\e}, and each backslash must be expressed as
-\samp{\e\e} inside a regular Python string literal.
-
-The solution is to use Python's raw string notation for regular
-expression patterns; backslashes are not handled in any special way in
-a string literal prefixed with \character{r}. So \code{r"\e n"} is a
-two-character string containing \character{\e} and \character{n},
-while \code{"\e n"} is a one-character string containing a newline.
-Usually patterns will be expressed in Python code using this raw
-string notation.
-
-\begin{seealso}
- \seetitle{Mastering Regular Expressions}{Book on regular expressions
- by Jeffrey Friedl, published by O'Reilly. The second
- edition of the book no longer covers Python at all,
- but the first edition covered writing good regular expression
- patterns in great detail.}
-\end{seealso}
-
-
-\subsection{Regular Expression Syntax \label{re-syntax}}
-
-A regular expression (or RE) specifies a set of strings that matches
-it; the functions in this module let you check if a particular string
-matches a given regular expression (or if a given regular expression
-matches a particular string, which comes down to the same thing).
-
-Regular expressions can be concatenated to form new regular
-expressions; if \emph{A} and \emph{B} are both regular expressions,
-then \emph{AB} is also a regular expression. In general, if a string
-\emph{p} matches \emph{A} and another string \emph{q} matches \emph{B},
-the string \emph{pq} will match AB. This holds unless \emph{A} or
-\emph{B} contain low precedence operations; boundary conditions between
-\emph{A} and \emph{B}; or have numbered group references. Thus, complex
-expressions can easily be constructed from simpler primitive
-expressions like the ones described here. For details of the theory
-and implementation of regular expressions, consult the Friedl book
-referenced above, or almost any textbook about compiler construction.
-
-A brief explanation of the format of regular expressions follows. For
-further information and a gentler presentation, consult the Regular
-Expression HOWTO, accessible from \url{http://www.python.org/doc/howto/}.
-
-Regular expressions can contain both special and ordinary characters.
-Most ordinary characters, like \character{A}, \character{a}, or
-\character{0}, are the simplest regular expressions; they simply match
-themselves. You can concatenate ordinary characters, so \regexp{last}
-matches the string \code{'last'}. (In the rest of this section, we'll
-write RE's in \regexp{this special style}, usually without quotes, and
-strings to be matched \code{'in single quotes'}.)
-
-Some characters, like \character{|} or \character{(}, are special.
-Special characters either stand for classes of ordinary characters, or
-affect how the regular expressions around them are interpreted.
-
-The special characters are:
-%
-\begin{description}
-
-\item[\character{.}] (Dot.) In the default mode, this matches any
-character except a newline. If the \constant{DOTALL} flag has been
-specified, this matches any character including a newline.
-
-\item[\character{\textasciicircum}] (Caret.) Matches the start of the
-string, and in \constant{MULTILINE} mode also matches immediately
-after each newline.
-
-\item[\character{\$}] Matches the end of the string or just before the
-newline at the end of the string, and in \constant{MULTILINE} mode
-also matches before a newline. \regexp{foo} matches both 'foo' and
-'foobar', while the regular expression \regexp{foo\$} matches only
-'foo'. More interestingly, searching for \regexp{foo.\$} in
-'foo1\textbackslash nfoo2\textbackslash n' matches 'foo2' normally,
-but 'foo1' in \constant{MULTILINE} mode.
-
-\item[\character{*}] Causes the resulting RE to
-match 0 or more repetitions of the preceding RE, as many repetitions
-as are possible. \regexp{ab*} will
-match 'a', 'ab', or 'a' followed by any number of 'b's.
-
-\item[\character{+}] Causes the
-resulting RE to match 1 or more repetitions of the preceding RE.
-\regexp{ab+} will match 'a' followed by any non-zero number of 'b's; it
-will not match just 'a'.
-
-\item[\character{?}] Causes the resulting RE to
-match 0 or 1 repetitions of the preceding RE. \regexp{ab?} will
-match either 'a' or 'ab'.
-
-\item[\code{*?}, \code{+?}, \code{??}] The \character{*},
-\character{+}, and \character{?} qualifiers are all \dfn{greedy}; they
-match as much text as possible. Sometimes this behaviour isn't
-desired; if the RE \regexp{<.*>} is matched against
-\code{'<H1>title</H1>'}, it will match the entire string, and not just
-\code{'<H1>'}. Adding \character{?} after the qualifier makes it
-perform the match in \dfn{non-greedy} or \dfn{minimal} fashion; as
-\emph{few} characters as possible will be matched. Using \regexp{.*?}
-in the previous expression will match only \code{'<H1>'}.
-
-\item[\code{\{\var{m}\}}]
-Specifies that exactly \var{m} copies of the previous RE should be
-matched; fewer matches cause the entire RE not to match. For example,
-\regexp{a\{6\}} will match exactly six \character{a} characters, but
-not five.
-
-\item[\code{\{\var{m},\var{n}\}}] Causes the resulting RE to match from
-\var{m} to \var{n} repetitions of the preceding RE, attempting to
-match as many repetitions as possible. For example, \regexp{a\{3,5\}}
-will match from 3 to 5 \character{a} characters. Omitting \var{m}
-specifies a lower bound of zero,
-and omitting \var{n} specifies an infinite upper bound. As an
-example, \regexp{a\{4,\}b} will match \code{aaaab} or a thousand
-\character{a} characters followed by a \code{b}, but not \code{aaab}.
-The comma may not be omitted or the modifier would be confused with
-the previously described form.
-
-\item[\code{\{\var{m},\var{n}\}?}] Causes the resulting RE to
-match from \var{m} to \var{n} repetitions of the preceding RE,
-attempting to match as \emph{few} repetitions as possible. This is
-the non-greedy version of the previous qualifier. For example, on the
-6-character string \code{'aaaaaa'}, \regexp{a\{3,5\}} will match 5
-\character{a} characters, while \regexp{a\{3,5\}?} will only match 3
-characters.
-
-\item[\character{\e}] Either escapes special characters (permitting
-you to match characters like \character{*}, \character{?}, and so
-forth), or signals a special sequence; special sequences are discussed
-below.
-
-If you're not using a raw string to
-express the pattern, remember that Python also uses the
-backslash as an escape sequence in string literals; if the escape
-sequence isn't recognized by Python's parser, the backslash and
-subsequent character are included in the resulting string. However,
-if Python would recognize the resulting sequence, the backslash should
-be repeated twice. This is complicated and hard to understand, so
-it's highly recommended that you use raw strings for all but the
-simplest expressions.
-
-\item[\code{[]}] Used to indicate a set of characters. Characters can
-be listed individually, or a range of characters can be indicated by
-giving two characters and separating them by a \character{-}. Special
-characters are not active inside sets. For example, \regexp{[akm\$]}
-will match any of the characters \character{a}, \character{k},
-\character{m}, or \character{\$}; \regexp{[a-z]}
-will match any lowercase letter, and \code{[a-zA-Z0-9]} matches any
-letter or digit. Character classes such as \code{\e w} or \code{\e S}
-(defined below) are also acceptable inside a range. If you want to
-include a \character{]} or a \character{-} inside a set, precede it with a
-backslash, or place it as the first character. The
-pattern \regexp{[]]} will match \code{']'}, for example.
-
-You can match the characters not within a range by \dfn{complementing}
-the set. This is indicated by including a
-\character{\textasciicircum} as the first character of the set;
-\character{\textasciicircum} elsewhere will simply match the
-\character{\textasciicircum} character. For example,
-\regexp{[{\textasciicircum}5]} will match
-any character except \character{5}, and
-\regexp{[\textasciicircum\code{\textasciicircum}]} will match any character
-except \character{\textasciicircum}.
-
-\item[\character{|}]\code{A|B}, where A and B can be arbitrary REs,
-creates a regular expression that will match either A or B. An
-arbitrary number of REs can be separated by the \character{|} in this
-way. This can be used inside groups (see below) as well. As the target
-string is scanned, REs separated by \character{|} are tried from left to
-right. When one pattern completely matches, that branch is accepted.
-This means that once \code{A} matches, \code{B} will not be tested further,
-even if it would produce a longer overall match. In other words, the
-\character{|} operator is never greedy. To match a literal \character{|},
-use \regexp{\e|}, or enclose it inside a character class, as in \regexp{[|]}.
-
-\item[\code{(...)}] Matches whatever regular expression is inside the
-parentheses, and indicates the start and end of a group; the contents
-of a group can be retrieved after a match has been performed, and can
-be matched later in the string with the \regexp{\e \var{number}} special
-sequence, described below. To match the literals \character{(} or
-\character{)}, use \regexp{\e(} or \regexp{\e)}, or enclose them
-inside a character class: \regexp{[(] [)]}.
-
-\item[\code{(?...)}] This is an extension notation (a \character{?}
-following a \character{(} is not meaningful otherwise). The first
-character after the \character{?}
-determines what the meaning and further syntax of the construct is.
-Extensions usually do not create a new group;
-\regexp{(?P<\var{name}>...)} is the only exception to this rule.
-Following are the currently supported extensions.
-
-\item[\code{(?iLmsux)}] (One or more letters from the set \character{i},
-\character{L}, \character{m}, \character{s}, \character{u},
-\character{x}.) The group matches the empty string; the letters set
-the corresponding flags (\constant{re.I}, \constant{re.L},
-\constant{re.M}, \constant{re.S}, \constant{re.U}, \constant{re.X})
-for the entire regular expression. This is useful if you wish to
-include the flags as part of the regular expression, instead of
-passing a \var{flag} argument to the \function{compile()} function.
-
-Note that the \regexp{(?x)} flag changes how the expression is parsed.
-It should be used first in the expression string, or after one or more
-whitespace characters. If there are non-whitespace characters before
-the flag, the results are undefined.
-
-\item[\code{(?:...)}] A non-grouping version of regular parentheses.
-Matches whatever regular expression is inside the parentheses, but the
-substring matched by the
-group \emph{cannot} be retrieved after performing a match or
-referenced later in the pattern.
-
-\item[\code{(?P<\var{name}>...)}] Similar to regular parentheses, but
-the substring matched by the group is accessible via the symbolic group
-name \var{name}. Group names must be valid Python identifiers, and
-each group name must be defined only once within a regular expression. A
-symbolic group is also a numbered group, just as if the group were not
-named. So the group named 'id' in the example above can also be
-referenced as the numbered group 1.
-
-For example, if the pattern is
-\regexp{(?P<id>[a-zA-Z_]\e w*)}, the group can be referenced by its
-name in arguments to methods of match objects, such as
-\code{m.group('id')} or \code{m.end('id')}, and also by name in
-pattern text (for example, \regexp{(?P=id)}) and replacement text
-(such as \code{\e g<id>}).
-
-\item[\code{(?P=\var{name})}] Matches whatever text was matched by the
-earlier group named \var{name}.
-
-\item[\code{(?\#...)}] A comment; the contents of the parentheses are
-simply ignored.
-
-\item[\code{(?=...)}] Matches if \regexp{...} matches next, but doesn't
-consume any of the string. This is called a lookahead assertion. For
-example, \regexp{Isaac (?=Asimov)} will match \code{'Isaac~'} only if it's
-followed by \code{'Asimov'}.
-
-\item[\code{(?!...)}] Matches if \regexp{...} doesn't match next. This
-is a negative lookahead assertion. For example,
-\regexp{Isaac (?!Asimov)} will match \code{'Isaac~'} only if it's \emph{not}
-followed by \code{'Asimov'}.
-
-\item[\code{(?<=...)}] Matches if the current position in the string
-is preceded by a match for \regexp{...} that ends at the current
-position. This is called a \dfn{positive lookbehind assertion}.
-\regexp{(?<=abc)def} will find a match in \samp{abcdef}, since the
-lookbehind will back up 3 characters and check if the contained
-pattern matches. The contained pattern must only match strings of
-some fixed length, meaning that \regexp{abc} or \regexp{a|b} are
-allowed, but \regexp{a*} and \regexp{a\{3,4\}} are not. Note that
-patterns which start with positive lookbehind assertions will never
-match at the beginning of the string being searched; you will most
-likely want to use the \function{search()} function rather than the
-\function{match()} function:
-
-\begin{verbatim}
->>> import re
->>> m = re.search('(?<=abc)def', 'abcdef')
->>> m.group(0)
-'def'
-\end{verbatim}
-
-This example looks for a word following a hyphen:
-
-\begin{verbatim}
->>> m = re.search('(?<=-)\w+', 'spam-egg')
->>> m.group(0)
-'egg'
-\end{verbatim}
-
-\item[\code{(?<!...)}] Matches if the current position in the string
-is not preceded by a match for \regexp{...}. This is called a
-\dfn{negative lookbehind assertion}. Similar to positive lookbehind
-assertions, the contained pattern must only match strings of some
-fixed length. Patterns which start with negative lookbehind
-assertions may match at the beginning of the string being searched.
-
-\item[\code{(?(\var{id/name})yes-pattern|no-pattern)}] Will try to match
-with \regexp{yes-pattern} if the group with given \var{id} or \var{name}
-exists, and with \regexp{no-pattern} if it doesn't. \regexp{|no-pattern}
-is optional and can be omitted. For example,
-\regexp{(<)?(\e w+@\e w+(?:\e .\e w+)+)(?(1)>)} is a poor email matching
-pattern, which will match with \code{'<user@host.com>'} as well as
-\code{'user@host.com'}, but not with \code{'<user@host.com'}.
-\versionadded{2.4}
-
-\end{description}
-
-The special sequences consist of \character{\e} and a character from the
-list below. If the ordinary character is not on the list, then the
-resulting RE will match the second character. For example,
-\regexp{\e\$} matches the character \character{\$}.
-%
-\begin{description}
-
-\item[\code{\e \var{number}}] Matches the contents of the group of the
-same number. Groups are numbered starting from 1. For example,
-\regexp{(.+) \e 1} matches \code{'the the'} or \code{'55 55'}, but not
-\code{'the end'} (note
-the space after the group). This special sequence can only be used to
-match one of the first 99 groups. If the first digit of \var{number}
-is 0, or \var{number} is 3 octal digits long, it will not be interpreted
-as a group match, but as the character with octal value \var{number}.
-Inside the \character{[} and \character{]} of a character class, all numeric
-escapes are treated as characters.
-
-\item[\code{\e A}] Matches only at the start of the string.
-
-\item[\code{\e b}] Matches the empty string, but only at the
-beginning or end of a word. A word is defined as a sequence of
-alphanumeric or underscore characters, so the end of a word is indicated by
-whitespace or a non-alphanumeric, non-underscore character. Note that
-{}\code{\e b} is defined as the boundary between \code{\e w} and \code{\e
-W}, so the precise set of characters deemed to be alphanumeric depends on the
-values of the \code{UNICODE} and \code{LOCALE} flags. Inside a character
-range, \regexp{\e b} represents the backspace character, for compatibility
-with Python's string literals.
-
-\item[\code{\e B}] Matches the empty string, but only when it is \emph{not}
-at the beginning or end of a word. This is just the opposite of {}\code{\e
-b}, so is also subject to the settings of \code{LOCALE} and \code{UNICODE}.
-
-\item[\code{\e d}]When the \constant{UNICODE} flag is not specified, matches
-any decimal digit; this is equivalent to the set \regexp{[0-9]}.
-With \constant{UNICODE}, it will match whatever is classified as a digit
-in the Unicode character properties database.
-
-\item[\code{\e D}]When the \constant{UNICODE} flag is not specified, matches
-any non-digit character; this is equivalent to the set
-\regexp{[{\textasciicircum}0-9]}. With \constant{UNICODE}, it will match
-anything other than character marked as digits in the Unicode character
-properties database.
-
-\item[\code{\e s}]When the \constant{LOCALE} and \constant{UNICODE}
-flags are not specified, matches any whitespace character; this is
-equivalent to the set \regexp{[ \e t\e n\e r\e f\e v]}.
-With \constant{LOCALE}, it will match this set plus whatever characters
-are defined as space for the current locale. If \constant{UNICODE} is set,
-this will match the characters \regexp{[ \e t\e n\e r\e f\e v]} plus
-whatever is classified as space in the Unicode character properties
-database.
-
-\item[\code{\e S}]When the \constant{LOCALE} and \constant{UNICODE}
-flags are not specified, matches any non-whitespace character; this is
-equivalent to the set \regexp{[\textasciicircum\ \e t\e n\e r\e f\e v]}
-With \constant{LOCALE}, it will match any character not in this set,
-and not defined as space in the current locale. If \constant{UNICODE}
-is set, this will match anything other than \regexp{[ \e t\e n\e r\e f\e v]}
-and characters marked as space in the Unicode character properties database.
-
-\item[\code{\e w}]When the \constant{LOCALE} and \constant{UNICODE}
-flags are not specified, matches any alphanumeric character and the
-underscore; this is equivalent to the set
-\regexp{[a-zA-Z0-9_]}. With \constant{LOCALE}, it will match the set
-\regexp{[0-9_]} plus whatever characters are defined as alphanumeric for
-the current locale. If \constant{UNICODE} is set, this will match the
-characters \regexp{[0-9_]} plus whatever is classified as alphanumeric
-in the Unicode character properties database.
-
-\item[\code{\e W}]When the \constant{LOCALE} and \constant{UNICODE}
-flags are not specified, matches any non-alphanumeric character; this
-is equivalent to the set \regexp{[{\textasciicircum}a-zA-Z0-9_]}. With
-\constant{LOCALE}, it will match any character not in the set
-\regexp{[0-9_]}, and not defined as alphanumeric for the current locale.
-If \constant{UNICODE} is set, this will match anything other than
-\regexp{[0-9_]} and characters marked as alphanumeric in the Unicode
-character properties database.
-
-\item[\code{\e Z}]Matches only at the end of the string.
-
-\end{description}
-
-Most of the standard escapes supported by Python string literals are
-also accepted by the regular expression parser:
-
-\begin{verbatim}
-\a \b \f \n
-\r \t \v \x
-\\
-\end{verbatim}
-
-Octal escapes are included in a limited form: If the first digit is a
-0, or if there are three octal digits, it is considered an octal
-escape. Otherwise, it is a group reference. As for string literals,
-octal escapes are always at most three digits in length.
-
-
-% Note the lack of a period in the section title; it causes problems
-% with readers of the GNU info version. See http://www.python.org/sf/581414.
-\subsection{Matching vs Searching \label{matching-searching}}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-Python offers two different primitive operations based on regular
-expressions: match and search. If you are accustomed to Perl's
-semantics, the search operation is what you're looking for. See the
-\function{search()} function and corresponding method of compiled
-regular expression objects.
-
-Note that match may differ from search using a regular expression
-beginning with \character{\textasciicircum}:
-\character{\textasciicircum} matches only at the
-start of the string, or in \constant{MULTILINE} mode also immediately
-following a newline. The ``match'' operation succeeds only if the
-pattern matches at the start of the string regardless of mode, or at
-the starting position given by the optional \var{pos} argument
-regardless of whether a newline precedes it.
-
-% Examples from Tim Peters:
-\begin{verbatim}
-re.compile("a").match("ba", 1) # succeeds
-re.compile("^a").search("ba", 1) # fails; 'a' not at start
-re.compile("^a").search("\na", 1) # fails; 'a' not at start
-re.compile("^a", re.M).search("\na", 1) # succeeds
-re.compile("^a", re.M).search("ba", 1) # fails; no preceding \n
-\end{verbatim}
-
-
-\subsection{Module Contents}
-\nodename{Contents of Module re}
-
-The module defines several functions, constants, and an exception. Some of the
-functions are simplified versions of the full featured methods for compiled
-regular expressions. Most non-trivial applications always use the compiled
-form.
-
-\begin{funcdesc}{compile}{pattern\optional{, flags}}
- Compile a regular expression pattern into a regular expression
- object, which can be used for matching using its \function{match()} and
- \function{search()} methods, described below.
-
- The expression's behaviour can be modified by specifying a
- \var{flags} value. Values can be any of the following variables,
- combined using bitwise OR (the \code{|} operator).
-
-The sequence
-
-\begin{verbatim}
-prog = re.compile(pat)
-result = prog.match(str)
-\end{verbatim}
-
-is equivalent to
-
-\begin{verbatim}
-result = re.match(pat, str)
-\end{verbatim}
-
-but the version using \function{compile()} is more efficient when the
-expression will be used several times in a single program.
-%(The compiled version of the last pattern passed to
-%\function{re.match()} or \function{re.search()} is cached, so
-%programs that use only a single regular expression at a time needn't
-%worry about compiling regular expressions.)
-\end{funcdesc}
-
-\begin{datadesc}{I}
-\dataline{IGNORECASE}
-Perform case-insensitive matching; expressions like \regexp{[A-Z]}
-will match lowercase letters, too. This is not affected by the
-current locale.
-\end{datadesc}
-
-\begin{datadesc}{L}
-\dataline{LOCALE}
-Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b}, \regexp{\e B},
-\regexp{\e s} and \regexp{\e S} dependent on the current locale.
-\end{datadesc}
-
-\begin{datadesc}{M}
-\dataline{MULTILINE}
-When specified, the pattern character \character{\textasciicircum}
-matches at the beginning of the string and at the beginning of each
-line (immediately following each newline); and the pattern character
-\character{\$} matches at the end of the string and at the end of each
-line (immediately preceding each newline). By default,
-\character{\textasciicircum} matches only at the beginning of the
-string, and \character{\$} only at the end of the string and
-immediately before the newline (if any) at the end of the string.
-\end{datadesc}
-
-\begin{datadesc}{S}
-\dataline{DOTALL}
-Make the \character{.} special character match any character at all,
-including a newline; without this flag, \character{.} will match
-anything \emph{except} a newline.
-\end{datadesc}
-
-\begin{datadesc}{U}
-\dataline{UNICODE}
-Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b}, \regexp{\e B},
-\regexp{\e d}, \regexp{\e D}, \regexp{\e s} and \regexp{\e S}
-dependent on the Unicode character properties database.
-\versionadded{2.0}
-\end{datadesc}
-
-\begin{datadesc}{X}
-\dataline{VERBOSE}
-This flag allows you to write regular expressions that look nicer.
-Whitespace within the pattern is ignored,
-except when in a character class or preceded by an unescaped
-backslash, and, when a line contains a \character{\#} neither in a
-character class or preceded by an unescaped backslash, all characters
-from the leftmost such \character{\#} through the end of the line are
-ignored.
-% XXX should add an example here
-\end{datadesc}
-
-
-\begin{funcdesc}{search}{pattern, string\optional{, flags}}
- Scan through \var{string} looking for a location where the regular
- expression \var{pattern} produces a match, and return a
- corresponding \class{MatchObject} instance.
- Return \code{None} if no
- position in the string matches the pattern; note that this is
- different from finding a zero-length match at some point in the string.
-\end{funcdesc}
-
-\begin{funcdesc}{match}{pattern, string\optional{, flags}}
- If zero or more characters at the beginning of \var{string} match
- the regular expression \var{pattern}, return a corresponding
- \class{MatchObject} instance. Return \code{None} if the string does not
- match the pattern; note that this is different from a zero-length
- match.
-
- \note{If you want to locate a match anywhere in
- \var{string}, use \method{search()} instead.}
-\end{funcdesc}
-
-\begin{funcdesc}{split}{pattern, string\optional{, maxsplit\code{ = 0}}}
- Split \var{string} by the occurrences of \var{pattern}. If
- capturing parentheses are used in \var{pattern}, then the text of all
- groups in the pattern are also returned as part of the resulting list.
- If \var{maxsplit} is nonzero, at most \var{maxsplit} splits
- occur, and the remainder of the string is returned as the final
- element of the list. (Incompatibility note: in the original Python
- 1.5 release, \var{maxsplit} was ignored. This has been fixed in
- later releases.)
-
-\begin{verbatim}
->>> 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.']
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{findall}{pattern, string\optional{, flags}}
- Return a list of all non-overlapping matches of \var{pattern} in
- \var{string}. If one or more groups are present in the pattern,
- return a list of groups; this will be a list of tuples if the
- pattern has more than one group. Empty matches are included in the
- result unless they touch the beginning of another match.
- \versionadded{1.5.2}
- \versionchanged[Added the optional flags argument]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{finditer}{pattern, string\optional{, flags}}
- Return an iterator over all non-overlapping matches for the RE
- \var{pattern} in \var{string}. For each match, the iterator returns
- a match object. Empty matches are included in the result unless they
- touch the beginning of another match.
- \versionadded{2.2}
- \versionchanged[Added the optional flags argument]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{sub}{pattern, repl, string\optional{, count}}
- Return the string obtained by replacing the leftmost non-overlapping
- occurrences of \var{pattern} in \var{string} by the replacement
- \var{repl}. If the pattern isn't found, \var{string} is returned
- unchanged. \var{repl} can be a string or a function; if it is a
- string, any backslash escapes in it are processed. That is,
- \samp{\e n} is converted to a single newline character, \samp{\e r}
- is converted to a linefeed, and so forth. Unknown escapes such as
- \samp{\e j} are left alone. Backreferences, such as \samp{\e6}, are
- replaced with the substring matched by group 6 in the pattern. For
- example:
-
-\begin{verbatim}
->>> re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):',
-... r'static PyObject*\npy_\1(void)\n{',
-... 'def myfunc():')
-'static PyObject*\npy_myfunc(void)\n{'
-\end{verbatim}
-
- If \var{repl} is a function, it is called for every non-overlapping
- occurrence of \var{pattern}. The function takes a single match
- object argument, and returns the replacement string. For example:
-
-\begin{verbatim}
->>> def dashrepl(matchobj):
-... if matchobj.group(0) == '-': return ' '
-... else: return '-'
->>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
-'pro--gram files'
-\end{verbatim}
-
- The pattern may be a string or an RE object; if you need to specify
- regular expression flags, you must use a RE object, or use embedded
- modifiers in a pattern; for example, \samp{sub("(?i)b+", "x", "bbbb
- BBBB")} returns \code{'x x'}.
-
- The optional argument \var{count} is the maximum number of pattern
- occurrences to be replaced; \var{count} must be a non-negative
- integer. If omitted or zero, all occurrences will be replaced.
- Empty matches for the pattern are replaced only when not adjacent to
- a previous match, so \samp{sub('x*', '-', 'abc')} returns
- \code{'-a-b-c-'}.
-
- In addition to character escapes and backreferences as described
- above, \samp{\e g<name>} will use the substring matched by the group
- named \samp{name}, as defined by the \regexp{(?P<name>...)} syntax.
- \samp{\e g<number>} uses the corresponding group number;
- \samp{\e g<2>} is therefore equivalent to \samp{\e 2}, but isn't
- ambiguous in a replacement such as \samp{\e g<2>0}. \samp{\e 20}
- would be interpreted as a reference to group 20, not a reference to
- group 2 followed by the literal character \character{0}. The
- backreference \samp{\e g<0>} substitutes in the entire substring
- matched by the RE.
-\end{funcdesc}
-
-\begin{funcdesc}{subn}{pattern, repl, string\optional{, count}}
- Perform the same operation as \function{sub()}, but return a tuple
- \code{(\var{new_string}, \var{number_of_subs_made})}.
-\end{funcdesc}
-
-\begin{funcdesc}{escape}{string}
- Return \var{string} with all non-alphanumerics backslashed; this is
- useful if you want to match an arbitrary literal string that may have
- regular expression metacharacters in it.
-\end{funcdesc}
-
-\begin{excdesc}{error}
- Exception raised when a string passed to one of the functions here
- is not a valid regular expression (for example, it might contain
- unmatched parentheses) or when some other error occurs during
- compilation or matching. It is never an error if a string contains
- no match for a pattern.
-\end{excdesc}
-
-
-\subsection{Regular Expression Objects \label{re-objects}}
-
-Compiled regular expression objects support the following methods and
-attributes:
-
-\begin{methoddesc}[RegexObject]{match}{string\optional{, pos\optional{,
- endpos}}}
- If zero or more characters at the beginning of \var{string} match
- this regular expression, return a corresponding
- \class{MatchObject} instance. Return \code{None} if the string does not
- match the pattern; note that this is different from a zero-length
- match.
-
- \note{If you want to locate a match anywhere in
- \var{string}, use \method{search()} instead.}
-
- The optional second parameter \var{pos} gives an index in the string
- where the search is to start; it defaults to \code{0}. This is not
- completely equivalent to slicing the string; the
- \code{'\textasciicircum'} pattern
- character matches at the real beginning of the string and at positions
- just after a newline, but not necessarily at the index where the search
- is to start.
-
- The optional parameter \var{endpos} limits how far the string will
- be searched; it will be as if the string is \var{endpos} characters
- long, so only the characters from \var{pos} to \code{\var{endpos} -
- 1} will be searched for a match. If \var{endpos} is less than
- \var{pos}, no match will be found, otherwise, if \var{rx} is a
- compiled regular expression object,
- \code{\var{rx}.match(\var{string}, 0, 50)} is equivalent to
- \code{\var{rx}.match(\var{string}[:50], 0)}.
-\end{methoddesc}
-
-\begin{methoddesc}[RegexObject]{search}{string\optional{, pos\optional{,
- endpos}}}
- Scan through \var{string} looking for a location where this regular
- expression produces a match, and return a
- corresponding \class{MatchObject} instance. Return \code{None} if no
- position in the string matches the pattern; note that this is
- different from finding a zero-length match at some point in the string.
-
- The optional \var{pos} and \var{endpos} parameters have the same
- meaning as for the \method{match()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[RegexObject]{split}{string\optional{,
- maxsplit\code{ = 0}}}
-Identical to the \function{split()} function, using the compiled pattern.
-\end{methoddesc}
-
-\begin{methoddesc}[RegexObject]{findall}{string\optional{, pos\optional{,
- endpos}}}
-Identical to the \function{findall()} function, using the compiled pattern.
-\end{methoddesc}
-
-\begin{methoddesc}[RegexObject]{finditer}{string\optional{, pos\optional{,
- endpos}}}
-Identical to the \function{finditer()} function, using the compiled pattern.
-\end{methoddesc}
-
-\begin{methoddesc}[RegexObject]{sub}{repl, string\optional{, count\code{ = 0}}}
-Identical to the \function{sub()} function, using the compiled pattern.
-\end{methoddesc}
-
-\begin{methoddesc}[RegexObject]{subn}{repl, string\optional{,
- count\code{ = 0}}}
-Identical to the \function{subn()} function, using the compiled pattern.
-\end{methoddesc}
-
-
-\begin{memberdesc}[RegexObject]{flags}
-The flags argument used when the RE object was compiled, or
-\code{0} if no flags were provided.
-\end{memberdesc}
-
-\begin{memberdesc}[RegexObject]{groupindex}
-A dictionary mapping any symbolic group names defined by
-\regexp{(?P<\var{id}>)} to group numbers. The dictionary is empty if no
-symbolic groups were used in the pattern.
-\end{memberdesc}
-
-\begin{memberdesc}[RegexObject]{pattern}
-The pattern string from which the RE object was compiled.
-\end{memberdesc}
-
-
-\subsection{Match Objects \label{match-objects}}
-
-\class{MatchObject} instances support the following methods and
-attributes:
-
-\begin{methoddesc}[MatchObject]{expand}{template}
- Return the string obtained by doing backslash substitution on the
-template string \var{template}, as done by the \method{sub()} method.
-Escapes such as \samp{\e n} are converted to the appropriate
-characters, and numeric backreferences (\samp{\e 1}, \samp{\e 2}) and
-named backreferences (\samp{\e g<1>}, \samp{\e g<name>}) are replaced
-by the contents of the corresponding group.
-\end{methoddesc}
-
-\begin{methoddesc}[MatchObject]{group}{\optional{group1, \moreargs}}
-Returns one or more subgroups of the match. If there is a single
-argument, the result is a single string; if there are
-multiple arguments, the result is a tuple with one item per argument.
-Without arguments, \var{group1} defaults to zero (the whole match
-is returned).
-If a \var{groupN} argument is zero, the corresponding return value is the
-entire matching string; if it is in the inclusive range [1..99], it is
-the string matching the corresponding parenthesized group. If a
-group number is negative or larger than the number of groups defined
-in the pattern, an \exception{IndexError} exception is raised.
-If a group is contained in a part of the pattern that did not match,
-the corresponding result is \code{None}. If a group is contained in a
-part of the pattern that matched multiple times, the last match is
-returned.
-
-If the regular expression uses the \regexp{(?P<\var{name}>...)} syntax,
-the \var{groupN} arguments may also be strings identifying groups by
-their group name. If a string argument is not used as a group name in
-the pattern, an \exception{IndexError} exception is raised.
-
-A moderately complicated example:
-
-\begin{verbatim}
-m = re.match(r"(?P<int>\d+)\.(\d*)", '3.14')
-\end{verbatim}
-
-After performing this match, \code{m.group(1)} is \code{'3'}, as is
-\code{m.group('int')}, and \code{m.group(2)} is \code{'14'}.
-\end{methoddesc}
-
-\begin{methoddesc}[MatchObject]{groups}{\optional{default}}
-Return a tuple containing all the subgroups of the match, from 1 up to
-however many groups are in the pattern. The \var{default} argument is
-used for groups that did not participate in the match; it defaults to
-\code{None}. (Incompatibility note: in the original Python 1.5
-release, if the tuple was one element long, a string would be returned
-instead. In later versions (from 1.5.1 on), a singleton tuple is
-returned in such cases.)
-\end{methoddesc}
-
-\begin{methoddesc}[MatchObject]{groupdict}{\optional{default}}
-Return a dictionary containing all the \emph{named} subgroups of the
-match, keyed by the subgroup name. The \var{default} argument is
-used for groups that did not participate in the match; it defaults to
-\code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[MatchObject]{start}{\optional{group}}
-\methodline[MatchObject]{end}{\optional{group}}
-Return the indices of the start and end of the substring
-matched by \var{group}; \var{group} defaults to zero (meaning the whole
-matched substring).
-Return \code{-1} if \var{group} exists but
-did not contribute to the match. For a match object
-\var{m}, and a group \var{g} that did contribute to the match, the
-substring matched by group \var{g} (equivalent to
-\code{\var{m}.group(\var{g})}) is
-
-\begin{verbatim}
-m.string[m.start(g):m.end(g)]
-\end{verbatim}
-
-Note that
-\code{m.start(\var{group})} will equal \code{m.end(\var{group})} if
-\var{group} matched a null string. For example, after \code{\var{m} =
-re.search('b(c?)', 'cba')}, \code{\var{m}.start(0)} is 1,
-\code{\var{m}.end(0)} is 2, \code{\var{m}.start(1)} and
-\code{\var{m}.end(1)} are both 2, and \code{\var{m}.start(2)} raises
-an \exception{IndexError} exception.
-\end{methoddesc}
-
-\begin{methoddesc}[MatchObject]{span}{\optional{group}}
-For \class{MatchObject} \var{m}, return the 2-tuple
-\code{(\var{m}.start(\var{group}), \var{m}.end(\var{group}))}.
-Note that if \var{group} did not contribute to the match, this is
-\code{(-1, -1)}. Again, \var{group} defaults to zero.
-\end{methoddesc}
-
-\begin{memberdesc}[MatchObject]{pos}
-The value of \var{pos} which was passed to the \function{search()} or
-\function{match()} method of the \class{RegexObject}. This is the
-index into the string at which the RE engine started looking for a
-match.
-\end{memberdesc}
-
-\begin{memberdesc}[MatchObject]{endpos}
-The value of \var{endpos} which was passed to the \function{search()}
-or \function{match()} method of the \class{RegexObject}. This is the
-index into the string beyond which the RE engine will not go.
-\end{memberdesc}
-
-\begin{memberdesc}[MatchObject]{lastindex}
-The integer index of the last matched capturing group, or \code{None}
-if no group was matched at all. For example, the expressions
-\regexp{(a)b}, \regexp{((a)(b))}, and \regexp{((ab))} will have
-\code{lastindex == 1} if applied to the string \code{'ab'},
-while the expression \regexp{(a)(b)} will have \code{lastindex == 2},
-if applied to the same string.
-\end{memberdesc}
-
-\begin{memberdesc}[MatchObject]{lastgroup}
-The name of the last matched capturing group, or \code{None} if the
-group didn't have a name, or if no group was matched at all.
-\end{memberdesc}
-
-\begin{memberdesc}[MatchObject]{re}
-The regular expression object whose \method{match()} or
-\method{search()} method produced this \class{MatchObject} instance.
-\end{memberdesc}
-
-\begin{memberdesc}[MatchObject]{string}
-The string passed to \function{match()} or \function{search()}.
-\end{memberdesc}
-
-\subsection{Examples}
-
-\leftline{\strong{Simulating \cfunction{scanf()}}}
-
-Python does not currently have an equivalent to \cfunction{scanf()}.
-\ttindex{scanf()}
-Regular expressions are generally more powerful, though also more
-verbose, than \cfunction{scanf()} format strings. The table below
-offers some more-or-less equivalent mappings between
-\cfunction{scanf()} format tokens and regular expressions.
-
-\begin{tableii}{l|l}{textrm}{\cfunction{scanf()} Token}{Regular Expression}
- \lineii{\code{\%c}}
- {\regexp{.}}
- \lineii{\code{\%5c}}
- {\regexp{.\{5\}}}
- \lineii{\code{\%d}}
- {\regexp{[-+]?\e d+}}
- \lineii{\code{\%e}, \code{\%E}, \code{\%f}, \code{\%g}}
- {\regexp{[-+]?(\e d+(\e.\e d*)?|\e.\e d+)([eE][-+]?\e d+)?}}
- \lineii{\code{\%i}}
- {\regexp{[-+]?(0[xX][\e dA-Fa-f]+|0[0-7]*|\e d+)}}
- \lineii{\code{\%o}}
- {\regexp{0[0-7]*}}
- \lineii{\code{\%s}}
- {\regexp{\e S+}}
- \lineii{\code{\%u}}
- {\regexp{\e d+}}
- \lineii{\code{\%x}, \code{\%X}}
- {\regexp{0[xX][\e dA-Fa-f]+}}
-\end{tableii}
-
-To extract the filename and numbers from a string like
-
-\begin{verbatim}
- /usr/sbin/sendmail - 0 errors, 4 warnings
-\end{verbatim}
-
-you would use a \cfunction{scanf()} format like
-
-\begin{verbatim}
- %s - %d errors, %d warnings
-\end{verbatim}
-
-The equivalent regular expression would be
-
-\begin{verbatim}
- (\S+) - (\d+) errors, (\d+) warnings
-\end{verbatim}
-
-\leftline{\strong{Avoiding recursion}}
-
-If you create regular expressions that require the engine to perform a
-lot of recursion, you may encounter a \exception{RuntimeError} exception with
-the message \code{maximum recursion limit} exceeded. For example,
-
-\begin{verbatim}
->>> import re
->>> s = 'Begin ' + 1000*'a very long string ' + 'end'
->>> re.match('Begin (\w| )*? end', s).end()
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
- File "/usr/local/lib/python2.5/re.py", line 132, in match
- return _compile(pattern, flags).match(string)
-RuntimeError: maximum recursion limit exceeded
-\end{verbatim}
-
-You can often restructure your regular expression to avoid recursion.
-
-Starting with Python 2.3, simple uses of the \regexp{*?} pattern are
-special-cased to avoid recursion. Thus, the above regular expression
-can avoid recursion by being recast as
-\regexp{Begin [a-zA-Z0-9_ ]*?end}. As a further benefit, such regular
-expressions will run faster than their recursive equivalents.
diff --git a/Doc/lib/libreadline.tex b/Doc/lib/libreadline.tex
deleted file mode 100644
index dec37b6..0000000
--- a/Doc/lib/libreadline.tex
+++ /dev/null
@@ -1,196 +0,0 @@
-\section{\module{readline} ---
- GNU readline interface}
-
-\declaremodule{builtin}{readline}
- \platform{Unix}
-\sectionauthor{Skip Montanaro}{skip@mojam.com}
-\modulesynopsis{GNU readline support for Python.}
-
-
-The \module{readline} module defines a number of functions to
-facilitate completion and reading/writing of history files from the
-Python interpreter. This module can be used directly or via the
-\refmodule{rlcompleter} module. Settings made using
-this module affect the behaviour of both the interpreter's interactive prompt
-and the prompts offered by the \function{raw_input()} and \function{input()}
-built-in functions.
-
-The \module{readline} module defines the following functions:
-
-
-\begin{funcdesc}{parse_and_bind}{string}
-Parse and execute single line of a readline init file.
-\end{funcdesc}
-
-\begin{funcdesc}{get_line_buffer}{}
-Return the current contents of the line buffer.
-\end{funcdesc}
-
-\begin{funcdesc}{insert_text}{string}
-Insert text into the command line.
-\end{funcdesc}
-
-\begin{funcdesc}{read_init_file}{\optional{filename}}
-Parse a readline initialization file.
-The default filename is the last filename used.
-\end{funcdesc}
-
-\begin{funcdesc}{read_history_file}{\optional{filename}}
-Load a readline history file.
-The default filename is \file{\~{}/.history}.
-\end{funcdesc}
-
-\begin{funcdesc}{write_history_file}{\optional{filename}}
-Save a readline history file.
-The default filename is \file{\~{}/.history}.
-\end{funcdesc}
-
-\begin{funcdesc}{clear_history}{}
-Clear the current history. (Note: this function is not available if
-the installed version of GNU readline doesn't support it.)
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{get_history_length}{}
-Return the desired length of the history file. Negative values imply
-unlimited history file size.
-\end{funcdesc}
-
-\begin{funcdesc}{set_history_length}{length}
-Set the number of lines to save in the history file.
-\function{write_history_file()} uses this value to truncate the
-history file when saving. Negative values imply unlimited history
-file size.
-\end{funcdesc}
-
-\begin{funcdesc}{get_current_history_length}{}
-Return the number of lines currently in the history. (This is different
-from \function{get_history_length()}, which returns the maximum number of
-lines that will be written to a history file.) \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{get_history_item}{index}
-Return the current contents of history item at \var{index}.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{remove_history_item}{pos}
-Remove history item specified by its position from the history.
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{replace_history_item}{pos, line}
-Replace history item specified by its position with the given line.
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{redisplay}{}
-Change what's displayed on the screen to reflect the current contents
-of the line buffer. \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{set_startup_hook}{\optional{function}}
-Set or remove the startup_hook function. If \var{function} is specified,
-it will be used as the new startup_hook function; if omitted or
-\code{None}, any hook function already installed is removed. The
-startup_hook function is called with no arguments just
-before readline prints the first prompt.
-\end{funcdesc}
-
-\begin{funcdesc}{set_pre_input_hook}{\optional{function}}
-Set or remove the pre_input_hook function. If \var{function} is specified,
-it will be used as the new pre_input_hook function; if omitted or
-\code{None}, any hook function already installed is removed. The
-pre_input_hook function is called with no arguments after the first prompt
-has been printed and just before readline starts reading input characters.
-\end{funcdesc}
-
-\begin{funcdesc}{set_completer}{\optional{function}}
-Set or remove the completer function. If \var{function} is specified,
-it will be used as the new completer function; if omitted or
-\code{None}, any completer function already installed is removed. The
-completer function is called as \code{\var{function}(\var{text},
-\var{state})}, for \var{state} in \code{0}, \code{1}, \code{2}, ...,
-until it returns a non-string value. It should return the next
-possible completion starting with \var{text}.
-\end{funcdesc}
-
-\begin{funcdesc}{get_completer}{}
-Get the completer function, or \code{None} if no completer function
-has been set. \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{get_begidx}{}
-Get the beginning index of the readline tab-completion scope.
-\end{funcdesc}
-
-\begin{funcdesc}{get_endidx}{}
-Get the ending index of the readline tab-completion scope.
-\end{funcdesc}
-
-\begin{funcdesc}{set_completer_delims}{string}
-Set the readline word delimiters for tab-completion.
-\end{funcdesc}
-
-\begin{funcdesc}{get_completer_delims}{}
-Get the readline word delimiters for tab-completion.
-\end{funcdesc}
-
-\begin{funcdesc}{add_history}{line}
-Append a line to the history buffer, as if it was the last line typed.
-\end{funcdesc}
-
-\begin{seealso}
- \seemodule{rlcompleter}{Completion of Python identifiers at the
- interactive prompt.}
-\end{seealso}
-
-
-\subsection{Example \label{readline-example}}
-
-The following example demonstrates how to use the
-\module{readline} module's history reading and writing functions to
-automatically load and save a history file named \file{.pyhist} from
-the user's home directory. The code below would normally be executed
-automatically during interactive sessions from the user's
-\envvar{PYTHONSTARTUP} file.
-
-\begin{verbatim}
-import os
-histfile = os.path.join(os.environ["HOME"], ".pyhist")
-try:
- readline.read_history_file(histfile)
-except IOError:
- pass
-import atexit
-atexit.register(readline.write_history_file, histfile)
-del os, histfile
-\end{verbatim}
-
-The following example extends the \class{code.InteractiveConsole} class to
-support history save/restore.
-
-\begin{verbatim}
-import code
-import readline
-import atexit
-import os
-
-class HistoryConsole(code.InteractiveConsole):
- def __init__(self, locals=None, filename="<console>",
- histfile=os.path.expanduser("~/.console-history")):
- code.InteractiveConsole.__init__(self)
- self.init_history(histfile)
-
- def init_history(self, histfile):
- readline.parse_and_bind("tab: complete")
- if hasattr(readline, "read_history_file"):
- try:
- readline.read_history_file(histfile)
- except IOError:
- pass
- atexit.register(self.save_history, histfile)
-
- def save_history(self, histfile):
- readline.write_history_file(histfile)
-\end{verbatim}
diff --git a/Doc/lib/librepr.tex b/Doc/lib/librepr.tex
deleted file mode 100644
index 2876448..0000000
--- a/Doc/lib/librepr.tex
+++ /dev/null
@@ -1,133 +0,0 @@
-\section{\module{repr} ---
- Alternate \function{repr()} implementation}
-
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\declaremodule{standard}{repr}
-\modulesynopsis{Alternate \function{repr()} implementation with size limits.}
-
-
-The \module{repr} module provides a means for producing object
-representations with limits on the size of the resulting strings.
-This is used in the Python debugger and may be useful in other
-contexts as well.
-
-This module provides a class, an instance, and a function:
-
-
-\begin{classdesc}{Repr}{}
- Class which provides formatting services useful in implementing
- functions similar to the built-in \function{repr()}; size limits for
- different object types are added to avoid the generation of
- representations which are excessively long.
-\end{classdesc}
-
-
-\begin{datadesc}{aRepr}
- This is an instance of \class{Repr} which is used to provide the
- \function{repr()} function described below. Changing the attributes
- of this object will affect the size limits used by \function{repr()}
- and the Python debugger.
-\end{datadesc}
-
-
-\begin{funcdesc}{repr}{obj}
- This is the \method{repr()} method of \code{aRepr}. It returns a
- string similar to that returned by the built-in function of the same
- name, but with limits on most sizes.
-\end{funcdesc}
-
-
-\subsection{Repr Objects \label{Repr-objects}}
-
-\class{Repr} instances provide several members which can be used to
-provide size limits for the representations of different object types,
-and methods which format specific object types.
-
-
-\begin{memberdesc}[Repr]{maxlevel}
- Depth limit on the creation of recursive representations. The
- default is \code{6}.
-\end{memberdesc}
-
-\begin{memberdesc}[Repr]{maxdict}
-\memberline[Repr]{maxlist}
-\memberline[Repr]{maxtuple}
-\memberline[Repr]{maxset}
-\memberline[Repr]{maxfrozenset}
-\memberline[Repr]{maxdeque}
-\memberline[Repr]{maxarray}
- Limits on the number of entries represented for the named object
- type. The default is \code{4} for \member{maxdict}, \code{5} for
- \member{maxarray}, and \code{6} for the others.
- \versionadded[\member{maxset}, \member{maxfrozenset},
- and \member{set}]{2.4}.
-\end{memberdesc}
-
-\begin{memberdesc}[Repr]{maxlong}
- Maximum number of characters in the representation for a long
- integer. Digits are dropped from the middle. The default is
- \code{40}.
-\end{memberdesc}
-
-\begin{memberdesc}[Repr]{maxstring}
- Limit on the number of characters in the representation of the
- string. Note that the ``normal'' representation of the string is
- used as the character source: if escape sequences are needed in the
- representation, these may be mangled when the representation is
- shortened. The default is \code{30}.
-\end{memberdesc}
-
-\begin{memberdesc}[Repr]{maxother}
- This limit is used to control the size of object types for which no
- specific formatting method is available on the \class{Repr} object.
- It is applied in a similar manner as \member{maxstring}. The
- default is \code{20}.
-\end{memberdesc}
-
-\begin{methoddesc}[Repr]{repr}{obj}
- The equivalent to the built-in \function{repr()} that uses the
- formatting imposed by the instance.
-\end{methoddesc}
-
-\begin{methoddesc}[Repr]{repr1}{obj, level}
- Recursive implementation used by \method{repr()}. This uses the
- type of \var{obj} to determine which formatting method to call,
- passing it \var{obj} and \var{level}. The type-specific methods
- should call \method{repr1()} to perform recursive formatting, with
- \code{\var{level} - 1} for the value of \var{level} in the recursive
- call.
-\end{methoddesc}
-
-\begin{methoddescni}[Repr]{repr_\var{type}}{obj, level}
- Formatting methods for specific types are implemented as methods
- with a name based on the type name. In the method name, \var{type}
- is replaced by
- \code{string.join(string.split(type(\var{obj}).__name__, '_'))}.
- Dispatch to these methods is handled by \method{repr1()}.
- Type-specific methods which need to recursively format a value
- should call \samp{self.repr1(\var{subobj}, \var{level} - 1)}.
-\end{methoddescni}
-
-
-\subsection{Subclassing Repr Objects \label{subclassing-reprs}}
-
-The use of dynamic dispatching by \method{Repr.repr1()} allows
-subclasses of \class{Repr} to add support for additional built-in
-object types or to modify the handling of types already supported.
-This example shows how special support for file objects could be
-added:
-
-\begin{verbatim}
-import repr
-import sys
-
-class MyRepr(repr.Repr):
- def repr_file(self, obj, level):
- if obj.name in ['<stdin>', '<stdout>', '<stderr>']:
- return obj.name
- else:
- return `obj`
-
-aRepr = MyRepr()
-print aRepr.repr(sys.stdin) # prints '<stdin>'
-\end{verbatim}
diff --git a/Doc/lib/libresource.tex b/Doc/lib/libresource.tex
deleted file mode 100644
index 8e102b8..0000000
--- a/Doc/lib/libresource.tex
+++ /dev/null
@@ -1,215 +0,0 @@
-\section{\module{resource} ---
- Resource usage information}
-
-\declaremodule{builtin}{resource}
- \platform{Unix}
-\modulesynopsis{An interface to provide resource usage information on
- the current process.}
-\moduleauthor{Jeremy Hylton}{jeremy@alum.mit.edu}
-\sectionauthor{Jeremy Hylton}{jeremy@alum.mit.edu}
-
-
-This module provides basic mechanisms for measuring and controlling
-system resources utilized by a program.
-
-Symbolic constants are used to specify particular system resources and
-to request usage information about either the current process or its
-children.
-
-A single exception is defined for errors:
-
-
-\begin{excdesc}{error}
- The functions described below may raise this error if the underlying
- system call failures unexpectedly.
-\end{excdesc}
-
-\subsection{Resource Limits}
-
-Resources usage can be limited using the \function{setrlimit()} function
-described below. Each resource is controlled by a pair of limits: a
-soft limit and a hard limit. The soft limit is the current limit, and
-may be lowered or raised by a process over time. The soft limit can
-never exceed the hard limit. The hard limit can be lowered to any
-value greater than the soft limit, but not raised. (Only processes with
-the effective UID of the super-user can raise a hard limit.)
-
-The specific resources that can be limited are system dependent. They
-are described in the \manpage{getrlimit}{2} man page. The resources
-listed below are supported when the underlying operating system
-supports them; resources which cannot be checked or controlled by the
-operating system are not defined in this module for those platforms.
-
-\begin{funcdesc}{getrlimit}{resource}
- Returns a tuple \code{(\var{soft}, \var{hard})} with the current
- soft and hard limits of \var{resource}. Raises \exception{ValueError} if
- an invalid resource is specified, or \exception{error} if the
- underlying system call fails unexpectedly.
-\end{funcdesc}
-
-\begin{funcdesc}{setrlimit}{resource, limits}
- Sets new limits of consumption of \var{resource}. The \var{limits}
- argument must be a tuple \code{(\var{soft}, \var{hard})} of two
- integers describing the new limits. A value of \code{-1} can be used to
- specify the maximum possible upper limit.
-
- Raises \exception{ValueError} if an invalid resource is specified,
- if the new soft limit exceeds the hard limit, or if a process tries
- to raise its hard limit (unless the process has an effective UID of
- super-user). Can also raise \exception{error} if the underlying
- system call fails.
-\end{funcdesc}
-
-These symbols define resources whose consumption can be controlled
-using the \function{setrlimit()} and \function{getrlimit()} functions
-described below. The values of these symbols are exactly the constants
-used by \C{} programs.
-
-The \UNIX{} man page for \manpage{getrlimit}{2} lists the available
-resources. Note that not all systems use the same symbol or same
-value to denote the same resource. This module does not attempt to
-mask platform differences --- symbols not defined for a platform will
-not be available from this module on that platform.
-
-\begin{datadesc}{RLIMIT_CORE}
- The maximum size (in bytes) of a core file that the current process
- can create. This may result in the creation of a partial core file
- if a larger core would be required to contain the entire process
- image.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_CPU}
- The maximum amount of processor time (in seconds) that a process can
- use. If this limit is exceeded, a \constant{SIGXCPU} signal is sent to
- the process. (See the \refmodule{signal} module documentation for
- information about how to catch this signal and do something useful,
- e.g. flush open files to disk.)
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_FSIZE}
- The maximum size of a file which the process may create. This only
- affects the stack of the main thread in a multi-threaded process.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_DATA}
- The maximum size (in bytes) of the process's heap.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_STACK}
- The maximum size (in bytes) of the call stack for the current
- process.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_RSS}
- The maximum resident set size that should be made available to the
- process.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_NPROC}
- The maximum number of processes the current process may create.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_NOFILE}
- The maximum number of open file descriptors for the current
- process.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_OFILE}
- The BSD name for \constant{RLIMIT_NOFILE}.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_MEMLOCK}
- The maximum address space which may be locked in memory.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_VMEM}
- The largest area of mapped memory which the process may occupy.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_AS}
- The maximum area (in bytes) of address space which may be taken by
- the process.
-\end{datadesc}
-
-\subsection{Resource Usage}
-
-These functions are used to retrieve resource usage information:
-
-\begin{funcdesc}{getrusage}{who}
- This function returns an object that describes the resources
- consumed by either the current process or its children, as specified
- by the \var{who} parameter. The \var{who} parameter should be
- specified using one of the \constant{RUSAGE_*} constants described
- below.
-
- The fields of the return value each describe how a particular system
- resource has been used, e.g. amount of time spent running is user mode
- or number of times the process was swapped out of main memory. Some
- values are dependent on the clock tick internal, e.g. the amount of
- memory the process is using.
-
- For backward compatibility, the return value is also accessible as
- a tuple of 16 elements.
-
- The fields \member{ru_utime} and \member{ru_stime} of the return value
- are floating point values representing the amount of time spent
- executing in user mode and the amount of time spent executing in system
- mode, respectively. The remaining values are integers. Consult the
- \manpage{getrusage}{2} man page for detailed information about these
- values. A brief summary is presented here:
-
-\begin{tableiii}{r|l|l}{code}{Index}{Field}{Resource}
- \lineiii{0}{\member{ru_utime}}{time in user mode (float)}
- \lineiii{1}{\member{ru_stime}}{time in system mode (float)}
- \lineiii{2}{\member{ru_maxrss}}{maximum resident set size}
- \lineiii{3}{\member{ru_ixrss}}{shared memory size}
- \lineiii{4}{\member{ru_idrss}}{unshared memory size}
- \lineiii{5}{\member{ru_isrss}}{unshared stack size}
- \lineiii{6}{\member{ru_minflt}}{page faults not requiring I/O}
- \lineiii{7}{\member{ru_majflt}}{page faults requiring I/O}
- \lineiii{8}{\member{ru_nswap}}{number of swap outs}
- \lineiii{9}{\member{ru_inblock}}{block input operations}
- \lineiii{10}{\member{ru_oublock}}{block output operations}
- \lineiii{11}{\member{ru_msgsnd}}{messages sent}
- \lineiii{12}{\member{ru_msgrcv}}{messages received}
- \lineiii{13}{\member{ru_nsignals}}{signals received}
- \lineiii{14}{\member{ru_nvcsw}}{voluntary context switches}
- \lineiii{15}{\member{ru_nivcsw}}{involuntary context switches}
-\end{tableiii}
-
- This function will raise a \exception{ValueError} if an invalid
- \var{who} parameter is specified. It may also raise
- \exception{error} exception in unusual circumstances.
-
- \versionchanged[Added access to values as attributes of the
- returned object]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getpagesize}{}
- Returns the number of bytes in a system page. (This need not be the
- same as the hardware page size.) This function is useful for
- determining the number of bytes of memory a process is using. The
- third element of the tuple returned by \function{getrusage()} describes
- memory usage in pages; multiplying by page size produces number of
- bytes.
-\end{funcdesc}
-
-The following \constant{RUSAGE_*} symbols are passed to the
-\function{getrusage()} function to specify which processes information
-should be provided for.
-
-\begin{datadesc}{RUSAGE_SELF}
- \constant{RUSAGE_SELF} should be used to
- request information pertaining only to the process itself.
-\end{datadesc}
-
-\begin{datadesc}{RUSAGE_CHILDREN}
- Pass to \function{getrusage()} to request resource information for
- child processes of the calling process.
-\end{datadesc}
-
-\begin{datadesc}{RUSAGE_BOTH}
- Pass to \function{getrusage()} to request resources consumed by both
- the current process and child processes. May not be available on all
- systems.
-\end{datadesc}
diff --git a/Doc/lib/librfc822.tex b/Doc/lib/librfc822.tex
deleted file mode 100644
index b59e6ad..0000000
--- a/Doc/lib/librfc822.tex
+++ /dev/null
@@ -1,336 +0,0 @@
-\section{\module{rfc822} ---
- Parse RFC 2822 mail headers}
-
-\declaremodule{standard}{rfc822}
-\modulesynopsis{Parse \rfc{2822} style mail messages.}
-
-\deprecated{2.3}{The \refmodule{email} package should be used in
- preference to the \module{rfc822} module. This
- module is present only to maintain backward
- compatibility.}
-
-This module defines a class, \class{Message}, which represents an
-``email message'' as defined by the Internet standard
-\rfc{2822}.\footnote{This module originally conformed to \rfc{822},
-hence the name. Since then, \rfc{2822} has been released as an
-update to \rfc{822}. This module should be considered
-\rfc{2822}-conformant, especially in cases where the
-syntax or semantics have changed since \rfc{822}.} Such messages
-consist of a collection of message headers, and a message body. This
-module also defines a helper class
-\class{AddressList} for parsing \rfc{2822} addresses. Please refer to
-the RFC for information on the specific syntax of \rfc{2822} messages.
-
-The \refmodule{mailbox}\refstmodindex{mailbox} module provides classes
-to read mailboxes produced by various end-user mail programs.
-
-\begin{classdesc}{Message}{file\optional{, seekable}}
-A \class{Message} instance is instantiated with an input object as
-parameter. Message relies only on the input object having a
-\method{readline()} method; in particular, ordinary file objects
-qualify. Instantiation reads headers from the input object up to a
-delimiter line (normally a blank line) and stores them in the
-instance. The message body, following the headers, is not consumed.
-
-This class can work with any input object that supports a
-\method{readline()} method. If the input object has seek and tell
-capability, the \method{rewindbody()} method will work; also, illegal
-lines will be pushed back onto the input stream. If the input object
-lacks seek but has an \method{unread()} method that can push back a
-line of input, \class{Message} will use that to push back illegal
-lines. Thus this class can be used to parse messages coming from a
-buffered stream.
-
-The optional \var{seekable} argument is provided as a workaround for
-certain stdio libraries in which \cfunction{tell()} discards buffered
-data before discovering that the \cfunction{lseek()} system call
-doesn't work. For maximum portability, you should set the seekable
-argument to zero to prevent that initial \method{tell()} when passing
-in an unseekable object such as a file object created from a socket
-object.
-
-Input lines as read from the file may either be terminated by CR-LF or
-by a single linefeed; a terminating CR-LF is replaced by a single
-linefeed before the line is stored.
-
-All header matching is done independent of upper or lower case;
-e.g.\ \code{\var{m}['From']}, \code{\var{m}['from']} and
-\code{\var{m}['FROM']} all yield the same result.
-\end{classdesc}
-
-\begin{classdesc}{AddressList}{field}
-You may instantiate the \class{AddressList} helper class using a single
-string parameter, a comma-separated list of \rfc{2822} addresses to be
-parsed. (The parameter \code{None} yields an empty list.)
-\end{classdesc}
-
-\begin{funcdesc}{quote}{str}
-Return a new string with backslashes in \var{str} replaced by two
-backslashes and double quotes replaced by backslash-double quote.
-\end{funcdesc}
-
-\begin{funcdesc}{unquote}{str}
-Return a new string which is an \emph{unquoted} version of \var{str}.
-If \var{str} ends and begins with double quotes, they are stripped
-off. Likewise if \var{str} ends and begins with angle brackets, they
-are stripped off.
-\end{funcdesc}
-
-\begin{funcdesc}{parseaddr}{address}
-Parse \var{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 \code{(None, None)} is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{dump_address_pair}{pair}
-The inverse of \method{parseaddr()}, this takes a 2-tuple of the form
-\code{(\var{realname}, \var{email_address})} and returns the string
-value suitable for a \mailheader{To} or \mailheader{Cc} header. If
-the first element of \var{pair} is false, then the second element is
-returned unmodified.
-\end{funcdesc}
-
-\begin{funcdesc}{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
-\function{parsedate()} tries to guess correctly in such cases.
-\var{date} is a string containing an \rfc{2822} date, such as
-\code{'Mon, 20 Nov 1995 19:12:08 -0500'}. If it succeeds in parsing
-the date, \function{parsedate()} returns a 9-tuple that can be passed
-directly to \function{time.mktime()}; otherwise \code{None} will be
-returned. Note that indexes 6, 7, and 8 of the result tuple are not
-usable.
-\end{funcdesc}
-
-\begin{funcdesc}{parsedate_tz}{date}
-Performs the same function as \function{parsedate()}, but returns
-either \code{None} or a 10-tuple; the first 9 elements make up a tuple
-that can be passed directly to \function{time.mktime()}, and the tenth
-is the offset of the date's timezone from UTC (which is the official
-term for Greenwich Mean Time). (Note that the sign of the timezone
-offset is the opposite of the sign of the \code{time.timezone}
-variable for the same timezone; the latter variable follows the
-\POSIX{} standard while this module follows \rfc{2822}.) If the input
-string has no timezone, the last element of the tuple returned is
-\code{None}. Note that indexes 6, 7, and 8 of the result tuple are not
-usable.
-\end{funcdesc}
-
-\begin{funcdesc}{mktime_tz}{tuple}
-Turn a 10-tuple as returned by \function{parsedate_tz()} into a UTC
-timestamp. If the timezone item in the tuple is \code{None}, assume
-local time. Minor deficiency: this first interprets the first 8
-elements as a local time and then compensates for the timezone
-difference; this may yield a slight error around daylight savings time
-switch dates. Not enough to worry about for common use.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{email}{Comprehensive email handling package; supersedes
- the \module{rfc822} module.}
- \seemodule{mailbox}{Classes to read various mailbox formats produced
- by end-user mail programs.}
- \seemodule{mimetools}{Subclass of \class{rfc822.Message} that
- handles MIME encoded messages.}
-\end{seealso}
-
-
-\subsection{Message Objects \label{message-objects}}
-
-A \class{Message} instance has the following methods:
-
-\begin{methoddesc}[Message]{rewindbody}{}
-Seek to the start of the message body. This only works if the file
-object is seekable.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{isheader}{line}
-Returns a line's canonicalized fieldname (the dictionary key that will
-be used to index it) if the line is a legal \rfc{2822} header; otherwise
-returns \code{None} (implying that parsing should stop here and the
-line be pushed back on the input stream). It is sometimes useful to
-override this method in a subclass.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{islast}{line}
-Return true if the given line is a delimiter on which Message should
-stop. The delimiter line is consumed, and the file object's read
-location positioned immediately after it. By default this method just
-checks that the line is blank, but you can override it in a subclass.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{iscomment}{line}
-Return \code{True} if the given line should be ignored entirely, just skipped.
-By default this is a stub that always returns \code{False}, but you can
-override it in a subclass.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getallmatchingheaders}{name}
-Return a list of lines consisting of all headers matching
-\var{name}, if any. Each physical line, whether it is a continuation
-line or not, is a separate list item. Return the empty list if no
-header matches \var{name}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getfirstmatchingheader}{name}
-Return a list of lines comprising the first header matching
-\var{name}, and its continuation line(s), if any. Return
-\code{None} if there is no header matching \var{name}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getrawheader}{name}
-Return a single string consisting of the text after the colon in the
-first header matching \var{name}. This includes leading whitespace,
-the trailing linefeed, and internal linefeeds and whitespace if there
-any continuation line(s) were present. Return \code{None} if there is
-no header matching \var{name}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getheader}{name\optional{, default}}
-Like \code{getrawheader(\var{name})}, but strip leading and trailing
-whitespace. Internal whitespace is not stripped. The optional
-\var{default} argument can be used to specify a different default to
-be returned when there is no header matching \var{name}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get}{name\optional{, default}}
-An alias for \method{getheader()}, to make the interface more compatible
-with regular dictionaries.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getaddr}{name}
-Return a pair \code{(\var{full name}, \var{email address})} parsed
-from the string returned by \code{getheader(\var{name})}. If no
-header matching \var{name} exists, return \code{(None, None)};
-otherwise both the full name and the address are (possibly empty)
-strings.
-
-Example: If \var{m}'s first \mailheader{From} header contains the
-string \code{'jack@cwi.nl (Jack Jansen)'}, then
-\code{m.getaddr('From')} will yield the pair
-\code{('Jack Jansen', 'jack@cwi.nl')}.
-If the header contained
-\code{'Jack Jansen <jack@cwi.nl>'} instead, it would yield the
-exact same result.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getaddrlist}{name}
-This is similar to \code{getaddr(\var{list})}, but parses a header
-containing a list of email addresses (e.g.\ a \mailheader{To} header) and
-returns a list of \code{(\var{full name}, \var{email address})} pairs
-(even if there was only one address in the header). If there is no
-header matching \var{name}, return an empty list.
-
-If multiple headers exist that match the named header (e.g. if there
-are several \mailheader{Cc} headers), all are parsed for addresses.
-Any continuation lines the named headers contain are also parsed.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getdate}{name}
-Retrieve a header using \method{getheader()} and parse it into a 9-tuple
-compatible with \function{time.mktime()}; note that fields 6, 7, and 8
-are not usable. If there is no header matching
-\var{name}, or it is unparsable, return \code{None}.
-
-Date parsing appears to be a black art, and not all mailers adhere to
-the standard. While it has been tested and found correct on a large
-collection of email from many sources, it is still possible that this
-function may occasionally yield an incorrect result.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getdate_tz}{name}
-Retrieve a header using \method{getheader()} and parse it into a
-10-tuple; the first 9 elements will make a tuple compatible with
-\function{time.mktime()}, and the 10th is a number giving the offset
-of the date's timezone from UTC. Note that fields 6, 7, and 8
-are not usable. Similarly to \method{getdate()}, if
-there is no header matching \var{name}, or it is unparsable, return
-\code{None}.
-\end{methoddesc}
-
-\class{Message} instances also support a limited mapping interface.
-In particular: \code{\var{m}[name]} is like
-\code{\var{m}.getheader(name)} but raises \exception{KeyError} if
-there is no matching header; and \code{len(\var{m})},
-\code{\var{m}.get(\var{name}\optional{, \var{default}})},
-\code{\var{m}.has_key(\var{name})}, \code{\var{m}.keys()},
-\code{\var{m}.values()} \code{\var{m}.items()}, and
-\code{\var{m}.setdefault(\var{name}\optional{, \var{default}})} act as
-expected, with the one difference that \method{setdefault()} uses
-an empty string as the default value. \class{Message} instances
-also support the mapping writable interface \code{\var{m}[name] =
-value} and \code{del \var{m}[name]}. \class{Message} objects do not
-support the \method{clear()}, \method{copy()}, \method{popitem()}, or
-\method{update()} methods of the mapping interface. (Support for
-\method{get()} and \method{setdefault()} was only added in Python
-2.2.)
-
-Finally, \class{Message} instances have some public instance variables:
-
-\begin{memberdesc}[Message]{headers}
-A list containing the entire set of header lines, in the order in
-which they were read (except that setitem calls may disturb this
-order). Each line contains a trailing newline. The
-blank line terminating the headers is not contained in the list.
-\end{memberdesc}
-
-\begin{memberdesc}[Message]{fp}
-The file or file-like object passed at instantiation time. This can
-be used to read the message content.
-\end{memberdesc}
-
-\begin{memberdesc}[Message]{unixfrom}
-The \UNIX{} \samp{From~} line, if the message had one, or an empty
-string. This is needed to regenerate the message in some contexts,
-such as an \code{mbox}-style mailbox file.
-\end{memberdesc}
-
-
-\subsection{AddressList Objects \label{addresslist-objects}}
-
-An \class{AddressList} instance has the following methods:
-
-\begin{methoddesc}[AddressList]{__len__}{}
-Return the number of addresses in the address list.
-\end{methoddesc}
-
-\begin{methoddesc}[AddressList]{__str__}{}
-Return a canonicalized string representation of the address list.
-Addresses are rendered in "name" <host@domain> form, comma-separated.
-\end{methoddesc}
-
-\begin{methoddesc}[AddressList]{__add__}{alist}
-Return a new \class{AddressList} instance that contains all addresses
-in both \class{AddressList} operands, with duplicates removed (set
-union).
-\end{methoddesc}
-
-\begin{methoddesc}[AddressList]{__iadd__}{alist}
-In-place version of \method{__add__()}; turns this \class{AddressList}
-instance into the union of itself and the right-hand instance,
-\var{alist}.
-\end{methoddesc}
-
-\begin{methoddesc}[AddressList]{__sub__}{alist}
-Return a new \class{AddressList} instance that contains every address
-in the left-hand \class{AddressList} operand that is not present in
-the right-hand address operand (set difference).
-\end{methoddesc}
-
-\begin{methoddesc}[AddressList]{__isub__}{alist}
-In-place version of \method{__sub__()}, removing addresses in this
-list which are also in \var{alist}.
-\end{methoddesc}
-
-
-Finally, \class{AddressList} instances have one public instance variable:
-
-\begin{memberdesc}[AddressList]{addresslist}
-A list of tuple string pairs, one per address. In each member, the
-first is the canonicalized name part, the second is the
-actual route-address (\character{@}-separated username-host.domain
-pair).
-\end{memberdesc}
diff --git a/Doc/lib/librlcompleter.tex b/Doc/lib/librlcompleter.tex
deleted file mode 100644
index cb2ac59..0000000
--- a/Doc/lib/librlcompleter.tex
+++ /dev/null
@@ -1,65 +0,0 @@
-\section{\module{rlcompleter} ---
- Completion function for GNU readline}
-
-\declaremodule{standard}{rlcompleter}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Python identifier completion, suitable for the GNU readline library.}
-
-The \module{rlcompleter} module defines a completion function suitable for
-the \refmodule{readline} module by completing valid Python identifiers
-and keywords.
-
-When this module is imported on a \UNIX\ platform with the \module{readline}
-module available, an instance of the \class{Completer} class is automatically
-created and its \method{complete} method is set as the \module{readline}
-completer.
-
-Example:
-
-\begin{verbatim}
->>> import rlcompleter
->>> import readline
->>> readline.parse_and_bind("tab: complete")
->>> readline. <TAB PRESSED>
-readline.__doc__ readline.get_line_buffer readline.read_init_file
-readline.__file__ readline.insert_text readline.set_completer
-readline.__name__ readline.parse_and_bind
->>> readline.
-\end{verbatim}
-
-The \module{rlcompleter} module is designed for use with Python's
-interactive mode. A user can add the following lines to his or her
-initialization file (identified by the \envvar{PYTHONSTARTUP}
-environment variable) to get automatic \kbd{Tab} completion:
-
-\begin{verbatim}
-try:
- import readline
-except ImportError:
- print "Module readline not available."
-else:
- import rlcompleter
- readline.parse_and_bind("tab: complete")
-\end{verbatim}
-
-
-On platforms without \module{readline}, the \class{Completer} class defined
-by this module can still be used for custom purposes.
-
-\subsection{Completer Objects \label{completer-objects}}
-
-Completer objects have the following method:
-
-\begin{methoddesc}[Completer]{complete}{text, state}
-Return the \var{state}th completion for \var{text}.
-
-If called for \var{text} that doesn't include a period character
-(\character{.}), it will complete from names currently defined in
-\refmodule[main]{__main__}, \refmodule[builtin]{__builtin__} and
-keywords (as defined by the \refmodule{keyword} module).
-
-If called for a dotted name, it will try to evaluate anything without
-obvious side-effects (functions will not be evaluated, but it
-can generate calls to \method{__getattr__()}) up to the last part, and
-find matches for the rest via the \function{dir()} function.
-\end{methoddesc}
diff --git a/Doc/lib/librobotparser.tex b/Doc/lib/librobotparser.tex
deleted file mode 100644
index 5eac528..0000000
--- a/Doc/lib/librobotparser.tex
+++ /dev/null
@@ -1,66 +0,0 @@
-\section{\module{robotparser} ---
- Parser for robots.txt}
-
-\declaremodule{standard}{robotparser}
-\modulesynopsis{Loads a \protect\file{robots.txt} file and
- answers questions about fetchability of other URLs.}
-\sectionauthor{Skip Montanaro}{skip@mojam.com}
-
-\index{WWW}
-\index{World Wide Web}
-\index{URL}
-\index{robots.txt}
-
-This module provides a single class, \class{RobotFileParser}, which answers
-questions about whether or not a particular user agent can fetch a URL on
-the Web site that published the \file{robots.txt} file. For more details on
-the structure of \file{robots.txt} files, see
-\url{http://www.robotstxt.org/wc/norobots.html}.
-
-\begin{classdesc}{RobotFileParser}{}
-
-This class provides a set of methods to read, parse and answer questions
-about a single \file{robots.txt} file.
-
-\begin{methoddesc}{set_url}{url}
-Sets the URL referring to a \file{robots.txt} file.
-\end{methoddesc}
-
-\begin{methoddesc}{read}{}
-Reads the \file{robots.txt} URL and feeds it to the parser.
-\end{methoddesc}
-
-\begin{methoddesc}{parse}{lines}
-Parses the lines argument.
-\end{methoddesc}
-
-\begin{methoddesc}{can_fetch}{useragent, url}
-Returns \code{True} if the \var{useragent} is allowed to fetch the \var{url}
-according to the rules contained in the parsed \file{robots.txt} file.
-\end{methoddesc}
-
-\begin{methoddesc}{mtime}{}
-Returns the time the \code{robots.txt} file was last fetched. This is
-useful for long-running web spiders that need to check for new
-\code{robots.txt} files periodically.
-\end{methoddesc}
-
-\begin{methoddesc}{modified}{}
-Sets the time the \code{robots.txt} file was last fetched to the current
-time.
-\end{methoddesc}
-
-\end{classdesc}
-
-The following example demonstrates basic use of the RobotFileParser class.
-
-\begin{verbatim}
->>> import robotparser
->>> rp = robotparser.RobotFileParser()
->>> rp.set_url("http://www.musi-cal.com/robots.txt")
->>> rp.read()
->>> rp.can_fetch("*", "http://www.musi-cal.com/cgi-bin/search?city=San+Francisco")
-False
->>> rp.can_fetch("*", "http://www.musi-cal.com/")
-True
-\end{verbatim}
diff --git a/Doc/lib/librunpy.tex b/Doc/lib/librunpy.tex
deleted file mode 100644
index 60707ca..0000000
--- a/Doc/lib/librunpy.tex
+++ /dev/null
@@ -1,76 +0,0 @@
-\section{\module{runpy} ---
- Locating and executing Python modules.}
-
-\declaremodule{standard}{runpy} % standard library, in Python
-
-\moduleauthor{Nick Coghlan}{ncoghlan@gmail.com}
-
-\modulesynopsis{Locate and execute Python modules as scripts}
-
-\versionadded{2.5}
-
-The \module{runpy} module is used to locate and run Python modules
-without importing them first. Its main use is to implement the
-\programopt{-m} command line switch that allows scripts to be located
-using the Python module namespace rather than the filesystem.
-
-When executed as a script, the module effectively operates as follows:
-\begin{verbatim}
- del sys.argv[0] # Remove the runpy module from the arguments
- run_module(sys.argv[0], run_name="__main__", alter_sys=True)
-\end{verbatim}
-
-The \module{runpy} module provides a single function:
-
-\begin{funcdesc}{run_module}{mod_name\optional{, init_globals}
-\optional{, run_name}\optional{, alter_sys}}
-Execute the code of the specified module and return the resulting
-module globals dictionary. The module's code is first located using
-the standard import mechanism (refer to PEP 302 for details) and
-then executed in a fresh module namespace.
-
-The optional dictionary argument \var{init_globals} may be used to
-pre-populate the globals dictionary before the code is executed.
-The supplied dictionary will not be modified. If any of the special
-global variables below are defined in the supplied dictionary, those
-definitions are overridden by the \code{run_module} function.
-
-The special global variables \code{__name__}, \code{__file__},
-\code{__loader__} and \code{__builtins__} are set in the globals
-dictionary before the module code is executed.
-
-\code{__name__} is set to \var{run_name} if this optional argument is
-supplied, and the \var{mod_name} argument otherwise.
-
-\code{__loader__} is set to the PEP 302 module loader used to retrieve
-the code for the module (This loader may be a wrapper around the
-standard import mechanism).
-
-\code{__file__} is set to the name provided by the module loader. If
-the loader does not make filename information available, this
-variable is set to \code{None}.
-
-\code{__builtins__} is automatically initialised with a reference to
-the top level namespace of the \module{__builtin__} module.
-
-If the argument \var{alter_sys} is supplied and evaluates to
-\code{True}, then \code{sys.argv[0]} is updated with the value of
-\code{__file__} and \code{sys.modules[__name__]} is updated with a
-new module object for the module being executed. Note that neither
-\code{sys.argv[0]} nor \code{sys.modules[__name__]} are restored to
-their original values before the function returns - if client code
-needs these values preserved, it must either save them explicitly or
-else avoid enabling the automatic alterations to \module{sys}.
-
-Note that this manipulation of \module{sys} is not thread-safe. Other
-threads may see the partially initialised module, as well as the
-altered list of arguments. It is recommended that the \module{sys}
-module be left alone when invoking this function from threaded code.
-\end{funcdesc}
-
-\begin{seealso}
-
-\seepep{338}{Executing modules as scripts}{PEP written and
-implemented by Nick Coghlan.}
-
-\end{seealso}
diff --git a/Doc/lib/libsched.tex b/Doc/lib/libsched.tex
deleted file mode 100644
index 75bab7e..0000000
--- a/Doc/lib/libsched.tex
+++ /dev/null
@@ -1,97 +0,0 @@
-\section{\module{sched} ---
- Event scheduler}
-
-% LaTeXed and enhanced from comments in file
-
-\declaremodule{standard}{sched}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{General purpose event scheduler.}
-
-The \module{sched} module defines a class which implements a general
-purpose event scheduler:\index{event scheduling}
-
-\begin{classdesc}{scheduler}{timefunc, delayfunc}
-The \class{scheduler} class defines a generic interface to scheduling
-events. It needs two functions to actually deal with the ``outside world''
---- \var{timefunc} should be callable without arguments, and return
-a number (the ``time'', in any units whatsoever). The \var{delayfunc}
-function should be callable with one argument, compatible with the output
-of \var{timefunc}, and should delay that many time units.
-\var{delayfunc} will also be called with the argument \code{0} after
-each event is run to allow other threads an opportunity to run in
-multi-threaded applications.
-\end{classdesc}
-
-Example:
-
-\begin{verbatim}
->>> import sched, time
->>> s=sched.scheduler(time.time, time.sleep)
->>> def print_time(): print "From print_time", time.time()
-...
->>> def print_some_times():
-... print time.time()
-... s.enter(5, 1, print_time, ())
-... s.enter(10, 1, print_time, ())
-... s.run()
-... print time.time()
-...
->>> print_some_times()
-930343690.257
-From print_time 930343695.274
-From print_time 930343700.273
-930343700.276
-\end{verbatim}
-
-
-\subsection{Scheduler Objects \label{scheduler-objects}}
-
-\class{scheduler} instances have the following methods:
-
-\begin{methoddesc}[scheduler]{enterabs}{time, priority, action, argument}
-Schedule a new event. The \var{time} argument should be a numeric type
-compatible with the return value of the \var{timefunc} function passed
-to the constructor. Events scheduled for
-the same \var{time} will be executed in the order of their
-\var{priority}.
-
-Executing the event means executing
-\code{\var{action}(*\var{argument})}. \var{argument} must be a
-sequence holding the parameters for \var{action}.
-
-Return value is an event which may be used for later cancellation of
-the event (see \method{cancel()}).
-\end{methoddesc}
-
-\begin{methoddesc}[scheduler]{enter}{delay, priority, action, argument}
-Schedule an event for \var{delay} more time units. Other then the
-relative time, the other arguments, the effect and the return value
-are the same as those for \method{enterabs()}.
-\end{methoddesc}
-
-\begin{methoddesc}[scheduler]{cancel}{event}
-Remove the event from the queue. If \var{event} is not an event
-currently in the queue, this method will raise a
-\exception{RuntimeError}.
-\end{methoddesc}
-
-\begin{methoddesc}[scheduler]{empty}{}
-Return true if the event queue is empty.
-\end{methoddesc}
-
-\begin{methoddesc}[scheduler]{run}{}
-Run all scheduled events. This function will wait
-(using the \function{delayfunc} function passed to the constructor)
-for the next event, then execute it and so on until there are no more
-scheduled events.
-
-Either \var{action} or \var{delayfunc} can raise an exception. In
-either case, the scheduler will maintain a consistent state and
-propagate the exception. If an exception is raised by \var{action},
-the event will not be attempted in future calls to \method{run()}.
-
-If a sequence of events takes longer to run than the time available
-before the next event, the scheduler will simply fall behind. No
-events will be dropped; the calling code is responsible for canceling
-events which are no longer pertinent.
-\end{methoddesc}
diff --git a/Doc/lib/libselect.tex b/Doc/lib/libselect.tex
deleted file mode 100644
index 69583d4..0000000
--- a/Doc/lib/libselect.tex
+++ /dev/null
@@ -1,132 +0,0 @@
-\section{\module{select} ---
- Waiting for I/O completion}
-
-\declaremodule{builtin}{select}
-\modulesynopsis{Wait for I/O completion on multiple streams.}
-
-
-This module provides access to the \cfunction{select()}
-and \cfunction{poll()} functions
-available in most operating systems. Note that on Windows, it only
-works for sockets; on other operating systems, it also works for other
-file types (in particular, on \UNIX, it works on pipes). It cannot
-be used on regular files to determine whether a file has grown since
-it was last read.
-
-The module defines the following:
-
-\begin{excdesc}{error}
-The exception raised when an error occurs. The accompanying value is
-a pair containing the numeric error code from \cdata{errno} and the
-corresponding string, as would be printed by the \C{} function
-\cfunction{perror()}.
-\end{excdesc}
-
-\begin{funcdesc}{poll}{}
-(Not supported by all operating systems.) Returns a polling object,
-which supports registering and unregistering file descriptors, and
-then polling them for I/O events;
-see section~\ref{poll-objects} below for the methods supported by
-polling objects.
-\end{funcdesc}
-
-\begin{funcdesc}{select}{iwtd, owtd, ewtd\optional{, timeout}}
-This is a straightforward interface to the \UNIX{} \cfunction{select()}
-system call. The first three arguments are sequences of `waitable
-objects': either integers representing file descriptors or
-objects with a parameterless method named \method{fileno()} returning
-such an integer. The three sequences of waitable objects are for input,
-output and `exceptional conditions', respectively. Empty sequences are
-allowed, but acceptance of three empty sequences is platform-dependent.
-(It is known to work on \UNIX{} but not on Windows.) The optional
-\var{timeout} argument specifies a time-out as a floating point number
-in seconds. When the \var{timeout} argument is omitted the function
-blocks until at least one file descriptor is ready. A time-out value
-of zero specifies a poll and never blocks.
-
-The return value is a triple of lists of objects that are ready:
-subsets of the first three arguments. When the time-out is reached
-without a file descriptor becoming ready, three empty lists are
-returned.
-
-Among the acceptable object types in the sequences are Python file
-objects (e.g. \code{sys.stdin}, or objects returned by
-\function{open()} or \function{os.popen()}), socket objects
-returned by \function{socket.socket()}.%
-\withsubitem{(in module socket)}{\ttindex{socket()}}
-\withsubitem{(in module os)}{\ttindex{popen()}}
-You may also define a \dfn{wrapper} class yourself, as long as it has
-an appropriate \method{fileno()} method (that really returns a file
-descriptor, not just a random integer).
-\note{File objects on Windows are not acceptable, but sockets
-are.\index{WinSock} On Windows, the underlying \cfunction{select()}
-function is provided by the WinSock library, and does not handle file
-descriptors that don't originate from WinSock.}
-\end{funcdesc}
-
-\subsection{Polling Objects
- \label{poll-objects}}
-
-The \cfunction{poll()} system call, supported on most \UNIX{} systems,
-provides better scalability for network servers that service many,
-many clients at the same time.
-\cfunction{poll()} scales better because the system call only
-requires listing the file descriptors of interest, while \cfunction{select()}
-builds a bitmap, turns on bits for the fds of interest, and then
-afterward the whole bitmap has to be linearly scanned again.
-\cfunction{select()} is O(highest file descriptor), while
-\cfunction{poll()} is O(number of file descriptors).
-
-\begin{methoddesc}[poll]{register}{fd\optional{, eventmask}}
-Register a file descriptor with the polling object. Future calls to
-the \method{poll()} method will then check whether the file descriptor
-has any pending I/O events. \var{fd} can be either an integer, or an
-object with a \method{fileno()} method that returns an integer. File
-objects implement
-\method{fileno()}, so they can also be used as the argument.
-
-\var{eventmask} is an optional bitmask describing the type of events you
-want to check for, and can be a combination of the constants
-\constant{POLLIN}, \constant{POLLPRI}, and \constant{POLLOUT},
-described in the table below. If not specified, the default value
-used will check for all 3 types of events.
-
-\begin{tableii}{l|l}{constant}{Constant}{Meaning}
- \lineii{POLLIN}{There is data to read}
- \lineii{POLLPRI}{There is urgent data to read}
- \lineii{POLLOUT}{Ready for output: writing will not block}
- \lineii{POLLERR}{Error condition of some sort}
- \lineii{POLLHUP}{Hung up}
- \lineii{POLLNVAL}{Invalid request: descriptor not open}
-\end{tableii}
-
-Registering a file descriptor that's already registered is not an
-error, and has the same effect as registering the descriptor exactly
-once.
-\end{methoddesc}
-
-\begin{methoddesc}[poll]{unregister}{fd}
-Remove a file descriptor being tracked by a polling object. Just like
-the \method{register()} method, \var{fd} can be an integer or an
-object with a \method{fileno()} method that returns an integer.
-
-Attempting to remove a file descriptor that was never registered
-causes a \exception{KeyError} exception to be raised.
-\end{methoddesc}
-
-\begin{methoddesc}[poll]{poll}{\optional{timeout}}
-Polls the set of registered file descriptors, and returns a
-possibly-empty list containing \code{(\var{fd}, \var{event})} 2-tuples
-for the descriptors that have events or errors to report.
-\var{fd} is the file descriptor, and \var{event} is a bitmask
-with bits set for the reported events for that descriptor
---- \constant{POLLIN} for waiting input,
-\constant{POLLOUT} to indicate that the descriptor can be written to, and
-so forth.
-An empty list indicates that the call timed out and no file
-descriptors had any events to report.
-If \var{timeout} is given, it specifies the length of time in
-milliseconds which the system will wait for events before returning.
-If \var{timeout} is omitted, negative, or \constant{None}, the call will
-block until there is an event for this poll object.
-\end{methoddesc}
diff --git a/Doc/lib/libsgmllib.tex b/Doc/lib/libsgmllib.tex
deleted file mode 100644
index 1fe0d63..0000000
--- a/Doc/lib/libsgmllib.tex
+++ /dev/null
@@ -1,271 +0,0 @@
-\section{\module{sgmllib} ---
- Simple SGML parser}
-
-\declaremodule{standard}{sgmllib}
-\modulesynopsis{Only as much of an SGML parser as needed to parse HTML.}
-
-\index{SGML}
-
-This module defines a class \class{SGMLParser} which serves as the
-basis for parsing text files formatted in SGML (Standard Generalized
-Mark-up Language). In fact, it does not provide a full SGML parser
---- it only parses SGML insofar as it is used by HTML, and the module
-only exists as a base for the \refmodule{htmllib} module. Another
-HTML parser which supports XHTML and offers a somewhat different
-interface is available in the \refmodule{HTMLParser} module.
-
-\begin{classdesc}{SGMLParser}{}
-The \class{SGMLParser} class is instantiated without arguments.
-The parser is hardcoded to recognize the following
-constructs:
-
-\begin{itemize}
-\item
-Opening and closing tags of the form
-\samp{<\var{tag} \var{attr}="\var{value}" ...>} and
-\samp{</\var{tag}>}, respectively.
-
-\item
-Numeric character references of the form \samp{\&\#\var{name};}.
-
-\item
-Entity references of the form \samp{\&\var{name};}.
-
-\item
-SGML comments of the form \samp{<!--\var{text}-->}. Note that
-spaces, tabs, and newlines are allowed between the trailing
-\samp{>} and the immediately preceding \samp{--}.
-
-\end{itemize}
-\end{classdesc}
-
-A single exception is defined as well:
-
-\begin{excdesc}{SGMLParseError}
-Exception raised by the \class{SGMLParser} class when it encounters an
-error while parsing.
-\versionadded{2.1}
-\end{excdesc}
-
-
-\class{SGMLParser} instances have the following methods:
-
-
-\begin{methoddesc}{reset}{}
-Reset the instance. Loses all unprocessed data. This is called
-implicitly at instantiation time.
-\end{methoddesc}
-
-\begin{methoddesc}{setnomoretags}{}
-Stop processing tags. Treat all following input as literal input
-(CDATA). (This is only provided so the HTML tag
-\code{<PLAINTEXT>} can be implemented.)
-\end{methoddesc}
-
-\begin{methoddesc}{setliteral}{}
-Enter literal mode (CDATA mode).
-\end{methoddesc}
-
-\begin{methoddesc}{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 \method{close()} is called.
-\end{methoddesc}
-
-\begin{methoddesc}{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 \method{close()}.
-\end{methoddesc}
-
-\begin{methoddesc}{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.).
-\end{methoddesc}
-
-\begin{methoddesc}{handle_starttag}{tag, method, attributes}
-This method is called to handle start tags for which either a
-\method{start_\var{tag}()} or \method{do_\var{tag}()} method has been
-defined. The \var{tag} argument is the name of the tag converted to
-lower case, and the \var{method} argument is the bound method which
-should be used to support semantic interpretation of the start tag.
-The \var{attributes} argument is a list of \code{(\var{name},
-\var{value})} pairs containing the attributes found inside the tag's
-\code{<>} brackets.
-
-The \var{name} has been translated to lower case.
-Double quotes and backslashes in the \var{value} have been interpreted,
-as well as known character references and known entity references
-terminated by a semicolon (normally, entity references can be terminated
-by any non-alphanumerical character, but this would break the very
-common case of \code{<A HREF="url?spam=1\&eggs=2">} when \code{eggs}
-is a valid entity name).
-
-For instance, for the tag \code{<A HREF="http://www.cwi.nl/">}, this
-method would be called as \samp{unknown_starttag('a', [('href',
-'http://www.cwi.nl/')])}. The base implementation simply calls
-\var{method} with \var{attributes} as the only argument.
-\versionadded[Handling of entity and character references within
- attribute values]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{handle_endtag}{tag, method}
-This method is called to handle endtags for which an
-\method{end_\var{tag}()} method has been defined. The
-\var{tag} argument is the name of the tag converted to lower case, and
-the \var{method} argument is the bound method which should be used to
-support semantic interpretation of the end tag. If no
-\method{end_\var{tag}()} method is defined for the closing element,
-this handler is not called. The base implementation simply calls
-\var{method}.
-\end{methoddesc}
-
-\begin{methoddesc}{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.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_charref}{ref}
-This method is called to process a character reference of the form
-\samp{\&\#\var{ref};}. The base implementation uses
-\method{convert_charref()} to convert the reference to a string. If
-that method returns a string, it is passed to \method{handle_data()},
-otherwise \method{unknown_charref(\var{ref})} is called to handle the
-error.
-\versionchanged[Use \method{convert_charref()} instead of hard-coding
-the conversion]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{convert_charref}{ref}
-Convert a character reference to a string, or \code{None}. \var{ref}
-is the reference passed in as a string. In the base implementation,
-\var{ref} must be a decimal number in the range 0-255. It converts
-the code point found using the \method{convert_codepoint()} method.
-If \var{ref} is invalid or out of range, this method returns
-\code{None}. This method is called by the default
-\method{handle_charref()} implementation and by the attribute value
-parser.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{convert_codepoint}{codepoint}
-Convert a codepoint to a \class{str} value. Encodings can be handled
-here if appropriate, though the rest of \module{sgmllib} is oblivious
-on this matter.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{handle_entityref}{ref}
-This method is called to process a general entity reference of the
-form \samp{\&\var{ref};} where \var{ref} is an general entity
-reference. It converts \var{ref} by passing it to
-\method{convert_entityref()}. If a translation is returned, it
-calls the method \method{handle_data()} with the translation;
-otherwise, it calls the method \code{unknown_entityref(\var{ref})}.
-The default \member{entitydefs} defines translations for
-\code{\&}, \code{\&apos}, \code{\>}, \code{\<}, and
-\code{\"}.
-\versionchanged[Use \method{convert_entityref()} instead of hard-coding
-the conversion]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{convert_entityref}{ref}
-Convert a named entity reference to a \class{str} value, or
-\code{None}. The resulting value will not be parsed. \var{ref} will
-be only the name of the entity. The default implementation looks for
-\var{ref} in the instance (or class) variable \member{entitydefs}
-which should be a mapping from entity names to corresponding
-translations. If no translation is available for \var{ref}, this
-method returns \code{None}. This method is called by the default
-\method{handle_entityref()} implementation and by the attribute value
-parser.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{handle_comment}{comment}
-This method is called when a comment is encountered. The
-\var{comment} argument is a string containing the text between the
-\samp{<!--} and \samp{-->} delimiters, but not the delimiters
-themselves. For example, the comment \samp{<!--text-->} will
-cause this method to be called with the argument \code{'text'}. The
-default method does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_decl}{data}
-Method called when an SGML declaration is read by the parser. In
-practice, the \code{DOCTYPE} declaration is the only thing observed in
-HTML, but the parser does not discriminate among different (or broken)
-declarations. Internal subsets in a \code{DOCTYPE} declaration are
-not supported. The \var{data} parameter will be the entire contents
-of the declaration inside the \code{<!}...\code{>} markup. The
-default implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{report_unbalanced}{tag}
-This method is called when an end tag is found which does not
-correspond to any open element.
-\end{methoddesc}
-
-\begin{methoddesc}{unknown_starttag}{tag, attributes}
-This method is called to process an unknown start tag. It is intended
-to be overridden by a derived class; the base class implementation
-does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{unknown_endtag}{tag}
-This method is called to process an unknown end tag. It is intended
-to be overridden by a derived class; the base class implementation
-does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{unknown_charref}{ref}
-This method is called to process unresolvable numeric character
-references. Refer to \method{handle_charref()} to determine what is
-handled by default. It is intended to be overridden by a derived
-class; the base class implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{unknown_entityref}{ref}
-This method is called to process an unknown entity reference. It is
-intended to be overridden by a derived class; the base class
-implementation does nothing.
-\end{methoddesc}
-
-Apart from overriding or extending the methods listed above, derived
-classes may also define methods of the following form to define
-processing of specific tags. Tag names in the input stream are case
-independent; the \var{tag} occurring in method names must be in lower
-case:
-
-\begin{methoddescni}{start_\var{tag}}{attributes}
-This method is called to process an opening tag \var{tag}. It has
-preference over \method{do_\var{tag}()}. The
-\var{attributes} argument has the same meaning as described for
-\method{handle_starttag()} above.
-\end{methoddescni}
-
-\begin{methoddescni}{do_\var{tag}}{attributes}
-This method is called to process an opening tag \var{tag}
-for which no \method{start_\var{tag}} method is defined.
-The \var{attributes} argument
-has the same meaning as described for \method{handle_starttag()} above.
-\end{methoddescni}
-
-\begin{methoddescni}{end_\var{tag}}{}
-This method is called to process a closing tag \var{tag}.
-\end{methoddescni}
-
-Note that the parser maintains a stack of open elements for which no
-end tag has been found yet. Only tags processed by
-\method{start_\var{tag}()} are pushed on this stack. Definition of an
-\method{end_\var{tag}()} method is optional for these tags. For tags
-processed by \method{do_\var{tag}()} or by \method{unknown_tag()}, no
-\method{end_\var{tag}()} method must be defined; if defined, it will
-not be used. If both \method{start_\var{tag}()} and
-\method{do_\var{tag}()} methods exist for a tag, the
-\method{start_\var{tag}()} method takes precedence.
diff --git a/Doc/lib/libshelve.tex b/Doc/lib/libshelve.tex
deleted file mode 100644
index 6ca3576..0000000
--- a/Doc/lib/libshelve.tex
+++ /dev/null
@@ -1,174 +0,0 @@
-\section{\module{shelve} ---
- Python object persistence}
-
-\declaremodule{standard}{shelve}
-\modulesynopsis{Python object persistence.}
-
-
-A ``shelf'' is a persistent, dictionary-like object. The difference
-with ``dbm'' databases is that the values (not the keys!) in a shelf
-can be essentially arbitrary Python objects --- anything that the
-\refmodule{pickle} module can handle. This includes most class
-instances, recursive data types, and objects containing lots of shared
-sub-objects. The keys are ordinary strings.
-\refstmodindex{pickle}
-
-\begin{funcdesc}{open}{filename\optional{,flag='c'\optional{,protocol=\code{None}\optional{,writeback=\code{False}}}}}
-Open a persistent dictionary. The filename specified is the base filename
-for the underlying database. As a side-effect, an extension may be added to
-the filename and more than one file may be created. By default, the
-underlying database file is opened for reading and writing. The optional
-{}\var{flag} parameter has the same interpretation as the \var{flag}
-parameter of \function{anydbm.open}.
-
-By default, version 0 pickles are used to serialize values.
-The version of the pickle protocol can be specified with the
-\var{protocol} parameter. \versionchanged[The \var{protocol}
-parameter was added]{2.3}
-
-By default, mutations to persistent-dictionary mutable entries are not
-automatically written back. If the optional \var{writeback} parameter
-is set to {}\var{True}, all entries accessed are cached in memory, and
-written back at close time; this can make it handier to mutate mutable
-entries in the persistent dictionary, but, if many entries are
-accessed, it can consume vast amounts of memory for the cache, and it
-can make the close operation very slow since all accessed entries are
-written back (there is no way to determine which accessed entries are
-mutable, nor which ones were actually mutated).
-
-\end{funcdesc}
-
-Shelve objects support all methods supported by dictionaries. This eases
-the transition from dictionary based scripts to those requiring persistent
-storage.
-
-One additional method is supported:
-\begin{methoddesc}[Shelf]{sync}{}
-Write back all entries in the cache if the shelf was opened with
-\var{writeback} set to \var{True}. Also empty the cache and synchronize
-the persistent dictionary on disk, if feasible. This is called automatically
-when the shelf is closed with \method{close()}.
-\end{methoddesc}
-
-\subsection{Restrictions}
-
-\begin{itemize}
-
-\item
-The choice of which database package will be used
-(such as \refmodule{dbm}, \refmodule{gdbm} or \refmodule{bsddb}) depends on
-which interface is available. Therefore it is not safe to open the database
-directly using \refmodule{dbm}. The database is also (unfortunately) subject
-to the limitations of \refmodule{dbm}, if it is used --- this means
-that (the pickled representation of) the objects stored in the
-database should be fairly small, and in rare cases key collisions may
-cause the database to refuse updates.
-\refbimodindex{dbm}
-\refbimodindex{gdbm}
-\refbimodindex{bsddb}
-
-\item
-Depending on the implementation, closing a persistent dictionary may
-or may not be necessary to flush changes to disk. The \method{__del__}
-method of the \class{Shelf} class calls the \method{close} method, so the
-programmer generally need not do this explicitly.
-
-\item
-The \module{shelve} module does not support \emph{concurrent} read/write
-access to shelved objects. (Multiple simultaneous read accesses are
-safe.) When a program has a shelf open for writing, no other program
-should have it open for reading or writing. \UNIX{} file locking can
-be used to solve this, but this differs across \UNIX{} versions and
-requires knowledge about the database implementation used.
-
-\end{itemize}
-
-\begin{classdesc}{Shelf}{dict\optional{, protocol=None\optional{, writeback=False}}}
-A subclass of \class{UserDict.DictMixin} which stores pickled values in the
-\var{dict} object.
-
-By default, version 0 pickles are used to serialize values. The
-version of the pickle protocol can be specified with the
-\var{protocol} parameter. See the \module{pickle} documentation for a
-discussion of the pickle protocols. \versionchanged[The \var{protocol}
-parameter was added]{2.3}
-
-If the \var{writeback} parameter is \code{True}, the object will hold a
-cache of all entries accessed and write them back to the \var{dict} at
-sync and close times. This allows natural operations on mutable entries,
-but can consume much more memory and make sync and close take a long time.
-\end{classdesc}
-
-\begin{classdesc}{BsdDbShelf}{dict\optional{, protocol=None\optional{, writeback=False}}}
-
-A subclass of \class{Shelf} which exposes \method{first},
-\method{next}, \method{previous}, \method{last} and
-\method{set_location} which are available in the \module{bsddb} module
-but not in other database modules. The \var{dict} object passed to
-the constructor must support those methods. This is generally
-accomplished by calling one of \function{bsddb.hashopen},
-\function{bsddb.btopen} or \function{bsddb.rnopen}. The optional
-\var{protocol} and \var{writeback} parameters have the
-same interpretation as for the \class{Shelf} class.
-
-\end{classdesc}
-
-\begin{classdesc}{DbfilenameShelf}{filename\optional{, flag='c'\optional{, protocol=None\optional{, writeback=False}}}}
-
-A subclass of \class{Shelf} which accepts a \var{filename} instead of
-a dict-like object. The underlying file will be opened using
-{}\function{anydbm.open}. By default, the file will be created and
-opened for both read and write. The optional \var{flag} parameter has
-the same interpretation as for the \function{open} function. The
-optional \var{protocol} and \var{writeback} parameters
-have the same interpretation as for the \class{Shelf} class.
-
-\end{classdesc}
-
-\subsection{Example}
-
-To summarize the interface (\code{key} is a string, \code{data} is an
-arbitrary object):
-
-\begin{verbatim}
-import shelve
-
-d = shelve.open(filename) # open -- file may get suffix added by low-level
- # library
-
-d[key] = data # store data at key (overwrites old data if
- # using an existing key)
-data = d[key] # retrieve a COPY of data at key (raise KeyError if no
- # such key)
-del d[key] # delete data stored at key (raises KeyError
- # if no such key)
-flag = d.has_key(key) # true if the key exists
-klist = d.keys() # a list of all existing keys (slow!)
-
-# as d was opened WITHOUT writeback=True, beware:
-d['xx'] = range(4) # this works as expected, but...
-d['xx'].append(5) # *this doesn't!* -- d['xx'] is STILL range(4)!!!
-
-# having opened d without writeback=True, you need to code carefully:
-temp = d['xx'] # extracts the copy
-temp.append(5) # mutates the copy
-d['xx'] = temp # stores the copy right back, to persist it
-
-# or, d=shelve.open(filename,writeback=True) would let you just code
-# d['xx'].append(5) and have it work as expected, BUT it would also
-# consume more memory and make the d.close() operation slower.
-
-d.close() # close it
-\end{verbatim}
-
-\begin{seealso}
- \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
- \seemodule{bsddb}{BSD \code{db} database interface.}
- \seemodule{dbhash}{Thin layer around the \module{bsddb} which provides an
- \function{open} function like the other database modules.}
- \seemodule{dbm}{Standard \UNIX{} database interface.}
- \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}
- \seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.}
- \seemodule{pickle}{Object serialization used by \module{shelve}.}
- \seemodule{cPickle}{High-performance version of \refmodule{pickle}.}
-\end{seealso}
diff --git a/Doc/lib/libshlex.tex b/Doc/lib/libshlex.tex
deleted file mode 100644
index 230ae9f..0000000
--- a/Doc/lib/libshlex.tex
+++ /dev/null
@@ -1,279 +0,0 @@
-\section{\module{shlex} ---
- Simple lexical analysis}
-
-\declaremodule{standard}{shlex}
-\modulesynopsis{Simple lexical analysis for \UNIX\ shell-like languages.}
-\moduleauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-\moduleauthor{Gustavo Niemeyer}{niemeyer@conectiva.com}
-\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-\sectionauthor{Gustavo Niemeyer}{niemeyer@conectiva.com}
-
-\versionadded{1.5.2}
-
-The \class{shlex} class makes it easy to write lexical analyzers for
-simple syntaxes resembling that of the \UNIX{} shell. This will often
-be useful for writing minilanguages, (for example, in run control
-files for Python applications) or for parsing quoted strings.
-
-\note{The \module{shlex} module currently does not support Unicode input.}
-
-The \module{shlex} module defines the following functions:
-
-\begin{funcdesc}{split}{s\optional{, comments\optional{, posix}}}
-Split the string \var{s} using shell-like syntax. If \var{comments} is
-\constant{False} (the default), the parsing of comments in the given
-string will be disabled (setting the \member{commenters} member of the
-\class{shlex} instance to the empty string). This function operates
-in \POSIX{} mode by default, but uses non-\POSIX{} mode if the
-\var{posix} argument is false.
-\versionadded{2.3}
-\versionchanged[Added the \var{posix} parameter]{2.6}
-\note{Since the \function{split()} function instantiates a \class{shlex}
- instance, passing \code{None} for \var{s} will read the string
- to split from standard input.}
-\end{funcdesc}
-
-The \module{shlex} module defines the following class:
-
-\begin{classdesc}{shlex}{\optional{instream\optional{,
- infile\optional{, posix}}}}
-A \class{shlex} instance or subclass instance is a lexical analyzer
-object. The initialization argument, if present, specifies where to
-read characters from. It must be a file-/stream-like object with
-\method{read()} and \method{readline()} methods, or a string (strings
-are accepted since Python 2.3). If no argument is given, input will be
-taken from \code{sys.stdin}. The second optional argument is a filename
-string, which sets the initial value of the \member{infile} member. If
-the \var{instream} argument is omitted or equal to \code{sys.stdin},
-this second argument defaults to ``stdin''. The \var{posix} argument
-was introduced in Python 2.3, and defines the operational mode. When
-\var{posix} is not true (default), the \class{shlex} instance will
-operate in compatibility mode. When operating in \POSIX{} mode,
-\class{shlex} will try to be as close as possible to the \POSIX{} shell
-parsing rules. See section~\ref{shlex-objects}.
-\end{classdesc}
-
-\begin{seealso}
- \seemodule{ConfigParser}{Parser for configuration files similar to the
- Windows \file{.ini} files.}
-\end{seealso}
-
-
-\subsection{shlex Objects \label{shlex-objects}}
-
-A \class{shlex} instance has the following methods:
-
-\begin{methoddesc}[shlex]{get_token}{}
-Return a token. If tokens have been stacked using
-\method{push_token()}, pop a token off the stack. Otherwise, read one
-from the input stream. If reading encounters an immediate
-end-of-file, \member{self.eof} is returned (the empty string (\code{''})
-in non-\POSIX{} mode, and \code{None} in \POSIX{} mode).
-\end{methoddesc}
-
-\begin{methoddesc}[shlex]{push_token}{str}
-Push the argument onto the token stack.
-\end{methoddesc}
-
-\begin{methoddesc}[shlex]{read_token}{}
-Read a raw token. Ignore the pushback stack, and do not interpret source
-requests. (This is not ordinarily a useful entry point, and is
-documented here only for the sake of completeness.)
-\end{methoddesc}
-
-\begin{methoddesc}[shlex]{sourcehook}{filename}
-When \class{shlex} detects a source request (see
-\member{source} below) this method is given the following token as
-argument, and expected to return a tuple consisting of a filename and
-an open file-like object.
-
-Normally, this method first strips any quotes off the argument. If
-the result is an absolute pathname, or there was no previous source
-request in effect, or the previous source was a stream
-(such as \code{sys.stdin}), the result is left alone. Otherwise, if the
-result is a relative pathname, the directory part of the name of the
-file immediately before it on the source inclusion stack is prepended
-(this behavior is like the way the C preprocessor handles
-\code{\#include "file.h"}).
-
-The result of the manipulations is treated as a filename, and returned
-as the first component of the tuple, with
-\function{open()} called on it to yield the second component. (Note:
-this is the reverse of the order of arguments in instance initialization!)
-
-This hook is exposed so that you can use it to implement directory
-search paths, addition of file extensions, and other namespace hacks.
-There is no corresponding `close' hook, but a shlex instance will call
-the \method{close()} method of the sourced input stream when it
-returns \EOF.
-
-For more explicit control of source stacking, use the
-\method{push_source()} and \method{pop_source()} methods.
-\end{methoddesc}
-
-\begin{methoddesc}[shlex]{push_source}{stream\optional{, filename}}
-Push an input source stream onto the input stack. If the filename
-argument is specified it will later be available for use in error
-messages. This is the same method used internally by the
-\method{sourcehook} method.
-\versionadded{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[shlex]{pop_source}{}
-Pop the last-pushed input source from the input stack.
-This is the same method used internally when the lexer reaches
-\EOF{} on a stacked input stream.
-\versionadded{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[shlex]{error_leader}{\optional{file\optional{, line}}}
-This method generates an error message leader in the format of a
-\UNIX{} C compiler error label; the format is \code{'"\%s", line \%d: '},
-where the \samp{\%s} is replaced with the name of the current source
-file and the \samp{\%d} with the current input line number (the
-optional arguments can be used to override these).
-
-This convenience is provided to encourage \module{shlex} users to
-generate error messages in the standard, parseable format understood
-by Emacs and other \UNIX{} tools.
-\end{methoddesc}
-
-Instances of \class{shlex} subclasses have some public instance
-variables which either control lexical analysis or can be used for
-debugging:
-
-\begin{memberdesc}[shlex]{commenters}
-The string of characters that are recognized as comment beginners.
-All characters from the comment beginner to end of line are ignored.
-Includes just \character{\#} by default.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{wordchars}
-The string of characters that will accumulate into multi-character
-tokens. By default, includes all \ASCII{} alphanumerics and
-underscore.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{whitespace}
-Characters that will be considered whitespace and skipped. Whitespace
-bounds tokens. By default, includes space, tab, linefeed and
-carriage-return.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{escape}
-Characters that will be considered as escape. This will be only used
-in \POSIX{} mode, and includes just \character{\textbackslash} by default.
-\versionadded{2.3}
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{quotes}
-Characters that will be considered string quotes. The token
-accumulates until the same quote is encountered again (thus, different
-quote types protect each other as in the shell.) By default, includes
-\ASCII{} single and double quotes.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{escapedquotes}
-Characters in \member{quotes} that will interpret escape characters
-defined in \member{escape}. This is only used in \POSIX{} mode, and
-includes just \character{"} by default.
-\versionadded{2.3}
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{whitespace_split}
-If \code{True}, tokens will only be split in whitespaces. This is useful, for
-example, for parsing command lines with \class{shlex}, getting tokens
-in a similar way to shell arguments.
-\versionadded{2.3}
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{infile}
-The name of the current input file, as initially set at class
-instantiation time or stacked by later source requests. It may
-be useful to examine this when constructing error messages.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{instream}
-The input stream from which this \class{shlex} instance is reading
-characters.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{source}
-This member is \code{None} by default. If you assign a string to it,
-that string will be recognized as a lexical-level inclusion request
-similar to the \samp{source} keyword in various shells. That is, the
-immediately following token will opened as a filename and input taken
-from that stream until \EOF, at which point the \method{close()}
-method of that stream will be called and the input source will again
-become the original input stream. Source requests may be stacked any
-number of levels deep.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{debug}
-If this member is numeric and \code{1} or more, a \class{shlex}
-instance will print verbose progress output on its behavior. If you
-need to use this, you can read the module source code to learn the
-details.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{lineno}
-Source line number (count of newlines seen so far plus one).
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{token}
-The token buffer. It may be useful to examine this when catching
-exceptions.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{eof}
-Token used to determine end of file. This will be set to the empty
-string (\code{''}), in non-\POSIX{} mode, and to \code{None} in
-\POSIX{} mode.
-\versionadded{2.3}
-\end{memberdesc}
-
-\subsection{Parsing Rules\label{shlex-parsing-rules}}
-
-When operating in non-\POSIX{} mode, \class{shlex} will try to obey to
-the following rules.
-
-\begin{itemize}
-\item Quote characters are not recognized within words
- (\code{Do"Not"Separate} is parsed as the single word
- \code{Do"Not"Separate});
-\item Escape characters are not recognized;
-\item Enclosing characters in quotes preserve the literal value of
- all characters within the quotes;
-\item Closing quotes separate words (\code{"Do"Separate} is parsed
- as \code{"Do"} and \code{Separate});
-\item If \member{whitespace_split} is \code{False}, any character not
- declared to be a word character, whitespace, or a quote will be
- returned as a single-character token. If it is \code{True},
- \class{shlex} will only split words in whitespaces;
-\item EOF is signaled with an empty string (\code{''});
-\item It's not possible to parse empty strings, even if quoted.
-\end{itemize}
-
-When operating in \POSIX{} mode, \class{shlex} will try to obey to the
-following parsing rules.
-
-\begin{itemize}
-\item Quotes are stripped out, and do not separate words
- (\code{"Do"Not"Separate"} is parsed as the single word
- \code{DoNotSeparate});
-\item Non-quoted escape characters (e.g. \character{\textbackslash})
- preserve the literal value of the next character that follows;
-\item Enclosing characters in quotes which are not part of
- \member{escapedquotes} (e.g. \character{'}) preserve the literal
- value of all characters within the quotes;
-\item Enclosing characters in quotes which are part of
- \member{escapedquotes} (e.g. \character{"}) preserves the literal
- value of all characters within the quotes, with the exception of
- the characters mentioned in \member{escape}. The escape characters
- retain its special meaning only when followed by the quote in use,
- or the escape character itself. Otherwise the escape character
- will be considered a normal character.
-\item EOF is signaled with a \constant{None} value;
-\item Quoted empty strings (\code{''}) are allowed;
-\end{itemize}
-
diff --git a/Doc/lib/libshutil.tex b/Doc/lib/libshutil.tex
deleted file mode 100644
index 65cba54..0000000
--- a/Doc/lib/libshutil.tex
+++ /dev/null
@@ -1,152 +0,0 @@
-\section{\module{shutil} ---
- High-level file operations}
-
-\declaremodule{standard}{shutil}
-\modulesynopsis{High-level file operations, including copying.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-% partly based on the docstrings
-
-
-The \module{shutil} module offers a number of high-level operations on
-files and collections of files. In particular, functions are provided
-which support file copying and removal.
-\index{file!copying}
-\index{copying files}
-
-\strong{Caveat:} On MacOS, the resource fork and other metadata are
-not used. For file copies, this means that resources will be lost and
-file type and creator codes will not be correct.
-
-
-\begin{funcdesc}{copyfile}{src, dst}
- Copy the contents of the file named \var{src} to a file named
- \var{dst}. The destination location must be writable; otherwise,
- an \exception{IOError} exception will be raised.
- If \var{dst} already exists, it will be replaced.
- Special files such as character or block devices
- and pipes cannot be copied with this function. \var{src} and
- \var{dst} are path names given as strings.
-\end{funcdesc}
-
-\begin{funcdesc}{copyfileobj}{fsrc, fdst\optional{, length}}
- Copy the contents of the file-like object \var{fsrc} to the
- file-like object \var{fdst}. The integer \var{length}, if given,
- is the buffer size. In particular, a negative \var{length} value
- means to copy the data without looping over the source data in
- chunks; by default the data is read in chunks to avoid uncontrolled
- memory consumption. Note that if the current file position of the
- \var{fsrc} object is not 0, only the contents from the current file
- position to the end of the file will be copied.
-\end{funcdesc}
-
-\begin{funcdesc}{copymode}{src, dst}
- Copy the permission bits from \var{src} to \var{dst}. The file
- contents, owner, and group are unaffected. \var{src} and \var{dst}
- are path names given as strings.
-\end{funcdesc}
-
-\begin{funcdesc}{copystat}{src, dst}
- Copy the permission bits, last access time, last modification time,
- and flags from \var{src} to \var{dst}. The file contents, owner, and
- group are unaffected. \var{src} and \var{dst} are path names given
- as strings.
-\end{funcdesc}
-
-\begin{funcdesc}{copy}{src, dst}
- Copy the file \var{src} to the file or directory \var{dst}. If
- \var{dst} is a directory, a file with the same basename as \var{src}
- is created (or overwritten) in the directory specified. Permission
- bits are copied. \var{src} and \var{dst} are path names given as
- strings.
-\end{funcdesc}
-
-\begin{funcdesc}{copy2}{src, dst}
- Similar to \function{copy()}, but last access time and last
- modification time are copied as well. This is similar to the
- \UNIX{} command \program{cp} \programopt{-p}.
-\end{funcdesc}
-
-\begin{funcdesc}{copytree}{src, dst\optional{, symlinks}}
- Recursively copy an entire directory tree rooted at \var{src}. The
- destination directory, named by \var{dst}, must not already exist;
- it will be created as well as missing parent directories.
- Permissions and times of directories are copied with \function{copystat()},
- individual files are copied using \function{copy2()}.
- If \var{symlinks} is true, symbolic links in
- the source tree are represented as symbolic links in the new tree;
- if false or omitted, the contents of the linked files are copied to
- the new tree. If exception(s) occur, an \exception{Error} is raised
- with a list of reasons.
-
- The source code for this should be considered an example rather than
- a tool.
-
- \versionchanged[\exception{Error} is raised if any exceptions occur during
- copying, rather than printing a message]{2.3}
-
- \versionchanged[Create intermediate directories needed to create \var{dst},
- rather than raising an error. Copy permissions and times of
- directories using \function{copystat()}]{2.5}
-
-\end{funcdesc}
-
-\begin{funcdesc}{rmtree}{path\optional{, ignore_errors\optional{, onerror}}}
- \index{directory!deleting}
- Delete an entire directory tree (\var{path} must point to a directory).
- If \var{ignore_errors} is true, errors resulting from failed removals
- will be ignored; if false or omitted, such errors are handled by
- calling a handler specified by \var{onerror} or, if that is omitted,
- they raise an exception.
-
- If \var{onerror} is provided, it must be a callable that accepts
- three parameters: \var{function}, \var{path}, and \var{excinfo}.
- The first parameter, \var{function}, is the function which raised
- the exception; it will be \function{os.listdir()}, \function{os.remove()} or
- \function{os.rmdir()}. The second parameter, \var{path}, will be
- the path name passed to \var{function}. The third parameter,
- \var{excinfo}, will be the exception information return by
- \function{sys.exc_info()}. Exceptions raised by \var{onerror} will
- not be caught.
-\end{funcdesc}
-
-\begin{funcdesc}{move}{src, dst}
-Recursively move a file or directory to another location.
-
-If the destination is on our current filesystem, then simply use
-rename. Otherwise, copy src to the dst and then remove src.
-
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{excdesc}{Error}
-This exception collects exceptions that raised during a mult-file
-operation. For \function{copytree}, the exception argument is a
-list of 3-tuples (\var{srcname}, \var{dstname}, \var{exception}).
-
-\versionadded{2.3}
-\end{excdesc}
-
-\subsection{Example \label{shutil-example}}
-
-This example is the implementation of the \function{copytree()}
-function, described above, with the docstring omitted. It
-demonstrates many of the other functions provided by this module.
-
-\begin{verbatim}
-def copytree(src, dst, symlinks=0):
- names = os.listdir(src)
- os.mkdir(dst)
- for name in names:
- srcname = os.path.join(src, name)
- dstname = os.path.join(dst, name)
- try:
- if symlinks and os.path.islink(srcname):
- linkto = os.readlink(srcname)
- os.symlink(linkto, dstname)
- elif os.path.isdir(srcname):
- copytree(srcname, dstname, symlinks)
- else:
- copy2(srcname, dstname)
- except (IOError, os.error) as why:
- print "Can't copy %s to %s: %s" % (`srcname`, `dstname`, str(why))
-\end{verbatim}
diff --git a/Doc/lib/libsignal.tex b/Doc/lib/libsignal.tex
deleted file mode 100644
index e98aa90..0000000
--- a/Doc/lib/libsignal.tex
+++ /dev/null
@@ -1,173 +0,0 @@
-\section{\module{signal} ---
- Set handlers for asynchronous events}
-
-\declaremodule{builtin}{signal}
-\modulesynopsis{Set handlers for asynchronous events.}
-
-
-This module provides mechanisms to use signal handlers in Python.
-Some general rules for working with signals and their handlers:
-
-\begin{itemize}
-
-\item
-A handler for a particular signal, once set, remains installed until
-it is explicitly reset (Python emulates the BSD style interface
-regardless of the underlying implementation), with the exception of
-the handler for \constant{SIGCHLD}, which follows the underlying
-implementation.
-
-\item
-There is no way to ``block'' signals temporarily from critical
-sections (since this is not supported by all \UNIX{} flavors).
-
-\item
-Although Python signal handlers are called asynchronously as far as
-the Python user is concerned, they can only occur between the
-``atomic'' instructions of the Python interpreter. This means that
-signals arriving during long calculations implemented purely in C
-(such as regular expression matches on large bodies of text) may be
-delayed for an arbitrary amount of time.
-
-\item
-When a signal arrives during an I/O operation, it is possible that the
-I/O operation raises an exception after the signal handler returns.
-This is dependent on the underlying \UNIX{} system's semantics regarding
-interrupted system calls.
-
-\item
-Because the \C{} signal handler always returns, it makes little sense to
-catch synchronous errors like \constant{SIGFPE} or \constant{SIGSEGV}.
-
-\item
-Python installs a small number of signal handlers by default:
-\constant{SIGPIPE} is ignored (so write errors on pipes and sockets can be
-reported as ordinary Python exceptions) and \constant{SIGINT} is translated
-into a \exception{KeyboardInterrupt} exception. All of these can be
-overridden.
-
-\item
-Some care must be taken if both signals and threads are used in the
-same program. The fundamental thing to remember in using signals and
-threads simultaneously is:\ always perform \function{signal()} operations
-in the main thread of execution. Any thread can perform an
-\function{alarm()}, \function{getsignal()}, or \function{pause()};
-only the main thread can set a new signal handler, and the main thread
-will be the only one to receive signals (this is enforced by the
-Python \module{signal} module, even if the underlying thread
-implementation supports sending signals to individual threads). This
-means that signals can't be used as a means of inter-thread
-communication. Use locks instead.
-
-\end{itemize}
-
-The variables defined in the \module{signal} module are:
-
-\begin{datadesc}{SIG_DFL}
- This is one of two standard signal handling options; it will simply
- perform the default function for the signal. For example, on most
- systems the default action for \constant{SIGQUIT} is to dump core
- and exit, while the default action for \constant{SIGCLD} is to
- simply ignore it.
-\end{datadesc}
-
-\begin{datadesc}{SIG_IGN}
- This is another standard signal handler, which will simply ignore
- the given signal.
-\end{datadesc}
-
-\begin{datadesc}{SIG*}
- All the signal numbers are defined symbolically. For example, the
- hangup signal is defined as \constant{signal.SIGHUP}; the variable names
- are identical to the names used in C programs, as found in
- \code{<signal.h>}.
- The \UNIX{} man page for `\cfunction{signal()}' lists the existing
- signals (on some systems this is \manpage{signal}{2}, on others the
- list is in \manpage{signal}{7}).
- Note that not all systems define the same set of signal names; only
- those names defined by the system are defined by this module.
-\end{datadesc}
-
-\begin{datadesc}{NSIG}
- One more than the number of the highest signal number.
-\end{datadesc}
-
-The \module{signal} module defines the following functions:
-
-\begin{funcdesc}{alarm}{time}
- If \var{time} is non-zero, this function requests that a
- \constant{SIGALRM} signal be sent to the process in \var{time} seconds.
- Any previously scheduled alarm is canceled (only one alarm can
- be scheduled at any time). The returned value is then the number of
- seconds before any previously set alarm was to have been delivered.
- If \var{time} is zero, no alarm is scheduled, and any scheduled
- alarm is canceled. If the return value
- is zero, no alarm is currently scheduled. (See the \UNIX{} man page
- \manpage{alarm}{2}.)
- Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getsignal}{signalnum}
- Return the current signal handler for the signal \var{signalnum}.
- The returned value may be a callable Python object, or one of the
- special values \constant{signal.SIG_IGN}, \constant{signal.SIG_DFL} or
- \constant{None}. Here, \constant{signal.SIG_IGN} means that the
- signal was previously ignored, \constant{signal.SIG_DFL} means that the
- default way of handling the signal was previously in use, and
- \code{None} means that the previous signal handler was not installed
- from Python.
-\end{funcdesc}
-
-\begin{funcdesc}{pause}{}
- Cause the process to sleep until a signal is received; the
- appropriate handler will then be called. Returns nothing. Not on
- Windows. (See the \UNIX{} man page \manpage{signal}{2}.)
-\end{funcdesc}
-
-\begin{funcdesc}{signal}{signalnum, handler}
- Set the handler for signal \var{signalnum} to the function
- \var{handler}. \var{handler} can be a callable Python object
- taking two arguments (see below), or
- one of the special values \constant{signal.SIG_IGN} or
- \constant{signal.SIG_DFL}. The previous signal handler will be returned
- (see the description of \function{getsignal()} above). (See the
- \UNIX{} man page \manpage{signal}{2}.)
-
- When threads are enabled, this function can only be called from the
- main thread; attempting to call it from other threads will cause a
- \exception{ValueError} exception to be raised.
-
- The \var{handler} is called with two arguments: the signal number
- and the current stack frame (\code{None} or a frame object;
- for a description of frame objects, see the reference manual section
- on the standard type hierarchy or see the attribute descriptions in
- the \refmodule{inspect} module).
-\end{funcdesc}
-
-\subsection{Example}
-\nodename{Signal Example}
-
-Here is a minimal example program. It uses the \function{alarm()}
-function to limit the time spent waiting to open a file; this is
-useful if the file is for a serial device that may not be turned on,
-which would normally cause the \function{os.open()} to hang
-indefinitely. The solution is to set a 5-second alarm before opening
-the file; if the operation takes too long, the alarm signal will be
-sent, and the handler raises an exception.
-
-\begin{verbatim}
-import signal, os
-
-def handler(signum, frame):
- print 'Signal handler called with signal', signum
- raise IOError, "Couldn't open device!"
-
-# Set the signal handler and a 5-second alarm
-signal.signal(signal.SIGALRM, handler)
-signal.alarm(5)
-
-# This open() may hang indefinitely
-fd = os.open('/dev/ttyS0', os.O_RDWR)
-
-signal.alarm(0) # Disable the alarm
-\end{verbatim}
diff --git a/Doc/lib/libsimplehttp.tex b/Doc/lib/libsimplehttp.tex
deleted file mode 100644
index efb40ec..0000000
--- a/Doc/lib/libsimplehttp.tex
+++ /dev/null
@@ -1,86 +0,0 @@
-\section{\module{SimpleHTTPServer} ---
- Simple HTTP request handler}
-
-\declaremodule{standard}{SimpleHTTPServer}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{This module provides a basic request handler for HTTP
- servers.}
-
-
-The \module{SimpleHTTPServer} module defines a request-handler class,
-interface-compatible with \class{BaseHTTPServer.BaseHTTPRequestHandler},
-that serves files only from a base directory.
-
-The \module{SimpleHTTPServer} module defines the following class:
-
-\begin{classdesc}{SimpleHTTPRequestHandler}{request, client_address, server}
-This class is used to serve files from the current directory and below,
-directly mapping the directory structure to HTTP requests.
-
-A lot of the work, such as parsing the request, is done by the base
-class \class{BaseHTTPServer.BaseHTTPRequestHandler}. This class
-implements the \function{do_GET()} and \function{do_HEAD()} functions.
-\end{classdesc}
-
-The \class{SimpleHTTPRequestHandler} defines the following member
-variables:
-
-\begin{memberdesc}{server_version}
-This will be \code{"SimpleHTTP/" + __version__}, where \code{__version__}
-is defined in the module.
-\end{memberdesc}
-
-\begin{memberdesc}{extensions_map}
-A dictionary mapping suffixes into MIME types. The default is signified
-by an empty string, and is considered to be \code{application/octet-stream}.
-The mapping is used case-insensitively, and so should contain only
-lower-cased keys.
-\end{memberdesc}
-
-The \class{SimpleHTTPRequestHandler} defines the following methods:
-
-\begin{methoddesc}{do_HEAD}{}
-This method serves the \code{'HEAD'} request type: it sends the
-headers it would send for the equivalent \code{GET} request. See the
-\method{do_GET()} method for a more complete explanation of the possible
-headers.
-\end{methoddesc}
-
-\begin{methoddesc}{do_GET}{}
-The request is mapped to a local file by interpreting the request as
-a path relative to the current working directory.
-
-If the request was mapped to a directory, the directory is checked for
-a file named \code{index.html} or \code{index.htm} (in that order).
-If found, the file's contents are returned; otherwise a directory
-listing is generated by calling the \method{list_directory()} method.
-This method uses \function{os.listdir()} to scan the directory, and
-returns a \code{404} error response if the \function{listdir()} fails.
-
-If the request was mapped to a file, it is opened and the contents are
-returned. Any \exception{IOError} exception in opening the requested
-file is mapped to a \code{404}, \code{'File not found'}
-error. Otherwise, the content type is guessed by calling the
-\method{guess_type()} method, which in turn uses the
-\var{extensions_map} variable.
-
-A \code{'Content-type:'} header with the guessed content type is
-output, followed by a \code{'Content-Length:'} header with the file's
-size and a \code{'Last-Modified:'} header with the file's modification
-time.
-
-Then follows a blank line signifying the end of the headers,
-and then the contents of the file are output. If the file's MIME type
-starts with \code{text/} the file is opened in text mode; otherwise
-binary mode is used.
-
-For example usage, see the implementation of the \function{test()}
-function.
-\versionadded[The \code{'Last-Modified'} header]{2.5}
-\end{methoddesc}
-
-
-\begin{seealso}
- \seemodule{BaseHTTPServer}{Base class implementation for Web server
- and request handler.}
-\end{seealso}
diff --git a/Doc/lib/libsimplexmlrpc.tex b/Doc/lib/libsimplexmlrpc.tex
deleted file mode 100644
index 235905e..0000000
--- a/Doc/lib/libsimplexmlrpc.tex
+++ /dev/null
@@ -1,235 +0,0 @@
-\section{\module{SimpleXMLRPCServer} ---
- Basic XML-RPC server}
-
-\declaremodule{standard}{SimpleXMLRPCServer}
-\modulesynopsis{Basic XML-RPC server implementation.}
-\moduleauthor{Brian Quinlan}{brianq@activestate.com}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-\versionadded{2.2}
-
-The \module{SimpleXMLRPCServer} module provides a basic server
-framework for XML-RPC servers written in Python. Servers can either
-be free standing, using \class{SimpleXMLRPCServer}, or embedded in a
-CGI environment, using \class{CGIXMLRPCRequestHandler}.
-
-\begin{classdesc}{SimpleXMLRPCServer}{addr\optional{,
- requestHandler\optional{,
- logRequests\optional{,
- allow_none\optional{,
- encoding}}}}}
-
- Create a new server instance. This class
- provides methods for registration of functions that can be called by
- the XML-RPC protocol. The \var{requestHandler} parameter
- should be a factory for request handler instances; it defaults to
- \class{SimpleXMLRPCRequestHandler}. The \var{addr} and
- \var{requestHandler} parameters are passed to the
- \class{\refmodule{SocketServer}.TCPServer} constructor. If
- \var{logRequests} is true (the default), requests will be logged;
- setting this parameter to false will turn off logging.
- The \var{allow_none} and \var{encoding} parameters are passed on to
- \module{xmlrpclib} and control the XML-RPC responses that will be returned
- from the server. The \var{bind_and_activate} parameter controls whether
- \method{server_bind()} and \method{server_activate()} are called immediately
- by the constructor; it defaults to true. Setting it to false allows code to
- manipulate the \var{allow_reuse_address} class variable before the address
- is bound.
- \versionchanged[The \var{allow_none} and \var{encoding} parameters were added]{2.5}
- \versionchanged[The \var{bind_and_activate} parameter was added]{2.6}
-\end{classdesc}
-
-\begin{classdesc}{CGIXMLRPCRequestHandler}{\optional{allow_none\optional{, encoding}}}
- Create a new instance to handle XML-RPC requests in a CGI
- environment.
- The \var{allow_none} and \var{encoding} parameters are passed on to
- \module{xmlrpclib} and control the XML-RPC responses that will be returned
- from the server.
- \versionadded{2.3}
- \versionchanged[The \var{allow_none} and \var{encoding} parameters were added]{2.5}
-\end{classdesc}
-
-\begin{classdesc}{SimpleXMLRPCRequestHandler}{}
- Create a new request handler instance. This request handler
- supports \code{POST} requests and modifies logging so that the
- \var{logRequests} parameter to the \class{SimpleXMLRPCServer}
- constructor parameter is honored.
-\end{classdesc}
-
-
-\subsection{SimpleXMLRPCServer Objects \label{simple-xmlrpc-servers}}
-
-The \class{SimpleXMLRPCServer} class is based on
-\class{SocketServer.TCPServer} and provides a means of creating
-simple, stand alone XML-RPC servers.
-
-\begin{methoddesc}[SimpleXMLRPCServer]{register_function}{function\optional{,
- name}}
- Register a function that can respond to XML-RPC requests. If
- \var{name} is given, it will be the method name associated with
- \var{function}, otherwise \code{\var{function}.__name__} will be
- used. \var{name} can be either a normal or Unicode string, and may
- contain characters not legal in Python identifiers, including the
- period character.
-\end{methoddesc}
-
-\begin{methoddesc}[SimpleXMLRPCServer]{register_instance}{instance\optional{,
- allow_dotted_names}}
- Register an object which is used to expose method names which have
- not been registered using \method{register_function()}. If
- \var{instance} contains a \method{_dispatch()} method, it is called
- with the requested method name and the parameters from the request. Its
- API is \code{def \method{_dispatch}(self, method, params)} (note that
- \var{params} does not represent a variable argument list). If it calls an
- underlying function to perform its task, that function is called as
- \code{func(*params)}, expanding the parameter list.
- The return value from \method{_dispatch()} is returned to the client as
- the result. If
- \var{instance} does not have a \method{_dispatch()} method, it is
- searched for an attribute matching the name of the requested method.
-
- If the optional \var{allow_dotted_names} argument is true and the
- instance does not have a \method{_dispatch()} method, then
- if the requested method name contains periods, each component of the
- method name is searched for individually, with the effect that a
- simple hierarchical search is performed. The value found from this
- search is then called with the parameters from the request, and the
- return value is passed back to the client.
-
- \begin{notice}[warning]
- Enabling the \var{allow_dotted_names} option allows intruders to access
- your module's global variables and may allow intruders to execute
- arbitrary code on your machine. Only use this option on a secure,
- closed network.
- \end{notice}
-
- \versionchanged[\var{allow_dotted_names} was added to plug a security hole;
- prior versions are insecure]{2.3.5, 2.4.1}
-
-\end{methoddesc}
-
-\begin{methoddesc}[SimpleXMLRPCServer]{register_introspection_functions}{}
- Registers the XML-RPC introspection functions \code{system.listMethods},
- \code{system.methodHelp} and \code{system.methodSignature}.
- \versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[SimpleXMLRPCServer]{register_multicall_functions}{}
- Registers the XML-RPC multicall function system.multicall.
-\end{methoddesc}
-
-\begin{memberdesc}[SimpleXMLRPCServer]{rpc_paths}
-An attribute value that must be a tuple listing valid path portions of
-the URL for receiving XML-RPC requests. Requests posted to other
-paths will result in a 404 ``no such page'' HTTP error. If this
-tuple is empty, all paths will be considered valid.
-The default value is \code{('/', '/RPC2')}.
- \versionadded{2.5}
-\end{memberdesc}
-
-Example:
-
-\begin{verbatim}
-from SimpleXMLRPCServer import SimpleXMLRPCServer
-
-# Create server
-server = SimpleXMLRPCServer(("localhost", 8000))
-server.register_introspection_functions()
-
-# Register pow() function; this will use the value of
-# pow.__name__ as the name, which is just 'pow'.
-server.register_function(pow)
-
-# Register a function under a different name
-def adder_function(x,y):
- return x + y
-server.register_function(adder_function, 'add')
-
-# Register an instance; all the methods of the instance are
-# published as XML-RPC methods (in this case, just 'div').
-class MyFuncs:
- def div(self, x, y):
- return x // y
-
-server.register_instance(MyFuncs())
-
-# Run the server's main loop
-server.serve_forever()
-\end{verbatim}
-
-The following client code will call the methods made available by
-the preceding server:
-
-\begin{verbatim}
-import xmlrpclib
-
-s = xmlrpclib.Server('http://localhost:8000')
-print s.pow(2,3) # Returns 2**3 = 8
-print s.add(2,3) # Returns 5
-print s.div(5,2) # Returns 5//2 = 2
-
-# Print list of available methods
-print s.system.listMethods()
-\end{verbatim}
-
-
-\subsection{CGIXMLRPCRequestHandler}
-
-The \class{CGIXMLRPCRequestHandler} class can be used to
-handle XML-RPC requests sent to Python CGI scripts.
-
-\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_function}{function\optional{, name}}
-Register a function that can respond to XML-RPC requests. If
-\var{name} is given, it will be the method name associated with
-function, otherwise \var{function.__name__} will be used. \var{name}
-can be either a normal or Unicode string, and may contain
-characters not legal in Python identifiers, including the period
-character.
-\end{methoddesc}
-
-\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_instance}{instance}
-Register an object which is used to expose method names
-which have not been registered using \method{register_function()}. If
-instance contains a \method{_dispatch()} method, it is called with the
-requested method name and the parameters from the
-request; the return value is returned to the client as the result.
-If instance does not have a \method{_dispatch()} method, it is searched
-for an attribute matching the name of the requested method; if
-the requested method name contains periods, each
-component of the method name is searched for individually,
-with the effect that a simple hierarchical search is performed.
-The value found from this search is then called with the
-parameters from the request, and the return value is passed
-back to the client.
-\end{methoddesc}
-
-\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_introspection_functions}{}
-Register the XML-RPC introspection functions
-\code{system.listMethods}, \code{system.methodHelp} and
-\code{system.methodSignature}.
-\end{methoddesc}
-
-\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_multicall_functions}{}
-Register the XML-RPC multicall function \code{system.multicall}.
-\end{methoddesc}
-
-\begin{methoddesc}[CGIXMLRPCRequestHandler]{handle_request}{\optional{request_text = None}}
-Handle a XML-RPC request. If \var{request_text} is given, it
-should be the POST data provided by the HTTP server,
-otherwise the contents of stdin will be used.
-\end{methoddesc}
-
-Example:
-
-\begin{verbatim}
-class MyFuncs:
- def div(self, x, y) : return x // y
-
-
-handler = CGIXMLRPCRequestHandler()
-handler.register_function(pow)
-handler.register_function(lambda x,y: x+y, 'add')
-handler.register_introspection_functions()
-handler.register_instance(MyFuncs())
-handler.handle_request()
-\end{verbatim}
diff --git a/Doc/lib/libsite.tex b/Doc/lib/libsite.tex
deleted file mode 100644
index 11858d1..0000000
--- a/Doc/lib/libsite.tex
+++ /dev/null
@@ -1,93 +0,0 @@
-\section{\module{site} ---
- Site-specific configuration hook}
-
-\declaremodule{standard}{site}
-\modulesynopsis{A standard way to reference site-specific modules.}
-
-
-\strong{This module is automatically imported during initialization.}
-The automatic import can be suppressed using the interpreter's
-\programopt{-S} option.
-
-Importing this module will append site-specific paths to the module
-search path.
-\indexiii{module}{search}{path}
-
-It starts by constructing up to four directories from a head and a
-tail part. For the head part, it uses \code{sys.prefix} and
-\code{sys.exec_prefix}; empty heads are skipped. For
-the tail part, it uses the empty string and then
-\file{lib/site-packages} (on Windows) or
-\file{lib/python\shortversion/site-packages} and then
-\file{lib/site-python} (on \UNIX{} and Macintosh). For each of the
-distinct head-tail combinations, it sees if it refers to an existing
-directory, and if so, adds it to \code{sys.path} and also inspects
-the newly added path for configuration files.
-\indexii{site-python}{directory}
-\indexii{site-packages}{directory}
-
-A path configuration file is a file whose name has the form
-\file{\var{package}.pth} and exists in one of the four directories
-mentioned above; its contents are additional items (one per line) to
-be added to \code{sys.path}. Non-existing items are never added to
-\code{sys.path}, but no check is made that the item refers to a
-directory (rather than a file). No item is added to \code{sys.path}
-more than once. Blank lines and lines beginning with \code{\#} are
-skipped. Lines starting with \code{import} (followed by space or tab)
-are executed.
-
-\versionchanged[A space or tab is now required after the import
-keyword]{2.6}
-
-\index{package}
-\indexiii{path}{configuration}{file}
-
-For example, suppose \code{sys.prefix} and \code{sys.exec_prefix} are
-set to \file{/usr/local}. The Python \version\ library is then
-installed in \file{/usr/local/lib/python\shortversion} (where only the
-first three characters of \code{sys.version} are used to form the
-installation path name). Suppose this has a subdirectory
-\file{/usr/local/lib/python\shortversion/site-packages} with three
-subsubdirectories, \file{foo}, \file{bar} and \file{spam}, and two
-path configuration files, \file{foo.pth} and \file{bar.pth}. Assume
-\file{foo.pth} contains the following:
-
-\begin{verbatim}
-# foo package configuration
-
-foo
-bar
-bletch
-\end{verbatim}
-
-and \file{bar.pth} contains:
-
-\begin{verbatim}
-# bar package configuration
-
-bar
-\end{verbatim}
-
-Then the following directories are added to \code{sys.path}, in this
-order:
-
-\begin{verbatim}
-/usr/local/lib/python2.3/site-packages/bar
-/usr/local/lib/python2.3/site-packages/foo
-\end{verbatim}
-
-Note that \file{bletch} is omitted because it doesn't exist; the
-\file{bar} directory precedes the \file{foo} directory because
-\file{bar.pth} comes alphabetically before \file{foo.pth}; and
-\file{spam} is omitted because it is not mentioned in either path
-configuration file.
-
-After these path manipulations, an attempt is made to import a module
-named \module{sitecustomize}\refmodindex{sitecustomize}, which can
-perform arbitrary site-specific customizations. If this import fails
-with an \exception{ImportError} exception, it is silently ignored.
-
-Note that for some non-\UNIX{} systems, \code{sys.prefix} and
-\code{sys.exec_prefix} are empty, and the path manipulations are
-skipped; however the import of
-\module{sitecustomize}\refmodindex{sitecustomize} is still attempted.
diff --git a/Doc/lib/libsmtpd.tex b/Doc/lib/libsmtpd.tex
deleted file mode 100644
index 657050d..0000000
--- a/Doc/lib/libsmtpd.tex
+++ /dev/null
@@ -1,63 +0,0 @@
-\section{\module{smtpd} ---
- SMTP Server}
-
-\declaremodule{standard}{smtpd}
-
-\moduleauthor{Barry Warsaw}{barry@zope.com}
-\sectionauthor{Moshe Zadka}{moshez@moshez.org}
-
-\modulesynopsis{Implement a flexible SMTP server}
-
-This module offers several classes to implement SMTP servers. One is
-a generic do-nothing implementation, which can be overridden, while
-the other two offer specific mail-sending strategies.
-
-
-\subsection{SMTPServer Objects}
-
-\begin{classdesc}{SMTPServer}{localaddr, remoteaddr}
-Create a new \class{SMTPServer} object, which binds to local address
-\var{localaddr}. It will treat \var{remoteaddr} as an upstream SMTP
-relayer. It inherits from \class{asyncore.dispatcher}, and so will
-insert itself into \refmodule{asyncore}'s event loop on instantiation.
-\end{classdesc}
-
-\begin{methoddesc}[SMTPServer]{process_message}{peer, mailfrom, rcpttos, data}
-Raise \exception{NotImplementedError} exception. Override this in
-subclasses to do something useful with this message. Whatever was
-passed in the constructor as \var{remoteaddr} will be available as the
-\member{_remoteaddr} attribute. \var{peer} is the remote host's address,
-\var{mailfrom} is the envelope originator, \var{rcpttos} are the
-envelope recipients and \var{data} is a string containing the contents
-of the e-mail (which should be in \rfc{2822} format).
-\end{methoddesc}
-
-
-\subsection{DebuggingServer Objects}
-
-\begin{classdesc}{DebuggingServer}{localaddr, remoteaddr}
-Create a new debugging server. Arguments are as per
-\class{SMTPServer}. Messages will be discarded, and printed on
-stdout.
-\end{classdesc}
-
-
-\subsection{PureProxy Objects}
-
-\begin{classdesc}{PureProxy}{localaddr, remoteaddr}
-Create a new pure proxy server. Arguments are as per \class{SMTPServer}.
-Everything will be relayed to \var{remoteaddr}. Note that running
-this has a good chance to make you into an open relay, so please be
-careful.
-\end{classdesc}
-
-
-\subsection{MailmanProxy Objects}
-
-\begin{classdesc}{MailmanProxy}{localaddr, remoteaddr}
-Create a new pure proxy server. Arguments are as per
-\class{SMTPServer}. Everything will be relayed to \var{remoteaddr},
-unless local mailman configurations knows about an address, in which
-case it will be handled via mailman. Note that running this has a
-good chance to make you into an open relay, so please be careful.
-\end{classdesc}
diff --git a/Doc/lib/libsmtplib.tex b/Doc/lib/libsmtplib.tex
deleted file mode 100644
index 7786102..0000000
--- a/Doc/lib/libsmtplib.tex
+++ /dev/null
@@ -1,344 +0,0 @@
-\section{\module{smtplib} ---
- SMTP protocol client}
-
-\declaremodule{standard}{smtplib}
-\modulesynopsis{SMTP protocol client (requires sockets).}
-\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-
-\indexii{SMTP}{protocol}
-\index{Simple Mail Transfer Protocol}
-
-The \module{smtplib} module defines an SMTP client session object that
-can be used to send mail to any Internet machine with an SMTP or ESMTP
-listener daemon. For details of SMTP and ESMTP operation, consult
-\rfc{821} (\citetitle{Simple Mail Transfer Protocol}) and \rfc{1869}
-(\citetitle{SMTP Service Extensions}).
-
-\begin{classdesc}{SMTP}{\optional{host\optional{, port\optional{,
- local_hostname\optional{, timeout}}}}}
-A \class{SMTP} instance encapsulates an SMTP connection. It has
-methods that support a full repertoire of SMTP and ESMTP
-operations. If the optional host and port parameters are given, the
-SMTP \method{connect()} method is called with those parameters during
-initialization. An \exception{SMTPConnectError} is raised if the
-specified host doesn't respond correctly.
-The optional \var{timeout} parameter specifies a timeout in seconds for the
-connection attempt (if not specified, or passed as None, the global
-default timeout setting will be used).
-
-For normal use, you should only require the initialization/connect,
-\method{sendmail()}, and \method{quit()} methods. An example is
-included below.
-
-\versionchanged[\var{timeout} was added]{2.6}
-\end{classdesc}
-
-\begin{classdesc}{SMTP_SSL}{\optional{host\optional{, port\optional{,
- local_hostname\optional{,
- keyfile\optional{,
- certfile\optional{, timeout}}}}}}}
-A \class{SMTP_SSL} instance behaves exactly the same as instances of \class{SMTP}.
-\class{SMTP_SSL} should be used for situations where SSL is required from
-the beginning of the connection and using \method{starttls()} is not appropriate.
-If \var{host} is not specified, the local host is used. If \var{port} is
-omitted, the standard SMTP-over-SSL port (465) is used. \var{keyfile} and \var{certfile}
-are also optional, and can contain a PEM formatted private key and
-certificate chain file for the SSL connection.
-The optional \var{timeout} parameter specifies a timeout in seconds for the
-connection attempt (if not specified, or passed as None, the global
-default timeout setting will be used).
-
-\versionchanged[\var{timeout} was added]{2.6}
-\end{classdesc}
-
-\begin{classdesc}{LMTP}{\optional{host\optional{, port\optional{,
- local_hostname}}}}
-
-The LMTP protocol, which is very similar to ESMTP, is heavily based
-on the standard SMTP client. It's common to use Unix sockets for LMTP,
-so our connect() method must support that as well as a regular
-host:port server. To specify a Unix socket, you must use an absolute
-path for \var{host}, starting with a '/'.
-
-Authentication is supported, using the regular SMTP mechanism. When
-using a Unix socket, LMTP generally don't support or require any
-authentication, but your mileage might vary.
-
-\versionadded{2.6}
-
-\end{classdesc}
-
-A nice selection of exceptions is defined as well:
-
-\begin{excdesc}{SMTPException}
- Base exception class for all exceptions raised by this module.
-\end{excdesc}
-
-\begin{excdesc}{SMTPServerDisconnected}
- This exception is raised when the server unexpectedly disconnects,
- or when an attempt is made to use the \class{SMTP} instance before
- connecting it to a server.
-\end{excdesc}
-
-\begin{excdesc}{SMTPResponseException}
- Base class for all exceptions that include an SMTP error code.
- These exceptions are generated in some instances when the SMTP
- server returns an error code. The error code is stored in the
- \member{smtp_code} attribute of the error, and the
- \member{smtp_error} attribute is set to the error message.
-\end{excdesc}
-
-\begin{excdesc}{SMTPSenderRefused}
- Sender address refused. In addition to the attributes set by on all
- \exception{SMTPResponseException} exceptions, this sets `sender' to
- the string that the SMTP server refused.
-\end{excdesc}
-
-\begin{excdesc}{SMTPRecipientsRefused}
- All recipient addresses refused. The errors for each recipient are
- accessible through the attribute \member{recipients}, which is a
- dictionary of exactly the same sort as \method{SMTP.sendmail()}
- returns.
-\end{excdesc}
-
-\begin{excdesc}{SMTPDataError}
- The SMTP server refused to accept the message data.
-\end{excdesc}
-
-\begin{excdesc}{SMTPConnectError}
- Error occurred during establishment of a connection with the server.
-\end{excdesc}
-
-\begin{excdesc}{SMTPHeloError}
- The server refused our \samp{HELO} message.
-\end{excdesc}
-
-\begin{excdesc}{SMTPAuthenticationError}
- SMTP authentication went wrong. Most probably the server didn't accept
- the username/password combination provided.
-\end{excdesc}
-
-\begin{seealso}
- \seerfc{821}{Simple Mail Transfer Protocol}{Protocol definition for
- SMTP. This document covers the model, operating procedure,
- and protocol details for SMTP.}
- \seerfc{1869}{SMTP Service Extensions}{Definition of the ESMTP
- extensions for SMTP. This describes a framework for
- extending SMTP with new commands, supporting dynamic
- discovery of the commands provided by the server, and
- defines a few additional commands.}
-\end{seealso}
-
-
-\subsection{SMTP Objects \label{SMTP-objects}}
-
-An \class{SMTP} instance has the following methods:
-
-\begin{methoddesc}[SMTP]{set_debuglevel}{level}
-Set the debug output level. A true value for \var{level} results in
-debug messages for connection and for all messages sent to and
-received from the server.
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{connect}{\optional{host\optional{, port}}}
-Connect to a host on a given port. The defaults are to connect to the
-local host at the standard SMTP port (25).
-If the hostname ends with a colon (\character{:}) followed by a
-number, that suffix will be stripped off and the number interpreted as
-the port number to use.
-This method is automatically invoked by the constructor if a
-host is specified during instantiation.
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{docmd}{cmd, \optional{, argstring}}
-Send a command \var{cmd} to the server. The optional argument
-\var{argstring} is simply concatenated to the command, separated by a
-space.
-
-This returns a 2-tuple composed of a numeric response code and the
-actual response line (multiline responses are joined into one long
-line.)
-
-In normal operation it should not be necessary to call this method
-explicitly. It is used to implement other methods and may be useful
-for testing private extensions.
-
-If the connection to the server is lost while waiting for the reply,
-\exception{SMTPServerDisconnected} will be raised.
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{helo}{\optional{hostname}}
-Identify yourself to the SMTP server using \samp{HELO}. The hostname
-argument defaults to the fully qualified domain name of the local
-host.
-
-In normal operation it should not be necessary to call this method
-explicitly. It will be implicitly called by the \method{sendmail()}
-when necessary.
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{ehlo}{\optional{hostname}}
-Identify yourself to an ESMTP server using \samp{EHLO}. The hostname
-argument defaults to the fully qualified domain name of the local
-host. Examine the response for ESMTP option and store them for use by
-\method{has_extn()}.
-
-Unless you wish to use \method{has_extn()} before sending
-mail, it should not be necessary to call this method explicitly. It
-will be implicitly called by \method{sendmail()} when necessary.
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{has_extn}{name}
-Return \constant{True} if \var{name} is in the set of SMTP service
-extensions returned by the server, \constant{False} otherwise.
-Case is ignored.
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{verify}{address}
-Check the validity of an address on this server using SMTP \samp{VRFY}.
-Returns a tuple consisting of code 250 and a full \rfc{822} address
-(including human name) if the user address is valid. Otherwise returns
-an SMTP error code of 400 or greater and an error string.
-
-\note{Many sites disable SMTP \samp{VRFY} in order to foil spammers.}
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{login}{user, password}
-Log in on an SMTP server that requires authentication.
-The arguments are the username and the password to authenticate with.
-If there has been no previous \samp{EHLO} or \samp{HELO} command this
-session, this method tries ESMTP \samp{EHLO} first.
-This method will return normally if the authentication was successful,
-or may raise the following exceptions:
-
-\begin{description}
- \item[\exception{SMTPHeloError}]
- The server didn't reply properly to the \samp{HELO} greeting.
- \item[\exception{SMTPAuthenticationError}]
- The server didn't accept the username/password combination.
- \item[\exception{SMTPException}]
- No suitable authentication method was found.
-\end{description}
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{starttls}{\optional{keyfile\optional{, certfile}}}
-Put the SMTP connection in TLS (Transport Layer Security) mode. All
-SMTP commands that follow will be encrypted. You should then call
-\method{ehlo()} again.
-
-If \var{keyfile} and \var{certfile} are provided, these are passed to
-the \refmodule{socket} module's \function{ssl()} function.
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{sendmail}{from_addr, to_addrs, msg\optional{,
- mail_options, rcpt_options}}
-Send mail. The required arguments are an \rfc{822} from-address
-string, a list of \rfc{822} to-address strings (a bare string will be
-treated as a list with 1 address), and a message string. The caller
-may pass a list of ESMTP options (such as \samp{8bitmime}) to be used
-in \samp{MAIL FROM} commands as \var{mail_options}. ESMTP options
-(such as \samp{DSN} commands) that should be used with all \samp{RCPT}
-commands can be passed as \var{rcpt_options}. (If you need to use
-different ESMTP options to different recipients you have to use the
-low-level methods such as \method{mail}, \method{rcpt} and
-\method{data} to send the message.)
-
-\note{The \var{from_addr} and \var{to_addrs} parameters are
-used to construct the message envelope used by the transport agents.
-The \class{SMTP} does not modify the message headers in any way.}
-
-If there has been no previous \samp{EHLO} or \samp{HELO} command this
-session, this method tries ESMTP \samp{EHLO} first. If the server does
-ESMTP, message size and each of the specified options will be passed
-to it (if the option is in the feature set the server advertises). If
-\samp{EHLO} fails, \samp{HELO} will be tried and ESMTP options
-suppressed.
-
-This method will return normally if the mail is accepted for at least
-one recipient. Otherwise it will throw an exception. That is, if this
-method does not throw an exception, then someone should get your mail.
-If this method does not throw an exception, it returns a dictionary,
-with one entry for each recipient that was refused. Each entry
-contains a tuple of the SMTP error code and the accompanying error
-message sent by the server.
-
-This method may raise the following exceptions:
-
-\begin{description}
-\item[\exception{SMTPRecipientsRefused}]
-All recipients were refused. Nobody got the mail. The
-\member{recipients} attribute of the exception object is a dictionary
-with information about the refused recipients (like the one returned
-when at least one recipient was accepted).
-
-\item[\exception{SMTPHeloError}]
-The server didn't reply properly to the \samp{HELO} greeting.
-
-\item[\exception{SMTPSenderRefused}]
-The server didn't accept the \var{from_addr}.
-
-\item[\exception{SMTPDataError}]
-The server replied with an unexpected error code (other than a refusal
-of a recipient).
-\end{description}
-
-Unless otherwise noted, the connection will be open even after
-an exception is raised.
-
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{quit}{}
-Terminate the SMTP session and close the connection.
-\end{methoddesc}
-
-Low-level methods corresponding to the standard SMTP/ESMTP commands
-\samp{HELP}, \samp{RSET}, \samp{NOOP}, \samp{MAIL}, \samp{RCPT}, and
-\samp{DATA} are also supported. Normally these do not need to be
-called directly, so they are not documented here. For details,
-consult the module code.
-
-
-\subsection{SMTP Example \label{SMTP-example}}
-
-This example prompts the user for addresses needed in the message
-envelope (`To' and `From' addresses), and the message to be
-delivered. Note that the headers to be included with the message must
-be included in the message as entered; this example doesn't do any
-processing of the \rfc{822} headers. In particular, the `To' and
-`From' addresses must be included in the message headers explicitly.
-
-\begin{verbatim}
-import smtplib
-
-def raw_input(prompt):
- import sys
- sys.stdout.write(prompt)
- sys.stdout.flush()
- return sys.stdin.readline()
-
-def prompt(prompt):
- return raw_input(prompt).strip()
-
-fromaddr = prompt("From: ")
-toaddrs = prompt("To: ").split()
-print "Enter message, end with ^D (Unix) or ^Z (Windows):"
-
-# Add the From: and To: headers at the start!
-msg = ("From: %s\r\nTo: %s\r\n\r\n"
- % (fromaddr, ", ".join(toaddrs)))
-while 1:
- try:
- line = raw_input()
- except EOFError:
- break
- if not line:
- break
- msg = msg + line
-
-print "Message length is " + repr(len(msg))
-
-server = smtplib.SMTP('localhost')
-server.set_debuglevel(1)
-server.sendmail(fromaddr, toaddrs, msg)
-server.quit()
-\end{verbatim}
diff --git a/Doc/lib/libsndhdr.tex b/Doc/lib/libsndhdr.tex
deleted file mode 100644
index a7f8c6e..0000000
--- a/Doc/lib/libsndhdr.tex
+++ /dev/null
@@ -1,41 +0,0 @@
-\section{\module{sndhdr} ---
- Determine type of sound file}
-
-\declaremodule{standard}{sndhdr}
-\modulesynopsis{Determine type of a sound file.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-% Based on comments in the module source file.
-
-
-The \module{sndhdr} provides utility functions which attempt to
-determine the type of sound data which is in a file. When these
-functions are able to determine what type of sound data is stored in a
-file, they return a tuple \code{(\var{type}, \var{sampling_rate},
-\var{channels}, \var{frames}, \var{bits_per_sample})}. The value for
-\var{type} indicates the data type and will be one of the strings
-\code{'aifc'}, \code{'aiff'}, \code{'au'}, \code{'hcom'},
-\code{'sndr'}, \code{'sndt'}, \code{'voc'}, \code{'wav'},
-\code{'8svx'}, \code{'sb'}, \code{'ub'}, or \code{'ul'}. The
-\var{sampling_rate} will be either the actual value or \code{0} if
-unknown or difficult to decode. Similarly, \var{channels} will be
-either the number of channels or \code{0} if it cannot be determined
-or if the value is difficult to decode. The value for \var{frames}
-will be either the number of frames or \code{-1}. The last item in
-the tuple, \var{bits_per_sample}, will either be the sample size in
-bits or \code{'A'} for A-LAW\index{A-LAW} or \code{'U'} for
-u-LAW\index{u-LAW}.
-
-
-\begin{funcdesc}{what}{filename}
- Determines the type of sound data stored in the file \var{filename}
- using \function{whathdr()}. If it succeeds, returns a tuple as
- described above, otherwise \code{None} is returned.
-\end{funcdesc}
-
-
-\begin{funcdesc}{whathdr}{filename}
- Determines the type of sound data stored in a file based on the file
- header. The name of the file is given by \var{filename}. This
- function returns a tuple as described above on success, or
- \code{None}.
-\end{funcdesc}
diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex
deleted file mode 100644
index e3fce23..0000000
--- a/Doc/lib/libsocket.tex
+++ /dev/null
@@ -1,921 +0,0 @@
-\section{\module{socket} ---
- Low-level networking interface}
-
-\declaremodule{builtin}{socket}
-\modulesynopsis{Low-level networking interface.}
-
-
-This module provides access to the BSD \emph{socket} interface.
-It is available on all modern \UNIX{} systems, Windows, MacOS, BeOS,
-OS/2, and probably additional platforms. \note{Some behavior may be
-platform dependent, since calls are made to the operating system socket APIs.}
-
-For an introduction to socket programming (in C), see the following
-papers: \citetitle{An Introductory 4.3BSD Interprocess Communication
-Tutorial}, by Stuart Sechrest and \citetitle{An Advanced 4.3BSD
-Interprocess Communication Tutorial}, by Samuel J. Leffler et al,
-both in the \citetitle{UNIX Programmer's Manual, Supplementary Documents 1}
-(sections PS1:7 and PS1:8). The platform-specific reference material
-for the various socket-related system calls are also a valuable source
-of information on the details of socket semantics. For \UNIX, refer
-to the manual pages; for Windows, see the WinSock (or Winsock 2)
-specification.
-For IPv6-ready APIs, readers may want to refer to \rfc{2553} titled
-\citetitle{Basic Socket Interface Extensions for IPv6}.
-
-The Python interface is a straightforward transliteration of the
-\UNIX{} system call and library interface for sockets to Python's
-object-oriented style: the \function{socket()} function returns a
-\dfn{socket object}\obindex{socket} whose methods implement the
-various socket system calls. Parameter types are somewhat
-higher-level than in the C interface: as with \method{read()} and
-\method{write()} operations on Python files, buffer allocation on
-receive operations is automatic, and buffer length is implicit on send
-operations.
-
-Socket addresses are represented as follows:
-A single string is used for the \constant{AF_UNIX} address family.
-A pair \code{(\var{host}, \var{port})} is used for the
-\constant{AF_INET} address family, where \var{host} is a string
-representing either a hostname in Internet domain notation like
-\code{'daring.cwi.nl'} or an IPv4 address like \code{'100.50.200.5'},
-and \var{port} is an integral port number.
-For \constant{AF_INET6} address family, a four-tuple
-\code{(\var{host}, \var{port}, \var{flowinfo}, \var{scopeid})} is
-used, where \var{flowinfo} and \var{scopeid} represents
-\code{sin6_flowinfo} and \code{sin6_scope_id} member in
-\constant{struct sockaddr_in6} in C.
-For \module{socket} module methods, \var{flowinfo} and \var{scopeid}
-can be omitted just for backward compatibility. Note, however,
-omission of \var{scopeid} can cause problems in manipulating scoped
-IPv6 addresses. Other address families are currently not supported.
-The address format required by a particular socket object is
-automatically selected based on the address family specified when the
-socket object was created.
-
-For IPv4 addresses, two special forms are accepted instead of a host
-address: the empty string represents \constant{INADDR_ANY}, and the string
-\code{'<broadcast>'} represents \constant{INADDR_BROADCAST}.
-The behavior is not available for IPv6 for backward compatibility,
-therefore, you may want to avoid these if you intend to support IPv6 with
-your Python programs.
-
-If you use a hostname in the \var{host} portion of IPv4/v6 socket
-address, the program may show a nondeterministic behavior, as Python
-uses the first address returned from the DNS resolution. The socket
-address will be resolved differently into an actual IPv4/v6 address,
-depending on the results from DNS resolution and/or the host
-configuration. For deterministic behavior use a numeric address in
-\var{host} portion.
-
-\versionadded[AF_NETLINK sockets are represented as
-pairs \code{\var{pid}, \var{groups}}]{2.5}
-
-All errors raise exceptions. The normal exceptions for invalid
-argument types and out-of-memory conditions can be raised; errors
-related to socket or address semantics raise the error
-\exception{socket.error}.
-
-Non-blocking mode is supported through
-\method{setblocking()}. A generalization of this based on timeouts
-is supported through \method{settimeout()}.
-
-The module \module{socket} exports the following constants and functions:
-
-
-\begin{excdesc}{error}
-This exception is raised for socket-related errors.
-The accompanying value is either a string telling what went wrong or a
-pair \code{(\var{errno}, \var{string})}
-representing an error returned by a system
-call, similar to the value accompanying \exception{os.error}.
-See the module \refmodule{errno}\refbimodindex{errno}, which contains
-names for the error codes defined by the underlying operating system.
-\end{excdesc}
-
-\begin{excdesc}{herror}
-This exception is raised for address-related errors, i.e. for
-functions that use \var{h_errno} in the C API, including
-\function{gethostbyname_ex()} and \function{gethostbyaddr()}.
-
-The accompanying value is a pair \code{(\var{h_errno}, \var{string})}
-representing an error returned by a library call. \var{string}
-represents the description of \var{h_errno}, as returned by
-the \cfunction{hstrerror()} C function.
-\end{excdesc}
-
-\begin{excdesc}{gaierror}
-This exception is raised for address-related errors, for
-\function{getaddrinfo()} and \function{getnameinfo()}.
-The accompanying value is a pair \code{(\var{error}, \var{string})}
-representing an error returned by a library call.
-\var{string} represents the description of \var{error}, as returned
-by the \cfunction{gai_strerror()} C function.
-The \var{error} value will match one of the \constant{EAI_*} constants
-defined in this module.
-\end{excdesc}
-
-\begin{excdesc}{timeout}
-This exception is raised when a timeout occurs on a socket which has
-had timeouts enabled via a prior call to \method{settimeout()}. The
-accompanying value is a string whose value is currently always ``timed
-out''.
-\versionadded{2.3}
-\end{excdesc}
-
-\begin{datadesc}{AF_UNIX}
-\dataline{AF_INET}
-\dataline{AF_INET6}
-These constants represent the address (and protocol) families,
-used for the first argument to \function{socket()}. If the
-\constant{AF_UNIX} constant is not defined then this protocol is
-unsupported.
-\end{datadesc}
-
-\begin{datadesc}{SOCK_STREAM}
-\dataline{SOCK_DGRAM}
-\dataline{SOCK_RAW}
-\dataline{SOCK_RDM}
-\dataline{SOCK_SEQPACKET}
-These constants represent the socket types,
-used for the second argument to \function{socket()}.
-(Only \constant{SOCK_STREAM} and
-\constant{SOCK_DGRAM} appear to be generally useful.)
-\end{datadesc}
-
-\begin{datadesc}{SO_*}
-\dataline{SOMAXCONN}
-\dataline{MSG_*}
-\dataline{SOL_*}
-\dataline{IPPROTO_*}
-\dataline{IPPORT_*}
-\dataline{INADDR_*}
-\dataline{IP_*}
-\dataline{IPV6_*}
-\dataline{EAI_*}
-\dataline{AI_*}
-\dataline{NI_*}
-\dataline{TCP_*}
-Many constants of these forms, documented in the \UNIX{} documentation on
-sockets and/or the IP protocol, are also defined in the socket module.
-They are generally used in arguments to the \method{setsockopt()} and
-\method{getsockopt()} methods of socket objects. In most cases, only
-those symbols that are defined in the \UNIX{} header files are defined;
-for a few symbols, default values are provided.
-\end{datadesc}
-
-\begin{datadesc}{has_ipv6}
-This constant contains a boolean value which indicates if IPv6 is
-supported on this platform.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{funcdesc}{create_connection}{address\optional{, timeout}}
-Connects to the \var{address} received (as usual, a \code{(host, port)}
-pair), with an optional timeout for the connection. Specially useful for
-higher-level protocols, it is not normally used directly from
-application-level code. Passing the optional \var{timeout} parameter
-will set the timeout on the socket instance (if it is not given or
-\code{None}, the global default timeout setting is used).
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{getaddrinfo}{host, port\optional{, family\optional{,
- socktype\optional{, proto\optional{,
- flags}}}}}
-Resolves the \var{host}/\var{port} argument, into a sequence of
-5-tuples that contain all the necessary argument for the sockets
-manipulation. \var{host} is a domain name, a string representation of
-IPv4/v6 address or \code{None}.
-\var{port} is a string service name (like \code{'http'}), a numeric
-port number or \code{None}.
-
-The rest of the arguments are optional and must be numeric if
-specified. For \var{host} and \var{port}, by passing either an empty
-string or \code{None}, you can pass \code{NULL} to the C API. The
-\function{getaddrinfo()} function returns a list of 5-tuples with
-the following structure:
-
-\code{(\var{family}, \var{socktype}, \var{proto}, \var{canonname},
- \var{sockaddr})}
-
-\var{family}, \var{socktype}, \var{proto} are all integer and are meant to
-be passed to the \function{socket()} function.
-\var{canonname} is a string representing the canonical name of the \var{host}.
-It can be a numeric IPv4/v6 address when \constant{AI_CANONNAME} is specified
-for a numeric \var{host}.
-\var{sockaddr} is a tuple describing a socket address, as described above.
-See the source for the \refmodule{httplib} and other library modules
-for a typical usage of the function.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{getfqdn}{\optional{name}}
-Return a fully qualified domain name for \var{name}.
-If \var{name} is omitted or empty, it is interpreted as the local
-host. To find the fully qualified name, the hostname returned by
-\function{gethostbyaddr()} is checked, then aliases for the host, if
-available. The first name which includes a period is selected. In
-case no fully qualified domain name is available, the hostname as
-returned by \function{gethostname()} is returned.
-\versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{gethostbyname}{hostname}
-Translate a host name to IPv4 address format. The IPv4 address is
-returned as a string, such as \code{'100.50.200.5'}. If the host name
-is an IPv4 address itself it is returned unchanged. See
-\function{gethostbyname_ex()} for a more complete interface.
-\function{gethostbyname()} does not support IPv6 name resolution, and
-\function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support.
-\end{funcdesc}
-
-\begin{funcdesc}{gethostbyname_ex}{hostname}
-Translate a host name to IPv4 address format, extended interface.
-Return a triple \code{(\var{hostname}, \var{aliaslist},
-\var{ipaddrlist})} where
-\var{hostname} is the primary host name responding to the given
-\var{ip_address}, \var{aliaslist} is a (possibly empty) list of
-alternative host names for the same address, and \var{ipaddrlist} is
-a list of IPv4 addresses for the same interface on the same
-host (often but not always a single address).
-\function{gethostbyname_ex()} does not support IPv6 name resolution, and
-\function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support.
-\end{funcdesc}
-
-\begin{funcdesc}{gethostname}{}
-Return a string containing the hostname of the machine where
-the Python interpreter is currently executing.
-If you want to know the current machine's IP address, you may want to use
-\code{gethostbyname(gethostname())}.
-This operation assumes that there is a valid address-to-host mapping for
-the host, and the assumption does not always hold.
-Note: \function{gethostname()} doesn't always return the fully qualified
-domain name; use \code{getfqdn()}
-(see above).
-\end{funcdesc}
-
-\begin{funcdesc}{gethostbyaddr}{ip_address}
-Return a triple \code{(\var{hostname}, \var{aliaslist},
-\var{ipaddrlist})} where \var{hostname} is the primary host name
-responding to the given \var{ip_address}, \var{aliaslist} is a
-(possibly empty) list of alternative host names for the same address,
-and \var{ipaddrlist} is a list of IPv4/v6 addresses for the same interface
-on the same host (most likely containing only a single address).
-To find the fully qualified domain name, use the function
-\function{getfqdn()}.
-\function{gethostbyaddr} supports both IPv4 and IPv6.
-\end{funcdesc}
-
-\begin{funcdesc}{getnameinfo}{sockaddr, flags}
-Translate a socket address \var{sockaddr} into a 2-tuple
-\code{(\var{host}, \var{port})}.
-Depending on the settings of \var{flags}, the result can contain a
-fully-qualified domain name or numeric address representation in
-\var{host}. Similarly, \var{port} can contain a string port name or a
-numeric port number.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{getprotobyname}{protocolname}
-Translate an Internet protocol name (for example, \code{'icmp'}) to a constant
-suitable for passing as the (optional) third argument to the
-\function{socket()} function. This is usually only needed for sockets
-opened in ``raw'' mode (\constant{SOCK_RAW}); for the normal socket
-modes, the correct protocol is chosen automatically if the protocol is
-omitted or zero.
-\end{funcdesc}
-
-\begin{funcdesc}{getservbyname}{servicename\optional{, protocolname}}
-Translate an Internet service name and protocol name to a port number
-for that service. The optional protocol name, if given, should be
-\code{'tcp'} or \code{'udp'}, otherwise any protocol will match.
-\end{funcdesc}
-
-\begin{funcdesc}{getservbyport}{port\optional{, protocolname}}
-Translate an Internet port number and protocol name to a service name
-for that service. The optional protocol name, if given, should be
-\code{'tcp'} or \code{'udp'}, otherwise any protocol will match.
-\end{funcdesc}
-
-\begin{funcdesc}{socket}{\optional{family\optional{,
- type\optional{, proto}}}}
-Create a new socket using the given address family, socket type and
-protocol number. The address family should be \constant{AF_INET} (the
-default), \constant{AF_INET6} or \constant{AF_UNIX}. The socket type
-should be \constant{SOCK_STREAM} (the default), \constant{SOCK_DGRAM}
-or perhaps one of the other \samp{SOCK_} constants. The protocol
-number is usually zero and may be omitted in that case.
-\end{funcdesc}
-
-\begin{funcdesc}{ssl}{sock\optional{, keyfile, certfile}}
-Initiate a SSL connection over the socket \var{sock}. \var{keyfile} is
-the name of a PEM formatted file that contains your private
-key. \var{certfile} is a PEM formatted certificate chain file. On
-success, a new \class{SSLObject} is returned.
-
-\warning{This does not do any certificate verification!}
-\end{funcdesc}
-
-\begin{funcdesc}{socketpair}{\optional{family\optional{, type\optional{, proto}}}}
-Build a pair of connected socket objects using the given address
-family, socket type, and protocol number. Address family, socket type,
-and protocol number are as for the \function{socket()} function above.
-The default family is \constant{AF_UNIX} if defined on the platform;
-otherwise, the default is \constant{AF_INET}.
-Availability: \UNIX. \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}}
-Duplicate the file descriptor \var{fd} (an integer as returned by a file
-object's \method{fileno()} method) and build a socket object from the
-result. Address family, socket type and protocol number are as for the
-\function{socket()} function above.
-The file descriptor should refer to a socket, but this is not
-checked --- subsequent operations on the object may fail if the file
-descriptor is invalid. This function is rarely needed, but can be
-used to get or set socket options on a socket passed to a program as
-standard input or output (such as a server started by the \UNIX{} inet
-daemon). The socket is assumed to be in blocking mode.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{ntohl}{x}
-Convert 32-bit positive integers from network to host byte order. On machines
-where the host byte order is the same as network byte order, this is a
-no-op; otherwise, it performs a 4-byte swap operation.
-\end{funcdesc}
-
-\begin{funcdesc}{ntohs}{x}
-Convert 16-bit positive integers from network to host byte order. On machines
-where the host byte order is the same as network byte order, this is a
-no-op; otherwise, it performs a 2-byte swap operation.
-\end{funcdesc}
-
-\begin{funcdesc}{htonl}{x}
-Convert 32-bit positive integers from host to network byte order. On machines
-where the host byte order is the same as network byte order, this is a
-no-op; otherwise, it performs a 4-byte swap operation.
-\end{funcdesc}
-
-\begin{funcdesc}{htons}{x}
-Convert 16-bit positive integers from host to network byte order. On machines
-where the host byte order is the same as network byte order, this is a
-no-op; otherwise, it performs a 2-byte swap operation.
-\end{funcdesc}
-
-\begin{funcdesc}{inet_aton}{ip_string}
-Convert an IPv4 address from dotted-quad string format (for example,
-'123.45.67.89') to 32-bit packed binary format, as a string four
-characters in length. This is useful when conversing with a program
-that uses the standard C library and needs objects of type
-\ctype{struct in_addr}, which is the C type for the 32-bit packed
-binary this function returns.
-
-If the IPv4 address string passed to this function is invalid,
-\exception{socket.error} will be raised. Note that exactly what is
-valid depends on the underlying C implementation of
-\cfunction{inet_aton()}.
-
-\function{inet_aton()} does not support IPv6, and
-\function{getnameinfo()} should be used instead for IPv4/v6 dual stack
-support.
-\end{funcdesc}
-
-\begin{funcdesc}{inet_ntoa}{packed_ip}
-Convert a 32-bit packed IPv4 address (a string four characters in
-length) to its standard dotted-quad string representation (for
-example, '123.45.67.89'). This is useful when conversing with a
-program that uses the standard C library and needs objects of type
-\ctype{struct in_addr}, which is the C type for the 32-bit packed
-binary data this function takes as an argument.
-
-If the string passed to this function is not exactly 4 bytes in
-length, \exception{socket.error} will be raised.
-\function{inet_ntoa()} does not support IPv6, and
-\function{getnameinfo()} should be used instead for IPv4/v6 dual stack
-support.
-\end{funcdesc}
-
-\begin{funcdesc}{inet_pton}{address_family, ip_string}
-Convert an IP address from its family-specific string format to a packed,
-binary format.
-\function{inet_pton()} is useful when a library or network protocol calls for
-an object of type \ctype{struct in_addr} (similar to \function{inet_aton()})
-or \ctype{struct in6_addr}.
-
-Supported values for \var{address_family} are currently
-\constant{AF_INET} and \constant{AF_INET6}.
-If the IP address string \var{ip_string} is invalid,
-\exception{socket.error} will be raised. Note that exactly what is valid
-depends on both the value of \var{address_family} and the underlying
-implementation of \cfunction{inet_pton()}.
-
-Availability: \UNIX{} (maybe not all platforms).
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{inet_ntop}{address_family, packed_ip}
-Convert a packed IP address (a string of some number of characters) to
-its standard, family-specific string representation (for example,
-\code{'7.10.0.5'} or \code{'5aef:2b::8'})
-\function{inet_ntop()} is useful when a library or network protocol returns
-an object of type \ctype{struct in_addr} (similar to \function{inet_ntoa()})
-or \ctype{struct in6_addr}.
-
-Supported values for \var{address_family} are currently
-\constant{AF_INET} and \constant{AF_INET6}.
-If the string \var{packed_ip} is not the correct length for the
-specified address family, \exception{ValueError} will be raised. A
-\exception{socket.error} is raised for errors from the call to
-\function{inet_ntop()}.
-
-Availability: \UNIX{} (maybe not all platforms).
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getdefaulttimeout}{}
-Return the default timeout in floating seconds for new socket objects.
-A value of \code{None} indicates that new socket objects have no timeout.
-When the socket module is first imported, the default is \code{None}.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{setdefaulttimeout}{timeout}
-Set the default timeout in floating seconds for new socket objects.
-A value of \code{None} indicates that new socket objects have no timeout.
-When the socket module is first imported, the default is \code{None}.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{datadesc}{SocketType}
-This is a Python type object that represents the socket object type.
-It is the same as \code{type(socket(...))}.
-\end{datadesc}
-
-
-\begin{seealso}
- \seemodule{SocketServer}{Classes that simplify writing network servers.}
-\end{seealso}
-
-
-\subsection{Socket Objects \label{socket-objects}}
-
-Socket objects have the following methods. Except for
-\method{makefile()} these correspond to \UNIX{} system calls
-applicable to sockets.
-
-\begin{methoddesc}[socket]{accept}{}
-Accept a connection.
-The socket must be bound to an address and listening for connections.
-The return value is a pair \code{(\var{conn}, \var{address})}
-where \var{conn} is a \emph{new} socket object usable to send and
-receive data on the connection, and \var{address} is the address bound
-to the socket on the other end of the connection.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{bind}{address}
-Bind the socket to \var{address}. The socket must not already be bound.
-(The format of \var{address} depends on the address family --- see
-above.) \note{This method has historically accepted a pair
-of parameters for \constant{AF_INET} addresses instead of only a
-tuple. This was never intentional and is no longer available in
-Python 2.0 and later.}
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{close}{}
-Close the socket. All future operations on the socket object will fail.
-The remote end will receive no more data (after queued data is flushed).
-Sockets are automatically closed when they are garbage-collected.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{connect}{address}
-Connect to a remote socket at \var{address}.
-(The format of \var{address} depends on the address family --- see
-above.) \note{This method has historically accepted a pair
-of parameters for \constant{AF_INET} addresses instead of only a
-tuple. This was never intentional and is no longer available in
-Python 2.0 and later.}
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{connect_ex}{address}
-Like \code{connect(\var{address})}, but return an error indicator
-instead of raising an exception for errors returned by the C-level
-\cfunction{connect()} call (other problems, such as ``host not found,''
-can still raise exceptions). The error indicator is \code{0} if the
-operation succeeded, otherwise the value of the \cdata{errno}
-variable. This is useful to support, for example, asynchronous connects.
-\note{This method has historically accepted a pair of
-parameters for \constant{AF_INET} addresses instead of only a tuple.
-This was never intentional and is no longer available in Python
-2.0 and later.}
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{fileno}{}
-Return the socket's file descriptor (a small integer). This is useful
-with \function{select.select()}.
-
-Under Windows the small integer returned by this method cannot be used where
-a file descriptor can be used (such as \function{os.fdopen()}). \UNIX{} does
-not have this limitation.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{getpeername}{}
-Return the remote address to which the socket is connected. This is
-useful to find out the port number of a remote IPv4/v6 socket, for instance.
-(The format of the address returned depends on the address family ---
-see above.) On some systems this function is not supported.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{getsockname}{}
-Return the socket's own address. This is useful to find out the port
-number of an IPv4/v6 socket, for instance.
-(The format of the address returned depends on the address family ---
-see above.)
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{getsockopt}{level, optname\optional{, buflen}}
-Return the value of the given socket option (see the \UNIX{} man page
-\manpage{getsockopt}{2}). The needed symbolic constants
-(\constant{SO_*} etc.) are defined in this module. If \var{buflen}
-is absent, an integer option is assumed and its integer value
-is returned by the function. If \var{buflen} is present, it specifies
-the maximum length of the buffer used to receive the option in, and
-this buffer is returned as a string. It is up to the caller to decode
-the contents of the buffer (see the optional built-in module
-\refmodule{struct} for a way to decode C structures encoded as strings).
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{listen}{backlog}
-Listen for connections made to the socket. The \var{backlog} argument
-specifies the maximum number of queued connections and should be at
-least 1; the maximum value is system-dependent (usually 5).
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{makefile}{\optional{mode\optional{, bufsize}}}
-Return a \dfn{file object} associated with the socket. (File objects
-are described in \ref{bltin-file-objects}, ``File Objects.'')
-The file object references a \cfunction{dup()}ped version of the
-socket file descriptor, so the file object and socket object may be
-closed or garbage-collected independently.
-The socket must be in blocking mode (it can not have a timeout).
-\index{I/O control!buffering}The optional \var{mode}
-and \var{bufsize} arguments are interpreted the same way as by the
-built-in \function{file()} function; see ``Built-in Functions''
-(section \ref{built-in-funcs}) for more information.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{recv}{bufsize\optional{, flags}}
-Receive data from the socket. The return value is a string representing
-the data received. The maximum amount of data to be received
-at once is specified by \var{bufsize}. See the \UNIX{} manual page
-\manpage{recv}{2} for the meaning of the optional argument
-\var{flags}; it defaults to zero.
-\note{For best match with hardware and network realities, the value of
-\var{bufsize} should be a relatively small power of 2, for example, 4096.}
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{recvfrom}{bufsize\optional{, flags}}
-Receive data from the socket. The return value is a pair
-\code{(\var{string}, \var{address})} where \var{string} is a string
-representing the data received and \var{address} is the address of the
-socket sending the data. See the \UNIX{} manual page
-\manpage{recv}{2} for the meaning of the optional argument
-\var{flags}; it defaults to zero.
-(The format of \var{address} depends on the address family --- see above.)
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{recvfrom_into}{buffer\optional{, nbytes\optional{, flags}}}
-Receive data from the socket, writing it into \var{buffer} instead of
-creating a new string. The return value is a pair
-\code{(\var{nbytes}, \var{address})} where \var{nbytes} is the number
-of bytes received and \var{address} is the address of the socket
-sending the data. See the \UNIX{} manual page
-\manpage{recv}{2} for the meaning of the optional argument
-\var{flags}; it defaults to zero. (The format of \var{address}
-depends on the address family --- see above.)
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{recv_into}{buffer\optional{, nbytes\optional{, flags}}}
-Receive up to \var{nbytes} bytes from the socket,
-storing the data into a buffer rather than creating a new string.
-If \var{nbytes} is not specified (or 0),
-receive up to the size available in the given buffer.
-See the \UNIX{} manual page \manpage{recv}{2} for the meaning of the
-optional argument \var{flags}; it defaults to zero.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{send}{string\optional{, flags}}
-Send data to the socket. The socket must be connected to a remote
-socket. The optional \var{flags} argument has the same meaning as for
-\method{recv()} above. Returns the number of bytes sent.
-Applications are responsible for checking that all data has been sent;
-if only some of the data was transmitted, the application needs to
-attempt delivery of the remaining data.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{sendall}{string\optional{, flags}}
-Send data to the socket. The socket must be connected to a remote
-socket. The optional \var{flags} argument has the same meaning as for
-\method{recv()} above. Unlike \method{send()}, this method continues
-to send data from \var{string} until either all data has been sent or
-an error occurs. \code{None} is returned on success. On error, an
-exception is raised, and there is no way to determine how much data,
-if any, was successfully sent.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{sendto}{string\optional{, flags}, address}
-Send data to the socket. The socket should not be connected to a
-remote socket, since the destination socket is specified by
-\var{address}. The optional \var{flags} argument has the same
-meaning as for \method{recv()} above. Return the number of bytes sent.
-(The format of \var{address} depends on the address family --- see above.)
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{setblocking}{flag}
-Set blocking or non-blocking mode of the socket: if \var{flag} is 0,
-the socket is set to non-blocking, else to blocking mode. Initially
-all sockets are in blocking mode. In non-blocking mode, if a
-\method{recv()} call doesn't find any data, or if a
-\method{send()} call can't immediately dispose of the data, a
-\exception{error} exception is raised; in blocking mode, the calls
-block until they can proceed.
-\code{s.setblocking(0)} is equivalent to \code{s.settimeout(0)};
-\code{s.setblocking(1)} is equivalent to \code{s.settimeout(None)}.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{settimeout}{value}
-Set a timeout on blocking socket operations. The \var{value} argument
-can be a nonnegative float expressing seconds, or \code{None}.
-If a float is
-given, subsequent socket operations will raise an \exception{timeout}
-exception if the timeout period \var{value} has elapsed before the
-operation has completed. Setting a timeout of \code{None} disables
-timeouts on socket operations.
-\code{s.settimeout(0.0)} is equivalent to \code{s.setblocking(0)};
-\code{s.settimeout(None)} is equivalent to \code{s.setblocking(1)}.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{gettimeout}{}
-Return the timeout in floating seconds associated with socket
-operations, or \code{None} if no timeout is set. This reflects
-the last call to \method{setblocking()} or \method{settimeout()}.
-\versionadded{2.3}
-\end{methoddesc}
-
-Some notes on socket blocking and timeouts: A socket object can be in
-one of three modes: blocking, non-blocking, or timeout. Sockets are
-always created in blocking mode. In blocking mode, operations block
-until complete. In non-blocking mode, operations fail (with an error
-that is unfortunately system-dependent) if they cannot be completed
-immediately. In timeout mode, operations fail if they cannot be
-completed within the timeout specified for the socket. The
-\method{setblocking()} method is simply a shorthand for certain
-\method{settimeout()} calls.
-
-Timeout mode internally sets the socket in non-blocking mode. The
-blocking and timeout modes are shared between file descriptors and
-socket objects that refer to the same network endpoint. A consequence
-of this is that file objects returned by the \method{makefile()}
-method must only be used when the socket is in blocking mode; in
-timeout or non-blocking mode file operations that cannot be completed
-immediately will fail.
-
-Note that the \method{connect()} operation is subject to the timeout
-setting, and in general it is recommended to call
-\method{settimeout()} before calling \method{connect()}.
-
-\begin{methoddesc}[socket]{setsockopt}{level, optname, value}
-Set the value of the given socket option (see the \UNIX{} manual page
-\manpage{setsockopt}{2}). The needed symbolic constants are defined in
-the \module{socket} module (\constant{SO_*} etc.). The value can be an
-integer or a string representing a buffer. In the latter case it is
-up to the caller to ensure that the string contains the proper bits
-(see the optional built-in module
-\refmodule{struct}\refbimodindex{struct} for a way to encode C
-structures as strings).
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{shutdown}{how}
-Shut down one or both halves of the connection. If \var{how} is
-\constant{SHUT_RD}, further receives are disallowed. If \var{how} is \constant{SHUT_WR},
-further sends are disallowed. If \var{how} is \constant{SHUT_RDWR}, further sends
-and receives are disallowed.
-\end{methoddesc}
-
-Note that there are no methods \method{read()} or \method{write()};
-use \method{recv()} and \method{send()} without \var{flags} argument
-instead.
-
-
-Socket objects also have these (read-only) attributes that correspond
-to the values given to the \class{socket} constructor.
-
-\begin{memberdesc}[socket]{family}
-The socket family.
-\versionadded{2.5}
-\end{memberdesc}
-
-\begin{memberdesc}[socket]{type}
-The socket type.
-\versionadded{2.5}
-\end{memberdesc}
-
-\begin{memberdesc}[socket]{proto}
-The socket protocol.
-\versionadded{2.5}
-\end{memberdesc}
-
-
-\subsection{SSL Objects \label{ssl-objects}}
-
-SSL objects have the following methods.
-
-\begin{methoddesc}[SSL]{write}{s}
-Writes the string \var{s} to the on the object's SSL connection.
-The return value is the number of bytes written.
-\end{methoddesc}
-
-\begin{methoddesc}[SSL]{read}{\optional{n}}
-If \var{n} is provided, read \var{n} bytes from the SSL connection, otherwise
-read until EOF. The return value is a string of the bytes read.
-\end{methoddesc}
-
-\begin{methoddesc}[SSL]{server}{}
-Returns a string describing the server's certificate.
-Useful for debugging purposes; do not parse the content of this string
-because its format can't be parsed unambiguously.
-\end{methoddesc}
-
-\begin{methoddesc}[SSL]{issuer}{}
-Returns a string describing the issuer of the server's certificate.
-Useful for debugging purposes; do not parse the content of this string
-because its format can't be parsed unambiguously.
-\end{methoddesc}
-
-\subsection{Example \label{socket-example}}
-
-Here are four minimal example programs using the TCP/IP protocol:\ a
-server that echoes all data that it receives back (servicing only one
-client), and a client using it. Note that a server must perform the
-sequence \function{socket()}, \method{bind()}, \method{listen()},
-\method{accept()} (possibly repeating the \method{accept()} to service
-more than one client), while a client only needs the sequence
-\function{socket()}, \method{connect()}. Also note that the server
-does not \method{send()}/\method{recv()} on the
-socket it is listening on but on the new socket returned by
-\method{accept()}.
-
-The first two examples support IPv4 only.
-
-\begin{verbatim}
-# Echo server program
-import socket
-
-HOST = '' # Symbolic name meaning the local host
-PORT = 50007 # Arbitrary non-privileged port
-s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-s.bind((HOST, PORT))
-s.listen(1)
-conn, addr = s.accept()
-print 'Connected by', addr
-while 1:
- data = conn.recv(1024)
- if not data: break
- conn.send(data)
-conn.close()
-\end{verbatim}
-
-\begin{verbatim}
-# Echo client program
-import socket
-
-HOST = 'daring.cwi.nl' # The remote host
-PORT = 50007 # The same port as used by the server
-s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-s.connect((HOST, PORT))
-s.send('Hello, world')
-data = s.recv(1024)
-s.close()
-print 'Received', repr(data)
-\end{verbatim}
-
-The next two examples are identical to the above two, but support both
-IPv4 and IPv6.
-The server side will listen to the first address family available
-(it should listen to both instead).
-On most of IPv6-ready systems, IPv6 will take precedence
-and the server may not accept IPv4 traffic.
-The client side will try to connect to the all addresses returned as a result
-of the name resolution, and sends traffic to the first one connected
-successfully.
-
-\begin{verbatim}
-# Echo server program
-import socket
-import sys
-
-HOST = '' # Symbolic name meaning the local host
-PORT = 50007 # Arbitrary non-privileged port
-s = None
-for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
- af, socktype, proto, canonname, sa = res
- try:
- s = socket.socket(af, socktype, proto)
- except socket.error as msg:
- s = None
- continue
- try:
- s.bind(sa)
- s.listen(1)
- except socket.error as msg:
- s.close()
- s = None
- continue
- break
-if s is None:
- print 'could not open socket'
- sys.exit(1)
-conn, addr = s.accept()
-print 'Connected by', addr
-while 1:
- data = conn.recv(1024)
- if not data: break
- conn.send(data)
-conn.close()
-\end{verbatim}
-
-\begin{verbatim}
-# Echo client program
-import socket
-import sys
-
-HOST = 'daring.cwi.nl' # The remote host
-PORT = 50007 # The same port as used by the server
-s = None
-for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
- af, socktype, proto, canonname, sa = res
- try:
- s = socket.socket(af, socktype, proto)
- except socket.error as msg:
- s = None
- continue
- try:
- s.connect(sa)
- except socket.error as msg:
- s.close()
- s = None
- continue
- break
-if s is None:
- print 'could not open socket'
- sys.exit(1)
-s.send('Hello, world')
-data = s.recv(1024)
-s.close()
-print 'Received', repr(data)
-\end{verbatim}
-
-This example connects to an SSL server, prints the
-server and issuer's distinguished names, sends some bytes,
-and reads part of the response:
-
-\begin{verbatim}
-import socket
-
-s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-s.connect(('www.verisign.com', 443))
-
-ssl_sock = socket.ssl(s)
-
-print repr(ssl_sock.server())
-print repr(ssl_sock.issuer())
-
-# Set a simple HTTP request -- use httplib in actual code.
-ssl_sock.write("""GET / HTTP/1.0\r
-Host: www.verisign.com\r\n\r\n""")
-
-# Read a chunk of data. Will not necessarily
-# read all the data returned by the server.
-data = ssl_sock.read()
-
-# Note that you need to close the underlying socket, not the SSL object.
-del ssl_sock
-s.close()
-\end{verbatim}
-
-At this writing, this SSL example prints the following output (line
-breaks inserted for readability):
-
-\begin{verbatim}
-'/C=US/ST=California/L=Mountain View/
- O=VeriSign, Inc./OU=Production Services/
- OU=Terms of use at www.verisign.com/rpa (c)00/
- CN=www.verisign.com'
-'/O=VeriSign Trust Network/OU=VeriSign, Inc./
- OU=VeriSign International Server CA - Class 3/
- OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign'
-\end{verbatim}
diff --git a/Doc/lib/libsocksvr.tex b/Doc/lib/libsocksvr.tex
deleted file mode 100644
index c7b28ea..0000000
--- a/Doc/lib/libsocksvr.tex
+++ /dev/null
@@ -1,293 +0,0 @@
-\section{\module{SocketServer} ---
- A framework for network servers}
-
-\declaremodule{standard}{SocketServer}
-\modulesynopsis{A framework for network servers.}
-
-
-The \module{SocketServer} module simplifies the task of writing network
-servers.
-
-There are four basic server classes: \class{TCPServer} uses the
-Internet TCP protocol, which provides for continuous streams of data
-between the client and server. \class{UDPServer} uses datagrams, which
-are discrete packets of information that may arrive out of order or be
-lost while in transit. The more infrequently used
-\class{UnixStreamServer} and \class{UnixDatagramServer} classes are
-similar, but use \UNIX{} domain sockets; they're not available on
-non-\UNIX{} platforms. For more details on network programming, consult
-a book such as W. Richard Steven's \citetitle{UNIX Network Programming}
-or Ralph Davis's \citetitle{Win32 Network Programming}.
-
-These four classes process requests \dfn{synchronously}; each request
-must be completed before the next request can be started. This isn't
-suitable if each request takes a long time to complete, because it
-requires a lot of computation, or because it returns a lot of data
-which the client is slow to process. The solution is to create a
-separate process or thread to handle each request; the
-\class{ForkingMixIn} and \class{ThreadingMixIn} mix-in classes can be
-used to support asynchronous behaviour.
-
-Creating a server requires several steps. First, you must create a
-request handler class by subclassing the \class{BaseRequestHandler}
-class and overriding its \method{handle()} method; this method will
-process incoming requests. Second, you must instantiate one of the
-server classes, passing it the server's address and the request
-handler class. Finally, call the \method{handle_request()} or
-\method{serve_forever()} method of the server object to process one or
-many requests.
-
-When inheriting from \class{ThreadingMixIn} for threaded connection
-behavior, you should explicitly declare how you want your threads
-to behave on an abrupt shutdown. The \class{ThreadingMixIn} class
-defines an attribute \var{daemon_threads}, which indicates whether
-or not the server should wait for thread termination. You should
-set the flag explicitly if you would like threads to behave
-autonomously; the default is \constant{False}, meaning that Python
-will not exit until all threads created by \class{ThreadingMixIn} have
-exited.
-
-Server classes have the same external methods and attributes, no
-matter what network protocol they use:
-
-\setindexsubitem{(SocketServer protocol)}
-
-\subsection{Server Creation Notes}
-
-There are five classes in an inheritance diagram, four of which represent
-synchronous servers of four types:
-
-\begin{verbatim}
- +------------+
- | BaseServer |
- +------------+
- |
- v
- +-----------+ +------------------+
- | TCPServer |------->| UnixStreamServer |
- +-----------+ +------------------+
- |
- v
- +-----------+ +--------------------+
- | UDPServer |------->| UnixDatagramServer |
- +-----------+ +--------------------+
-\end{verbatim}
-
-Note that \class{UnixDatagramServer} derives from \class{UDPServer}, not
-from \class{UnixStreamServer} --- the only difference between an IP and a
-\UNIX{} stream server is the address family, which is simply repeated in both
-\UNIX{} server classes.
-
-Forking and threading versions of each type of server can be created using
-the \class{ForkingMixIn} and \class{ThreadingMixIn} mix-in classes. For
-instance, a threading UDP server class is created as follows:
-
-\begin{verbatim}
- class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass
-\end{verbatim}
-
-The mix-in class must come first, since it overrides a method defined in
-\class{UDPServer}. Setting the various member variables also changes the
-behavior of the underlying server mechanism.
-
-To implement a service, you must derive a class from
-\class{BaseRequestHandler} and redefine its \method{handle()} method. You
-can then run various versions of the service by combining one of the server
-classes with your request handler class. The request handler class must be
-different for datagram or stream services. This can be hidden by using the
-handler subclasses \class{StreamRequestHandler} or \class{DatagramRequestHandler}.
-
-Of course, you still have to use your head! For instance, it makes no sense
-to use a forking server if the service contains state in memory that can be
-modified by different requests, since the modifications in the child process
-would never reach the initial state kept in the parent process and passed to
-each child. In this case, you can use a threading server, but you will
-probably have to use locks to protect the integrity of the shared data.
-
-On the other hand, if you are building an HTTP server where all data is
-stored externally (for instance, in the file system), a synchronous class
-will essentially render the service "deaf" while one request is being
-handled -- which may be for a very long time if a client is slow to receive
-all the data it has requested. Here a threading or forking server is
-appropriate.
-
-In some cases, it may be appropriate to process part of a request
-synchronously, but to finish processing in a forked child depending on the
-request data. This can be implemented by using a synchronous server and
-doing an explicit fork in the request handler class \method{handle()}
-method.
-
-Another approach to handling multiple simultaneous requests in an
-environment that supports neither threads nor \function{fork()} (or where
-these are too expensive or inappropriate for the service) is to maintain an
-explicit table of partially finished requests and to use \function{select()}
-to decide which request to work on next (or whether to handle a new incoming
-request). This is particularly important for stream services where each
-client can potentially be connected for a long time (if threads or
-subprocesses cannot be used).
-
-%XXX should data and methods be intermingled, or separate?
-% how should the distinction between class and instance variables be
-% drawn?
-
-\subsection{Server Objects}
-
-\begin{funcdesc}{fileno}{}
-Return an integer file descriptor for the socket on which the server
-is listening. This function is most commonly passed to
-\function{select.select()}, to allow monitoring multiple servers in the
-same process.
-\end{funcdesc}
-
-\begin{funcdesc}{handle_request}{}
-Process a single request. This function calls the following methods
-in order: \method{get_request()}, \method{verify_request()}, and
-\method{process_request()}. If the user-provided \method{handle()}
-method of the handler class raises an exception, the server's
-\method{handle_error()} method will be called.
-\end{funcdesc}
-
-\begin{funcdesc}{serve_forever}{}
-Handle an infinite number of requests. This simply calls
-\method{handle_request()} inside an infinite loop.
-\end{funcdesc}
-
-\begin{datadesc}{address_family}
-The family of protocols to which the server's socket belongs.
-\constant{socket.AF_INET} and \constant{socket.AF_UNIX} are two
-possible values.
-\end{datadesc}
-
-\begin{datadesc}{RequestHandlerClass}
-The user-provided request handler class; an instance of this class is
-created for each request.
-\end{datadesc}
-
-\begin{datadesc}{server_address}
-The address on which the server is listening. The format of addresses
-varies depending on the protocol family; see the documentation for the
-socket module for details. For Internet protocols, this is a tuple
-containing a string giving the address, and an integer port number:
-\code{('127.0.0.1', 80)}, for example.
-\end{datadesc}
-
-\begin{datadesc}{socket}
-The socket object on which the server will listen for incoming requests.
-\end{datadesc}
-
-% XXX should class variables be covered before instance variables, or
-% vice versa?
-
-The server classes support the following class variables:
-
-\begin{datadesc}{allow_reuse_address}
-Whether the server will allow the reuse of an address. This defaults
-to \constant{False}, and can be set in subclasses to change the policy.
-\end{datadesc}
-
-\begin{datadesc}{request_queue_size}
-The size of the request queue. If it takes a long time to process a
-single request, any requests that arrive while the server is busy are
-placed into a queue, up to \member{request_queue_size} requests. Once
-the queue is full, further requests from clients will get a
-``Connection denied'' error. The default value is usually 5, but this
-can be overridden by subclasses.
-\end{datadesc}
-
-\begin{datadesc}{socket_type}
-The type of socket used by the server; \constant{socket.SOCK_STREAM}
-and \constant{socket.SOCK_DGRAM} are two possible values.
-\end{datadesc}
-
-There are various server methods that can be overridden by subclasses
-of base server classes like \class{TCPServer}; these methods aren't
-useful to external users of the server object.
-
-% should the default implementations of these be documented, or should
-% it be assumed that the user will look at SocketServer.py?
-
-\begin{funcdesc}{finish_request}{}
-Actually processes the request by instantiating
-\member{RequestHandlerClass} and calling its \method{handle()} method.
-\end{funcdesc}
-
-\begin{funcdesc}{get_request}{}
-Must accept a request from the socket, and return a 2-tuple containing
-the \emph{new} socket object to be used to communicate with the
-client, and the client's address.
-\end{funcdesc}
-
-\begin{funcdesc}{handle_error}{request, client_address}
-This function is called if the \member{RequestHandlerClass}'s
-\method{handle()} method raises an exception. The default action is
-to print the traceback to standard output and continue handling
-further requests.
-\end{funcdesc}
-
-\begin{funcdesc}{process_request}{request, client_address}
-Calls \method{finish_request()} to create an instance of the
-\member{RequestHandlerClass}. If desired, this function can create a
-new process or thread to handle the request; the \class{ForkingMixIn}
-and \class{ThreadingMixIn} classes do this.
-\end{funcdesc}
-
-% Is there any point in documenting the following two functions?
-% What would the purpose of overriding them be: initializing server
-% instance variables, adding new network families?
-
-\begin{funcdesc}{server_activate}{}
-Called by the server's constructor to activate the server. The default
-behavior just \method{listen}s to the server's socket.
-May be overridden.
-\end{funcdesc}
-
-\begin{funcdesc}{server_bind}{}
-Called by the server's constructor to bind the socket to the desired
-address. May be overridden.
-\end{funcdesc}
-
-\begin{funcdesc}{verify_request}{request, client_address}
-Must return a Boolean value; if the value is \constant{True}, the request will be
-processed, and if it's \constant{False}, the request will be denied.
-This function can be overridden to implement access controls for a server.
-The default implementation always returns \constant{True}.
-\end{funcdesc}
-
-\subsection{RequestHandler Objects}
-
-The request handler class must define a new \method{handle()} method,
-and can override any of the following methods. A new instance is
-created for each request.
-
-\begin{funcdesc}{finish}{}
-Called after the \method{handle()} method to perform any clean-up
-actions required. The default implementation does nothing. If
-\method{setup()} or \method{handle()} raise an exception, this
-function will not be called.
-\end{funcdesc}
-
-\begin{funcdesc}{handle}{}
-This function must do all the work required to service a request.
-The default implementation does nothing.
-Several instance attributes are available to it; the request is
-available as \member{self.request}; the client address as
-\member{self.client_address}; and the server instance as
-\member{self.server}, in case it needs access to per-server
-information.
-
-The type of \member{self.request} is different for datagram or stream
-services. For stream services, \member{self.request} is a socket
-object; for datagram services, \member{self.request} is a string.
-However, this can be hidden by using the request handler subclasses
-\class{StreamRequestHandler} or \class{DatagramRequestHandler}, which
-override the \method{setup()} and \method{finish()} methods, and
-provide \member{self.rfile} and \member{self.wfile} attributes.
-\member{self.rfile} and \member{self.wfile} can be read or written,
-respectively, to get the request data or return data to the client.
-\end{funcdesc}
-
-\begin{funcdesc}{setup}{}
-Called before the \method{handle()} method to perform any
-initialization actions required. The default implementation does
-nothing.
-\end{funcdesc}
diff --git a/Doc/lib/libsomeos.tex b/Doc/lib/libsomeos.tex
deleted file mode 100644
index 680c590..0000000
--- a/Doc/lib/libsomeos.tex
+++ /dev/null
@@ -1,10 +0,0 @@
-\chapter{Optional Operating System Services}
-\label{someos}
-
-The modules described in this chapter provide interfaces to operating
-system features that are available on selected operating systems only.
-The interfaces are generally modeled after the \UNIX{} or \C{}
-interfaces but they are available on some other systems as well
-(e.g. Windows or NT). Here's an overview:
-
-\localmoduletable
diff --git a/Doc/lib/libspwd.tex b/Doc/lib/libspwd.tex
deleted file mode 100644
index 5f0e6f1..0000000
--- a/Doc/lib/libspwd.tex
+++ /dev/null
@@ -1,48 +0,0 @@
-\section{\module{spwd} ---
- The shadow password database}
-
-\declaremodule{builtin}{spwd}
- \platform{Unix}
-\modulesynopsis{The shadow password database (\function{getspnam()} and friends).}
-\versionadded{2.5}
-
-This module provides access to the \UNIX{} shadow password database.
-It is available on various \UNIX{} versions.
-
-You must have enough privileges to access the shadow password database
-(this usually means you have to be root).
-
-Shadow password database entries are reported as a tuple-like object, whose
-attributes correspond to the members of the \code{spwd} structure
-(Attribute field below, see \code{<shadow.h>}):
-
-\begin{tableiii}{r|l|l}{textrm}{Index}{Attribute}{Meaning}
- \lineiii{0}{\code{sp_nam}}{Login name}
- \lineiii{1}{\code{sp_pwd}}{Encrypted password}
- \lineiii{2}{\code{sp_lstchg}}{Date of last change}
- \lineiii{3}{\code{sp_min}}{Minimal number of days between changes}
- \lineiii{4}{\code{sp_max}}{Maximum number of days between changes}
- \lineiii{5}{\code{sp_warn}}{Number of days before password expires to warn user about it}
- \lineiii{6}{\code{sp_inact}}{Number of days after password expires until account is blocked}
- \lineiii{7}{\code{sp_expire}}{Number of days since 1970-01-01 until account is disabled}
- \lineiii{8}{\code{sp_flag}}{Reserved}
-\end{tableiii}
-
-The sp_nam and sp_pwd items are strings, all others are integers.
-\exception{KeyError} is raised if the entry asked for cannot be found.
-
-It defines the following items:
-
-\begin{funcdesc}{getspnam}{name}
-Return the shadow password database entry for the given user name.
-\end{funcdesc}
-
-\begin{funcdesc}{getspall}{}
-Return a list of all available shadow password database entries, in arbitrary order.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{grp}{An interface to the group database, similar to this.}
- \seemodule{pwd}{An interface to the normal password database, similar to this.}
-\end{seealso}
diff --git a/Doc/lib/libsqlite3.tex b/Doc/lib/libsqlite3.tex
deleted file mode 100644
index a7a0e94..0000000
--- a/Doc/lib/libsqlite3.tex
+++ /dev/null
@@ -1,648 +0,0 @@
-\section{\module{sqlite3} ---
- DB-API 2.0 interface for SQLite databases}
-
-\declaremodule{builtin}{sqlite3}
-\modulesynopsis{A DB-API 2.0 implementation using SQLite 3.x.}
-\sectionauthor{Gerhard Häring}{gh@ghaering.de}
-\versionadded{2.5}
-
-SQLite is a C library that provides a lightweight disk-based database
-that doesn't require a separate server process and allows accessing
-the database using a nonstandard variant of the SQL query language.
-Some applications can use SQLite for internal data storage. It's also
-possible to prototype an application using SQLite and then port the
-code to a larger database such as PostgreSQL or Oracle.
-
-pysqlite was written by Gerhard H\"aring and provides a SQL interface
-compliant with the DB-API 2.0 specification described by
-\pep{249}.
-
-To use the module, you must first create a \class{Connection} object
-that represents the database. Here the data will be stored in the
-\file{/tmp/example} file:
-
-\begin{verbatim}
-conn = sqlite3.connect('/tmp/example')
-\end{verbatim}
-
-You can also supply the special name \samp{:memory:} to create
-a database in RAM.
-
-Once you have a \class{Connection}, you can create a \class{Cursor}
-object and call its \method{execute()} method to perform SQL commands:
-
-\begin{verbatim}
-c = conn.cursor()
-
-# Create table
-c.execute('''create table stocks
-(date text, trans text, symbol text,
- qty real, price real)''')
-
-# Insert a row of data
-c.execute("""insert into stocks
- values ('2006-01-05','BUY','RHAT',100,35.14)""")
-
-# Save (commit) the changes
-conn.commit()
-
-# We can also close the cursor if we are done with it
-c.close()
-\end{verbatim}
-
-Usually your SQL operations will need to use values from Python
-variables. You shouldn't assemble your query using Python's string
-operations because doing so is insecure; it makes your program
-vulnerable to an SQL injection attack.
-
-Instead, use the DB-API's parameter substitution. Put \samp{?} as a
-placeholder wherever you want to use a value, and then provide a tuple
-of values as the second argument to the cursor's \method{execute()}
-method. (Other database modules may use a different placeholder,
-such as \samp{\%s} or \samp{:1}.) For example:
-
-\begin{verbatim}
-# Never do this -- insecure!
-symbol = 'IBM'
-c.execute("... where symbol = '%s'" % symbol)
-
-# Do this instead
-t = (symbol,)
-c.execute('select * from stocks where symbol=?', t)
-
-# Larger example
-for t in (('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
- ('2006-04-05', 'BUY', 'MSOFT', 1000, 72.00),
- ('2006-04-06', 'SELL', 'IBM', 500, 53.00),
- ):
- c.execute('insert into stocks values (?,?,?,?,?)', t)
-\end{verbatim}
-
-To retrieve data after executing a SELECT statement, you can either
-treat the cursor as an iterator, call the cursor's \method{fetchone()}
-method to retrieve a single matching row,
-or call \method{fetchall()} to get a list of the matching rows.
-
-This example uses the iterator form:
-
-\begin{verbatim}
->>> c = conn.cursor()
->>> c.execute('select * from stocks order by price')
->>> for row in c:
-... print row
-...
-(u'2006-01-05', u'BUY', u'RHAT', 100, 35.140000000000001)
-(u'2006-03-28', u'BUY', u'IBM', 1000, 45.0)
-(u'2006-04-06', u'SELL', u'IBM', 500, 53.0)
-(u'2006-04-05', u'BUY', u'MSOFT', 1000, 72.0)
->>>
-\end{verbatim}
-
-\begin{seealso}
-
-\seeurl{http://www.pysqlite.org}
-{The pysqlite web page.}
-
-\seeurl{http://www.sqlite.org}
-{The SQLite web page; the documentation describes the syntax and the
-available data types for the supported SQL dialect.}
-
-\seepep{249}{Database API Specification 2.0}{PEP written by
-Marc-Andr\'e Lemburg.}
-
-\end{seealso}
-
-
-\subsection{Module functions and constants\label{sqlite3-Module-Contents}}
-
-\begin{datadesc}{PARSE_DECLTYPES}
-This constant is meant to be used with the \var{detect_types} parameter of the
-\function{connect} function.
-
-Setting it makes the \module{sqlite3} module parse the declared type for each column it
-returns. It will parse out the first word of the declared type, i. e. for
-"integer primary key", it will parse out "integer". Then for that column, it
-will look into the converters dictionary and use the converter function
-registered for that type there. Converter names are case-sensitive!
-\end{datadesc}
-
-
-\begin{datadesc}{PARSE_COLNAMES}
-This constant is meant to be used with the \var{detect_types} parameter of the
-\function{connect} function.
-
-Setting this makes the SQLite interface parse the column name for each column
-it returns. It will look for a string formed [mytype] in there, and then
-decide that 'mytype' is the type of the column. It will try to find an entry of
-'mytype' in the converters dictionary and then use the converter function found
-there to return the value. The column name found in \member{cursor.description} is only
-the first word of the column name, i. e. if you use something like
-\code{'as "x [datetime]"'} in your SQL, then we will parse out everything until the
-first blank for the column name: the column name would simply be "x".
-\end{datadesc}
-
-\begin{funcdesc}{connect}{database\optional{, timeout, isolation_level, detect_types, factory}}
-Opens a connection to the SQLite database file \var{database}. You can use
-\code{":memory:"} to open a database connection to a database that resides in
-RAM instead of on disk.
-
-When a database is accessed by multiple connections, and one of the processes
-modifies the database, the SQLite database is locked until that transaction is
-committed. The \var{timeout} parameter specifies how long the connection should
-wait for the lock to go away until raising an exception. The default for the
-timeout parameter is 5.0 (five seconds).
-
-For the \var{isolation_level} parameter, please see the \member{isolation_level}
-property of \class{Connection} objects in section~\ref{sqlite3-Connection-IsolationLevel}.
-
-SQLite natively supports only the types TEXT, INTEGER, FLOAT, BLOB and NULL. If
-you want to use other types you must add support for them yourself.
-The \var{detect_types} parameter and the using custom \strong{converters} registered with
-the module-level \function{register_converter} function allow you to easily do that.
-
-\var{detect_types} defaults to 0 (i. e. off, no type detection), you can set it
-to any combination of \constant{PARSE_DECLTYPES} and \constant{PARSE_COLNAMES} to turn type
-detection on.
-
-By default, the \module{sqlite3} module uses its \class{Connection} class for the
-connect call. You can, however, subclass the \class{Connection} class and make
-\function{connect} use your class instead by providing your class for the
-\var{factory} parameter.
-
-Consult the section \ref{sqlite3-Types} of this manual for details.
-
-The \module{sqlite3} module internally uses a statement cache to avoid SQL parsing
-overhead. If you want to explicitly set the number of statements that are
-cached for the connection, you can set the \var{cached_statements} parameter.
-The currently implemented default is to cache 100 statements.
-\end{funcdesc}
-
-\begin{funcdesc}{register_converter}{typename, callable}
-Registers a callable to convert a bytestring from the database into a custom
-Python type. The callable will be invoked for all database values that are of
-the type \var{typename}. Confer the parameter \var{detect_types} of the
-\function{connect} function for how the type detection works. Note that the case of
-\var{typename} and the name of the type in your query must match!
-\end{funcdesc}
-
-\begin{funcdesc}{register_adapter}{type, callable}
-Registers a callable to convert the custom Python type \var{type} into one of
-SQLite's supported types. The callable \var{callable} accepts as single
-parameter the Python value, and must return a value of the following types:
-int, long, float, str (UTF-8 encoded), unicode or buffer.
-\end{funcdesc}
-
-\begin{funcdesc}{complete_statement}{sql}
-Returns \constant{True} if the string \var{sql} contains one or more complete SQL
-statements terminated by semicolons. It does not verify that the SQL is
-syntactically correct, only that there are no unclosed string literals and the
-statement is terminated by a semicolon.
-
-This can be used to build a shell for SQLite, as in the following example:
-
- \verbatiminput{sqlite3/complete_statement.py}
-\end{funcdesc}
-
-\begin{funcdesc}{enable_callback_tracebacks}{flag}
-By default you will not get any tracebacks in user-defined functions,
-aggregates, converters, authorizer callbacks etc. If you want to debug them,
-you can call this function with \var{flag} as True. Afterwards, you will get
-tracebacks from callbacks on \code{sys.stderr}. Use \constant{False} to disable
-the feature again.
-\end{funcdesc}
-
-\subsection{Connection Objects \label{sqlite3-Connection-Objects}}
-
-A \class{Connection} instance has the following attributes and methods:
-
-\label{sqlite3-Connection-IsolationLevel}
-\begin{memberdesc}[Connection]{isolation_level}
- Get or set the current isolation level. None for autocommit mode or one of
- "DEFERRED", "IMMEDIATE" or "EXLUSIVE". See ``Controlling Transactions'',
- section~\ref{sqlite3-Controlling-Transactions}, for a more detailed explanation.
-\end{memberdesc}
-
-\begin{methoddesc}[Connection]{cursor}{\optional{cursorClass}}
- The cursor method accepts a single optional parameter \var{cursorClass}.
- If supplied, this must be a custom cursor class that extends
- \class{sqlite3.Cursor}.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{execute}{sql, \optional{parameters}}
-This is a nonstandard shortcut that creates an intermediate cursor object by
-calling the cursor method, then calls the cursor's \method{execute} method with the
-parameters given.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{executemany}{sql, \optional{parameters}}
-This is a nonstandard shortcut that creates an intermediate cursor object by
-calling the cursor method, then calls the cursor's \method{executemany} method with the
-parameters given.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{executescript}{sql_script}
-This is a nonstandard shortcut that creates an intermediate cursor object by
-calling the cursor method, then calls the cursor's \method{executescript} method with the
-parameters given.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{create_function}{name, num_params, func}
-
-Creates a user-defined function that you can later use from within SQL
-statements under the function name \var{name}. \var{num_params} is the number
-of parameters the function accepts, and \var{func} is a Python callable that is
-called as the SQL function.
-
-The function can return any of the types supported by SQLite: unicode, str,
-int, long, float, buffer and None.
-
-Example:
-
- \verbatiminput{sqlite3/md5func.py}
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{create_aggregate}{name, num_params, aggregate_class}
-
-Creates a user-defined aggregate function.
-
-The aggregate class must implement a \code{step} method, which accepts the
-number of parameters \var{num_params}, and a \code{finalize} method which
-will return the final result of the aggregate.
-
-The \code{finalize} method can return any of the types supported by SQLite:
-unicode, str, int, long, float, buffer and None.
-
-Example:
-
- \verbatiminput{sqlite3/mysumaggr.py}
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{create_collation}{name, callable}
-
-Creates a collation with the specified \var{name} and \var{callable}. The
-callable will be passed two string arguments. It should return -1 if the first
-is ordered lower than the second, 0 if they are ordered equal and 1 if the
-first is ordered higher than the second. Note that this controls sorting
-(ORDER BY in SQL) so your comparisons don't affect other SQL operations.
-
-Note that the callable will get its parameters as Python bytestrings, which
-will normally be encoded in UTF-8.
-
-The following example shows a custom collation that sorts "the wrong way":
-
- \verbatiminput{sqlite3/collation_reverse.py}
-
-To remove a collation, call \code{create_collation} with None as callable:
-
-\begin{verbatim}
- con.create_collation("reverse", None)
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{interrupt}{}
-
-You can call this method from a different thread to abort any queries that
-might be executing on the connection. The query will then abort and the caller
-will get an exception.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{set_authorizer}{authorizer_callback}
-
-This routine registers a callback. The callback is invoked for each attempt to
-access a column of a table in the database. The callback should return
-\constant{SQLITE_OK} if access is allowed, \constant{SQLITE_DENY} if the entire
-SQL statement should be aborted with an error and \constant{SQLITE_IGNORE} if
-the column should be treated as a NULL value. These constants are available in
-the \module{sqlite3} module.
-
-The first argument to the callback signifies what kind of operation is to be
-authorized. The second and third argument will be arguments or \constant{None}
-depending on the first argument. The 4th argument is the name of the database
-("main", "temp", etc.) if applicable. The 5th argument is the name of the
-inner-most trigger or view that is responsible for the access attempt or
-\constant{None} if this access attempt is directly from input SQL code.
-
-Please consult the SQLite documentation about the possible values for the first
-argument and the meaning of the second and third argument depending on the
-first one. All necessary constants are available in the \module{sqlite3}
-module.
-\end{methoddesc}
-
-\begin{memberdesc}[Connection]{row_factory}
- You can change this attribute to a callable that accepts the cursor and
- the original row as a tuple and will return the real result row. This
- way, you can implement more advanced ways of returning results, such
- as returning an object that can also access columns by name.
-
- Example:
-
- \verbatiminput{sqlite3/row_factory.py}
-
- If returning a tuple doesn't suffice and you want name-based
- access to columns, you should consider setting \member{row_factory} to the
- highly-optimized \class{sqlite3.Row} type. \class{Row} provides both
- index-based and case-insensitive name-based access to columns with almost
- no memory overhead. It will probably be better than your own custom
- dictionary-based approach or even a db_row based solution.
- % XXX what's a db_row-based solution?
-\end{memberdesc}
-
-\begin{memberdesc}[Connection]{text_factory}
- Using this attribute you can control what objects are returned for the
- TEXT data type. By default, this attribute is set to \class{unicode} and
- the \module{sqlite3} module will return Unicode objects for TEXT. If you want to return
- bytestrings instead, you can set it to \class{str}.
-
- For efficiency reasons, there's also a way to return Unicode objects only
- for non-ASCII data, and bytestrings otherwise. To activate it, set this
- attribute to \constant{sqlite3.OptimizedUnicode}.
-
- You can also set it to any other callable that accepts a single bytestring
- parameter and returns the resulting object.
-
- See the following example code for illustration:
-
- \verbatiminput{sqlite3/text_factory.py}
-\end{memberdesc}
-
-\begin{memberdesc}[Connection]{total_changes}
- Returns the total number of database rows that have been modified, inserted,
- or deleted since the database connection was opened.
-\end{memberdesc}
-
-
-
-
-
-\subsection{Cursor Objects \label{sqlite3-Cursor-Objects}}
-
-A \class{Cursor} instance has the following attributes and methods:
-
-\begin{methoddesc}[Cursor]{execute}{sql, \optional{parameters}}
-
-Executes a SQL statement. The SQL statement may be parametrized (i. e.
-placeholders instead of SQL literals). The \module{sqlite3} module supports two kinds of
-placeholders: question marks (qmark style) and named placeholders (named
-style).
-
-This example shows how to use parameters with qmark style:
-
- \verbatiminput{sqlite3/execute_1.py}
-
-This example shows how to use the named style:
-
- \verbatiminput{sqlite3/execute_2.py}
-
- \method{execute()} will only execute a single SQL statement. If you try to
- execute more than one statement with it, it will raise a Warning. Use
- \method{executescript()} if you want to execute multiple SQL statements with one
- call.
-\end{methoddesc}
-
-
-\begin{methoddesc}[Cursor]{executemany}{sql, seq_of_parameters}
-Executes a SQL command against all parameter sequences or mappings found in the
-sequence \var{sql}. The \module{sqlite3} module also allows
-using an iterator yielding parameters instead of a sequence.
-
-\verbatiminput{sqlite3/executemany_1.py}
-
-Here's a shorter example using a generator:
-
-\verbatiminput{sqlite3/executemany_2.py}
-\end{methoddesc}
-
-\begin{methoddesc}[Cursor]{executescript}{sql_script}
-
-This is a nonstandard convenience method for executing multiple SQL statements
-at once. It issues a COMMIT statement first, then executes the SQL script it
-gets as a parameter.
-
-\var{sql_script} can be a bytestring or a Unicode string.
-
-Example:
-
-\verbatiminput{sqlite3/executescript.py}
-\end{methoddesc}
-
-\begin{memberdesc}[Cursor]{rowcount}
- Although the \class{Cursor} class of the \module{sqlite3} module implements this
- attribute, the database engine's own support for the determination of "rows
- affected"/"rows selected" is quirky.
-
- For \code{SELECT} statements, \member{rowcount} is always None because we cannot
- determine the number of rows a query produced until all rows were fetched.
-
- For \code{DELETE} statements, SQLite reports \member{rowcount} as 0 if you make a
- \code{DELETE FROM table} without any condition.
-
- For \method{executemany} statements, the number of modifications are summed
- up into \member{rowcount}.
-
- As required by the Python DB API Spec, the \member{rowcount} attribute "is -1
- in case no executeXX() has been performed on the cursor or the rowcount
- of the last operation is not determinable by the interface".
-\end{memberdesc}
-
-\subsection{SQLite and Python types\label{sqlite3-Types}}
-
-\subsubsection{Introduction}
-
-SQLite natively supports the following types: NULL, INTEGER, REAL, TEXT, BLOB.
-
-The following Python types can thus be sent to SQLite without any problem:
-
-\begin{tableii} {c|l}{code}{Python type}{SQLite type}
-\lineii{None}{NULL}
-\lineii{int}{INTEGER}
-\lineii{long}{INTEGER}
-\lineii{float}{REAL}
-\lineii{str (UTF8-encoded)}{TEXT}
-\lineii{unicode}{TEXT}
-\lineii{buffer}{BLOB}
-\end{tableii}
-
-This is how SQLite types are converted to Python types by default:
-
-\begin{tableii} {c|l}{code}{SQLite type}{Python type}
-\lineii{NULL}{None}
-\lineii{INTEGER}{int or long, depending on size}
-\lineii{REAL}{float}
-\lineii{TEXT}{depends on text_factory, unicode by default}
-\lineii{BLOB}{buffer}
-\end{tableii}
-
-The type system of the \module{sqlite3} module is extensible in two ways: you can store
-additional Python types in a SQLite database via object adaptation, and you can
-let the \module{sqlite3} module convert SQLite types to different Python types via
-converters.
-
-\subsubsection{Using adapters to store additional Python types in SQLite databases}
-
-As described before, SQLite supports only a limited set of types natively. To
-use other Python types with SQLite, you must \strong{adapt} them to one of the sqlite3
-module's supported types for SQLite: one of NoneType, int, long, float,
-str, unicode, buffer.
-
-The \module{sqlite3} module uses Python object adaptation, as described in \pep{246} for this. The protocol to use is \class{PrepareProtocol}.
-
-There are two ways to enable the \module{sqlite3} module to adapt a custom Python type
-to one of the supported ones.
-
-\paragraph{Letting your object adapt itself}
-
-This is a good approach if you write the class yourself. Let's suppose you have
-a class like this:
-
-\begin{verbatim}
-class Point(object):
- def __init__(self, x, y):
- self.x, self.y = x, y
-\end{verbatim}
-
-Now you want to store the point in a single SQLite column. First you'll have to
-choose one of the supported types first to be used for representing the point.
-Let's just use str and separate the coordinates using a semicolon. Then you
-need to give your class a method \code{__conform__(self, protocol)} which must
-return the converted value. The parameter \var{protocol} will be
-\class{PrepareProtocol}.
-
-\verbatiminput{sqlite3/adapter_point_1.py}
-
-\paragraph{Registering an adapter callable}
-
-The other possibility is to create a function that converts the type to the
-string representation and register the function with \method{register_adapter}.
-
-\begin{notice}
-The type/class to adapt must be a new-style class, i. e. it must have
-\class{object} as one of its bases.
-\end{notice}
-
- \verbatiminput{sqlite3/adapter_point_2.py}
-
-The \module{sqlite3} module has two default adapters for Python's built-in
-\class{datetime.date} and \class{datetime.datetime} types. Now let's suppose
-we want to store \class{datetime.datetime} objects not in ISO representation,
-but as a \UNIX{} timestamp.
-
- \verbatiminput{sqlite3/adapter_datetime.py}
-
-\subsubsection{Converting SQLite values to custom Python types}
-
-Writing an adapter lets you send custom Python types to SQLite.
-But to make it really useful we need to make the Python to SQLite to Python
-roundtrip work.
-
-Enter converters.
-
-Let's go back to the \class{Point} class. We stored the x and y
-coordinates separated via semicolons as strings in SQLite.
-
-First, we'll define a converter function that accepts the string as a
-parameter and constructs a \class{Point} object from it.
-
-\begin{notice}
-Converter functions \strong{always} get called with a string, no matter
-under which data type you sent the value to SQLite.
-\end{notice}
-
-\begin{notice}
-Converter names are looked up in a case-sensitive manner.
-\end{notice}
-
-
-\begin{verbatim}
- def convert_point(s):
- x, y = map(float, s.split(";"))
- return Point(x, y)
-\end{verbatim}
-
-Now you need to make the \module{sqlite3} module know that what you select from the
-database is actually a point. There are two ways of doing this:
-
-\begin{itemize}
- \item Implicitly via the declared type
- \item Explicitly via the column name
-\end{itemize}
-
-Both ways are described in ``Module Constants'', section~\ref{sqlite3-Module-Contents}, in
-the entries for the constants \constant{PARSE_DECLTYPES} and
-\constant{PARSE_COLNAMES}.
-
-
-The following example illustrates both approaches.
-
- \verbatiminput{sqlite3/converter_point.py}
-
-\subsubsection{Default adapters and converters}
-
-There are default adapters for the date and datetime types in the datetime
-module. They will be sent as ISO dates/ISO timestamps to SQLite.
-
-The default converters are registered under the name "date" for \class{datetime.date}
-and under the name "timestamp" for \class{datetime.datetime}.
-
-This way, you can use date/timestamps from Python without any additional
-fiddling in most cases. The format of the adapters is also compatible with the
-experimental SQLite date/time functions.
-
-The following example demonstrates this.
-
- \verbatiminput{sqlite3/pysqlite_datetime.py}
-
-\subsection{Controlling Transactions \label{sqlite3-Controlling-Transactions}}
-
-By default, the \module{sqlite3} module opens transactions implicitly before a Data Modification Language (DML)
-statement (i.e. INSERT/UPDATE/DELETE/REPLACE), and commits transactions implicitly
-before a non-DML, non-query statement (i. e. anything other than
-SELECT/INSERT/UPDATE/DELETE/REPLACE).
-
-So if you are within a transaction and issue a command like \code{CREATE TABLE
-...}, \code{VACUUM}, \code{PRAGMA}, the \module{sqlite3} module will commit implicitly
-before executing that command. There are two reasons for doing that. The first
-is that some of these commands don't work within transactions. The other reason
-is that pysqlite needs to keep track of the transaction state (if a transaction
-is active or not).
-
-You can control which kind of "BEGIN" statements pysqlite implicitly executes
-(or none at all) via the \var{isolation_level} parameter to the
-\function{connect} call, or via the \member{isolation_level} property of
-connections.
-
-If you want \strong{autocommit mode}, then set \member{isolation_level} to None.
-
-Otherwise leave it at its default, which will result in a plain "BEGIN"
-statement, or set it to one of SQLite's supported isolation levels: DEFERRED,
-IMMEDIATE or EXCLUSIVE.
-
-As the \module{sqlite3} module needs to keep track of the transaction state, you should
-not use \code{OR ROLLBACK} or \code{ON CONFLICT ROLLBACK} in your SQL. Instead,
-catch the \exception{IntegrityError} and call the \method{rollback} method of
-the connection yourself.
-
-\subsection{Using pysqlite efficiently}
-
-\subsubsection{Using shortcut methods}
-
-Using the nonstandard \method{execute}, \method{executemany} and
-\method{executescript} methods of the \class{Connection} object, your code can
-be written more concisely because you don't have to create the (often
-superfluous) \class{Cursor} objects explicitly. Instead, the \class{Cursor}
-objects are created implicitly and these shortcut methods return the cursor
-objects. This way, you can execute a SELECT statement and iterate
-over it directly using only a single call on the \class{Connection} object.
-
- \verbatiminput{sqlite3/shortcut_methods.py}
-
-\subsubsection{Accessing columns by name instead of by index}
-
-One useful feature of the \module{sqlite3} module is the builtin \class{sqlite3.Row} class
-designed to be used as a row factory.
-
-Rows wrapped with this class can be accessed both by index (like tuples) and
-case-insensitively by name:
-
- \verbatiminput{sqlite3/rowclass.py}
-
-
diff --git a/Doc/lib/libstat.tex b/Doc/lib/libstat.tex
deleted file mode 100644
index d5353f1..0000000
--- a/Doc/lib/libstat.tex
+++ /dev/null
@@ -1,157 +0,0 @@
-\section{\module{stat} ---
- Interpreting \function{stat()} results}
-
-\declaremodule{standard}{stat}
-\modulesynopsis{Utilities for interpreting the results of
- \function{os.stat()}, \function{os.lstat()} and \function{os.fstat()}.}
-\sectionauthor{Skip Montanaro}{skip@automatrix.com}
-
-
-The \module{stat} module defines constants and functions for
-interpreting the results of \function{os.stat()},
-\function{os.fstat()} and \function{os.lstat()} (if they exist). For
-complete details about the \cfunction{stat()}, \cfunction{fstat()} and
-\cfunction{lstat()} calls, consult the documentation for your system.
-
-The \module{stat} module defines the following functions to test for
-specific file types:
-
-
-\begin{funcdesc}{S_ISDIR}{mode}
-Return non-zero if the mode is from a directory.
-\end{funcdesc}
-
-\begin{funcdesc}{S_ISCHR}{mode}
-Return non-zero if the mode is from a character special device file.
-\end{funcdesc}
-
-\begin{funcdesc}{S_ISBLK}{mode}
-Return non-zero if the mode is from a block special device file.
-\end{funcdesc}
-
-\begin{funcdesc}{S_ISREG}{mode}
-Return non-zero if the mode is from a regular file.
-\end{funcdesc}
-
-\begin{funcdesc}{S_ISFIFO}{mode}
-Return non-zero if the mode is from a FIFO (named pipe).
-\end{funcdesc}
-
-\begin{funcdesc}{S_ISLNK}{mode}
-Return non-zero if the mode is from a symbolic link.
-\end{funcdesc}
-
-\begin{funcdesc}{S_ISSOCK}{mode}
-Return non-zero if the mode is from a socket.
-\end{funcdesc}
-
-Two additional functions are defined for more general manipulation of
-the file's mode:
-
-\begin{funcdesc}{S_IMODE}{mode}
-Return the portion of the file's mode that can be set by
-\function{os.chmod()}---that is, the file's permission bits, plus the
-sticky bit, set-group-id, and set-user-id bits (on systems that support
-them).
-\end{funcdesc}
-
-\begin{funcdesc}{S_IFMT}{mode}
-Return the portion of the file's mode that describes the file type (used
-by the \function{S_IS*()} functions above).
-\end{funcdesc}
-
-Normally, you would use the \function{os.path.is*()} functions for
-testing the type of a file; the functions here are useful when you are
-doing multiple tests of the same file and wish to avoid the overhead of
-the \cfunction{stat()} system call for each test. These are also
-useful when checking for information about a file that isn't handled
-by \refmodule{os.path}, like the tests for block and character
-devices.
-
-All the variables below are simply symbolic indexes into the 10-tuple
-returned by \function{os.stat()}, \function{os.fstat()} or
-\function{os.lstat()}.
-
-\begin{datadesc}{ST_MODE}
-Inode protection mode.
-\end{datadesc}
-
-\begin{datadesc}{ST_INO}
-Inode number.
-\end{datadesc}
-
-\begin{datadesc}{ST_DEV}
-Device inode resides on.
-\end{datadesc}
-
-\begin{datadesc}{ST_NLINK}
-Number of links to the inode.
-\end{datadesc}
-
-\begin{datadesc}{ST_UID}
-User id of the owner.
-\end{datadesc}
-
-\begin{datadesc}{ST_GID}
-Group id of the owner.
-\end{datadesc}
-
-\begin{datadesc}{ST_SIZE}
-Size in bytes of a plain file; amount of data waiting on some special
-files.
-\end{datadesc}
-
-\begin{datadesc}{ST_ATIME}
-Time of last access.
-\end{datadesc}
-
-\begin{datadesc}{ST_MTIME}
-Time of last modification.
-\end{datadesc}
-
-\begin{datadesc}{ST_CTIME}
-The ``ctime'' as reported by the operating system. On some systems
-(like \UNIX) is the time of the last metadata change, and, on others
-(like Windows), is the creation time (see platform documentation for
-details).
-\end{datadesc}
-
-The interpretation of ``file size'' changes according to the file
-type. For plain files this is the size of the file in bytes. For
-FIFOs and sockets under most flavors of \UNIX{} (including Linux in
-particular), the ``size'' is the number of bytes waiting to be read at
-the time of the call to \function{os.stat()}, \function{os.fstat()},
-or \function{os.lstat()}; this can sometimes be useful, especially for
-polling one of these special files after a non-blocking open. The
-meaning of the size field for other character and block devices varies
-more, depending on the implementation of the underlying system call.
-
-Example:
-
-\begin{verbatim}
-import os, sys
-from stat import *
-
-def walktree(top, callback):
- '''recursively descend the directory tree rooted at top,
- calling the callback function for each regular file'''
-
- for f in os.listdir(top):
- pathname = os.path.join(top, f)
- mode = os.stat(pathname)[ST_MODE]
- if S_ISDIR(mode):
- # It's a directory, recurse into it
- walktree(pathname, callback)
- elif S_ISREG(mode):
- # It's a file, call the callback function
- callback(pathname)
- else:
- # Unknown file type, print a message
- print 'Skipping %s' % pathname
-
-def visitfile(file):
- print 'visiting', file
-
-if __name__ == '__main__':
- walktree(sys.argv[1], visitfile)
-\end{verbatim}
diff --git a/Doc/lib/libstatvfs.tex b/Doc/lib/libstatvfs.tex
deleted file mode 100644
index 2dc8933..0000000
--- a/Doc/lib/libstatvfs.tex
+++ /dev/null
@@ -1,55 +0,0 @@
-\section{\module{statvfs} ---
- Constants used with \function{os.statvfs()}}
-
-\declaremodule{standard}{statvfs}
-% LaTeX'ed from comments in module
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Constants for interpreting the result of
- \function{os.statvfs()}.}
-
-The \module{statvfs} module defines constants so interpreting the result
-if \function{os.statvfs()}, which returns a tuple, can be made without
-remembering ``magic numbers.'' Each of the constants defined in this
-module is the \emph{index} of the entry in the tuple returned by
-\function{os.statvfs()} that contains the specified information.
-
-
-\begin{datadesc}{F_BSIZE}
-Preferred file system block size.
-\end{datadesc}
-
-\begin{datadesc}{F_FRSIZE}
-Fundamental file system block size.
-\end{datadesc}
-
-\begin{datadesc}{F_BLOCKS}
-Total number of blocks in the filesystem.
-\end{datadesc}
-
-\begin{datadesc}{F_BFREE}
-Total number of free blocks.
-\end{datadesc}
-
-\begin{datadesc}{F_BAVAIL}
-Free blocks available to non-super user.
-\end{datadesc}
-
-\begin{datadesc}{F_FILES}
-Total number of file nodes.
-\end{datadesc}
-
-\begin{datadesc}{F_FFREE}
-Total number of free file nodes.
-\end{datadesc}
-
-\begin{datadesc}{F_FAVAIL}
-Free nodes available to non-super user.
-\end{datadesc}
-
-\begin{datadesc}{F_FLAG}
-Flags. System dependent: see \cfunction{statvfs()} man page.
-\end{datadesc}
-
-\begin{datadesc}{F_NAMEMAX}
-Maximum file name length.
-\end{datadesc}
diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
deleted file mode 100644
index 95033f9..0000000
--- a/Doc/lib/libstdtypes.tex
+++ /dev/null
@@ -1,2070 +0,0 @@
-\chapter{Built-in Types \label{types}}
-
-The following sections describe the standard types that are built into
-the interpreter.
-\note{Historically (until release 2.2), Python's built-in types have
-differed from user-defined types because it was not possible to use
-the built-in types as the basis for object-oriented inheritance.
-This limitation does not exist any longer.}
-
-The principal built-in types are numerics, sequences, mappings, files,
-classes, instances and exceptions.
-\indexii{built-in}{types}
-
-Some operations are supported by several object types; in particular,
-practically all objects can be compared, tested for truth value,
-and converted to a string (with
-the \function{repr()} function or the slightly different
-\function{str()} function). The latter
-function is implicitly used when an object is written by the
-\keyword{print}\stindex{print} statement.
-(Information on the \ulink{\keyword{print} statement}{../ref/print.html}
-and other language statements can be found in the
-\citetitle[../ref/ref.html]{Python Reference Manual} and the
-\citetitle[../tut/tut.html]{Python Tutorial}.)
-
-
-\section{Truth Value Testing\label{truth}}
-
-Any object can be tested for truth value, for use in an \keyword{if} or
-\keyword{while} condition or as operand of the Boolean operations below.
-The following values are considered false:
-\stindex{if}
-\stindex{while}
-\indexii{truth}{value}
-\indexii{Boolean}{operations}
-\index{false}
-
-\begin{itemize}
-
-\item \code{None}
- \withsubitem{(Built-in object)}{\ttindex{None}}
-
-\item \code{False}
- \withsubitem{(Built-in object)}{\ttindex{False}}
-
-\item zero of any numeric type, for example, \code{0}, \code{0L},
- \code{0.0}, \code{0j}.
-
-\item any empty sequence, for example, \code{''}, \code{()}, \code{[]}.
-
-\item any empty mapping, for example, \code{\{\}}.
-
-\item instances of user-defined classes, if the class defines a
- \method{__bool__()} or \method{__len__()} method, when that
- method returns the integer zero or \class{bool} value
- \code{False}.\footnote{Additional
-information on these special methods may be found in the
-\citetitle[../ref/ref.html]{Python Reference Manual}.}
-
-\end{itemize}
-
-All other values are considered true --- so objects of many types are
-always true.
-\index{true}
-
-Operations and built-in functions that have a Boolean result always
-return \code{0} or \code{False} for false and \code{1} or \code{True}
-for true, unless otherwise stated. (Important exception: the Boolean
-operations \samp{or}\opindex{or} and \samp{and}\opindex{and} always
-return one of their operands.)
-\index{False}
-\index{True}
-
-\section{Boolean Operations ---
- \keyword{and}, \keyword{or}, \keyword{not}
- \label{boolean}}
-
-These are the Boolean operations, ordered by ascending priority:
-\indexii{Boolean}{operations}
-
-\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
- \lineiii{\var{x} or \var{y}}
- {if \var{x} is false, then \var{y}, else \var{x}}{(1)}
- \lineiii{\var{x} and \var{y}}
- {if \var{x} is false, then \var{x}, else \var{y}}{(1)}
- \hline
- \lineiii{not \var{x}}
- {if \var{x} is false, then \code{True}, else \code{False}}{(2)}
-\end{tableiii}
-\opindex{and}
-\opindex{or}
-\opindex{not}
-
-\noindent
-Notes:
-
-\begin{description}
-
-\item[(1)]
-These only evaluate their second argument if needed for their outcome.
-
-\item[(2)]
-\samp{not} has a lower priority than non-Boolean operators, so
-\code{not \var{a} == \var{b}} is interpreted as \code{not (\var{a} ==
-\var{b})}, and \code{\var{a} == not \var{b}} is a syntax error.
-
-\end{description}
-
-
-\section{Comparisons \label{comparisons}}
-
-Comparison operations are supported by all objects. They all have the
-same priority (which is higher than that of the Boolean operations).
-Comparisons can be chained arbitrarily; for example, \code{\var{x} <
-\var{y} <= \var{z}} is equivalent to \code{\var{x} < \var{y} and
-\var{y} <= \var{z}}, except that \var{y} is evaluated only once (but
-in both cases \var{z} is not evaluated at all when \code{\var{x} <
-\var{y}} is found to be false).
-\indexii{chaining}{comparisons}
-
-This table summarizes the comparison operations:
-
-\begin{tableiii}{c|l|c}{code}{Operation}{Meaning}{Notes}
- \lineiii{<}{strictly less than}{}
- \lineiii{<=}{less than or equal}{}
- \lineiii{>}{strictly greater than}{}
- \lineiii{>=}{greater than or equal}{}
- \lineiii{==}{equal}{}
- \lineiii{!=}{not equal}{}
- \lineiii{is}{object identity}{}
- \lineiii{is not}{negated object identity}{}
-\end{tableiii}
-\indexii{operator}{comparison}
-\opindex{==} % XXX *All* others have funny characters < ! >
-\opindex{is}
-\opindex{is not}
-
-Objects of different types, except different numeric types and different string types, never
-compare equal; such objects are ordered consistently but arbitrarily
-(so that sorting a heterogeneous array yields a consistent result).
-Furthermore, some types (for example, file objects) support only a
-degenerate notion of comparison where any two objects of that type are
-unequal. Again, such objects are ordered arbitrarily but
-consistently. The \code{<}, \code{<=}, \code{>} and \code{>=}
-operators will raise a \exception{TypeError} exception when any operand
-is a complex number.
-\indexii{object}{numeric}
-\indexii{objects}{comparing}
-
-Instances of a class normally compare as non-equal unless the class
-\withsubitem{(instance method)}{\ttindex{__cmp__()}}
-defines the \method{__cmp__()} method. Refer to the
-\citetitle[../ref/customization.html]{Python Reference Manual} for
-information on the use of this method to effect object comparisons.
-
-\strong{Implementation note:} Objects of different types except
-numbers are ordered by their type names; objects of the same types
-that don't support proper comparison are ordered by their address.
-
-Two more operations with the same syntactic priority,
-\samp{in}\opindex{in} and \samp{not in}\opindex{not in}, are supported
-only by sequence types (below).
-
-
-\section{Numeric Types ---
- \class{int}, \class{float}, \class{long}, \class{complex}
- \label{typesnumeric}}
-
-There are four distinct numeric types: \dfn{plain integers},
-\dfn{long integers},
-\dfn{floating point numbers}, and \dfn{complex numbers}.
-In addition, Booleans are a subtype of plain integers.
-Plain integers (also just called \dfn{integers})
-are implemented using \ctype{long} in C, which gives them at least 32
-bits of precision (\code{sys.maxint} is always set to the maximum
-plain integer value for the current platform, the minimum value is
-\code{-sys.maxint - 1}). Long integers have unlimited precision.
-Floating point numbers are implemented using \ctype{double} in C.
-All bets on their precision are off unless you happen to know the
-machine you are working with.
-\obindex{numeric}
-\obindex{Boolean}
-\obindex{integer}
-\obindex{long integer}
-\obindex{floating point}
-\obindex{complex number}
-\indexii{C}{language}
-
-Complex numbers have a real and imaginary part, which are each
-implemented using \ctype{double} in C. To extract these parts from
-a complex number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}.
-
-Numbers are created by numeric literals or as the result of built-in
-functions and operators. Unadorned integer literals (including hex
-and octal numbers) yield plain integers unless the value they denote
-is too large to be represented as a plain integer, in which case
-they yield a long integer. Integer literals with an
-\character{L} or \character{l} suffix yield long integers
-(\character{L} is preferred because \samp{1l} looks too much like
-eleven!). Numeric literals containing a decimal point or an exponent
-sign yield floating point numbers. Appending \character{j} or
-\character{J} to a numeric literal yields a complex number with a
-zero real part. A complex numeric literal is the sum of a real and
-an imaginary part.
-\indexii{numeric}{literals}
-\indexii{integer}{literals}
-\indexiii{long}{integer}{literals}
-\indexii{floating point}{literals}
-\indexii{complex number}{literals}
-\indexii{hexadecimal}{literals}
-\indexii{octal}{literals}
-
-Python fully supports mixed arithmetic: when a binary arithmetic
-operator has operands of different numeric types, the operand with the
-``narrower'' type is widened to that of the other, where plain
-integer is narrower than long integer is narrower than floating point is
-narrower than complex.
-Comparisons between numbers of mixed type use the same rule.\footnote{
- As a consequence, the list \code{[1, 2]} is considered equal
- to \code{[1.0, 2.0]}, and similarly for tuples.
-} The constructors \function{int()}, \function{long()}, \function{float()},
-and \function{complex()} can be used
-to produce numbers of a specific type.
-\index{arithmetic}
-\bifuncindex{int}
-\bifuncindex{long}
-\bifuncindex{float}
-\bifuncindex{complex}
-
-All numeric types (except complex) support the following operations,
-sorted by ascending priority (operations in the same box have the same
-priority; all numeric operations have a higher priority than
-comparison operations):
-
-\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
- \lineiii{\var{x} + \var{y}}{sum of \var{x} and \var{y}}{}
- \lineiii{\var{x} - \var{y}}{difference of \var{x} and \var{y}}{}
- \hline
- \lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{}
- \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)}
- \lineiii{\var{x} // \var{y}}{(floored) quotient of \var{x} and \var{y}}{(5)}
- \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{(4)}
- \hline
- \lineiii{-\var{x}}{\var{x} negated}{}
- \lineiii{+\var{x}}{\var{x} unchanged}{}
- \hline
- \lineiii{abs(\var{x})}{absolute value or magnitude of \var{x}}{}
- \lineiii{int(\var{x})}{\var{x} converted to integer}{(2)}
- \lineiii{long(\var{x})}{\var{x} converted to long integer}{(2)}
- \lineiii{float(\var{x})}{\var{x} converted to floating point}{}
- \lineiii{complex(\var{re},\var{im})}{a complex number with real part \var{re}, imaginary part \var{im}. \var{im} defaults to zero.}{}
- \lineiii{\var{c}.conjugate()}{conjugate of the complex number \var{c}}{}
- \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} // \var{y}, \var{x} \%{} \var{y})}}{(3)(4)}
- \lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{}
- \lineiii{\var{x} ** \var{y}}{\var{x} to the power \var{y}}{}
-\end{tableiii}
-\indexiii{operations on}{numeric}{types}
-\withsubitem{(complex number method)}{\ttindex{conjugate()}}
-
-\noindent
-Notes:
-\begin{description}
-
-\item[(1)]
-For (plain or long) integer division, the result is an integer.
-The result is always rounded towards minus infinity: 1/2 is 0,
-(-1)/2 is -1, 1/(-2) is -1, and (-1)/(-2) is 0. Note that the result
-is a long integer if either operand is a long integer, regardless of
-the numeric value.
-\indexii{integer}{division}
-\indexiii{long}{integer}{division}
-
-\item[(2)]
-Conversion from floating point to (long or plain) integer may round or
-truncate as in C; see functions \function{floor()} and
-\function{ceil()} in the \refmodule{math}\refbimodindex{math} module
-for well-defined conversions.
-\withsubitem{(in module math)}{\ttindex{floor()}\ttindex{ceil()}}
-\indexii{numeric}{conversions}
-\indexii{C}{language}
-
-\item[(3)]
-See section \ref{built-in-funcs}, ``Built-in Functions,'' for a full
-description.
-
-\item[(4)]
-Complex floor division operator, modulo operator, and \function{divmod()}.
-
-\deprecated{2.3}{Instead convert to float using \function{abs()}
-if appropriate.}
-
-\item[(5)]
-Also referred to as integer division. The resultant value is a whole integer,
-though the result's type is not necessarily int.
-\end{description}
-% XXXJH exceptions: overflow (when? what operations?) zerodivision
-
-\subsection{Bit-string Operations on Integer Types \label{bitstring-ops}}
-\nodename{Bit-string Operations}
-
-Plain and long integer types support additional operations that make
-sense only for bit-strings. Negative numbers are treated as their 2's
-complement value (for long integers, this assumes a sufficiently large
-number of bits that no overflow occurs during the operation).
-
-The priorities of the binary bit-wise operations are all lower than
-the numeric operations and higher than the comparisons; the unary
-operation \samp{\~} has the same priority as the other unary numeric
-operations (\samp{+} and \samp{-}).
-
-This table lists the bit-string operations sorted in ascending
-priority (operations in the same box have the same priority):
-
-\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
- \lineiii{\var{x} | \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{}
- \lineiii{\var{x} \^{} \var{y}}{bitwise \dfn{exclusive or} of \var{x} and \var{y}}{}
- \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} of \var{x} and \var{y}}{}
- % The empty groups below prevent conversion to guillemets.
- \lineiii{\var{x} <{}< \var{n}}{\var{x} shifted left by \var{n} bits}{(1), (2)}
- \lineiii{\var{x} >{}> \var{n}}{\var{x} shifted right by \var{n} bits}{(1), (3)}
- \hline
- \lineiii{\~\var{x}}{the bits of \var{x} inverted}{}
-\end{tableiii}
-\indexiii{operations on}{integer}{types}
-\indexii{bit-string}{operations}
-\indexii{shifting}{operations}
-\indexii{masking}{operations}
-
-\noindent
-Notes:
-\begin{description}
-\item[(1)] Negative shift counts are illegal and cause a
-\exception{ValueError} to be raised.
-\item[(2)] A left shift by \var{n} bits is equivalent to
-multiplication by \code{pow(2, \var{n})} without overflow check.
-\item[(3)] A right shift by \var{n} bits is equivalent to
-division by \code{pow(2, \var{n})} without overflow check.
-\end{description}
-
-
-\section{Iterator Types \label{typeiter}}
-
-\versionadded{2.2}
-\index{iterator protocol}
-\index{protocol!iterator}
-\index{sequence!iteration}
-\index{container!iteration over}
-
-Python supports a concept of iteration over containers. This is
-implemented using two distinct methods; these are used to allow
-user-defined classes to support iteration. Sequences, described below
-in more detail, always support the iteration methods.
-
-One method needs to be defined for container objects to provide
-iteration support:
-
-\begin{methoddesc}[container]{__iter__}{}
- Return an iterator object. The object is required to support the
- iterator protocol described below. If a container supports
- different types of iteration, additional methods can be provided to
- specifically request iterators for those iteration types. (An
- example of an object supporting multiple forms of iteration would be
- a tree structure which supports both breadth-first and depth-first
- traversal.) This method corresponds to the \member{tp_iter} slot of
- the type structure for Python objects in the Python/C API.
-\end{methoddesc}
-
-The iterator objects themselves are required to support the following
-two methods, which together form the \dfn{iterator protocol}:
-
-\begin{methoddesc}[iterator]{__iter__}{}
- Return the iterator object itself. This is required to allow both
- containers and iterators to be used with the \keyword{for} and
- \keyword{in} statements. This method corresponds to the
- \member{tp_iter} slot of the type structure for Python objects in
- the Python/C API.
-\end{methoddesc}
-
-\begin{methoddesc}[iterator]{next}{}
- Return the next item from the container. If there are no further
- items, raise the \exception{StopIteration} exception. This method
- corresponds to the \member{tp_iternext} slot of the type structure
- for Python objects in the Python/C API.
-\end{methoddesc}
-
-Python defines several iterator objects to support iteration over
-general and specific sequence types, dictionaries, and other more
-specialized forms. The specific types are not important beyond their
-implementation of the iterator protocol.
-
-The intention of the protocol is that once an iterator's \method{__next__()}
-method raises \exception{StopIteration}, it will continue to do so on subsequent
-calls. Implementations that do not obey this property are deemed broken. (This
-constraint was added in Python 2.3; in Python 2.2, various iterators are broken
-according to this rule.)
-
-Python's generators provide a convenient way to implement the iterator protocol.
-If a container object's \method{__iter__()} method is implemented as a
-generator, it will automatically return an iterator object (technically, a
-generator object) supplying the \method{__iter__()} and \method{__next__()}
-methods.
-
-
-\section{Sequence Types ---
- \class{str}, \class{unicode}, \class{list},
- \class{tuple}, \class{buffer}, \class{range}
- \label{typesseq}}
-
-There are six sequence types: strings, Unicode strings, lists,
-tuples, buffers, and range objects.
-
-String literals are written in single or double quotes:
-\code{'xyzzy'}, \code{"frobozz"}. See chapter 2 of the
-\citetitle[../ref/strings.html]{Python Reference Manual} for more about
-string literals. Unicode strings are much like strings, but are
-specified in the syntax using a preceding \character{u} character:
-\code{u'abc'}, \code{u"def"}. Lists are constructed with square brackets,
-separating items with commas: \code{[a, b, c]}. Tuples are
-constructed by the comma operator (not within square brackets), with
-or without enclosing parentheses, but an empty tuple must have the
-enclosing parentheses, such as \code{a, b, c} or \code{()}. A single
-item tuple must have a trailing comma, such as \code{(d,)}.
-\obindex{sequence}
-\obindex{string}
-\obindex{Unicode}
-\obindex{tuple}
-\obindex{list}
-
-Buffer objects are not directly supported by Python syntax, but can be
-created by calling the builtin function
-\function{buffer()}.\bifuncindex{buffer} They don't support
-concatenation or repetition.
-\obindex{buffer}
-
-Xrange objects are similar to buffers in that there is no specific
-syntax to create them, but they are created using the \function{range()}
-function.\bifuncindex{range} They don't support slicing,
-concatenation or repetition, and using \code{in}, \code{not in},
-\function{min()} or \function{max()} on them is inefficient.
-\obindex{range}
-
-Most sequence types support the following operations. The \samp{in} and
-\samp{not in} operations have the same priorities as the comparison
-operations. The \samp{+} and \samp{*} operations have the same
-priority as the corresponding numeric operations.\footnote{They must
-have since the parser can't tell the type of the operands.}
-
-This table lists the sequence operations sorted in ascending priority
-(operations in the same box have the same priority). In the table,
-\var{s} and \var{t} are sequences of the same type; \var{n}, \var{i}
-and \var{j} are integers:
-
-\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
- \lineiii{\var{x} in \var{s}}{\code{True} if an item of \var{s} is equal to \var{x}, else \code{False}}{(1)}
- \lineiii{\var{x} not in \var{s}}{\code{False} if an item of \var{s} is
-equal to \var{x}, else \code{True}}{(1)}
- \hline
- \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{(6)}
- \lineiii{\var{s} * \var{n}\textrm{,} \var{n} * \var{s}}{\var{n} shallow copies of \var{s} concatenated}{(2)}
- \hline
- \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(3)}
- \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(3), (4)}
- \lineiii{\var{s}[\var{i}:\var{j}:\var{k}]}{slice of \var{s} from \var{i} to \var{j} with step \var{k}}{(3), (5)}
- \hline
- \lineiii{len(\var{s})}{length of \var{s}}{}
- \lineiii{min(\var{s})}{smallest item of \var{s}}{}
- \lineiii{max(\var{s})}{largest item of \var{s}}{}
-\end{tableiii}
-\indexiii{operations on}{sequence}{types}
-\bifuncindex{len}
-\bifuncindex{min}
-\bifuncindex{max}
-\indexii{concatenation}{operation}
-\indexii{repetition}{operation}
-\indexii{subscript}{operation}
-\indexii{slice}{operation}
-\indexii{extended slice}{operation}
-\opindex{in}
-\opindex{not in}
-
-\noindent
-Notes:
-
-\begin{description}
-\item[(1)] When \var{s} is a string or Unicode string object the
-\code{in} and \code{not in} operations act like a substring test. In
-Python versions before 2.3, \var{x} had to be a string of length 1.
-In Python 2.3 and beyond, \var{x} may be a string of any length.
-
-\item[(2)] Values of \var{n} less than \code{0} are treated as
- \code{0} (which yields an empty sequence of the same type as
- \var{s}). Note also that the copies are shallow; nested structures
- are not copied. This often haunts new Python programmers; consider:
-
-\begin{verbatim}
->>> lists = [[]] * 3
->>> lists
-[[], [], []]
->>> lists[0].append(3)
->>> lists
-[[3], [3], [3]]
-\end{verbatim}
-
- What has happened is that \code{[[]]} is a one-element list containing
- an empty list, so all three elements of \code{[[]] * 3} are (pointers to)
- this single empty list. Modifying any of the elements of \code{lists}
- modifies this single list. You can create a list of different lists this
- way:
-
-\begin{verbatim}
->>> lists = [[] for i in range(3)]
->>> lists[0].append(3)
->>> lists[1].append(5)
->>> lists[2].append(7)
->>> lists
-[[3], [5], [7]]
-\end{verbatim}
-
-\item[(3)] If \var{i} or \var{j} is negative, the index is relative to
- the end of the string: \code{len(\var{s}) + \var{i}} or
- \code{len(\var{s}) + \var{j}} is substituted. But note that \code{-0} is
- still \code{0}.
-
-\item[(4)] The slice of \var{s} from \var{i} to \var{j} is defined as
- the sequence of items with index \var{k} such that \code{\var{i} <=
- \var{k} < \var{j}}. If \var{i} or \var{j} is greater than
- \code{len(\var{s})}, use \code{len(\var{s})}. If \var{i} is omitted
- or \code{None}, use \code{0}. If \var{j} is omitted or \code{None},
- use \code{len(\var{s})}. If \var{i} is greater than or equal to \var{j},
- the slice is empty.
-
-\item[(5)] The slice of \var{s} from \var{i} to \var{j} with step
- \var{k} is defined as the sequence of items with index
- \code{\var{x} = \var{i} + \var{n}*\var{k}} such that
- $0 \leq n < \frac{j-i}{k}$. In other words, the indices
- are \code{i}, \code{i+k}, \code{i+2*k}, \code{i+3*k} and so on, stopping when
- \var{j} is reached (but never including \var{j}). If \var{i} or \var{j}
- is greater than \code{len(\var{s})}, use \code{len(\var{s})}. If
- \var{i} or \var{j} are omitted or \code{None}, they become ``end'' values
- (which end depends on the sign of \var{k}). Note, \var{k} cannot
- be zero. If \var{k} is \code{None}, it is treated like \code{1}.
-
-\item[(6)] If \var{s} and \var{t} are both strings, some Python
-implementations such as CPython can usually perform an in-place optimization
-for assignments of the form \code{\var{s}=\var{s}+\var{t}} or
-\code{\var{s}+=\var{t}}. When applicable, this optimization makes
-quadratic run-time much less likely. This optimization is both version
-and implementation dependent. For performance sensitive code, it is
-preferable to use the \method{str.join()} method which assures consistent
-linear concatenation performance across versions and implementations.
-\versionchanged[Formerly, string concatenation never occurred in-place]{2.4}
-
-\end{description}
-
-
-\subsection{String Methods \label{string-methods}}
-\indexii{string}{methods}
-
-These are the string methods which both 8-bit strings and Unicode
-objects support:
-
-\begin{methoddesc}[str]{capitalize}{}
-Return a copy of the string with only its first character capitalized.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{center}{width\optional{, fillchar}}
-Return centered in a string of length \var{width}. Padding is done
-using the specified \var{fillchar} (default is a space).
-\versionchanged[Support for the \var{fillchar} argument]{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{count}{sub\optional{, start\optional{, end}}}
-Return the number of occurrences of substring \var{sub} in string
-S\code{[\var{start}:\var{end}]}. Optional arguments \var{start} and
-\var{end} are interpreted as in slice notation.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{decode}{\optional{encoding\optional{, errors}}}
-Decodes the string using the codec registered for \var{encoding}.
-\var{encoding} defaults to the default string encoding. \var{errors}
-may be given to set a different error handling scheme. The default is
-\code{'strict'}, meaning that encoding errors raise
-\exception{UnicodeError}. Other possible values are \code{'ignore'},
-\code{'replace'} and any other name registered via
-\function{codecs.register_error}, see section~\ref{codec-base-classes}.
-\versionadded{2.2}
-\versionchanged[Support for other error handling schemes added]{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{encode}{\optional{encoding\optional{,errors}}}
-Return an encoded version of the string. Default encoding is the current
-default string encoding. \var{errors} may be given to set a different
-error handling scheme. The default for \var{errors} is
-\code{'strict'}, meaning that encoding errors raise a
-\exception{UnicodeError}. Other possible values are \code{'ignore'},
-\code{'replace'}, \code{'xmlcharrefreplace'}, \code{'backslashreplace'}
-and any other name registered via \function{codecs.register_error},
-see section~\ref{codec-base-classes}.
-For a list of possible encodings, see section~\ref{standard-encodings}.
-\versionadded{2.0}
-\versionchanged[Support for \code{'xmlcharrefreplace'} and
-\code{'backslashreplace'} and other error handling schemes added]{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{endswith}{suffix\optional{, start\optional{, end}}}
-Return \code{True} if the string ends with the specified \var{suffix},
-otherwise return \code{False}. \var{suffix} can also be a tuple of
-suffixes to look for. With optional \var{start}, test beginning at
-that position. With optional \var{end}, stop comparing at that position.
-
-\versionchanged[Accept tuples as \var{suffix}]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{expandtabs}{\optional{tabsize}}
-Return a copy of the string where all tab characters are expanded
-using spaces. If \var{tabsize} is not given, a tab size of \code{8}
-characters is assumed.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{find}{sub\optional{, start\optional{, end}}}
-Return the lowest index in the string where substring \var{sub} is
-found, such that \var{sub} is contained in the range [\var{start},
-\var{end}]. Optional arguments \var{start} and \var{end} are
-interpreted as in slice notation. Return \code{-1} if \var{sub} is
-not found.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{index}{sub\optional{, start\optional{, end}}}
-Like \method{find()}, but raise \exception{ValueError} when the
-substring is not found.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{isalnum}{}
-Return true if all characters in the string are alphanumeric and there
-is at least one character, false otherwise.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{isalpha}{}
-Return true if all characters in the string are alphabetic and there
-is at least one character, false otherwise.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{isdigit}{}
-Return true if all characters in the string are digits and there
-is at least one character, false otherwise.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{isidentifier}{}
-Return True if S is a valid identifier according
-to the language definition.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{islower}{}
-Return true if all cased characters in the string are lowercase and
-there is at least one cased character, false otherwise.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{isspace}{}
-Return true if there are only whitespace characters in the string and
-there is at least one character, false otherwise.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{istitle}{}
-Return true if the string is a titlecased string and there is at least one
-character, for example uppercase characters may only follow uncased
-characters and lowercase characters only cased ones. Return false
-otherwise.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{isupper}{}
-Return true if all cased characters in the string are uppercase and
-there is at least one cased character, false otherwise.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{join}{seq}
-Return a string which is the concatenation of the strings in the
-sequence \var{seq}. The separator between elements is the string
-providing this method.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{ljust}{width\optional{, fillchar}}
-Return the string left justified in a string of length \var{width}.
-Padding is done using the specified \var{fillchar} (default is a
-space). The original string is returned if
-\var{width} is less than \code{len(\var{s})}.
-\versionchanged[Support for the \var{fillchar} argument]{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{lower}{}
-Return a copy of the string converted to lowercase.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{lstrip}{\optional{chars}}
-Return a copy of the string with leading characters removed. The
-\var{chars} argument is a string specifying the set of characters
-to be removed. If omitted or \code{None}, the \var{chars} argument
-defaults to removing whitespace. The \var{chars} argument is not
-a prefix; rather, all combinations of its values are stripped:
-\begin{verbatim}
- >>> ' spacious '.lstrip()
- 'spacious '
- >>> 'www.example.com'.lstrip('cmowz.')
- 'example.com'
-\end{verbatim}
-\versionchanged[Support for the \var{chars} argument]{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{partition}{sep}
-Split the string at the first occurrence of \var{sep}, and return
-a 3-tuple containing the part before the separator, the separator
-itself, and the part after the separator. If the separator is not
-found, return a 3-tuple containing the string itself, followed by
-two empty strings.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{replace}{old, new\optional{, count}}
-Return a copy of the string with all occurrences of substring
-\var{old} replaced by \var{new}. If the optional argument
-\var{count} is given, only the first \var{count} occurrences are
-replaced.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{rfind}{sub \optional{,start \optional{,end}}}
-Return the highest index in the string where substring \var{sub} is
-found, such that \var{sub} is contained within s[start,end]. Optional
-arguments \var{start} and \var{end} are interpreted as in slice
-notation. Return \code{-1} on failure.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{rindex}{sub\optional{, start\optional{, end}}}
-Like \method{rfind()} but raises \exception{ValueError} when the
-substring \var{sub} is not found.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{rjust}{width\optional{, fillchar}}
-Return the string right justified in a string of length \var{width}.
-Padding is done using the specified \var{fillchar} (default is a space).
-The original string is returned if
-\var{width} is less than \code{len(\var{s})}.
-\versionchanged[Support for the \var{fillchar} argument]{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{rpartition}{sep}
-Split the string at the last occurrence of \var{sep}, and return
-a 3-tuple containing the part before the separator, the separator
-itself, and the part after the separator. If the separator is not
-found, return a 3-tuple containing two empty strings, followed by
-the string itself.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{rsplit}{\optional{sep \optional{,maxsplit}}}
-Return a list of the words in the string, using \var{sep} as the
-delimiter string. If \var{maxsplit} is given, at most \var{maxsplit}
-splits are done, the \emph{rightmost} ones. If \var{sep} is not specified
-or \code{None}, any whitespace string is a separator. Except for splitting
-from the right, \method{rsplit()} behaves like \method{split()} which
-is described in detail below.
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{rstrip}{\optional{chars}}
-Return a copy of the string with trailing characters removed. The
-\var{chars} argument is a string specifying the set of characters
-to be removed. If omitted or \code{None}, the \var{chars} argument
-defaults to removing whitespace. The \var{chars} argument is not
-a suffix; rather, all combinations of its values are stripped:
-\begin{verbatim}
- >>> ' spacious '.rstrip()
- ' spacious'
- >>> 'mississippi'.rstrip('ipz')
- 'mississ'
-\end{verbatim}
-\versionchanged[Support for the \var{chars} argument]{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{split}{\optional{sep \optional{,maxsplit}}}
-Return a list of the words in the string, using \var{sep} as the
-delimiter string. If \var{maxsplit} is given, at most \var{maxsplit}
-splits are done. (thus, the list will have at most \code{\var{maxsplit}+1}
-elements). If \var{maxsplit} is not specified, then there
-is no limit on the number of splits (all possible splits are made).
-Consecutive delimiters are not grouped together and are
-deemed to delimit empty strings (for example, \samp{'1,,2'.split(',')}
-returns \samp{['1', '', '2']}). The \var{sep} argument may consist of
-multiple characters (for example, \samp{'1, 2, 3'.split(', ')} returns
-\samp{['1', '2', '3']}). Splitting an empty string with a specified
-separator returns \samp{['']}.
-
-If \var{sep} is not specified or is \code{None}, a different splitting
-algorithm is applied. First, whitespace characters (spaces, tabs,
-newlines, returns, and formfeeds) are stripped from both ends. Then,
-words are separated by arbitrary length strings of whitespace
-characters. Consecutive whitespace delimiters are treated as a single
-delimiter (\samp{'1 2 3'.split()} returns \samp{['1', '2', '3']}).
-Splitting an empty string or a string consisting of just whitespace
-returns an empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{splitlines}{\optional{keepends}}
-Return a list of the lines in the string, breaking at line
-boundaries. Line breaks are not included in the resulting list unless
-\var{keepends} is given and true.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{startswith}{prefix\optional{,
- start\optional{, end}}}
-Return \code{True} if string starts with the \var{prefix}, otherwise
-return \code{False}. \var{prefix} can also be a tuple of
-prefixes to look for. With optional \var{start}, test string beginning at
-that position. With optional \var{end}, stop comparing string at that
-position.
-
-\versionchanged[Accept tuples as \var{prefix}]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{strip}{\optional{chars}}
-Return a copy of the string with the leading and trailing characters
-removed. The \var{chars} argument is a string specifying the set of
-characters to be removed. If omitted or \code{None}, the \var{chars}
-argument defaults to removing whitespace. The \var{chars} argument is not
-a prefix or suffix; rather, all combinations of its values are stripped:
-\begin{verbatim}
- >>> ' spacious '.strip()
- 'spacious'
- >>> 'www.example.com'.strip('cmowz.')
- 'example'
-\end{verbatim}
-\versionchanged[Support for the \var{chars} argument]{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{swapcase}{}
-Return a copy of the string with uppercase characters converted to
-lowercase and vice versa.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{title}{}
-Return a titlecased version of the string: words start with uppercase
-characters, all remaining cased characters are lowercase.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{translate}{table\optional{, deletechars}}
-Return a copy of the string where all characters occurring in the
-optional argument \var{deletechars} are removed, and the remaining
-characters have been mapped through the given translation table, which
-must be a string of length 256.
-
-You can use the \function{maketrans()} helper function in the
-\refmodule{string} module to create a translation table.
-For string objects, set the \var{table} argument to \code{None}
-for translations that only delete characters:
-\begin{verbatim}
- >>> 'read this short text'.translate(None, 'aeiou')
- 'rd ths shrt txt'
-\end{verbatim}
-\versionadded[Support for a \code{None} \var{table} argument]{2.6}
-
-For Unicode objects, the \method{translate()} method does not
-accept the optional \var{deletechars} argument. Instead, it
-returns a copy of the \var{s} where all characters have been mapped
-through the given translation table which must be a mapping of
-Unicode ordinals to Unicode ordinals, Unicode strings or \code{None}.
-Unmapped characters are left untouched. Characters mapped to \code{None}
-are deleted. Note, a more flexible approach is to create a custom
-character mapping codec using the \refmodule{codecs} module (see
-\module{encodings.cp1251} for an example).
-\end{methoddesc}
-
-\begin{methoddesc}[str]{upper}{}
-Return a copy of the string converted to uppercase.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{zfill}{width}
-Return the numeric string left filled with zeros in a string
-of length \var{width}. The original string is returned if
-\var{width} is less than \code{len(\var{s})}.
-\versionadded{2.2.2}
-\end{methoddesc}
-
-
-\subsection{String Formatting Operations \label{typesseq-strings}}
-
-\index{formatting, string (\%{})}
-\index{interpolation, string (\%{})}
-\index{string!formatting}
-\index{string!interpolation}
-\index{printf-style formatting}
-\index{sprintf-style formatting}
-\index{\protect\%{} formatting}
-\index{\protect\%{} interpolation}
-
-String and Unicode objects have one unique built-in operation: the
-\code{\%} operator (modulo). This is also known as the string
-\emph{formatting} or \emph{interpolation} operator. Given
-\code{\var{format} \% \var{values}} (where \var{format} is a string or
-Unicode object), \code{\%} conversion specifications in \var{format}
-are replaced with zero or more elements of \var{values}. The effect
-is similar to the using \cfunction{sprintf()} in the C language. If
-\var{format} is a Unicode object, or if any of the objects being
-converted using the \code{\%s} conversion are Unicode objects, the
-result will also be a Unicode object.
-
-If \var{format} requires a single argument, \var{values} may be a
-single non-tuple object.\footnote{To format only a tuple you
-should therefore provide a singleton tuple whose only element
-is the tuple to be formatted.} Otherwise, \var{values} must be a tuple with
-exactly the number of items specified by the format string, or a
-single mapping object (for example, a dictionary).
-
-A conversion specifier contains two or more characters and has the
-following components, which must occur in this order:
-
-\begin{enumerate}
- \item The \character{\%} character, which marks the start of the
- specifier.
- \item Mapping key (optional), consisting of a parenthesised sequence
- of characters (for example, \code{(somename)}).
- \item Conversion flags (optional), which affect the result of some
- conversion types.
- \item Minimum field width (optional). If specified as an
- \character{*} (asterisk), the actual width is read from the
- next element of the tuple in \var{values}, and the object to
- convert comes after the minimum field width and optional
- precision.
- \item Precision (optional), given as a \character{.} (dot) followed
- by the precision. If specified as \character{*} (an
- asterisk), the actual width is read from the next element of
- the tuple in \var{values}, and the value to convert comes after
- the precision.
- \item Length modifier (optional).
- \item Conversion type.
-\end{enumerate}
-
-When the right argument is a dictionary (or other mapping type), then
-the formats in the string \emph{must} include a parenthesised mapping key into
-that dictionary inserted immediately after the \character{\%}
-character. The mapping key selects the value to be formatted from the
-mapping. For example:
-
-\begin{verbatim}
->>> print '%(language)s has %(#)03d quote types.' % \
- {'language': "Python", "#": 2}
-Python has 002 quote types.
-\end{verbatim}
-
-In this case no \code{*} specifiers may occur in a format (since they
-require a sequential parameter list).
-
-The conversion flag characters are:
-
-\begin{tableii}{c|l}{character}{Flag}{Meaning}
- \lineii{\#}{The value conversion will use the ``alternate form''
- (where defined below).}
- \lineii{0}{The conversion will be zero padded for numeric values.}
- \lineii{-}{The converted value is left adjusted (overrides
- the \character{0} conversion if both are given).}
- \lineii{{~}}{(a space) A blank should be left before a positive number
- (or empty string) produced by a signed conversion.}
- \lineii{+}{A sign character (\character{+} or \character{-}) will
- precede the conversion (overrides a "space" flag).}
-\end{tableii}
-
-A length modifier (\code{h}, \code{l}, or \code{L}) may be
-present, but is ignored as it is not necessary for Python.
-
-The conversion types are:
-
-\begin{tableiii}{c|l|c}{character}{Conversion}{Meaning}{Notes}
- \lineiii{d}{Signed integer decimal.}{}
- \lineiii{i}{Signed integer decimal.}{}
- \lineiii{o}{Unsigned octal.}{(1)}
- \lineiii{u}{Unsigned decimal.}{}
- \lineiii{x}{Unsigned hexadecimal (lowercase).}{(2)}
- \lineiii{X}{Unsigned hexadecimal (uppercase).}{(2)}
- \lineiii{e}{Floating point exponential format (lowercase).}{(3)}
- \lineiii{E}{Floating point exponential format (uppercase).}{(3)}
- \lineiii{f}{Floating point decimal format.}{(3)}
- \lineiii{F}{Floating point decimal format.}{(3)}
- \lineiii{g}{Floating point format. Uses exponential format
- if exponent is greater than -4 or less than precision,
- decimal format otherwise.}{(4)}
- \lineiii{G}{Floating point format. Uses exponential format
- if exponent is greater than -4 or less than precision,
- decimal format otherwise.}{(4)}
- \lineiii{c}{Single character (accepts integer or single character
- string).}{}
- \lineiii{r}{String (converts any python object using
- \function{repr()}).}{(5)}
- \lineiii{s}{String (converts any python object using
- \function{str()}).}{(6)}
- \lineiii{\%}{No argument is converted, results in a \character{\%}
- character in the result.}{}
-\end{tableiii}
-
-\noindent
-Notes:
-\begin{description}
- \item[(1)]
- The alternate form causes a leading zero (\character{0}) to be
- inserted between left-hand padding and the formatting of the
- number if the leading character of the result is not already a
- zero.
- \item[(2)]
- The alternate form causes a leading \code{'0x'} or \code{'0X'}
- (depending on whether the \character{x} or \character{X} format
- was used) to be inserted between left-hand padding and the
- formatting of the number if the leading character of the result is
- not already a zero.
- \item[(3)]
- The alternate form causes the result to always contain a decimal
- point, even if no digits follow it.
-
- The precision determines the number of digits after the decimal
- point and defaults to 6.
- \item[(4)]
- The alternate form causes the result to always contain a decimal
- point, and trailing zeroes are not removed as they would
- otherwise be.
-
- The precision determines the number of significant digits before
- and after the decimal point and defaults to 6.
- \item[(5)]
- The \code{\%r} conversion was added in Python 2.0.
-
- The precision determines the maximal number of characters used.
- \item[(6)]
- If the object or format provided is a \class{unicode} string,
- the resulting string will also be \class{unicode}.
-
- The precision determines the maximal number of characters used.
-\end{description}
-
-% XXX Examples?
-
-Since Python strings have an explicit length, \code{\%s} conversions
-do not assume that \code{'\e0'} is the end of the string.
-
-For safety reasons, floating point precisions are clipped to 50;
-\code{\%f} conversions for numbers whose absolute value is over 1e25
-are replaced by \code{\%g} conversions.\footnote{
- These numbers are fairly arbitrary. They are intended to
- avoid printing endless strings of meaningless digits without hampering
- correct use and without having to know the exact precision of floating
- point values on a particular machine.
-} All other errors raise exceptions.
-
-Additional string operations are defined in standard modules
-\refmodule{string}\refstmodindex{string}\ and
-\refmodule{re}.\refstmodindex{re}
-
-
-\subsection{XRange Type \label{typesseq-range}}
-
-The \class{range}\obindex{range} type is an immutable sequence which
-is commonly used for looping. The advantage of the \class{range}
-type is that an \class{range} object will always take the same amount
-of memory, no matter the size of the range it represents. There are
-no consistent performance advantages.
-
-XRange objects have very little behavior: they only support indexing,
-iteration, and the \function{len()} function.
-
-
-\subsection{Mutable Sequence Types \label{typesseq-mutable}}
-
-List objects support additional operations that allow in-place
-modification of the object.
-Other mutable sequence types (when added to the language) should
-also support these operations.
-Strings and tuples are immutable sequence types: such objects cannot
-be modified once created.
-The following operations are defined on mutable sequence types (where
-\var{x} is an arbitrary object):
-\indexiii{mutable}{sequence}{types}
-\obindex{list}
-
-\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
- \lineiii{\var{s}[\var{i}] = \var{x}}
- {item \var{i} of \var{s} is replaced by \var{x}}{}
- \lineiii{\var{s}[\var{i}:\var{j}] = \var{t}}
- {slice of \var{s} from \var{i} to \var{j}
- is replaced by the contents of the iterable \var{t}}{}
- \lineiii{del \var{s}[\var{i}:\var{j}]}
- {same as \code{\var{s}[\var{i}:\var{j}] = []}}{}
- \lineiii{\var{s}[\var{i}:\var{j}:\var{k}] = \var{t}}
- {the elements of \code{\var{s}[\var{i}:\var{j}:\var{k}]} are replaced by those of \var{t}}{(1)}
- \lineiii{del \var{s}[\var{i}:\var{j}:\var{k}]}
- {removes the elements of \code{\var{s}[\var{i}:\var{j}:\var{k}]} from the list}{}
- \lineiii{\var{s}.append(\var{x})}
- {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{(2)}
- \lineiii{\var{s}.extend(\var{x})}
- {same as \code{\var{s}[len(\var{s}):len(\var{s})] = \var{x}}}{(3)}
- \lineiii{\var{s}.count(\var{x})}
- {return number of \var{i}'s for which \code{\var{s}[\var{i}] == \var{x}}}{}
- \lineiii{\var{s}.index(\var{x}\optional{, \var{i}\optional{, \var{j}}})}
- {return smallest \var{k} such that \code{\var{s}[\var{k}] == \var{x}} and
- \code{\var{i} <= \var{k} < \var{j}}}{(4)}
- \lineiii{\var{s}.insert(\var{i}, \var{x})}
- {same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]}}{(5)}
- \lineiii{\var{s}.pop(\optional{\var{i}})}
- {same as \code{\var{x} = \var{s}[\var{i}]; del \var{s}[\var{i}]; return \var{x}}}{(6)}
- \lineiii{\var{s}.remove(\var{x})}
- {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(4)}
- \lineiii{\var{s}.reverse()}
- {reverses the items of \var{s} in place}{(7)}
- \lineiii{\var{s}.sort(\optional{\var{cmp}\optional{,
- \var{key}\optional{, \var{reverse}}}})}
- {sort the items of \var{s} in place}{(7), (8), (9), (10)}
-\end{tableiii}
-\indexiv{operations on}{mutable}{sequence}{types}
-\indexiii{operations on}{sequence}{types}
-\indexiii{operations on}{list}{type}
-\indexii{subscript}{assignment}
-\indexii{slice}{assignment}
-\indexii{extended slice}{assignment}
-\stindex{del}
-\withsubitem{(list method)}{
- \ttindex{append()}\ttindex{extend()}\ttindex{count()}\ttindex{index()}
- \ttindex{insert()}\ttindex{pop()}\ttindex{remove()}\ttindex{reverse()}
- \ttindex{sort()}}
-\noindent
-Notes:
-\begin{description}
-\item[(1)] \var{t} must have the same length as the slice it is
- replacing.
-
-\item[(2)] The C implementation of Python has historically accepted
- multiple parameters and implicitly joined them into a tuple; this
- no longer works in Python 2.0. Use of this misfeature has been
- deprecated since Python 1.4.
-
-\item[(3)] \var{x} can be any iterable object.
-
-\item[(4)] Raises \exception{ValueError} when \var{x} is not found in
- \var{s}. When a negative index is passed as the second or third parameter
- to the \method{index()} method, the list length is added, as for slice
- indices. If it is still negative, it is truncated to zero, as for
- slice indices. \versionchanged[Previously, \method{index()} didn't
- have arguments for specifying start and stop positions]{2.3}
-
-\item[(5)] When a negative index is passed as the first parameter to
- the \method{insert()} method, the list length is added, as for slice
- indices. If it is still negative, it is truncated to zero, as for
- slice indices. \versionchanged[Previously, all negative indices
- were truncated to zero]{2.3}
-
-\item[(6)] The \method{pop()} method is only supported by the list and
- array types. The optional argument \var{i} defaults to \code{-1},
- so that by default the last item is removed and returned.
-
-\item[(7)] The \method{sort()} and \method{reverse()} methods modify the
- list in place for economy of space when sorting or reversing a large
- list. To remind you that they operate by side effect, they don't return
- the sorted or reversed list.
-
-\item[(8)] The \method{sort()} method takes optional arguments for
- controlling the comparisons.
-
- \var{cmp} specifies a custom comparison function of two arguments
- (list items) 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:
- \samp{\var{cmp}=\keyword{lambda} \var{x},\var{y}:
- \function{cmp}(x.lower(), y.lower())}
-
- \var{key} specifies a function of one argument that is used to
- extract a comparison key from each list element:
- \samp{\var{key}=\function{str.lower}}
-
- \var{reverse} is a boolean value. If set to \code{True}, then the
- list elements are sorted as if each comparison were reversed.
-
- In general, the \var{key} and \var{reverse} conversion processes are
- much faster than specifying an equivalent \var{cmp} function. This is
- because \var{cmp} is called multiple times for each list element while
- \var{key} and \var{reverse} touch each element only once.
-
- \versionchanged[Support for \code{None} as an equivalent to omitting
- \var{cmp} was added]{2.3}
-
- \versionchanged[Support for \var{key} and \var{reverse} was added]{2.4}
-
-\item[(9)] Starting with Python 2.3, the \method{sort()} method is
- guaranteed to be stable. A sort is stable if it guarantees not to
- change the relative order of elements that compare equal --- this is
- helpful for sorting in multiple passes (for example, sort by
- department, then by salary grade).
-
-\item[(10)] While a list is being sorted, the effect of attempting to
- mutate, or even inspect, the list is undefined. The C
- implementation of Python 2.3 and newer makes the list appear empty
- for the duration, and raises \exception{ValueError} if it can detect
- that the list has been mutated during a sort.
-\end{description}
-
-\section{Set Types ---
- \class{set}, \class{frozenset}
- \label{types-set}}
-\obindex{set}
-
-A \dfn{set} object is an unordered collection of distinct hashable objects.
-Common uses include membership testing, removing duplicates from a sequence,
-and computing mathematical operations such as intersection, union, difference,
-and symmetric difference.
-\versionadded{2.4}
-
-Like other collections, sets support \code{\var{x} in \var{set}},
-\code{len(\var{set})}, and \code{for \var{x} in \var{set}}. Being an
-unordered collection, sets do not record element position or order of
-insertion. Accordingly, sets do not support indexing, slicing, or
-other sequence-like behavior.
-
-There are currently two builtin set types, \class{set} and \class{frozenset}.
-The \class{set} type is mutable --- the contents can be changed using methods
-like \method{add()} and \method{remove()}. Since it is mutable, it has no
-hash value and cannot be used as either a dictionary key or as an element of
-another set. The \class{frozenset} type is immutable and hashable --- its
-contents cannot be altered after is created; however, it can be used as
-a dictionary key or as an element of another set.
-
-Instances of \class{set} and \class{frozenset} provide the following operations:
-
-\begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result}
- \lineiii{len(\var{s})}{}{cardinality of set \var{s}}
-
- \hline
- \lineiii{\var{x} in \var{s}}{}
- {test \var{x} for membership in \var{s}}
- \lineiii{\var{x} not in \var{s}}{}
- {test \var{x} for non-membership in \var{s}}
- \lineiii{\var{s}.issubset(\var{t})}{\code{\var{s} <= \var{t}}}
- {test whether every element in \var{s} is in \var{t}}
- \lineiii{\var{s}.issuperset(\var{t})}{\code{\var{s} >= \var{t}}}
- {test whether every element in \var{t} is in \var{s}}
-
- \hline
- \lineiii{\var{s}.union(\var{t})}{\var{s} | \var{t}}
- {new set with elements from both \var{s} and \var{t}}
- \lineiii{\var{s}.intersection(\var{t})}{\var{s} \&\ \var{t}}
- {new set with elements common to \var{s} and \var{t}}
- \lineiii{\var{s}.difference(\var{t})}{\var{s} - \var{t}}
- {new set with elements in \var{s} but not in \var{t}}
- \lineiii{\var{s}.symmetric_difference(\var{t})}{\var{s} \^\ \var{t}}
- {new set with elements in either \var{s} or \var{t} but not both}
- \lineiii{\var{s}.copy()}{}
- {new set with a shallow copy of \var{s}}
-\end{tableiii}
-
-Note, the non-operator versions of \method{union()}, \method{intersection()},
-\method{difference()}, and \method{symmetric_difference()},
-\method{issubset()}, and \method{issuperset()} methods will accept any
-iterable as an argument. In contrast, their operator based counterparts
-require their arguments to be sets. This precludes error-prone constructions
-like \code{set('abc') \&\ 'cbs'} in favor of the more readable
-\code{set('abc').intersection('cbs')}.
-
-Both \class{set} and \class{frozenset} support set to set comparisons.
-Two sets are equal if and only if every element of each set is contained in
-the other (each is a subset of the other).
-A set is less than another set if and only if the first set is a proper
-subset of the second set (is a subset, but is not equal).
-A set is greater than another set if and only if the first set is a proper
-superset of the second set (is a superset, but is not equal).
-
-Instances of \class{set} are compared to instances of \class{frozenset} based
-on their members. For example, \samp{set('abc') == frozenset('abc')} returns
-\code{True}.
-
-The subset and equality comparisons do not generalize to a complete
-ordering function. For example, any two disjoint sets are not equal and
-are not subsets of each other, so \emph{all} of the following return
-\code{False}: \code{\var{a}<\var{b}}, \code{\var{a}==\var{b}}, or
-\code{\var{a}>\var{b}}.
-Accordingly, sets do not implement the \method{__cmp__} method.
-
-Since sets only define partial ordering (subset relationships), the output
-of the \method{list.sort()} method is undefined for lists of sets.
-
-Set elements are like dictionary keys; they need to define both
-\method{__hash__} and \method{__eq__} methods.
-
-Binary operations that mix \class{set} instances with \class{frozenset}
-return the type of the first operand. For example:
-\samp{frozenset('ab') | set('bc')} returns an instance of \class{frozenset}.
-
-The following table lists operations available for \class{set}
-that do not apply to immutable instances of \class{frozenset}:
-
-\begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result}
- \lineiii{\var{s}.update(\var{t})}
- {\var{s} |= \var{t}}
- {update set \var{s}, adding elements from \var{t}}
- \lineiii{\var{s}.intersection_update(\var{t})}
- {\var{s} \&= \var{t}}
- {update set \var{s}, keeping only elements found in both \var{s} and \var{t}}
- \lineiii{\var{s}.difference_update(\var{t})}
- {\var{s} -= \var{t}}
- {update set \var{s}, removing elements found in \var{t}}
- \lineiii{\var{s}.symmetric_difference_update(\var{t})}
- {\var{s} \textasciicircum= \var{t}}
- {update set \var{s}, keeping only elements found in either \var{s} or \var{t}
- but not in both}
-
- \hline
- \lineiii{\var{s}.add(\var{x})}{}
- {add element \var{x} to set \var{s}}
- \lineiii{\var{s}.remove(\var{x})}{}
- {remove \var{x} from set \var{s}; raises \exception{KeyError}
- if not present}
- \lineiii{\var{s}.discard(\var{x})}{}
- {removes \var{x} from set \var{s} if present}
- \lineiii{\var{s}.pop()}{}
- {remove and return an arbitrary element from \var{s}; raises
- \exception{KeyError} if empty}
- \lineiii{\var{s}.clear()}{}
- {remove all elements from set \var{s}}
-\end{tableiii}
-
-Note, the non-operator versions of the \method{update()},
-\method{intersection_update()}, \method{difference_update()}, and
-\method{symmetric_difference_update()} methods will accept any iterable
-as an argument.
-
-
-\section{Mapping Types --- \class{dict} \label{typesmapping}}
-\obindex{mapping}
-\obindex{dictionary}
-
-A \dfn{mapping} object maps immutable values to
-arbitrary objects. Mappings are mutable objects. There is currently
-only one standard mapping type, the \dfn{dictionary}. A dictionary's keys are
-almost arbitrary values. Only values containing lists, dictionaries
-or other mutable types (that are compared by value rather than by
-object identity) may not be used as keys.
-Numeric types used for keys obey the normal rules for numeric
-comparison: if two numbers compare equal (such as \code{1} and
-\code{1.0}) then they can be used interchangeably to index the same
-dictionary entry.
-
-Dictionaries are created by placing a comma-separated list of
-\code{\var{key}: \var{value}} pairs within braces, for example:
-\code{\{'jack': 4098, 'sjoerd': 4127\}} or
-\code{\{4098: 'jack', 4127: 'sjoerd'\}}.
-
-The following operations are defined on mappings (where \var{a} and
-\var{b} are mappings, \var{k} is a key, and \var{v} and \var{x} are
-arbitrary objects):
-\indexiii{operations on}{mapping}{types}
-\indexiii{operations on}{dictionary}{type}
-\stindex{del}
-\bifuncindex{len}
-\withsubitem{(dictionary method)}{
- \ttindex{clear()}
- \ttindex{copy()}
- \ttindex{has_key()}
- \ttindex{fromkeys()}
- \ttindex{items()}
- \ttindex{keys()}
- \ttindex{update()}
- \ttindex{values()}
- \ttindex{get()}
- \ttindex{setdefault()}
- \ttindex{pop()}
- \ttindex{popitem()}
- \ttindex{iteritems()}
- \ttindex{iterkeys()}
- \ttindex{itervalues()}}
-
-\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
- \lineiii{len(\var{a})}{the number of items in \var{a}}{}
- \lineiii{\var{a}[\var{k}]}{the item of \var{a} with key \var{k}}{(1), (10)}
- \lineiii{\var{a}[\var{k}] = \var{v}}
- {set \code{\var{a}[\var{k}]} to \var{v}}
- {}
- \lineiii{del \var{a}[\var{k}]}
- {remove \code{\var{a}[\var{k}]} from \var{a}}
- {(1)}
- \lineiii{\var{a}.clear()}{remove all items from \code{a}}{}
- \lineiii{\var{a}.copy()}{a (shallow) copy of \code{a}}{}
- \lineiii{\var{k} in \var{a}}
- {\code{True} if \var{a} has a key \var{k}, else \code{False}}
- {(2)}
- \lineiii{\var{k} not in \var{a}}
- {Equivalent to \code{not} \var{k} in \var{a}}
- {(2)}
- \lineiii{\var{a}.has_key(\var{k})}
- {Equivalent to \var{k} \code{in} \var{a}, use that form in new code}
- {}
- \lineiii{\var{a}.items()}
- {a copy of \var{a}'s list of (\var{key}, \var{value}) pairs}
- {(3)}
- \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(3)}
- \lineiii{\var{a}.update(\optional{\var{b}})}
- {updates \var{a} with key/value pairs from \var{b}, overwriting
- existing keys, returns \code{None}}
- {(9)}
- \lineiii{\var{a}.fromkeys(\var{seq}\optional{, \var{value}})}
- {Creates a new dictionary with keys from \var{seq} and values set to \var{value}}
- {(7)}
- \lineiii{\var{a}.values()}{a copy of \var{a}'s list of values}{(3)}
- \lineiii{\var{a}.get(\var{k}\optional{, \var{x}})}
- {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}},
- else \var{x}}
- {(4)}
- \lineiii{\var{a}.setdefault(\var{k}\optional{, \var{x}})}
- {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}},
- else \var{x} (also setting it)}
- {(5)}
- \lineiii{\var{a}.pop(\var{k}\optional{, \var{x}})}
- {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}},
- else \var{x} (and remove k)}
- {(8)}
- \lineiii{\var{a}.popitem()}
- {remove and return an arbitrary (\var{key}, \var{value}) pair}
- {(6)}
- \lineiii{\var{a}.iteritems()}
- {return an iterator over (\var{key}, \var{value}) pairs}
- {(2), (3)}
- \lineiii{\var{a}.iterkeys()}
- {return an iterator over the mapping's keys}
- {(2), (3)}
- \lineiii{\var{a}.itervalues()}
- {return an iterator over the mapping's values}
- {(2), (3)}
-\end{tableiii}
-
-\noindent
-Notes:
-\begin{description}
-\item[(1)] Raises a \exception{KeyError} exception if \var{k} is not
-in the map.
-
-\item[(2)] \versionadded{2.2}
-
-\item[(3)] Keys and values are listed in an arbitrary order which is
-non-random, varies across Python implementations, and depends on the
-dictionary's history of insertions and deletions.
-If \method{items()}, \method{keys()}, \method{values()},
-\method{iteritems()}, \method{iterkeys()}, and \method{itervalues()}
-are called with no intervening modifications to the dictionary, the
-lists will directly correspond. This allows the creation of
-\code{(\var{value}, \var{key})} pairs using \function{zip()}:
-\samp{pairs = zip(\var{a}.values(), \var{a}.keys())}. The same
-relationship holds for the \method{iterkeys()} and
-\method{itervalues()} methods: \samp{pairs = zip(\var{a}.itervalues(),
-\var{a}.iterkeys())} provides the same value for \code{pairs}.
-Another way to create the same list is \samp{pairs = [(v, k) for (k,
-v) in \var{a}.iteritems()]}.
-
-\item[(4)] Never raises an exception if \var{k} is not in the map,
-instead it returns \var{x}. \var{x} is optional; when \var{x} is not
-provided and \var{k} is not in the map, \code{None} is returned.
-
-\item[(5)] \function{setdefault()} is like \function{get()}, except
-that if \var{k} is missing, \var{x} is both returned and inserted into
-the dictionary as the value of \var{k}. \var{x} defaults to \code{None}.
-
-\item[(6)] \function{popitem()} is useful to destructively iterate
-over a dictionary, as often used in set algorithms. If the dictionary
-is empty, calling \function{popitem()} raises a \exception{KeyError}.
-
-\item[(7)] \function{fromkeys()} is a class method that returns a
-new dictionary. \var{value} defaults to \code{None}. \versionadded{2.3}
-
-\item[(8)] \function{pop()} raises a \exception{KeyError} when no default
-value is given and the key is not found. \versionadded{2.3}
-
-\item[(9)] \function{update()} accepts either another mapping object
-or an iterable of key/value pairs (as a tuple or other iterable of
-length two). If keyword arguments are specified, the mapping is
-then is updated with those key/value pairs:
-\samp{d.update(red=1, blue=2)}.
-\versionchanged[Allowed the argument to be an iterable of key/value
- pairs and allowed keyword arguments]{2.4}
-
-\item[(10)] If a subclass of dict defines a method \method{__missing__},
-if the key \var{k} is not present, the \var{a}[\var{k}] operation calls
-that method with the key \var{k} as argument. The \var{a}[\var{k}]
-operation then returns or raises whatever is returned or raised by the
-\function{__missing__}(\var{k}) call if the key is not present.
-No other operations or methods invoke \method{__missing__}().
-If \method{__missing__} is not defined, \exception{KeyError} is raised.
-\method{__missing__} must be a method; it cannot be an instance variable.
-For an example, see \module{collections}.\class{defaultdict}.
-\versionadded{2.5}
-
-\end{description}
-
-\section{File Objects
- \label{bltin-file-objects}}
-
-File objects\obindex{file} are implemented using C's \code{stdio}
-package and can be created with the built-in constructor
-\function{file()}\bifuncindex{file} described in section
-\ref{built-in-funcs}, ``Built-in Functions.''\footnote{\function{file()}
-is new in Python 2.2. The older built-in \function{open()} is an
-alias for \function{file()}.} File objects are also returned
-by some other built-in functions and methods, such as
-\function{os.popen()} and \function{os.fdopen()} and the
-\method{makefile()} method of socket objects.
-\refstmodindex{os}
-\refbimodindex{socket}
-
-When a file operation fails for an I/O-related reason, the exception
-\exception{IOError} is raised. This includes situations where the
-operation is not defined for some reason, like \method{seek()} on a tty
-device or writing a file opened for reading.
-
-Files have the following methods:
-
-
-\begin{methoddesc}[file]{close}{}
- Close the file. A closed file cannot be read or written any more.
- Any operation which requires that the file be open will raise a
- \exception{ValueError} after the file has been closed. Calling
- \method{close()} more than once is allowed.
-
- As of Python 2.5, you can avoid having to call this method explicitly
- if you use the \keyword{with} statement. For example, the following
- code will automatically close \code{f} when the \keyword{with} block
- is exited:
-
-\begin{verbatim}
-from __future__ import with_statement
-
-with open("hello.txt") as f:
- for line in f:
- print line
-\end{verbatim}
-
- In older versions of Python, you would have needed to do this to get
- the same effect:
-
-\begin{verbatim}
-f = open("hello.txt")
-try:
- for line in f:
- print line
-finally:
- f.close()
-\end{verbatim}
-
- \note{Not all ``file-like'' types in Python support use as a context
- manager for the \keyword{with} statement. If your code is intended to
- work with any file-like object, you can use the \function{closing()}
- function in the \module{contextlib} module instead of using the object
- directly. See section~\ref{context-closing} for details.}
-
-\end{methoddesc}
-
-\begin{methoddesc}[file]{flush}{}
- Flush the internal buffer, like \code{stdio}'s
- \cfunction{fflush()}. This may be a no-op on some file-like
- objects.
-\end{methoddesc}
-
-\begin{methoddesc}[file]{fileno}{}
- \index{file descriptor}
- \index{descriptor, file}
- Return the integer ``file descriptor'' that is used by the
- underlying implementation to request I/O operations from the
- operating system. This can be useful for other, lower level
- interfaces that use file descriptors, such as the
- \refmodule{fcntl}\refbimodindex{fcntl} module or
- \function{os.read()} and friends. \note{File-like objects
- which do not have a real file descriptor should \emph{not} provide
- this method!}
-\end{methoddesc}
-
-\begin{methoddesc}[file]{isatty}{}
- Return \code{True} if the file is connected to a tty(-like) device, else
- \code{False}. \note{If a file-like object is not associated
- with a real file, this method should \emph{not} be implemented.}
-\end{methoddesc}
-
-\begin{methoddesc}[file]{__next__}{}
-A file object is its own iterator, for example \code{iter(\var{f})} returns
-\var{f} (unless \var{f} is closed). When a file is used as an
-iterator, typically in a \keyword{for} loop (for example,
-\code{for line in f: print line}), the \method{__next__()} method is
-called repeatedly. This method returns the next input line, or raises
-\exception{StopIteration} when \EOF{} is hit when the file is open for
-reading (behavior is undefined when the file is open for writing). In
-order to make a \keyword{for} loop the most efficient way of looping
-over the lines of a file (a very common operation), the
-\method{__next__()} method uses a hidden read-ahead buffer. As a
-consequence of using a read-ahead buffer, combining \method{__next__()}
-with other file methods (like \method{readline()}) does not work
-right. However, using \method{seek()} to reposition the file to an
-absolute position will flush the read-ahead buffer.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[file]{read}{\optional{size}}
- Read at most \var{size} bytes from the file (less if the read hits
- \EOF{} before obtaining \var{size} bytes). If the \var{size}
- argument is negative or omitted, read all data until \EOF{} is
- reached. The bytes are returned as a string object. An empty
- string is returned when \EOF{} is encountered immediately. (For
- certain files, like ttys, it makes sense to continue reading after
- an \EOF{} is hit.) Note that this method may call the underlying
- C function \cfunction{fread()} more than once in an effort to
- acquire as close to \var{size} bytes as possible. Also note that
- when in non-blocking mode, less data than what was requested may
- be returned, even if no \var{size} parameter was given.
-\end{methoddesc}
-
-\begin{methoddesc}[file]{readline}{\optional{size}}
- Read one entire line from the file. A trailing newline character is
- kept in the string (but may be absent when a file ends with an
- incomplete line).\footnote{
- The advantage of leaving the newline on is that
- returning an empty string is then an unambiguous \EOF{}
- indication. It is also possible (in cases where it might
- matter, for example, if you
- want to make an exact copy of a file while scanning its lines)
- to tell whether the last line of a file ended in a newline
- or not (yes this happens!).
- } If the \var{size} argument is present and
- non-negative, it is a maximum byte count (including the trailing
- newline) and an incomplete line may be returned.
- An empty string is returned \emph{only} when \EOF{} is encountered
- immediately. \note{Unlike \code{stdio}'s \cfunction{fgets()}, the
- returned string contains null characters (\code{'\e 0'}) if they
- occurred in the input.}
-\end{methoddesc}
-
-\begin{methoddesc}[file]{readlines}{\optional{sizehint}}
- Read until \EOF{} using \method{readline()} and return a list containing
- the lines thus read. If the optional \var{sizehint} argument is
- present, instead of reading up to \EOF, whole lines totalling
- approximately \var{sizehint} bytes (possibly after rounding up to an
- internal buffer size) are read. Objects implementing a file-like
- interface may choose to ignore \var{sizehint} if it cannot be
- implemented, or cannot be implemented efficiently.
-\end{methoddesc}
-
-\begin{methoddesc}[file]{seek}{offset\optional{, whence}}
- Set the file's current position, like \code{stdio}'s \cfunction{fseek()}.
- The \var{whence} argument is optional and defaults to
- \code{os.SEEK_SET} or \code{0}
- (absolute file positioning); other values are \code{os.SEEK_CUR} or \code{1}
- (seek
- relative to the current position) and \code{os.SEEK_END} or \code{2}
- (seek relative to the
- file's end). There is no return value. Note that if the file is
- opened for appending (mode \code{'a'} or \code{'a+'}), any
- \method{seek()} operations will be undone at the next write. If the
- file is only opened for writing in append mode (mode \code{'a'}),
- this method is essentially a no-op, but it remains useful for files
- opened in append mode with reading enabled (mode \code{'a+'}). If the
- file is opened in text mode (without \code{'b'}), only offsets returned
- by \method{tell()} are legal. Use of other offsets causes undefined
- behavior.
-
- Note that not all file objects are seekable.
- \versionchanged{Passing float values as offset has been deprecated}[2.6]
-\end{methoddesc}
-
-\begin{methoddesc}[file]{tell}{}
- Return the file's current position, like \code{stdio}'s
- \cfunction{ftell()}.
-
- \note{On Windows, \method{tell()} can return illegal values (after an
- \cfunction{fgets()}) when reading files with \UNIX{}-style line-endings.
- Use binary mode (\code{'rb'}) to circumvent this problem.}
-\end{methoddesc}
-
-\begin{methoddesc}[file]{truncate}{\optional{size}}
- Truncate the file's size. If the optional \var{size} argument is
- present, the file is truncated to (at most) that size. The size
- defaults to the current position. The current file position is
- not changed. Note that if a specified size exceeds the file's
- current size, the result is platform-dependent: possibilities
- include that the file may remain unchanged, increase to the specified
- size as if zero-filled, or increase to the specified size with
- undefined new content.
- Availability: Windows, many \UNIX{} variants.
-\end{methoddesc}
-
-\begin{methoddesc}[file]{write}{str}
- Write a string to the file. There is no return value. Due to
- buffering, the string may not actually show up in the file until
- the \method{flush()} or \method{close()} method is called.
-\end{methoddesc}
-
-\begin{methoddesc}[file]{writelines}{sequence}
- Write a sequence of strings to the file. The sequence can be any
- iterable object producing strings, typically a list of strings.
- There is no return value.
- (The name is intended to match \method{readlines()};
- \method{writelines()} does not add line separators.)
-\end{methoddesc}
-
-
-Files support the iterator protocol. Each iteration returns the same
-result as \code{\var{file}.readline()}, and iteration ends when the
-\method{readline()} method returns an empty string.
-
-
-File objects also offer a number of other interesting attributes.
-These are not required for file-like objects, but should be
-implemented if they make sense for the particular object.
-
-\begin{memberdesc}[file]{closed}
-bool indicating the current state of the file object. This is a
-read-only attribute; the \method{close()} method changes the value.
-It may not be available on all file-like objects.
-\end{memberdesc}
-
-\begin{memberdesc}[file]{encoding}
-The encoding that this file uses. When Unicode strings are written
-to a file, they will be converted to byte strings using this encoding.
-In addition, when the file is connected to a terminal, the attribute
-gives the encoding that the terminal is likely to use (that
-information might be incorrect if the user has misconfigured the
-terminal). The attribute is read-only and may not be present on
-all file-like objects. It may also be \code{None}, in which case
-the file uses the system default encoding for converting Unicode
-strings.
-
-\versionadded{2.3}
-\end{memberdesc}
-
-\begin{memberdesc}[file]{mode}
-The I/O mode for the file. If the file was created using the
-\function{open()} built-in function, this will be the value of the
-\var{mode} parameter. This is a read-only attribute and may not be
-present on all file-like objects.
-\end{memberdesc}
-
-\begin{memberdesc}[file]{name}
-If the file object was created using \function{open()}, the name of
-the file. Otherwise, some string that indicates the source of the
-file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only
-attribute and may not be present on all file-like objects.
-\end{memberdesc}
-
-\begin{memberdesc}[file]{newlines}
-If Python was built with the \longprogramopt{with-universal-newlines}
-option to \program{configure} (the default) this read-only attribute
-exists, and for files opened in
-universal newline read mode it keeps track of the types of newlines
-encountered while reading the file. The values it can take are
-\code{'\e r'}, \code{'\e n'}, \code{'\e r\e n'}, \code{None} (unknown,
-no newlines read yet) or a tuple containing all the newline
-types seen, to indicate that multiple
-newline conventions were encountered. For files not opened in universal
-newline read mode the value of this attribute will be \code{None}.
-\end{memberdesc}
-
-\begin{memberdesc}[file]{softspace}
-Boolean that indicates whether a space character needs to be printed
-before another value when using the \keyword{print} statement.
-Classes that are trying to simulate a file object should also have a
-writable \member{softspace} attribute, which should be initialized to
-zero. This will be automatic for most classes implemented in Python
-(care may be needed for objects that override attribute access); types
-implemented in C will have to provide a writable
-\member{softspace} attribute.
-\note{This attribute is not used to control the
-\keyword{print} statement, but to allow the implementation of
-\keyword{print} to keep track of its internal state.}
-\end{memberdesc}
-
-
-\section{Context Manager Types \label{typecontextmanager}}
-
-\versionadded{2.5}
-\index{context manager}
-\index{context management protocol}
-\index{protocol!context management}
-
-Python's \keyword{with} statement supports the concept of a runtime
-context defined by a context manager. This is implemented using
-two separate methods that allow user-defined classes to define
-a runtime context that is entered before the statement body is
-executed and exited when the statement ends.
-
-The \dfn{context management protocol} consists of a pair of
-methods that need to be provided for a context manager object to
-define a runtime context:
-
-\begin{methoddesc}[context manager]{__enter__}{}
- Enter the runtime context and return either this object or another
- object related to the runtime context. The value returned by this
- method is bound to the identifier in the \keyword{as} clause of
- \keyword{with} statements using this context manager.
-
- An example of a context manager that returns itself is a file object.
- File objects return themselves from __enter__() to allow
- \function{open()} to be used as the context expression in a
- \keyword{with} statement.
-
- An example of a context manager that returns a related
- object is the one returned by \code{decimal.Context.get_manager()}.
- These managers set the active decimal context to a copy of the
- original decimal context and then return the copy. This allows
- changes to be made to the current decimal context in the body of
- the \keyword{with} statement without affecting code outside
- the \keyword{with} statement.
-\end{methoddesc}
-
-\begin{methoddesc}[context manager]{__exit__}{exc_type, exc_val, exc_tb}
- Exit the runtime context and return a Boolean flag indicating if any
- expection that occurred should be suppressed. If an exception
- occurred while executing the body of the \keyword{with} statement, the
- arguments contain the exception type, value and traceback information.
- Otherwise, all three arguments are \code{None}.
-
- Returning a true value from this method will cause the \keyword{with}
- statement to suppress the exception and continue execution with the
- statement immediately following the \keyword{with} statement. Otherwise
- the exception continues propagating after this method has finished
- executing. Exceptions that occur during execution of this method will
- replace any exception that occurred in the body of the \keyword{with}
- statement.
-
- The exception passed in should never be reraised explicitly - instead,
- this method should return a false value to indicate that the method
- completed successfully and does not want to suppress the raised
- exception. This allows context management code (such as
- \code{contextlib.nested}) to easily detect whether or not an
- \method{__exit__()} method has actually failed.
-\end{methoddesc}
-
-Python defines several context managers to support easy thread
-synchronisation, prompt closure of files or other objects, and
-simpler manipulation of the active decimal arithmetic
-context. The specific types are not treated specially beyond
-their implementation of the context management protocol.
-
-Python's generators and the \code{contextlib.contextfactory} decorator
-provide a convenient way to implement these protocols. If a generator
-function is decorated with the \code{contextlib.contextfactory}
-decorator, it will return a context manager implementing the necessary
-\method{__enter__()} and \method{__exit__()} methods, rather than the
-iterator produced by an undecorated generator function.
-
-Note that there is no specific slot for any of these methods in the
-type structure for Python objects in the Python/C API. Extension
-types wanting to define these methods must provide them as a normal
-Python accessible method. Compared to the overhead of setting up the
-runtime context, the overhead of a single class dictionary lookup
-is negligible.
-
-
-\section{Other Built-in Types \label{typesother}}
-
-The interpreter supports several other kinds of objects.
-Most of these support only one or two operations.
-
-
-\subsection{Modules \label{typesmodules}}
-
-The only special operation on a module is attribute access:
-\code{\var{m}.\var{name}}, where \var{m} is a module and \var{name}
-accesses a name defined in \var{m}'s symbol table. Module attributes
-can be assigned to. (Note that the \keyword{import} statement is not,
-strictly speaking, an operation on a module object; \code{import
-\var{foo}} does not require a module object named \var{foo} to exist,
-rather it requires an (external) \emph{definition} for a module named
-\var{foo} somewhere.)
-
-A special member of every module is \member{__dict__}.
-This is the dictionary containing the module's symbol table.
-Modifying this dictionary will actually change the module's symbol
-table, but direct assignment to the \member{__dict__} attribute is not
-possible (you can write \code{\var{m}.__dict__['a'] = 1}, which
-defines \code{\var{m}.a} to be \code{1}, but you can't write
-\code{\var{m}.__dict__ = \{\}}). Modifying \member{__dict__} directly
-is not recommended.
-
-Modules built into the interpreter are written like this:
-\code{<module 'sys' (built-in)>}. If loaded from a file, they are
-written as \code{<module 'os' from
-'/usr/local/lib/python\shortversion/os.pyc'>}.
-
-
-\subsection{Classes and Class Instances \label{typesobjects}}
-\nodename{Classes and Instances}
-
-See chapters 3 and 7 of the \citetitle[../ref/ref.html]{Python
-Reference Manual} for these.
-
-
-\subsection{Functions \label{typesfunctions}}
-
-Function objects are created by function definitions. The only
-operation on a function object is to call it:
-\code{\var{func}(\var{argument-list})}.
-
-There are really two flavors of function objects: built-in functions
-and user-defined functions. Both support the same operation (to call
-the function), but the implementation is different, hence the
-different object types.
-
-See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
-information.
-
-\subsection{Methods \label{typesmethods}}
-\obindex{method}
-
-Methods are functions that are called using the attribute notation.
-There are two flavors: built-in methods (such as \method{append()} on
-lists) and class instance methods. Built-in methods are described
-with the types that support them.
-
-The implementation adds two special read-only attributes to class
-instance methods: \code{\var{m}.im_self} is the object on which the
-method operates, and \code{\var{m}.im_func} is the function
-implementing the method. Calling \code{\var{m}(\var{arg-1},
-\var{arg-2}, \textrm{\ldots}, \var{arg-n})} is completely equivalent to
-calling \code{\var{m}.im_func(\var{m}.im_self, \var{arg-1},
-\var{arg-2}, \textrm{\ldots}, \var{arg-n})}.
-
-Class instance methods are either \emph{bound} or \emph{unbound},
-referring to whether the method was accessed through an instance or a
-class, respectively. When a method is unbound, its \code{im_self}
-attribute will be \code{None} and if called, an explicit \code{self}
-object must be passed as the first argument. In this case,
-\code{self} must be an instance of the unbound method's class (or a
-subclass of that class), otherwise a \exception{TypeError} is raised.
-
-Like function objects, methods objects support getting
-arbitrary attributes. However, since method attributes are actually
-stored on the underlying function object (\code{meth.im_func}),
-setting method attributes on either bound or unbound methods is
-disallowed. Attempting to set a method attribute results in a
-\exception{TypeError} being raised. In order to set a method attribute,
-you need to explicitly set it on the underlying function object:
-
-\begin{verbatim}
-class C:
- def method(self):
- pass
-
-c = C()
-c.method.im_func.whoami = 'my name is c'
-\end{verbatim}
-
-See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
-information.
-
-
-\subsection{Code Objects \label{bltin-code-objects}}
-\obindex{code}
-
-Code objects are used by the implementation to represent
-``pseudo-compiled'' executable Python code such as a function body.
-They differ from function objects because they don't contain a
-reference to their global execution environment. Code objects are
-returned by the built-in \function{compile()} function and can be
-extracted from function objects through their \member{__code__}
-attribute.
-\bifuncindex{compile}
-\withsubitem{(function object attribute)}{\ttindex{__code__}}
-
-A code object can be executed or evaluated by passing it (instead of a
-source string) to the \function{exec()} or \function{eval()}
-built-in functions.
-\bifuncindex{exec}
-\bifuncindex{eval}
-
-See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
-information.
-
-
-\subsection{Type Objects \label{bltin-type-objects}}
-
-Type objects represent the various object types. An object's type is
-accessed by the built-in function \function{type()}. There are no special
-operations on types. The standard module \refmodule{types} defines names
-for all standard built-in types.
-\bifuncindex{type}
-\refstmodindex{types}
-
-Types are written like this: \code{<type 'int'>}.
-
-
-\subsection{The Null Object \label{bltin-null-object}}
-
-This object is returned by functions that don't explicitly return a
-value. It supports no special operations. There is exactly one null
-object, named \code{None} (a built-in name).
-
-It is written as \code{None}.
-
-
-\subsection{The Ellipsis Object \label{bltin-ellipsis-object}}
-
-This object is mostly used by extended slice notation (see the
-\citetitle[../ref/ref.html]{Python Reference Manual}). It supports no
-special operations. There is exactly one ellipsis object, named
-\constant{Ellipsis} (a built-in name).
-
-It is written as \code{Ellipsis} or \code{...}.
-
-\subsection{Boolean Values}
-
-Boolean values are the two constant objects \code{False} and
-\code{True}. They are used to represent truth values (although other
-values can also be considered false or true). In numeric contexts
-(for example when used as the argument to an arithmetic operator),
-they behave like the integers 0 and 1, respectively. The built-in
-function \function{bool()} can be used to cast any value to a Boolean,
-if the value can be interpreted as a truth value (see section Truth
-Value Testing above).
-
-They are written as \code{False} and \code{True}, respectively.
-\index{False}
-\index{True}
-\indexii{Boolean}{values}
-
-
-\subsection{Internal Objects \label{typesinternal}}
-
-See the \citetitle[../ref/ref.html]{Python Reference Manual} for this
-information. It describes stack frame objects, traceback objects, and
-slice objects.
-
-
-\section{Special Attributes \label{specialattrs}}
-
-The implementation adds a few special read-only attributes to several
-object types, where they are relevant. Some of these are not reported
-by the \function{dir()} built-in function.
-
-\begin{memberdesc}[object]{__dict__}
-A dictionary or other mapping object used to store an
-object's (writable) attributes.
-\end{memberdesc}
-
-\begin{memberdesc}[instance]{__class__}
-The class to which a class instance belongs.
-\end{memberdesc}
-
-\begin{memberdesc}[class]{__bases__}
-The tuple of base classes of a class object. If there are no base
-classes, this will be an empty tuple.
-\end{memberdesc}
-
-\begin{memberdesc}[class]{__name__}
-The name of the class or type.
-\end{memberdesc}
diff --git a/Doc/lib/libstring.tex b/Doc/lib/libstring.tex
deleted file mode 100644
index 9948cb7..0000000
--- a/Doc/lib/libstring.tex
+++ /dev/null
@@ -1,425 +0,0 @@
-\section{\module{string} ---
- Common string operations}
-
-\declaremodule{standard}{string}
-\modulesynopsis{Common string operations.}
-
-The \module{string} module contains a number of useful constants and classes,
-as well as some deprecated legacy functions that are also available as methods
-on strings. See the module \refmodule{re}\refstmodindex{re} for string
-functions based on regular expressions.
-
-\subsection{String constants}
-
-The constants defined in this module are:
-
-\begin{datadesc}{ascii\_letters}
- The concatenation of the \constant{ascii_lowercase} and
- \constant{ascii_uppercase} constants described below. This value is
- not locale-dependent.
-\end{datadesc}
-
-\begin{datadesc}{ascii\_lowercase}
- The lowercase letters \code{'abcdefghijklmnopqrstuvwxyz'}. This
- value is not locale-dependent and will not change.
-\end{datadesc}
-
-\begin{datadesc}{ascii\_uppercase}
- The uppercase letters \code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. This
- value is not locale-dependent and will not change.
-\end{datadesc}
-
-\begin{datadesc}{digits}
- The string \code{'0123456789'}.
-\end{datadesc}
-
-\begin{datadesc}{hexdigits}
- The string \code{'0123456789abcdefABCDEF'}.
-\end{datadesc}
-
-\begin{datadesc}{octdigits}
- The string \code{'01234567'}.
-\end{datadesc}
-
-\begin{datadesc}{punctuation}
- String of \ASCII{} characters which are considered punctuation
- characters in the \samp{C} locale.
-\end{datadesc}
-
-\begin{datadesc}{printable}
- String of characters which are considered printable. This is a
- combination of \constant{digits}, \constant{letters},
- \constant{punctuation}, and \constant{whitespace}.
-\end{datadesc}
-
-\begin{datadesc}{whitespace}
- A string containing all characters that are considered whitespace.
- On most systems this includes the characters space, tab, linefeed,
- return, formfeed, and vertical tab. Do not change its definition ---
- the effect on the routines \function{strip()} and \function{split()}
- is undefined.
-\end{datadesc}
-
-\subsection{Template strings}
-
-Templates provide simpler string substitutions as described in \pep{292}.
-Instead of the normal \samp{\%}-based substitutions, Templates support
-\samp{\$}-based substitutions, using the following rules:
-
-\begin{itemize}
-\item \samp{\$\$} is an escape; it is replaced with a single \samp{\$}.
-
-\item \samp{\$identifier} names a substitution placeholder matching a mapping
- key of "identifier". By default, "identifier" must spell a Python
- identifier. The first non-identifier character after the \samp{\$}
- character terminates this placeholder specification.
-
-\item \samp{\$\{identifier\}} is equivalent to \samp{\$identifier}. It is
- required when valid identifier characters follow the placeholder but are
- not part of the placeholder, such as "\$\{noun\}ification".
-\end{itemize}
-
-Any other appearance of \samp{\$} in the string will result in a
-\exception{ValueError} being raised.
-
-\versionadded{2.4}
-
-The \module{string} module provides a \class{Template} class that implements
-these rules. The methods of \class{Template} are:
-
-\begin{classdesc}{Template}{template}
-The constructor takes a single argument which is the template string.
-\end{classdesc}
-
-\begin{methoddesc}[Template]{substitute}{mapping\optional{, **kws}}
-Performs the template substitution, returning a new string. \var{mapping} is
-any dictionary-like object with keys that match the placeholders in the
-template. Alternatively, you can provide keyword arguments, where the
-keywords are the placeholders. When both \var{mapping} and \var{kws} are
-given and there are duplicates, the placeholders from \var{kws} take
-precedence.
-\end{methoddesc}
-
-\begin{methoddesc}[Template]{safe_substitute}{mapping\optional{, **kws}}
-Like \method{substitute()}, except that if placeholders are missing from
-\var{mapping} and \var{kws}, instead of raising a \exception{KeyError}
-exception, the original placeholder will appear in the resulting string
-intact. Also, unlike with \method{substitute()}, any other appearances of the
-\samp{\$} will simply return \samp{\$} instead of raising
-\exception{ValueError}.
-
-While other exceptions may still occur, this method is called ``safe'' because
-substitutions always tries to return a usable string instead of raising an
-exception. In another sense, \method{safe_substitute()} may be anything other
-than safe, since it will silently ignore malformed templates containing
-dangling delimiters, unmatched braces, or placeholders that are not valid
-Python identifiers.
-\end{methoddesc}
-
-\class{Template} instances also provide one public data attribute:
-
-\begin{memberdesc}[string]{template}
-This is the object passed to the constructor's \var{template} argument. In
-general, you shouldn't change it, but read-only access is not enforced.
-\end{memberdesc}
-
-Here is an example of how to use a Template:
-
-\begin{verbatim}
->>> from string import Template
->>> s = Template('$who likes $what')
->>> s.substitute(who='tim', what='kung pao')
-'tim likes kung pao'
->>> d = dict(who='tim')
->>> Template('Give $who $100').substitute(d)
-Traceback (most recent call last):
-[...]
-ValueError: Invalid placeholder in string: line 1, col 10
->>> Template('$who likes $what').substitute(d)
-Traceback (most recent call last):
-[...]
-KeyError: 'what'
->>> Template('$who likes $what').safe_substitute(d)
-'tim likes $what'
-\end{verbatim}
-
-Advanced usage: you can derive subclasses of \class{Template} to customize the
-placeholder syntax, delimiter character, or the entire regular expression used
-to parse template strings. To do this, you can override these class
-attributes:
-
-\begin{itemize}
-\item \var{delimiter} -- This is the literal string describing a placeholder
- introducing delimiter. The default value \samp{\$}. Note that this
- should \emph{not} be a regular expression, as the implementation will
- call \method{re.escape()} on this string as needed.
-\item \var{idpattern} -- This is the regular expression describing the pattern
- for non-braced placeholders (the braces will be added automatically as
- appropriate). The default value is the regular expression
- \samp{[_a-z][_a-z0-9]*}.
-\end{itemize}
-
-Alternatively, you can provide the entire regular expression pattern by
-overriding the class attribute \var{pattern}. If you do this, the value must
-be a regular expression object with four named capturing groups. The
-capturing groups correspond to the rules given above, along with the invalid
-placeholder rule:
-
-\begin{itemize}
-\item \var{escaped} -- This group matches the escape sequence,
- e.g. \samp{\$\$}, in the default pattern.
-\item \var{named} -- This group matches the unbraced placeholder name; it
- should not include the delimiter in capturing group.
-\item \var{braced} -- This group matches the brace enclosed placeholder name;
- it should not include either the delimiter or braces in the capturing
- group.
-\item \var{invalid} -- This group matches any other delimiter pattern (usually
- a single delimiter), and it should appear last in the regular
- expression.
-\end{itemize}
-
-\subsection{String functions}
-
-The following functions are available to operate on string and Unicode
-objects. They are not available as string methods.
-
-\begin{funcdesc}{capwords}{s}
- Split the argument into words using \function{split()}, capitalize
- each word using \function{capitalize()}, and join the capitalized
- words using \function{join()}. Note that this replaces runs of
- whitespace characters by a single space, and removes leading and
- trailing whitespace.
-\end{funcdesc}
-
-\begin{funcdesc}{maketrans}{from, to}
- Return a translation table suitable for passing to
- \function{translate()}, that will map
- each character in \var{from} into the character at the same position
- in \var{to}; \var{from} and \var{to} must have the same length.
-
- \warning{Don't use strings derived from \constant{lowercase}
- and \constant{uppercase} as arguments; in some locales, these don't have
- the same length. For case conversions, always use
- \function{lower()} and \function{upper()}.}
-\end{funcdesc}
-
-\subsection{Deprecated string functions}
-
-The following list of functions are also defined as methods of string and
-Unicode objects; see ``String Methods'' (section
-\ref{string-methods}) for more information on those. You should consider
-these functions as deprecated, although they will not be removed until Python
-3.0. The functions defined in this module are:
-
-\begin{funcdesc}{atof}{s}
- \deprecated{2.0}{Use the \function{float()} built-in function.}
- Convert a string to a floating point number. The string must have
- the standard syntax for a floating point literal in Python,
- optionally preceded by a sign (\samp{+} or \samp{-}). Note that
- this behaves identical to the built-in function
- \function{float()}\bifuncindex{float} when passed a string.
-
- \note{When passing in a string, values for NaN\index{NaN}
- and Infinity\index{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.}
-\end{funcdesc}
-
-\begin{funcdesc}{atoi}{s\optional{, base}}
- \deprecated{2.0}{Use the \function{int()} built-in function.}
- Convert string \var{s} to an integer in the given \var{base}. The
- string must consist of one or more digits, optionally preceded by a
- sign (\samp{+} or \samp{-}). The \var{base} defaults to 10. If it
- is 0, a default base is chosen depending on the leading characters
- of the string (after stripping the sign): \samp{0x} or \samp{0X}
- means 16, \samp{0} means 8, anything else means 10. If \var{base}
- is 16, a leading \samp{0x} or \samp{0X} is always accepted, though
- not required. This behaves identically to the built-in function
- \function{int()} when passed a string. (Also note: for a more
- flexible interpretation of numeric literals, use the built-in
- function \function{eval()}\bifuncindex{eval}.)
-\end{funcdesc}
-
-\begin{funcdesc}{atol}{s\optional{, base}}
- \deprecated{2.0}{Use the \function{long()} built-in function.}
- Convert string \var{s} to a long integer in the given \var{base}.
- The string must consist of one or more digits, optionally preceded
- by a sign (\samp{+} or \samp{-}). The \var{base} argument has the
- same meaning as for \function{atoi()}. A trailing \samp{l} or
- \samp{L} is not allowed, except if the base is 0. Note that when
- invoked without \var{base} or with \var{base} set to 10, this
- behaves identical to the built-in function
- \function{long()}\bifuncindex{long} when passed a string.
-\end{funcdesc}
-
-\begin{funcdesc}{capitalize}{word}
- Return a copy of \var{word} with only its first character capitalized.
-\end{funcdesc}
-
-\begin{funcdesc}{expandtabs}{s\optional{, tabsize}}
- Expand tabs in a string replacing them by one or more spaces,
- depending on the current column and the given tab size. The column
- number is reset to zero after each newline occurring in the string.
- This doesn't understand other non-printing characters or escape
- sequences. The tab size defaults to 8.
-\end{funcdesc}
-
-\begin{funcdesc}{find}{s, sub\optional{, start\optional{,end}}}
- Return the lowest index in \var{s} where the substring \var{sub} is
- found such that \var{sub} is wholly contained in
- \code{\var{s}[\var{start}:\var{end}]}. Return \code{-1} on failure.
- Defaults for \var{start} and \var{end} and interpretation of
- negative values is the same as for slices.
-\end{funcdesc}
-
-\begin{funcdesc}{rfind}{s, sub\optional{, start\optional{, end}}}
- Like \function{find()} but find the highest index.
-\end{funcdesc}
-
-\begin{funcdesc}{index}{s, sub\optional{, start\optional{, end}}}
- Like \function{find()} but raise \exception{ValueError} when the
- substring is not found.
-\end{funcdesc}
-
-\begin{funcdesc}{rindex}{s, sub\optional{, start\optional{, end}}}
- Like \function{rfind()} but raise \exception{ValueError} when the
- substring is not found.
-\end{funcdesc}
-
-\begin{funcdesc}{count}{s, sub\optional{, start\optional{, end}}}
- Return the number of (non-overlapping) occurrences of substring
- \var{sub} in string \code{\var{s}[\var{start}:\var{end}]}.
- Defaults for \var{start} and \var{end} and interpretation of
- negative values are the same as for slices.
-\end{funcdesc}
-
-\begin{funcdesc}{lower}{s}
- Return a copy of \var{s}, but with upper case letters converted to
- lower case.
-\end{funcdesc}
-
-\begin{funcdesc}{split}{s\optional{, sep\optional{, maxsplit}}}
- Return a list of the words of the string \var{s}. If the optional
- second argument \var{sep} is absent or \code{None}, the words are
- separated by arbitrary strings of whitespace characters (space, tab,
- newline, return, formfeed). If the second argument \var{sep} is
- present and not \code{None}, it specifies a string to be used as the
- word separator. The returned list will then have one more item
- than the number of non-overlapping occurrences of the separator in
- the string. The optional third argument \var{maxsplit} defaults to
- 0. If it is nonzero, at most \var{maxsplit} number of splits occur,
- and the remainder of the string is returned as the final element of
- the list (thus, the list will have at most \code{\var{maxsplit}+1}
- elements).
-
- The behavior of split on an empty string depends on the value of \var{sep}.
- If \var{sep} is not specified, or specified as \code{None}, the result will
- be an empty list. If \var{sep} is specified as any string, the result will
- be a list containing one element which is an empty string.
-\end{funcdesc}
-
-\begin{funcdesc}{rsplit}{s\optional{, sep\optional{, maxsplit}}}
- Return a list of the words of the string \var{s}, scanning \var{s}
- from the end. To all intents and purposes, the resulting list of
- words is the same as returned by \function{split()}, except when the
- optional third argument \var{maxsplit} is explicitly specified and
- nonzero. When \var{maxsplit} is nonzero, at most \var{maxsplit}
- number of splits -- the \emph{rightmost} ones -- occur, and the remainder
- of the string is returned as the first element of the list (thus, the
- list will have at most \code{\var{maxsplit}+1} elements).
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{splitfields}{s\optional{, sep\optional{, maxsplit}}}
- This function behaves identically to \function{split()}. (In the
- past, \function{split()} was only used with one argument, while
- \function{splitfields()} was only used with two arguments.)
-\end{funcdesc}
-
-\begin{funcdesc}{join}{words\optional{, sep}}
- Concatenate a list or tuple of words with intervening occurrences of
- \var{sep}. The default value for \var{sep} is a single space
- character. It is always true that
- \samp{string.join(string.split(\var{s}, \var{sep}), \var{sep})}
- equals \var{s}.
-\end{funcdesc}
-
-\begin{funcdesc}{joinfields}{words\optional{, sep}}
- This function behaves identically to \function{join()}. (In the past,
- \function{join()} was only used with one argument, while
- \function{joinfields()} was only used with two arguments.)
- Note that there is no \method{joinfields()} method on string
- objects; use the \method{join()} method instead.
-\end{funcdesc}
-
-\begin{funcdesc}{lstrip}{s\optional{, chars}}
-Return a copy of the string with leading characters removed. If
-\var{chars} is omitted or \code{None}, whitespace characters are
-removed. If given and not \code{None}, \var{chars} must be a string;
-the characters in the string will be stripped from the beginning of
-the string this method is called on.
-\versionchanged[The \var{chars} parameter was added. The \var{chars}
-parameter cannot be passed in earlier 2.2 versions]{2.2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{rstrip}{s\optional{, chars}}
-Return a copy of the string with trailing characters removed. If
-\var{chars} is omitted or \code{None}, whitespace characters are
-removed. If given and not \code{None}, \var{chars} must be a string;
-the characters in the string will be stripped from the end of the
-string this method is called on.
-\versionchanged[The \var{chars} parameter was added. The \var{chars}
-parameter cannot be passed in earlier 2.2 versions]{2.2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{strip}{s\optional{, chars}}
-Return a copy of the string with leading and trailing characters
-removed. If \var{chars} is omitted or \code{None}, whitespace
-characters are removed. If given and not \code{None}, \var{chars}
-must be a string; the characters in the string will be stripped from
-the both ends of the string this method is called on.
-\versionchanged[The \var{chars} parameter was added. The \var{chars}
-parameter cannot be passed in earlier 2.2 versions]{2.2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{swapcase}{s}
- Return a copy of \var{s}, but with lower case letters
- converted to upper case and vice versa.
-\end{funcdesc}
-
-\begin{funcdesc}{translate}{s, table\optional{, deletechars}}
- Delete all characters from \var{s} that are in \var{deletechars} (if
- present), and then translate the characters using \var{table}, which
- must be a 256-character string giving the translation for each
- character value, indexed by its ordinal. If \var{table} is \code{None},
- then only the character deletion step is performed.
-\end{funcdesc}
-
-\begin{funcdesc}{upper}{s}
- Return a copy of \var{s}, but with lower case letters converted to
- upper case.
-\end{funcdesc}
-
-\begin{funcdesc}{ljust}{s, width}
-\funcline{rjust}{s, width}
-\funcline{center}{s, width}
- These functions respectively left-justify, right-justify and center
- a string in a field of given width. They return a string that is at
- least \var{width} characters wide, created by padding the string
- \var{s} with spaces until the given width on the right, left or both
- sides. The string is never truncated.
-\end{funcdesc}
-
-\begin{funcdesc}{zfill}{s, width}
- Pad a numeric string on the left with zero digits until the given
- width is reached. Strings starting with a sign are handled
- correctly.
-\end{funcdesc}
-
-\begin{funcdesc}{replace}{str, old, new\optional{, maxreplace}}
- Return a copy of string \var{str} with all occurrences of substring
- \var{old} replaced by \var{new}. If the optional argument
- \var{maxreplace} is given, the first \var{maxreplace} occurrences are
- replaced.
-\end{funcdesc}
diff --git a/Doc/lib/libstringio.tex b/Doc/lib/libstringio.tex
deleted file mode 100644
index 73ff0e4..0000000
--- a/Doc/lib/libstringio.tex
+++ /dev/null
@@ -1,125 +0,0 @@
-\section{\module{StringIO} ---
- Read and write strings as files}
-
-\declaremodule{standard}{StringIO}
-\modulesynopsis{Read and write strings as if they were files.}
-
-
-This module implements a file-like class, \class{StringIO},
-that reads and writes a string buffer (also known as \emph{memory
-files}). See the description of file objects for operations (section
-\ref{bltin-file-objects}).
-
-\begin{classdesc}{StringIO}{\optional{buffer}}
-When a \class{StringIO} object is created, it can be initialized
-to an existing string by passing the string to the constructor.
-If no string is given, the \class{StringIO} will start empty.
-In both cases, the initial file position starts at zero.
-
-The \class{StringIO} object can accept either Unicode or 8-bit
-strings, but mixing the two may take some care. If both are used,
-8-bit strings that cannot be interpreted as 7-bit \ASCII{} (that
-use the 8th bit) will cause a \exception{UnicodeError} to be raised
-when \method{getvalue()} is called.
-\end{classdesc}
-
-The following methods of \class{StringIO} objects require special
-mention:
-
-\begin{methoddesc}{getvalue}{}
-Retrieve the entire contents of the ``file'' at any time before the
-\class{StringIO} object's \method{close()} method is called. See the
-note above for information about mixing Unicode and 8-bit strings;
-such mixing can cause this method to raise \exception{UnicodeError}.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
-Free the memory buffer.
-\end{methoddesc}
-
-Example usage:
-
-\begin{verbatim}
-import StringIO
-
-output = StringIO.StringIO()
-output.write('First line.\n')
-print >>output, 'Second line.'
-
-# Retrieve file contents -- this will be
-# 'First line.\nSecond line.\n'
-contents = output.getvalue()
-
-# Close object and discard memory buffer --
-# .getvalue() will now raise an exception.
-output.close()
-\end{verbatim}
-
-
-\section{\module{cStringIO} ---
- Faster version of \module{StringIO}}
-
-\declaremodule{builtin}{cStringIO}
-\modulesynopsis{Faster version of \module{StringIO}, but not
- subclassable.}
-\moduleauthor{Jim Fulton}{jim@zope.com}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-The module \module{cStringIO} provides an interface similar to that of
-the \refmodule{StringIO} module. Heavy use of \class{StringIO.StringIO}
-objects can be made more efficient by using the function
-\function{StringIO()} from this module instead.
-
-Since this module provides a factory function which returns objects of
-built-in types, there's no way to build your own version using
-subclassing. Use the original \refmodule{StringIO} module in that case.
-
-Unlike the memory files implemented by the \refmodule{StringIO}
-module, those provided by this module are not able to accept Unicode
-strings that cannot be encoded as plain \ASCII{} strings.
-
-Calling \function{StringIO()} with a Unicode string parameter populates
-the object with the buffer representation of the Unicode string, instead of
-encoding the string.
-
-Another difference from the \refmodule{StringIO} module is that calling
-\function{StringIO()} with a string parameter creates a read-only object.
-Unlike an object created without a string parameter, it does not have
-write methods. These objects are not generally visible. They turn up in
-tracebacks as \class{StringI} and \class{StringO}.
-
-The following data objects are provided as well:
-
-
-\begin{datadesc}{InputType}
- The type object of the objects created by calling
- \function{StringIO} with a string parameter.
-\end{datadesc}
-
-\begin{datadesc}{OutputType}
- The type object of the objects returned by calling
- \function{StringIO} with no parameters.
-\end{datadesc}
-
-
-There is a C API to the module as well; refer to the module source for
-more information.
-
-Example usage:
-
-\begin{verbatim}
-import cStringIO
-
-output = cStringIO.StringIO()
-output.write('First line.\n')
-print >>output, 'Second line.'
-
-# Retrieve file contents -- this will be
-# 'First line.\nSecond line.\n'
-contents = output.getvalue()
-
-# Close object and discard memory buffer --
-# .getvalue() will now raise an exception.
-output.close()
-\end{verbatim}
-
diff --git a/Doc/lib/libstringprep.tex b/Doc/lib/libstringprep.tex
deleted file mode 100644
index 2614314..0000000
--- a/Doc/lib/libstringprep.tex
+++ /dev/null
@@ -1,136 +0,0 @@
-\section{\module{stringprep} ---
- Internet String Preparation}
-
-\declaremodule{standard}{stringprep}
-\modulesynopsis{String preparation, as per RFC 3453}
-\moduleauthor{Martin v. L\"owis}{martin@v.loewis.de}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\versionadded{2.3}
-
-When identifying things (such as host names) in the internet, it is
-often necessary to compare such identifications for
-``equality''. Exactly how this comparison is executed may depend on
-the application domain, e.g. whether it should be case-insensitive or
-not. It may be also necessary to restrict the possible
-identifications, to allow only identifications consisting of
-``printable'' characters.
-
-\rfc{3454} defines a procedure for ``preparing'' Unicode strings in
-internet protocols. Before passing strings onto the wire, they are
-processed with the preparation procedure, after which they have a
-certain normalized form. The RFC defines a set of tables, which can be
-combined into profiles. Each profile must define which tables it uses,
-and what other optional parts of the \code{stringprep} procedure are
-part of the profile. One example of a \code{stringprep} profile is
-\code{nameprep}, which is used for internationalized domain names.
-
-The module \module{stringprep} only exposes the tables from RFC
-3454. As these tables would be very large to represent them as
-dictionaries or lists, the module uses the Unicode character database
-internally. The module source code itself was generated using the
-\code{mkstringprep.py} utility.
-
-As a result, these tables are exposed as functions, not as data
-structures. There are two kinds of tables in the RFC: sets and
-mappings. For a set, \module{stringprep} provides the ``characteristic
-function'', i.e. a function that returns true if the parameter is part
-of the set. For mappings, it provides the mapping function: given the
-key, it returns the associated value. Below is a list of all functions
-available in the module.
-
-\begin{funcdesc}{in_table_a1}{code}
-Determine whether \var{code} is in table{A.1} (Unassigned code points
-in Unicode 3.2).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_b1}{code}
-Determine whether \var{code} is in table{B.1} (Commonly mapped to
-nothing).
-\end{funcdesc}
-
-\begin{funcdesc}{map_table_b2}{code}
-Return the mapped value for \var{code} according to table{B.2}
-(Mapping for case-folding used with NFKC).
-\end{funcdesc}
-
-\begin{funcdesc}{map_table_b3}{code}
-Return the mapped value for \var{code} according to table{B.3}
-(Mapping for case-folding used with no normalization).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c11}{code}
-Determine whether \var{code} is in table{C.1.1}
-(ASCII space characters).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c12}{code}
-Determine whether \var{code} is in table{C.1.2}
-(Non-ASCII space characters).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c11_c12}{code}
-Determine whether \var{code} is in table{C.1}
-(Space characters, union of C.1.1 and C.1.2).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c21}{code}
-Determine whether \var{code} is in table{C.2.1}
-(ASCII control characters).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c22}{code}
-Determine whether \var{code} is in table{C.2.2}
-(Non-ASCII control characters).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c21_c22}{code}
-Determine whether \var{code} is in table{C.2}
-(Control characters, union of C.2.1 and C.2.2).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c3}{code}
-Determine whether \var{code} is in table{C.3}
-(Private use).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c4}{code}
-Determine whether \var{code} is in table{C.4}
-(Non-character code points).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c5}{code}
-Determine whether \var{code} is in table{C.5}
-(Surrogate codes).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c6}{code}
-Determine whether \var{code} is in table{C.6}
-(Inappropriate for plain text).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c7}{code}
-Determine whether \var{code} is in table{C.7}
-(Inappropriate for canonical representation).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c8}{code}
-Determine whether \var{code} is in table{C.8}
-(Change display properties or are deprecated).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c9}{code}
-Determine whether \var{code} is in table{C.9}
-(Tagging characters).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_d1}{code}
-Determine whether \var{code} is in table{D.1}
-(Characters with bidirectional property ``R'' or ``AL'').
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_d2}{code}
-Determine whether \var{code} is in table{D.2}
-(Characters with bidirectional property ``L'').
-\end{funcdesc}
-
diff --git a/Doc/lib/libstrings.tex b/Doc/lib/libstrings.tex
deleted file mode 100644
index f3a31f4..0000000
--- a/Doc/lib/libstrings.tex
+++ /dev/null
@@ -1,10 +0,0 @@
-\chapter{String Services}
-\label{strings}
-
-The modules described in this chapter provide a wide range of string
-manipulation operations. Here's an overview:
-
-\localmoduletable
-
-Information on the methods of string objects can be found in
-section~\ref{string-methods}, ``String Methods.''
diff --git a/Doc/lib/libstruct.tex b/Doc/lib/libstruct.tex
deleted file mode 100644
index 68c5c9a..0000000
--- a/Doc/lib/libstruct.tex
+++ /dev/null
@@ -1,269 +0,0 @@
-\section{\module{struct} ---
- Interpret strings as packed binary data}
-\declaremodule{builtin}{struct}
-
-\modulesynopsis{Interpret strings as packed binary data.}
-
-\indexii{C}{structures}
-\indexiii{packing}{binary}{data}
-
-This module performs conversions between Python values and C
-structs represented as Python strings. It uses \dfn{format strings}
-(explained below) as compact descriptions of the lay-out of the C
-structs and the intended conversion to/from Python values. This can
-be used in handling binary data stored in files or from network
-connections, among other sources.
-
-The module defines the following exception and functions:
-
-
-\begin{excdesc}{error}
- Exception raised on various occasions; argument is a string
- describing what is wrong.
-\end{excdesc}
-
-\begin{funcdesc}{pack}{fmt, v1, v2, \textrm{\ldots}}
- Return a string containing the values
- \code{\var{v1}, \var{v2}, \textrm{\ldots}} packed according to the given
- format. The arguments must match the values required by the format
- exactly.
-\end{funcdesc}
-
-\begin{funcdesc}{pack_into}{fmt, buffer, offset, v1, v2, \moreargs}
- Pack the values \code{\var{v1}, \var{v2}, \textrm{\ldots}} according to the given
- format, write the packed bytes into the writable \var{buffer} starting at
- \var{offset}.
- Note that the offset is not an optional argument.
-
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{unpack}{fmt, string}
- Unpack the string (presumably packed by \code{pack(\var{fmt},
- \textrm{\ldots})}) according to the given format. The result is a
- tuple even if it contains exactly one item. The string must contain
- exactly the amount of data required by the format
- (\code{len(\var{string})} must equal \code{calcsize(\var{fmt})}).
-\end{funcdesc}
-
-\begin{funcdesc}{unpack_from}{fmt, buffer\optional{,offset \code{= 0}}}
- Unpack the \var{buffer} according to tthe given format.
- The result is a tuple even if it contains exactly one item. The
- \var{buffer} must contain at least the amount of data required by the
- format (\code{len(buffer[offset:])} must be at least
- \code{calcsize(\var{fmt})}).
-
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{calcsize}{fmt}
- Return the size of the struct (and hence of the string)
- corresponding to the given format.
-\end{funcdesc}
-
-Format characters have the following meaning; the conversion between
-C and Python values should be obvious given their types:
-
-\begin{tableiv}{c|l|l|c}{samp}{Format}{C Type}{Python}{Notes}
- \lineiv{x}{pad byte}{no value}{}
- \lineiv{c}{\ctype{char}}{string of length 1}{}
- \lineiv{b}{\ctype{signed char}}{integer}{}
- \lineiv{B}{\ctype{unsigned char}}{integer}{}
- \lineiv{t}{\ctype{_Bool}}{bool}{(1)}
- \lineiv{h}{\ctype{short}}{integer}{}
- \lineiv{H}{\ctype{unsigned short}}{integer}{}
- \lineiv{i}{\ctype{int}}{integer}{}
- \lineiv{I}{\ctype{unsigned int}}{long}{}
- \lineiv{l}{\ctype{long}}{integer}{}
- \lineiv{L}{\ctype{unsigned long}}{long}{}
- \lineiv{q}{\ctype{long long}}{long}{(2)}
- \lineiv{Q}{\ctype{unsigned long long}}{long}{(2)}
- \lineiv{f}{\ctype{float}}{float}{}
- \lineiv{d}{\ctype{double}}{float}{}
- \lineiv{s}{\ctype{char[]}}{string}{}
- \lineiv{p}{\ctype{char[]}}{string}{}
- \lineiv{P}{\ctype{void *}}{integer}{}
-\end{tableiv}
-
-\noindent
-Notes:
-
-\begin{description}
-\item[(1)]
- The \character{t} conversion code corresponds to the \ctype{_Bool} type
- defined by C99. If this type is not available, it is simulated using a
- \ctype{char}. In standard mode, it is always represented by one byte.
- \versionadded{2.6}
-\item[(2)]
- The \character{q} and \character{Q} conversion codes are available in
- native mode only if the platform C compiler supports C \ctype{long long},
- or, on Windows, \ctype{__int64}. They are always available in standard
- modes.
- \versionadded{2.2}
-\end{description}
-
-
-A format character may be preceded by an integral repeat count. For
-example, the format string \code{'4h'} means exactly the same as
-\code{'hhhh'}.
-
-Whitespace characters between formats are ignored; a count and its
-format must not contain whitespace though.
-
-For the \character{s} format character, the count is interpreted as the
-size of the string, not a repeat count like for the other format
-characters; for example, \code{'10s'} means a single 10-byte string, while
-\code{'10c'} means 10 characters. For packing, the string is
-truncated or padded with null bytes as appropriate to make it fit.
-For unpacking, the resulting string always has exactly the specified
-number of bytes. As a special case, \code{'0s'} means a single, empty
-string (while \code{'0c'} means 0 characters).
-
-The \character{p} format character encodes a "Pascal string", meaning
-a short variable-length string stored in a fixed number of bytes.
-The count is the total number of bytes stored. The first byte stored is
-the length of the string, or 255, whichever is smaller. The bytes
-of the string follow. If the string passed in to \function{pack()} is too
-long (longer than the count minus 1), only the leading count-1 bytes of the
-string are stored. If the string is shorter than count-1, it is padded
-with null bytes so that exactly count bytes in all are used. Note that
-for \function{unpack()}, the \character{p} format character consumes count
-bytes, but that the string returned can never contain more than 255
-characters.
-
-For the \character{I}, \character{L}, \character{q} and \character{Q}
-format characters, the return value is a Python long integer.
-
-For the \character{P} format character, the return value is a Python
-integer or long integer, depending on the size needed to hold a
-pointer when it has been cast to an integer type. A \NULL{} pointer will
-always be returned as the Python integer \code{0}. When packing pointer-sized
-values, Python integer or long integer objects may be used. For
-example, the Alpha and Merced processors use 64-bit pointer values,
-meaning a Python long integer will be used to hold the pointer; other
-platforms use 32-bit pointers and will use a Python integer.
-
-For the \character{t} format character, the return value is either
-\constant{True} or \constant{False}. When packing, the truth value
-of the argument object is used. Either 0 or 1 in the native or standard
-bool representation will be packed, and any non-zero value will be True
-when unpacking.
-
-By default, C numbers are represented in the machine's native format
-and byte order, and properly aligned by skipping pad bytes if
-necessary (according to the rules used by the C compiler).
-
-Alternatively, the first character of the format string can be used to
-indicate the byte order, size and alignment of the packed data,
-according to the following table:
-
-\begin{tableiii}{c|l|l}{samp}{Character}{Byte order}{Size and alignment}
- \lineiii{@}{native}{native}
- \lineiii{=}{native}{standard}
- \lineiii{<}{little-endian}{standard}
- \lineiii{>}{big-endian}{standard}
- \lineiii{!}{network (= big-endian)}{standard}
-\end{tableiii}
-
-If the first character is not one of these, \character{@} is assumed.
-
-Native byte order is big-endian or little-endian, depending on the
-host system. For example, Motorola and Sun processors are big-endian;
-Intel and DEC processors are little-endian.
-
-Native size and alignment are determined using the C compiler's
-\keyword{sizeof} expression. This is always combined with native byte
-order.
-
-Standard size and alignment are as follows: no alignment is required
-for any type (so you have to use pad bytes);
-\ctype{short} is 2 bytes;
-\ctype{int} and \ctype{long} are 4 bytes;
-\ctype{long long} (\ctype{__int64} on Windows) is 8 bytes;
-\ctype{float} and \ctype{double} are 32-bit and 64-bit
-IEEE floating point numbers, respectively.
-\ctype{_Bool} is 1 byte.
-
-Note the difference between \character{@} and \character{=}: both use
-native byte order, but the size and alignment of the latter is
-standardized.
-
-The form \character{!} is available for those poor souls who claim they
-can't remember whether network byte order is big-endian or
-little-endian.
-
-There is no way to indicate non-native byte order (force
-byte-swapping); use the appropriate choice of \character{<} or
-\character{>}.
-
-The \character{P} format character is only available for the native
-byte ordering (selected as the default or with the \character{@} byte
-order character). The byte order character \character{=} chooses to
-use little- or big-endian ordering based on the host system. The
-struct module does not interpret this as native ordering, so the
-\character{P} format is not available.
-
-Examples (all using native byte order, size and alignment, on a
-big-endian machine):
-
-\begin{verbatim}
->>> from struct import *
->>> pack('hhl', 1, 2, 3)
-'\x00\x01\x00\x02\x00\x00\x00\x03'
->>> unpack('hhl', '\x00\x01\x00\x02\x00\x00\x00\x03')
-(1, 2, 3)
->>> calcsize('hhl')
-8
-\end{verbatim}
-
-Hint: to align the end of a structure to the alignment requirement of
-a particular type, end the format with the code for that type with a
-repeat count of zero. For example, the format \code{'llh0l'}
-specifies two pad bytes at the end, assuming longs are aligned on
-4-byte boundaries. This only works when native size and alignment are
-in effect; standard size and alignment does not enforce any alignment.
-
-\begin{seealso}
- \seemodule{array}{Packed binary storage of homogeneous data.}
- \seemodule{xdrlib}{Packing and unpacking of XDR data.}
-\end{seealso}
-
-\subsection{Struct Objects \label{struct-objects}}
-
-The \module{struct} module also defines the following type:
-
-\begin{classdesc}{Struct}{format}
- Return a new Struct object which writes and reads binary data according to
- the format string \var{format}. Creating a Struct object once and calling
- its methods is more efficient than calling the \module{struct} functions
- with the same format since the format string only needs to be compiled once.
-
- \versionadded{2.5}
-\end{classdesc}
-
-Compiled Struct objects support the following methods and attributes:
-
-\begin{methoddesc}[Struct]{pack}{v1, v2, \moreargs}
- Identical to the \function{pack()} function, using the compiled format.
- (\code{len(result)} will equal \member{self.size}.)
-\end{methoddesc}
-
-\begin{methoddesc}[Struct]{pack_into}{buffer, offset, v1, v2, \moreargs}
- Identical to the \function{pack_into()} function, using the compiled format.
-\end{methoddesc}
-
-\begin{methoddesc}[Struct]{unpack}{string}
- Identical to the \function{unpack()} function, using the compiled format.
- (\code{len(string)} must equal \member{self.size}).
-\end{methoddesc}
-
-\begin{methoddesc}[Struct]{unpack_from}{buffer\optional{,offset
- \code{= 0}}}
- Identical to the \function{unpack_from()} function, using the compiled format.
- (\code{len(buffer[offset:])} must be at least \member{self.size}).
-\end{methoddesc}
-
-\begin{memberdesc}[Struct]{format}
- The format string used to construct this Struct object.
-\end{memberdesc}
-
diff --git a/Doc/lib/libsubprocess.tex b/Doc/lib/libsubprocess.tex
deleted file mode 100644
index e2a9bb6..0000000
--- a/Doc/lib/libsubprocess.tex
+++ /dev/null
@@ -1,340 +0,0 @@
-\section{\module{subprocess} --- Subprocess management}
-
-\declaremodule{standard}{subprocess}
-\modulesynopsis{Subprocess management.}
-\moduleauthor{Peter \AA strand}{astrand@lysator.liu.se}
-\sectionauthor{Peter \AA strand}{astrand@lysator.liu.se}
-
-\versionadded{2.4}
-
-The \module{subprocess} module allows you to spawn new processes,
-connect to their input/output/error pipes, and obtain their return
-codes. This module intends to replace several other, older modules
-and functions, such as:
-
-\begin{verbatim}
-os.system
-os.spawn*
-commands.*
-\end{verbatim}
-
-Information about how the \module{subprocess} module can be used to
-replace these modules and functions can be found in the following
-sections.
-
-\subsection{Using the subprocess Module}
-
-This module defines one class called \class{Popen}:
-
-\begin{classdesc}{Popen}{args, bufsize=0, executable=None,
- stdin=None, stdout=None, stderr=None,
- preexec_fn=None, close_fds=False, shell=False,
- cwd=None, env=None, universal_newlines=False,
- startupinfo=None, creationflags=0}
-
-Arguments are:
-
-\var{args} should be a string, or a sequence of program arguments. The
-program to execute is normally the first item in the args sequence or
-string, but can be explicitly set by using the executable argument.
-
-On \UNIX{}, with \var{shell=False} (default): In this case, the Popen
-class uses \method{os.execvp()} to execute the child program.
-\var{args} should normally be a sequence. A string will be treated as a
-sequence with the string as the only item (the program to execute).
-
-On \UNIX{}, with \var{shell=True}: If args is a string, it specifies the
-command string to execute through the shell. If \var{args} is a
-sequence, the first item specifies the command string, and any
-additional items will be treated as additional shell arguments.
-
-On Windows: the \class{Popen} class uses CreateProcess() to execute
-the child program, which operates on strings. If \var{args} is a
-sequence, it will be converted to a string using the
-\method{list2cmdline} method. Please note that not all MS Windows
-applications interpret the command line the same way:
-\method{list2cmdline} is designed for applications using the same
-rules as the MS C runtime.
-
-\var{bufsize}, if given, has the same meaning as the corresponding
-argument to the built-in open() function: \constant{0} means unbuffered,
-\constant{1} means line buffered, any other positive value means use a
-buffer of (approximately) that size. A negative \var{bufsize} means to
-use the system default, which usually means fully buffered. The default
-value for \var{bufsize} is \constant{0} (unbuffered).
-
-The \var{executable} argument specifies the program to execute. It is
-very seldom needed: Usually, the program to execute is defined by the
-\var{args} argument. If \code{shell=True}, the \var{executable}
-argument specifies which shell to use. On \UNIX{}, the default shell
-is \file{/bin/sh}. On Windows, the default shell is specified by the
-\envvar{COMSPEC} environment variable.
-
-\var{stdin}, \var{stdout} and \var{stderr} specify the executed
-programs' standard input, standard output and standard error file
-handles, respectively. Valid values are \code{PIPE}, an existing file
-descriptor (a positive integer), an existing file object, and
-\code{None}. \code{PIPE} indicates that a new pipe to the child
-should be created. With \code{None}, no redirection will occur; the
-child's file handles will be inherited from the parent. Additionally,
-\var{stderr} can be \code{STDOUT}, which indicates that the stderr
-data from the applications should be captured into the same file
-handle as for stdout.
-
-If \var{preexec_fn} is set to a callable object, this object will be
-called in the child process just before the child is executed.
-(\UNIX{} only)
-
-If \var{close_fds} is true, all file descriptors except \constant{0},
-\constant{1} and \constant{2} will be closed before the child process is
-executed. (\UNIX{} only). Or, on Windows, if \var{close_fds} is true
-then no handles will be inherited by the child process. Note that on
-Windows, you cannot set \var{close_fds} to true and also redirect the
-standard handles by setting \var{stdin}, \var{stdout} or \var{stderr}.
-
-If \var{shell} is \constant{True}, the specified command will be
-executed through the shell.
-
-If \var{cwd} is not \code{None}, the child's current directory will be
-changed to \var{cwd} before it is executed. Note that this directory
-is not considered when searching the executable, so you can't specify
-the program's path relative to \var{cwd}.
-
-If \var{env} is not \code{None}, it defines the environment variables
-for the new process.
-
-If \var{universal_newlines} is \constant{True}, the file objects stdout
-and stderr are opened as text files, but lines may be terminated by
-any of \code{'\e n'}, the \UNIX{} end-of-line convention, \code{'\e r'},
-the Macintosh convention or \code{'\e r\e n'}, the Windows convention.
-All of these external representations are seen as \code{'\e n'} by the
-Python program. \note{This feature is only available if Python is built
-with universal newline support (the default). Also, the newlines
-attribute of the file objects \member{stdout}, \member{stdin} and
-\member{stderr} are not updated by the communicate() method.}
-
-The \var{startupinfo} and \var{creationflags}, if given, will be
-passed to the underlying CreateProcess() function. They can specify
-things such as appearance of the main window and priority for the new
-process. (Windows only)
-\end{classdesc}
-
-\subsubsection{Convenience Functions}
-
-This module also defines two shortcut functions:
-
-\begin{funcdesc}{call}{*popenargs, **kwargs}
-Run command with arguments. Wait for command to complete, then
-return the \member{returncode} attribute.
-
-The arguments are the same as for the Popen constructor. Example:
-
-\begin{verbatim}
- retcode = call(["ls", "-l"])
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{check_call}{*popenargs, **kwargs}
-Run command with arguments. Wait for command to complete. If the exit
-code was zero then return, otherwise raise \exception{CalledProcessError.}
-The \exception{CalledProcessError} object will have the return code in the
-\member{returncode} attribute.
-
-The arguments are the same as for the Popen constructor. Example:
-
-\begin{verbatim}
- check_call(["ls", "-l"])
-\end{verbatim}
-
-\versionadded{2.5}
-\end{funcdesc}
-
-\subsubsection{Exceptions}
-
-Exceptions raised in the child process, before the new program has
-started to execute, will be re-raised in the parent. Additionally,
-the exception object will have one extra attribute called
-\member{child_traceback}, which is a string containing traceback
-information from the childs point of view.
-
-The most common exception raised is \exception{OSError}. This occurs,
-for example, when trying to execute a non-existent file. Applications
-should prepare for \exception{OSError} exceptions.
-
-A \exception{ValueError} will be raised if \class{Popen} is called
-with invalid arguments.
-
-check_call() will raise \exception{CalledProcessError}, if the called
-process returns a non-zero return code.
-
-
-\subsubsection{Security}
-
-Unlike some other popen functions, this implementation will never call
-/bin/sh implicitly. This means that all characters, including shell
-metacharacters, can safely be passed to child processes.
-
-
-\subsection{Popen Objects}
-
-Instances of the \class{Popen} class have the following methods:
-
-\begin{methoddesc}[Popen]{poll}{}
-Check if child process has terminated. Returns returncode
-attribute.
-\end{methoddesc}
-
-\begin{methoddesc}[Popen]{wait}{}
-Wait for child process to terminate. Returns returncode attribute.
-\end{methoddesc}
-
-\begin{methoddesc}[Popen]{communicate}{input=None}
-Interact with process: Send data to stdin. Read data from stdout and
-stderr, until end-of-file is reached. Wait for process to terminate.
-The optional \var{input} argument should be a string to be sent to the
-child process, or \code{None}, if no data should be sent to the child.
-
-communicate() returns a tuple (stdout, stderr).
-
-\note{The data read is buffered in memory, so do not use this method
-if the data size is large or unlimited.}
-\end{methoddesc}
-
-The following attributes are also available:
-
-\begin{memberdesc}[Popen]{stdin}
-If the \var{stdin} argument is \code{PIPE}, this attribute is a file
-object that provides input to the child process. Otherwise, it is
-\code{None}.
-\end{memberdesc}
-
-\begin{memberdesc}[Popen]{stdout}
-If the \var{stdout} argument is \code{PIPE}, this attribute is a file
-object that provides output from the child process. Otherwise, it is
-\code{None}.
-\end{memberdesc}
-
-\begin{memberdesc}[Popen]{stderr}
-If the \var{stderr} argument is \code{PIPE}, this attribute is file
-object that provides error output from the child process. Otherwise,
-it is \code{None}.
-\end{memberdesc}
-
-\begin{memberdesc}[Popen]{pid}
-The process ID of the child process.
-\end{memberdesc}
-
-\begin{memberdesc}[Popen]{returncode}
-The child return code. A \code{None} value indicates that the process
-hasn't terminated yet. A negative value -N indicates that the child
-was terminated by signal N (\UNIX{} only).
-\end{memberdesc}
-
-
-\subsection{Replacing Older Functions with the subprocess Module}
-
-In this section, "a ==> b" means that b can be used as a replacement
-for a.
-
-\note{All functions in this section fail (more or less) silently if
-the executed program cannot be found; this module raises an
-\exception{OSError} exception.}
-
-In the following examples, we assume that the subprocess module is
-imported with "from subprocess import *".
-
-\subsubsection{Replacing /bin/sh shell backquote}
-
-\begin{verbatim}
-output=`mycmd myarg`
-==>
-output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]
-\end{verbatim}
-
-\subsubsection{Replacing shell pipe line}
-
-\begin{verbatim}
-output=`dmesg | grep hda`
-==>
-p1 = Popen(["dmesg"], stdout=PIPE)
-p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
-output = p2.communicate()[0]
-\end{verbatim}
-
-\subsubsection{Replacing os.system()}
-
-\begin{verbatim}
-sts = os.system("mycmd" + " myarg")
-==>
-p = Popen("mycmd" + " myarg", shell=True)
-sts = os.waitpid(p.pid, 0)
-\end{verbatim}
-
-Notes:
-
-\begin{itemize}
-\item Calling the program through the shell is usually not required.
-\item It's easier to look at the \member{returncode} attribute than
- the exit status.
-\end{itemize}
-
-A more realistic example would look like this:
-
-\begin{verbatim}
-try:
- retcode = call("mycmd" + " myarg", shell=True)
- if retcode < 0:
- print >>sys.stderr, "Child was terminated by signal", -retcode
- else:
- print >>sys.stderr, "Child returned", retcode
-except OSError as e:
- print >>sys.stderr, "Execution failed:", e
-\end{verbatim}
-
-\subsubsection{Replacing os.spawn*}
-
-P_NOWAIT example:
-
-\begin{verbatim}
-pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
-==>
-pid = Popen(["/bin/mycmd", "myarg"]).pid
-\end{verbatim}
-
-P_WAIT example:
-
-\begin{verbatim}
-retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
-==>
-retcode = call(["/bin/mycmd", "myarg"])
-\end{verbatim}
-
-Vector example:
-
-\begin{verbatim}
-os.spawnvp(os.P_NOWAIT, path, args)
-==>
-Popen([path] + args[1:])
-\end{verbatim}
-
-Environment example:
-
-\begin{verbatim}
-os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
-==>
-Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
-\end{verbatim}
-
-\subsubsection{Replacing os.popen*}
-
-\begin{verbatim}
-pipe = os.popen(cmd, mode='r', bufsize)
-==>
-pipe = Popen(cmd, shell=True, bufsize=bufsize, stdout=PIPE).stdout
-\end{verbatim}
-
-\begin{verbatim}
-pipe = os.popen(cmd, mode='w', bufsize)
-==>
-pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin
-\end{verbatim}
diff --git a/Doc/lib/libsunau.tex b/Doc/lib/libsunau.tex
deleted file mode 100644
index 235bc3b..0000000
--- a/Doc/lib/libsunau.tex
+++ /dev/null
@@ -1,218 +0,0 @@
-\section{\module{sunau} ---
- Read and write Sun AU files}
-
-\declaremodule{standard}{sunau}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Provide an interface to the Sun AU sound format.}
-
-The \module{sunau} module provides a convenient interface to the Sun
-AU sound format. Note that this module is interface-compatible with
-the modules \refmodule{aifc} and \refmodule{wave}.
-
-An audio file consists of a header followed by the data. The fields
-of the header are:
-
-\begin{tableii}{l|l}{textrm}{Field}{Contents}
- \lineii{magic word}{The four bytes \samp{.snd}.}
- \lineii{header size}{Size of the header, including info, in bytes.}
- \lineii{data size}{Physical size of the data, in bytes.}
- \lineii{encoding}{Indicates how the audio samples are encoded.}
- \lineii{sample rate}{The sampling rate.}
- \lineii{\# of channels}{The number of channels in the samples.}
- \lineii{info}{\ASCII{} string giving a description of the audio
- file (padded with null bytes).}
-\end{tableii}
-
-Apart from the info field, all header fields are 4 bytes in size.
-They are all 32-bit unsigned integers encoded in big-endian byte
-order.
-
-
-The \module{sunau} module defines the following functions:
-
-\begin{funcdesc}{open}{file, mode}
-If \var{file} is a string, open the file by that name, otherwise treat it
-as a seekable file-like object. \var{mode} can be any of
-\begin{description}
- \item[\code{'r'}] Read only mode.
- \item[\code{'w'}] Write only mode.
-\end{description}
-Note that it does not allow read/write files.
-
-A \var{mode} of \code{'r'} returns a \class{AU_read}
-object, while a \var{mode} of \code{'w'} or \code{'wb'} returns
-a \class{AU_write} object.
-\end{funcdesc}
-
-\begin{funcdesc}{openfp}{file, mode}
-A synonym for \function{open}, maintained for backwards compatibility.
-\end{funcdesc}
-
-The \module{sunau} module defines the following exception:
-
-\begin{excdesc}{Error}
-An error raised when something is impossible because of Sun AU specs or
-implementation deficiency.
-\end{excdesc}
-
-The \module{sunau} module defines the following data items:
-
-\begin{datadesc}{AUDIO_FILE_MAGIC}
-An integer every valid Sun AU file begins with, stored in big-endian
-form. This is the string \samp{.snd} interpreted as an integer.
-\end{datadesc}
-
-\begin{datadesc}{AUDIO_FILE_ENCODING_MULAW_8}
-\dataline{AUDIO_FILE_ENCODING_LINEAR_8}
-\dataline{AUDIO_FILE_ENCODING_LINEAR_16}
-\dataline{AUDIO_FILE_ENCODING_LINEAR_24}
-\dataline{AUDIO_FILE_ENCODING_LINEAR_32}
-\dataline{AUDIO_FILE_ENCODING_ALAW_8}
-Values of the encoding field from the AU header which are supported by
-this module.
-\end{datadesc}
-
-\begin{datadesc}{AUDIO_FILE_ENCODING_FLOAT}
-\dataline{AUDIO_FILE_ENCODING_DOUBLE}
-\dataline{AUDIO_FILE_ENCODING_ADPCM_G721}
-\dataline{AUDIO_FILE_ENCODING_ADPCM_G722}
-\dataline{AUDIO_FILE_ENCODING_ADPCM_G723_3}
-\dataline{AUDIO_FILE_ENCODING_ADPCM_G723_5}
-Additional known values of the encoding field from the AU header, but
-which are not supported by this module.
-\end{datadesc}
-
-
-\subsection{AU_read Objects \label{au-read-objects}}
-
-AU_read objects, as returned by \function{open()} above, have the
-following methods:
-
-\begin{methoddesc}[AU_read]{close}{}
-Close the stream, and make the instance unusable. (This is
-called automatically on deletion.)
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getnchannels}{}
-Returns number of audio channels (1 for mone, 2 for stereo).
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getsampwidth}{}
-Returns sample width in bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getframerate}{}
-Returns sampling frequency.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getnframes}{}
-Returns number of audio frames.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getcomptype}{}
-Returns compression type.
-Supported compression types are \code{'ULAW'}, \code{'ALAW'} and \code{'NONE'}.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getcompname}{}
-Human-readable version of \method{getcomptype()}.
-The supported types have the respective names \code{'CCITT G.711
-u-law'}, \code{'CCITT G.711 A-law'} and \code{'not compressed'}.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getparams}{}
-Returns a tuple \code{(\var{nchannels}, \var{sampwidth},
-\var{framerate}, \var{nframes}, \var{comptype}, \var{compname})},
-equivalent to output of the \method{get*()} methods.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{readframes}{n}
-Reads and returns at most \var{n} frames of audio, as a string of
-bytes. The data will be returned in linear format. If the original
-data is in u-LAW format, it will be converted.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{rewind}{}
-Rewind the file pointer to the beginning of the audio stream.
-\end{methoddesc}
-
-The following two methods define a term ``position'' which is compatible
-between them, and is otherwise implementation dependent.
-
-\begin{methoddesc}[AU_read]{setpos}{pos}
-Set the file pointer to the specified position. Only values returned
-from \method{tell()} should be used for \var{pos}.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{tell}{}
-Return current file pointer position. Note that the returned value
-has nothing to do with the actual position in the file.
-\end{methoddesc}
-
-The following two functions are defined for compatibility with the
-\refmodule{aifc}, and don't do anything interesting.
-
-\begin{methoddesc}[AU_read]{getmarkers}{}
-Returns \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getmark}{id}
-Raise an error.
-\end{methoddesc}
-
-
-\subsection{AU_write Objects \label{au-write-objects}}
-
-AU_write objects, as returned by \function{open()} above, have the
-following methods:
-
-\begin{methoddesc}[AU_write]{setnchannels}{n}
-Set the number of channels.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{setsampwidth}{n}
-Set the sample width (in bytes.)
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{setframerate}{n}
-Set the frame rate.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{setnframes}{n}
-Set the number of frames. This can be later changed, when and if more
-frames are written.
-\end{methoddesc}
-
-
-\begin{methoddesc}[AU_write]{setcomptype}{type, name}
-Set the compression type and description.
-Only \code{'NONE'} and \code{'ULAW'} are supported on output.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{setparams}{tuple}
-The \var{tuple} should be \code{(\var{nchannels}, \var{sampwidth},
-\var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}, with
-values valid for the \method{set*()} methods. Set all parameters.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{tell}{}
-Return current position in the file, with the same disclaimer for
-the \method{AU_read.tell()} and \method{AU_read.setpos()} methods.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{writeframesraw}{data}
-Write audio frames, without correcting \var{nframes}.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{writeframes}{data}
-Write audio frames and make sure \var{nframes} is correct.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{close}{}
-Make sure \var{nframes} is correct, and close the file.
-
-This method is called upon deletion.
-\end{methoddesc}
-
-Note that it is invalid to set any parameters after calling
-\method{writeframes()} or \method{writeframesraw()}.
diff --git a/Doc/lib/libsymbol.tex b/Doc/lib/libsymbol.tex
deleted file mode 100644
index 54cabeb..0000000
--- a/Doc/lib/libsymbol.tex
+++ /dev/null
@@ -1,30 +0,0 @@
-\section{\module{symbol} ---
- Constants used with Python parse trees}
-
-\declaremodule{standard}{symbol}
-\modulesynopsis{Constants representing internal nodes of the parse tree.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-This module provides constants which represent the numeric values of
-internal nodes of the parse tree. Unlike most Python constants, these
-use lower-case names. Refer to the file \file{Grammar/Grammar} in the
-Python distribution for the definitions of the names in the context of
-the language grammar. The specific numeric values which the names map
-to may change between Python versions.
-
-This module also provides one additional data object:
-
-
-\begin{datadesc}{sym_name}
- Dictionary mapping the numeric values of the constants defined in
- this module back to name strings, allowing more human-readable
- representation of parse trees to be generated.
-\end{datadesc}
-
-
-\begin{seealso}
- \seemodule{parser}{The second example for the \refmodule{parser}
- module shows how to use the \module{symbol}
- module.}
-\end{seealso}
diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex
deleted file mode 100644
index 4ab3247..0000000
--- a/Doc/lib/libsys.tex
+++ /dev/null
@@ -1,582 +0,0 @@
-\section{\module{sys} ---
- System-specific parameters and functions}
-
-\declaremodule{builtin}{sys}
-\modulesynopsis{Access system-specific parameters and functions.}
-
-This module provides access to some variables used or maintained by the
-interpreter and to functions that interact strongly with the interpreter.
-It is always available.
-
-
-\begin{datadesc}{argv}
- The list of command line arguments passed to a Python script.
- \code{argv[0]} is the script name (it is operating system dependent
- whether this is a full pathname or not). If the command was
- executed using the \programopt{-c} command line option to the
- interpreter, \code{argv[0]} is set to the string \code{'-c'}. If no
- script name was passed to the Python interpreter, \code{argv[0]} is
- the empty string.
-\end{datadesc}
-
-\begin{datadesc}{byteorder}
- An indicator of the native byte order. This will have the value
- \code{'big'} on big-endian (most-significant byte first) platforms,
- and \code{'little'} on little-endian (least-significant byte first)
- platforms.
- \versionadded{2.0}
-\end{datadesc}
-
-\begin{datadesc}{subversion}
- A triple (repo, branch, version) representing the Subversion
- information of the Python interpreter.
- \var{repo} is the name of the repository, \code{'CPython'}.
- \var{branch} is a string of one of the forms \code{'trunk'},
- \code{'branches/name'} or \code{'tags/name'}.
- \var{version} is the output of \code{svnversion}, if the
- interpreter was built from a Subversion checkout; it contains
- the revision number (range) and possibly a trailing 'M' if
- there were local modifications. If the tree was exported
- (or svnversion was not available), it is the revision of
- \code{Include/patchlevel.h} if the branch is a tag. Otherwise,
- it is \code{None}.
- \versionadded{2.5}
-\end{datadesc}
-
-\begin{datadesc}{builtin_module_names}
- A tuple of strings giving the names of all modules that are compiled
- into this Python interpreter. (This information is not available in
- any other way --- \code{modules.keys()} only lists the imported
- modules.)
-\end{datadesc}
-
-\begin{datadesc}{copyright}
- A string containing the copyright pertaining to the Python
- interpreter.
-\end{datadesc}
-
-\begin{funcdesc}{_current_frames}{}
- Return a dictionary mapping each thread's identifier to the topmost stack
- frame currently active in that thread at the time the function is called.
- Note that functions in the \refmodule{traceback} module can build the
- call stack given such a frame.
-
- This is most useful for debugging deadlock: this function does not
- require the deadlocked threads' cooperation, and such threads' call stacks
- are frozen for as long as they remain deadlocked. The frame returned
- for a non-deadlocked thread may bear no relationship to that thread's
- current activity by the time calling code examines the frame.
-
- This function should be used for internal and specialized purposes
- only.
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{datadesc}{dllhandle}
- Integer specifying the handle of the Python DLL.
- Availability: Windows.
-\end{datadesc}
-
-\begin{funcdesc}{displayhook}{\var{value}}
- If \var{value} is not \code{None}, this function prints it to
- \code{sys.stdout}, and saves it in \code{__builtin__._}.
-
- \code{sys.displayhook} is called on the result of evaluating an
- expression entered in an interactive Python session. The display of
- these values can be customized by assigning another one-argument
- function to \code{sys.displayhook}.
-\end{funcdesc}
-
-\begin{funcdesc}{excepthook}{\var{type}, \var{value}, \var{traceback}}
- This function prints out a given traceback and exception to
- \code{sys.stderr}.
-
- When an exception is raised and uncaught, the interpreter calls
- \code{sys.excepthook} with three arguments, the exception class,
- exception instance, and a traceback object. In an interactive
- session this happens just before control is returned to the prompt;
- in a Python program this happens just before the program exits. The
- handling of such top-level exceptions can be customized by assigning
- another three-argument function to \code{sys.excepthook}.
-\end{funcdesc}
-
-\begin{datadesc}{__displayhook__}
-\dataline{__excepthook__}
- These objects contain the original values of \code{displayhook} and
- \code{excepthook} at the start of the program. They are saved so
- that \code{displayhook} and \code{excepthook} can be restored in
- case they happen to get replaced with broken objects.
-\end{datadesc}
-
-\begin{funcdesc}{exc_info}{}
- This function returns a tuple of three values that give information
- about the exception that is currently being handled. The
- information returned is specific both to the current thread and to
- the current stack frame. If the current stack frame is not handling
- an exception, the information is taken from the calling stack frame,
- or its caller, and so on until a stack frame is found that is
- handling an exception. Here, ``handling an exception'' is defined
- as ``executing or having executed an except clause.'' For any stack
- frame, only information about the most recently handled exception is
- accessible.
-
- If no exception is being handled anywhere on the stack, a tuple
- containing three \code{None} values is returned. Otherwise, the
- values returned are \code{(\var{type}, \var{value},
- \var{traceback})}. Their meaning is: \var{type} gets the exception
- type of the exception being handled (a class object);
- \var{value} gets the exception parameter (its \dfn{associated value}
- or the second argument to \keyword{raise}, which is always a class
- instance if the exception type is a class object); \var{traceback}
- gets a traceback object (see the Reference Manual) which
- encapsulates the call stack at the point where the exception
- originally occurred. \obindex{traceback}
-
- \warning{Assigning the \var{traceback} return value to a
- local variable in a function that is handling an exception will
- cause a circular reference. This will prevent anything referenced
- by a local variable in the same function or by the traceback from
- being garbage collected. Since most functions don't need access to
- the traceback, the best solution is to use something like
- \code{exctype, value = sys.exc_info()[:2]} to extract only the
- exception type and value. If you do need the traceback, make sure
- to delete it after use (best done with a \keyword{try}
- ... \keyword{finally} statement) or to call \function{exc_info()} in
- a function that does not itself handle an exception.} \note{Beginning
- with Python 2.2, such cycles are automatically reclaimed when garbage
- collection is enabled and they become unreachable, but it remains more
- efficient to avoid creating cycles.}
-\end{funcdesc}
-
-\begin{datadesc}{exec_prefix}
- A string giving the site-specific directory prefix where the
- platform-dependent Python files are installed; by default, this is
- also \code{'/usr/local'}. This can be set at build time with the
- \longprogramopt{exec-prefix} argument to the \program{configure}
- script. Specifically, all configuration files (e.g. the
- \file{pyconfig.h} header file) are installed in the directory
- \code{exec_prefix + '/lib/python\var{version}/config'}, and shared
- library modules are installed in \code{exec_prefix +
- '/lib/python\var{version}/lib-dynload'}, where \var{version} is
- equal to \code{version[:3]}.
-\end{datadesc}
-
-\begin{datadesc}{executable}
- A string giving the name of the executable binary for the Python
- interpreter, on systems where this makes sense.
-\end{datadesc}
-
-\begin{funcdesc}{exit}{\optional{arg}}
- Exit from Python. This is implemented by raising the
- \exception{SystemExit} exception, so cleanup actions specified by
- finally clauses of \keyword{try} statements are honored, and it is
- possible to intercept the exit attempt at an outer level. The
- optional argument \var{arg} can be an integer giving the exit status
- (defaulting to zero), or another type of object. If it is an
- integer, zero is considered ``successful termination'' and any
- nonzero value is considered ``abnormal termination'' by shells and
- the like. Most systems require it to be in the range 0-127, and
- produce undefined results otherwise. Some systems have a convention
- for assigning specific meanings to specific exit codes, but these
- are generally underdeveloped; \UNIX{} programs generally use 2 for
- command line syntax errors and 1 for all other kind of errors. If
- another type of object is passed, \code{None} is equivalent to
- passing zero, and any other object is printed to \code{sys.stderr}
- and results in an exit code of 1. In particular,
- \code{sys.exit("some error message")} is a quick way to exit a
- program when an error occurs.
-\end{funcdesc}
-
-\begin{funcdesc}{getcheckinterval}{}
- Return the interpreter's ``check interval'';
- see \function{setcheckinterval()}.
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getdefaultencoding}{}
- Return the name of the current default string encoding used by the
- Unicode implementation.
- \versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{getdlopenflags}{}
- Return the current value of the flags that are used for
- \cfunction{dlopen()} calls. The flag constants are defined in the
- \refmodule{dl} and \module{DLFCN} modules.
- Availability: \UNIX.
- \versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{getfilesystemencoding}{}
- Return the name of the encoding used to convert Unicode filenames
- into system file names, or \code{None} if the system default encoding
- is used. The result value depends on the operating system:
-\begin{itemize}
-\item On Windows 9x, the encoding is ``mbcs''.
-\item On Mac OS X, the encoding is ``utf-8''.
-\item On \UNIX, the encoding is the user's preference
- according to the result of nl_langinfo(CODESET), or \constant{None}
- if the \code{nl_langinfo(CODESET)} failed.
-\item On Windows NT+, file names are Unicode natively, so no conversion
- is performed. \function{getfilesystemencoding()} still returns
- \code{'mbcs'}, as this is the encoding that applications should use
- when they explicitly want to convert Unicode strings to byte strings
- that are equivalent when used as file names.
-\end{itemize}
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getrefcount}{object}
- Return the reference count of the \var{object}. The count returned
- is generally one higher than you might expect, because it includes
- the (temporary) reference as an argument to
- \function{getrefcount()}.
-\end{funcdesc}
-
-\begin{funcdesc}{getrecursionlimit}{}
- Return the current value of the recursion limit, the maximum depth
- of the Python interpreter stack. This limit prevents infinite
- recursion from causing an overflow of the C stack and crashing
- Python. It can be set by \function{setrecursionlimit()}.
-\end{funcdesc}
-
-\begin{funcdesc}{_getframe}{\optional{depth}}
- Return a frame object from the call stack. If optional integer
- \var{depth} is given, return the frame object that many calls below
- the top of the stack. If that is deeper than the call stack,
- \exception{ValueError} is raised. The default for \var{depth} is
- zero, returning the frame at the top of the call stack.
-
- This function should be used for internal and specialized purposes
- only.
-\end{funcdesc}
-
-\begin{funcdesc}{getwindowsversion}{}
- Return a tuple containing five components, describing the Windows
- version currently running. The elements are \var{major}, \var{minor},
- \var{build}, \var{platform}, and \var{text}. \var{text} contains
- a string while all other values are integers.
-
- \var{platform} may be one of the following values:
-
- \begin{tableii}{l|l}{constant}{Constant}{Platform}
- \lineii{0 (VER_PLATFORM_WIN32s)} {Win32s on Windows 3.1}
- \lineii{1 (VER_PLATFORM_WIN32_WINDOWS)}{Windows 95/98/ME}
- \lineii{2 (VER_PLATFORM_WIN32_NT)} {Windows NT/2000/XP}
- \lineii{3 (VER_PLATFORM_WIN32_CE)} {Windows CE}
- \end{tableii}
-
- This function wraps the Win32 \cfunction{GetVersionEx()} function;
- see the Microsoft documentation for more information about these
- fields.
-
- Availability: Windows.
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{datadesc}{hexversion}
- The version number encoded as a single integer. This is guaranteed
- to increase with each version, including proper support for
- non-production releases. For example, to test that the Python
- interpreter is at least version 1.5.2, use:
-
-\begin{verbatim}
-if sys.hexversion >= 0x010502F0:
- # use some advanced feature
- ...
-else:
- # use an alternative implementation or warn the user
- ...
-\end{verbatim}
-
- This is called \samp{hexversion} since it only really looks
- meaningful when viewed as the result of passing it to the built-in
- \function{hex()} function. The \code{version_info} value may be
- used for a more human-friendly encoding of the same information.
- \versionadded{1.5.2}
-\end{datadesc}
-
-\begin{funcdesc}{intern}{string}
- Enter \var{string} in the table of ``interned'' strings and return
- the interned string -- which is \var{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[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 \function{intern()}
- around to benefit from it]{2.3}
-\end{funcdesc}
-
-\begin{datadesc}{last_type}
-\dataline{last_value}
-\dataline{last_traceback}
- These three variables are not always defined; they are set when an
- exception is not handled and the interpreter prints an error message
- and a stack traceback. Their intended use is to allow an
- interactive user to import a debugger module and engage in
- post-mortem debugging without having to re-execute the command that
- caused the error. (Typical use is \samp{import pdb; pdb.pm()} to
- enter the post-mortem debugger; see chapter~\ref{debugger}, ``The
- Python Debugger,'' for more information.)
-
- The meaning of the variables is the same as that of the return
- values from \function{exc_info()} above. (Since there is only one
- interactive thread, thread-safety is not a concern for these
- variables, unlike for \code{exc_type} etc.)
-\end{datadesc}
-
-\begin{datadesc}{maxint}
- The largest positive integer supported by Python's regular integer
- type. This is at least 2**31-1. The largest negative integer is
- \code{-maxint-1} --- the asymmetry results from the use of 2's
- complement binary arithmetic.
-\end{datadesc}
-
-\begin{datadesc}{maxunicode}
- An integer giving the largest supported code point for a Unicode
- character. The value of this depends on the configuration option
- that specifies whether Unicode characters are stored as UCS-2 or
- UCS-4.
-\end{datadesc}
-
-\begin{datadesc}{modules}
- This is a dictionary that maps module names to modules which have
- already been loaded. This can be manipulated to force reloading of
- modules and other tricks.
-\end{datadesc}
-
-\begin{datadesc}{path}
-\indexiii{module}{search}{path}
- A list of strings that specifies the search path for modules.
- Initialized from the environment variable \envvar{PYTHONPATH}, plus an
- installation-dependent default.
-
- As initialized upon program startup,
- the first item of this list, \code{path[0]}, is the directory
- containing the script that was used to invoke the Python
- interpreter. If the script directory is not available (e.g. if the
- interpreter is invoked interactively or if the script is read from
- standard input), \code{path[0]} is the empty string, which directs
- Python to search modules in the current directory first. Notice
- that the script directory is inserted \emph{before} the entries
- inserted as a result of \envvar{PYTHONPATH}.
-
- A program is free to modify this list for its own purposes.
-
- \versionchanged[Unicode strings are no longer ignored]{2.3}
-\end{datadesc}
-
-\begin{datadesc}{platform}
- This string contains a platform identifier, e.g. \code{'sunos5'} or
- \code{'linux1'}. This can be used to append platform-specific
- components to \code{path}, for instance.
-\end{datadesc}
-
-\begin{datadesc}{prefix}
- A string giving the site-specific directory prefix where the
- platform independent Python files are installed; by default, this is
- the string \code{'/usr/local'}. This can be set at build time with
- the \longprogramopt{prefix} argument to the \program{configure}
- script. The main collection of Python library modules is installed
- in the directory \code{prefix + '/lib/python\var{version}'} while
- the platform independent header files (all except \file{pyconfig.h})
- are stored in \code{prefix + '/include/python\var{version}'}, where
- \var{version} is equal to \code{version[:3]}.
-\end{datadesc}
-
-\begin{datadesc}{ps1}
-\dataline{ps2}
-\index{interpreter prompts}
-\index{prompts, interpreter}
- Strings specifying the primary and secondary prompt of the
- interpreter. These are only defined if the interpreter is in
- interactive mode. Their initial values in this case are
- \code{'>>>~'} and \code{'...~'}. If a non-string object is
- assigned to either variable, its \function{str()} is re-evaluated
- each time the interpreter prepares to read a new interactive
- command; this can be used to implement a dynamic prompt.
-\end{datadesc}
-
-\begin{funcdesc}{setcheckinterval}{interval}
- Set the interpreter's ``check interval''. This integer value
- determines how often the interpreter checks for periodic things such
- as thread switches and signal handlers. The default is \code{100},
- meaning the check is performed every 100 Python virtual instructions.
- Setting it to a larger value may increase performance for programs
- using threads. Setting it to a value \code{<=} 0 checks every
- virtual instruction, maximizing responsiveness as well as overhead.
-\end{funcdesc}
-
-\begin{funcdesc}{setdefaultencoding}{name}
- Set the current default string encoding used by the Unicode
- implementation. If \var{name} does not match any available
- encoding, \exception{LookupError} is raised. This function is only
- intended to be used by the \refmodule{site} module implementation
- and, where needed, by \module{sitecustomize}. Once used by the
- \refmodule{site} module, it is removed from the \module{sys}
- module's namespace.
-% Note that \refmodule{site} is not imported if
-% the \programopt{-S} option is passed to the interpreter, in which
-% case this function will remain available.
- \versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{setdlopenflags}{n}
- Set the flags used by the interpreter for \cfunction{dlopen()}
- calls, such as when the interpreter loads extension modules. Among
- other things, this will enable a lazy resolving of symbols when
- importing a module, if called as \code{sys.setdlopenflags(0)}. To
- share symbols across extension modules, call as
- \code{sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL)}. Symbolic
- names for the flag modules can be either found in the \refmodule{dl}
- module, or in the \module{DLFCN} module. If \module{DLFCN} is not
- available, it can be generated from \file{/usr/include/dlfcn.h}
- using the \program{h2py} script.
- Availability: \UNIX.
- \versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{setprofile}{profilefunc}
- Set the system's profile function,\index{profile function} which
- allows you to implement a Python source code profiler in
- Python.\index{profiler} See chapter~\ref{profile} for more
- information on the Python profiler. The system's profile function
- is called similarly to the system's trace function (see
- \function{settrace()}), but it isn't called for each executed line
- of code (only on call and return, but the return event is reported
- even when an exception has been set). The function is
- thread-specific, but there is no way for the profiler to know about
- context switches between threads, so it does not make sense to use
- this in the presence of multiple threads.
- Also, its return value is not used, so it can simply return
- \code{None}.
-\end{funcdesc}
-
-\begin{funcdesc}{setrecursionlimit}{limit}
- Set the maximum depth of the Python interpreter stack to
- \var{limit}. This limit prevents infinite recursion from causing an
- overflow of the C stack and crashing Python.
-
- The highest possible limit is platform-dependent. A user may need
- to set the limit higher when she has a program that requires deep
- recursion and a platform that supports a higher limit. This should
- be done with care, because a too-high limit can lead to a crash.
-\end{funcdesc}
-
-\begin{funcdesc}{settrace}{tracefunc}
- Set the system's trace function,\index{trace function} which allows
- you to implement a Python source code debugger in Python. See
- section \ref{debugger-hooks}, ``How It Works,'' in the chapter on
- the Python debugger.\index{debugger} The function is
- thread-specific; for a debugger to support multiple threads, it must
- be registered using \function{settrace()} for each thread being
- debugged. \note{The \function{settrace()} function is intended only
- for implementing debuggers, profilers, coverage tools and the like.
- Its behavior is part of the implementation platform, rather than
- part of the language definition, and thus may not be available in
- all Python implementations.}
-\end{funcdesc}
-
-\begin{funcdesc}{settscdump}{on_flag}
- Activate dumping of VM measurements using the Pentium timestamp
- counter, if \var{on_flag} is true. Deactivate these dumps if
- \var{on_flag} is off. The function is available only if Python
- was compiled with \longprogramopt{with-tsc}. To understand the
- output of this dump, read \file{Python/ceval.c} in the Python
- sources.
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{datadesc}{stdin}
-\dataline{stdout}
-\dataline{stderr}
- File objects corresponding to the interpreter's standard input,
- output and error streams. \code{stdin} is used for all interpreter
- input except for scripts. \code{stdout} is
- used for the output of \keyword{print} and expression statements.
- The interpreter's own prompts and (almost all of) its error messages
- go to \code{stderr}. \code{stdout} and \code{stderr} needn't be
- built-in file objects: any object is acceptable as long as it has a
- \method{write()} method that takes a string argument. (Changing
- these objects doesn't affect the standard I/O streams of processes
- executed by \function{os.popen()}, \function{os.system()} or the
- \function{exec*()} family of functions in the \refmodule{os}
- module.)
-\end{datadesc}
-
-\begin{datadesc}{__stdin__}
-\dataline{__stdout__}
-\dataline{__stderr__}
- These objects contain the original values of \code{stdin},
- \code{stderr} and \code{stdout} at the start of the program. They
- are used during finalization, and could be useful to restore the
- actual files to known working file objects in case they have been
- overwritten with a broken object.
-\end{datadesc}
-
-\begin{datadesc}{tracebacklimit}
- When this variable is set to an integer value, it determines the
- maximum number of levels of traceback information printed when an
- unhandled exception occurs. The default is \code{1000}. When set
- to \code{0} or less, all traceback information is suppressed and
- only the exception type and value are printed.
-\end{datadesc}
-
-\begin{datadesc}{version}
- A string containing the version number of the Python interpreter
- plus additional information on the build number and compiler used.
- It has a value of the form \code{'\var{version}
- (\#\var{build_number}, \var{build_date}, \var{build_time})
- [\var{compiler}]'}. The first three characters are used to identify
- the version in the installation directories (where appropriate on
- each platform). An example:
-
-\begin{verbatim}
->>> import sys
->>> sys.version
-'1.5.2 (#0 Apr 13 1999, 10:51:12) [MSC 32 bit (Intel)]'
-\end{verbatim}
-\end{datadesc}
-
-\begin{datadesc}{api_version}
- The C API version for this interpreter. Programmers may find this useful
- when debugging version conflicts between Python and extension
- modules. \versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{version_info}
- A tuple containing the five components of the version number:
- \var{major}, \var{minor}, \var{micro}, \var{releaselevel}, and
- \var{serial}. All values except \var{releaselevel} are integers;
- the release level is \code{'alpha'}, \code{'beta'},
- \code{'candidate'}, or \code{'final'}. The \code{version_info}
- value corresponding to the Python version 2.0 is \code{(2, 0, 0,
- 'final', 0)}.
- \versionadded{2.0}
-\end{datadesc}
-
-\begin{datadesc}{warnoptions}
- This is an implementation detail of the warnings framework; do not
- modify this value. Refer to the \refmodule{warnings} module for
- more information on the warnings framework.
-\end{datadesc}
-
-\begin{datadesc}{winver}
- The version number used to form registry keys on Windows platforms.
- This is stored as string resource 1000 in the Python DLL. The value
- is normally the first three characters of \constant{version}. It is
- provided in the \module{sys} module for informational purposes;
- modifying this value has no effect on the registry keys used by
- Python.
- Availability: Windows.
-\end{datadesc}
-
-
-\begin{seealso}
- \seemodule{site}
- {This describes how to use .pth files to extend \code{sys.path}.}
-\end{seealso}
diff --git a/Doc/lib/libsyslog.tex b/Doc/lib/libsyslog.tex
deleted file mode 100644
index fc59776..0000000
--- a/Doc/lib/libsyslog.tex
+++ /dev/null
@@ -1,76 +0,0 @@
-\section{\module{syslog} ---
- \UNIX{} syslog library routines}
-
-\declaremodule{builtin}{syslog}
- \platform{Unix}
-\modulesynopsis{An interface to the \UNIX\ syslog library routines.}
-
-
-This module provides an interface to the \UNIX{} \code{syslog} library
-routines. Refer to the \UNIX{} manual pages for a detailed description
-of the \code{syslog} facility.
-
-The module defines the following functions:
-
-
-\begin{funcdesc}{syslog}{\optional{priority,} message}
-Send the string \var{message} to the system logger. A trailing
-newline is added if necessary. Each message is tagged with a priority
-composed of a \var{facility} and a \var{level}. The optional
-\var{priority} argument, which defaults to \constant{LOG_INFO},
-determines the message priority. If the facility is not encoded in
-\var{priority} using logical-or (\code{LOG_INFO | LOG_USER}), the
-value given in the \function{openlog()} call is used.
-\end{funcdesc}
-
-\begin{funcdesc}{openlog}{ident\optional{, logopt\optional{, facility}}}
-Logging options other than the defaults can be set by explicitly
-opening the log file with \function{openlog()} prior to calling
-\function{syslog()}. The defaults are (usually) \var{ident} =
-\code{'syslog'}, \var{logopt} = \code{0}, \var{facility} =
-\constant{LOG_USER}. The \var{ident} argument is a string which is
-prepended to every message. The optional \var{logopt} argument is a
-bit field - see below for possible values to combine. The optional
-\var{facility} argument sets the default facility for messages which
-do not have a facility explicitly encoded.
-\end{funcdesc}
-
-\begin{funcdesc}{closelog}{}
-Close the log file.
-\end{funcdesc}
-
-\begin{funcdesc}{setlogmask}{maskpri}
-Set the priority mask to \var{maskpri} and return the
-previous mask value. Calls to \function{syslog()} with a priority
-level not set in \var{maskpri} are ignored. The default is to log all
-priorities. The function \code{LOG_MASK(\var{pri})} calculates the
-mask for the individual priority \var{pri}. The function
-\code{LOG_UPTO(\var{pri})} calculates the mask for all priorities up
-to and including \var{pri}.
-\end{funcdesc}
-
-
-The module defines the following constants:
-
-\begin{description}
-
-\item[Priority levels (high to low):]
-
-\constant{LOG_EMERG}, \constant{LOG_ALERT}, \constant{LOG_CRIT},
-\constant{LOG_ERR}, \constant{LOG_WARNING}, \constant{LOG_NOTICE},
-\constant{LOG_INFO}, \constant{LOG_DEBUG}.
-
-\item[Facilities:]
-
-\constant{LOG_KERN}, \constant{LOG_USER}, \constant{LOG_MAIL},
-\constant{LOG_DAEMON}, \constant{LOG_AUTH}, \constant{LOG_LPR},
-\constant{LOG_NEWS}, \constant{LOG_UUCP}, \constant{LOG_CRON} and
-\constant{LOG_LOCAL0} to \constant{LOG_LOCAL7}.
-
-\item[Log options:]
-
-\constant{LOG_PID}, \constant{LOG_CONS}, \constant{LOG_NDELAY},
-\constant{LOG_NOWAIT} and \constant{LOG_PERROR} if defined in
-\code{<syslog.h>}.
-
-\end{description}
diff --git a/Doc/lib/libtabnanny.tex b/Doc/lib/libtabnanny.tex
deleted file mode 100644
index 12b9385..0000000
--- a/Doc/lib/libtabnanny.tex
+++ /dev/null
@@ -1,62 +0,0 @@
-\section{\module{tabnanny} ---
- Detection of ambiguous indentation}
-
-% rudimentary documentation based on module comments, by Peter Funk
-% <pf@artcom-gmbh.de>
-
-\declaremodule{standard}{tabnanny}
-\modulesynopsis{Tool for detecting white space related problems
- in Python source files in a directory tree.}
-\moduleauthor{Tim Peters}{tim_one@users.sourceforge.net}
-\sectionauthor{Peter Funk}{pf@artcom-gmbh.de}
-
-For the time being this module is intended to be called as a script.
-However it is possible to import it into an IDE and use the function
-\function{check()} described below.
-
-\warning{The API provided by this module is likely to change
-in future releases; such changes may not be backward compatible.}
-
-\begin{funcdesc}{check}{file_or_dir}
- If \var{file_or_dir} is a directory and not a symbolic link, then
- recursively descend the directory tree named by \var{file_or_dir},
- checking all \file{.py} files along the way. If \var{file_or_dir}
- is an ordinary Python source file, it is checked for whitespace
- related problems. The diagnostic messages are written to standard
- output using the print statement.
-\end{funcdesc}
-
-
-\begin{datadesc}{verbose}
- Flag indicating whether to print verbose messages.
- This is incremented by the \code{-v} option if called as a script.
-\end{datadesc}
-
-
-\begin{datadesc}{filename_only}
- Flag indicating whether to print only the filenames of files
- containing whitespace related problems. This is set to true by the
- \code{-q} option if called as a script.
-\end{datadesc}
-
-
-\begin{excdesc}{NannyNag}
- Raised by \function{tokeneater()} if detecting an ambiguous indent.
- Captured and handled in \function{check()}.
-\end{excdesc}
-
-
-\begin{funcdesc}{tokeneater}{type, token, start, end, line}
- This function is used by \function{check()} as a callback parameter to
- the function \function{tokenize.tokenize()}.
-\end{funcdesc}
-
-% XXX FIXME: Document \function{errprint},
-% \function{format_witnesses} \class{Whitespace}
-% check_equal, indents
-% \function{reset_globals}
-
-\begin{seealso}
- \seemodule{tokenize}{Lexical scanner for Python source code.}
- % XXX may be add a reference to IDLE?
-\end{seealso}
diff --git a/Doc/lib/libtarfile.tex b/Doc/lib/libtarfile.tex
deleted file mode 100644
index 95ea051..0000000
--- a/Doc/lib/libtarfile.tex
+++ /dev/null
@@ -1,664 +0,0 @@
-\section{\module{tarfile} --- Read and write tar archive files}
-
-\declaremodule{standard}{tarfile}
-\modulesynopsis{Read and write tar-format archive files.}
-\versionadded{2.3}
-
-\moduleauthor{Lars Gust\"abel}{lars@gustaebel.de}
-\sectionauthor{Lars Gust\"abel}{lars@gustaebel.de}
-
-The \module{tarfile} module makes it possible to read and create tar archives.
-Some facts and figures:
-
-\begin{itemize}
-\item reads and writes \module{gzip} and \module{bzip2} compressed archives.
-\item read/write support for the \POSIX{}.1-1988 (ustar) format.
-\item read/write support for the GNU tar format including \emph{longname} and
- \emph{longlink} extensions, read-only support for the \emph{sparse}
- extension.
-\item read/write support for the \POSIX{}.1-2001 (pax) format.
- \versionadded{2.6}
-\item handles directories, regular files, hardlinks, symbolic links, fifos,
- character devices and block devices and is able to acquire and
- restore file information like timestamp, access permissions and owner.
-\item can handle tape devices.
-\end{itemize}
-
-\begin{funcdesc}{open}{name\optional{, mode\optional{,
- fileobj\optional{, bufsize}}}, **kwargs}
- Return a \class{TarFile} object for the pathname \var{name}.
- For detailed information on \class{TarFile} objects and the keyword
- arguments that are allowed, see \citetitle{TarFile Objects}
- (section \ref{tarfile-objects}).
-
- \var{mode} has to be a string of the form \code{'filemode[:compression]'},
- it defaults to \code{'r'}. Here is a full list of mode combinations:
-
- \begin{tableii}{c|l}{code}{mode}{action}
- \lineii{'r' or 'r:*'}{Open for reading with transparent compression (recommended).}
- \lineii{'r:'}{Open for reading exclusively without compression.}
- \lineii{'r:gz'}{Open for reading with gzip compression.}
- \lineii{'r:bz2'}{Open for reading with bzip2 compression.}
- \lineii{'a' or 'a:'}{Open for appending with no compression. The file
- is created if it does not exist.}
- \lineii{'w' or 'w:'}{Open for uncompressed writing.}
- \lineii{'w:gz'}{Open for gzip compressed writing.}
- \lineii{'w:bz2'}{Open for bzip2 compressed writing.}
- \end{tableii}
-
- Note that \code{'a:gz'} or \code{'a:bz2'} is not possible.
- If \var{mode} is not suitable to open a certain (compressed) file for
- reading, \exception{ReadError} is raised. Use \var{mode} \code{'r'} to
- avoid this. If a compression method is not supported,
- \exception{CompressionError} is raised.
-
- If \var{fileobj} is specified, it is used as an alternative to a file
- object opened for \var{name}. It is supposed to be at position 0.
-
- For special purposes, there is a second format for \var{mode}:
- \code{'filemode|[compression]'}. \function{open()} will return a
- \class{TarFile} object that processes its data as a stream of
- blocks. No random seeking will be done on the file. If given,
- \var{fileobj} may be any object that has a \method{read()} or
- \method{write()} method (depending on the \var{mode}).
- \var{bufsize} specifies the blocksize and defaults to \code{20 *
- 512} bytes. Use this variant in combination with
- e.g. \code{sys.stdin}, a socket file object or a tape device.
- However, such a \class{TarFile} object is limited in that it does
- not allow to be accessed randomly, see ``Examples''
- (section~\ref{tar-examples}). The currently possible modes:
-
- \begin{tableii}{c|l}{code}{Mode}{Action}
- \lineii{'r|*'}{Open a \emph{stream} of tar blocks for reading with transparent compression.}
- \lineii{'r|'}{Open a \emph{stream} of uncompressed tar blocks for reading.}
- \lineii{'r|gz'}{Open a gzip compressed \emph{stream} for reading.}
- \lineii{'r|bz2'}{Open a bzip2 compressed \emph{stream} for reading.}
- \lineii{'w|'}{Open an uncompressed \emph{stream} for writing.}
- \lineii{'w|gz'}{Open an gzip compressed \emph{stream} for writing.}
- \lineii{'w|bz2'}{Open an bzip2 compressed \emph{stream} for writing.}
- \end{tableii}
-\end{funcdesc}
-
-\begin{classdesc*}{TarFile}
- Class for reading and writing tar archives. Do not use this
- class directly, better use \function{open()} instead.
- See ``TarFile Objects'' (section~\ref{tarfile-objects}).
-\end{classdesc*}
-
-\begin{funcdesc}{is_tarfile}{name}
- Return \constant{True} if \var{name} is a tar archive file, that
- the \module{tarfile} module can read.
-\end{funcdesc}
-
-\begin{classdesc}{TarFileCompat}{filename\optional{, mode\optional{,
- compression}}}
- Class for limited access to tar archives with a
- \refmodule{zipfile}-like interface. Please consult the
- documentation of the \refmodule{zipfile} module for more details.
- \var{compression} must be one of the following constants:
- \begin{datadesc}{TAR_PLAIN}
- Constant for an uncompressed tar archive.
- \end{datadesc}
- \begin{datadesc}{TAR_GZIPPED}
- Constant for a \refmodule{gzip} compressed tar archive.
- \end{datadesc}
-\end{classdesc}
-
-\begin{excdesc}{TarError}
- Base class for all \module{tarfile} exceptions.
-\end{excdesc}
-
-\begin{excdesc}{ReadError}
- Is raised when a tar archive is opened, that either cannot be handled by
- the \module{tarfile} module or is somehow invalid.
-\end{excdesc}
-
-\begin{excdesc}{CompressionError}
- Is raised when a compression method is not supported or when the data
- cannot be decoded properly.
-\end{excdesc}
-
-\begin{excdesc}{StreamError}
- Is raised for the limitations that are typical for stream-like
- \class{TarFile} objects.
-\end{excdesc}
-
-\begin{excdesc}{ExtractError}
- Is raised for \emph{non-fatal} errors when using \method{extract()}, but
- only if \member{TarFile.errorlevel}\code{ == 2}.
-\end{excdesc}
-
-\begin{excdesc}{HeaderError}
- Is raised by \method{frombuf()} if the buffer it gets is invalid.
- \versionadded{2.6}
-\end{excdesc}
-
-Each of the following constants defines a tar archive format that the
-\module{tarfile} module is able to create. See section \ref{tar-formats} for
-details.
-
-\begin{datadesc}{USTAR_FORMAT}
- \POSIX{}.1-1988 (ustar) format.
-\end{datadesc}
-
-\begin{datadesc}{GNU_FORMAT}
- GNU tar format.
-\end{datadesc}
-
-\begin{datadesc}{PAX_FORMAT}
- \POSIX{}.1-2001 (pax) format.
-\end{datadesc}
-
-\begin{datadesc}{DEFAULT_FORMAT}
- The default format for creating archives. This is currently
- \constant{GNU_FORMAT}.
-\end{datadesc}
-
-\begin{seealso}
- \seemodule{zipfile}{Documentation of the \refmodule{zipfile}
- standard module.}
-
- \seetitle[http://www.gnu.org/software/tar/manual/html_node/tar_134.html\#SEC134]
- {GNU tar manual, Basic Tar Format}{Documentation for tar archive files,
- including GNU tar extensions.}
-\end{seealso}
-
-%-----------------
-% TarFile Objects
-%-----------------
-
-\subsection{TarFile Objects \label{tarfile-objects}}
-
-The \class{TarFile} object provides an interface to a tar archive. A tar
-archive is a sequence of blocks. An archive member (a stored file) is made up
-of a header block followed by data blocks. It is possible to store a file in a
-tar archive several times. Each archive member is represented by a
-\class{TarInfo} object, see \citetitle{TarInfo Objects} (section
-\ref{tarinfo-objects}) for details.
-
-\begin{classdesc}{TarFile}{name=None, mode='r', fileobj=None,
- format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False,
- ignore_zeros=False, encoding=None, errors=None, pax_headers=None,
- debug=0, errorlevel=0}
-
- All following arguments are optional and can be accessed as instance
- attributes as well.
-
- \var{name} is the pathname of the archive. It can be omitted if
- \var{fileobj} is given. In this case, the file object's \member{name}
- attribute is used if it exists.
-
- \var{mode} is either \code{'r'} to read from an existing archive,
- \code{'a'} to append data to an existing file or \code{'w'} to create a new
- file overwriting an existing one.
-
- If \var{fileobj} is given, it is used for reading or writing data.
- If it can be determined, \var{mode} is overridden by \var{fileobj}'s mode.
- \var{fileobj} will be used from position 0.
- \begin{notice}
- \var{fileobj} is not closed, when \class{TarFile} is closed.
- \end{notice}
-
- \var{format} controls the archive format. It must be one of the constants
- \constant{USTAR_FORMAT}, \constant{GNU_FORMAT} or \constant{PAX_FORMAT}
- that are defined at module level.
- \versionadded{2.6}
-
- The \var{tarinfo} argument can be used to replace the default
- \class{TarInfo} class with a different one.
- \versionadded{2.6}
-
- If \var{dereference} is \code{False}, add symbolic and hard links to the
- archive. If it is \code{True}, add the content of the target files to the
- archive. This has no effect on systems that do not support symbolic links.
-
- If \var{ignore_zeros} is \code{False}, treat an empty block as the end of
- the archive. If it is \var{True}, skip empty (and invalid) blocks and try
- to get as many members as possible. This is only useful for reading
- concatenated or damaged archives.
-
- \var{debug} can be set from \code{0} (no debug messages) up to \code{3}
- (all debug messages). The messages are written to \code{sys.stderr}.
-
- If \var{errorlevel} is \code{0}, all errors are ignored when using
- \method{extract()}. Nevertheless, they appear as error messages in the
- debug output, when debugging is enabled. If \code{1}, all \emph{fatal}
- errors are raised as \exception{OSError} or \exception{IOError} exceptions.
- If \code{2}, all \emph{non-fatal} errors are raised as \exception{TarError}
- exceptions as well.
-
- The \var{encoding} and \var{errors} arguments control the way strings are
- converted to unicode objects and vice versa. The default settings will work
- for most users. See section \ref{tar-unicode} for in-depth information.
- \versionadded{2.6}
-
- The \var{pax_headers} argument is an optional dictionary of unicode strings
- which will be added as a pax global header if \var{format} is
- \constant{PAX_FORMAT}.
- \versionadded{2.6}
-\end{classdesc}
-
-\begin{methoddesc}{open}{...}
- Alternative constructor. The \function{open()} function on module level is
- actually a shortcut to this classmethod. See section~\ref{module-tarfile}
- for details.
-\end{methoddesc}
-
-\begin{methoddesc}{getmember}{name}
- Return a \class{TarInfo} object for member \var{name}. If \var{name} can
- not be found in the archive, \exception{KeyError} is raised.
- \begin{notice}
- If a member occurs more than once in the archive, its last
- occurrence is assumed to be the most up-to-date version.
- \end{notice}
-\end{methoddesc}
-
-\begin{methoddesc}{getmembers}{}
- Return the members of the archive as a list of \class{TarInfo} objects.
- The list has the same order as the members in the archive.
-\end{methoddesc}
-
-\begin{methoddesc}{getnames}{}
- Return the members as a list of their names. It has the same order as
- the list returned by \method{getmembers()}.
-\end{methoddesc}
-
-\begin{methoddesc}{list}{verbose=True}
- Print a table of contents to \code{sys.stdout}. If \var{verbose} is
- \constant{False}, only the names of the members are printed. If it is
- \constant{True}, output similar to that of \program{ls -l} is produced.
-\end{methoddesc}
-
-\begin{methoddesc}{next}{}
- Return the next member of the archive as a \class{TarInfo} object, when
- \class{TarFile} is opened for reading. Return \code{None} if there is no
- more available.
-\end{methoddesc}
-
-\begin{methoddesc}{extractall}{\optional{path\optional{, members}}}
- Extract all members from the archive to the current working directory
- or directory \var{path}. If optional \var{members} is given, it must be
- a subset of the list returned by \method{getmembers()}.
- Directory information like owner, modification time and permissions are
- set after all members have been extracted. This is done to work around two
- problems: A directory's modification time is reset each time a file is
- created in it. And, if a directory's permissions do not allow writing,
- extracting files to it will fail.
- \versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{extract}{member\optional{, path}}
- Extract a member from the archive to the current working directory,
- using its full name. Its file information is extracted as accurately as
- possible.
- \var{member} may be a filename or a \class{TarInfo} object.
- You can specify a different directory using \var{path}.
- \begin{notice}
- Because the \method{extract()} method allows random access to a tar
- archive there are some issues you must take care of yourself. See the
- description for \method{extractall()} above.
- \end{notice}
-\end{methoddesc}
-
-\begin{methoddesc}{extractfile}{member}
- Extract a member from the archive as a file object.
- \var{member} may be a filename or a \class{TarInfo} object.
- If \var{member} is a regular file, a file-like object is returned.
- If \var{member} is a link, a file-like object is constructed from the
- link's target.
- If \var{member} is none of the above, \code{None} is returned.
- \begin{notice}
- The file-like object is read-only and provides the following methods:
- \method{read()}, \method{readline()}, \method{readlines()},
- \method{seek()}, \method{tell()}.
- \end{notice}
-\end{methoddesc}
-
-\begin{methoddesc}{add}{name\optional{, arcname\optional{, recursive\optional{, exclude}}}}
- Add the file \var{name} to the archive. \var{name} may be any type
- of file (directory, fifo, symbolic link, etc.).
- If given, \var{arcname} specifies an alternative name for the file in the
- archive. Directories are added recursively by default.
- This can be avoided by setting \var{recursive} to \constant{False}.
- If \var{exclude} is given it must be a function that takes one filename
- argument and returns a boolean value. Depending on this value the
- respective file is either excluded (\constant{True}) or added
- (\constant{False}).
- \versionchanged[Added the \var{exclude} parameter]{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}{addfile}{tarinfo\optional{, fileobj}}
- Add the \class{TarInfo} object \var{tarinfo} to the archive.
- If \var{fileobj} is given, \code{\var{tarinfo}.size} bytes are read
- from it and added to the archive. You can create \class{TarInfo} objects
- using \method{gettarinfo()}.
- \begin{notice}
- On Windows platforms, \var{fileobj} should always be opened with mode
- \code{'rb'} to avoid irritation about the file size.
- \end{notice}
-\end{methoddesc}
-
-\begin{methoddesc}{gettarinfo}{\optional{name\optional{,
- arcname\optional{, fileobj}}}}
- Create a \class{TarInfo} object for either the file \var{name} or
- the file object \var{fileobj} (using \function{os.fstat()} on its
- file descriptor). You can modify some of the \class{TarInfo}'s
- attributes before you add it using \method{addfile()}. If given,
- \var{arcname} specifies an alternative name for the file in the
- archive.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
- Close the \class{TarFile}. In write mode, two finishing zero
- blocks are appended to the archive.
-\end{methoddesc}
-
-\begin{memberdesc}{posix}
- Setting this to \constant{True} is equivalent to setting the
- \member{format} attribute to \constant{USTAR_FORMAT},
- \constant{False} is equivalent to \constant{GNU_FORMAT}.
- \versionchanged[\var{posix} defaults to \constant{False}]{2.4}
- \deprecated{2.6}{Use the \member{format} attribute instead.}
-\end{memberdesc}
-
-\begin{memberdesc}{pax_headers}
- A dictionary containing key-value pairs of pax global headers.
- \versionadded{2.6}
-\end{memberdesc}
-
-%-----------------
-% TarInfo Objects
-%-----------------
-
-\subsection{TarInfo Objects \label{tarinfo-objects}}
-
-A \class{TarInfo} object represents one member in a
-\class{TarFile}. Aside from storing all required attributes of a file
-(like file type, size, time, permissions, owner etc.), it provides
-some useful methods to determine its type. It does \emph{not} contain
-the file's data itself.
-
-\class{TarInfo} objects are returned by \class{TarFile}'s methods
-\method{getmember()}, \method{getmembers()} and \method{gettarinfo()}.
-
-\begin{classdesc}{TarInfo}{\optional{name}}
- Create a \class{TarInfo} object.
-\end{classdesc}
-
-\begin{methoddesc}{frombuf}{buf}
- Create and return a \class{TarInfo} object from string buffer \var{buf}.
- \versionadded[Raises \exception{HeaderError} if the buffer is
- invalid.]{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}{fromtarfile}{tarfile}
- Read the next member from the \class{TarFile} object \var{tarfile} and
- return it as a \class{TarInfo} object.
- \versionadded{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}{tobuf}{\optional{format\optional{, encoding
- \optional{, errors}}}}
- Create a string buffer from a \class{TarInfo} object. For information
- on the arguments see the constructor of the \class{TarFile} class.
- \versionchanged[The arguments were added]{2.6}
-\end{methoddesc}
-
-A \code{TarInfo} object has the following public data attributes:
-
-\begin{memberdesc}{name}
- Name of the archive member.
-\end{memberdesc}
-
-\begin{memberdesc}{size}
- Size in bytes.
-\end{memberdesc}
-
-\begin{memberdesc}{mtime}
- Time of last modification.
-\end{memberdesc}
-
-\begin{memberdesc}{mode}
- Permission bits.
-\end{memberdesc}
-
-\begin{memberdesc}{type}
- File type. \var{type} is usually one of these constants:
- \constant{REGTYPE}, \constant{AREGTYPE}, \constant{LNKTYPE},
- \constant{SYMTYPE}, \constant{DIRTYPE}, \constant{FIFOTYPE},
- \constant{CONTTYPE}, \constant{CHRTYPE}, \constant{BLKTYPE},
- \constant{GNUTYPE_SPARSE}. To determine the type of a
- \class{TarInfo} object more conveniently, use the \code{is_*()}
- methods below.
-\end{memberdesc}
-
-\begin{memberdesc}{linkname}
- Name of the target file name, which is only present in
- \class{TarInfo} objects of type \constant{LNKTYPE} and
- \constant{SYMTYPE}.
-\end{memberdesc}
-
-\begin{memberdesc}{uid}
- User ID of the user who originally stored this member.
-\end{memberdesc}
-
-\begin{memberdesc}{gid}
- Group ID of the user who originally stored this member.
-\end{memberdesc}
-
-\begin{memberdesc}{uname}
- User name.
-\end{memberdesc}
-
-\begin{memberdesc}{gname}
- Group name.
-\end{memberdesc}
-
-\begin{memberdesc}{pax_headers}
- A dictionary containing key-value pairs of an associated pax
- extended header.
- \versionadded{2.6}
-\end{memberdesc}
-
-A \class{TarInfo} object also provides some convenient query methods:
-
-\begin{methoddesc}{isfile}{}
- Return \constant{True} if the \class{Tarinfo} object is a regular
- file.
-\end{methoddesc}
-
-\begin{methoddesc}{isreg}{}
- Same as \method{isfile()}.
-\end{methoddesc}
-
-\begin{methoddesc}{isdir}{}
- Return \constant{True} if it is a directory.
-\end{methoddesc}
-
-\begin{methoddesc}{issym}{}
- Return \constant{True} if it is a symbolic link.
-\end{methoddesc}
-
-\begin{methoddesc}{islnk}{}
- Return \constant{True} if it is a hard link.
-\end{methoddesc}
-
-\begin{methoddesc}{ischr}{}
- Return \constant{True} if it is a character device.
-\end{methoddesc}
-
-\begin{methoddesc}{isblk}{}
- Return \constant{True} if it is a block device.
-\end{methoddesc}
-
-\begin{methoddesc}{isfifo}{}
- Return \constant{True} if it is a FIFO.
-\end{methoddesc}
-
-\begin{methoddesc}{isdev}{}
- Return \constant{True} if it is one of character device, block
- device or FIFO.
-\end{methoddesc}
-
-%------------------------
-% Examples
-%------------------------
-
-\subsection{Examples \label{tar-examples}}
-
-How to extract an entire tar archive to the current working directory:
-\begin{verbatim}
-import tarfile
-tar = tarfile.open("sample.tar.gz")
-tar.extractall()
-tar.close()
-\end{verbatim}
-
-How to create an uncompressed tar archive from a list of filenames:
-\begin{verbatim}
-import tarfile
-tar = tarfile.open("sample.tar", "w")
-for name in ["foo", "bar", "quux"]:
- tar.add(name)
-tar.close()
-\end{verbatim}
-
-How to read a gzip compressed tar archive and display some member information:
-\begin{verbatim}
-import tarfile
-tar = tarfile.open("sample.tar.gz", "r:gz")
-for tarinfo in tar:
- print tarinfo.name, "is", tarinfo.size, "bytes in size and is",
- if tarinfo.isreg():
- print "a regular file."
- elif tarinfo.isdir():
- print "a directory."
- else:
- print "something else."
-tar.close()
-\end{verbatim}
-
-How to create a tar archive with faked information:
-\begin{verbatim}
-import tarfile
-tar = tarfile.open("sample.tar.gz", "w:gz")
-for name in namelist:
- tarinfo = tar.gettarinfo(name, "fakeproj-1.0/" + name)
- tarinfo.uid = 123
- tarinfo.gid = 456
- tarinfo.uname = "johndoe"
- tarinfo.gname = "fake"
- tar.addfile(tarinfo, file(name))
-tar.close()
-\end{verbatim}
-
-The \emph{only} way to extract an uncompressed tar stream from
-\code{sys.stdin}:
-\begin{verbatim}
-import sys
-import tarfile
-tar = tarfile.open(mode="r|", fileobj=sys.stdin)
-for tarinfo in tar:
- tar.extract(tarinfo)
-tar.close()
-\end{verbatim}
-
-%------------
-% Tar format
-%------------
-
-\subsection{Supported tar formats \label{tar-formats}}
-
-There are three tar formats that can be created with the \module{tarfile}
-module:
-
-\begin{itemize}
-
-\item
-The \POSIX{}.1-1988 ustar format (\constant{USTAR_FORMAT}). It supports
-filenames up to a length of at best 256 characters and linknames up to 100
-characters. The maximum file size is 8 gigabytes. This is an old and limited
-but widely supported format.
-
-\item
-The GNU tar format (\constant{GNU_FORMAT}). It supports long filenames and
-linknames, files bigger than 8 gigabytes and sparse files. It is the de facto
-standard on GNU/Linux systems. \module{tarfile} fully supports the GNU tar
-extensions for long names, sparse file support is read-only.
-
-\item
-The \POSIX{}.1-2001 pax format (\constant{PAX_FORMAT}). It is the most
-flexible format with virtually no limits. It supports long filenames and
-linknames, large files and stores pathnames in a portable way. However, not
-all tar implementations today are able to handle pax archives properly.
-
-The \emph{pax} format is an extension to the existing \emph{ustar} format. It
-uses extra headers for information that cannot be stored otherwise. There are
-two flavours of pax headers: Extended headers only affect the subsequent file
-header, global headers are valid for the complete archive and affect all
-following files. All the data in a pax header is encoded in \emph{UTF-8} for
-portability reasons.
-
-\end{itemize}
-
-There are some more variants of the tar format which can be read, but not
-created:
-
-\begin{itemize}
-
-\item
-The ancient V7 format. This is the first tar format from \UNIX{} Seventh
-Edition, storing only regular files and directories. Names must not be longer
-than 100 characters, there is no user/group name information. Some archives
-have miscalculated header checksums in case of fields with non-\ASCII{}
-characters.
-
-\item
-The SunOS tar extended format. This format is a variant of the \POSIX{}.1-2001
-pax format, but is not compatible.
-
-\end{itemize}
-
-%----------------
-% Unicode issues
-%----------------
-
-\subsection{Unicode issues \label{tar-unicode}}
-
-The tar format was originally conceived to make backups on tape drives with the
-main focus on preserving file system information. Nowadays tar archives are
-commonly used for file distribution and exchanging archives over networks. One
-problem of the original format (that all other formats are merely variants of)
-is that there is no concept of supporting different character encodings.
-For example, an ordinary tar archive created on a \emph{UTF-8} system cannot be
-read correctly on a \emph{Latin-1} system if it contains non-\ASCII{}
-characters. Names (i.e. filenames, linknames, user/group names) containing
-these characters will appear damaged. Unfortunately, there is no way to
-autodetect the encoding of an archive.
-
-The pax format was designed to solve this problem. It stores non-\ASCII{} names
-using the universal character encoding \emph{UTF-8}. When a pax archive is
-read, these \emph{UTF-8} names are converted to the encoding of the local
-file system.
-
-The details of unicode conversion are controlled by the \var{encoding} and
-\var{errors} keyword arguments of the \class{TarFile} class.
-
-The default value for \var{encoding} is the local character encoding. It is
-deduced from \function{sys.getfilesystemencoding()} and
-\function{sys.getdefaultencoding()}. In read mode, \var{encoding} is used
-exclusively to convert unicode names from a pax archive to strings in the local
-character encoding. In write mode, the use of \var{encoding} depends on the
-chosen archive format. In case of \constant{PAX_FORMAT}, input names that
-contain non-\ASCII{} characters need to be decoded before being stored as
-\emph{UTF-8} strings. The other formats do not make use of \var{encoding}
-unless unicode objects are used as input names. These are converted to
-8-bit character strings before they are added to the archive.
-
-The \var{errors} argument defines how characters are treated that cannot be
-converted to or from \var{encoding}. Possible values are listed in section
-\ref{codec-base-classes}. In read mode, there is an additional scheme
-\code{'utf-8'} which means that bad characters are replaced by their
-\emph{UTF-8} representation. This is the default scheme. In write mode the
-default value for \var{errors} is \code{'strict'} to ensure that name
-information is not altered unnoticed.
diff --git a/Doc/lib/libtelnetlib.tex b/Doc/lib/libtelnetlib.tex
deleted file mode 100644
index 853788f..0000000
--- a/Doc/lib/libtelnetlib.tex
+++ /dev/null
@@ -1,228 +0,0 @@
-\section{\module{telnetlib} ---
- Telnet client}
-
-\declaremodule{standard}{telnetlib}
-\modulesynopsis{Telnet client class.}
-\sectionauthor{Skip Montanaro}{skip@mojam.com}
-
-\index{protocol!Telnet}
-
-The \module{telnetlib} module provides a \class{Telnet} class that
-implements the Telnet protocol. See \rfc{854} for details about the
-protocol. In addition, it provides symbolic constants for the protocol
-characters (see below), and for the telnet options. The
-symbolic names of the telnet options follow the definitions in
-\code{arpa/telnet.h}, with the leading \code{TELOPT_} removed. For
-symbolic names of options which are traditionally not included in
-\code{arpa/telnet.h}, see the module source itself.
-
-The symbolic constants for the telnet commands are: IAC, DONT, DO,
-WONT, WILL, SE (Subnegotiation End), NOP (No Operation), DM (Data
-Mark), BRK (Break), IP (Interrupt process), AO (Abort output), AYT
-(Are You There), EC (Erase Character), EL (Erase Line), GA (Go Ahead),
-SB (Subnegotiation Begin).
-
-
-\begin{classdesc}{Telnet}{\optional{host\optional{, port\optional{, timeout}}}}
-\class{Telnet} represents a connection to a Telnet server. The
-instance is initially not connected by default; the \method{open()}
-method must be used to establish a connection. Alternatively, the
-host name and optional port number can be passed to the constructor,
-to, in which case the connection to the server will be established
-before the constructor returns.
-The optional \var{timeout} parameter specifies a timeout in seconds for the
-connection attempt (if not specified, or passed as None, the global default
-timeout setting will be used).
-
-Do not reopen an already connected instance.
-
-This class has many \method{read_*()} methods. Note that some of them
-raise \exception{EOFError} when the end of the connection is read,
-because they can return an empty string for other reasons. See the
-individual descriptions below.
-\versionchanged[\var{timeout} was added]{2.6}
-\end{classdesc}
-
-
-\begin{seealso}
- \seerfc{854}{Telnet Protocol Specification}{
- Definition of the Telnet protocol.}
-\end{seealso}
-
-
-
-\subsection{Telnet Objects \label{telnet-objects}}
-
-\class{Telnet} instances have the following methods:
-
-
-\begin{methoddesc}[Telnet]{read_until}{expected\optional{, timeout}}
-Read until a given string, \var{expected}, is encountered or until
-\var{timeout} seconds have passed.
-
-When no match is found, return whatever is available instead,
-possibly the empty string. Raise \exception{EOFError} if the connection
-is closed and no cooked data is available.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{read_all}{}
-Read all data until \EOF; block until connection closed.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{read_some}{}
-Read at least one byte of cooked data unless \EOF{} is hit.
-Return \code{''} if \EOF{} is hit. Block if no data is immediately
-available.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{read_very_eager}{}
-Read everything that can be without blocking in I/O (eager).
-
-Raise \exception{EOFError} if connection closed and no cooked data
-available. Return \code{''} if no cooked data available otherwise.
-Do not block unless in the midst of an IAC sequence.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{read_eager}{}
-Read readily available data.
-
-Raise \exception{EOFError} if connection closed and no cooked data
-available. Return \code{''} if no cooked data available otherwise.
-Do not block unless in the midst of an IAC sequence.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{read_lazy}{}
-Process and return data already in the queues (lazy).
-
-Raise \exception{EOFError} if connection closed and no data available.
-Return \code{''} if no cooked data available otherwise. Do not block
-unless in the midst of an IAC sequence.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{read_very_lazy}{}
-Return any data available in the cooked queue (very lazy).
-
-Raise \exception{EOFError} if connection closed and no data available.
-Return \code{''} if no cooked data available otherwise. This method
-never blocks.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{read_sb_data}{}
-Return the data collected between a SB/SE pair (suboption begin/end).
-The callback should access these data when it was invoked with a
-\code{SE} command. This method never blocks.
-
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{open}{host\optional{, port\optional{, timeout}}}
-Connect to a host.
-The optional second argument is the port number, which
-defaults to the standard Telnet port (23).
-The optional \var{timeout} parameter specifies a timeout in seconds for the
-connection attempt (if not specified, or passed as None, the global default
-timeout setting will be used).
-
-Do not try to reopen an already connected instance.
-\versionchanged[\var{timeout} was added]{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{msg}{msg\optional{, *args}}
-Print a debug message when the debug level is \code{>} 0.
-If extra arguments are present, they are substituted in the
-message using the standard string formatting operator.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{set_debuglevel}{debuglevel}
-Set the debug level. The higher the value of \var{debuglevel}, the
-more debug output you get (on \code{sys.stdout}).
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{close}{}
-Close the connection.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{get_socket}{}
-Return the socket object used internally.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{fileno}{}
-Return the file descriptor of the socket object used internally.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{write}{buffer}
-Write a string to the socket, doubling any IAC characters.
-This can block if the connection is blocked. May raise
-\exception{socket.error} if the connection is closed.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{interact}{}
-Interaction function, emulates a very dumb Telnet client.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{mt_interact}{}
-Multithreaded version of \method{interact()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{expect}{list\optional{, timeout}}
-Read until one from a list of a regular expressions matches.
-
-The first argument is a list of regular expressions, either
-compiled (\class{re.RegexObject} instances) or uncompiled (strings).
-The optional second argument is a timeout, in seconds; the default
-is to block indefinitely.
-
-Return a tuple of three items: the index in the list of the
-first regular expression that matches; the match object
-returned; and the text read up till and including the match.
-
-If end of file is found and no text was read, raise
-\exception{EOFError}. Otherwise, when nothing matches, return
-\code{(-1, None, \var{text})} where \var{text} is the text received so
-far (may be the empty string if a timeout happened).
-
-If a regular expression ends with a greedy match (such as \regexp{.*})
-or if more than one expression can match the same input, the
-results are indeterministic, and may depend on the I/O timing.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{set_option_negotiation_callback}{callback}
-Each time a telnet option is read on the input flow, this
-\var{callback} (if set) is called with the following parameters :
-callback(telnet socket, command (DO/DONT/WILL/WONT), option). No other
-action is done afterwards by telnetlib.
-\end{methoddesc}
-
-
-\subsection{Telnet Example \label{telnet-example}}
-\sectionauthor{Peter Funk}{pf@artcom-gmbh.de}
-
-A simple example illustrating typical use:
-
-\begin{verbatim}
-import getpass
-import sys
-import telnetlib
-
-def raw_input(prompt):
- sys.stdout.write(prompt)
- sys.stdout.flush()
- return sys.stdin.readline()
-
-HOST = "localhost"
-user = raw_input("Enter your remote account: ")
-password = getpass.getpass()
-
-tn = telnetlib.Telnet(HOST)
-
-tn.read_until("login: ")
-tn.write(user + "\n")
-if password:
- tn.read_until("Password: ")
- tn.write(password + "\n")
-
-tn.write("ls\n")
-tn.write("exit\n")
-
-print tn.read_all()
-\end{verbatim}
diff --git a/Doc/lib/libtempfile.tex b/Doc/lib/libtempfile.tex
deleted file mode 100644
index 8bc559e..0000000
--- a/Doc/lib/libtempfile.tex
+++ /dev/null
@@ -1,214 +0,0 @@
-\section{\module{tempfile} ---
- Generate temporary files and directories}
-\sectionauthor{Zack Weinberg}{zack@codesourcery.com}
-
-\declaremodule{standard}{tempfile}
-\modulesynopsis{Generate temporary files and directories.}
-
-\indexii{temporary}{file name}
-\indexii{temporary}{file}
-
-This module generates temporary files and directories. It works on
-all supported platforms.
-
-In version 2.3 of Python, this module was overhauled for enhanced
-security. It now provides three new functions,
-\function{NamedTemporaryFile()}, \function{mkstemp()}, and
-\function{mkdtemp()}, which should eliminate all remaining need to use
-the insecure \function{mktemp()} function. Temporary file names created
-by this module no longer contain the process ID; instead a string of
-six random characters is used.
-
-Also, all the user-callable functions now take additional arguments
-which allow direct control over the location and name of temporary
-files. It is no longer necessary to use the global \var{tempdir} and
-\var{template} variables. To maintain backward compatibility, the
-argument order is somewhat odd; it is recommended to use keyword
-arguments for clarity.
-
-The module defines the following user-callable functions:
-
-\begin{funcdesc}{TemporaryFile}{\optional{mode=\code{'w+b'}\optional{,
- bufsize=\code{-1}\optional{,
- suffix\optional{, prefix\optional{, dir}}}}}}
-Return a file (or file-like) object that can be used as a temporary
-storage area. The file is created using \function{mkstemp}. It will
-be destroyed as soon as it is closed (including an implicit close when
-the object is garbage collected). Under \UNIX, the directory entry
-for the file is removed immediately after the file is created. Other
-platforms do not support this; your code should not rely on a
-temporary file created using this function having or not having a
-visible name in the file system.
-
-The \var{mode} parameter defaults to \code{'w+b'} so that the file
-created can be read and written without being closed. Binary mode is
-used so that it behaves consistently on all platforms without regard
-for the data that is stored. \var{bufsize} defaults to \code{-1},
-meaning that the operating system default is used.
-
-The \var{dir}, \var{prefix} and \var{suffix} parameters are passed to
-\function{mkstemp()}.
-\end{funcdesc}
-
-\begin{funcdesc}{NamedTemporaryFile}{\optional{mode=\code{'w+b'}\optional{,
- bufsize=\code{-1}\optional{,
- suffix\optional{, prefix\optional{,
- dir\optional{, delete}}}}}}}
-This function operates exactly as \function{TemporaryFile()} does,
-except that the file is guaranteed to have a visible name in the file
-system (on \UNIX, the directory entry is not unlinked). That name can
-be retrieved from the \member{name} member of the file object. Whether
-the name can be used to open the file a second time, while the
-named temporary file is still open, varies across platforms (it can
-be so used on \UNIX; it cannot on Windows NT or later).
-If \var{delete} is true (the default), the file is deleted as soon as
-it is closed.
-\versionadded{2.3}
-\versionadded[The \var{delete} parameter]{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{SpooledTemporaryFile}{\optional{max\_size=\code{0},
- \optional{mode=\code{'w+b'}\optional{,
- bufsize=\code{-1}\optional{,
- suffix\optional{, prefix\optional{,
- dir}}}}}}}
-This function operates exactly as \function{TemporaryFile()} does,
-except that data is spooled in memory until the file size exceeds
-\var{max_size}, or until the file's \function{fileno()} method is
-called, at which point the contents are written to disk and operation
-proceeds as with \function{TemporaryFile()}.
-
-The resulting file has one additional method, \function{rollover()},
-which causes the file to roll over to an on-disk file regardless of
-its size.
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{mkstemp}{\optional{suffix\optional{,
- prefix\optional{, dir\optional{, text}}}}}
-Creates a temporary file in the most secure manner possible. There
-are no race conditions in the file's creation, assuming that the
-platform properly implements the \constant{O_EXCL} flag for
-\function{os.open()}. The file is readable and writable only by the
-creating user ID. If the platform uses permission bits to indicate
-whether a file is executable, the file is executable by no one. The
-file descriptor is not inherited by child processes.
-
-Unlike \function{TemporaryFile()}, the user of \function{mkstemp()} is
-responsible for deleting the temporary file when done with it.
-
-If \var{suffix} is specified, the file name will end with that suffix,
-otherwise there will be no suffix. \function{mkstemp()} does not put a
-dot between the file name and the suffix; if you need one, put it at
-the beginning of \var{suffix}.
-
-If \var{prefix} is specified, the file name will begin with that
-prefix; otherwise, a default prefix is used.
-
-If \var{dir} is specified, the file will be created in that directory;
-otherwise, a default directory is used. The default directory is chosen
-from a platform-dependent list, but the user of the application can control
-the directory location by setting the \var{TMPDIR}, \var{TEMP} or \var{TMP}
-environment variables. There is thus no guarantee that the generated
-filename will have any nice properties, such as not requiring quoting when
-passed to external commands via \code{os.popen()}.
-
-If \var{text} is specified, it indicates whether to open the file in
-binary mode (the default) or text mode. On some platforms, this makes
-no difference.
-
-\function{mkstemp()} returns a tuple containing an OS-level handle to
-an open file (as would be returned by \function{os.open()}) and the
-absolute pathname of that file, in that order.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{mkdtemp}{\optional{suffix\optional{, prefix\optional{, dir}}}}
-Creates a temporary directory in the most secure manner possible.
-There are no race conditions in the directory's creation. The
-directory is readable, writable, and searchable only by the
-creating user ID.
-
-The user of \function{mkdtemp()} is responsible for deleting the
-temporary directory and its contents when done with it.
-
-The \var{prefix}, \var{suffix}, and \var{dir} arguments are the same
-as for \function{mkstemp()}.
-
-\function{mkdtemp()} returns the absolute pathname of the new directory.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{mktemp}{\optional{suffix\optional{, prefix\optional{, dir}}}}
-\deprecated{2.3}{Use \function{mkstemp()} instead.}
-Return an absolute pathname of a file that did not exist at the time
-the call is made. The \var{prefix}, \var{suffix}, and \var{dir}
-arguments are the same as for \function{mkstemp()}.
-
-\warning{Use of this function may introduce a security hole in your
-program. By the time you get around to doing anything with the file
-name it returns, someone else may have beaten you to the punch.}
-\end{funcdesc}
-
-The module uses two global variables that tell it how to construct a
-temporary name. They are initialized at the first call to any of the
-functions above. The caller may change them, but this is discouraged;
-use the appropriate function arguments, instead.
-
-\begin{datadesc}{tempdir}
-When set to a value other than \code{None}, this variable defines the
-default value for the \var{dir} argument to all the functions defined
-in this module.
-
-If \code{tempdir} is unset or \code{None} at any call to any of the
-above functions, Python searches a standard list of directories and
-sets \var{tempdir} to the first one which the calling user can create
-files in. The list is:
-
-\begin{enumerate}
-\item The directory named by the \envvar{TMPDIR} environment variable.
-\item The directory named by the \envvar{TEMP} environment variable.
-\item The directory named by the \envvar{TMP} environment variable.
-\item A platform-specific location:
- \begin{itemize}
- \item On RiscOS, the directory named by the
- \envvar{Wimp\$ScrapDir} environment variable.
- \item On Windows, the directories
- \file{C:$\backslash$TEMP},
- \file{C:$\backslash$TMP},
- \file{$\backslash$TEMP}, and
- \file{$\backslash$TMP}, in that order.
- \item On all other platforms, the directories
- \file{/tmp}, \file{/var/tmp}, and \file{/usr/tmp}, in that order.
- \end{itemize}
-\item As a last resort, the current working directory.
-\end{enumerate}
-\end{datadesc}
-
-\begin{funcdesc}{gettempdir}{}
-Return the directory currently selected to create temporary files in.
-If \code{tempdir} is not \code{None}, this simply returns its contents;
-otherwise, the search described above is performed, and the result
-returned.
-\end{funcdesc}
-
-\begin{datadesc}{template}
-\deprecated{2.0}{Use \function{gettempprefix()} instead.}
-When set to a value other than \code{None}, this variable defines the
-prefix of the final component of the filenames returned by
-\function{mktemp()}. A string of six random letters and digits is
-appended to the prefix to make the filename unique. On Windows,
-the default prefix is \file{\textasciitilde{}T}; on all other systems
-it is \file{tmp}.
-
-Older versions of this module used to require that \code{template} be
-set to \code{None} after a call to \function{os.fork()}; this has not
-been necessary since version 1.5.2.
-\end{datadesc}
-
-\begin{funcdesc}{gettempprefix}{}
-Return the filename prefix used to create temporary files. This does
-not contain the directory component. Using this function is preferred
-over reading the \var{template} variable directly.
-\versionadded{1.5.2}
-\end{funcdesc}
diff --git a/Doc/lib/libtermios.tex b/Doc/lib/libtermios.tex
deleted file mode 100644
index 64f3438..0000000
--- a/Doc/lib/libtermios.tex
+++ /dev/null
@@ -1,112 +0,0 @@
-\section{\module{termios} ---
- \POSIX{} style tty control}
-
-\declaremodule{builtin}{termios}
- \platform{Unix}
-\modulesynopsis{\POSIX\ style tty control.}
-
-\indexii{\POSIX}{I/O control}
-\indexii{tty}{I/O control}
-
-
-This module provides an interface to the \POSIX{} calls for tty I/O
-control. For a complete description of these calls, see the \POSIX{} or
-\UNIX{} manual pages. It is only available for those \UNIX{} versions
-that support \POSIX{} \emph{termios} style tty I/O control (and then
-only if configured at installation time).
-
-All functions in this module take a file descriptor \var{fd} as their
-first argument. This can be an integer file descriptor, such as
-returned by \code{sys.stdin.fileno()}, or a file object, such as
-\code{sys.stdin} itself.
-
-This module also defines all the constants needed to work with the
-functions provided here; these have the same name as their
-counterparts in C. Please refer to your system documentation for more
-information on using these terminal control interfaces.
-
-The module defines the following functions:
-
-\begin{funcdesc}{tcgetattr}{fd}
-Return a list containing the tty attributes for file descriptor
-\var{fd}, as follows: \code{[}\var{iflag}, \var{oflag}, \var{cflag},
-\var{lflag}, \var{ispeed}, \var{ospeed}, \var{cc}\code{]} where
-\var{cc} is a list of the tty special characters (each a string of
-length 1, except the items with indices \constant{VMIN} and
-\constant{VTIME}, which are integers when these fields are
-defined). The interpretation of the flags and the speeds as well as
-the indexing in the \var{cc} array must be done using the symbolic
-constants defined in the \module{termios}
-module.
-\end{funcdesc}
-
-\begin{funcdesc}{tcsetattr}{fd, when, attributes}
-Set the tty attributes for file descriptor \var{fd} from the
-\var{attributes}, which is a list like the one returned by
-\function{tcgetattr()}. The \var{when} argument determines when the
-attributes are changed: \constant{TCSANOW} to change immediately,
-\constant{TCSADRAIN} to change after transmitting all queued output,
-or \constant{TCSAFLUSH} to change after transmitting all queued
-output and discarding all queued input.
-\end{funcdesc}
-
-\begin{funcdesc}{tcsendbreak}{fd, duration}
-Send a break on file descriptor \var{fd}. A zero \var{duration} sends
-a break for 0.25--0.5 seconds; a nonzero \var{duration} has a system
-dependent meaning.
-\end{funcdesc}
-
-\begin{funcdesc}{tcdrain}{fd}
-Wait until all output written to file descriptor \var{fd} has been
-transmitted.
-\end{funcdesc}
-
-\begin{funcdesc}{tcflush}{fd, queue}
-Discard queued data on file descriptor \var{fd}. The \var{queue}
-selector specifies which queue: \constant{TCIFLUSH} for the input
-queue, \constant{TCOFLUSH} for the output queue, or
-\constant{TCIOFLUSH} for both queues.
-\end{funcdesc}
-
-\begin{funcdesc}{tcflow}{fd, action}
-Suspend or resume input or output on file descriptor \var{fd}. The
-\var{action} argument can be \constant{TCOOFF} to suspend output,
-\constant{TCOON} to restart output, \constant{TCIOFF} to suspend
-input, or \constant{TCION} to restart input.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{tty}{Convenience functions for common terminal control
- operations.}
-\end{seealso}
-
-
-\subsection{Example}
-\nodename{termios Example}
-
-Here's a function that prompts for a password with echoing turned
-off. Note the technique using a separate \function{tcgetattr()} call
-and a \keyword{try} ... \keyword{finally} statement to ensure that the
-old tty attributes are restored exactly no matter what happens:
-
-\begin{verbatim}
-def raw_input(prompt):
- import sys
- sys.stdout.write(prompt)
- sys.stdout.flush()
- return sys.stdin.readline()
-
-def getpass(prompt = "Password: "):
- import termios, sys
- fd = sys.stdin.fileno()
- old = termios.tcgetattr(fd)
- new = termios.tcgetattr(fd)
- new[3] = new[3] & ~termios.ECHO # lflags
- try:
- termios.tcsetattr(fd, termios.TCSADRAIN, new)
- passwd = raw_input(prompt)
- finally:
- termios.tcsetattr(fd, termios.TCSADRAIN, old)
- return passwd
-\end{verbatim}
diff --git a/Doc/lib/libtest.tex b/Doc/lib/libtest.tex
deleted file mode 100644
index d258089..0000000
--- a/Doc/lib/libtest.tex
+++ /dev/null
@@ -1,316 +0,0 @@
-\section{\module{test} ---
- Regression tests package for Python}
-
-\declaremodule{standard}{test}
-\sectionauthor{Brett Cannon}{brett@python.org}
-\modulesynopsis{Regression tests package containing the testing suite
- for Python.}
-
-
-The \module{test} package contains all regression tests for Python as
-well as the modules \module{test.test_support} and
-\module{test.regrtest}. \module{test.test_support} is used to enhance
-your tests while \module{test.regrtest} drives the testing suite.
-
-Each module in the \module{test} package whose name starts with
-\samp{test_} is a testing suite for a specific module or feature.
-All new tests should be written using the \refmodule{unittest} or
-\refmodule{doctest} module. Some older tests are
-written using a ``traditional'' testing style that compares output
-printed to \code{sys.stdout}; this style of test is considered
-deprecated.
-
-\begin{seealso}
-\seemodule{unittest}{Writing PyUnit regression tests.}
-\seemodule{doctest}{Tests embedded in documentation strings.}
-\end{seealso}
-
-
-\subsection{Writing Unit Tests for the \module{test} package%
- \label{writing-tests}}
-
-It is preferred that tests that use the \refmodule{unittest} module
-follow a few guidelines.
-One is to name the test module by starting it with \samp{test_} and end it with
-the name of the module being tested.
-The test methods in the test module should start with \samp{test_} and end with
-a description of what the method is testing.
-This is needed so that the methods are recognized by the test driver as
-test methods.
-Also, no documentation string for the method should be included.
-A comment (such as
-\samp{\# Tests function returns only True or False}) should be used to provide
-documentation for test methods.
-This is done because documentation strings get printed out if they exist and
-thus what test is being run is not stated.
-
-A basic boilerplate is often used:
-
-\begin{verbatim}
-import unittest
-from test import test_support
-
-class MyTestCase1(unittest.TestCase):
-
- # Only use setUp() and tearDown() if necessary
-
- def setUp(self):
- ... code to execute in preparation for tests ...
-
- def tearDown(self):
- ... code to execute to clean up after tests ...
-
- def test_feature_one(self):
- # Test feature one.
- ... testing code ...
-
- def test_feature_two(self):
- # Test feature two.
- ... testing code ...
-
- ... more test methods ...
-
-class MyTestCase2(unittest.TestCase):
- ... same structure as MyTestCase1 ...
-
-... more test classes ...
-
-def test_main():
- test_support.run_unittest(MyTestCase1,
- MyTestCase2,
- ... list other tests ...
- )
-
-if __name__ == '__main__':
- test_main()
-\end{verbatim}
-
-This boilerplate code allows the testing suite to be run by
-\module{test.regrtest} as well as on its own as a script.
-
-The goal for regression testing is to try to break code.
-This leads to a few guidelines to be followed:
-
-\begin{itemize}
-\item The testing suite should exercise all classes, functions, and
- constants.
- This includes not just the external API that is to be presented to the
- outside world but also "private" code.
-\item Whitebox testing (examining the code being tested when the tests are
- being written) is preferred.
- Blackbox testing (testing only the published user interface) is not
- complete enough to make sure all boundary and edge cases are tested.
-\item Make sure all possible values are tested including invalid ones.
- This makes sure that not only all valid values are acceptable but also
- that improper values are handled correctly.
-\item Exhaust as many code paths as possible.
- Test where branching occurs and thus tailor input to make sure as many
- different paths through the code are taken.
-\item Add an explicit test for any bugs discovered for the tested code.
- This will make sure that the error does not crop up again if the code is
- changed in the future.
-\item Make sure to clean up after your tests (such as close and remove all
- temporary files).
-\item If a test is dependent on a specific condition of the operating system
- then verify the condition already exists before attempting the test.
-\item Import as few modules as possible and do it as soon as possible.
- This minimizes external dependencies of tests and also minimizes possible
- anomalous behavior from side-effects of importing a module.
-\item Try to maximize code reuse.
- On occasion, tests will vary by something as small as what type
- of input is used.
- Minimize code duplication by subclassing a basic test class with a class
- that specifies the input:
-\begin{verbatim}
-class TestFuncAcceptsSequences(unittest.TestCase):
-
- func = mySuperWhammyFunction
-
- def test_func(self):
- self.func(self.arg)
-
-class AcceptLists(TestFuncAcceptsSequences):
- arg = [1,2,3]
-
-class AcceptStrings(TestFuncAcceptsSequences):
- arg = 'abc'
-
-class AcceptTuples(TestFuncAcceptsSequences):
- arg = (1,2,3)
-\end{verbatim}
-\end{itemize}
-
-\begin{seealso}
-\seetitle{Test Driven Development}
- {A book by Kent Beck on writing tests before code.}
-\end{seealso}
-
-
-\subsection{Running tests using \module{test.regrtest} \label{regrtest}}
-
-\module{test.regrtest} can be used as a script to drive Python's
-regression test suite.
-Running the script by itself automatically starts running all
-regression tests in the \module{test} package.
-It does this by finding all modules in the package whose name starts with
-\samp{test_}, importing them, and executing the function
-\function{test_main()} if present.
-The names of tests to execute may also be passed to the script.
-Specifying a single regression test (\program{python regrtest.py}
-\programopt{test_spam.py}) will minimize output and only print whether
-the test passed or failed and thus minimize output.
-
-Running \module{test.regrtest} directly allows what resources are
-available for tests to use to be set.
-You do this by using the \programopt{-u} command-line option.
-Run \program{python regrtest.py} \programopt{-uall} to turn on all
-resources; specifying \programopt{all} as an option for
-\programopt{-u} enables all possible resources.
-If all but one resource is desired (a more common case), a
-comma-separated list of resources that are not desired may be listed after
-\programopt{all}.
-The command \program{python regrtest.py}
-\programopt{-uall,-audio,-largefile} will run \module{test.regrtest}
-with all resources except the \programopt{audio} and
-\programopt{largefile} resources.
-For a list of all resources and more command-line options, run
-\program{python regrtest.py} \programopt{-h}.
-
-Some other ways to execute the regression tests depend on what platform the
-tests are being executed on.
-On \UNIX{}, you can run \program{make} \programopt{test} at the
-top-level directory where Python was built.
-On Windows, executing \program{rt.bat} from your \file{PCBuild}
-directory will run all regression tests.
-
-
-\section{\module{test.test_support} ---
- Utility functions for tests}
-
-\declaremodule[test.testsupport]{standard}{test.test_support}
-\modulesynopsis{Support for Python regression tests.}
-
-The \module{test.test_support} module provides support for Python's
-regression tests.
-
-This module defines the following exceptions:
-
-\begin{excdesc}{TestFailed}
-Exception to be raised when a test fails. This is deprecated in favor
-of \module{unittest}-based tests and \class{unittest.TestCase}'s
-assertion methods.
-\end{excdesc}
-
-\begin{excdesc}{TestSkipped}
-Subclass of \exception{TestFailed}.
-Raised when a test is skipped.
-This occurs when a needed resource (such as a network connection) is not
-available at the time of testing.
-\end{excdesc}
-
-\begin{excdesc}{ResourceDenied}
-Subclass of \exception{TestSkipped}.
-Raised when a resource (such as a network connection) is not available.
-Raised by the \function{requires()} function.
-\end{excdesc}
-
-
-The \module{test.test_support} module defines the following constants:
-
-\begin{datadesc}{verbose}
-\constant{True} when verbose output is enabled.
-Should be checked when more detailed information is desired about a running
-test.
-\var{verbose} is set by \module{test.regrtest}.
-\end{datadesc}
-
-\begin{datadesc}{have_unicode}
-\constant{True} when Unicode support is available.
-\end{datadesc}
-
-\begin{datadesc}{is_jython}
-\constant{True} if the running interpreter is Jython.
-\end{datadesc}
-
-\begin{datadesc}{TESTFN}
-Set to the path that a temporary file may be created at.
-Any temporary that is created should be closed and unlinked (removed).
-\end{datadesc}
-
-
-The \module{test.test_support} module defines the following functions:
-
-\begin{funcdesc}{forget}{module_name}
-Removes the module named \var{module_name} from \code{sys.modules} and deletes
-any byte-compiled files of the module.
-\end{funcdesc}
-
-\begin{funcdesc}{is_resource_enabled}{resource}
-Returns \constant{True} if \var{resource} is enabled and available.
-The list of available resources is only set when \module{test.regrtest}
-is executing the tests.
-\end{funcdesc}
-
-\begin{funcdesc}{requires}{resource\optional{, msg}}
-Raises \exception{ResourceDenied} if \var{resource} is not available.
-\var{msg} is the argument to \exception{ResourceDenied} if it is raised.
-Always returns true if called by a function whose \code{__name__} is
-\code{'__main__'}.
-Used when tests are executed by \module{test.regrtest}.
-\end{funcdesc}
-
-\begin{funcdesc}{findfile}{filename}
-Return the path to the file named \var{filename}.
-If no match is found \var{filename} is returned.
-This does not equal a failure since it could be the path to the file.
-\end{funcdesc}
-
-\begin{funcdesc}{guard_warnings_filter}{}
-Returns a context manager that guards the \module{warnings} module's
-filter settings.
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{run_unittest}{*classes}
-Execute \class{unittest.TestCase} subclasses passed to the function.
-The function scans the classes for methods starting with the prefix
-\samp{test_} and executes the tests individually.
-
-It is also legal to pass strings as parameters; these should be keys in
-\code{sys.modules}. Each associated module will be scanned by
-\code{unittest.TestLoader.loadTestsFromModule()}. This is usually seen in
-the following \function{test_main()} function:
-
-\begin{verbatim}
-def test_main():
- test_support.run_unittest(__name__)
-\end{verbatim}
-
-This will run all tests defined in the named module.
-\end{funcdesc}
-
-The \module{test.test_support} module defines the following classes:
-
-\begin{classdesc}{TransientResource}{exc\optional{, **kwargs}}
-Create a context manager that raises \class{ResourceDenied} if the specified
-exception type is raised. Any keyword arguments are treated as name/value
-pairs to be compared against any exception raised with the \code{with}
-statement. Only if all pairs match is \class{ResourceDenied} raised.
-\versionadded{2.6}
-\end{classdesc}
-
-\begin{classdesc}{EnvironmentVarGuard}{}
-Class used to temporarily set or unset environment variables. Instances can be
-used as a context manager.
-\versionadded{2.6}
-\end{classdesc}
-
-\begin{methoddesc}{set}{envvar, value}
-Temporarily set the environment variable \code{envvar} to the value of
-\code{value}.
-\end{methoddesc}
-
-\begin{methoddesc}{unset}{envvar}
-Temporarily unset the environment variable \code{envvar}.
-\end{methoddesc}
-
diff --git a/Doc/lib/libtextwrap.tex b/Doc/lib/libtextwrap.tex
deleted file mode 100644
index 8ea25a8..0000000
--- a/Doc/lib/libtextwrap.tex
+++ /dev/null
@@ -1,188 +0,0 @@
-\section{\module{textwrap} ---
- Text wrapping and filling}
-
-\declaremodule{standard}{textwrap}
-\modulesynopsis{Text wrapping and filling}
-\moduleauthor{Greg Ward}{gward@python.net}
-\sectionauthor{Greg Ward}{gward@python.net}
-
-\versionadded{2.3}
-
-The \module{textwrap} module provides two convenience functions,
-\function{wrap()} and \function{fill()}, as well as
-\class{TextWrapper}, the class that does all the work, and a utility function
-\function{dedent()}. If you're just wrapping or filling one or two
-text strings, the convenience functions should be good enough; otherwise,
-you should use an instance of \class{TextWrapper} for efficiency.
-
-\begin{funcdesc}{wrap}{text\optional{, width\optional{, \moreargs}}}
-Wraps the single paragraph in \var{text} (a string) so every line is at
-most \var{width} characters long. Returns a list of output lines,
-without final newlines.
-
-Optional keyword arguments correspond to the instance attributes of
-\class{TextWrapper}, documented below. \var{width} defaults to
-\code{70}.
-\end{funcdesc}
-
-\begin{funcdesc}{fill}{text\optional{, width\optional{, \moreargs}}}
-Wraps the single paragraph in \var{text}, and returns a single string
-containing the wrapped paragraph. \function{fill()} is shorthand for
-\begin{verbatim}
-"\n".join(wrap(text, ...))
-\end{verbatim}
-
-In particular, \function{fill()} accepts exactly the same keyword
-arguments as \function{wrap()}.
-\end{funcdesc}
-
-Both \function{wrap()} and \function{fill()} work by creating a
-\class{TextWrapper} instance and calling a single method on it. That
-instance is not reused, so for applications that wrap/fill many text
-strings, it will be more efficient for you to create your own
-\class{TextWrapper} object.
-
-An additional utility function, \function{dedent()}, is provided to
-remove indentation from strings that have unwanted whitespace to the
-left of the text.
-
-\begin{funcdesc}{dedent}{text}
-Remove any common leading whitespace from every line in \var{text}.
-
-This can be used to make triple-quoted strings line up with the left
-edge of the display, while still presenting them in the source code
-in indented form.
-
-Note that tabs and spaces are both treated as whitespace, but they are
-not equal: the lines \code{" {} hello"} and \code{"\e thello"}
-are considered to have no common leading whitespace. (This behaviour is
-new in Python 2.5; older versions of this module incorrectly expanded
-tabs before searching for common leading whitespace.)
-
-For example:
-\begin{verbatim}
-def test():
- # end first line with \ to avoid the empty line!
- s = '''\
- hello
- world
- '''
- print repr(s) # prints ' hello\n world\n '
- print repr(dedent(s)) # prints 'hello\n world\n'
-\end{verbatim}
-\end{funcdesc}
-
-\begin{classdesc}{TextWrapper}{...}
-The \class{TextWrapper} constructor accepts a number of optional
-keyword arguments. Each argument corresponds to one instance attribute,
-so for example
-\begin{verbatim}
-wrapper = TextWrapper(initial_indent="* ")
-\end{verbatim}
-is the same as
-\begin{verbatim}
-wrapper = TextWrapper()
-wrapper.initial_indent = "* "
-\end{verbatim}
-
-You can re-use the same \class{TextWrapper} object many times, and you
-can change any of its options through direct assignment to instance
-attributes between uses.
-\end{classdesc}
-
-The \class{TextWrapper} instance attributes (and keyword arguments to
-the constructor) are as follows:
-
-\begin{memberdesc}{width}
-(default: \code{70}) The maximum length of wrapped lines. As long as
-there are no individual words in the input text longer than
-\member{width}, \class{TextWrapper} guarantees that no output line
-will be longer than \member{width} characters.
-\end{memberdesc}
-
-\begin{memberdesc}{expand_tabs}
-(default: \code{True}) If true, then all tab characters in \var{text}
-will be expanded to spaces using the \method{expandtabs()} method of
-\var{text}.
-\end{memberdesc}
-
-\begin{memberdesc}{replace_whitespace}
-(default: \code{True}) If true, each whitespace character (as defined
-by \code{string.whitespace}) remaining after tab expansion will be
-replaced by a single space. \note{If \member{expand_tabs} is false
-and \member{replace_whitespace} is true, each tab character will be
-replaced by a single space, which is \emph{not} the same as tab
-expansion.}
-\end{memberdesc}
-
-\begin{memberdesc}{drop_whitespace}
-(default: \code{True}) If true, whitespace that, after wrapping, happens
-to end up at the beginning or end of a line is dropped (leading whitespace
-in the first line is always preserved, though).
-\versionadded[Whitespace was always dropped in earlier versions]{2.6}
-\end{memberdesc}
-
-\begin{memberdesc}{initial_indent}
-(default: \code{''}) String that will be prepended to the first line
-of wrapped output. Counts towards the length of the first line.
-\end{memberdesc}
-
-\begin{memberdesc}{subsequent_indent}
-(default: \code{''}) String that will be prepended to all lines of
-wrapped output except the first. Counts towards the length of each
-line except the first.
-\end{memberdesc}
-
-\begin{memberdesc}{fix_sentence_endings}
-(default: \code{False}) If true, \class{TextWrapper} attempts to detect
-sentence endings and ensure that sentences are always separated by
-exactly two spaces. This is generally desired for text in a monospaced
-font. However, the sentence detection algorithm is imperfect: it
-assumes that a sentence ending consists of a lowercase letter followed
-by one of \character{.},
-\character{!}, or \character{?}, possibly followed by one of
-\character{"} or \character{'}, followed by a space. One problem
-with this is algorithm is that it is unable to detect the difference
-between ``Dr.'' in
-
-\begin{verbatim}
-[...] Dr. Frankenstein's monster [...]
-\end{verbatim}
-
-and ``Spot.'' in
-
-\begin{verbatim}
-[...] See Spot. See Spot run [...]
-\end{verbatim}
-
-\member{fix_sentence_endings} is false by default.
-
-Since the sentence detection algorithm relies on
-\code{string.lowercase} for the definition of ``lowercase letter,''
-and a convention of using two spaces after a period to separate
-sentences on the same line, it is specific to English-language texts.
-\end{memberdesc}
-
-\begin{memberdesc}{break_long_words}
-(default: \code{True}) If true, then words longer than
-\member{width} will be broken in order to ensure that no lines are
-longer than \member{width}. If it is false, long words will not be
-broken, and some lines may be longer than \member{width}. (Long words
-will be put on a line by themselves, in order to minimize the amount
-by which \member{width} is exceeded.)
-\end{memberdesc}
-
-\class{TextWrapper} also provides two public methods, analogous to the
-module-level convenience functions:
-
-\begin{methoddesc}{wrap}{text}
-Wraps the single paragraph in \var{text} (a string) so every line is
-at most \member{width} characters long. All wrapping options are
-taken from instance attributes of the \class{TextWrapper} instance.
-Returns a list of output lines, without final newlines.
-\end{methoddesc}
-
-\begin{methoddesc}{fill}{text}
-Wraps the single paragraph in \var{text}, and returns a single string
-containing the wrapped paragraph.
-\end{methoddesc}
diff --git a/Doc/lib/libthread.tex b/Doc/lib/libthread.tex
deleted file mode 100644
index d007eec..0000000
--- a/Doc/lib/libthread.tex
+++ /dev/null
@@ -1,173 +0,0 @@
-\section{\module{thread} ---
- Multiple threads of control}
-
-\declaremodule{builtin}{thread}
-\modulesynopsis{Create multiple threads of control within one interpreter.}
-
-
-This module provides low-level primitives for working with multiple
-threads (a.k.a.\ \dfn{light-weight processes} or \dfn{tasks}) --- multiple
-threads of control sharing their global data space. For
-synchronization, simple locks (a.k.a.\ \dfn{mutexes} or \dfn{binary
-semaphores}) are provided.
-\index{light-weight processes}
-\index{processes, light-weight}
-\index{binary semaphores}
-\index{semaphores, binary}
-
-The module is optional. It is supported on Windows, Linux, SGI
-IRIX, Solaris 2.x, as well as on systems that have a \POSIX{} thread
-(a.k.a. ``pthread'') implementation. For systems lacking the \module{thread}
-module, the \refmodule[dummythread]{dummy_thread} module is available.
-It duplicates this module's interface and can be
-used as a drop-in replacement.
-\index{pthreads}
-\indexii{threads}{\POSIX}
-
-It defines the following constant and functions:
-
-\begin{excdesc}{error}
-Raised on thread-specific errors.
-\end{excdesc}
-
-\begin{datadesc}{LockType}
-This is the type of lock objects.
-\end{datadesc}
-
-\begin{funcdesc}{start_new_thread}{function, args\optional{, kwargs}}
-Start a new thread and return its identifier. The thread executes the function
-\var{function} with the argument list \var{args} (which must be a tuple). The
-optional \var{kwargs} argument specifies a dictionary of keyword arguments.
-When the function returns, the thread silently exits. When the function
-terminates with an unhandled exception, a stack trace is printed and
-then the thread exits (but other threads continue to run).
-\end{funcdesc}
-
-\begin{funcdesc}{interrupt_main}{}
-Raise a \exception{KeyboardInterrupt} exception in the main thread. A subthread
-can use this function to interrupt the main thread.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{exit}{}
-Raise the \exception{SystemExit} exception. When not caught, this
-will cause the thread to exit silently.
-\end{funcdesc}
-
-%\begin{funcdesc}{exit_prog}{status}
-%Exit all threads and report the value of the integer argument
-%\var{status} as the exit status of the entire program.
-%\strong{Caveat:} code in pending \keyword{finally} clauses, in this thread
-%or in other threads, is not executed.
-%\end{funcdesc}
-
-\begin{funcdesc}{allocate_lock}{}
-Return a new lock object. Methods of locks are described below. The
-lock is initially unlocked.
-\end{funcdesc}
-
-\begin{funcdesc}{get_ident}{}
-Return the `thread identifier' of the current thread. This is a
-nonzero integer. Its value has no direct meaning; it is intended as a
-magic cookie to be used e.g. to index a dictionary of thread-specific
-data. Thread identifiers may be recycled when a thread exits and
-another thread is created.
-\end{funcdesc}
-
-\begin{funcdesc}{stack_size}{\optional{size}}
-Return the thread stack size used when creating new threads. The
-optional \var{size} argument specifies the stack size to be used for
-subsequently created threads, and must be 0 (use platform or
-configured default) or a positive integer value of at least 32,768 (32kB).
-If changing the thread stack size is unsupported, a \exception{ThreadError}
-is raised. If the specified stack size is invalid, a \exception{ValueError}
-is raised and the stack size is unmodified. 32kB is currently the minimum
-supported stack size value to guarantee sufficient stack space for the
-interpreter itself. Note that some platforms may have particular
-restrictions on values for the stack size, such as requiring a minimum
-stack size > 32kB or requiring allocation in multiples of the system
-memory page size - platform documentation should be referred to for
-more information (4kB pages are common; using multiples of 4096 for
-the stack size is the suggested approach in the absence of more
-specific information).
-Availability: Windows, systems with \POSIX{} threads.
-\versionadded{2.5}
-\end{funcdesc}
-
-
-Lock objects have the following methods:
-
-\begin{methoddesc}[lock]{acquire}{\optional{waitflag}}
-Without the optional argument, this method acquires the lock
-unconditionally, if necessary waiting until it is released by another
-thread (only one thread at a time can acquire a lock --- that's their
-reason for existence). If the integer
-\var{waitflag} argument is present, the action depends on its
-value: if it is zero, the lock is only acquired if it can be acquired
-immediately without waiting, while if it is nonzero, the lock is
-acquired unconditionally as before. The
-return value is \code{True} if the lock is acquired successfully,
-\code{False} if not.
-\end{methoddesc}
-
-\begin{methoddesc}[lock]{release}{}
-Releases the lock. The lock must have been acquired earlier, but not
-necessarily by the same thread.
-\end{methoddesc}
-
-\begin{methoddesc}[lock]{locked}{}
-Return the status of the lock:\ \code{True} if it has been acquired by
-some thread, \code{False} if not.
-\end{methoddesc}
-
-In addition to these methods, lock objects can also be used via the
-\keyword{with} statement, e.g.:
-
-\begin{verbatim}
-from __future__ import with_statement
-import thread
-
-a_lock = thread.allocate_lock()
-
-with a_lock:
- print "a_lock is locked while this executes"
-\end{verbatim}
-
-\strong{Caveats:}
-
-\begin{itemize}
-\item
-Threads interact strangely with interrupts: the
-\exception{KeyboardInterrupt} exception will be received by an
-arbitrary thread. (When the \refmodule{signal}\refbimodindex{signal}
-module is available, interrupts always go to the main thread.)
-
-\item
-Calling \function{sys.exit()} or raising the \exception{SystemExit}
-exception is equivalent to calling \function{exit()}.
-
-\item
-Not all built-in functions that may block waiting for I/O allow other
-threads to run. (The most popular ones (\function{time.sleep()},
-\method{\var{file}.read()}, \function{select.select()}) work as
-expected.)
-
-\item
-It is not possible to interrupt the \method{acquire()} method on a lock
---- the \exception{KeyboardInterrupt} exception will happen after the
-lock has been acquired.
-
-\item
-When the main thread exits, it is system defined whether the other
-threads survive. On SGI IRIX using the native thread implementation,
-they survive. On most other systems, they are killed without
-executing \keyword{try} ... \keyword{finally} clauses or executing
-object destructors.
-\indexii{threads}{IRIX}
-
-\item
-When the main thread exits, it does not do any of its usual cleanup
-(except that \keyword{try} ... \keyword{finally} clauses are honored),
-and the standard I/O files are not flushed.
-
-\end{itemize}
diff --git a/Doc/lib/libthreading.tex b/Doc/lib/libthreading.tex
deleted file mode 100644
index 19c496e..0000000
--- a/Doc/lib/libthreading.tex
+++ /dev/null
@@ -1,728 +0,0 @@
-\section{\module{threading} ---
- Higher-level threading interface}
-
-\declaremodule{standard}{threading}
-\modulesynopsis{Higher-level threading interface.}
-
-
-This module constructs higher-level threading interfaces on top of the
-lower level \refmodule{thread} module.
-
-The \refmodule[dummythreading]{dummy_threading} module is provided for
-situations where \module{threading} cannot be used because
-\refmodule{thread} is missing.
-
-This module defines the following functions and objects:
-
-\begin{funcdesc}{activeCount}{}
-Return the number of \class{Thread} objects currently alive. The
-returned count is equal to the length of the list returned by
-\function{enumerate()}.
-\end{funcdesc}
-
-\begin{funcdescni}{Condition}{}
-A factory function that returns a new condition variable object.
-A condition variable allows one or more threads to wait until they
-are notified by another thread.
-\end{funcdescni}
-
-\begin{funcdesc}{currentThread}{}
-Return the current \class{Thread} object, corresponding to the
-caller's thread of control. If the caller's thread of control was not
-created through the
-\module{threading} module, a dummy thread object with limited functionality
-is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{enumerate}{}
-Return a list of all \class{Thread} objects currently alive. The list
-includes daemonic threads, dummy thread objects created by
-\function{currentThread()}, and the main thread. It excludes
-terminated threads and threads that have not yet been started.
-\end{funcdesc}
-
-\begin{funcdescni}{Event}{}
-A factory function that returns a new event object. An event manages
-a flag that can be set to true with the \method{set()} method and
-reset to false with the \method{clear()} method. The \method{wait()}
-method blocks until the flag is true.
-\end{funcdescni}
-
-\begin{classdesc*}{local}{}
-A class that represents thread-local data. Thread-local data are data
-whose values are thread specific. To manage thread-local data, just
-create an instance of \class{local} (or a subclass) and store
-attributes on it:
-
-\begin{verbatim}
-mydata = threading.local()
-mydata.x = 1
-\end{verbatim}
-
-The instance's values will be different for separate threads.
-
-For more details and extensive examples, see the documentation string
-of the \module{_threading_local} module.
-
-\versionadded{2.4}
-\end{classdesc*}
-
-\begin{funcdesc}{Lock}{}
-A factory function that returns a new primitive lock object. Once
-a thread has acquired it, subsequent attempts to acquire it block,
-until it is released; any thread may release it.
-\end{funcdesc}
-
-\begin{funcdesc}{RLock}{}
-A factory function that returns a new reentrant lock object.
-A reentrant lock must be released by the thread that acquired it.
-Once a thread has acquired a reentrant lock, the same thread may
-acquire it again without blocking; the thread must release it once
-for each time it has acquired it.
-\end{funcdesc}
-
-\begin{funcdescni}{Semaphore}{\optional{value}}
-A factory function that returns a new semaphore object. A
-semaphore manages a counter representing the number of \method{release()}
-calls minus the number of \method{acquire()} calls, plus an initial value.
-The \method{acquire()} method blocks if necessary until it can return
-without making the counter negative. If not given, \var{value} defaults to
-1.
-\end{funcdescni}
-
-\begin{funcdesc}{BoundedSemaphore}{\optional{value}}
-A factory function that returns a new bounded semaphore object. A bounded
-semaphore checks to make sure its current value doesn't exceed its initial
-value. If it does, \exception{ValueError} is raised. In most situations
-semaphores are used to guard resources with limited capacity. If the
-semaphore is released too many times it's a sign of a bug. If not given,
-\var{value} defaults to 1.
-\end{funcdesc}
-
-\begin{classdesc*}{Thread}
-A class that represents a thread of control. This class can be safely
-subclassed in a limited fashion.
-\end{classdesc*}
-
-\begin{classdesc*}{Timer}
-A thread that executes a function after a specified interval has passed.
-\end{classdesc*}
-
-\begin{funcdesc}{settrace}{func}
-Set a trace function\index{trace function} for all threads started
-from the \module{threading} module. The \var{func} will be passed to
-\function{sys.settrace()} for each thread, before its \method{run()}
-method is called.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{setprofile}{func}
-Set a profile function\index{profile function} for all threads started
-from the \module{threading} module. The \var{func} will be passed to
-\function{sys.setprofile()} for each thread, before its \method{run()}
-method is called.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{stack_size}{\optional{size}}
-Return the thread stack size used when creating new threads. The
-optional \var{size} argument specifies the stack size to be used for
-subsequently created threads, and must be 0 (use platform or
-configured default) or a positive integer value of at least 32,768 (32kB).
-If changing the thread stack size is unsupported, a \exception{ThreadError}
-is raised. If the specified stack size is invalid, a \exception{ValueError}
-is raised and the stack size is unmodified. 32kB is currently the minimum
-supported stack size value to guarantee sufficient stack space for the
-interpreter itself. Note that some platforms may have particular
-restrictions on values for the stack size, such as requiring a minimum
-stack size > 32kB or requiring allocation in multiples of the system
-memory page size - platform documentation should be referred to for
-more information (4kB pages are common; using multiples of 4096 for
-the stack size is the suggested approach in the absence of more
-specific information).
-Availability: Windows, systems with \POSIX{} threads.
-\versionadded{2.5}
-\end{funcdesc}
-
-Detailed interfaces for the objects are documented below.
-
-The design of this module is loosely based on Java's threading model.
-However, where Java makes locks and condition variables basic behavior
-of every object, they are separate objects in Python. Python's \class{Thread}
-class supports a subset of the behavior of Java's Thread class;
-currently, there are no priorities, no thread groups, and threads
-cannot be destroyed, stopped, suspended, resumed, or interrupted. The
-static methods of Java's Thread class, when implemented, are mapped to
-module-level functions.
-
-All of the methods described below are executed atomically.
-
-
-\subsection{Lock Objects \label{lock-objects}}
-
-A primitive lock is a synchronization primitive that is not owned
-by a particular thread when locked. In Python, it is currently
-the lowest level synchronization primitive available, implemented
-directly by the \refmodule{thread} extension module.
-
-A primitive lock is in one of two states, ``locked'' or ``unlocked''.
-It is created in the unlocked state. It has two basic methods,
-\method{acquire()} and \method{release()}. When the state is
-unlocked, \method{acquire()} changes the state to locked and returns
-immediately. When the state is locked, \method{acquire()} blocks
-until a call to \method{release()} in another thread changes it to
-unlocked, then the \method{acquire()} call resets it to locked and
-returns. The \method{release()} method should only be called in the
-locked state; it changes the state to unlocked and returns
-immediately. If an attempt is made to release an unlocked lock, a
-\exception{RuntimeError} will be raised.
-
-When more than one thread is blocked in \method{acquire()} waiting for
-the state to turn to unlocked, only one thread proceeds when a
-\method{release()} call resets the state to unlocked; which one of the
-waiting threads proceeds is not defined, and may vary across
-implementations.
-
-All methods are executed atomically.
-
-\begin{methoddesc}[Lock]{acquire}{\optional{blocking\code{ = 1}}}
-Acquire a lock, blocking or non-blocking.
-
-When invoked without arguments, block until the lock is
-unlocked, then set it to locked, and return true.
-
-When invoked with the \var{blocking} argument set to true, do the
-same thing as when called without arguments, and return true.
-
-When invoked with the \var{blocking} argument set to false, do not
-block. If a call without an argument would block, return false
-immediately; otherwise, do the same thing as when called
-without arguments, and return true.
-\end{methoddesc}
-
-\begin{methoddesc}[Lock]{release}{}
-Release a lock.
-
-When the lock is locked, reset it to unlocked, and return. If
-any other threads are blocked waiting for the lock to become
-unlocked, allow exactly one of them to proceed.
-
-Do not call this method when the lock is unlocked.
-
-There is no return value.
-\end{methoddesc}
-
-
-\subsection{RLock Objects \label{rlock-objects}}
-
-A reentrant lock is a synchronization primitive that may be
-acquired multiple times by the same thread. Internally, it uses
-the concepts of ``owning thread'' and ``recursion level'' in
-addition to the locked/unlocked state used by primitive locks. In
-the locked state, some thread owns the lock; in the unlocked
-state, no thread owns it.
-
-To lock the lock, a thread calls its \method{acquire()} method; this
-returns once the thread owns the lock. To unlock the lock, a
-thread calls its \method{release()} method.
-\method{acquire()}/\method{release()} call pairs may be nested; only
-the final \method{release()} (the \method{release()} of the outermost
-pair) resets the lock to unlocked and allows another thread blocked in
-\method{acquire()} to proceed.
-
-\begin{methoddesc}[RLock]{acquire}{\optional{blocking\code{ = 1}}}
-Acquire a lock, blocking or non-blocking.
-
-When invoked without arguments: if this thread already owns
-the lock, increment the recursion level by one, and return
-immediately. Otherwise, if another thread owns the lock,
-block until the lock is unlocked. Once the lock is unlocked
-(not owned by any thread), then grab ownership, set the
-recursion level to one, and return. If more than one thread
-is blocked waiting until the lock is unlocked, only one at a
-time will be able to grab ownership of the lock. There is no
-return value in this case.
-
-When invoked with the \var{blocking} argument set to true, do the
-same thing as when called without arguments, and return true.
-
-When invoked with the \var{blocking} argument set to false, do not
-block. If a call without an argument would block, return false
-immediately; otherwise, do the same thing as when called
-without arguments, and return true.
-\end{methoddesc}
-
-\begin{methoddesc}[RLock]{release}{}
-Release a lock, decrementing the recursion level. If after the
-decrement it is zero, reset the lock to unlocked (not owned by any
-thread), and if any other threads are blocked waiting for the lock to
-become unlocked, allow exactly one of them to proceed. If after the
-decrement the recursion level is still nonzero, the lock remains
-locked and owned by the calling thread.
-
-Only call this method when the calling thread owns the lock. A
-\exception{RuntimeError} is raised if this method is called when the
-lock is unlocked.
-
-There is no return value.
-\end{methoddesc}
-
-
-\subsection{Condition Objects \label{condition-objects}}
-
-A condition variable is always associated with some kind of lock;
-this can be passed in or one will be created by default. (Passing
-one in is useful when several condition variables must share the
-same lock.)
-
-A condition variable has \method{acquire()} and \method{release()}
-methods that call the corresponding methods of the associated lock.
-It also has a \method{wait()} method, and \method{notify()} and
-\method{notifyAll()} methods. These three must only be called when
-the calling thread has acquired the lock, otherwise a
-\exception{RuntimeError} is raised.
-
-The \method{wait()} method releases the lock, and then blocks until it
-is awakened by a \method{notify()} or \method{notifyAll()} call for
-the same condition variable in another thread. Once awakened, it
-re-acquires the lock and returns. It is also possible to specify a
-timeout.
-
-The \method{notify()} method wakes up one of the threads waiting for
-the condition variable, if any are waiting. The \method{notifyAll()}
-method wakes up all threads waiting for the condition variable.
-
-Note: the \method{notify()} and \method{notifyAll()} methods don't
-release the lock; this means that the thread or threads awakened will
-not return from their \method{wait()} call immediately, but only when
-the thread that called \method{notify()} or \method{notifyAll()}
-finally relinquishes ownership of the lock.
-
-Tip: the typical programming style using condition variables uses the
-lock to synchronize access to some shared state; threads that are
-interested in a particular change of state call \method{wait()}
-repeatedly until they see the desired state, while threads that modify
-the state call \method{notify()} or \method{notifyAll()} when they
-change the state in such a way that it could possibly be a desired
-state for one of the waiters. For example, the following code is a
-generic producer-consumer situation with unlimited buffer capacity:
-
-\begin{verbatim}
-# Consume one item
-cv.acquire()
-while not an_item_is_available():
- cv.wait()
-get_an_available_item()
-cv.release()
-
-# Produce one item
-cv.acquire()
-make_an_item_available()
-cv.notify()
-cv.release()
-\end{verbatim}
-
-To choose between \method{notify()} and \method{notifyAll()}, consider
-whether one state change can be interesting for only one or several
-waiting threads. E.g. in a typical producer-consumer situation,
-adding one item to the buffer only needs to wake up one consumer
-thread.
-
-\begin{classdesc}{Condition}{\optional{lock}}
-If the \var{lock} argument is given and not \code{None}, it must be a
-\class{Lock} or \class{RLock} object, and it is used as the underlying
-lock. Otherwise, a new \class{RLock} object is created and used as
-the underlying lock.
-\end{classdesc}
-
-\begin{methoddesc}{acquire}{*args}
-Acquire the underlying lock.
-This method calls the corresponding method on the underlying
-lock; the return value is whatever that method returns.
-\end{methoddesc}
-
-\begin{methoddesc}{release}{}
-Release the underlying lock.
-This method calls the corresponding method on the underlying
-lock; there is no return value.
-\end{methoddesc}
-
-\begin{methoddesc}{wait}{\optional{timeout}}
-Wait until notified or until a timeout occurs. If the calling thread
-has not acquired the lock when this method is called, a
-\exception{RuntimeError} is raised.
-
-This method releases the underlying lock, and then blocks until it is
-awakened by a \method{notify()} or \method{notifyAll()} call for the
-same condition variable in another thread, or until the optional
-timeout occurs. Once awakened or timed out, it re-acquires the lock
-and returns.
-
-When the \var{timeout} argument is present and not \code{None}, it
-should be a floating point number specifying a timeout for the
-operation in seconds (or fractions thereof).
-
-When the underlying lock is an \class{RLock}, it is not released using
-its \method{release()} method, since this may not actually unlock the
-lock when it was acquired multiple times recursively. Instead, an
-internal interface of the \class{RLock} class is used, which really
-unlocks it even when it has been recursively acquired several times.
-Another internal interface is then used to restore the recursion level
-when the lock is reacquired.
-\end{methoddesc}
-
-\begin{methoddesc}{notify}{}
-Wake up a thread waiting on this condition, if any. Wait until
-notified or until a timeout occurs. If the calling thread has not
-acquired the lock when this method is called, a
-\exception{RuntimeError} is raised.
-
-This method wakes up one of the threads waiting for the condition
-variable, if any are waiting; it is a no-op if no threads are waiting.
-
-The current implementation wakes up exactly one thread, if any are
-waiting. However, it's not safe to rely on this behavior. A future,
-optimized implementation may occasionally wake up more than one
-thread.
-
-Note: the awakened thread does not actually return from its
-\method{wait()} call until it can reacquire the lock. Since
-\method{notify()} does not release the lock, its caller should.
-\end{methoddesc}
-
-\begin{methoddesc}{notifyAll}{}
-Wake up all threads waiting on this condition. This method acts like
-\method{notify()}, but wakes up all waiting threads instead of one. If
-the calling thread has not acquired the lock when this method is
-called, a \exception{RuntimeError} is raised.
-\end{methoddesc}
-
-
-\subsection{Semaphore Objects \label{semaphore-objects}}
-
-This is one of the oldest synchronization primitives in the history of
-computer science, invented by the early Dutch computer scientist
-Edsger W. Dijkstra (he used \method{P()} and \method{V()} instead of
-\method{acquire()} and \method{release()}).
-
-A semaphore manages an internal counter which is decremented by each
-\method{acquire()} call and incremented by each \method{release()}
-call. The counter can never go below zero; when \method{acquire()}
-finds that it is zero, it blocks, waiting until some other thread
-calls \method{release()}.
-
-\begin{classdesc}{Semaphore}{\optional{value}}
-The optional argument gives the initial \var{value} for the internal
-counter; it defaults to \code{1}. If the \var{value} given is less
-than 0, \exception{ValueError} is raised.
-\end{classdesc}
-
-\begin{methoddesc}{acquire}{\optional{blocking}}
-Acquire a semaphore.
-
-When invoked without arguments: if the internal counter is larger than
-zero on entry, decrement it by one and return immediately. If it is
-zero on entry, block, waiting until some other thread has called
-\method{release()} to make it larger than zero. This is done with
-proper interlocking so that if multiple \method{acquire()} calls are
-blocked, \method{release()} will wake exactly one of them up. The
-implementation may pick one at random, so the order in which blocked
-threads are awakened should not be relied on. There is no return
-value in this case.
-
-When invoked with \var{blocking} set to true, do the same thing as
-when called without arguments, and return true.
-
-When invoked with \var{blocking} set to false, do not block. If a
-call without an argument would block, return false immediately;
-otherwise, do the same thing as when called without arguments, and
-return true.
-\end{methoddesc}
-
-\begin{methoddesc}{release}{}
-Release a semaphore,
-incrementing the internal counter by one. When it was zero on
-entry and another thread is waiting for it to become larger
-than zero again, wake up that thread.
-\end{methoddesc}
-
-
-\subsubsection{\class{Semaphore} Example \label{semaphore-examples}}
-
-Semaphores are often used to guard resources with limited capacity, for
-example, a database server. In any situation where the size of the resource
-size is fixed, you should use a bounded semaphore. Before spawning any
-worker threads, your main thread would initialize the semaphore:
-
-\begin{verbatim}
-maxconnections = 5
-...
-pool_sema = BoundedSemaphore(value=maxconnections)
-\end{verbatim}
-
-Once spawned, worker threads call the semaphore's acquire and release
-methods when they need to connect to the server:
-
-\begin{verbatim}
-pool_sema.acquire()
-conn = connectdb()
-... use connection ...
-conn.close()
-pool_sema.release()
-\end{verbatim}
-
-The use of a bounded semaphore reduces the chance that a programming error
-which causes the semaphore to be released more than it's acquired will go
-undetected.
-
-
-\subsection{Event Objects \label{event-objects}}
-
-This is one of the simplest mechanisms for communication between
-threads: one thread signals an event and other threads wait for it.
-
-An event object manages an internal flag that can be set to true with
-the \method{set()} method and reset to false with the \method{clear()}
-method. The \method{wait()} method blocks until the flag is true.
-
-
-\begin{classdesc}{Event}{}
-The internal flag is initially false.
-\end{classdesc}
-
-\begin{methoddesc}{isSet}{}
-Return true if and only if the internal flag is true.
-\end{methoddesc}
-
-\begin{methoddesc}{set}{}
-Set the internal flag to true.
-All threads waiting for it to become true are awakened.
-Threads that call \method{wait()} once the flag is true will not block
-at all.
-\end{methoddesc}
-
-\begin{methoddesc}{clear}{}
-Reset the internal flag to false.
-Subsequently, threads calling \method{wait()} will block until
-\method{set()} is called to set the internal flag to true again.
-\end{methoddesc}
-
-\begin{methoddesc}{wait}{\optional{timeout}}
-Block until the internal flag is true.
-If the internal flag is true on entry, return immediately. Otherwise,
-block until another thread calls \method{set()} to set the flag to
-true, or until the optional timeout occurs.
-
-When the timeout argument is present and not \code{None}, it should be a
-floating point number specifying a timeout for the operation in
-seconds (or fractions thereof).
-\end{methoddesc}
-
-
-\subsection{Thread Objects \label{thread-objects}}
-
-This class represents an activity that is run in a separate thread
-of control. There are two ways to specify the activity: by
-passing a callable object to the constructor, or by overriding the
-\method{run()} method in a subclass. No other methods (except for the
-constructor) should be overridden in a subclass. In other words,
-\emph{only} override the \method{__init__()} and \method{run()}
-methods of this class.
-
-Once a thread object is created, its activity must be started by
-calling the thread's \method{start()} method. This invokes the
-\method{run()} method in a separate thread of control.
-
-Once the thread's activity is started, the thread is considered
-'alive'. It stops being alive when its \method{run()} method terminates
--- either normally, or by raising an unhandled exception. The
-\method{isAlive()} method tests whether the thread is alive.
-
-Other threads can call a thread's \method{join()} method. This blocks
-the calling thread until the thread whose \method{join()} method is
-called is terminated.
-
-A thread has a name. The name can be passed to the constructor,
-set with the \method{setName()} method, and retrieved with the
-\method{getName()} method.
-
-A thread can be flagged as a ``daemon thread''. The significance
-of this flag is that the entire Python program exits when only
-daemon threads are left. The initial value is inherited from the
-creating thread. The flag can be set with the \method{setDaemon()}
-method and retrieved with the \method{isDaemon()} method.
-
-There is a ``main thread'' object; this corresponds to the
-initial thread of control in the Python program. It is not a
-daemon thread.
-
-There is the possibility that ``dummy thread objects'' are created.
-These are thread objects corresponding to ``alien threads'', which
-are threads of control started outside the threading module, such as
-directly from C code. Dummy thread objects have limited
-functionality; they are always considered alive and daemonic, and
-cannot be \method{join()}ed. They are never deleted, since it is
-impossible to detect the termination of alien threads.
-
-
-\begin{classdesc}{Thread}{group=None, target=None, name=None,
- args=(), kwargs=\{\}}
-This constructor should always be called with keyword
-arguments. Arguments are:
-
-\var{group} should be \code{None}; reserved for future extension when
-a \class{ThreadGroup} class is implemented.
-
-\var{target} is the callable object to be invoked by the
-\method{run()} method. Defaults to \code{None}, meaning nothing is
-called.
-
-\var{name} is the thread name. By default, a unique name is
-constructed of the form ``Thread-\var{N}'' where \var{N} is a small
-decimal number.
-
-\var{args} is the argument tuple for the target invocation. Defaults
-to \code{()}.
-
-\var{kwargs} is a dictionary of keyword arguments for the target
-invocation. Defaults to \code{\{\}}.
-
-If the subclass overrides the constructor, it must make sure
-to invoke the base class constructor (\code{Thread.__init__()})
-before doing anything else to the thread.
-\end{classdesc}
-
-\begin{methoddesc}{start}{}
-Start the thread's activity.
-
-It must be called at most once per thread object. It arranges for the
-object's \method{run()} method to be invoked in a separate thread of
-control.
-
-This method will raise a \exception{RuntimeException} if called more
-than once on the same thread object.
-\end{methoddesc}
-
-\begin{methoddesc}{run}{}
-Method representing the thread's activity.
-
-You may override this method in a subclass. The standard
-\method{run()} method invokes the callable object passed to the
-object's constructor as the \var{target} argument, if any, with
-sequential and keyword arguments taken from the \var{args} and
-\var{kwargs} arguments, respectively.
-\end{methoddesc}
-
-\begin{methoddesc}{join}{\optional{timeout}}
-Wait until the thread terminates.
-This blocks the calling thread until the thread whose \method{join()}
-method is called terminates -- either normally or through an
-unhandled exception -- or until the optional timeout occurs.
-
-When the \var{timeout} argument is present and not \code{None}, it
-should be a floating point number specifying a timeout for the
-operation in seconds (or fractions thereof). As \method{join()} always
-returns \code{None}, you must call \method{isAlive()} to decide whether
-a timeout happened.
-
-When the \var{timeout} argument is not present or \code{None}, the
-operation will block until the thread terminates.
-
-A thread can be \method{join()}ed many times.
-
-\method{join()} may throw a \exception{RuntimeError}, if an attempt is
-made to join the current thread as that would cause a deadlock. It is
-also an error to \method{join()} a thread before it has been started
-and attempts to do so raises same exception.
-\end{methoddesc}
-
-\begin{methoddesc}{getName}{}
-Return the thread's name.
-\end{methoddesc}
-
-\begin{methoddesc}{setName}{name}
-Set the thread's name.
-
-The name is a string used for identification purposes only.
-It has no semantics. Multiple threads may be given the same
-name. The initial name is set by the constructor.
-\end{methoddesc}
-
-\begin{methoddesc}{isAlive}{}
-Return whether the thread is alive.
-
-Roughly, a thread is alive from the moment the \method{start()} method
-returns until its \method{run()} method terminates. The module
-function \function{enumerate()} returns a list of all alive threads.
-\end{methoddesc}
-
-\begin{methoddesc}{isDaemon}{}
-Return the thread's daemon flag.
-\end{methoddesc}
-
-\begin{methoddesc}{setDaemon}{daemonic}
-Set the thread's daemon flag to the Boolean value \var{daemonic}.
-This must be called before \method{start()} is called, otherwise
-\exception{RuntimeError} is raised.
-
-The initial value is inherited from the creating thread.
-
-The entire Python program exits when no alive non-daemon threads are
-left.
-\end{methoddesc}
-
-
-\subsection{Timer Objects \label{timer-objects}}
-
-This class represents an action that should be run only after a
-certain amount of time has passed --- a timer. \class{Timer} is a
-subclass of \class{Thread} and as such also functions as an example of
-creating custom threads.
-
-Timers are started, as with threads, by calling their \method{start()}
-method. The timer can be stopped (before its action has begun) by
-calling the \method{cancel()} method. The interval the timer will
-wait before executing its action may not be exactly the same as the
-interval specified by the user.
-
-For example:
-\begin{verbatim}
-def hello():
- print "hello, world"
-
-t = Timer(30.0, hello)
-t.start() # after 30 seconds, "hello, world" will be printed
-\end{verbatim}
-
-\begin{classdesc}{Timer}{interval, function, args=[], kwargs=\{\}}
-Create a timer that will run \var{function} with arguments \var{args} and
-keyword arguments \var{kwargs}, after \var{interval} seconds have passed.
-\end{classdesc}
-
-\begin{methoddesc}{cancel}{}
-Stop the timer, and cancel the execution of the timer's action. This
-will only work if the timer is still in its waiting stage.
-\end{methoddesc}
-
-\subsection{Using locks, conditions, and semaphores in the \keyword{with}
-statement \label{with-locks}}
-
-All of the objects provided by this module that have \method{acquire()} and
-\method{release()} methods can be used as context managers for a \keyword{with}
-statement. The \method{acquire()} method will be called when the block is
-entered, and \method{release()} will be called when the block is exited.
-
-Currently, \class{Lock}, \class{RLock}, \class{Condition}, \class{Semaphore},
-and \class{BoundedSemaphore} objects may be used as \keyword{with}
-statement context managers. For example:
-
-\begin{verbatim}
-from __future__ import with_statement
-import threading
-
-some_rlock = threading.RLock()
-
-with some_rlock:
- print "some_rlock is locked while this executes"
-\end{verbatim}
-
diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex
deleted file mode 100644
index 8a45bfc..0000000
--- a/Doc/lib/libtime.tex
+++ /dev/null
@@ -1,475 +0,0 @@
-\section{\module{time} ---
- Time access and conversions}
-
-\declaremodule{builtin}{time}
-\modulesynopsis{Time access and conversions.}
-
-
-This module provides various time-related functions. It is always
-available, but not all functions are available on all platforms. Most
-of the functions defined in this module call platform C library
-functions with the same name. It may sometimes be helpful to consult
-the platform documentation, because the semantics of these functions
-varies among platforms.
-
-An explanation of some terminology and conventions is in order.
-
-\begin{itemize}
-
-\item
-The \dfn{epoch}\index{epoch} is the point where the time starts. On
-January 1st of that year, at 0 hours, the ``time since the epoch'' is
-zero. For \UNIX, the epoch is 1970. To find out what the epoch is,
-look at \code{gmtime(0)}.
-
-\item
-The functions in this module do not handle dates and times before the
-epoch or far in the future. The cut-off point in the future is
-determined by the C library; for \UNIX, it is typically in
-2038\index{Year 2038}.
-
-\item
-\strong{Year 2000 (Y2K) issues}:\index{Year 2000}\index{Y2K} Python
-depends on the platform's C library, which generally doesn't have year
-2000 issues, since all dates and times are represented internally as
-seconds since the epoch. Functions accepting a \class{struct_time}
-(see below) generally require a 4-digit year. For backward
-compatibility, 2-digit years are supported if the module variable
-\code{accept2dyear} is a non-zero integer; this variable is
-initialized to \code{1} unless the environment variable
-\envvar{PYTHONY2K} is set to a non-empty string, in which case it is
-initialized to \code{0}. Thus, you can set
-\envvar{PYTHONY2K} to a non-empty string in the environment to require 4-digit
-years for all year input. When 2-digit years are accepted, they are
-converted according to the \POSIX{} or X/Open standard: values 69-99
-are mapped to 1969-1999, and values 0--68 are mapped to 2000--2068.
-Values 100--1899 are always illegal. Note that this is new as of
-Python 1.5.2(a2); earlier versions, up to Python 1.5.1 and 1.5.2a1,
-would add 1900 to year values below 1900.
-
-\item
-UTC\index{UTC} is Coordinated Universal Time\index{Coordinated
-Universal Time} (formerly known as Greenwich Mean
-Time,\index{Greenwich Mean Time} or GMT). The acronym UTC is not a
-mistake but a compromise between English and French.
-
-\item
-DST is Daylight Saving Time,\index{Daylight Saving Time} an adjustment
-of the timezone by (usually) one hour during part of the year. DST
-rules are magic (determined by local law) and can change from year to
-year. The C library has a table containing the local rules (often it
-is read from a system file for flexibility) and is the only source of
-True Wisdom in this respect.
-
-\item
-The precision of the various real-time functions may be less than
-suggested by the units in which their value or argument is expressed.
-E.g.\ on most \UNIX{} systems, the clock ``ticks'' only 50 or 100 times a
-second, and on the Mac, times are only accurate to whole seconds.
-
-\item
-On the other hand, the precision of \function{time()} and
-\function{sleep()} is better than their \UNIX{} equivalents: times are
-expressed as floating point numbers, \function{time()} returns the
-most accurate time available (using \UNIX{} \cfunction{gettimeofday()}
-where available), and \function{sleep()} will accept a time with a
-nonzero fraction (\UNIX{} \cfunction{select()} is used to implement
-this, where available).
-
-\item
-The time value as returned by \function{gmtime()},
-\function{localtime()}, and \function{strptime()}, and accepted by
-\function{asctime()}, \function{mktime()} and \function{strftime()},
-is a sequence of 9 integers. The return values of \function{gmtime()},
-\function{localtime()}, and \function{strptime()} also offer attribute
-names for individual fields.
-
-\begin{tableiii}{c|l|l}{textrm}{Index}{Attribute}{Values}
- \lineiii{0}{\member{tm_year}}{(for example, 1993)}
- \lineiii{1}{\member{tm_mon}}{range [1,12]}
- \lineiii{2}{\member{tm_mday}}{range [1,31]}
- \lineiii{3}{\member{tm_hour}}{range [0,23]}
- \lineiii{4}{\member{tm_min}}{range [0,59]}
- \lineiii{5}{\member{tm_sec}}{range [0,61]; see \strong{(1)} in \function{strftime()} description}
- \lineiii{6}{\member{tm_wday}}{range [0,6], Monday is 0}
- \lineiii{7}{\member{tm_yday}}{range [1,366]}
- \lineiii{8}{\member{tm_isdst}}{0, 1 or -1; see below}
-\end{tableiii}
-
-Note that unlike the C structure, the month value is a
-range of 1-12, not 0-11. A year value will be handled as described
-under ``Year 2000 (Y2K) issues'' above. A \code{-1} argument as the
-daylight savings flag, passed to \function{mktime()} will usually
-result in the correct daylight savings state to be filled in.
-
-When a tuple with an incorrect length is passed to a function
-expecting a \class{struct_time}, or having elements of the wrong type, a
-\exception{TypeError} is raised.
-
-\versionchanged[The time value sequence was changed from a tuple to a
- \class{struct_time}, with the addition of attribute names
- for the fields]{2.2}
-\end{itemize}
-
-The module defines the following functions and data items:
-
-
-\begin{datadesc}{accept2dyear}
-Boolean value indicating whether two-digit year values will be
-accepted. This is true by default, but will be set to false if the
-environment variable \envvar{PYTHONY2K} has been set to a non-empty
-string. It may also be modified at run time.
-\end{datadesc}
-
-\begin{datadesc}{altzone}
-The offset of the local DST timezone, in seconds west of UTC, if one
-is defined. This is negative if the local DST timezone is east of UTC
-(as in Western Europe, including the UK). Only use this if
-\code{daylight} is nonzero.
-\end{datadesc}
-
-\begin{funcdesc}{asctime}{\optional{t}}
-Convert a tuple or \class{struct_time} representing a time as returned
-by \function{gmtime()}
-or \function{localtime()} to a 24-character string of the following form:
-\code{'Sun Jun 20 23:21:05 1993'}. If \var{t} is not provided, the
-current time as returned by \function{localtime()} is used.
-Locale information is not used by \function{asctime()}.
-\note{Unlike the C function of the same name, there is no trailing
-newline.}
-\versionchanged[Allowed \var{t} to be omitted]{2.1}
-\end{funcdesc}
-
-\begin{funcdesc}{clock}{}
-On \UNIX, return
-the current processor time as a floating point number expressed in
-seconds. The precision, and in fact the very definition of the meaning
-of ``processor time''\index{CPU time}\index{processor time}, depends
-on that of the C function of the same name, but in any case, this is
-the function to use for benchmarking\index{benchmarking} Python or
-timing algorithms.
-
-On Windows, this function returns wall-clock seconds elapsed since the
-first call to this function, as a floating point number,
-based on the Win32 function \cfunction{QueryPerformanceCounter()}.
-The resolution is typically better than one microsecond.
-\end{funcdesc}
-
-\begin{funcdesc}{ctime}{\optional{secs}}
-Convert a time expressed in seconds since the epoch to a string
-representing local time. If \var{secs} is not provided or
-\constant{None}, the current time as returned by \function{time()} is
-used. \code{ctime(\var{secs})} is equivalent to
-\code{asctime(localtime(\var{secs}))}.
-Locale information is not used by \function{ctime()}.
-\versionchanged[Allowed \var{secs} to be omitted]{2.1}
-\versionchanged[If \var{secs} is \constant{None}, the current time is
- used]{2.4}
-\end{funcdesc}
-
-\begin{datadesc}{daylight}
-Nonzero if a DST timezone is defined.
-\end{datadesc}
-
-\begin{funcdesc}{gmtime}{\optional{secs}}
-Convert a time expressed in seconds since the epoch to a \class{struct_time}
-in UTC in which the dst flag is always zero. If \var{secs} is not
-provided or \constant{None}, the current time as returned by
-\function{time()} is used. Fractions of a second are ignored. See
-above for a description of the \class{struct_time} object. See
-\function{calendar.timegm()} for the inverse of this function.
-\versionchanged[Allowed \var{secs} to be omitted]{2.1}
-\versionchanged[If \var{secs} is \constant{None}, the current time is
- used]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{localtime}{\optional{secs}}
-Like \function{gmtime()} but converts to local time. If \var{secs} is
-not provided or \constant{None}, the current time as returned by
-\function{time()} is used. The dst flag is set to \code{1} when DST
-applies to the given time.
-\versionchanged[Allowed \var{secs} to be omitted]{2.1}
-\versionchanged[If \var{secs} is \constant{None}, the current time is
- used]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{mktime}{t}
-This is the inverse function of \function{localtime()}. Its argument
-is the \class{struct_time} or full 9-tuple (since the dst flag is
-needed; use \code{-1} as the dst flag if it is unknown) which
-expresses the time in
-\emph{local} time, not UTC. It returns a floating point number, for
-compatibility with \function{time()}. If the input value cannot be
-represented as a valid time, either \exception{OverflowError} or
-\exception{ValueError} will be raised (which depends on whether the
-invalid value is caught by Python or the underlying C libraries). The
-earliest date for which it can generate a time is platform-dependent.
-\end{funcdesc}
-
-\begin{funcdesc}{sleep}{secs}
-Suspend execution for the given number of seconds. The argument may
-be a floating point number to indicate a more precise sleep time.
-The actual suspension time may be less than that requested because any
-caught signal will terminate the \function{sleep()} following
-execution of that signal's catching routine. Also, the suspension
-time may be longer than requested by an arbitrary amount because of
-the scheduling of other activity in the system.
-\end{funcdesc}
-
-\begin{funcdesc}{strftime}{format\optional{, t}}
-Convert a tuple or \class{struct_time} representing a time as returned
-by \function{gmtime()} or \function{localtime()} to a string as
-specified by the \var{format} argument. If \var{t} is not
-provided, the current time as returned by \function{localtime()} is
-used. \var{format} must be a string. \exception{ValueError} is raised
-if any field in \var{t} is outside of the allowed range.
-\versionchanged[Allowed \var{t} to be omitted]{2.1}
-\versionchanged[\exception{ValueError} raised if a field in \var{t} is
-out of range]{2.4}
-\versionchanged[0 is now a legal argument for any position in the time tuple;
-if it is normally illegal the value is forced to a correct one.]{2.5}
-
-
-The following directives can be embedded in the \var{format} string.
-They are shown without the optional field width and precision
-specification, and are replaced by the indicated characters in the
-\function{strftime()} result:
-
-\begin{tableiii}{c|p{24em}|c}{code}{Directive}{Meaning}{Notes}
- \lineiii{\%a}{Locale's abbreviated weekday name.}{}
- \lineiii{\%A}{Locale's full weekday name.}{}
- \lineiii{\%b}{Locale's abbreviated month name.}{}
- \lineiii{\%B}{Locale's full month name.}{}
- \lineiii{\%c}{Locale's appropriate date and time representation.}{}
- \lineiii{\%d}{Day of the month as a decimal number [01,31].}{}
- \lineiii{\%H}{Hour (24-hour clock) as a decimal number [00,23].}{}
- \lineiii{\%I}{Hour (12-hour clock) as a decimal number [01,12].}{}
- \lineiii{\%j}{Day of the year as a decimal number [001,366].}{}
- \lineiii{\%m}{Month as a decimal number [01,12].}{}
- \lineiii{\%M}{Minute as a decimal number [00,59].}{}
- \lineiii{\%p}{Locale's equivalent of either AM or PM.}{(1)}
- \lineiii{\%S}{Second as a decimal number [00,61].}{(2)}
- \lineiii{\%U}{Week number of the year (Sunday as the first day of the
- week) as a decimal number [00,53]. All days in a new year
- preceding the first Sunday are considered to be in week 0.}{(3)}
- \lineiii{\%w}{Weekday as a decimal number [0(Sunday),6].}{}
- \lineiii{\%W}{Week number of the year (Monday as the first day of the
- week) as a decimal number [00,53]. All days in a new year
- preceding the first Monday are considered to be in week 0.}{(3)}
- \lineiii{\%x}{Locale's appropriate date representation.}{}
- \lineiii{\%X}{Locale's appropriate time representation.}{}
- \lineiii{\%y}{Year without century as a decimal number [00,99].}{}
- \lineiii{\%Y}{Year with century as a decimal number.}{}
- \lineiii{\%Z}{Time zone name (no characters if no time zone exists).}{}
- \lineiii{\%\%}{A literal \character{\%} character.}{}
-\end{tableiii}
-
-\noindent
-Notes:
-
-\begin{description}
- \item[(1)]
- When used with the \function{strptime()} function, the \code{\%p}
- directive only affects the output hour field if the \code{\%I} directive
- is used to parse the hour.
- \item[(2)]
- The range really is \code{0} to \code{61}; this accounts for leap
- seconds and the (very rare) double leap seconds.
- \item[(3)]
- When used with the \function{strptime()} function, \code{\%U} and \code{\%W}
- are only used in calculations when the day of the week and the year are
- specified.
-\end{description}
-
-Here is an example, a format for dates compatible with that specified
-in the \rfc{2822} Internet email standard.
- \footnote{The use of \code{\%Z} is now
- deprecated, but the \code{\%z} escape that expands to the preferred
- hour/minute offset is not supported by all ANSI C libraries. Also,
- a strict reading of the original 1982 \rfc{822} standard calls for
- a two-digit year (\%y rather than \%Y), but practice moved to
- 4-digit years long before the year 2000. The 4-digit year has
- been mandated by \rfc{2822}, which obsoletes \rfc{822}.}
-
-\begin{verbatim}
->>> from time import gmtime, strftime
->>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
-'Thu, 28 Jun 2001 14:17:15 +0000'
-\end{verbatim}
-
-Additional directives may be supported on certain platforms, but
-only the ones listed here have a meaning standardized by ANSI C.
-
-On some platforms, an optional field width and precision
-specification can immediately follow the initial \character{\%} of a
-directive in the following order; this is also not portable.
-The field width is normally 2 except for \code{\%j} where it is 3.
-\end{funcdesc}
-
-\begin{funcdesc}{strptime}{string\optional{, format}}
-Parse a string representing a time according to a format. The return
-value is a \class{struct_time} as returned by \function{gmtime()} or
-\function{localtime()}.
-
-The \var{format} parameter uses the same directives as those used by
-\function{strftime()}; it defaults to \code{"\%a \%b \%d \%H:\%M:\%S
- \%Y"} which matches the formatting returned by \function{ctime()}.
-If \var{string} cannot be parsed according to \var{format}, or if it
-has excess data after parsing, \exception{ValueError} is raised. The
-default values used to fill in any missing data when more accurate
-values cannot be inferred are \code{(1900, 1, 1, 0, 0, 0, 0, 1, -1)}.
-
-For example:
-
-\begin{verbatim}
->>> import time
->>> time.strptime("30 Nov 00", "%d %b %y")
-(2000, 11, 30, 0, 0, 0, 3, 335, -1)
-\end{verbatim}
-
-Support for the \code{\%Z} directive is based on the values contained in
-\code{tzname} and whether \code{daylight} is true. Because of this,
-it is platform-specific except for recognizing UTC and GMT which are
-always known (and are considered to be non-daylight savings
-timezones).
-
-Only the directives specified in the documentation are supported. Because
-\code{strftime()} is implemented per platform it can sometimes offer more
-directives than those listed. But \code{strptime()} is independent of any
-platform and thus does not necessarily support all directives available that
-are not documented as supported.
-\end{funcdesc}
-
-\begin{datadesc}{struct_time}
-The type of the time value sequence returned by \function{gmtime()},
-\function{localtime()}, and \function{strptime()}.
-\versionadded{2.2}
-\end{datadesc}
-
-\begin{funcdesc}{time}{}
-Return the time as a floating point number expressed in seconds since
-the epoch, in UTC. Note that even though the time is always returned
-as a floating point number, not all systems provide time with a better
-precision than 1 second. While this function normally returns
-non-decreasing values, it can return a lower value than a previous
-call if the system clock has been set back between the two calls.
-\end{funcdesc}
-
-\begin{datadesc}{timezone}
-The offset of the local (non-DST) timezone, in seconds west of UTC
-(negative in most of Western Europe, positive in the US, zero in the
-UK).
-\end{datadesc}
-
-\begin{datadesc}{tzname}
-A tuple of two strings: the first is the name of the local non-DST
-timezone, the second is the name of the local DST timezone. If no DST
-timezone is defined, the second string should not be used.
-\end{datadesc}
-
-\begin{funcdesc}{tzset}{}
-Resets the time conversion rules used by the library routines.
-The environment variable \envvar{TZ} specifies how this is done.
-\versionadded{2.3}
-
-Availability: \UNIX.
-
-\begin{notice}
-Although in many cases, changing the \envvar{TZ} environment variable
-may affect the output of functions like \function{localtime} without calling
-\function{tzset}, this behavior should not be relied on.
-
-The \envvar{TZ} environment variable should contain no whitespace.
-\end{notice}
-
-The standard format of the \envvar{TZ} environment variable is:
-(whitespace added for clarity)
-\begin{itemize}
- \item[std offset [dst [offset] [,start[/time], end[/time]]]]
-\end{itemize}
-
-Where:
-
-\begin{itemize}
- \item[std and dst]
- Three or more alphanumerics giving the timezone abbreviations.
- These will be propagated into time.tzname
-
- \item[offset]
- The offset has the form: \plusminus{} hh[:mm[:ss]].
- This indicates the value added the local time to arrive at UTC.
- If preceded by a '-', the timezone is east of the Prime
- Meridian; otherwise, it is west. If no offset follows
- dst, summer time is assumed to be one hour ahead of standard time.
-
- \item[start[/time],end[/time]]
- Indicates when to change to and back from DST. The format of the
- start and end dates are one of the following:
-
- \begin{itemize}
- \item[J\var{n}]
- The Julian day \var{n} (1 <= \var{n} <= 365). Leap days are not
- counted, so in all years February 28 is day 59 and
- March 1 is day 60.
-
- \item[\var{n}]
- The zero-based Julian day (0 <= \var{n} <= 365). Leap days are
- counted, and it is possible to refer to February 29.
-
- \item[M\var{m}.\var{n}.\var{d}]
- The \var{d}'th day (0 <= \var{d} <= 6) or week \var{n}
- of month \var{m} of the year (1 <= \var{n} <= 5,
- 1 <= \var{m} <= 12, where week 5 means "the last \var{d} day
- in month \var{m}" which may occur in either the fourth or
- the fifth week). Week 1 is the first week in which the
- \var{d}'th day occurs. Day zero is Sunday.
- \end{itemize}
-
- time has the same format as offset except that no leading sign ('-' or
- '+') is allowed. The default, if time is not given, is 02:00:00.
-\end{itemize}
-
-
-\begin{verbatim}
->>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
->>> time.tzset()
->>> time.strftime('%X %x %Z')
-'02:07:36 05/08/03 EDT'
->>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
->>> time.tzset()
->>> time.strftime('%X %x %Z')
-'16:08:12 05/08/03 AEST'
-\end{verbatim}
-
-On many \UNIX{} systems (including *BSD, Linux, Solaris, and Darwin), it
-is more convenient to use the system's zoneinfo (\manpage{tzfile}{5})
-database to specify the timezone rules. To do this, set the
-\envvar{TZ} environment variable to the path of the required timezone
-datafile, relative to the root of the systems 'zoneinfo' timezone database,
-usually located at \file{/usr/share/zoneinfo}. For example,
-\code{'US/Eastern'}, \code{'Australia/Melbourne'}, \code{'Egypt'} or
-\code{'Europe/Amsterdam'}.
-
-\begin{verbatim}
->>> os.environ['TZ'] = 'US/Eastern'
->>> time.tzset()
->>> time.tzname
-('EST', 'EDT')
->>> os.environ['TZ'] = 'Egypt'
->>> time.tzset()
->>> time.tzname
-('EET', 'EEST')
-\end{verbatim}
-
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{datetime}{More object-oriented interface to dates and times.}
- \seemodule{locale}{Internationalization services. The locale
- settings can affect the return values for some of
- the functions in the \module{time} module.}
- \seemodule{calendar}{General calendar-related functions.
- \function{timegm()} is the inverse of
- \function{gmtime()} from this module.}
-\end{seealso}
diff --git a/Doc/lib/libtimeit.tex b/Doc/lib/libtimeit.tex
deleted file mode 100644
index 968728f..0000000
--- a/Doc/lib/libtimeit.tex
+++ /dev/null
@@ -1,249 +0,0 @@
-\section{\module{timeit} ---
- Measure execution time of small code snippets}
-
-\declaremodule{standard}{timeit}
-\modulesynopsis{Measure the execution time of small code snippets.}
-
-\versionadded{2.3}
-\index{Benchmarking}
-\index{Performance}
-
-This module provides a simple way to time small bits of Python code.
-It has both command line as well as callable interfaces. It avoids a
-number of common traps for measuring execution times. See also Tim
-Peters' introduction to the ``Algorithms'' chapter in the
-\citetitle{Python Cookbook}, published by O'Reilly.
-
-The module defines the following public class:
-
-\begin{classdesc}{Timer}{\optional{stmt=\code{'pass'}
- \optional{, setup=\code{'pass'}
- \optional{, timer=<timer function>}}}}
-Class for timing execution speed of small code snippets.
-
-The constructor takes a statement to be timed, an additional statement
-used for setup, and a timer function. Both statements default to
-\code{'pass'}; the timer function is platform-dependent (see the
-module doc string). The statements may contain newlines, as long as
-they don't contain multi-line string literals.
-
-To measure the execution time of the first statement, use the
-\method{timeit()} method. The \method{repeat()} method is a
-convenience to call \method{timeit()} multiple times and return a list
-of results.
-
-\versionchanged[The \var{stmt} and \var{setup} parameters can now also
- take objects that are callable without arguments. This
- will embed calls to them in a timer function that will
- then be executed by \method{timeit()}. Note that the timing
- overhead is a little larger in this case because of the
- extra function calls]{2.6}
-\end{classdesc}
-
-\begin{methoddesc}{print_exc}{\optional{file=\constant{None}}}
-Helper to print a traceback from the timed code.
-
-Typical use:
-
-\begin{verbatim}
- t = Timer(...) # outside the try/except
- try:
- t.timeit(...) # or t.repeat(...)
- except:
- t.print_exc()
-\end{verbatim}
-
-The advantage over the standard traceback is that source lines in the
-compiled template will be displayed.
-The optional \var{file} argument directs where the traceback is sent;
-it defaults to \code{sys.stderr}.
-\end{methoddesc}
-
-\begin{methoddesc}{repeat}{\optional{repeat\code{=3} \optional{,
- number\code{=1000000}}}}
-Call \method{timeit()} a few times.
-
-This is a convenience function that calls the \method{timeit()}
-repeatedly, returning a list of results. The first argument specifies
-how many times to call \method{timeit()}. The second argument
-specifies the \var{number} argument for \function{timeit()}.
-
-\begin{notice}
-It's tempting to calculate mean and standard deviation from the result
-vector and report these. However, this is not very useful. In a typical
-case, the lowest value gives a lower bound for how fast your machine can run
-the given code snippet; higher values in the result vector are typically not
-caused by variability in Python's speed, but by other processes interfering
-with your timing accuracy. So the \function{min()} of the result is
-probably the only number you should be interested in. After that, you
-should look at the entire vector and apply common sense rather than
-statistics.
-\end{notice}
-\end{methoddesc}
-
-\begin{methoddesc}{timeit}{\optional{number\code{=1000000}}}
-Time \var{number} executions of the main statement.
-This executes the setup statement once, and then
-returns the time it takes to execute the main statement a number of
-times, measured in seconds as a float. The argument is the number of
-times through the loop, defaulting to one million. The main
-statement, the setup statement and the timer function to be used are
-passed to the constructor.
-
-\begin{notice}
-By default, \method{timeit()} temporarily turns off garbage collection
-during the timing. The advantage of this approach is that it makes
-independent timings more comparable. This disadvantage is that GC
-may be an important component of the performance of the function being
-measured. If so, GC can be re-enabled as the first statement in the
-\var{setup} string. For example:
-\begin{verbatim}
- timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()
-\end{verbatim}
-\end{notice}
-\end{methoddesc}
-
-
-Starting with version 2.6, the module also defines two convenience functions:
-
-\begin{funcdesc}{repeat}{stmt\optional{, setup\optional{, timer\optional{,
- repeat\code{=3} \optional{, number\code{=1000000}}}}}}
-Create a \class{Timer} instance with the given statement, setup code and timer
-function and run its \method{repeat} method with the given repeat count and
-\var{number} executions.
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{timeit}{stmt\optional{, setup\optional{, timer\optional{,
- number\code{=1000000}}}}}
-Create a \class{Timer} instance with the given statement, setup code and timer
-function and run its \method{timeit} method with \var{number} executions.
-\versionadded{2.6}
-\end{funcdesc}
-
-
-\subsection{Command Line Interface}
-
-When called as a program from the command line, the following form is used:
-
-\begin{verbatim}
-python -m timeit [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]
-\end{verbatim}
-
-where the following options are understood:
-
-\begin{description}
-\item[-n N/\longprogramopt{number=N}] how many times to execute 'statement'
-\item[-r N/\longprogramopt{repeat=N}] how many times to repeat the timer (default 3)
-\item[-s S/\longprogramopt{setup=S}] statement to be executed once initially (default
-\code{'pass'})
-\item[-t/\longprogramopt{time}] use \function{time.time()}
-(default on all platforms but Windows)
-\item[-c/\longprogramopt{clock}] use \function{time.clock()} (default on Windows)
-\item[-v/\longprogramopt{verbose}] print raw timing results; repeat for more digits
-precision
-\item[-h/\longprogramopt{help}] print a short usage message and exit
-\end{description}
-
-A multi-line statement may be given by specifying each line as a
-separate statement argument; indented lines are possible by enclosing
-an argument in quotes and using leading spaces. Multiple
-\programopt{-s} options are treated similarly.
-
-If \programopt{-n} is not given, a suitable number of loops is
-calculated by trying successive powers of 10 until the total time is
-at least 0.2 seconds.
-
-The default timer function is platform dependent. On Windows,
-\function{time.clock()} has microsecond granularity but
-\function{time.time()}'s granularity is 1/60th of a second; on \UNIX,
-\function{time.clock()} has 1/100th of a second granularity and
-\function{time.time()} is much more precise. On either platform, the
-default timer functions measure wall clock time, not the CPU time.
-This means that other processes running on the same computer may
-interfere with the timing. The best thing to do when accurate timing
-is necessary is to repeat the timing a few times and use the best
-time. The \programopt{-r} option is good for this; the default of 3
-repetitions is probably enough in most cases. On \UNIX, you can use
-\function{time.clock()} to measure CPU time.
-
-\begin{notice}
- There is a certain baseline overhead associated with executing a
- pass statement. The code here doesn't try to hide it, but you
- should be aware of it. The baseline overhead can be measured by
- invoking the program without arguments.
-\end{notice}
-
-The baseline overhead differs between Python versions! Also, to
-fairly compare older Python versions to Python 2.3, you may want to
-use Python's \programopt{-O} option for the older versions to avoid
-timing \code{SET_LINENO} instructions.
-
-\subsection{Examples}
-
-Here are two example sessions (one using the command line, one using
-the module interface) that compare the cost of using
-\function{hasattr()} vs. \keyword{try}/\keyword{except} to test for
-missing and present object attributes.
-
-\begin{verbatim}
-% timeit.py 'try:' ' str.__bool__' 'except AttributeError:' ' pass'
-100000 loops, best of 3: 15.7 usec per loop
-% timeit.py 'if hasattr(str, "__bool__"): pass'
-100000 loops, best of 3: 4.26 usec per loop
-% timeit.py 'try:' ' int.__bool__' 'except AttributeError:' ' pass'
-1000000 loops, best of 3: 1.43 usec per loop
-% timeit.py 'if hasattr(int, "__bool__"): pass'
-100000 loops, best of 3: 2.23 usec per loop
-\end{verbatim}
-
-\begin{verbatim}
->>> import timeit
->>> s = """\
-... try:
-... str.__bool__
-... except AttributeError:
-... pass
-... """
->>> t = timeit.Timer(stmt=s)
->>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
-17.09 usec/pass
->>> s = """\
-... if hasattr(str, '__bool__'): pass
-... """
->>> t = timeit.Timer(stmt=s)
->>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
-4.85 usec/pass
->>> s = """\
-... try:
-... int.__bool__
-... except AttributeError:
-... pass
-... """
->>> t = timeit.Timer(stmt=s)
->>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
-1.97 usec/pass
->>> s = """\
-... if hasattr(int, '__bool__'): pass
-... """
->>> t = timeit.Timer(stmt=s)
->>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
-3.15 usec/pass
-\end{verbatim}
-
-To give the \module{timeit} module access to functions you
-define, you can pass a \code{setup} parameter which contains an import
-statement:
-
-\begin{verbatim}
-def test():
- "Stupid test function"
- L = []
- for i in range(100):
- L.append(i)
-
-if __name__=='__main__':
- from timeit import Timer
- t = Timer("test()", "from __main__ import test")
- print t.timeit()
-\end{verbatim}
diff --git a/Doc/lib/libtoken.tex b/Doc/lib/libtoken.tex
deleted file mode 100644
index 47f4750..0000000
--- a/Doc/lib/libtoken.tex
+++ /dev/null
@@ -1,44 +0,0 @@
-\section{\module{token} ---
- Constants used with Python parse trees}
-
-\declaremodule{standard}{token}
-\modulesynopsis{Constants representing terminal nodes of the parse tree.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-This module provides constants which represent the numeric values of
-leaf nodes of the parse tree (terminal tokens). Refer to the file
-\file{Grammar/Grammar} in the Python distribution for the definitions
-of the names in the context of the language grammar. The specific
-numeric values which the names map to may change between Python
-versions.
-
-This module also provides one data object and some functions. The
-functions mirror definitions in the Python C header files.
-
-
-
-\begin{datadesc}{tok_name}
-Dictionary mapping the numeric values of the constants defined in this
-module back to name strings, allowing more human-readable
-representation of parse trees to be generated.
-\end{datadesc}
-
-\begin{funcdesc}{ISTERMINAL}{x}
-Return true for terminal token values.
-\end{funcdesc}
-
-\begin{funcdesc}{ISNONTERMINAL}{x}
-Return true for non-terminal token values.
-\end{funcdesc}
-
-\begin{funcdesc}{ISEOF}{x}
-Return true if \var{x} is the marker indicating the end of input.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{parser}{The second example for the \refmodule{parser}
- module shows how to use the \module{symbol}
- module.}
-\end{seealso}
diff --git a/Doc/lib/libtokenize.tex b/Doc/lib/libtokenize.tex
deleted file mode 100644
index 8c9ad3e..0000000
--- a/Doc/lib/libtokenize.tex
+++ /dev/null
@@ -1,119 +0,0 @@
-\section{\module{tokenize} ---
- Tokenizer for Python source}
-
-\declaremodule{standard}{tokenize}
-\modulesynopsis{Lexical scanner for Python source code.}
-\moduleauthor{Ka Ping Yee}{}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-The \module{tokenize} module provides a lexical scanner for Python
-source code, implemented in Python. The scanner in this module
-returns comments as tokens as well, making it useful for implementing
-``pretty-printers,'' including colorizers for on-screen displays.
-
-The primary entry point is a generator:
-
-\begin{funcdesc}{generate_tokens}{readline}
- The \function{generate_tokens()} generator requires one argment,
- \var{readline}, which must be a callable object which
- provides the same interface as the \method{readline()} method of
- built-in file objects (see section~\ref{bltin-file-objects}). Each
- call to the function should return one line of input as a string.
-
- The generator produces 5-tuples with these members:
- the token type;
- the token string;
- a 2-tuple \code{(\var{srow}, \var{scol})} of ints specifying the
- row and column where the token begins in the source;
- a 2-tuple \code{(\var{erow}, \var{ecol})} of ints specifying the
- row and column where the token ends in the source;
- and the line on which the token was found.
- The line passed is the \emph{logical} line;
- continuation lines are included.
- \versionadded{2.2}
-\end{funcdesc}
-
-An older entry point is retained for backward compatibility:
-
-\begin{funcdesc}{tokenize}{readline\optional{, tokeneater}}
- The \function{tokenize()} function accepts two parameters: one
- representing the input stream, and one providing an output mechanism
- for \function{tokenize()}.
-
- The first parameter, \var{readline}, must be a callable object which
- provides the same interface as the \method{readline()} method of
- built-in file objects (see section~\ref{bltin-file-objects}). Each
- call to the function should return one line of input as a string.
- Alternately, \var{readline} may be a callable object that signals
- completion by raising \exception{StopIteration}.
- \versionchanged[Added \exception{StopIteration} support]{2.5}
-
- The second parameter, \var{tokeneater}, must also be a callable
- object. It is called once for each token, with five arguments,
- corresponding to the tuples generated by \function{generate_tokens()}.
-\end{funcdesc}
-
-
-All constants from the \refmodule{token} module are also exported from
-\module{tokenize}, as are two additional token type values that might be
-passed to the \var{tokeneater} function by \function{tokenize()}:
-
-\begin{datadesc}{COMMENT}
- Token value used to indicate a comment.
-\end{datadesc}
-\begin{datadesc}{NL}
- Token value used to indicate a non-terminating newline. The NEWLINE
- token indicates the end of a logical line of Python code; NL tokens
- are generated when a logical line of code is continued over multiple
- physical lines.
-\end{datadesc}
-
-Another function is provided to reverse the tokenization process.
-This is useful for creating tools that tokenize a script, modify
-the token stream, and write back the modified script.
-
-\begin{funcdesc}{untokenize}{iterable}
- Converts tokens back into Python source code. The \var{iterable}
- must return sequences with at least two elements, the token type and
- the token string. Any additional sequence elements are ignored.
-
- The reconstructed script is returned as a single string. The
- result is guaranteed to tokenize back to match the input so that
- the conversion is lossless and round-trips are assured. The
- guarantee applies only to the token type and token string as
- the spacing between tokens (column positions) may change.
- \versionadded{2.5}
-\end{funcdesc}
-
-Example of a script re-writer that transforms float literals into
-Decimal objects:
-\begin{verbatim}
-def decistmt(s):
- """Substitute Decimals for floats in a string of statements.
-
- >>> from decimal import Decimal
- >>> s = 'print +21.3e-5*-.1234/81.7'
- >>> decistmt(s)
- "print +Decimal ('21.3e-5')*-Decimal ('.1234')/Decimal ('81.7')"
-
- >>> exec(s)
- -3.21716034272e-007
- >>> exec(decistmt(s))
- -3.217160342717258261933904529E-7
-
- """
- result = []
- g = generate_tokens(StringIO(s).readline) # tokenize the string
- for toknum, tokval, _, _, _ in g:
- if toknum == NUMBER and '.' in tokval: # replace NUMBER tokens
- result.extend([
- (NAME, 'Decimal'),
- (OP, '('),
- (STRING, repr(tokval)),
- (OP, ')')
- ])
- else:
- result.append((toknum, tokval))
- return untokenize(result)
-\end{verbatim}
diff --git a/Doc/lib/libtrace.tex b/Doc/lib/libtrace.tex
deleted file mode 100644
index 2465aac..0000000
--- a/Doc/lib/libtrace.tex
+++ /dev/null
@@ -1,125 +0,0 @@
-\section{\module{trace} ---
- Trace or track Python statement execution}
-
-\declaremodule{standard}{trace}
-\modulesynopsis{Trace or track Python statement execution.}
-
-The \module{trace} module allows you to trace program execution, generate
-annotated statement coverage listings, print caller/callee relationships and
-list functions executed during a program run. It can be used in another
-program or from the command line.
-
-\subsection{Command Line Usage\label{trace-cli}}
-
-The \module{trace} module can be invoked from the command line. It can be
-as simple as
-
-\begin{verbatim}
-python -m trace --count somefile.py ...
-\end{verbatim}
-
-The above will generate annotated listings of all Python modules imported
-during the execution of \file{somefile.py}.
-
-The following command-line arguments are supported:
-
-\begin{description}
-\item[\longprogramopt{trace}, \programopt{-t}]
-Display lines as they are executed.
-
-\item[\longprogramopt{count}, \programopt{-c}]
-Produce a set of annotated listing files upon program
-completion that shows how many times each statement was executed.
-
-\item[\longprogramopt{report}, \programopt{-r}]
-Produce an annotated list from an earlier program run that
-used the \longprogramopt{count} and \longprogramopt{file} arguments.
-
-\item[\longprogramopt{no-report}, \programopt{-R}]
-Do not generate annotated listings. This is useful if you intend to make
-several runs with \longprogramopt{count} then produce a single set
-of annotated listings at the end.
-
-\item[\longprogramopt{listfuncs}, \programopt{-l}]
-List the functions executed by running the program.
-
-\item[\longprogramopt{trackcalls}, \programopt{-T}]
-Generate calling relationships exposed by running the program.
-
-\item[\longprogramopt{file}, \programopt{-f}]
-Name a file containing (or to contain) counts.
-
-\item[\longprogramopt{coverdir}, \programopt{-C}]
-Name a directory in which to save annotated listing files.
-
-\item[\longprogramopt{missing}, \programopt{-m}]
-When generating annotated listings, mark lines which
-were not executed with `\code{>>>>>>}'.
-
-\item[\longprogramopt{summary}, \programopt{-s}]
-When using \longprogramopt{count} or \longprogramopt{report}, write a
-brief summary to stdout for each file processed.
-
-\item[\longprogramopt{ignore-module}]
-Ignore the named module and its submodules (if it is
-a package). May be given multiple times.
-
-\item[\longprogramopt{ignore-dir}]
-Ignore all modules and packages in the named directory
-and subdirectories. May be given multiple times.
-\end{description}
-
-\subsection{Programming Interface\label{trace-api}}
-
-\begin{classdesc}{Trace}{\optional{count=1\optional{, trace=1\optional{,
- countfuncs=0\optional{, countcallers=0\optional{,
- ignoremods=()\optional{, ignoredirs=()\optional{,
- infile=None\optional{, outfile=None}}}}}}}}}
-Create an object to trace execution of a single statement or expression.
-All parameters are optional. \var{count} enables counting of line numbers.
-\var{trace} enables line execution tracing. \var{countfuncs} enables
-listing of the functions called during the run. \var{countcallers} enables
-call relationship tracking. \var{ignoremods} is a list of modules or
-packages to ignore. \var{ignoredirs} is a list of directories whose modules
-or packages should be ignored. \var{infile} is the file from which to read
-stored count information. \var{outfile} is a file in which to write updated
-count information.
-\end{classdesc}
-
-\begin{methoddesc}[Trace]{run}{cmd}
-Run \var{cmd} under control of the Trace object with the current tracing
-parameters.
-\end{methoddesc}
-
-\begin{methoddesc}[Trace]{runctx}{cmd\optional{, globals=None\optional{,
- locals=None}}}
-Run \var{cmd} under control of the Trace object with the current tracing
-parameters in the defined global and local environments. If not defined,
-\var{globals} and \var{locals} default to empty dictionaries.
-\end{methoddesc}
-
-\begin{methoddesc}[Trace]{runfunc}{func, *args, **kwds}
-Call \var{func} with the given arguments under control of the
-\class{Trace} object with the current tracing parameters.
-\end{methoddesc}
-
-This is a simple example showing the use of this module:
-
-\begin{verbatim}
-import sys
-import trace
-
-# create a Trace object, telling it what to ignore, and whether to
-# do tracing or line-counting or both.
-tracer = trace.Trace(
- ignoredirs=[sys.prefix, sys.exec_prefix],
- trace=0,
- count=1)
-
-# run the new command using the given tracer
-tracer.run('main()')
-
-# make a report, placing output in /tmp
-r = tracer.results()
-r.write_results(show_missing=True, coverdir="/tmp")
-\end{verbatim}
diff --git a/Doc/lib/libtraceback.tex b/Doc/lib/libtraceback.tex
deleted file mode 100644
index a87b1ef..0000000
--- a/Doc/lib/libtraceback.tex
+++ /dev/null
@@ -1,152 +0,0 @@
-\section{\module{traceback} ---
- Print or retrieve a stack traceback}
-
-\declaremodule{standard}{traceback}
-\modulesynopsis{Print or retrieve a stack traceback.}
-
-
-This module provides a standard interface to extract, format and print
-stack traces of Python programs. It exactly mimics the behavior of
-the Python interpreter when it prints a stack trace. This is useful
-when you want to print stack traces under program control, such as in a
-``wrapper'' around the interpreter.
-
-The module uses traceback objects --- this is the object type that is
-stored in the \code{sys.last_traceback} variable and returned
-as the third item from \function{sys.exc_info()}.
-\obindex{traceback}
-
-The module defines the following functions:
-
-\begin{funcdesc}{print_tb}{traceback\optional{, limit\optional{, file}}}
-Print up to \var{limit} stack trace entries from \var{traceback}. If
-\var{limit} is omitted or \code{None}, all entries are printed.
-If \var{file} is omitted or \code{None}, the output goes to
-\code{sys.stderr}; otherwise it should be an open file or file-like
-object to receive the output.
-\end{funcdesc}
-
-\begin{funcdesc}{print_exception}{type, value, traceback\optional{,
- limit\optional{, file}}}
-Print exception information and up to \var{limit} stack trace entries
-from \var{traceback} to \var{file}.
-This differs from \function{print_tb()} in the
-following ways: (1) if \var{traceback} is not \code{None}, it prints a
-header \samp{Traceback (most recent call last):}; (2) it prints the
-exception \var{type} and \var{value} after the stack trace; (3) if
-\var{type} is \exception{SyntaxError} and \var{value} has the
-appropriate format, it prints the line where the syntax error occurred
-with a caret indicating the approximate position of the error.
-\end{funcdesc}
-
-\begin{funcdesc}{print_exc}{\optional{limit\optional{, file}}}
-This is a shorthand for \code{print_exception(*\function{sys.exc_info()}}.
-\end{funcdesc}
-
-\begin{funcdesc}{format_exc}{\optional{limit}}
-This is like \code{print_exc(\var{limit})} but returns a string
-instead of printing to a file.
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{print_last}{\optional{limit\optional{, file}}}
-This is a shorthand for \code{print_exception(sys.last_type,
-sys.last_value, sys.last_traceback, \var{limit}, \var{file})}.
-\end{funcdesc}
-
-\begin{funcdesc}{print_stack}{\optional{f\optional{, limit\optional{, file}}}}
-This function prints a stack trace from its invocation point. The
-optional \var{f} argument can be used to specify an alternate stack
-frame to start. The optional \var{limit} and \var{file} arguments have the
-same meaning as for \function{print_exception()}.
-\end{funcdesc}
-
-\begin{funcdesc}{extract_tb}{traceback\optional{, limit}}
-Return a list of up to \var{limit} ``pre-processed'' stack trace
-entries extracted from the traceback object \var{traceback}. It is
-useful for alternate formatting of stack traces. If \var{limit} is
-omitted or \code{None}, all entries are extracted. A
-``pre-processed'' stack trace entry is a quadruple (\var{filename},
-\var{line number}, \var{function name}, \var{text}) representing
-the information that is usually printed for a stack trace. The
-\var{text} is a string with leading and trailing whitespace
-stripped; if the source is not available it is \code{None}.
-\end{funcdesc}
-
-\begin{funcdesc}{extract_stack}{\optional{f\optional{, limit}}}
-Extract the raw traceback from the current stack frame. The return
-value has the same format as for \function{extract_tb()}. The
-optional \var{f} and \var{limit} arguments have the same meaning as
-for \function{print_stack()}.
-\end{funcdesc}
-
-\begin{funcdesc}{format_list}{list}
-Given a list of tuples as returned by \function{extract_tb()} or
-\function{extract_stack()}, return a list of strings ready for
-printing. Each string in the resulting list corresponds to the item
-with the same index in the argument list. Each string ends in a
-newline; the strings may contain internal newlines as well, for those
-items whose source text line is not \code{None}.
-\end{funcdesc}
-
-\begin{funcdesc}{format_exception_only}{type, value}
-Format the exception part of a traceback. The arguments are the
-exception type and value such as given by \code{sys.last_type} and
-\code{sys.last_value}. The return value is a list of strings, each
-ending in a newline. Normally, the list contains a single string;
-however, for \exception{SyntaxError} exceptions, it contains several
-lines that (when printed) display detailed information about where the
-syntax error occurred. The message indicating which exception
-occurred is the always last string in the list.
-\end{funcdesc}
-
-\begin{funcdesc}{format_exception}{type, value, tb\optional{, limit}}
-Format a stack trace and the exception information. The arguments
-have the same meaning as the corresponding arguments to
-\function{print_exception()}. The return value is a list of strings,
-each ending in a newline and some containing internal newlines. When
-these lines are concatenated and printed, exactly the same text is
-printed as does \function{print_exception()}.
-\end{funcdesc}
-
-\begin{funcdesc}{format_tb}{tb\optional{, limit}}
-A shorthand for \code{format_list(extract_tb(\var{tb}, \var{limit}))}.
-\end{funcdesc}
-
-\begin{funcdesc}{format_stack}{\optional{f\optional{, limit}}}
-A shorthand for \code{format_list(extract_stack(\var{f}, \var{limit}))}.
-\end{funcdesc}
-
-\begin{funcdesc}{tb_lineno}{tb}
-This function returns the current line number set in the traceback
-object. This function was necessary because in versions of Python
-prior to 2.3 when the \programopt{-O} flag was passed to Python the
-\code{\var{tb}.tb_lineno} was not updated correctly. This function
-has no use in versions past 2.3.
-\end{funcdesc}
-
-
-\subsection{Traceback Example \label{traceback-example}}
-
-This simple example implements a basic read-eval-print loop, similar
-to (but less useful than) the standard Python interactive interpreter
-loop. For a more complete implementation of the interpreter loop,
-refer to the \refmodule{code} module.
-
-\begin{verbatim}
-import sys, traceback
-
-def run_user_code(envdir):
- source = raw_input(">>> ")
- try:
- exec(source, envdir)
- except:
- print "Exception in user code:"
- print '-'*60
- traceback.print_exc(file=sys.stdout)
- print '-'*60
-
-envdir = {}
-while 1:
- run_user_code(envdir)
-\end{verbatim}
diff --git a/Doc/lib/libtty.tex b/Doc/lib/libtty.tex
deleted file mode 100644
index d42771a..0000000
--- a/Doc/lib/libtty.tex
+++ /dev/null
@@ -1,34 +0,0 @@
-\section{\module{tty} ---
- Terminal control functions}
-
-\declaremodule{standard}{tty}
- \platform{Unix}
-\moduleauthor{Steen Lumholt}{}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Utility functions that perform common terminal control
- operations.}
-
-The \module{tty} module defines functions for putting the tty into
-cbreak and raw modes.
-
-Because it requires the \refmodule{termios} module, it will work
-only on \UNIX.
-
-The \module{tty} module defines the following functions:
-
-\begin{funcdesc}{setraw}{fd\optional{, when}}
-Change the mode of the file descriptor \var{fd} to raw. If \var{when}
-is omitted, it defaults to \constant{termios.TCSAFLUSH}, and is passed
-to \function{termios.tcsetattr()}.
-\end{funcdesc}
-
-\begin{funcdesc}{setcbreak}{fd\optional{, when}}
-Change the mode of file descriptor \var{fd} to cbreak. If \var{when}
-is omitted, it defaults to \constant{termios.TCSAFLUSH}, and is passed
-to \function{termios.tcsetattr()}.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{termios}{Low-level terminal control interface.}
-\end{seealso}
diff --git a/Doc/lib/libturtle.tex b/Doc/lib/libturtle.tex
deleted file mode 100644
index fa8f0dd..0000000
--- a/Doc/lib/libturtle.tex
+++ /dev/null
@@ -1,268 +0,0 @@
-\section{\module{turtle} ---
- Turtle graphics for Tk}
-
-\declaremodule{standard}{turtle}
- \platform{Tk}
-\moduleauthor{Guido van Rossum}{guido@python.org}
-\modulesynopsis{An environment for turtle graphics.}
-
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-
-
-The \module{turtle} module provides turtle graphics primitives, in both an
-object-oriented and procedure-oriented ways. Because it uses \module{Tkinter}
-for the underlying graphics, it needs a version of python installed with
-Tk support.
-
-The procedural interface uses a pen and a canvas which are automagically
-created when any of the functions are called.
-
-The \module{turtle} module defines the following functions:
-
-\begin{funcdesc}{degrees}{}
-Set angle measurement units to degrees.
-\end{funcdesc}
-
-\begin{funcdesc}{radians}{}
-Set angle measurement units to radians.
-\end{funcdesc}
-
-\begin{funcdesc}{setup}{**kwargs}
-Sets the size and position of the main window. Keywords are:
-\begin{itemize}
- \item \code{width}: either a size in pixels or a fraction of the screen.
- The default is 50\% of the screen.
- \item \code{height}: either a size in pixels or a fraction of the screen.
- The default is 50\% of the screen.
- \item \code{startx}: starting position in pixels from the left edge
- of the screen. \code{None} is the default value and
- centers the window horizontally on screen.
- \item \code{starty}: starting position in pixels from the top edge
- of the screen. \code{None} is the default value and
- centers the window vertically on screen.
-\end{itemize}
-
- Examples:
-
-\begin{verbatim}
-# Uses default geometry: 50% x 50% of screen, centered.
-setup()
-
-# Sets window to 200x200 pixels, in upper left of screen
-setup (width=200, height=200, startx=0, starty=0)
-
-# Sets window to 75% of screen by 50% of screen, and centers it.
-setup(width=.75, height=0.5, startx=None, starty=None)
-\end{verbatim}
-
-\end{funcdesc}
-
-\begin{funcdesc}{title}{title_str}
-Set the window's title to \var{title}.
-\end{funcdesc}
-
-\begin{funcdesc}{done}{}
-Enters the Tk main loop. The window will continue to
-be displayed until the user closes it or the process is killed.
-\end{funcdesc}
-
-\begin{funcdesc}{reset}{}
-Clear the screen, re-center the pen, and set variables to the default
-values.
-\end{funcdesc}
-
-\begin{funcdesc}{clear}{}
-Clear the screen.
-\end{funcdesc}
-
-\begin{funcdesc}{tracer}{flag}
-Set tracing on/off (according to whether flag is true or not). Tracing
-means line are drawn more slowly, with an animation of an arrow along the
-line.
-\end{funcdesc}
-
-\begin{funcdesc}{speed}{speed}
-Set the speed of the turtle. Valid values for the parameter
-\var{speed} are \code{'fastest'} (no delay), \code{'fast'},
-(delay 5ms), \code{'normal'} (delay 10ms), \code{'slow'}
-(delay 15ms), and \code{'slowest'} (delay 20ms).
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{delay}{delay}
-Set the speed of the turtle to \var{delay}, which is given
-in ms. \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{forward}{distance}
-Go forward \var{distance} steps.
-\end{funcdesc}
-
-\begin{funcdesc}{backward}{distance}
-Go backward \var{distance} steps.
-\end{funcdesc}
-
-\begin{funcdesc}{left}{angle}
-Turn left \var{angle} units. Units are by default degrees, but can be
-set via the \function{degrees()} and \function{radians()} functions.
-\end{funcdesc}
-
-\begin{funcdesc}{right}{angle}
-Turn right \var{angle} units. Units are by default degrees, but can be
-set via the \function{degrees()} and \function{radians()} functions.
-\end{funcdesc}
-
-\begin{funcdesc}{up}{}
-Move the pen up --- stop drawing.
-\end{funcdesc}
-
-\begin{funcdesc}{down}{}
-Move the pen down --- draw when moving.
-\end{funcdesc}
-
-\begin{funcdesc}{width}{width}
-Set the line width to \var{width}.
-\end{funcdesc}
-
-\begin{funcdesc}{color}{s}
-\funclineni{color}{(r, g, b)}
-\funclineni{color}{r, g, b}
-Set the pen color. In the first form, the color is specified as a
-Tk color specification as a string. The second form specifies the
-color as a tuple of the RGB values, each in the range [0..1]. For the
-third form, the color is specified giving the RGB values as three
-separate parameters (each in the range [0..1]).
-\end{funcdesc}
-
-\begin{funcdesc}{write}{text\optional{, move}}
-Write \var{text} at the current pen position. If \var{move} is true,
-the pen is moved to the bottom-right corner of the text. By default,
-\var{move} is false.
-\end{funcdesc}
-
-\begin{funcdesc}{fill}{flag}
-The complete specifications are rather complex, but the recommended
-usage is: call \code{fill(1)} before drawing a path you want to fill,
-and call \code{fill(0)} when you finish to draw the path.
-\end{funcdesc}
-
-\begin{funcdesc}{begin\_fill}{}
-Switch turtle into filling mode;
-Must eventually be followed by a corresponding end_fill() call.
-Otherwise it will be ignored.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{end\_fill}{}
-End filling mode, and fill the shape; equivalent to \code{fill(0)}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{circle}{radius\optional{, extent}}
-Draw a circle with radius \var{radius} whose center-point is
-\var{radius} units left of the turtle.
-\var{extent} determines which part of a circle is drawn: if
-not given it defaults to a full circle.
-
-If \var{extent} is not a full circle, one endpoint of the arc is the
-current pen position. The arc is drawn in a counter clockwise
-direction if \var{radius} is positive, otherwise in a clockwise
-direction. In the process, the direction of the turtle is changed
-by the amount of the \var{extent}.
-\end{funcdesc}
-
-\begin{funcdesc}{goto}{x, y}
-\funclineni{goto}{(x, y)}
-Go to co-ordinates \var{x}, \var{y}. The co-ordinates may be
-specified either as two separate arguments or as a 2-tuple.
-\end{funcdesc}
-
-\begin{funcdesc}{towards}{x, y}
-Return the angle of the line from the turtle's position
-to the point \var{x}, \var{y}. The co-ordinates may be
-specified either as two separate arguments, as a 2-tuple,
-or as another pen object.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{heading}{}
-Return the current orientation of the turtle.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{setheading}{angle}
-Set the orientation of the turtle to \var{angle}.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{position}{}
-Return the current location of the turtle as an \code{(x,y)} pair.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{setx}{x}
-Set the x coordinate of the turtle to \var{x}.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{sety}{y}
-Set the y coordinate of the turtle to \var{y}.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{window\_width}{}
-Return the width of the canvas window.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{window\_height}{}
-Return the height of the canvas window.
-\versionadded{2.3}
-\end{funcdesc}
-
-This module also does \code{from math import *}, so see the
-documentation for the \refmodule{math} module for additional constants
-and functions useful for turtle graphics.
-
-\begin{funcdesc}{demo}{}
-Exercise the module a bit.
-\end{funcdesc}
-
-\begin{excdesc}{Error}
-Exception raised on any error caught by this module.
-\end{excdesc}
-
-For examples, see the code of the \function{demo()} function.
-
-This module defines the following classes:
-
-\begin{classdesc}{Pen}{}
-Define a pen. All above functions can be called as a methods on the given
-pen. The constructor automatically creates a canvas do be drawn on.
-\end{classdesc}
-
-\begin{classdesc}{Turtle}{}
-Define a pen. This is essentially a synonym for \code{Pen()};
-\class{Turtle} is an empty subclass of \class{Pen}.
-\end{classdesc}
-
-\begin{classdesc}{RawPen}{canvas}
-Define a pen which draws on a canvas \var{canvas}. This is useful if
-you want to use the module to create graphics in a ``real'' program.
-\end{classdesc}
-
-\subsection{Turtle, Pen and RawPen Objects \label{pen-rawpen-objects}}
-
-Most of the global functions available in the module are also
-available as methods of the \class{Turtle}, \class{Pen} and
-\class{RawPen} classes, affecting only the state of the given pen.
-
-The only method which is more powerful as a method is
-\function{degrees()}, which takes an optional argument letting
-you specify the number of units corresponding to a full circle:
-
-\begin{methoddesc}[Turtle]{degrees}{\optional{fullcircle}}
-\var{fullcircle} is by default 360. This can cause the pen to have any
-angular units whatever: give \var{fullcircle} 2*$\pi$ for radians, or
-400 for gradians.
-\end{methoddesc}
diff --git a/Doc/lib/libtypes.tex b/Doc/lib/libtypes.tex
deleted file mode 100644
index 2b143b9..0000000
--- a/Doc/lib/libtypes.tex
+++ /dev/null
@@ -1,211 +0,0 @@
-\section{\module{types} ---
- Names for built-in types}
-
-\declaremodule{standard}{types}
-\modulesynopsis{Names for built-in types.}
-
-
-This module defines names for some object types that are used by
-the standard Python interpreter, but not for the types defined by various
-extension modules. Also, it does not include some of the types that
-arise during processing such as the \code{listiterator} type.
-It is safe to use \samp{from types import *} ---
-the module does not export any names besides the ones listed here.
-New names exported by future versions of this module will all end in
-\samp{Type}.
-
-Typical use is for functions that do different things depending on
-their argument types, like the following:
-
-\begin{verbatim}
-from types import *
-def delete(mylist, item):
- if type(item) is IntType:
- del mylist[item]
- else:
- mylist.remove(item)
-\end{verbatim}
-
-Starting in Python 2.2, built-in factory functions such as
-\function{int()} and \function{str()} are also names for the
-corresponding types. This is now the preferred way to access
-the type instead of using the \module{types} module. Accordingly,
-the example above should be written as follows:
-
-\begin{verbatim}
-def delete(mylist, item):
- if isinstance(item, int):
- del mylist[item]
- else:
- mylist.remove(item)
-\end{verbatim}
-
-The module defines the following names:
-
-\begin{datadesc}{NoneType}
-The type of \code{None}.
-\end{datadesc}
-
-\begin{datadesc}{TypeType}
-The type of type objects (such as returned by
-\function{type()}\bifuncindex{type}).
-\end{datadesc}
-
-\begin{datadesc}{BooleanType}
-The type of the \class{bool} values \code{True} and \code{False}; this
-is an alias of the built-in \function{bool()} function.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{IntType}
-The type of integers (e.g. \code{1}).
-\end{datadesc}
-
-\begin{datadesc}{LongType}
-The type of long integers (e.g. \code{1L}).
-\end{datadesc}
-
-\begin{datadesc}{FloatType}
-The type of floating point numbers (e.g. \code{1.0}).
-\end{datadesc}
-
-\begin{datadesc}{ComplexType}
-The type of complex numbers (e.g. \code{1.0j}). This is not defined
-if Python was built without complex number support.
-\end{datadesc}
-
-\begin{datadesc}{StringType}
-The type of character strings (e.g. \code{'Spam'}).
-\end{datadesc}
-
-\begin{datadesc}{UnicodeType}
-The type of Unicode character strings (e.g. \code{u'Spam'}). This is
-not defined if Python was built without Unicode support.
-\end{datadesc}
-
-\begin{datadesc}{TupleType}
-The type of tuples (e.g. \code{(1, 2, 3, 'Spam')}).
-\end{datadesc}
-
-\begin{datadesc}{ListType}
-The type of lists (e.g. \code{[0, 1, 2, 3]}).
-\end{datadesc}
-
-\begin{datadesc}{DictType}
-The type of dictionaries (e.g. \code{\{'Bacon': 1, 'Ham': 0\}}).
-\end{datadesc}
-
-\begin{datadesc}{DictionaryType}
-An alternate name for \code{DictType}.
-\end{datadesc}
-
-\begin{datadesc}{FunctionType}
-The type of user-defined functions and lambdas.
-\end{datadesc}
-
-\begin{datadesc}{LambdaType}
-An alternate name for \code{FunctionType}.
-\end{datadesc}
-
-\begin{datadesc}{GeneratorType}
-The type of generator-iterator objects, produced by calling a
-generator function.
-\versionadded{2.2}
-\end{datadesc}
-
-\begin{datadesc}{CodeType}
-The type for code objects such as returned by
-\function{compile()}\bifuncindex{compile}.
-\end{datadesc}
-
-\begin{datadesc}{ClassType}
-The type of user-defined classes.
-\end{datadesc}
-
-\begin{datadesc}{MethodType}
-The type of methods of user-defined class instances.
-\end{datadesc}
-
-\begin{datadesc}{UnboundMethodType}
-An alternate name for \code{MethodType}.
-\end{datadesc}
-
-\begin{datadesc}{BuiltinFunctionType}
-The type of built-in functions like \function{len()} or
-\function{sys.exit()}.
-\end{datadesc}
-
-\begin{datadesc}{BuiltinMethodType}
-An alternate name for \code{BuiltinFunction}.
-\end{datadesc}
-
-\begin{datadesc}{ModuleType}
-The type of modules.
-\end{datadesc}
-
-\begin{datadesc}{FileType}
-The type of open file objects such as \code{sys.stdout}.
-\end{datadesc}
-
-\begin{datadesc}{RangeType}
-The type of range objects returned by
-\function{range()}\bifuncindex{range}.
-\end{datadesc}
-
-\begin{datadesc}{SliceType}
-The type of objects returned by
-\function{slice()}\bifuncindex{slice}.
-\end{datadesc}
-
-\begin{datadesc}{EllipsisType}
-The type of \code{Ellipsis}.
-\end{datadesc}
-
-\begin{datadesc}{TracebackType}
-The type of traceback objects such as found in
-\code{sys.exc_info()[2]}.
-\end{datadesc}
-
-\begin{datadesc}{FrameType}
-The type of frame objects such as found in \code{tb.tb_frame} if
-\code{tb} is a traceback object.
-\end{datadesc}
-
-\begin{datadesc}{BufferType}
-The type of buffer objects created by the
-\function{buffer()}\bifuncindex{buffer} function.
-\end{datadesc}
-
-\begin{datadesc}{DictProxyType}
-The type of dict proxies, such as \code{TypeType.__dict__}.
-\end{datadesc}
-
-\begin{datadesc}{NotImplementedType}
-The type of \code{NotImplemented}
-\end{datadesc}
-
-\begin{datadesc}{GetSetDescriptorType}
-The type of objects defined in extension modules with \code{PyGetSetDef}, such
-as \code{FrameType.f_locals} or \code{array.array.typecode}. This constant is
-not defined in implementations of Python that do not have such extension
-types, so for portable code use \code{hasattr(types, 'GetSetDescriptorType')}.
-\versionadded{2.5}
-\end{datadesc}
-
-\begin{datadesc}{MemberDescriptorType}
-The type of objects defined in extension modules with \code{PyMemberDef}, such
-as \code {datetime.timedelta.days}. This constant is not defined in
-implementations of Python that do not have such extension types, so for
-portable code use \code{hasattr(types, 'MemberDescriptorType')}.
-\versionadded{2.5}
-\end{datadesc}
-
-\begin{datadesc}{StringTypes}
-A sequence containing \code{StringType} and \code{UnicodeType} used to
-facilitate easier checking for any string object. Using this is more
-portable than using a sequence of the two string types constructed
-elsewhere since it only contains \code{UnicodeType} if it has been
-built in the running version of Python. For example:
-\code{isinstance(s, types.StringTypes)}.
-\versionadded{2.2}
-\end{datadesc}
diff --git a/Doc/lib/libundoc.tex b/Doc/lib/libundoc.tex
deleted file mode 100644
index 6f51eee..0000000
--- a/Doc/lib/libundoc.tex
+++ /dev/null
@@ -1,82 +0,0 @@
-\chapter{Undocumented Modules \label{undoc}}
-
-Here's a quick listing of modules that are currently undocumented, but
-that should be documented. Feel free to contribute documentation for
-them! (Send via email to \email{docs@python.org}.)
-
-The idea and original contents for this chapter were taken
-from a posting by Fredrik Lundh; the specific contents of this chapter
-have been substantially revised.
-
-
-\section{Frameworks}
-
-Frameworks tend to be harder to document, but are well worth the
-effort spent.
-
-\begin{description}
-\item None at this time.
-\end{description}
-
-
-\section{Miscellaneous useful utilities}
-
-Some of these are very old and/or not very robust; marked with ``hmm.''
-
-\begin{description}
-\item[\module{bdb}]
---- A generic Python debugger base class (used by pdb).
-
-\item[\module{ihooks}]
---- Import hook support (for \refmodule{rexec}; may become obsolete).
-\end{description}
-
-
-
-\section{Platform specific modules}
-
-These modules are used to implement the \refmodule{os.path} module,
-and are not documented beyond this mention. There's little need to
-document these.
-
-\begin{description}
-\item[\module{ntpath}]
---- Implementation of \module{os.path} on Win32, Win64, WinCE, and
- OS/2 platforms.
-
-\item[\module{posixpath}]
---- Implementation of \module{os.path} on \POSIX.
-\end{description}
-
-
-\section{Multimedia}
-
-\begin{description}
-\item[\module{sunaudio}]
---- Interpret Sun audio headers (may become obsolete or a tool/demo).
-\end{description}
-
-
-\section{Obsolete \label{obsolete-modules}}
-
-These modules are not normally available for import; additional work
-must be done to make them available.
-
-%%% lib-old is empty as of Python 2.5
-% Those which are written in Python will be installed into the directory
-% \file{lib-old/} installed as part of the standard library. To use
-% these, the directory must be added to \code{sys.path}, possibly using
-% \envvar{PYTHONPATH}.
-
-These extension modules written in C are not built by default.
-Under \UNIX, these must be enabled by uncommenting the appropriate
-lines in \file{Modules/Setup} in the build tree and either rebuilding
-Python if the modules are statically linked, or building and
-installing the shared object if using dynamically-loaded extensions.
-
-% XXX need Windows instructions!
-
-\begin{description}
-\item
---- This section should be empty for Python 3.0.
-\end{description}
diff --git a/Doc/lib/libunicodedata.tex b/Doc/lib/libunicodedata.tex
deleted file mode 100644
index 435466a..0000000
--- a/Doc/lib/libunicodedata.tex
+++ /dev/null
@@ -1,160 +0,0 @@
-\section{\module{unicodedata} ---
- Unicode Database}
-
-\declaremodule{standard}{unicodedata}
-\modulesynopsis{Access the Unicode Database.}
-\moduleauthor{Marc-Andre Lemburg}{mal@lemburg.com}
-\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\index{Unicode}
-\index{character}
-\indexii{Unicode}{database}
-
-This module provides access to the Unicode Character Database which
-defines character properties for all Unicode characters. The data in
-this database is based on the \file{UnicodeData.txt} file version
-4.1.0 which is publicly available from \url{ftp://ftp.unicode.org/}.
-
-The module uses the same names and symbols as defined by the
-UnicodeData File Format 4.1.0 (see
-\url{http://www.unicode.org/Public/4.1.0/ucd/UCD.html}). It
-defines the following functions:
-
-\begin{funcdesc}{lookup}{name}
- Look up character by name. If a character with the
- given name is found, return the corresponding Unicode
- character. If not found, \exception{KeyError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{name}{unichr\optional{, default}}
- Returns the name assigned to the Unicode character
- \var{unichr} as a string. If no name is defined,
- \var{default} is returned, or, if not given,
- \exception{ValueError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{decimal}{unichr\optional{, default}}
- Returns the decimal value assigned to the Unicode character
- \var{unichr} as integer. If no such value is defined,
- \var{default} is returned, or, if not given,
- \exception{ValueError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{digit}{unichr\optional{, default}}
- Returns the digit value assigned to the Unicode character
- \var{unichr} as integer. If no such value is defined,
- \var{default} is returned, or, if not given,
- \exception{ValueError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{numeric}{unichr\optional{, default}}
- Returns the numeric value assigned to the Unicode character
- \var{unichr} as float. If no such value is defined, \var{default} is
- returned, or, if not given, \exception{ValueError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{category}{unichr}
- Returns the general category assigned to the Unicode character
- \var{unichr} as string.
-\end{funcdesc}
-
-\begin{funcdesc}{bidirectional}{unichr}
- Returns the bidirectional category assigned to the Unicode character
- \var{unichr} as string. If no such value is defined, an empty string
- is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{combining}{unichr}
- Returns the canonical combining class assigned to the Unicode
- character \var{unichr} as integer. Returns \code{0} if no combining
- class is defined.
-\end{funcdesc}
-
-\begin{funcdesc}{east_asian_width}{unichr}
- Returns the east asian width assigned to the Unicode character
- \var{unichr} as string.
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{mirrored}{unichr}
- Returns the mirrored property assigned to the Unicode character
- \var{unichr} as integer. Returns \code{1} if the character has been
- identified as a ``mirrored'' character in bidirectional text,
- \code{0} otherwise.
-\end{funcdesc}
-
-\begin{funcdesc}{decomposition}{unichr}
- Returns the character decomposition mapping assigned to the Unicode
- character \var{unichr} as string. An empty string is returned in case
- no such mapping is defined.
-\end{funcdesc}
-
-\begin{funcdesc}{normalize}{form, unistr}
-
-Return the normal form \var{form} for the Unicode string \var{unistr}.
-Valid values for \var{form} are 'NFC', 'NFKC', 'NFD', and 'NFKD'.
-
-The Unicode standard defines various normalization forms of a Unicode
-string, based on the definition of canonical equivalence and
-compatibility equivalence. In Unicode, several characters can be
-expressed in various way. For example, the character U+00C7 (LATIN
-CAPITAL LETTER C WITH CEDILLA) can also be expressed as the sequence
-U+0043 (LATIN CAPITAL LETTER C) U+0327 (COMBINING CEDILLA).
-
-For each character, there are two normal forms: normal form C and
-normal form D. Normal form D (NFD) is also known as canonical
-decomposition, and translates each character into its decomposed form.
-Normal form C (NFC) first applies a canonical decomposition, then
-composes pre-combined characters again.
-
-In addition to these two forms, there are two additional normal forms
-based on compatibility equivalence. In Unicode, certain characters are
-supported which normally would be unified with other characters. For
-example, U+2160 (ROMAN NUMERAL ONE) is really the same thing as U+0049
-(LATIN CAPITAL LETTER I). However, it is supported in Unicode for
-compatibility with existing character sets (e.g. gb2312).
-
-The normal form KD (NFKD) will apply the compatibility decomposition,
-i.e. replace all compatibility characters with their equivalents. The
-normal form KC (NFKC) first applies the compatibility decomposition,
-followed by the canonical composition.
-
-\versionadded{2.3}
-\end{funcdesc}
-
-In addition, the module exposes the following constant:
-
-\begin{datadesc}{unidata_version}
-The version of the Unicode database used in this module.
-
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{ucd_3_2_0}
-This is an object that has the same methods as the entire
-module, but uses the Unicode database version 3.2 instead,
-for applications that require this specific version of
-the Unicode database (such as IDNA).
-
-\versionadded{2.5}
-\end{datadesc}
-
-Examples:
-
-\begin{verbatim}
->>> unicodedata.lookup('LEFT CURLY BRACKET')
-u'{'
->>> unicodedata.name(u'/')
-'SOLIDUS'
->>> unicodedata.decimal(u'9')
-9
->>> unicodedata.decimal(u'a')
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ValueError: not a decimal
->>> unicodedata.category(u'A') # 'L'etter, 'u'ppercase
-'Lu'
->>> unicodedata.bidirectional(u'\u0660') # 'A'rabic, 'N'umber
-'AN'
-\end{verbatim}
diff --git a/Doc/lib/libunittest.tex b/Doc/lib/libunittest.tex
deleted file mode 100644
index fa198c7..0000000
--- a/Doc/lib/libunittest.tex
+++ /dev/null
@@ -1,978 +0,0 @@
-\section{\module{unittest} ---
- Unit testing framework}
-
-\declaremodule{standard}{unittest}
-\modulesynopsis{Unit testing framework for Python.}
-\moduleauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com}
-\sectionauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\sectionauthor{Raymond Hettinger}{python@rcn.com}
-
-\versionadded{2.1}
-
-The Python unit testing framework, sometimes referred to as ``PyUnit,'' is
-a Python language version of JUnit, by Kent Beck and Erich Gamma.
-JUnit is, in turn, a Java version of Kent's Smalltalk testing
-framework. Each is the de facto standard unit testing framework for
-its respective language.
-
-\module{unittest} supports test automation, sharing of setup and shutdown
-code for tests, aggregation of tests into collections, and independence of
-the tests from the reporting framework. The \module{unittest} module
-provides classes that make it easy to support these qualities for a
-set of tests.
-
-To achieve this, \module{unittest} supports some important concepts:
-
-\begin{definitions}
-\term{test fixture}
-A \dfn{test fixture} represents the preparation needed to perform one
-or more tests, and any associate cleanup actions. This may involve,
-for example, creating temporary or proxy databases, directories, or
-starting a server process.
-
-\term{test case}
-A \dfn{test case} is the smallest unit of testing. It checks for a
-specific response to a particular set of inputs. \module{unittest}
-provides a base class, \class{TestCase}, which may be used to create
-new test cases.
-
-\term{test suite}
-A \dfn{test suite} is a collection of test cases, test suites, or
-both. It is used to aggregate tests that should be executed
-together.
-
-\term{test runner}
-A \dfn{test runner} is a component which orchestrates the execution of
-tests and provides the outcome to the user. The runner may use a
-graphical interface, a textual interface, or return a special value to
-indicate the results of executing the tests.
-\end{definitions}
-
-
-The test case and test fixture concepts are supported through the
-\class{TestCase} and \class{FunctionTestCase} classes; the former
-should be used when creating new tests, and the latter can be used when
-integrating existing test code with a \module{unittest}-driven framework.
-When building test fixtures using \class{TestCase}, the \method{setUp()}
-and \method{tearDown()} methods can be overridden to provide
-initialization and cleanup for the fixture. With
-\class{FunctionTestCase}, existing functions can be passed to the
-constructor for these purposes. When the test is run, the
-fixture initialization is run first; if it succeeds, the cleanup
-method is run after the test has been executed, regardless of the
-outcome of the test. Each instance of the \class{TestCase} will only
-be used to run a single test method, so a new fixture is created for
-each test.
-
-Test suites are implemented by the \class{TestSuite} class. This
-class allows individual tests and test suites to be aggregated; when
-the suite is executed, all tests added directly to the suite and in
-``child'' test suites are run.
-
-A test runner is an object that provides a single method,
-\method{run()}, which accepts a \class{TestCase} or \class{TestSuite}
-object as a parameter, and returns a result object. The class
-\class{TestResult} is provided for use as the result object.
-\module{unittest} provides the \class{TextTestRunner} as an example
-test runner which reports test results on the standard error stream by
-default. Alternate runners can be implemented for other environments
-(such as graphical environments) without any need to derive from a
-specific class.
-
-
-\begin{seealso}
- \seemodule{doctest}{Another test-support module with a very
- different flavor.}
- \seetitle[http://www.XProgramming.com/testfram.htm]{Simple Smalltalk
- Testing: With Patterns}{Kent Beck's original paper on
- testing frameworks using the pattern shared by
- \module{unittest}.}
-\end{seealso}
-
-
-\subsection{Basic example \label{unittest-minimal-example}}
-
-The \module{unittest} module provides a rich set of tools for
-constructing and running tests. This section demonstrates that a
-small subset of the tools suffice to meet the needs of most users.
-
-Here is a short script to test three functions from the
-\refmodule{random} module:
-
-\begin{verbatim}
-import random
-import unittest
-
-class TestSequenceFunctions(unittest.TestCase):
-
- def setUp(self):
- self.seq = range(10)
-
- def testshuffle(self):
- # make sure the shuffled sequence does not lose any elements
- random.shuffle(self.seq)
- self.seq.sort()
- self.assertEqual(self.seq, range(10))
-
- def testchoice(self):
- element = random.choice(self.seq)
- self.assert_(element in self.seq)
-
- def testsample(self):
- self.assertRaises(ValueError, random.sample, self.seq, 20)
- for element in random.sample(self.seq, 5):
- self.assert_(element in self.seq)
-
-if __name__ == '__main__':
- unittest.main()
-\end{verbatim}
-
-A testcase is created by subclassing \class{unittest.TestCase}.
-The three individual tests are defined with methods whose names start with
-the letters \samp{test}. This naming convention informs the test runner
-about which methods represent tests.
-
-The crux of each test is a call to \method{assertEqual()} to
-check for an expected result; \method{assert_()} to verify a condition;
-or \method{assertRaises()} to verify that an expected exception gets
-raised. These methods are used instead of the \keyword{assert} statement
-so the test runner can accumulate all test results and produce a report.
-
-When a \method{setUp()} method is defined, the test runner will run that
-method prior to each test. Likewise, if a \method{tearDown()} method is
-defined, the test runner will invoke that method after each test. In the
-example, \method{setUp()} was used to create a fresh sequence for each test.
-
-The final block shows a simple way to run the tests.
-\function{unittest.main()} provides a command line interface to the
-test script. When run from the command line, the above script
-produces an output that looks like this:
-
-\begin{verbatim}
-...
-----------------------------------------------------------------------
-Ran 3 tests in 0.000s
-
-OK
-\end{verbatim}
-
-Instead of \function{unittest.main()}, there are other ways to run the tests
-with a finer level of control, less terse output, and no requirement to be
-run from the command line. For example, the last two lines may be replaced
-with:
-
-\begin{verbatim}
-suite = unittest.TestLoader().loadTestsFromTestCase(TestSequenceFunctions)
-unittest.TextTestRunner(verbosity=2).run(suite)
-\end{verbatim}
-
-Running the revised script from the interpreter or another script
-produces the following output:
-
-\begin{verbatim}
-testchoice (__main__.TestSequenceFunctions) ... ok
-testsample (__main__.TestSequenceFunctions) ... ok
-testshuffle (__main__.TestSequenceFunctions) ... ok
-
-----------------------------------------------------------------------
-Ran 3 tests in 0.110s
-
-OK
-\end{verbatim}
-
-The above examples show the most commonly used \module{unittest} features
-which are sufficient to meet many everyday testing needs. The remainder
-of the documentation explores the full feature set from first principles.
-
-
-\subsection{Organizing test code
- \label{organizing-tests}}
-
-The basic building blocks of unit testing are \dfn{test cases} ---
-single scenarios that must be set up and checked for correctness. In
-\module{unittest}, test cases are represented by instances of
-\module{unittest}'s \class{TestCase} class. To make
-your own test cases you must write subclasses of \class{TestCase}, or
-use \class{FunctionTestCase}.
-
-An instance of a \class{TestCase}-derived class is an object that can
-completely run a single test method, together with optional set-up
-and tidy-up code.
-
-The testing code of a \class{TestCase} instance should be entirely
-self contained, such that it can be run either in isolation or in
-arbitrary combination with any number of other test cases.
-
-The simplest \class{TestCase} subclass will simply override the
-\method{runTest()} method in order to perform specific testing code:
-
-\begin{verbatim}
-import unittest
-
-class DefaultWidgetSizeTestCase(unittest.TestCase):
- def runTest(self):
- widget = Widget('The widget')
- self.assertEqual(widget.size(), (50, 50), 'incorrect default size')
-\end{verbatim}
-
-Note that in order to test something, we use the one of the
-\method{assert*()} or \method{fail*()} methods provided by the
-\class{TestCase} base class. If the test fails, an exception will be
-raised, and \module{unittest} will identify the test case as a
-\dfn{failure}. Any other exceptions will be treated as \dfn{errors}.
-This helps you identify where the problem is: \dfn{failures} are caused by
-incorrect results - a 5 where you expected a 6. \dfn{Errors} are caused by
-incorrect code - e.g., a \exception{TypeError} caused by an incorrect
-function call.
-
-The way to run a test case will be described later. For now, note
-that to construct an instance of such a test case, we call its
-constructor without arguments:
-
-\begin{verbatim}
-testCase = DefaultWidgetSizeTestCase()
-\end{verbatim}
-
-Now, such test cases can be numerous, and their set-up can be
-repetitive. In the above case, constructing a \class{Widget} in each of
-100 Widget test case subclasses would mean unsightly duplication.
-
-Luckily, we can factor out such set-up code by implementing a method
-called \method{setUp()}, which the testing framework will
-automatically call for us when we run the test:
-
-\begin{verbatim}
-import unittest
-
-class SimpleWidgetTestCase(unittest.TestCase):
- def setUp(self):
- self.widget = Widget('The widget')
-
-class DefaultWidgetSizeTestCase(SimpleWidgetTestCase):
- def runTest(self):
- self.failUnless(self.widget.size() == (50,50),
- 'incorrect default size')
-
-class WidgetResizeTestCase(SimpleWidgetTestCase):
- def runTest(self):
- self.widget.resize(100,150)
- self.failUnless(self.widget.size() == (100,150),
- 'wrong size after resize')
-\end{verbatim}
-
-If the \method{setUp()} method raises an exception while the test is
-running, the framework will consider the test to have suffered an
-error, and the \method{runTest()} method will not be executed.
-
-Similarly, we can provide a \method{tearDown()} method that tidies up
-after the \method{runTest()} method has been run:
-
-\begin{verbatim}
-import unittest
-
-class SimpleWidgetTestCase(unittest.TestCase):
- def setUp(self):
- self.widget = Widget('The widget')
-
- def tearDown(self):
- self.widget.dispose()
- self.widget = None
-\end{verbatim}
-
-If \method{setUp()} succeeded, the \method{tearDown()} method will be
-run whether \method{runTest()} succeeded or not.
-
-Such a working environment for the testing code is called a
-\dfn{fixture}.
-
-Often, many small test cases will use the same fixture. In this case,
-we would end up subclassing \class{SimpleWidgetTestCase} into many
-small one-method classes such as
-\class{DefaultWidgetSizeTestCase}. This is time-consuming and
-
-discouraging, so in the same vein as JUnit, \module{unittest} provides
-a simpler mechanism:
-
-\begin{verbatim}
-import unittest
-
-class WidgetTestCase(unittest.TestCase):
- def setUp(self):
- self.widget = Widget('The widget')
-
- def tearDown(self):
- self.widget.dispose()
- self.widget = None
-
- def testDefaultSize(self):
- self.failUnless(self.widget.size() == (50,50),
- 'incorrect default size')
-
- def testResize(self):
- self.widget.resize(100,150)
- self.failUnless(self.widget.size() == (100,150),
- 'wrong size after resize')
-\end{verbatim}
-
-Here we have not provided a \method{runTest()} method, but have
-instead provided two different test methods. Class instances will now
-each run one of the \method{test*()} methods, with \code{self.widget}
-created and destroyed separately for each instance. When creating an
-instance we must specify the test method it is to run. We do this by
-passing the method name in the constructor:
-
-\begin{verbatim}
-defaultSizeTestCase = WidgetTestCase('testDefaultSize')
-resizeTestCase = WidgetTestCase('testResize')
-\end{verbatim}
-
-Test case instances are grouped together according to the features
-they test. \module{unittest} provides a mechanism for this: the
-\dfn{test suite}, represented by \module{unittest}'s \class{TestSuite}
-class:
-
-\begin{verbatim}
-widgetTestSuite = unittest.TestSuite()
-widgetTestSuite.addTest(WidgetTestCase('testDefaultSize'))
-widgetTestSuite.addTest(WidgetTestCase('testResize'))
-\end{verbatim}
-
-For the ease of running tests, as we will see later, it is a good
-idea to provide in each test module a callable object that returns a
-pre-built test suite:
-
-\begin{verbatim}
-def suite():
- suite = unittest.TestSuite()
- suite.addTest(WidgetTestCase('testDefaultSize'))
- suite.addTest(WidgetTestCase('testResize'))
- return suite
-\end{verbatim}
-
-or even:
-
-\begin{verbatim}
-def suite():
- tests = ['testDefaultSize', 'testResize']
-
- return unittest.TestSuite(map(WidgetTestCase, tests))
-\end{verbatim}
-
-Since it is a common pattern to create a \class{TestCase} subclass
-with many similarly named test functions, \module{unittest} provides a
-\class{TestLoader} class that can be used to automate the process of
-creating a test suite and populating it with individual tests.
-For example,
-
-\begin{verbatim}
-suite = unittest.TestLoader().loadTestsFromTestCase(WidgetTestCase)
-\end{verbatim}
-
-will create a test suite that will run
-\code{WidgetTestCase.testDefaultSize()} and \code{WidgetTestCase.testResize}.
-\class{TestLoader} uses the \code{'test'} method name prefix to identify
-test methods automatically.
-
-Note that the order in which the various test cases will be run is
-determined by sorting the test function names with the built-in
-\function{cmp()} function.
-
-Often it is desirable to group suites of test cases together, so as to
-run tests for the whole system at once. This is easy, since
-\class{TestSuite} instances can be added to a \class{TestSuite} just
-as \class{TestCase} instances can be added to a \class{TestSuite}:
-
-\begin{verbatim}
-suite1 = module1.TheTestSuite()
-suite2 = module2.TheTestSuite()
-alltests = unittest.TestSuite([suite1, suite2])
-\end{verbatim}
-
-You can place the definitions of test cases and test suites in the
-same modules as the code they are to test (such as \file{widget.py}),
-but there are several advantages to placing the test code in a
-separate module, such as \file{test_widget.py}:
-
-\begin{itemize}
- \item The test module can be run standalone from the command line.
- \item The test code can more easily be separated from shipped code.
- \item There is less temptation to change test code to fit the code
- it tests without a good reason.
- \item Test code should be modified much less frequently than the
- code it tests.
- \item Tested code can be refactored more easily.
- \item Tests for modules written in C must be in separate modules
- anyway, so why not be consistent?
- \item If the testing strategy changes, there is no need to change
- the source code.
-\end{itemize}
-
-
-\subsection{Re-using old test code
- \label{legacy-unit-tests}}
-
-Some users will find that they have existing test code that they would
-like to run from \module{unittest}, without converting every old test
-function to a \class{TestCase} subclass.
-
-For this reason, \module{unittest} provides a \class{FunctionTestCase}
-class. This subclass of \class{TestCase} can be used to wrap an existing
-test function. Set-up and tear-down functions can also be provided.
-
-Given the following test function:
-
-\begin{verbatim}
-def testSomething():
- something = makeSomething()
- assert something.name is not None
- # ...
-\end{verbatim}
-
-one can create an equivalent test case instance as follows:
-
-\begin{verbatim}
-testcase = unittest.FunctionTestCase(testSomething)
-\end{verbatim}
-
-If there are additional set-up and tear-down methods that should be
-called as part of the test case's operation, they can also be provided
-like so:
-
-\begin{verbatim}
-testcase = unittest.FunctionTestCase(testSomething,
- setUp=makeSomethingDB,
- tearDown=deleteSomethingDB)
-\end{verbatim}
-
-To make migrating existing test suites easier, \module{unittest}
-supports tests raising \exception{AssertionError} to indicate test failure.
-However, it is recommended that you use the explicit
-\method{TestCase.fail*()} and \method{TestCase.assert*()} methods instead,
-as future versions of \module{unittest} may treat \exception{AssertionError}
-differently.
-
-\note{Even though \class{FunctionTestCase} can be used to quickly convert
-an existing test base over to a \module{unittest}-based system, this
-approach is not recommended. Taking the time to set up proper
-\class{TestCase} subclasses will make future test refactorings infinitely
-easier.}
-
-
-
-\subsection{Classes and functions
- \label{unittest-contents}}
-
-\begin{classdesc}{TestCase}{\optional{methodName}}
- Instances of the \class{TestCase} class represent the smallest
- testable units in the \module{unittest} universe. This class is
- intended to be used as a base class, with specific tests being
- implemented by concrete subclasses. This class implements the
- interface needed by the test runner to allow it to drive the
- test, and methods that the test code can use to check for and
- report various kinds of failure.
-
- Each instance of \class{TestCase} will run a single test method:
- the method named \var{methodName}. If you remember, we had an
- earlier example that went something like this:
-
- \begin{verbatim}
- def suite():
- suite = unittest.TestSuite()
- suite.addTest(WidgetTestCase('testDefaultSize'))
- suite.addTest(WidgetTestCase('testResize'))
- return suite
- \end{verbatim}
-
- Here, we create two instances of \class{WidgetTestCase}, each of
- which runs a single test.
-
- \var{methodName} defaults to \code{'runTest'}.
-\end{classdesc}
-
-\begin{classdesc}{FunctionTestCase}{testFunc\optional{,
- setUp\optional{, tearDown\optional{, description}}}}
- This class implements the portion of the \class{TestCase} interface
- which allows the test runner to drive the test, but does not provide
- the methods which test code can use to check and report errors.
- This is used to create test cases using legacy test code, allowing
- it to be integrated into a \refmodule{unittest}-based test
- framework.
-\end{classdesc}
-
-\begin{classdesc}{TestSuite}{\optional{tests}}
- This class represents an aggregation of individual tests cases and
- test suites. The class presents the interface needed by the test
- runner to allow it to be run as any other test case. Running a
- \class{TestSuite} instance is the same as iterating over the suite,
- running each test individually.
-
- If \var{tests} is given, it must be an iterable of individual test cases or
- other test suites that will be used to build the suite initially.
- Additional methods are provided to add test cases and suites to the
- collection later on.
-\end{classdesc}
-
-\begin{classdesc}{TestLoader}{}
- This class is responsible for loading tests according to various
- criteria and returning them wrapped in a \class{TestSuite}.
- It can load all tests within a given module or \class{TestCase}
- subclass.
-\end{classdesc}
-
-\begin{classdesc}{TestResult}{}
- This class is used to compile information about which tests have succeeded
- and which have failed.
-\end{classdesc}
-
-\begin{datadesc}{defaultTestLoader}
- Instance of the \class{TestLoader} class intended to be shared. If no
- customization of the \class{TestLoader} is needed, this instance can
- be used instead of repeatedly creating new instances.
-\end{datadesc}
-
-\begin{classdesc}{TextTestRunner}{\optional{stream\optional{,
- descriptions\optional{, verbosity}}}}
- A basic test runner implementation which prints results on standard
- error. It has a few configurable parameters, but is essentially
- very simple. Graphical applications which run test suites should
- provide alternate implementations.
-\end{classdesc}
-
-\begin{funcdesc}{main}{\optional{module\optional{,
- defaultTest\optional{, argv\optional{,
- testRunner\optional{, testLoader}}}}}}
- A command-line program that runs a set of tests; this is primarily
- for making test modules conveniently executable. The simplest use
- for this function is to include the following line at the end of a
- test script:
-
-\begin{verbatim}
-if __name__ == '__main__':
- unittest.main()
-\end{verbatim}
-
- The \var{testRunner} argument can either be a test runner class or
- an already created instance of it.
-\end{funcdesc}
-
-In some cases, the existing tests may have been written using the
-\refmodule{doctest} module. If so, that module provides a
-\class{DocTestSuite} class that can automatically build
-\class{unittest.TestSuite} instances from the existing
-\module{doctest}-based tests.
-\versionadded{2.3}
-
-
-\subsection{TestCase Objects
- \label{testcase-objects}}
-
-Each \class{TestCase} instance represents a single test, but each
-concrete subclass may be used to define multiple tests --- the
-concrete class represents a single test fixture. The fixture is
-created and cleaned up for each test case.
-
-\class{TestCase} instances provide three groups of methods: one group
-used to run the test, another used by the test implementation to
-check conditions and report failures, and some inquiry methods
-allowing information about the test itself to be gathered.
-
-Methods in the first group (running the test) are:
-
-\begin{methoddesc}[TestCase]{setUp}{}
- Method called to prepare the test fixture. This is called
- immediately before calling the test method; any exception raised by
- this method will be considered an error rather than a test failure.
- The default implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{tearDown}{}
- Method called immediately after the test method has been called and
- the result recorded. This is called even if the test method raised
- an exception, so the implementation in subclasses may need to be
- particularly careful about checking internal state. Any exception
- raised by this method will be considered an error rather than a test
- failure. This method will only be called if the \method{setUp()}
- succeeds, regardless of the outcome of the test method.
- The default implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{run}{\optional{result}}
- Run the test, collecting the result into the test result object
- passed as \var{result}. If \var{result} is omitted or \constant{None},
- a temporary result object is created (by calling the
- \method{defaultTestCase()} method) and used; this result object is not
- returned to \method{run()}'s caller.
-
- The same effect may be had by simply calling the \class{TestCase}
- instance.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{debug}{}
- Run the test without collecting the result. This allows exceptions
- raised by the test to be propagated to the caller, and can be used
- to support running tests under a debugger.
-\end{methoddesc}
-
-
-The test code can use any of the following methods to check for and
-report failures.
-
-\begin{methoddesc}[TestCase]{assert_}{expr\optional{, msg}}
-\methodline[TestCase]{failUnless}{expr\optional{, msg}}
- Signal a test failure if \var{expr} is false; the explanation for
- the error will be \var{msg} if given, otherwise it will be
- \constant{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{assertEqual}{first, second\optional{, msg}}
-\methodline[TestCase]{failUnlessEqual}{first, second\optional{, msg}}
- Test that \var{first} and \var{second} are equal. If the values do
- not compare equal, the test will fail with the explanation given by
- \var{msg}, or \constant{None}. Note that using \method{failUnlessEqual()}
- improves upon doing the comparison as the first parameter to
- \method{failUnless()}: the default value for \var{msg} can be
- computed to include representations of both \var{first} and
- \var{second}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{assertNotEqual}{first, second\optional{, msg}}
-\methodline[TestCase]{failIfEqual}{first, second\optional{, msg}}
- Test that \var{first} and \var{second} are not equal. If the values
- do compare equal, the test will fail with the explanation given by
- \var{msg}, or \constant{None}. Note that using \method{failIfEqual()}
- improves upon doing the comparison as the first parameter to
- \method{failUnless()} is that the default value for \var{msg} can be
- computed to include representations of both \var{first} and
- \var{second}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{assertAlmostEqual}{first, second\optional{,
- places\optional{, msg}}}
-\methodline[TestCase]{failUnlessAlmostEqual}{first, second\optional{,
- places\optional{, msg}}}
- Test that \var{first} and \var{second} are approximately equal
- by computing the difference, rounding to the given number of \var{places},
- and comparing to zero. Note that comparing a given number of decimal places
- is not the same as comparing a given number of significant digits.
- If the values do not compare equal, the test will fail with the explanation
- given by \var{msg}, or \constant{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{assertNotAlmostEqual}{first, second\optional{,
- places\optional{, msg}}}
-\methodline[TestCase]{failIfAlmostEqual}{first, second\optional{,
- places\optional{, msg}}}
- Test that \var{first} and \var{second} are not approximately equal
- by computing the difference, rounding to the given number of \var{places},
- and comparing to zero. Note that comparing a given number of decimal places
- is not the same as comparing a given number of significant digits.
- If the values do not compare equal, the test will fail with the explanation
- given by \var{msg}, or \constant{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{assertRaises}{exception, callable, \moreargs}
-\methodline[TestCase]{failUnlessRaises}{exception, callable, \moreargs}
- Test that an exception is raised when \var{callable} is called with
- any positional or keyword arguments that are also passed to
- \method{assertRaises()}. The test passes if \var{exception} is
- raised, is an error if another exception is raised, or fails if no
- exception is raised. To catch any of a group of exceptions, a tuple
- containing the exception classes may be passed as \var{exception}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{failIf}{expr\optional{, msg}}
- The inverse of the \method{failUnless()} method is the
- \method{failIf()} method. This signals a test failure if \var{expr}
- is true, with \var{msg} or \constant{None} for the error message.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{fail}{\optional{msg}}
- Signals a test failure unconditionally, with \var{msg} or
- \constant{None} for the error message.
-\end{methoddesc}
-
-\begin{memberdesc}[TestCase]{failureException}
- This class attribute gives the exception raised by the
- \method{test()} method. If a test framework needs to use a
- specialized exception, possibly to carry additional information, it
- must subclass this exception in order to ``play fair'' with the
- framework. The initial value of this attribute is
- \exception{AssertionError}.
-\end{memberdesc}
-
-
-Testing frameworks can use the following methods to collect
-information on the test:
-
-\begin{methoddesc}[TestCase]{countTestCases}{}
- Return the number of tests represented by this test object. For
- \class{TestCase} instances, this will always be \code{1}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{defaultTestResult}{}
- Return an instance of the test result class that should be used
- for this test case class (if no other result instance is provided
- to the \method{run()} method).
-
- For \class{TestCase} instances, this will always be an instance of
- \class{TestResult}; subclasses of \class{TestCase} should
- override this as necessary.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{id}{}
- Return a string identifying the specific test case. This is usually
- the full name of the test method, including the module and class
- name.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{shortDescription}{}
- Returns a one-line description of the test, or \constant{None} if no
- description has been provided. The default implementation of this
- method returns the first line of the test method's docstring, if
- available, or \constant{None}.
-\end{methoddesc}
-
-
-\subsection{TestSuite Objects
- \label{testsuite-objects}}
-
-\class{TestSuite} objects behave much like \class{TestCase} objects,
-except they do not actually implement a test. Instead, they are used
-to aggregate tests into groups of tests that should be run together.
-Some additional methods are available to add tests to \class{TestSuite}
-instances:
-
-\begin{methoddesc}[TestSuite]{addTest}{test}
- Add a \class{TestCase} or \class{TestSuite} to the suite.
-\end{methoddesc}
-
-\begin{methoddesc}[TestSuite]{addTests}{tests}
- Add all the tests from an iterable of \class{TestCase} and
- \class{TestSuite} instances to this test suite.
-
- This is equivalent to iterating over \var{tests}, calling
- \method{addTest()} for each element.
-\end{methoddesc}
-
-\class{TestSuite} shares the following methods with \class{TestCase}:
-
-\begin{methoddesc}[TestSuite]{run}{result}
- Run the tests associated with this suite, collecting the result into
- the test result object passed as \var{result}. Note that unlike
- \method{TestCase.run()}, \method{TestSuite.run()} requires the
- result object to be passed in.
-\end{methoddesc}
-
-\begin{methoddesc}[TestSuite]{debug}{}
- Run the tests associated with this suite without collecting the result.
- This allows exceptions raised by the test to be propagated to the caller
- and can be used to support running tests under a debugger.
-\end{methoddesc}
-
-\begin{methoddesc}[TestSuite]{countTestCases}{}
- Return the number of tests represented by this test object, including
- all individual tests and sub-suites.
-\end{methoddesc}
-
-In the typical usage of a \class{TestSuite} object, the \method{run()}
-method is invoked by a \class{TestRunner} rather than by the end-user
-test harness.
-
-
-\subsection{TestResult Objects
- \label{testresult-objects}}
-
-A \class{TestResult} object stores the results of a set of tests. The
-\class{TestCase} and \class{TestSuite} classes ensure that results are
-properly recorded; test authors do not need to worry about recording the
-outcome of tests.
-
-Testing frameworks built on top of \refmodule{unittest} may want
-access to the \class{TestResult} object generated by running a set of
-tests for reporting purposes; a \class{TestResult} instance is
-returned by the \method{TestRunner.run()} method for this purpose.
-
-\class{TestResult} instances have the following attributes that will
-be of interest when inspecting the results of running a set of tests:
-
-\begin{memberdesc}[TestResult]{errors}
- A list containing 2-tuples of \class{TestCase} instances and
- strings holding formatted tracebacks. Each tuple represents a test which
- raised an unexpected exception.
- \versionchanged[Contains formatted tracebacks instead of
- \function{sys.exc_info()} results]{2.2}
-\end{memberdesc}
-
-\begin{memberdesc}[TestResult]{failures}
- A list containing 2-tuples of \class{TestCase} instances and strings
- holding formatted tracebacks. Each tuple represents a test where a failure
- was explicitly signalled using the \method{TestCase.fail*()} or
- \method{TestCase.assert*()} methods.
- \versionchanged[Contains formatted tracebacks instead of
- \function{sys.exc_info()} results]{2.2}
-\end{memberdesc}
-
-\begin{memberdesc}[TestResult]{testsRun}
- The total number of tests run so far.
-\end{memberdesc}
-
-\begin{methoddesc}[TestResult]{wasSuccessful}{}
- Returns \constant{True} if all tests run so far have passed,
- otherwise returns \constant{False}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestResult]{stop}{}
- This method can be called to signal that the set of tests being run
- should be aborted by setting the \class{TestResult}'s \code{shouldStop}
- attribute to \constant{True}. \class{TestRunner} objects should respect
- this flag and return without running any additional tests.
-
- For example, this feature is used by the \class{TextTestRunner} class
- to stop the test framework when the user signals an interrupt from
- the keyboard. Interactive tools which provide \class{TestRunner}
- implementations can use this in a similar manner.
-\end{methoddesc}
-
-
-The following methods of the \class{TestResult} class are used to
-maintain the internal data structures, and may be extended in
-subclasses to support additional reporting requirements. This is
-particularly useful in building tools which support interactive
-reporting while tests are being run.
-
-\begin{methoddesc}[TestResult]{startTest}{test}
- Called when the test case \var{test} is about to be run.
-
- The default implementation simply increments the instance's
- \code{testsRun} counter.
-\end{methoddesc}
-
-\begin{methoddesc}[TestResult]{stopTest}{test}
- Called after the test case \var{test} has been executed, regardless
- of the outcome.
-
- The default implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}[TestResult]{addError}{test, err}
- Called when the test case \var{test} raises an unexpected exception
- \var{err} is a tuple of the form returned by \function{sys.exc_info()}:
- \code{(\var{type}, \var{value}, \var{traceback})}.
-
- The default implementation appends \code{(\var{test}, \var{err})} to
- the instance's \code{errors} attribute.
-\end{methoddesc}
-
-\begin{methoddesc}[TestResult]{addFailure}{test, err}
- Called when the test case \var{test} signals a failure.
- \var{err} is a tuple of the form returned by
- \function{sys.exc_info()}: \code{(\var{type}, \var{value},
- \var{traceback})}.
-
- The default implementation appends \code{(\var{test}, \var{err})} to
- the instance's \code{failures} attribute.
-\end{methoddesc}
-
-\begin{methoddesc}[TestResult]{addSuccess}{test}
- Called when the test case \var{test} succeeds.
-
- The default implementation does nothing.
-\end{methoddesc}
-
-
-
-\subsection{TestLoader Objects
- \label{testloader-objects}}
-
-The \class{TestLoader} class is used to create test suites from
-classes and modules. Normally, there is no need to create an instance
-of this class; the \refmodule{unittest} module provides an instance
-that can be shared as \code{unittest.defaultTestLoader}.
-Using a subclass or instance, however, allows customization of some
-configurable properties.
-
-\class{TestLoader} objects have the following methods:
-
-\begin{methoddesc}[TestLoader]{loadTestsFromTestCase}{testCaseClass}
- Return a suite of all tests cases contained in the
- \class{TestCase}-derived \class{testCaseClass}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestLoader]{loadTestsFromModule}{module}
- Return a suite of all tests cases contained in the given module.
- This method searches \var{module} for classes derived from
- \class{TestCase} and creates an instance of the class for each test
- method defined for the class.
-
- \warning{While using a hierarchy of
- \class{TestCase}-derived classes can be convenient in sharing
- fixtures and helper functions, defining test methods on base classes
- that are not intended to be instantiated directly does not play well
- with this method. Doing so, however, can be useful when the
- fixtures are different and defined in subclasses.}
-\end{methoddesc}
-
-\begin{methoddesc}[TestLoader]{loadTestsFromName}{name\optional{, module}}
- Return a suite of all tests cases given a string specifier.
-
- The specifier \var{name} is a ``dotted name'' that may resolve
- either to a module, a test case class, a test method within a test
- case class, a \class{TestSuite} instance, or a callable object which
- returns a \class{TestCase} or \class{TestSuite} instance. These checks
- are applied in the order listed here; that is, a method on a possible
- test case class will be picked up as ``a test method within a test
- case class'', rather than ``a callable object''.
-
- For example, if you have a module \module{SampleTests} containing a
- \class{TestCase}-derived class \class{SampleTestCase} with three test
- methods (\method{test_one()}, \method{test_two()}, and
- \method{test_three()}), the specifier \code{'SampleTests.SampleTestCase'}
- would cause this method to return a suite which will run all three test
- methods. Using the specifier \code{'SampleTests.SampleTestCase.test_two'}
- would cause it to return a test suite which will run only the
- \method{test_two()} test method. The specifier can refer to modules
- and packages which have not been imported; they will be imported as
- a side-effect.
-
- The method optionally resolves \var{name} relative to the given
- \var{module}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestLoader]{loadTestsFromNames}{names\optional{, module}}
- Similar to \method{loadTestsFromName()}, but takes a sequence of
- names rather than a single name. The return value is a test suite
- which supports all the tests defined for each name.
-\end{methoddesc}
-
-\begin{methoddesc}[TestLoader]{getTestCaseNames}{testCaseClass}
- Return a sorted sequence of method names found within
- \var{testCaseClass}; this should be a subclass of \class{TestCase}.
-\end{methoddesc}
-
-
-The following attributes of a \class{TestLoader} can be configured
-either by subclassing or assignment on an instance:
-
-\begin{memberdesc}[TestLoader]{testMethodPrefix}
- String giving the prefix of method names which will be interpreted
- as test methods. The default value is \code{'test'}.
-
- This affects \method{getTestCaseNames()} and all the
- \method{loadTestsFrom*()} methods.
-\end{memberdesc}
-
-\begin{memberdesc}[TestLoader]{sortTestMethodsUsing}
- Function to be used to compare method names when sorting them in
- \method{getTestCaseNames()} and all the \method{loadTestsFrom*()} methods.
- The default value is the built-in \function{cmp()} function; the attribute
- can also be set to \constant{None} to disable the sort.
-\end{memberdesc}
-
-\begin{memberdesc}[TestLoader]{suiteClass}
- Callable object that constructs a test suite from a list of tests.
- No methods on the resulting object are needed. The default value is
- the \class{TestSuite} class.
-
- This affects all the \method{loadTestsFrom*()} methods.
-\end{memberdesc}
diff --git a/Doc/lib/libunix.tex b/Doc/lib/libunix.tex
deleted file mode 100644
index 686df01..0000000
--- a/Doc/lib/libunix.tex
+++ /dev/null
@@ -1,8 +0,0 @@
-\chapter{Unix Specific Services}
-\label{unix}
-
-The modules described in this chapter provide interfaces to features
-that are unique to the \UNIX{} operating system, or in some cases to
-some or many variants of it. Here's an overview:
-
-\localmoduletable
diff --git a/Doc/lib/liburllib.tex b/Doc/lib/liburllib.tex
deleted file mode 100644
index 77dfb8f..0000000
--- a/Doc/lib/liburllib.tex
+++ /dev/null
@@ -1,494 +0,0 @@
-\section{\module{urllib} ---
- Open arbitrary resources by URL}
-
-\declaremodule{standard}{urllib}
-\modulesynopsis{Open an arbitrary network resource by URL (requires sockets).}
-
-\index{WWW}
-\index{World Wide Web}
-\index{URL}
-
-
-This module provides a high-level interface for fetching data across
-the World Wide Web. In particular, the \function{urlopen()} function
-is similar to the built-in function \function{open()}, but accepts
-Universal Resource Locators (URLs) instead of filenames. Some
-restrictions apply --- it can only open URLs for reading, and no seek
-operations are available.
-
-It defines the following public functions:
-
-\begin{funcdesc}{urlopen}{url\optional{, data\optional{, proxies}}}
-Open a network object denoted by a URL for reading. If the URL does
-not have a scheme identifier, or if it has \file{file:} as its scheme
-identifier, this opens a local file (without universal newlines);
-otherwise it opens a socket to a server somewhere on the network. If
-the connection cannot be made
-the \exception{IOError} exception is raised. If all went well, a
-file-like object is returned. This supports the following methods:
-\method{read()}, \method{readline()}, \method{readlines()}, \method{fileno()},
-\method{close()}, \method{info()} and \method{geturl()}. It also has
-proper support for the iterator protocol.
-One caveat: the \method{read()} method, if the size argument is
-omitted or negative, may not read until the end of the data stream;
-there is no good way to determine that the entire stream from a socket
-has been read in the general case.
-
-Except for the \method{info()} and \method{geturl()} methods,
-these methods have the same interface as for
-file objects --- see section \ref{bltin-file-objects} in this
-manual. (It is not a built-in file object, however, so it can't be
-used at those few places where a true built-in file object is
-required.)
-
-The \method{info()} method returns an instance of the class
-\class{mimetools.Message} containing meta-information associated
-with the URL. When the method is HTTP, these headers are those
-returned by the server at the head of the retrieved HTML page
-(including Content-Length and Content-Type). When the method is FTP,
-a Content-Length header will be present if (as is now usual) the
-server passed back a file length in response to the FTP retrieval
-request. A Content-Type header will be present if the MIME type can
-be guessed. When the method is local-file, returned headers will include
-a Date representing the file's last-modified time, a Content-Length
-giving file size, and a Content-Type containing a guess at the file's
-type. See also the description of the
-\refmodule{mimetools}\refstmodindex{mimetools} module.
-
-The \method{geturl()} method returns the real URL of the page. In
-some cases, the HTTP server redirects a client to another URL. The
-\function{urlopen()} function handles this transparently, but in some
-cases the caller needs to know which URL the client was redirected
-to. The \method{geturl()} method can be used to get at this
-redirected URL.
-
-If the \var{url} uses the \file{http:} scheme identifier, the optional
-\var{data} argument may be given to specify a \code{POST} request
-(normally the request type is \code{GET}). The \var{data} argument
-must be in standard \mimetype{application/x-www-form-urlencoded} format;
-see the \function{urlencode()} function below.
-
-The \function{urlopen()} function works transparently with proxies
-which do not require authentication. In a \UNIX{} or Windows
-environment, set the \envvar{http_proxy}, or \envvar{ftp_proxy}
-environment variables to a URL that identifies
-the proxy server before starting the Python interpreter. For example
-(the \character{\%} is the command prompt):
-
-\begin{verbatim}
-% http_proxy="http://www.someproxy.com:3128"
-% export http_proxy
-% python
-...
-\end{verbatim}
-
-In a Windows environment, if no proxy environment variables are set,
-proxy settings are obtained from the registry's Internet Settings
-section.
-
-In a Macintosh environment, \function{urlopen()} will retrieve proxy
-information from Internet\index{Internet Config} Config.
-
-Alternatively, the optional \var{proxies} argument may be used to
-explicitly specify proxies. It must be a dictionary mapping scheme
-names to proxy URLs, where an empty dictionary causes no proxies to be
-used, and \code{None} (the default value) causes environmental proxy
-settings to be used as discussed above. For example:
-
-\begin{verbatim}
-# Use http://www.someproxy.com:3128 for http proxying
-proxies = {'http': 'http://www.someproxy.com:3128'}
-filehandle = urllib.urlopen(some_url, proxies=proxies)
-# Don't use any proxies
-filehandle = urllib.urlopen(some_url, proxies={})
-# Use proxies from environment - both versions are equivalent
-filehandle = urllib.urlopen(some_url, proxies=None)
-filehandle = urllib.urlopen(some_url)
-\end{verbatim}
-
-The \function{urlopen()} function does not support explicit proxy
-specification. If you need to override environmental proxy settings,
-use \class{URLopener}, or a subclass such as \class{FancyURLopener}.
-
-Proxies which require authentication for use are not currently
-supported; this is considered an implementation limitation.
-
-\versionchanged[Added the \var{proxies} support]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{urlretrieve}{url\optional{, filename\optional{,
- reporthook\optional{, data}}}}
-Copy a network object denoted by a URL to a local file, if necessary.
-If the URL points to a local file, or a valid cached copy of the
-object exists, the object is not copied. Return a tuple
-\code{(\var{filename}, \var{headers})} where \var{filename} is the
-local file name under which the object can be found, and \var{headers}
-is whatever the \method{info()} method of the object returned by
-\function{urlopen()} returned (for a remote object, possibly cached).
-Exceptions are the same as for \function{urlopen()}.
-
-The second argument, if present, specifies the file location to copy
-to (if absent, the location will be a tempfile with a generated name).
-The third argument, if present, is a hook function that will be called
-once on establishment of the network connection and once after each
-block read thereafter. The hook will be passed three arguments; a
-count of blocks transferred so far, a block size in bytes, and the
-total size of the file. The third argument may be \code{-1} on older
-FTP servers which do not return a file size in response to a retrieval
-request.
-
-If the \var{url} uses the \file{http:} scheme identifier, the optional
-\var{data} argument may be given to specify a \code{POST} request
-(normally the request type is \code{GET}). The \var{data} argument
-must in standard \mimetype{application/x-www-form-urlencoded} format;
-see the \function{urlencode()} function below.
-
-\versionchanged[
-\function{urlretrieve()} will raise \exception{ContentTooShortError}
-when it detects that the amount of data available
-was less than the expected amount (which is the size reported by a
-\var{Content-Length} header). This can occur, for example, when the
-download is interrupted.
-
-The \var{Content-Length} is treated as a lower bound: if there's more data
-to read, urlretrieve reads more data, but if less data is available,
-it raises the exception.
-
-You can still retrieve the downloaded data in this case, it is stored
-in the \member{content} attribute of the exception instance.
-
-If no \var{Content-Length} header was supplied, urlretrieve can
-not check the size of the data it has downloaded, and just returns it.
-In this case you just have to assume that the download was successful]{2.5}
-
-\end{funcdesc}
-
-\begin{datadesc}{_urlopener}
-The public functions \function{urlopen()} and
-\function{urlretrieve()} create an instance of the
-\class{FancyURLopener} class and use it to perform their requested
-actions. To override this functionality, programmers can create a
-subclass of \class{URLopener} or \class{FancyURLopener}, then assign
-an instance of that class to the
-\code{urllib._urlopener} variable before calling the desired function.
-For example, applications may want to specify a different
-\mailheader{User-Agent} header than \class{URLopener} defines. This
-can be accomplished with the following code:
-
-\begin{verbatim}
-import urllib
-
-class AppURLopener(urllib.FancyURLopener):
- version = "App/1.7"
-
-urllib._urlopener = AppURLopener()
-\end{verbatim}
-\end{datadesc}
-
-\begin{funcdesc}{urlcleanup}{}
-Clear the cache that may have been built up by previous calls to
-\function{urlretrieve()}.
-\end{funcdesc}
-
-\begin{funcdesc}{quote}{string\optional{, safe}}
-Replace special characters in \var{string} using the \samp{\%xx} escape.
-Letters, digits, and the characters \character{_.-} are never quoted.
-The optional \var{safe} parameter specifies additional characters
-that should not be quoted --- its default value is \code{'/'}.
-
-Example: \code{quote('/\~{}connolly/')} yields \code{'/\%7econnolly/'}.
-\end{funcdesc}
-
-\begin{funcdesc}{quote_plus}{string\optional{, safe}}
-Like \function{quote()}, but also replaces spaces by plus signs, as
-required for quoting HTML form values. Plus signs in the original
-string are escaped unless they are included in \var{safe}. It also
-does not have \var{safe} default to \code{'/'}.
-\end{funcdesc}
-
-\begin{funcdesc}{unquote}{string}
-Replace \samp{\%xx} escapes by their single-character equivalent.
-
-Example: \code{unquote('/\%7Econnolly/')} yields \code{'/\~{}connolly/'}.
-\end{funcdesc}
-
-\begin{funcdesc}{unquote_plus}{string}
-Like \function{unquote()}, but also replaces plus signs by spaces, as
-required for unquoting HTML form values.
-\end{funcdesc}
-
-\begin{funcdesc}{urlencode}{query\optional{, doseq}}
-Convert a mapping object or a sequence of two-element tuples to a
-``url-encoded'' string, suitable to pass to
-\function{urlopen()} above as the optional \var{data} argument. This
-is useful to pass a dictionary of form fields to a \code{POST}
-request. The resulting string is a series of
-\code{\var{key}=\var{value}} pairs separated by \character{\&}
-characters, where both \var{key} and \var{value} are quoted using
-\function{quote_plus()} above. If the optional parameter \var{doseq} is
-present and evaluates to true, individual \code{\var{key}=\var{value}} pairs
-are generated for each element of the sequence.
-When a sequence of two-element tuples is used as the \var{query} argument,
-the first element of each tuple is a key and the second is a value. The
-order of parameters in the encoded string will match the order of parameter
-tuples in the sequence.
-The \refmodule{cgi} module provides the functions
-\function{parse_qs()} and \function{parse_qsl()} which are used to
-parse query strings into Python data structures.
-\end{funcdesc}
-
-\begin{funcdesc}{pathname2url}{path}
-Convert the pathname \var{path} from the local syntax for a path to
-the form used in the path component of a URL. This does not produce a
-complete URL. The return value will already be quoted using the
-\function{quote()} function.
-\end{funcdesc}
-
-\begin{funcdesc}{url2pathname}{path}
-Convert the path component \var{path} from an encoded URL to the local
-syntax for a path. This does not accept a complete URL. This
-function uses \function{unquote()} to decode \var{path}.
-\end{funcdesc}
-
-\begin{classdesc}{URLopener}{\optional{proxies\optional{, **x509}}}
-Base class for opening and reading URLs. Unless you need to support
-opening objects using schemes other than \file{http:}, \file{ftp:},
-or \file{file:}, you probably want to use
-\class{FancyURLopener}.
-
-By default, the \class{URLopener} class sends a
-\mailheader{User-Agent} header of \samp{urllib/\var{VVV}}, where
-\var{VVV} is the \module{urllib} version number. Applications can
-define their own \mailheader{User-Agent} header by subclassing
-\class{URLopener} or \class{FancyURLopener} and setting the class
-attribute \member{version} to an appropriate string value in the
-subclass definition.
-
-The optional \var{proxies} parameter should be a dictionary mapping
-scheme names to proxy URLs, where an empty dictionary turns proxies
-off completely. Its default value is \code{None}, in which case
-environmental proxy settings will be used if present, as discussed in
-the definition of \function{urlopen()}, above.
-
-Additional keyword parameters, collected in \var{x509}, may be used for
-authentication of the client when using the \file{https:} scheme. The keywords
-\var{key_file} and \var{cert_file} are supported to provide an
-SSL key and certificate; both are needed to support client authentication.
-
-\class{URLopener} objects will raise an \exception{IOError} exception
-if the server returns an error code.
-\end{classdesc}
-
-\begin{classdesc}{FancyURLopener}{...}
-\class{FancyURLopener} subclasses \class{URLopener} providing default
-handling for the following HTTP response codes: 301, 302, 303, 307 and
-401. For the 30x response codes listed above, the
-\mailheader{Location} header is used to fetch the actual URL. For 401
-response codes (authentication required), basic HTTP authentication is
-performed. For the 30x response codes, recursion is bounded by the
-value of the \var{maxtries} attribute, which defaults to 10.
-
-For all other response codes, the method \method{http_error_default()}
-is called which you can override in subclasses to handle the error
-appropriately.
-
-\note{According to the letter of \rfc{2616}, 301 and 302 responses to
- POST requests must not be automatically redirected without
- confirmation by the user. In reality, browsers do allow automatic
- redirection of these responses, changing the POST to a GET, and
- \module{urllib} reproduces this behaviour.}
-
-The parameters to the constructor are the same as those for
-\class{URLopener}.
-
-\note{When performing basic authentication, a
-\class{FancyURLopener} instance calls its
-\method{prompt_user_passwd()} method. The default implementation asks
-the users for the required information on the controlling terminal. A
-subclass may override this method to support more appropriate behavior
-if needed.}
-\end{classdesc}
-
-\begin{excclassdesc}{ContentTooShortError}{msg\optional{, content}}
-This exception is raised when the \function{urlretrieve()} function
-detects that the amount of the downloaded data is less than the
-expected amount (given by the \var{Content-Length} header). The
-\member{content} attribute stores the downloaded (and supposedly
-truncated) data.
-\versionadded{2.5}
-\end{excclassdesc}
-
-Restrictions:
-
-\begin{itemize}
-
-\item
-Currently, only the following protocols are supported: HTTP, (versions
-0.9 and 1.0), FTP, and local files.
-\indexii{HTTP}{protocol}
-\indexii{FTP}{protocol}
-
-\item
-The caching feature of \function{urlretrieve()} has been disabled
-until I find the time to hack proper processing of Expiration time
-headers.
-
-\item
-There should be a function to query whether a particular URL is in
-the cache.
-
-\item
-For backward compatibility, if a URL appears to point to a local file
-but the file can't be opened, the URL is re-interpreted using the FTP
-protocol. This can sometimes cause confusing error messages.
-
-\item
-The \function{urlopen()} and \function{urlretrieve()} functions can
-cause arbitrarily long delays while waiting for a network connection
-to be set up. This means that it is difficult to build an interactive
-Web client using these functions without using threads.
-
-\item
-The data returned by \function{urlopen()} or \function{urlretrieve()}
-is the raw data returned by the server. This may be binary data
-(such as an image), plain text or (for example) HTML\index{HTML}. The
-HTTP\indexii{HTTP}{protocol} protocol provides type information in the
-reply header, which can be inspected by looking at the
-\mailheader{Content-Type} header. If the
-returned data is HTML, you can use the module
-\refmodule{htmllib}\refstmodindex{htmllib} to parse it.
-
-\item
-The code handling the FTP\index{FTP} protocol cannot differentiate
-between a file and a directory. This can lead to unexpected behavior
-when attempting to read a URL that points to a file that is not
-accessible. If the URL ends in a \code{/}, it is assumed to refer to
-a directory and will be handled accordingly. But if an attempt to
-read a file leads to a 550 error (meaning the URL cannot be found or
-is not accessible, often for permission reasons), then the path is
-treated as a directory in order to handle the case when a directory is
-specified by a URL but the trailing \code{/} has been left off. This can
-cause misleading results when you try to fetch a file whose read
-permissions make it inaccessible; the FTP code will try to read it,
-fail with a 550 error, and then perform a directory listing for the
-unreadable file. If fine-grained control is needed, consider using the
-\module{ftplib} module, subclassing \class{FancyURLOpener}, or changing
-\var{_urlopener} to meet your needs.
-
-\item
-This module does not support the use of proxies which require
-authentication. This may be implemented in the future.
-
-\item
-Although the \module{urllib} module contains (undocumented) routines
-to parse and unparse URL strings, the recommended interface for URL
-manipulation is in module \refmodule{urlparse}\refstmodindex{urlparse}.
-
-\end{itemize}
-
-
-\subsection{URLopener Objects \label{urlopener-objs}}
-\sectionauthor{Skip Montanaro}{skip@mojam.com}
-
-\class{URLopener} and \class{FancyURLopener} objects have the
-following attributes.
-
-\begin{methoddesc}[URLopener]{open}{fullurl\optional{, data}}
-Open \var{fullurl} using the appropriate protocol. This method sets
-up cache and proxy information, then calls the appropriate open method with
-its input arguments. If the scheme is not recognized,
-\method{open_unknown()} is called. The \var{data} argument
-has the same meaning as the \var{data} argument of \function{urlopen()}.
-\end{methoddesc}
-
-\begin{methoddesc}[URLopener]{open_unknown}{fullurl\optional{, data}}
-Overridable interface to open unknown URL types.
-\end{methoddesc}
-
-\begin{methoddesc}[URLopener]{retrieve}{url\optional{,
- filename\optional{,
- reporthook\optional{, data}}}}
-Retrieves the contents of \var{url} and places it in \var{filename}. The
-return value is a tuple consisting of a local filename and either a
-\class{mimetools.Message} object containing the response headers (for remote
-URLs) or \code{None} (for local URLs). The caller must then open and read the
-contents of \var{filename}. If \var{filename} is not given and the URL
-refers to a local file, the input filename is returned. If the URL is
-non-local and \var{filename} is not given, the filename is the output of
-\function{tempfile.mktemp()} with a suffix that matches the suffix of the last
-path component of the input URL. If \var{reporthook} is given, it must be
-a function accepting three numeric parameters. It will be called after each
-chunk of data is read from the network. \var{reporthook} is ignored for
-local URLs.
-
-If the \var{url} uses the \file{http:} scheme identifier, the optional
-\var{data} argument may be given to specify a \code{POST} request
-(normally the request type is \code{GET}). The \var{data} argument
-must in standard \mimetype{application/x-www-form-urlencoded} format;
-see the \function{urlencode()} function below.
-\end{methoddesc}
-
-\begin{memberdesc}[URLopener]{version}
-Variable that specifies the user agent of the opener object. To get
-\refmodule{urllib} to tell servers that it is a particular user agent,
-set this in a subclass as a class variable or in the constructor
-before calling the base constructor.
-\end{memberdesc}
-
-The \class{FancyURLopener} class offers one additional method that
-should be overloaded to provide the appropriate behavior:
-
-\begin{methoddesc}[FancyURLopener]{prompt_user_passwd}{host, realm}
-Return information needed to authenticate the user at the given host
-in the specified security realm. The return value should be a tuple,
-\code{(\var{user}, \var{password})}, which can be used for basic
-authentication.
-
-The implementation prompts for this information on the terminal; an
-application should override this method to use an appropriate
-interaction model in the local environment.
-\end{methoddesc}
-
-
-\subsection{Examples}
-\nodename{Urllib Examples}
-
-Here is an example session that uses the \samp{GET} method to retrieve
-a URL containing parameters:
-
-\begin{verbatim}
->>> import urllib
->>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
->>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query?%s" % params)
->>> print f.read()
-\end{verbatim}
-
-The following example uses the \samp{POST} method instead:
-
-\begin{verbatim}
->>> import urllib
->>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
->>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query", params)
->>> print f.read()
-\end{verbatim}
-
-The following example uses an explicitly specified HTTP proxy,
-overriding environment settings:
-
-\begin{verbatim}
->>> import urllib
->>> proxies = {'http': 'http://proxy.example.com:8080/'}
->>> opener = urllib.FancyURLopener(proxies)
->>> f = opener.open("http://www.python.org")
->>> f.read()
-\end{verbatim}
-
-The following example uses no proxies at all, overriding environment
-settings:
-
-\begin{verbatim}
->>> import urllib
->>> opener = urllib.FancyURLopener({})
->>> f = opener.open("http://www.python.org/")
->>> f.read()
-\end{verbatim}
diff --git a/Doc/lib/liburllib2.tex b/Doc/lib/liburllib2.tex
deleted file mode 100644
index 9d2c382..0000000
--- a/Doc/lib/liburllib2.tex
+++ /dev/null
@@ -1,872 +0,0 @@
-\section{\module{urllib2} ---
- extensible library for opening URLs}
-
-\declaremodule{standard}{urllib2}
-\moduleauthor{Jeremy Hylton}{jhylton@users.sourceforge.net}
-\sectionauthor{Moshe Zadka}{moshez@users.sourceforge.net}
-
-\modulesynopsis{An extensible library for opening URLs using a variety of
- protocols}
-
-The \module{urllib2} module defines functions and classes which help
-in opening URLs (mostly HTTP) in a complex world --- basic and digest
-authentication, redirections, cookies and more.
-
-The \module{urllib2} module defines the following functions:
-
-\begin{funcdesc}{urlopen}{url\optional{, data}\optional{, timeout}}
-Open the URL \var{url}, which can be either a string or a \class{Request}
-object.
-
-\var{data} may be a string specifying additional data to send to the
-server, or \code{None} if no such data is needed.
-Currently HTTP requests are the only ones that use \var{data};
-the HTTP request will be a POST instead of a GET when the \var{data}
-parameter is provided. \var{data} should be a buffer in the standard
-\mimetype{application/x-www-form-urlencoded} format. The
-\function{urllib.urlencode()} function takes a mapping or sequence of
-2-tuples and returns a string in this format.
-
-The optional \var{timeout} parameter specifies a timeout in seconds for the
-connection attempt (if not specified, or passed as None, the global default
-timeout setting will be used). This actually only work for HTTP, HTTPS, FTP
-and FTPS connections.
-
-This function returns a file-like object with two additional methods:
-
-\begin{itemize}
- \item \method{geturl()} --- return the URL of the resource retrieved
- \item \method{info()} --- return the meta-information of the page, as
- a dictionary-like object
-\end{itemize}
-
-Raises \exception{URLError} on errors.
-
-Note that \code{None} may be returned if no handler handles the
-request (though the default installed global \class{OpenerDirector}
-uses \class{UnknownHandler} to ensure this never happens).
-
-\versionchanged[\var{timeout} was added]{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{install_opener}{opener}
-Install an \class{OpenerDirector} instance as the default global
-opener. Installing an opener is only necessary if you want urlopen to
-use that opener; otherwise, simply call \method{OpenerDirector.open()}
-instead of \function{urlopen()}. The code does not check for a real
-\class{OpenerDirector}, and any class with the appropriate interface
-will work.
-\end{funcdesc}
-
-\begin{funcdesc}{build_opener}{\optional{handler, \moreargs}}
-Return an \class{OpenerDirector} instance, which chains the
-handlers in the order given. \var{handler}s can be either instances
-of \class{BaseHandler}, or subclasses of \class{BaseHandler} (in
-which case it must be possible to call the constructor without
-any parameters). Instances of the following classes will be in
-front of the \var{handler}s, unless the \var{handler}s contain
-them, instances of them or subclasses of them:
-\class{ProxyHandler}, \class{UnknownHandler}, \class{HTTPHandler},
-\class{HTTPDefaultErrorHandler}, \class{HTTPRedirectHandler},
-\class{FTPHandler}, \class{FileHandler}, \class{HTTPErrorProcessor}.
-
-If the Python installation has SSL support (\function{socket.ssl()}
-exists), \class{HTTPSHandler} will also be added.
-
-Beginning in Python 2.3, a \class{BaseHandler} subclass may also
-change its \member{handler_order} member variable to modify its
-position in the handlers list.
-\end{funcdesc}
-
-
-The following exceptions are raised as appropriate:
-
-\begin{excdesc}{URLError}
-The handlers raise this exception (or derived exceptions) when they
-run into a problem. It is a subclass of \exception{IOError}.
-\end{excdesc}
-
-\begin{excdesc}{HTTPError}
-A subclass of \exception{URLError}, it can also function as a
-non-exceptional file-like return value (the same thing that
-\function{urlopen()} returns). This is useful when handling exotic
-HTTP errors, such as requests for authentication.
-\end{excdesc}
-
-
-The following classes are provided:
-
-\begin{classdesc}{Request}{url\optional{, data}\optional{, headers}
- \optional{, origin_req_host}\optional{, unverifiable}}
-This class is an abstraction of a URL request.
-
-\var{url} should be a string containing a valid URL.
-
-\var{data} may be a string specifying additional data to send to the
-server, or \code{None} if no such data is needed.
-Currently HTTP requests are the only ones that use \var{data};
-the HTTP request will be a POST instead of a GET when the \var{data}
-parameter is provided. \var{data} should be a buffer in the standard
-\mimetype{application/x-www-form-urlencoded} format. The
-\function{urllib.urlencode()} function takes a mapping or sequence of
-2-tuples and returns a string in this format.
-
-\var{headers} should be a dictionary, and will be treated as if
-\method{add_header()} was called with each key and value as arguments.
-
-The final two arguments are only of interest for correct handling of
-third-party HTTP cookies:
-
-\var{origin_req_host} should be the request-host of the origin
-transaction, as defined by \rfc{2965}. It defaults to
-\code{cookielib.request_host(self)}. This is the host name or IP
-address of the original request that was initiated by the user. For
-example, if the request is for an image in an HTML document, this
-should be the request-host of the request for the page containing the
-image.
-
-\var{unverifiable} should indicate whether the request is
-unverifiable, as defined by RFC 2965. It defaults to False. An
-unverifiable request is one whose URL the user did not have the option
-to approve. For example, if the request is for an image in an HTML
-document, and the user had no option to approve the automatic fetching
-of the image, this should be true.
-\end{classdesc}
-
-\begin{classdesc}{OpenerDirector}{}
-The \class{OpenerDirector} class opens URLs via \class{BaseHandler}s
-chained together. It manages the chaining of handlers, and recovery
-from errors.
-\end{classdesc}
-
-\begin{classdesc}{BaseHandler}{}
-This is the base class for all registered handlers --- and handles only
-the simple mechanics of registration.
-\end{classdesc}
-
-\begin{classdesc}{HTTPDefaultErrorHandler}{}
-A class which defines a default handler for HTTP error responses; all
-responses are turned into \exception{HTTPError} exceptions.
-\end{classdesc}
-
-\begin{classdesc}{HTTPRedirectHandler}{}
-A class to handle redirections.
-\end{classdesc}
-
-\begin{classdesc}{HTTPCookieProcessor}{\optional{cookiejar}}
-A class to handle HTTP Cookies.
-\end{classdesc}
-
-\begin{classdesc}{ProxyHandler}{\optional{proxies}}
-Cause requests to go through a proxy.
-If \var{proxies} is given, it must be a dictionary mapping
-protocol names to URLs of proxies.
-The default is to read the list of proxies from the environment
-variables \envvar{<protocol>_proxy}.
-\end{classdesc}
-
-\begin{classdesc}{HTTPPasswordMgr}{}
-Keep a database of
-\code{(\var{realm}, \var{uri}) -> (\var{user}, \var{password})}
-mappings.
-\end{classdesc}
-
-\begin{classdesc}{HTTPPasswordMgrWithDefaultRealm}{}
-Keep a database of
-\code{(\var{realm}, \var{uri}) -> (\var{user}, \var{password})} mappings.
-A realm of \code{None} is considered a catch-all realm, which is searched
-if no other realm fits.
-\end{classdesc}
-
-\begin{classdesc}{AbstractBasicAuthHandler}{\optional{password_mgr}}
-This is a mixin class that helps with HTTP authentication, both
-to the remote host and to a proxy.
-\var{password_mgr}, if given, should be something that is compatible
-with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
-for information on the interface that must be supported.
-\end{classdesc}
-
-\begin{classdesc}{HTTPBasicAuthHandler}{\optional{password_mgr}}
-Handle authentication with the remote host.
-\var{password_mgr}, if given, should be something that is compatible
-with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
-for information on the interface that must be supported.
-\end{classdesc}
-
-\begin{classdesc}{ProxyBasicAuthHandler}{\optional{password_mgr}}
-Handle authentication with the proxy.
-\var{password_mgr}, if given, should be something that is compatible
-with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
-for information on the interface that must be supported.
-\end{classdesc}
-
-\begin{classdesc}{AbstractDigestAuthHandler}{\optional{password_mgr}}
-This is a mixin class that helps with HTTP authentication, both
-to the remote host and to a proxy.
-\var{password_mgr}, if given, should be something that is compatible
-with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
-for information on the interface that must be supported.
-\end{classdesc}
-
-\begin{classdesc}{HTTPDigestAuthHandler}{\optional{password_mgr}}
-Handle authentication with the remote host.
-\var{password_mgr}, if given, should be something that is compatible
-with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
-for information on the interface that must be supported.
-\end{classdesc}
-
-\begin{classdesc}{ProxyDigestAuthHandler}{\optional{password_mgr}}
-Handle authentication with the proxy.
-\var{password_mgr}, if given, should be something that is compatible
-with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
-for information on the interface that must be supported.
-\end{classdesc}
-
-\begin{classdesc}{HTTPHandler}{}
-A class to handle opening of HTTP URLs.
-\end{classdesc}
-
-\begin{classdesc}{HTTPSHandler}{}
-A class to handle opening of HTTPS URLs.
-\end{classdesc}
-
-\begin{classdesc}{FileHandler}{}
-Open local files.
-\end{classdesc}
-
-\begin{classdesc}{FTPHandler}{}
-Open FTP URLs.
-\end{classdesc}
-
-\begin{classdesc}{CacheFTPHandler}{}
-Open FTP URLs, keeping a cache of open FTP connections to minimize
-delays.
-\end{classdesc}
-
-\begin{classdesc}{UnknownHandler}{}
-A catch-all class to handle unknown URLs.
-\end{classdesc}
-
-
-\subsection{Request Objects \label{request-objects}}
-
-The following methods describe all of \class{Request}'s public interface,
-and so all must be overridden in subclasses.
-
-\begin{methoddesc}[Request]{add_data}{data}
-Set the \class{Request} data to \var{data}. This is ignored by all
-handlers except HTTP handlers --- and there it should be a byte
-string, and will change the request to be \code{POST} rather than
-\code{GET}.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{get_method}{}
-Return a string indicating the HTTP request method. This is only
-meaningful for HTTP requests, and currently always returns
-\code{'GET'} or \code{'POST'}.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{has_data}{}
-Return whether the instance has a non-\code{None} data.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{get_data}{}
-Return the instance's data.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{add_header}{key, val}
-Add another header to the request. Headers are currently ignored by
-all handlers except HTTP handlers, where they are added to the list
-of headers sent to the server. Note that there cannot be more than
-one header with the same name, and later calls will overwrite
-previous calls in case the \var{key} collides. Currently, this is
-no loss of HTTP functionality, since all headers which have meaning
-when used more than once have a (header-specific) way of gaining the
-same functionality using only one header.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{add_unredirected_header}{key, header}
-Add a header that will not be added to a redirected request.
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{has_header}{header}
-Return whether the instance has the named header (checks both regular
-and unredirected).
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{get_full_url}{}
-Return the URL given in the constructor.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{get_type}{}
-Return the type of the URL --- also known as the scheme.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{get_host}{}
-Return the host to which a connection will be made.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{get_selector}{}
-Return the selector --- the part of the URL that is sent to
-the server.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{set_proxy}{host, type}
-Prepare the request by connecting to a proxy server. The \var{host}
-and \var{type} will replace those of the instance, and the instance's
-selector will be the original URL given in the constructor.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{get_origin_req_host}{}
-Return the request-host of the origin transaction, as defined by
-\rfc{2965}. See the documentation for the \class{Request}
-constructor.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{is_unverifiable}{}
-Return whether the request is unverifiable, as defined by RFC 2965.
-See the documentation for the \class{Request} constructor.
-\end{methoddesc}
-
-
-\subsection{OpenerDirector Objects \label{opener-director-objects}}
-
-\class{OpenerDirector} instances have the following methods:
-
-\begin{methoddesc}[OpenerDirector]{add_handler}{handler}
-\var{handler} should be an instance of \class{BaseHandler}. The
-following methods are searched, and added to the possible chains (note
-that HTTP errors are a special case).
-
-\begin{itemize}
- \item \method{\var{protocol}_open()} ---
- signal that the handler knows how to open \var{protocol} URLs.
- \item \method{http_error_\var{type}()} ---
- signal that the handler knows how to handle HTTP errors with HTTP
- error code \var{type}.
- \item \method{\var{protocol}_error()} ---
- signal that the handler knows how to handle errors from
- (non-\code{http}) \var{protocol}.
- \item \method{\var{protocol}_request()} ---
- signal that the handler knows how to pre-process \var{protocol}
- requests.
- \item \method{\var{protocol}_response()} ---
- signal that the handler knows how to post-process \var{protocol}
- responses.
-\end{itemize}
-\end{methoddesc}
-
-\begin{methoddesc}[OpenerDirector]{open}{url\optional{, data}{\optional{, timeout}}}
-Open the given \var{url} (which can be a request object or a string),
-optionally passing the given \var{data}.
-Arguments, return values and exceptions raised are the same as those
-of \function{urlopen()} (which simply calls the \method{open()} method
-on the currently installed global \class{OpenerDirector}). The optional
-\var{timeout} parameter specifies a timeout in seconds for the connection
-attempt (if not specified, or passed as None, the global default timeout
-setting will be used; this actually only work for HTTP, HTTPS, FTP
-and FTPS connections).
-
-\versionchanged[\var{timeout} was added]{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}[OpenerDirector]{error}{proto\optional{,
- arg\optional{, \moreargs}}}
-Handle an error of the given protocol. This will call the registered
-error handlers for the given protocol with the given arguments (which
-are protocol specific). The HTTP protocol is a special case which
-uses the HTTP response code to determine the specific error handler;
-refer to the \method{http_error_*()} methods of the handler classes.
-
-Return values and exceptions raised are the same as those
-of \function{urlopen()}.
-\end{methoddesc}
-
-OpenerDirector objects open URLs in three stages:
-
-The order in which these methods are called within each stage is
-determined by sorting the handler instances.
-
-\begin{enumerate}
- \item Every handler with a method named like
- \method{\var{protocol}_request()} has that method called to
- pre-process the request.
-
- \item Handlers with a method named like
- \method{\var{protocol}_open()} are called to handle the request.
- This stage ends when a handler either returns a
- non-\constant{None} value (ie. a response), or raises an exception
- (usually \exception{URLError}). Exceptions are allowed to propagate.
-
- In fact, the above algorithm is first tried for methods named
- \method{default_open}. If all such methods return
- \constant{None}, the algorithm is repeated for methods named like
- \method{\var{protocol}_open()}. If all such methods return
- \constant{None}, the algorithm is repeated for methods named
- \method{unknown_open()}.
-
- Note that the implementation of these methods may involve calls of
- the parent \class{OpenerDirector} instance's \method{.open()} and
- \method{.error()} methods.
-
- \item Every handler with a method named like
- \method{\var{protocol}_response()} has that method called to
- post-process the response.
-
-\end{enumerate}
-
-\subsection{BaseHandler Objects \label{base-handler-objects}}
-
-\class{BaseHandler} objects provide a couple of methods that are
-directly useful, and others that are meant to be used by derived
-classes. These are intended for direct use:
-
-\begin{methoddesc}[BaseHandler]{add_parent}{director}
-Add a director as parent.
-\end{methoddesc}
-
-\begin{methoddesc}[BaseHandler]{close}{}
-Remove any parents.
-\end{methoddesc}
-
-The following members and methods should only be used by classes
-derived from \class{BaseHandler}. \note{The convention has been
-adopted that subclasses defining \method{\var{protocol}_request()} or
-\method{\var{protocol}_response()} methods are named
-\class{*Processor}; all others are named \class{*Handler}.}
-
-
-\begin{memberdesc}[BaseHandler]{parent}
-A valid \class{OpenerDirector}, which can be used to open using a
-different protocol, or handle errors.
-\end{memberdesc}
-
-\begin{methoddesc}[BaseHandler]{default_open}{req}
-This method is \emph{not} defined in \class{BaseHandler}, but
-subclasses should define it if they want to catch all URLs.
-
-This method, if implemented, will be called by the parent
-\class{OpenerDirector}. It should return a file-like object as
-described in the return value of the \method{open()} of
-\class{OpenerDirector}, or \code{None}. It should raise
-\exception{URLError}, unless a truly exceptional thing happens (for
-example, \exception{MemoryError} should not be mapped to
-\exception{URLError}).
-
-This method will be called before any protocol-specific open method.
-\end{methoddesc}
-
-\begin{methoddescni}[BaseHandler]{\var{protocol}_open}{req}
-This method is \emph{not} defined in \class{BaseHandler}, but
-subclasses should define it if they want to handle URLs with the given
-protocol.
-
-This method, if defined, will be called by the parent
-\class{OpenerDirector}. Return values should be the same as for
-\method{default_open()}.
-\end{methoddescni}
-
-\begin{methoddesc}[BaseHandler]{unknown_open}{req}
-This method is \var{not} defined in \class{BaseHandler}, but
-subclasses should define it if they want to catch all URLs with no
-specific registered handler to open it.
-
-This method, if implemented, will be called by the \member{parent}
-\class{OpenerDirector}. Return values should be the same as for
-\method{default_open()}.
-\end{methoddesc}
-
-\begin{methoddesc}[BaseHandler]{http_error_default}{req, fp, code, msg, hdrs}
-This method is \emph{not} defined in \class{BaseHandler}, but
-subclasses should override it if they intend to provide a catch-all
-for otherwise unhandled HTTP errors. It will be called automatically
-by the \class{OpenerDirector} getting the error, and should not
-normally be called in other circumstances.
-
-\var{req} will be a \class{Request} object, \var{fp} will be a
-file-like object with the HTTP error body, \var{code} will be the
-three-digit code of the error, \var{msg} will be the user-visible
-explanation of the code and \var{hdrs} will be a mapping object with
-the headers of the error.
-
-Return values and exceptions raised should be the same as those
-of \function{urlopen()}.
-\end{methoddesc}
-
-\begin{methoddesc}[BaseHandler]{http_error_\var{nnn}}{req, fp, code, msg, hdrs}
-\var{nnn} should be a three-digit HTTP error code. This method is
-also not defined in \class{BaseHandler}, but will be called, if it
-exists, on an instance of a subclass, when an HTTP error with code
-\var{nnn} occurs.
-
-Subclasses should override this method to handle specific HTTP
-errors.
-
-Arguments, return values and exceptions raised should be the same as
-for \method{http_error_default()}.
-\end{methoddesc}
-
-\begin{methoddescni}[BaseHandler]{\var{protocol}_request}{req}
-This method is \emph{not} defined in \class{BaseHandler}, but
-subclasses should define it if they want to pre-process requests of
-the given protocol.
-
-This method, if defined, will be called by the parent
-\class{OpenerDirector}. \var{req} will be a \class{Request} object.
-The return value should be a \class{Request} object.
-\end{methoddescni}
-
-\begin{methoddescni}[BaseHandler]{\var{protocol}_response}{req, response}
-This method is \emph{not} defined in \class{BaseHandler}, but
-subclasses should define it if they want to post-process responses of
-the given protocol.
-
-This method, if defined, will be called by the parent
-\class{OpenerDirector}. \var{req} will be a \class{Request} object.
-\var{response} will be an object implementing the same interface as
-the return value of \function{urlopen()}. The return value should
-implement the same interface as the return value of
-\function{urlopen()}.
-\end{methoddescni}
-
-\subsection{HTTPRedirectHandler Objects \label{http-redirect-handler}}
-
-\note{Some HTTP redirections require action from this module's client
- code. If this is the case, \exception{HTTPError} is raised. See
- \rfc{2616} for details of the precise meanings of the various
- redirection codes.}
-
-\begin{methoddesc}[HTTPRedirectHandler]{redirect_request}{req,
- fp, code, msg, hdrs}
-Return a \class{Request} or \code{None} in response to a redirect.
-This is called by the default implementations of the
-\method{http_error_30*()} methods when a redirection is received from
-the server. If a redirection should take place, return a new
-\class{Request} to allow \method{http_error_30*()} to perform the
-redirect. Otherwise, raise \exception{HTTPError} if no other handler
-should try to handle this URL, or return \code{None} if you can't but
-another handler might.
-
-\begin{notice}
- The default implementation of this method does not strictly
- follow \rfc{2616}, which says that 301 and 302 responses to \code{POST}
- requests must not be automatically redirected without confirmation by
- the user. In reality, browsers do allow automatic redirection of
- these responses, changing the POST to a \code{GET}, and the default
- implementation reproduces this behavior.
-\end{notice}
-\end{methoddesc}
-
-
-\begin{methoddesc}[HTTPRedirectHandler]{http_error_301}{req,
- fp, code, msg, hdrs}
-Redirect to the \code{Location:} URL. This method is called by
-the parent \class{OpenerDirector} when getting an HTTP
-`moved permanently' response.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPRedirectHandler]{http_error_302}{req,
- fp, code, msg, hdrs}
-The same as \method{http_error_301()}, but called for the
-`found' response.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPRedirectHandler]{http_error_303}{req,
- fp, code, msg, hdrs}
-The same as \method{http_error_301()}, but called for the
-`see other' response.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPRedirectHandler]{http_error_307}{req,
- fp, code, msg, hdrs}
-The same as \method{http_error_301()}, but called for the
-`temporary redirect' response.
-\end{methoddesc}
-
-
-\subsection{HTTPCookieProcessor Objects \label{http-cookie-processor}}
-
-\versionadded{2.4}
-
-\class{HTTPCookieProcessor} instances have one attribute:
-
-\begin{memberdesc}[HTTPCookieProcessor]{cookiejar}
-The \class{cookielib.CookieJar} in which cookies are stored.
-\end{memberdesc}
-
-
-\subsection{ProxyHandler Objects \label{proxy-handler}}
-
-\begin{methoddescni}[ProxyHandler]{\var{protocol}_open}{request}
-The \class{ProxyHandler} will have a method
-\method{\var{protocol}_open()} for every \var{protocol} which has a
-proxy in the \var{proxies} dictionary given in the constructor. The
-method will modify requests to go through the proxy, by calling
-\code{request.set_proxy()}, and call the next handler in the chain to
-actually execute the protocol.
-\end{methoddescni}
-
-
-\subsection{HTTPPasswordMgr Objects \label{http-password-mgr}}
-
-These methods are available on \class{HTTPPasswordMgr} and
-\class{HTTPPasswordMgrWithDefaultRealm} objects.
-
-\begin{methoddesc}[HTTPPasswordMgr]{add_password}{realm, uri, user, passwd}
-\var{uri} can be either a single URI, or a sequence of URIs. \var{realm},
-\var{user} and \var{passwd} must be strings. This causes
-\code{(\var{user}, \var{passwd})} to be used as authentication tokens
-when authentication for \var{realm} and a super-URI of any of the
-given URIs is given.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPPasswordMgr]{find_user_password}{realm, authuri}
-Get user/password for given realm and URI, if any. This method will
-return \code{(None, None)} if there is no matching user/password.
-
-For \class{HTTPPasswordMgrWithDefaultRealm} objects, the realm
-\code{None} will be searched if the given \var{realm} has no matching
-user/password.
-\end{methoddesc}
-
-
-\subsection{AbstractBasicAuthHandler Objects
- \label{abstract-basic-auth-handler}}
-
-\begin{methoddesc}[AbstractBasicAuthHandler]{http_error_auth_reqed}
- {authreq, host, req, headers}
-Handle an authentication request by getting a user/password pair, and
-re-trying the request. \var{authreq} should be the name of the header
-where the information about the realm is included in the request,
-\var{host} specifies the URL and path to authenticate for, \var{req}
-should be the (failed) \class{Request} object, and \var{headers}
-should be the error headers.
-
-\var{host} is either an authority (e.g. \code{"python.org"}) or a URL
-containing an authority component (e.g. \code{"http://python.org/"}).
-In either case, the authority must not contain a userinfo component
-(so, \code{"python.org"} and \code{"python.org:80"} are fine,
-\code{"joe:password@python.org"} is not).
-\end{methoddesc}
-
-
-\subsection{HTTPBasicAuthHandler Objects
- \label{http-basic-auth-handler}}
-
-\begin{methoddesc}[HTTPBasicAuthHandler]{http_error_401}{req, fp, code,
- msg, hdrs}
-Retry the request with authentication information, if available.
-\end{methoddesc}
-
-
-\subsection{ProxyBasicAuthHandler Objects
- \label{proxy-basic-auth-handler}}
-
-\begin{methoddesc}[ProxyBasicAuthHandler]{http_error_407}{req, fp, code,
- msg, hdrs}
-Retry the request with authentication information, if available.
-\end{methoddesc}
-
-
-\subsection{AbstractDigestAuthHandler Objects
- \label{abstract-digest-auth-handler}}
-
-\begin{methoddesc}[AbstractDigestAuthHandler]{http_error_auth_reqed}
- {authreq, host, req, headers}
-\var{authreq} should be the name of the header where the information about
-the realm is included in the request, \var{host} should be the host to
-authenticate to, \var{req} should be the (failed) \class{Request}
-object, and \var{headers} should be the error headers.
-\end{methoddesc}
-
-
-\subsection{HTTPDigestAuthHandler Objects
- \label{http-digest-auth-handler}}
-
-\begin{methoddesc}[HTTPDigestAuthHandler]{http_error_401}{req, fp, code,
- msg, hdrs}
-Retry the request with authentication information, if available.
-\end{methoddesc}
-
-
-\subsection{ProxyDigestAuthHandler Objects
- \label{proxy-digest-auth-handler}}
-
-\begin{methoddesc}[ProxyDigestAuthHandler]{http_error_407}{req, fp, code,
- msg, hdrs}
-Retry the request with authentication information, if available.
-\end{methoddesc}
-
-
-\subsection{HTTPHandler Objects \label{http-handler-objects}}
-
-\begin{methoddesc}[HTTPHandler]{http_open}{req}
-Send an HTTP request, which can be either GET or POST, depending on
-\code{\var{req}.has_data()}.
-\end{methoddesc}
-
-
-\subsection{HTTPSHandler Objects \label{https-handler-objects}}
-
-\begin{methoddesc}[HTTPSHandler]{https_open}{req}
-Send an HTTPS request, which can be either GET or POST, depending on
-\code{\var{req}.has_data()}.
-\end{methoddesc}
-
-
-\subsection{FileHandler Objects \label{file-handler-objects}}
-
-\begin{methoddesc}[FileHandler]{file_open}{req}
-Open the file locally, if there is no host name, or
-the host name is \code{'localhost'}. Change the
-protocol to \code{ftp} otherwise, and retry opening
-it using \member{parent}.
-\end{methoddesc}
-
-
-\subsection{FTPHandler Objects \label{ftp-handler-objects}}
-
-\begin{methoddesc}[FTPHandler]{ftp_open}{req}
-Open the FTP file indicated by \var{req}.
-The login is always done with empty username and password.
-\end{methoddesc}
-
-
-\subsection{CacheFTPHandler Objects \label{cacheftp-handler-objects}}
-
-\class{CacheFTPHandler} objects are \class{FTPHandler} objects with
-the following additional methods:
-
-\begin{methoddesc}[CacheFTPHandler]{setTimeout}{t}
-Set timeout of connections to \var{t} seconds.
-\end{methoddesc}
-
-\begin{methoddesc}[CacheFTPHandler]{setMaxConns}{m}
-Set maximum number of cached connections to \var{m}.
-\end{methoddesc}
-
-
-\subsection{UnknownHandler Objects \label{unknown-handler-objects}}
-
-\begin{methoddesc}[UnknownHandler]{unknown_open}{}
-Raise a \exception{URLError} exception.
-\end{methoddesc}
-
-
-\subsection{HTTPErrorProcessor Objects \label{http-error-processor-objects}}
-
-\versionadded{2.4}
-
-\begin{methoddesc}[HTTPErrorProcessor]{unknown_open}{}
-Process HTTP error responses.
-
-For 200 error codes, the response object is returned immediately.
-
-For non-200 error codes, this simply passes the job on to the
-\method{\var{protocol}_error_\var{code}()} handler methods, via
-\method{OpenerDirector.error()}. Eventually,
-\class{urllib2.HTTPDefaultErrorHandler} will raise an
-\exception{HTTPError} if no other handler handles the error.
-\end{methoddesc}
-
-
-\subsection{Examples \label{urllib2-examples}}
-
-This example gets the python.org main page and displays the first 100
-bytes of it:
-
-\begin{verbatim}
->>> import urllib2
->>> f = urllib2.urlopen('http://www.python.org/')
->>> print f.read(100)
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<?xml-stylesheet href="./css/ht2html
-\end{verbatim}
-
-Here we are sending a data-stream to the stdin of a CGI and reading
-the data it returns to us. Note that this example will only work when the
-Python installation supports SSL.
-
-\begin{verbatim}
->>> import urllib2
->>> req = urllib2.Request(url='https://localhost/cgi-bin/test.cgi',
-... data='This data is passed to stdin of the CGI')
->>> f = urllib2.urlopen(req)
->>> print f.read()
-Got Data: "This data is passed to stdin of the CGI"
-\end{verbatim}
-
-The code for the sample CGI used in the above example is:
-
-\begin{verbatim}
-#!/usr/bin/env python
-import sys
-data = sys.stdin.read()
-print 'Content-type: text-plain\n\nGot Data: "%s"' % data
-\end{verbatim}
-
-
-Use of Basic HTTP Authentication:
-
-\begin{verbatim}
-import urllib2
-# Create an OpenerDirector with support for Basic HTTP Authentication...
-auth_handler = urllib2.HTTPBasicAuthHandler()
-auth_handler.add_password(realm='PDQ Application',
- uri='https://mahler:8092/site-updates.py',
- user='klem',
- passwd='kadidd!ehopper')
-opener = urllib2.build_opener(auth_handler)
-# ...and install it globally so it can be used with urlopen.
-urllib2.install_opener(opener)
-urllib2.urlopen('http://www.example.com/login.html')
-\end{verbatim}
-
-\function{build_opener()} provides many handlers by default, including a
-\class{ProxyHandler}. By default, \class{ProxyHandler} uses the
-environment variables named \code{<scheme>_proxy}, where \code{<scheme>}
-is the URL scheme involved. For example, the \envvar{http_proxy}
-environment variable is read to obtain the HTTP proxy's URL.
-
-This example replaces the default \class{ProxyHandler} with one that uses
-programatically-supplied proxy URLs, and adds proxy authorization support
-with \class{ProxyBasicAuthHandler}.
-
-\begin{verbatim}
-proxy_handler = urllib2.ProxyHandler({'http': 'http://www.example.com:3128/'})
-proxy_auth_handler = urllib2.HTTPBasicAuthHandler()
-proxy_auth_handler.add_password('realm', 'host', 'username', 'password')
-
-opener = build_opener(proxy_handler, proxy_auth_handler)
-# This time, rather than install the OpenerDirector, we use it directly:
-opener.open('http://www.example.com/login.html')
-\end{verbatim}
-
-
-Adding HTTP headers:
-
-Use the \var{headers} argument to the \class{Request} constructor, or:
-
-\begin{verbatim}
-import urllib2
-req = urllib2.Request('http://www.example.com/')
-req.add_header('Referer', 'http://www.python.org/')
-r = urllib2.urlopen(req)
-\end{verbatim}
-
-\class{OpenerDirector} automatically adds a \mailheader{User-Agent}
-header to every \class{Request}. To change this:
-
-\begin{verbatim}
-import urllib2
-opener = urllib2.build_opener()
-opener.addheaders = [('User-agent', 'Mozilla/5.0')]
-opener.open('http://www.example.com/')
-\end{verbatim}
-
-Also, remember that a few standard headers
-(\mailheader{Content-Length}, \mailheader{Content-Type} and
-\mailheader{Host}) are added when the \class{Request} is passed to
-\function{urlopen()} (or \method{OpenerDirector.open()}).
diff --git a/Doc/lib/liburlparse.tex b/Doc/lib/liburlparse.tex
deleted file mode 100644
index 16f38a0..0000000
--- a/Doc/lib/liburlparse.tex
+++ /dev/null
@@ -1,253 +0,0 @@
-\section{\module{urlparse} ---
- Parse URLs into components}
-\declaremodule{standard}{urlparse}
-
-\modulesynopsis{Parse URLs into components.}
-
-\index{WWW}
-\index{World Wide Web}
-\index{URL}
-\indexii{URL}{parsing}
-\indexii{relative}{URL}
-
-
-This module defines a standard interface to break Uniform Resource
-Locator (URL) strings up in components (addressing scheme, network
-location, path etc.), to combine the components back into a URL
-string, and to convert a ``relative URL'' to an absolute URL given a
-``base URL.''
-
-The module has been designed to match the Internet RFC on Relative
-Uniform Resource Locators (and discovered a bug in an earlier
-draft!). It supports the following URL schemes:
-\code{file}, \code{ftp}, \code{gopher}, \code{hdl}, \code{http},
-\code{https}, \code{imap}, \code{mailto}, \code{mms}, \code{news},
-\code{nntp}, \code{prospero}, \code{rsync}, \code{rtsp}, \code{rtspu},
-\code{sftp}, \code{shttp}, \code{sip}, \code{sips}, \code{snews}, \code{svn},
-\code{svn+ssh}, \code{telnet}, \code{wais}.
-
-\versionadded[Support for the \code{sftp} and \code{sips} schemes]{2.5}
-
-The \module{urlparse} module defines the following functions:
-
-\begin{funcdesc}{urlparse}{urlstring\optional{,
- default_scheme\optional{, allow_fragments}}}
-Parse a URL into six components, returning a 6-tuple. This
-corresponds to the general structure of a URL:
-\code{\var{scheme}://\var{netloc}/\var{path};\var{parameters}?\var{query}\#\var{fragment}}.
-Each tuple item is a string, possibly empty.
-The components are not broken up in smaller parts (for example, the network
-location is a single string), and \% escapes are not expanded.
-The delimiters as shown above are not part of the result,
-except for a leading slash in the \var{path} component, which is
-retained if present. For example:
-
-\begin{verbatim}
->>> from urlparse import urlparse
->>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
->>> o
-('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '')
->>> o.scheme
-'http'
->>> o.port
-80
->>> o.geturl()
-'http://www.cwi.nl:80/%7Eguido/Python.html'
-\end{verbatim}
-
-If the \var{default_scheme} argument is specified, it gives the
-default addressing scheme, to be used only if the URL does not
-specify one. The default value for this argument is the empty string.
-
-If the \var{allow_fragments} argument is false, fragment identifiers
-are not allowed, even if the URL's addressing scheme normally does
-support them. The default value for this argument is \constant{True}.
-
-The return value is actually an instance of a subclass of
-\pytype{tuple}. This class has the following additional read-only
-convenience attributes:
-
-\begin{tableiv}{l|c|l|c}{member}{Attribute}{Index}{Value}{Value if not present}
- \lineiv{scheme} {0} {URL scheme specifier} {empty string}
- \lineiv{netloc} {1} {Network location part} {empty string}
- \lineiv{path} {2} {Hierarchical path} {empty string}
- \lineiv{params} {3} {Parameters for last path element} {empty string}
- \lineiv{query} {4} {Query component} {empty string}
- \lineiv{fragment}{5} {Fragment identifier} {empty string}
- \lineiv{username}{ } {User name} {\constant{None}}
- \lineiv{password}{ } {Password} {\constant{None}}
- \lineiv{hostname}{ } {Host name (lower case)} {\constant{None}}
- \lineiv{port} { } {Port number as integer, if present} {\constant{None}}
-\end{tableiv}
-
-See section~\ref{urlparse-result-object}, ``Results of
-\function{urlparse()} and \function{urlsplit()},'' for more
-information on the result object.
-
-\versionchanged[Added attributes to return value]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{urlunparse}{parts}
-Construct a URL from a tuple as returned by \code{urlparse()}.
-The \var{parts} argument can be any six-item iterable.
-This may result in a slightly different, but equivalent URL, if the
-URL that was parsed originally had unnecessary delimiters (for example,
-a ? with an empty query; the RFC states that these are equivalent).
-\end{funcdesc}
-
-\begin{funcdesc}{urlsplit}{urlstring\optional{,
- default_scheme\optional{, allow_fragments}}}
-This is similar to \function{urlparse()}, but does not split the
-params from the URL. This should generally be used instead of
-\function{urlparse()} if the more recent URL syntax allowing
-parameters to be applied to each segment of the \var{path} portion of
-the URL (see \rfc{2396}) is wanted. A separate function is needed to
-separate the path segments and parameters. This function returns a
-5-tuple: (addressing scheme, network location, path, query, fragment
-identifier).
-
-The return value is actually an instance of a subclass of
-\pytype{tuple}. This class has the following additional read-only
-convenience attributes:
-
-\begin{tableiv}{l|c|l|c}{member}{Attribute}{Index}{Value}{Value if not present}
- \lineiv{scheme} {0} {URL scheme specifier} {empty string}
- \lineiv{netloc} {1} {Network location part} {empty string}
- \lineiv{path} {2} {Hierarchical path} {empty string}
- \lineiv{query} {3} {Query component} {empty string}
- \lineiv{fragment} {4} {Fragment identifier} {empty string}
- \lineiv{username} { } {User name} {\constant{None}}
- \lineiv{password} { } {Password} {\constant{None}}
- \lineiv{hostname} { } {Host name (lower case)} {\constant{None}}
- \lineiv{port} { } {Port number as integer, if present} {\constant{None}}
-\end{tableiv}
-
-See section~\ref{urlparse-result-object}, ``Results of
-\function{urlparse()} and \function{urlsplit()},'' for more
-information on the result object.
-
-\versionadded{2.2}
-\versionchanged[Added attributes to return value]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{urlunsplit}{parts}
-Combine the elements of a tuple as returned by \function{urlsplit()}
-into a complete URL as a string.
-The \var{parts} argument can be any five-item iterable.
-This may result in a slightly different, but equivalent URL, if the
-URL that was parsed originally had unnecessary delimiters (for example,
-a ? with an empty query; the RFC states that these are equivalent).
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{urljoin}{base, url\optional{, allow_fragments}}
-Construct a full (``absolute'') URL by combining a ``base URL''
-(\var{base}) with another URL (\var{url}). Informally, this
-uses components of the base URL, in particular the addressing scheme,
-the network location and (part of) the path, to provide missing
-components in the relative URL. For example:
-
-\begin{verbatim}
->>> from urlparse import urljoin
->>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
-'http://www.cwi.nl/%7Eguido/FAQ.html'
-\end{verbatim}
-
-The \var{allow_fragments} argument has the same meaning and default as
-for \function{urlparse()}.
-
-\note{If \var{url} is an absolute URL (that is, starting with \code{//}
- or \code{scheme://}), the \var{url}'s host name and/or scheme
- will be present in the result. For example:}
-
-\begin{verbatim}
->>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
-... '//www.python.org/%7Eguido')
-'http://www.python.org/%7Eguido'
-\end{verbatim}
-
-If you do not want that behavior, preprocess
-the \var{url} with \function{urlsplit()} and \function{urlunsplit()},
-removing possible \emph{scheme} and \emph{netloc} parts.
-\end{funcdesc}
-
-\begin{funcdesc}{urldefrag}{url}
-If \var{url} contains a fragment identifier, returns a modified
-version of \var{url} with no fragment identifier, and the fragment
-identifier as a separate string. If there is no fragment identifier
-in \var{url}, returns \var{url} unmodified and an empty string.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seerfc{1738}{Uniform Resource Locators (URL)}{
- This specifies the formal syntax and semantics of absolute
- URLs.}
- \seerfc{1808}{Relative Uniform Resource Locators}{
- This Request For Comments includes the rules for joining an
- absolute and a relative URL, including a fair number of
- ``Abnormal Examples'' which govern the treatment of border
- cases.}
- \seerfc{2396}{Uniform Resource Identifiers (URI): Generic Syntax}{
- Document describing the generic syntactic requirements for
- both Uniform Resource Names (URNs) and Uniform Resource
- Locators (URLs).}
-\end{seealso}
-
-
-\subsection{Results of \function{urlparse()} and \function{urlsplit()}
- \label{urlparse-result-object}}
-
-The result objects from the \function{urlparse()} and
-\function{urlsplit()} functions are subclasses of the \pytype{tuple}
-type. These subclasses add the attributes described in those
-functions, as well as provide an additional method:
-
-\begin{methoddesc}[ParseResult]{geturl}{}
- Return the re-combined version of the original URL as a string.
- This may differ from the original URL in that the scheme will always
- be normalized to lower case and empty components may be dropped.
- Specifically, empty parameters, queries, and fragment identifiers
- will be removed.
-
- The result of this method is a fixpoint if passed back through the
- original parsing function:
-
-\begin{verbatim}
->>> import urlparse
->>> url = 'HTTP://www.Python.org/doc/#'
-
->>> r1 = urlparse.urlsplit(url)
->>> r1.geturl()
-'http://www.Python.org/doc/'
-
->>> r2 = urlparse.urlsplit(r1.geturl())
->>> r2.geturl()
-'http://www.Python.org/doc/'
-\end{verbatim}
-
-\versionadded{2.5}
-\end{methoddesc}
-
-The following classes provide the implementations of the parse results::
-
-\begin{classdesc*}{BaseResult}
- Base class for the concrete result classes. This provides most of
- the attribute definitions. It does not provide a \method{geturl()}
- method. It is derived from \class{tuple}, but does not override the
- \method{__init__()} or \method{__new__()} methods.
-\end{classdesc*}
-
-
-\begin{classdesc}{ParseResult}{scheme, netloc, path, params, query, fragment}
- Concrete class for \function{urlparse()} results. The
- \method{__new__()} method is overridden to support checking that the
- right number of arguments are passed.
-\end{classdesc}
-
-
-\begin{classdesc}{SplitResult}{scheme, netloc, path, query, fragment}
- Concrete class for \function{urlsplit()} results. The
- \method{__new__()} method is overridden to support checking that the
- right number of arguments are passed.
-\end{classdesc}
diff --git a/Doc/lib/libuser.tex b/Doc/lib/libuser.tex
deleted file mode 100644
index 6dd1546..0000000
--- a/Doc/lib/libuser.tex
+++ /dev/null
@@ -1,71 +0,0 @@
-\section{\module{user} ---
- User-specific configuration hook}
-
-\declaremodule{standard}{user}
-\modulesynopsis{A standard way to reference user-specific modules.}
-
-
-\indexii{.pythonrc.py}{file}
-\indexiii{user}{configuration}{file}
-
-As a policy, Python doesn't run user-specified code on startup of
-Python programs. (Only interactive sessions execute the script
-specified in the \envvar{PYTHONSTARTUP} environment variable if it
-exists).
-
-However, some programs or sites may find it convenient to allow users
-to have a standard customization file, which gets run when a program
-requests it. This module implements such a mechanism. A program
-that wishes to use the mechanism must execute the statement
-
-\begin{verbatim}
-import user
-\end{verbatim}
-
-The \module{user} module looks for a file \file{.pythonrc.py} in the user's
-home directory and if it can be opened, executes it (using
-\function{exec()}\bifuncindex{exec}) in its own (the
-module \module{user}'s) global namespace. Errors during this phase
-are not caught; that's up to the program that imports the
-\module{user} module, if it wishes. The home directory is assumed to
-be named by the \envvar{HOME} environment variable; if this is not set,
-the current directory is used.
-
-The user's \file{.pythonrc.py} could conceivably test for
-\code{sys.version} if it wishes to do different things depending on
-the Python version.
-
-A warning to users: be very conservative in what you place in your
-\file{.pythonrc.py} file. Since you don't know which programs will
-use it, changing the behavior of standard modules or functions is
-generally not a good idea.
-
-A suggestion for programmers who wish to use this mechanism: a simple
-way to let users specify options for your package is to have them
-define variables in their \file{.pythonrc.py} file that you test in
-your module. For example, a module \module{spam} that has a verbosity
-level can look for a variable \code{user.spam_verbose}, as follows:
-
-\begin{verbatim}
-import user
-
-verbose = bool(getattr(user, "spam_verbose", 0))
-\end{verbatim}
-
-(The three-argument form of \function{getattr()} is used in case
-the user has not defined \code{spam_verbose} in their
-\file{.pythonrc.py} file.)
-
-Programs with extensive customization needs are better off reading a
-program-specific customization file.
-
-Programs with security or privacy concerns should \emph{not} import
-this module; a user can easily break into a program by placing
-arbitrary code in the \file{.pythonrc.py} file.
-
-Modules for general use should \emph{not} import this module; it may
-interfere with the operation of the importing program.
-
-\begin{seealso}
- \seemodule{site}{Site-wide customization mechanism.}
-\end{seealso}
diff --git a/Doc/lib/libuserdict.tex b/Doc/lib/libuserdict.tex
deleted file mode 100644
index 0bb57c8..0000000
--- a/Doc/lib/libuserdict.tex
+++ /dev/null
@@ -1,181 +0,0 @@
-\section{\module{UserDict} ---
- Class wrapper for dictionary objects}
-
-\declaremodule{standard}{UserDict}
-\modulesynopsis{Class wrapper for dictionary objects.}
-
-
-The module defines a mixin, \class{DictMixin}, defining all dictionary
-methods for classes that already have a minimum mapping interface. This
-greatly simplifies writing classes that need to be substitutable for
-dictionaries (such as the shelve module).
-
-This also module defines a class, \class{UserDict}, that acts as a wrapper
-around dictionary objects. The need for this class has been largely
-supplanted by the ability to subclass directly from \class{dict} (a feature
-that became available starting with Python version 2.2). Prior to the
-introduction of \class{dict}, the \class{UserDict} class was used to
-create dictionary-like sub-classes that obtained new behaviors by overriding
-existing methods or adding new ones.
-
-The \module{UserDict} module defines the \class{UserDict} class
-and \class{DictMixin}:
-
-\begin{classdesc}{UserDict}{\optional{initialdata}}
-Class that simulates a dictionary. The instance's contents are kept
-in a regular dictionary, which is accessible via the \member{data}
-attribute of \class{UserDict} instances. If \var{initialdata} is
-provided, \member{data} is initialized with its contents; note that a
-reference to \var{initialdata} will not be kept, allowing it be used
-for other purposes. \note{For backward compatibility, instances of
-\class{UserDict} are not iterable.}
-\end{classdesc}
-
-\begin{classdesc}{IterableUserDict}{\optional{initialdata}}
-Subclass of \class{UserDict} that supports direct iteration (e.g.
-\code{for key in myDict}).
-\end{classdesc}
-
-In addition to supporting the methods and operations of mappings (see
-section \ref{typesmapping}), \class{UserDict} and
-\class{IterableUserDict} instances provide the following attribute:
-
-\begin{memberdesc}{data}
-A real dictionary used to store the contents of the \class{UserDict}
-class.
-\end{memberdesc}
-
-\begin{classdesc}{DictMixin}{}
-Mixin defining all dictionary methods for classes that already have
-a minimum dictionary interface including \method{__getitem__()},
-\method{__setitem__()}, \method{__delitem__()}, and \method{keys()}.
-
-This mixin should be used as a superclass. Adding each of the
-above methods adds progressively more functionality. For instance,
-defining all but \method{__delitem__} will preclude only \method{pop}
-and \method{popitem} from the full interface.
-
-In addition to the four base methods, progressively more efficiency
-comes with defining \method{__contains__()}, \method{__iter__()}, and
-\method{iteritems()}.
-
-Since the mixin has no knowledge of the subclass constructor, it
-does not define \method{__init__()} or \method{copy()}.
-\end{classdesc}
-
-
-\section{\module{UserList} ---
- Class wrapper for list objects}
-
-\declaremodule{standard}{UserList}
-\modulesynopsis{Class wrapper for list objects.}
-
-
-\note{This module is available for backward compatibility only. If
-you are writing code that does not need to work with versions of
-Python earlier than Python 2.2, please consider subclassing directly
-from the built-in \class{list} type.}
-
-This module defines a class that acts as a wrapper around
-list objects. It is a useful base class for
-your own list-like classes, which can inherit from
-them and override existing methods or add new ones. In this way one
-can add new behaviors to lists.
-
-The \module{UserList} module defines the \class{UserList} class:
-
-\begin{classdesc}{UserList}{\optional{list}}
-Class that simulates a list. The instance's
-contents are kept in a regular list, which is accessible via the
-\member{data} attribute of \class{UserList} instances. The instance's
-contents are initially set to a copy of \var{list}, defaulting to the
-empty list \code{[]}. \var{list} can be either a regular Python list,
-or an instance of \class{UserList} (or a subclass).
-\end{classdesc}
-
-In addition to supporting the methods and operations of mutable
-sequences (see section \ref{typesseq}), \class{UserList} instances
-provide the following attribute:
-
-\begin{memberdesc}{data}
-A real Python list object used to store the contents of the
-\class{UserList} class.
-\end{memberdesc}
-
-\strong{Subclassing requirements:}
-Subclasses of \class{UserList} are expect to offer a constructor which
-can be called with either no arguments or one argument. List
-operations which return a new sequence attempt to create an instance
-of the actual implementation class. To do so, it assumes that the
-constructor can be called with a single parameter, which is a sequence
-object used as a data source.
-
-If a derived class does not wish to comply with this requirement, all
-of the special methods supported by this class will need to be
-overridden; please consult the sources for information about the
-methods which need to be provided in that case.
-
-\versionchanged[Python versions 1.5.2 and 1.6 also required that the
- constructor be callable with no parameters, and offer
- a mutable \member{data} attribute. Earlier versions
- of Python did not attempt to create instances of the
- derived class]{2.0}
-
-
-\section{\module{UserString} ---
- Class wrapper for string objects}
-
-\declaremodule{standard}{UserString}
-\modulesynopsis{Class wrapper for string objects.}
-\moduleauthor{Peter Funk}{pf@artcom-gmbh.de}
-\sectionauthor{Peter Funk}{pf@artcom-gmbh.de}
-
-\note{This \class{UserString} class from this module is available for
-backward compatibility only. If you are writing code that does not
-need to work with versions of Python earlier than Python 2.2, please
-consider subclassing directly from the built-in \class{str} type
-instead of using \class{UserString} (there is no built-in equivalent
-to \class{MutableString}).}
-
-This module defines a class that acts as a wrapper around string
-objects. It is a useful base class for your own string-like classes,
-which can inherit from them and override existing methods or add new
-ones. In this way one can add new behaviors to strings.
-
-It should be noted that these classes are highly inefficient compared
-to real string or Unicode objects; this is especially the case for
-\class{MutableString}.
-
-The \module{UserString} module defines the following classes:
-
-\begin{classdesc}{UserString}{\optional{sequence}}
-Class that simulates a string or a Unicode string
-object. The instance's content is kept in a regular string or Unicode
-string object, which is accessible via the \member{data} attribute of
-\class{UserString} instances. The instance's contents are initially
-set to a copy of \var{sequence}. \var{sequence} can be either a
-regular Python string or Unicode string, an instance of
-\class{UserString} (or a subclass) or an arbitrary sequence which can
-be converted into a string using the built-in \function{str()} function.
-\end{classdesc}
-
-\begin{classdesc}{MutableString}{\optional{sequence}}
-This class is derived from the \class{UserString} above and redefines
-strings to be \emph{mutable}. Mutable strings can't be used as
-dictionary keys, because dictionaries require \emph{immutable} objects as
-keys. The main intention of this class is to serve as an educational
-example for inheritance and necessity to remove (override) the
-\method{__hash__()} method in order to trap attempts to use a
-mutable object as dictionary key, which would be otherwise very
-error prone and hard to track down.
-\end{classdesc}
-
-In addition to supporting the methods and operations of string and
-Unicode objects (see section \ref{string-methods}, ``String
-Methods''), \class{UserString} instances provide the following
-attribute:
-
-\begin{memberdesc}{data}
-A real Python string or Unicode object used to store the content of the
-\class{UserString} class.
-\end{memberdesc}
diff --git a/Doc/lib/libuu.tex b/Doc/lib/libuu.tex
deleted file mode 100644
index 7e546a0..0000000
--- a/Doc/lib/libuu.tex
+++ /dev/null
@@ -1,58 +0,0 @@
-\section{\module{uu} ---
- Encode and decode uuencode files}
-
-\declaremodule{standard}{uu}
-\modulesynopsis{Encode and decode files in uuencode format.}
-\moduleauthor{Lance Ellinghouse}{}
-
-
-This module encodes and decodes files in uuencode format, allowing
-arbitrary binary data to be transferred over ASCII-only connections.
-Wherever a file argument is expected, the methods accept a file-like
-object. For backwards compatibility, a string containing a pathname
-is also accepted, and the corresponding file will be opened for
-reading and writing; the pathname \code{'-'} is understood to mean the
-standard input or output. However, this interface is deprecated; it's
-better for the caller to open the file itself, and be sure that, when
-required, the mode is \code{'rb'} or \code{'wb'} on Windows.
-
-This code was contributed by Lance Ellinghouse, and modified by Jack
-Jansen.
-\index{Jansen, Jack}
-\index{Ellinghouse, Lance}
-
-The \module{uu} module defines the following functions:
-
-\begin{funcdesc}{encode}{in_file, out_file\optional{, name\optional{, mode}}}
- Uuencode file \var{in_file} into file \var{out_file}. The uuencoded
- file will have the header specifying \var{name} and \var{mode} as
- the defaults for the results of decoding the file. The default
- defaults are taken from \var{in_file}, or \code{'-'} and \code{0666}
- respectively.
-\end{funcdesc}
-
-\begin{funcdesc}{decode}{in_file\optional{, out_file\optional{, mode\optional{, quiet}}}}
- This call decodes uuencoded file \var{in_file} placing the result on
- file \var{out_file}. If \var{out_file} is a pathname, \var{mode} is
- used to set the permission bits if the file must be
- created. Defaults for \var{out_file} and \var{mode} are taken from
- the uuencode header. However, if the file specified in the header
- already exists, a \exception{uu.Error} is raised.
-
- \function{decode()} may print a warning to standard error if the
- input was produced by an incorrect uuencoder and Python could
- recover from that error. Setting \var{quiet} to a true value
- silences this warning.
-\end{funcdesc}
-
-\begin{excclassdesc}{Error}{}
- Subclass of \exception{Exception}, this can be raised by
- \function{uu.decode()} under various situations, such as described
- above, but also including a badly formatted header, or truncated
- input file.
-\end{excclassdesc}
-
-\begin{seealso}
- \seemodule{binascii}{Support module containing \ASCII-to-binary
- and binary-to-\ASCII{} conversions.}
-\end{seealso}
diff --git a/Doc/lib/libuuid.tex b/Doc/lib/libuuid.tex
deleted file mode 100644
index 5aa9d8c..0000000
--- a/Doc/lib/libuuid.tex
+++ /dev/null
@@ -1,233 +0,0 @@
-\section{\module{uuid} ---
- UUID objects according to RFC 4122}
-\declaremodule{builtin}{uuid}
-\modulesynopsis{UUID objects (universally unique identifiers) according to RFC 4122}
-\moduleauthor{Ka-Ping Yee}{ping@zesty.ca}
-\sectionauthor{George Yoshida}{quiver@users.sourceforge.net}
-
-\versionadded{2.5}
-
-This module provides immutable \class{UUID} objects (the \class{UUID} class)
-and the functions \function{uuid1()}, \function{uuid3()},
-\function{uuid4()}, \function{uuid5()} for generating version 1, 3, 4,
-and 5 UUIDs as specified in \rfc{4122}.
-
-If all you want is a unique ID, you should probably call
-\function{uuid1()} or \function{uuid4()}. Note that \function{uuid1()}
-may compromise privacy since it creates a UUID containing the computer's
-network address. \function{uuid4()} creates a random UUID.
-
-\begin{classdesc}{UUID}{\optional{hex\optional{, bytes\optional{,
-bytes_le\optional{, fields\optional{, int\optional{, version}}}}}}}
-
-Create a UUID from either a string of 32 hexadecimal digits,
-a string of 16 bytes as the \var{bytes} argument, a string of 16 bytes
-in little-endian order as the \var{bytes_le} argument, a tuple of six
-integers (32-bit \var{time_low}, 16-bit \var{time_mid},
-16-bit \var{time_hi_version},
-8-bit \var{clock_seq_hi_variant}, 8-bit \var{clock_seq_low}, 48-bit \var{node})
-as the \var{fields} argument, or a single 128-bit integer as the \var{int}
-argument. When a string of hex digits is given, curly braces,
-hyphens, and a URN prefix are all optional. For example, these
-expressions all yield the same UUID:
-
-\begin{verbatim}
-UUID('{12345678-1234-5678-1234-567812345678}')
-UUID('12345678123456781234567812345678')
-UUID('urn:uuid:12345678-1234-5678-1234-567812345678')
-UUID(bytes='\x12\x34\x56\x78'*4)
-UUID(bytes_le='\x78\x56\x34\x12\x34\x12\x78\x56' +
- '\x12\x34\x56\x78\x12\x34\x56\x78')
-UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678))
-UUID(int=0x12345678123456781234567812345678)
-\end{verbatim}
-
-Exactly one of \var{hex}, \var{bytes}, \var{bytes_le}, \var{fields},
-or \var{int} must
-be given. The \var{version} argument is optional; if given, the
-resulting UUID will have its variant and version number set according to
-RFC 4122, overriding bits in the given \var{hex}, \var{bytes},
-\var{bytes_le}, \var{fields}, or \var{int}.
-
-\end{classdesc}
-
-\class{UUID} instances have these read-only attributes:
-
-\begin{memberdesc}{bytes}
-The UUID as a 16-byte string (containing the six
-integer fields in big-endian byte order).
-\end{memberdesc}
-
-\begin{memberdesc}{bytes_le}
-The UUID as a 16-byte string (with \var{time_low}, \var{time_mid},
-and \var{time_hi_version} in little-endian byte order).
-\end{memberdesc}
-
-\begin{memberdesc}{fields}
-A tuple of the six integer fields of the UUID, which are also available
-as six individual attributes and two derived attributes:
-
-\begin{tableii}{l|l}{member}{Field}{Meaning}
- \lineii{time_low}{the first 32 bits of the UUID}
- \lineii{time_mid}{the next 16 bits of the UUID}
- \lineii{time_hi_version}{the next 16 bits of the UUID}
- \lineii{clock_seq_hi_variant}{the next 8 bits of the UUID}
- \lineii{clock_seq_low}{the next 8 bits of the UUID}
- \lineii{node}{the last 48 bits of the UUID}
- \lineii{time}{the 60-bit timestamp}
- \lineii{clock_seq}{the 14-bit sequence number}
-\end{tableii}
-
-
-\end{memberdesc}
-
-\begin{memberdesc}{hex}
-The UUID as a 32-character hexadecimal string.
-\end{memberdesc}
-
-\begin{memberdesc}{int}
-The UUID as a 128-bit integer.
-\end{memberdesc}
-
-\begin{memberdesc}{urn}
-The UUID as a URN as specified in RFC 4122.
-\end{memberdesc}
-
-\begin{memberdesc}{variant}
-The UUID variant, which determines the internal layout of the UUID.
-This will be one of the integer constants
-\constant{RESERVED_NCS},
-\constant{RFC_4122}, \constant{RESERVED_MICROSOFT}, or
-\constant{RESERVED_FUTURE}.
-\end{memberdesc}
-
-\begin{memberdesc}{version}
-The UUID version number (1 through 5, meaningful only
-when the variant is \constant{RFC_4122}).
-\end{memberdesc}
-
-The \module{uuid} module defines the following functions:
-
-\begin{funcdesc}{getnode}{}
-Get the hardware address as a 48-bit positive integer. The first time this
-runs, it may launch a separate program, which could be quite slow. If all
-attempts to obtain the hardware address fail, we choose a random 48-bit
-number with its eighth bit set to 1 as recommended in RFC 4122. "Hardware
-address" means the MAC address of a network interface, and on a machine
-with multiple network interfaces the MAC address of any one of them may
-be returned.
-\end{funcdesc}
-\index{getnode}
-
-\begin{funcdesc}{uuid1}{\optional{node\optional{, clock_seq}}}
-Generate a UUID from a host ID, sequence number, and the current time.
-If \var{node} is not given, \function{getnode()} is used to obtain the
-hardware address.
-If \var{clock_seq} is given, it is used as the sequence number;
-otherwise a random 14-bit sequence number is chosen.
-\end{funcdesc}
-\index{uuid1}
-
-\begin{funcdesc}{uuid3}{namespace, name}
-Generate a UUID based on the MD5 hash
-of a namespace identifier (which is a UUID) and a name (which is a string).
-\end{funcdesc}
-\index{uuid3}
-
-\begin{funcdesc}{uuid4}{}
-Generate a random UUID.
-\end{funcdesc}
-\index{uuid4}
-
-\begin{funcdesc}{uuid5}{namespace, name}
-Generate a UUID based on the SHA-1 hash
-of a namespace identifier (which is a UUID) and a name (which is a string).
-\end{funcdesc}
-\index{uuid5}
-
-The \module{uuid} module defines the following namespace identifiers
-for use with \function{uuid3()} or \function{uuid5()}.
-
-\begin{datadesc}{NAMESPACE_DNS}
-When this namespace is specified,
-the \var{name} string is a fully-qualified domain name.
-\end{datadesc}
-
-\begin{datadesc}{NAMESPACE_URL}
-When this namespace is specified,
-the \var{name} string is a URL.
-\end{datadesc}
-
-\begin{datadesc}{NAMESPACE_OID}
-When this namespace is specified,
-the \var{name} string is an ISO OID.
-\end{datadesc}
-
-\begin{datadesc}{NAMESPACE_X500}
-When this namespace is specified,
-the \var{name} string is an X.500 DN in DER or a text output format.
-\end{datadesc}
-
-The \module{uuid} module defines the following constants
-for the possible values of the \member{variant} attribute:
-
-\begin{datadesc}{RESERVED_NCS}
-Reserved for NCS compatibility.
-\end{datadesc}
-
-\begin{datadesc}{RFC_4122}
-Specifies the UUID layout given in \rfc{4122}.
-\end{datadesc}
-
-\begin{datadesc}{RESERVED_MICROSOFT}
-Reserved for Microsoft compatibility.
-\end{datadesc}
-
-\begin{datadesc}{RESERVED_FUTURE}
-Reserved for future definition.
-\end{datadesc}
-
-
-\begin{seealso}
- \seerfc{4122}{A Universally Unique IDentifier (UUID) URN Namespace}{
-This specification defines a Uniform Resource Name namespace for UUIDs,
-the internal format of UUIDs, and methods of generating UUIDs.}
-\end{seealso}
-
-\subsection{Example \label{uuid-example}}
-
-Here are some examples of typical usage of the \module{uuid} module:
-\begin{verbatim}
->>> import uuid
-
-# make a UUID based on the host ID and current time
->>> uuid.uuid1()
-UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')
-
-# make a UUID using an MD5 hash of a namespace UUID and a name
->>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
-UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')
-
-# make a random UUID
->>> uuid.uuid4()
-UUID('16fd2706-8baf-433b-82eb-8c7fada847da')
-
-# make a UUID using a SHA-1 hash of a namespace UUID and a name
->>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
-UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')
-
-# make a UUID from a string of hex digits (braces and hyphens ignored)
->>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')
-
-# convert a UUID to a string of hex digits in standard form
->>> str(x)
-'00010203-0405-0607-0809-0a0b0c0d0e0f'
-
-# get the raw 16 bytes of the UUID
->>> x.bytes
-'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'
-
-# make a UUID from a 16-byte string
->>> uuid.UUID(bytes=x.bytes)
-UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')
-\end{verbatim}
diff --git a/Doc/lib/libwarnings.tex b/Doc/lib/libwarnings.tex
deleted file mode 100644
index a37a9f5..0000000
--- a/Doc/lib/libwarnings.tex
+++ /dev/null
@@ -1,253 +0,0 @@
-\section{\module{warnings} ---
- Warning control}
-
-\declaremodule{standard}{warnings}
-\modulesynopsis{Issue warning messages and control their disposition.}
-\index{warnings}
-
-\versionadded{2.1}
-
-Warning messages are typically issued in situations where it is useful
-to alert the user of some condition in a program, where that condition
-(normally) doesn't warrant raising an exception and terminating the
-program. For example, one might want to issue a warning when a
-program uses an obsolete module.
-
-Python programmers issue warnings by calling the \function{warn()}
-function defined in this module. (C programmers use
-\cfunction{PyErr_Warn()}; see the
-\citetitle[../api/exceptionHandling.html]{Python/C API Reference
-Manual} for details).
-
-Warning messages are normally written to \code{sys.stderr}, but their
-disposition can be changed flexibly, from ignoring all warnings to
-turning them into exceptions. The disposition of warnings can vary
-based on the warning category (see below), the text of the warning
-message, and the source location where it is issued. Repetitions of a
-particular warning for the same source location are typically
-suppressed.
-
-There are two stages in warning control: first, each time a warning is
-issued, a determination is made whether a message should be issued or
-not; next, if a message is to be issued, it is formatted and printed
-using a user-settable hook.
-
-The determination whether to issue a warning message is controlled by
-the warning filter, which is a sequence of matching rules and actions.
-Rules can be added to the filter by calling
-\function{filterwarnings()} and reset to its default state by calling
-\function{resetwarnings()}.
-
-The printing of warning messages is done by calling
-\function{showwarning()}, which may be overridden; the default
-implementation of this function formats the message by calling
-\function{formatwarning()}, which is also available for use by custom
-implementations.
-
-
-\subsection{Warning Categories \label{warning-categories}}
-
-There are a number of built-in exceptions that represent warning
-categories. This categorization is useful to be able to filter out
-groups of warnings. The following warnings category classes are
-currently defined:
-
-\begin{tableii}{l|l}{exception}{Class}{Description}
-
-\lineii{Warning}{This is the base class of all warning category
-classes. It is a subclass of \exception{Exception}.}
-
-\lineii{UserWarning}{The default category for \function{warn()}.}
-
-\lineii{DeprecationWarning}{Base category for warnings about
-deprecated features.}
-
-\lineii{SyntaxWarning}{Base category for warnings about dubious
-syntactic features.}
-
-\lineii{RuntimeWarning}{Base category for warnings about dubious
-runtime features.}
-
-\lineii{FutureWarning}{Base category for warnings about constructs
-that will change semantically in the future.}
-
-\lineii{PendingDeprecationWarning}{Base category for warnings about
-features that will be deprecated in the future (ignored by default).}
-
-\lineii{ImportWarning}{Base category for warnings triggered during the
-process of importing a module (ignored by default).}
-
-\lineii{UnicodeWarning}{Base category for warnings related to Unicode.}
-
-\end{tableii}
-
-While these are technically built-in exceptions, they are documented
-here, because conceptually they belong to the warnings mechanism.
-
-User code can define additional warning categories by subclassing one
-of the standard warning categories. A warning category must always be
-a subclass of the \exception{Warning} class.
-
-
-\subsection{The Warnings Filter \label{warning-filter}}
-
-The warnings filter controls whether warnings are ignored, displayed,
-or turned into errors (raising an exception).
-
-Conceptually, the warnings filter maintains an ordered list of filter
-specifications; any specific warning is matched against each filter
-specification in the list in turn until a match is found; the match
-determines the disposition of the match. Each entry is a tuple of the
-form (\var{action}, \var{message}, \var{category}, \var{module},
-\var{lineno}), where:
-
-\begin{itemize}
-
-\item \var{action} is one of the following strings:
-
- \begin{tableii}{l|l}{code}{Value}{Disposition}
-
- \lineii{"error"}{turn matching warnings into exceptions}
-
- \lineii{"ignore"}{never print matching warnings}
-
- \lineii{"always"}{always print matching warnings}
-
- \lineii{"default"}{print the first occurrence of matching
- warnings for each location where the warning is issued}
-
- \lineii{"module"}{print the first occurrence of matching
- warnings for each module where the warning is issued}
-
- \lineii{"once"}{print only the first occurrence of matching
- warnings, regardless of location}
-
- \end{tableii}
-
-\item \var{message} is a string containing a regular expression that
-the warning message must match (the match is compiled to always be
-case-insensitive)
-
-\item \var{category} is a class (a subclass of \exception{Warning}) of
- which the warning category must be a subclass in order to match
-
-\item \var{module} is a string containing a regular expression that the module
- name must match (the match is compiled to be case-sensitive)
-
-\item \var{lineno} is an integer that the line number where the
- warning occurred must match, or \code{0} to match all line
- numbers
-
-\end{itemize}
-
-Since the \exception{Warning} class is derived from the built-in
-\exception{Exception} class, to turn a warning into an error we simply
-raise \code{category(message)}.
-
-The warnings filter is initialized by \programopt{-W} options passed
-to the Python interpreter command line. The interpreter saves the
-arguments for all \programopt{-W} options without interpretation in
-\code{sys.warnoptions}; the \module{warnings} module parses these when
-it is first imported (invalid options are ignored, after printing a
-message to \code{sys.stderr}).
-
-The warnings that are ignored by default may be enabled by passing
- \programopt{-Wd} to the interpreter. This enables default handling
-for all warnings, including those that are normally ignored by
-default. This is particular useful for enabling ImportWarning when
-debugging problems importing a developed package. ImportWarning can
-also be enabled explicitly in Python code using:
-
-\begin{verbatim}
- warnings.simplefilter('default', ImportWarning)
-\end{verbatim}
-
-
-\subsection{Available Functions \label{warning-functions}}
-
-\begin{funcdesc}{warn}{message\optional{, category\optional{, stacklevel}}}
-Issue a warning, or maybe ignore it or raise an exception. The
-\var{category} argument, if given, must be a warning category class
-(see above); it defaults to \exception{UserWarning}. Alternatively
-\var{message} can be a \exception{Warning} instance, in which case
-\var{category} will be ignored and \code{message.__class__} will be used.
-In this case the message text will be \code{str(message)}. This function
-raises an exception if the particular warning issued is changed
-into an error by the warnings filter see above. The \var{stacklevel}
-argument can be used by wrapper functions written in Python, like
-this:
-
-\begin{verbatim}
-def deprecation(message):
- warnings.warn(message, DeprecationWarning, stacklevel=2)
-\end{verbatim}
-
-This makes the warning refer to \function{deprecation()}'s caller,
-rather than to the source of \function{deprecation()} itself (since
-the latter would defeat the purpose of the warning message).
-\end{funcdesc}
-
-\begin{funcdesc}{warn_explicit}{message, category, filename,
- lineno\optional{, module\optional{, registry\optional{,
- module_globals}}}}
-This is a low-level interface to the functionality of
-\function{warn()}, passing in explicitly the message, category,
-filename and line number, and optionally the module name and the
-registry (which should be the \code{__warningregistry__} dictionary of
-the module). The module name defaults to the filename with \code{.py}
-stripped; if no registry is passed, the warning is never suppressed.
-\var{message} must be a string and \var{category} a subclass of
-\exception{Warning} or \var{message} may be a \exception{Warning} instance,
-in which case \var{category} will be ignored.
-
-\var{module_globals}, if supplied, should be the global namespace in use
-by the code for which the warning is issued. (This argument is used to
-support displaying source for modules found in zipfiles or other
-non-filesystem import sources, and was added in Python 2.5.)
-\end{funcdesc}
-
-\begin{funcdesc}{showwarning}{message, category, filename,
- lineno\optional{, file}}
-Write a warning to a file. The default implementation calls
-\code{formatwarning(\var{message}, \var{category}, \var{filename},
-\var{lineno})} and writes the resulting string to \var{file}, which
-defaults to \code{sys.stderr}. You may replace this function with an
-alternative implementation by assigning to
-\code{warnings.showwarning}.
-\end{funcdesc}
-
-\begin{funcdesc}{formatwarning}{message, category, filename, lineno}
-Format a warning the standard way. This returns a string which may
-contain embedded newlines and ends in a newline.
-\end{funcdesc}
-
-\begin{funcdesc}{filterwarnings}{action\optional{,
- message\optional{, category\optional{,
- module\optional{, lineno\optional{, append}}}}}}
-Insert an entry into the list of warnings filters. The entry is
-inserted at the front by default; if \var{append} is true, it is
-inserted at the end.
-This checks the types of the arguments, compiles the message and
-module regular expressions, and inserts them as a tuple in the
-list of warnings filters. Entries closer to the front of the list
-override entries later in the list, if both match a particular
-warning. Omitted arguments default to a value that matches
-everything.
-\end{funcdesc}
-
-\begin{funcdesc}{simplefilter}{action\optional{,
- category\optional{,
- lineno\optional{, append}}}}
-Insert a simple entry into the list of warnings filters. The meaning
-of the function parameters is as for \function{filterwarnings()}, but
-regular expressions are not needed as the filter inserted always
-matches any message in any module as long as the category and line
-number match.
-\end{funcdesc}
-
-\begin{funcdesc}{resetwarnings}{}
-Reset the warnings filter. This discards the effect of all previous
-calls to \function{filterwarnings()}, including that of the
-\programopt{-W} command line options and calls to
-\function{simplefilter()}.
-\end{funcdesc}
diff --git a/Doc/lib/libwave.tex b/Doc/lib/libwave.tex
deleted file mode 100644
index 936bbed..0000000
--- a/Doc/lib/libwave.tex
+++ /dev/null
@@ -1,171 +0,0 @@
-% Documentations stolen and LaTeX'ed from comments in file.
-\section{\module{wave} ---
- Read and write WAV files}
-
-\declaremodule{standard}{wave}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Provide an interface to the WAV sound format.}
-
-The \module{wave} module provides a convenient interface to the WAV sound
-format. It does not support compression/decompression, but it does support
-mono/stereo.
-
-The \module{wave} module defines the following function and exception:
-
-\begin{funcdesc}{open}{file\optional{, mode}}
-If \var{file} is a string, open the file by that name, other treat it
-as a seekable file-like object. \var{mode} can be any of
-\begin{description}
- \item[\code{'r'}, \code{'rb'}] Read only mode.
- \item[\code{'w'}, \code{'wb'}] Write only mode.
-\end{description}
-Note that it does not allow read/write WAV files.
-
-A \var{mode} of \code{'r'} or \code{'rb'} returns a \class{Wave_read}
-object, while a \var{mode} of \code{'w'} or \code{'wb'} returns
-a \class{Wave_write} object. If \var{mode} is omitted and a file-like
-object is passed as \var{file}, \code{\var{file}.mode} is used as the
-default value for \var{mode} (the \character{b} flag is still added if
-necessary).
-\end{funcdesc}
-
-\begin{funcdesc}{openfp}{file, mode}
-A synonym for \function{open()}, maintained for backwards compatibility.
-\end{funcdesc}
-
-\begin{excdesc}{Error}
-An error raised when something is impossible because it violates the
-WAV specification or hits an implementation deficiency.
-\end{excdesc}
-
-
-\subsection{Wave_read Objects \label{Wave-read-objects}}
-
-Wave_read objects, as returned by \function{open()}, have the
-following methods:
-
-\begin{methoddesc}[Wave_read]{close}{}
-Close the stream, and make the instance unusable. This is
-called automatically on object collection.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getnchannels}{}
-Returns number of audio channels (\code{1} for mono, \code{2} for
-stereo).
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getsampwidth}{}
-Returns sample width in bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getframerate}{}
-Returns sampling frequency.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getnframes}{}
-Returns number of audio frames.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getcomptype}{}
-Returns compression type (\code{'NONE'} is the only supported type).
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getcompname}{}
-Human-readable version of \method{getcomptype()}.
-Usually \code{'not compressed'} parallels \code{'NONE'}.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getparams}{}
-Returns a tuple
-\code{(\var{nchannels}, \var{sampwidth}, \var{framerate},
-\var{nframes}, \var{comptype}, \var{compname})}, equivalent to output
-of the \method{get*()} methods.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{readframes}{n}
-Reads and returns at most \var{n} frames of audio, as a string of bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{rewind}{}
-Rewind the file pointer to the beginning of the audio stream.
-\end{methoddesc}
-
-The following two methods are defined for compatibility with the
-\refmodule{aifc} module, and don't do anything interesting.
-
-\begin{methoddesc}[Wave_read]{getmarkers}{}
-Returns \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getmark}{id}
-Raise an error.
-\end{methoddesc}
-
-The following two methods define a term ``position'' which is compatible
-between them, and is otherwise implementation dependent.
-
-\begin{methoddesc}[Wave_read]{setpos}{pos}
-Set the file pointer to the specified position.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{tell}{}
-Return current file pointer position.
-\end{methoddesc}
-
-
-\subsection{Wave_write Objects \label{Wave-write-objects}}
-
-Wave_write objects, as returned by \function{open()}, have the
-following methods:
-
-\begin{methoddesc}[Wave_write]{close}{}
-Make sure \var{nframes} is correct, and close the file.
-This method is called upon deletion.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{setnchannels}{n}
-Set the number of channels.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{setsampwidth}{n}
-Set the sample width to \var{n} bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{setframerate}{n}
-Set the frame rate to \var{n}.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{setnframes}{n}
-Set the number of frames to \var{n}. This will be changed later if
-more frames are written.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{setcomptype}{type, name}
-Set the compression type and description.
-At the moment, only compression type \samp{NONE} is supported,
-meaning no compression.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{setparams}{tuple}
-The \var{tuple} should be \code{(\var{nchannels}, \var{sampwidth},
-\var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}, with
-values valid for the \method{set*()} methods. Sets all parameters.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{tell}{}
-Return current position in the file, with the same disclaimer for
-the \method{Wave_read.tell()} and \method{Wave_read.setpos()}
-methods.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{writeframesraw}{data}
-Write audio frames, without correcting \var{nframes}.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{writeframes}{data}
-Write audio frames and make sure \var{nframes} is correct.
-\end{methoddesc}
-
-Note that it is invalid to set any parameters after calling
-\method{writeframes()} or \method{writeframesraw()}, and any attempt
-to do so will raise \exception{wave.Error}.
diff --git a/Doc/lib/libweakref.tex b/Doc/lib/libweakref.tex
deleted file mode 100644
index 6f676a2..0000000
--- a/Doc/lib/libweakref.tex
+++ /dev/null
@@ -1,336 +0,0 @@
-\section{\module{weakref} ---
- Weak references}
-
-\declaremodule{extension}{weakref}
-\modulesynopsis{Support for weak references and weak dictionaries.}
-\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\moduleauthor{Neil Schemenauer}{nas@arctrix.com}
-\moduleauthor{Martin von L\"owis}{martin@loewis.home.cs.tu-berlin.de}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-\versionadded{2.1}
-
-% When making changes to the examples in this file, be sure to update
-% Lib/test/test_weakref.py::libreftest too!
-
-The \module{weakref} module allows the Python programmer to create
-\dfn{weak references} to objects.
-
-In the following, the term \dfn{referent} means the
-object which is referred to by a weak reference.
-
-A weak reference to an object is not enough to keep the object alive:
-when the only remaining references to a referent are weak references,
-garbage collection is free to destroy the referent and reuse its memory
-for something else. A primary use for weak references is to implement
-caches or mappings holding large objects, where it's desired that a
-large object not be kept alive solely because it appears in a cache or
-mapping. For example, if you have a number of large binary image objects,
-you may wish to associate a name with each. If you used a Python
-dictionary to map names to images, or images to names, the image objects
-would remain alive just because they appeared as values or keys in the
-dictionaries. The \class{WeakKeyDictionary} and
-\class{WeakValueDictionary} classes supplied by the \module{weakref}
-module are an alternative, using weak references to construct mappings
-that don't keep objects alive solely because they appear in the mapping
-objects. If, for example, an image object is a value in a
-\class{WeakValueDictionary}, then when the last remaining
-references to that image object are the weak references held by weak
-mappings, garbage collection can reclaim the object, and its corresponding
-entries in weak mappings are simply deleted.
-
-\class{WeakKeyDictionary} and \class{WeakValueDictionary} use weak
-references in their implementation, setting up callback functions on
-the weak references that notify the weak dictionaries when a key or value
-has been reclaimed by garbage collection. Most programs should find that
-using one of these weak dictionary types is all they need -- it's
-not usually necessary to create your own weak references directly. The
-low-level machinery used by the weak dictionary implementations is exposed
-by the \module{weakref} module for the benefit of advanced uses.
-
-Not all objects can be weakly referenced; those objects which can
-include class instances, functions written in Python (but not in C),
-methods (both bound and unbound), sets, frozensets, file objects,
-generators, type objects, DBcursor objects from the \module{bsddb} module,
-sockets, arrays, deques, and regular expression pattern objects.
-\versionchanged[Added support for files, sockets, arrays, and patterns]{2.4}
-
-Several builtin types such as \class{list} and \class{dict} do not
-directly support weak references but can add support through subclassing:
-
-\begin{verbatim}
-class Dict(dict):
- pass
-
-obj = Dict(red=1, green=2, blue=3) # this object is weak referencable
-\end{verbatim}
-
-Extension types can easily be made to support weak references; see
-``\ulink{Weak Reference Support}{../ext/weakref-support.html}'' in
-\citetitle[../ext/ext.html]{Extending and Embedding the Python
-Interpreter}.
-% The referenced section used to appear in this document with the
-% \label weakref-extension. It would be good to be able to generate a
-% redirect for the corresponding HTML page (weakref-extension.html)
-% for on-line versions of this document.
-
-\begin{classdesc}{ref}{object\optional{, callback}}
- Return a weak reference to \var{object}. The original object can be
- retrieved by calling the reference object if the referent is still
- alive; if the referent is no longer alive, calling the reference
- object will cause \constant{None} to be returned. If \var{callback} is
- provided and not \constant{None}, and the returned weakref object is
- still alive, the callback will be called when the object is about to be
- finalized; the weak reference object will be passed as the only
- parameter to the callback; the referent will no longer be available.
-
- It is allowable for many weak references to be constructed for the
- same object. Callbacks registered for each weak reference will be
- called from the most recently registered callback to the oldest
- registered callback.
-
- Exceptions raised by the callback will be noted on the standard
- error output, but cannot be propagated; they are handled in exactly
- the same way as exceptions raised from an object's
- \method{__del__()} method.
-
- Weak references are hashable if the \var{object} is hashable. They
- will maintain their hash value even after the \var{object} was
- deleted. If \function{hash()} is called the first time only after
- the \var{object} was deleted, the call will raise
- \exception{TypeError}.
-
- Weak references support tests for equality, but not ordering. If
- the referents are still alive, two references have the same
- equality relationship as their referents (regardless of the
- \var{callback}). If either referent has been deleted, the
- references are equal only if the reference objects are the same
- object.
-
- \versionchanged[This is now a subclassable type rather than a
- factory function; it derives from \class{object}]
- {2.4}
-\end{classdesc}
-
-\begin{funcdesc}{proxy}{object\optional{, callback}}
- Return a proxy to \var{object} which uses a weak reference. This
- supports use of the proxy in most contexts instead of requiring the
- explicit dereferencing used with weak reference objects. The
- returned object will have a type of either \code{ProxyType} or
- \code{CallableProxyType}, depending on whether \var{object} is
- callable. Proxy objects are not hashable regardless of the
- referent; this avoids a number of problems related to their
- fundamentally mutable nature, and prevent their use as dictionary
- keys. \var{callback} is the same as the parameter of the same name
- to the \function{ref()} function.
-\end{funcdesc}
-
-\begin{funcdesc}{getweakrefcount}{object}
- Return the number of weak references and proxies which refer to
- \var{object}.
-\end{funcdesc}
-
-\begin{funcdesc}{getweakrefs}{object}
- Return a list of all weak reference and proxy objects which refer to
- \var{object}.
-\end{funcdesc}
-
-\begin{classdesc}{WeakKeyDictionary}{\optional{dict}}
- Mapping class that references keys weakly. Entries in the
- dictionary will be discarded when there is no longer a strong
- reference to the key. This can be used to associate additional data
- with an object owned by other parts of an application without adding
- attributes to those objects. This can be especially useful with
- objects that override attribute accesses.
-
- \note{Caution: Because a \class{WeakKeyDictionary} is built on top
- of a Python dictionary, it must not change size when iterating
- over it. This can be difficult to ensure for a
- \class{WeakKeyDictionary} because actions performed by the
- program during iteration may cause items in the dictionary
- to vanish "by magic" (as a side effect of garbage collection).}
-\end{classdesc}
-
-\class{WeakKeyDictionary} objects have the following additional
-methods. These expose the internal references directly. The
-references are not guaranteed to be ``live'' at the time they are
-used, so the result of calling the references needs to be checked
-before being used. This can be used to avoid creating references that
-will cause the garbage collector to keep the keys around longer than
-needed.
-
-\begin{methoddesc}{iterkeyrefs}{}
- Return an iterator that yields the weak references to the keys.
- \versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{keyrefs}{}
- Return a list of weak references to the keys.
- \versionadded{2.5}
-\end{methoddesc}
-
-\begin{classdesc}{WeakValueDictionary}{\optional{dict}}
- Mapping class that references values weakly. Entries in the
- dictionary will be discarded when no strong reference to the value
- exists any more.
-
- \note{Caution: Because a \class{WeakValueDictionary} is built on top
- of a Python dictionary, it must not change size when iterating
- over it. This can be difficult to ensure for a
- \class{WeakValueDictionary} because actions performed by the
- program during iteration may cause items in the dictionary
- to vanish "by magic" (as a side effect of garbage collection).}
-\end{classdesc}
-
-\class{WeakValueDictionary} objects have the following additional
-methods. These method have the same issues as the
-\method{iterkeyrefs()} and \method{keyrefs()} methods of
-\class{WeakKeyDictionary} objects.
-
-\begin{methoddesc}{itervaluerefs}{}
- Return an iterator that yields the weak references to the values.
- \versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{valuerefs}{}
- Return a list of weak references to the values.
- \versionadded{2.5}
-\end{methoddesc}
-
-\begin{datadesc}{ReferenceType}
- The type object for weak references objects.
-\end{datadesc}
-
-\begin{datadesc}{ProxyType}
- The type object for proxies of objects which are not callable.
-\end{datadesc}
-
-\begin{datadesc}{CallableProxyType}
- The type object for proxies of callable objects.
-\end{datadesc}
-
-\begin{datadesc}{ProxyTypes}
- Sequence containing all the type objects for proxies. This can make
- it simpler to test if an object is a proxy without being dependent
- on naming both proxy types.
-\end{datadesc}
-
-\begin{excdesc}{ReferenceError}
- Exception raised when a proxy object is used but the underlying
- object has been collected. This is the same as the standard
- \exception{ReferenceError} exception.
-\end{excdesc}
-
-
-\begin{seealso}
- \seepep{0205}{Weak References}{The proposal and rationale for this
- feature, including links to earlier implementations
- and information about similar features in other
- languages.}
-\end{seealso}
-
-
-\subsection{Weak Reference Objects
- \label{weakref-objects}}
-
-Weak reference objects have no attributes or methods, but do allow the
-referent to be obtained, if it still exists, by calling it:
-
-\begin{verbatim}
->>> import weakref
->>> class Object:
-... pass
-...
->>> o = Object()
->>> r = weakref.ref(o)
->>> o2 = r()
->>> o is o2
-True
-\end{verbatim}
-
-If the referent no longer exists, calling the reference object returns
-\constant{None}:
-
-\begin{verbatim}
->>> del o, o2
->>> print r()
-None
-\end{verbatim}
-
-Testing that a weak reference object is still live should be done
-using the expression \code{\var{ref}() is not None}. Normally,
-application code that needs to use a reference object should follow
-this pattern:
-
-\begin{verbatim}
-# r is a weak reference object
-o = r()
-if o is None:
- # referent has been garbage collected
- print "Object has been deallocated; can't frobnicate."
-else:
- print "Object is still live!"
- o.do_something_useful()
-\end{verbatim}
-
-Using a separate test for ``liveness'' creates race conditions in
-threaded applications; another thread can cause a weak reference to
-become invalidated before the weak reference is called; the
-idiom shown above is safe in threaded applications as well as
-single-threaded applications.
-
-Specialized versions of \class{ref} objects can be created through
-subclassing. This is used in the implementation of the
-\class{WeakValueDictionary} to reduce the memory overhead for each
-entry in the mapping. This may be most useful to associate additional
-information with a reference, but could also be used to insert
-additional processing on calls to retrieve the referent.
-
-This example shows how a subclass of \class{ref} can be used to store
-additional information about an object and affect the value that's
-returned when the referent is accessed:
-
-\begin{verbatim}
-import weakref
-
-class ExtendedRef(weakref.ref):
- def __init__(self, ob, callback=None, **annotations):
- super(ExtendedRef, self).__init__(ob, callback)
- self.__counter = 0
- for k, v in annotations.iteritems():
- setattr(self, k, v)
-
- def __call__(self):
- """Return a pair containing the referent and the number of
- times the reference has been called.
- """
- ob = super(ExtendedRef, self).__call__()
- if ob is not None:
- self.__counter += 1
- ob = (ob, self.__counter)
- return ob
-\end{verbatim}
-
-
-\subsection{Example \label{weakref-example}}
-
-This simple example shows how an application can use objects IDs to
-retrieve objects that it has seen before. The IDs of the objects can
-then be used in other data structures without forcing the objects to
-remain alive, but the objects can still be retrieved by ID if they
-do.
-
-% Example contributed by Tim Peters.
-\begin{verbatim}
-import weakref
-
-_id2obj_dict = weakref.WeakValueDictionary()
-
-def remember(obj):
- oid = id(obj)
- _id2obj_dict[oid] = obj
- return oid
-
-def id2obj(oid):
- return _id2obj_dict[oid]
-\end{verbatim}
diff --git a/Doc/lib/libwebbrowser.tex b/Doc/lib/libwebbrowser.tex
deleted file mode 100644
index 5d5f236..0000000
--- a/Doc/lib/libwebbrowser.tex
+++ /dev/null
@@ -1,173 +0,0 @@
-\section{\module{webbrowser} ---
- Convenient Web-browser controller}
-
-\declaremodule{standard}{webbrowser}
-\modulesynopsis{Easy-to-use controller for Web browsers.}
-\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-The \module{webbrowser} module provides a high-level interface to
-allow displaying Web-based documents to users. Under most
-circumstances, simply calling the \function{open()} function from this
-module will do the right thing.
-
-Under \UNIX{}, graphical browsers are preferred under X11, but text-mode
-browsers will be used if graphical browsers are not available or an X11
-display isn't available. If text-mode browsers are used, the calling
-process will block until the user exits the browser.
-
-If the environment variable \envvar{BROWSER} exists, it
-is interpreted to override the platform default list of browsers, as a
-os.pathsep-separated list of browsers to try in order. When the value of
-a list part contains the string \code{\%s}, then it is
-interpreted as a literal browser command line to be used with the argument URL
-substituted for \code{\%s}; if the part does not contain
-\code{\%s}, it is simply interpreted as the name of the browser to
-launch.
-
-For non-\UNIX{} platforms, or when a remote browser is available on
-\UNIX{}, the controlling process will not wait for the user to finish
-with the browser, but allow the remote browser to maintain its own
-windows on the display. If remote browsers are not available on \UNIX{},
-the controlling process will launch a new browser and wait.
-
-The script \program{webbrowser} can be used as a command-line interface
-for the module. It accepts an URL as the argument. It accepts the following
-optional parameters: \programopt{-n} opens the URL in a new browser window,
-if possible; \programopt{-t} opens the URL in a new browser page ("tab"). The
-options are, naturally, mutually exclusive.
-
-The following exception is defined:
-
-\begin{excdesc}{Error}
- Exception raised when a browser control error occurs.
-\end{excdesc}
-
-The following functions are defined:
-
-\begin{funcdesc}{open}{url\optional{, new=0\optional{, autoraise=1}}}
- Display \var{url} using the default browser. If \var{new} is 0, the
- \var{url} is opened in the same browser window if possible. If \var{new} is 1,
- a new browser window is opened if possible. If \var{new} is 2,
- a new browser page ("tab") is opened if possible. If \var{autoraise} is
- true, the window is raised if possible (note that under many window
- managers this will occur regardless of the setting of this variable).
-\versionchanged[\var{new} can now be 2]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{open_new}{url}
- Open \var{url} in a new window of the default browser, if possible,
- otherwise, open \var{url} in the only browser window.
-\end{funcdesc}
-
-\begin{funcdesc}{open_new_tab}{url}
- Open \var{url} in a new page ("tab") of the default browser, if possible,
- otherwise equivalent to \function{open_new}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{get}{\optional{name}}
- Return a controller object for the browser type \var{name}. If
- \var{name} is empty, return a controller for a default browser
- appropriate to the caller's environment.
-\end{funcdesc}
-
-\begin{funcdesc}{register}{name, constructor\optional{, instance}}
- Register the browser type \var{name}. Once a browser type is
- registered, the \function{get()} function can return a controller
- for that browser type. If \var{instance} is not provided, or is
- \code{None}, \var{constructor} will be called without parameters to
- create an instance when needed. If \var{instance} is provided,
- \var{constructor} will never be called, and may be \code{None}.
-
- This entry point is only useful if you plan to either set the
- \envvar{BROWSER} variable or call \function{get} with a nonempty
- argument matching the name of a handler you declare.
-\end{funcdesc}
-
-A number of browser types are predefined. This table gives the type
-names that may be passed to the \function{get()} function and the
-corresponding instantiations for the controller classes, all defined
-in this module.
-
-\begin{tableiii}{l|l|c}{code}{Type Name}{Class Name}{Notes}
- \lineiii{'mozilla'}{\class{Mozilla('mozilla')}}{}
- \lineiii{'firefox'}{\class{Mozilla('mozilla')}}{}
- \lineiii{'netscape'}{\class{Mozilla('netscape')}}{}
- \lineiii{'galeon'}{\class{Galeon('galeon')}}{}
- \lineiii{'epiphany'}{\class{Galeon('epiphany')}}{}
- \lineiii{'skipstone'}{\class{BackgroundBrowser('skipstone')}}{}
- \lineiii{'kfmclient'}{\class{Konqueror()}}{(1)}
- \lineiii{'konqueror'}{\class{Konqueror()}}{(1)}
- \lineiii{'kfm'}{\class{Konqueror()}}{(1)}
- \lineiii{'mosaic'}{\class{BackgroundBrowser('mosaic')}}{}
- \lineiii{'opera'}{\class{Opera()}}{}
- \lineiii{'grail'}{\class{Grail()}}{}
- \lineiii{'links'}{\class{GenericBrowser('links')}}{}
- \lineiii{'elinks'}{\class{Elinks('elinks')}}{}
- \lineiii{'lynx'}{\class{GenericBrowser('lynx')}}{}
- \lineiii{'w3m'}{\class{GenericBrowser('w3m')}}{}
- \lineiii{'windows-default'}{\class{WindowsDefault}}{(2)}
- \lineiii{'internet-config'}{\class{InternetConfig}}{(3)}
- \lineiii{'macosx'}{\class{MacOSX('default')}}{(4)}
-\end{tableiii}
-
-\noindent
-Notes:
-
-\begin{description}
-\item[(1)]
-``Konqueror'' is the file manager for the KDE desktop environment for
-\UNIX{}, and only makes sense to use if KDE is running. Some way of
-reliably detecting KDE would be nice; the \envvar{KDEDIR} variable is
-not sufficient. Note also that the name ``kfm'' is used even when
-using the \program{konqueror} command with KDE 2 --- the
-implementation selects the best strategy for running Konqueror.
-
-\item[(2)]
-Only on Windows platforms.
-
-\item[(3)]
-Only on MacOS platforms; requires the standard MacPython \module{ic}
-module, described in the \citetitle[../mac/module-ic.html]{Macintosh
-Library Modules} manual.
-
-\item[(4)]
-Only on MacOS X platform.
-\end{description}
-
-Here are some simple examples:
-
-\begin{verbatim}
-url = 'http://www.python.org'
-
-# Open URL in a new tab, if a browser window is already open.
-webbrowser.open_new_tab(url + '/doc')
-
-# Open URL in new window, raising the window if possible.
-webbrowser.open_new(url)
-\end{verbatim}
-
-
-\subsection{Browser Controller Objects \label{browser-controllers}}
-
-Browser controllers provide two methods which parallel two of the
-module-level convenience functions:
-
-\begin{methoddesc}[controller]{open}{url\optional{, new\optional{, autoraise=1}}}
- Display \var{url} using the browser handled by this controller.
- If \var{new} is 1, a new browser window is opened if possible.
- If \var{new} is 2, a new browser page ("tab") is opened if possible.
-\end{methoddesc}
-
-\begin{methoddesc}[controller]{open_new}{url}
- Open \var{url} in a new window of the browser handled by this
- controller, if possible, otherwise, open \var{url} in the only
- browser window. Alias \function{open_new}.
-\end{methoddesc}
-
-\begin{methoddesc}[controller]{open_new_tab}{url}
- Open \var{url} in a new page ("tab") of the browser handled by this
- controller, if possible, otherwise equivalent to \function{open_new}.
-\versionadded{2.5}
-\end{methoddesc}
diff --git a/Doc/lib/libwhichdb.tex b/Doc/lib/libwhichdb.tex
deleted file mode 100644
index 92d37e7..0000000
--- a/Doc/lib/libwhichdb.tex
+++ /dev/null
@@ -1,20 +0,0 @@
-\section{\module{whichdb} ---
- Guess which DBM module created a database}
-
-\declaremodule{standard}{whichdb}
-\modulesynopsis{Guess which DBM-style module created a given database.}
-
-
-The single function in this module attempts to guess which of the
-several simple database modules available--\refmodule{dbm},
-\refmodule{gdbm}, or \refmodule{dbhash}--should be used to open a
-given file.
-
-\begin{funcdesc}{whichdb}{filename}
-Returns one of the following values: \code{None} if the file can't be
-opened because it's unreadable or doesn't exist; the empty string
-(\code{''}) if the file's format can't be guessed; or a string
-containing the required module name, such as \code{'dbm'} or
-\code{'gdbm'}.
-\end{funcdesc}
-
diff --git a/Doc/lib/libwinreg.tex b/Doc/lib/libwinreg.tex
deleted file mode 100644
index d31c3ca..0000000
--- a/Doc/lib/libwinreg.tex
+++ /dev/null
@@ -1,414 +0,0 @@
-\section{\module{_winreg} --
- Windows registry access}
-
-\declaremodule[-winreg]{extension}{_winreg}
- \platform{Windows}
-\modulesynopsis{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 \code{winreg}
-module will be created offering a higher-level interface to the
-registry API.
-
-This module offers the following functions:
-
-
-\begin{funcdesc}{CloseKey}{hkey}
- Closes a previously opened registry key.
- The hkey argument specifies a previously opened key.
-
- Note that if \var{hkey} is not closed using this method (or via
- \method{handle.Close()}), it is closed when the \var{hkey} object
- is destroyed by Python.
-\end{funcdesc}
-
-
-\begin{funcdesc}{ConnectRegistry}{computer_name, key}
- Establishes a connection to a predefined registry handle on
- another computer, and returns a \dfn{handle object}
-
- \var{computer_name} is the name of the remote computer, of the
- form \code{r"\e\e computername"}. If \code{None}, the local computer
- is used.
-
- \var{key} is the predefined handle to connect to.
-
- The return value is the handle of the opened key.
- If the function fails, an \exception{EnvironmentError} exception is
- raised.
-\end{funcdesc}
-
-
-\begin{funcdesc}{CreateKey}{key, sub_key}
- Creates or opens the specified key, returning a \dfn{handle object}
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- \var{sub_key} is a string that names the key this method opens
- or creates.
-
- If \var{key} is one of the predefined keys, \var{sub_key} may
- be \code{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 \exception{EnvironmentError} exception is
- raised.
-\end{funcdesc}
-
-\begin{funcdesc}{DeleteKey}{key, sub_key}
- Deletes the specified key.
-
- \var{key} is an already open key, or any one of the predefined
- \constant{HKEY_*} constants.
-
- \var{sub_key} is a string that must be a subkey of the key
- identified by the \var{key} parameter. This value must not be
- \code{None}, and the key may not have subkeys.
-
- \emph{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 \exception{EnvironmentError}
- exception is raised.
-\end{funcdesc}
-
-
-\begin{funcdesc}{DeleteValue}{key, value}
- Removes a named value from a registry key.
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- \var{value} is a string that identifies the value to remove.
-\end{funcdesc}
-
-
-\begin{funcdesc}{EnumKey}{key, index}
- Enumerates subkeys of an open registry key, returning a string.
-
- \var{key} is an already open key, or any one of the predefined
- \constant{HKEY_*} constants.
-
- \var{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
- \exception{EnvironmentError} exception
- is raised, indicating, no more values are available.
-\end{funcdesc}
-
-
-\begin{funcdesc}{EnumValue}{key, index}
- Enumerates values of an open registry key, returning a tuple.
-
- \var{key} is an already open key, or any one of the predefined
- \constant{HKEY_*} constants.
-
- \var{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
- \exception{EnvironmentError} exception is raised, indicating
- no more values.
-
- The result is a tuple of 3 items:
-
- \begin{tableii}{c|p{3in}}{code}{Index}{Meaning}
- \lineii{0}{A string that identifies the value name}
- \lineii{1}{An object that holds the value data, and whose
- type depends on the underlying registry type}
- \lineii{2}{An integer that identifies the type of the value data}
- \end{tableii}
-
-\end{funcdesc}
-
-
-\begin{funcdesc}{FlushKey}{key}
- Writes all the attributes of a key to the registry.
-
- \var{key} is an already open key, or one of the predefined
- \constant{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 \function{CloseKey()}, the \function{FlushKey()} method
- returns only when all the data has been written to the registry.
- An application should only call \function{FlushKey()} if it requires absolute
- certainty that registry changes are on disk.
-
- \note{If you don't know whether a \function{FlushKey()} call is required, it
- probably isn't.}
-
-\end{funcdesc}
-
-
-\begin{funcdesc}{RegLoadKey}{key, sub_key, file_name}
- Creates a subkey under the specified key and stores registration
- information from a specified file into that subkey.
-
- \var{key} is an already open key, or any of the predefined
- \constant{HKEY_*} constants.
-
- \var{sub_key} is a string that identifies the sub_key to load.
-
- \var {file_name} is the name of the file to load registry data from.
- This file must have been created with the \function{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
- \constant{SE_RESTORE_PRIVILEGE} privilege. Note that privileges
- are different than permissions - see the Win32 documentation for
- more details.
-
- If \var{key} is a handle returned by \function{ConnectRegistry()},
- then the path specified in \var{fileName} is relative to the
- remote computer.
-
- The Win32 documentation implies \var{key} must be in the
- \constant{HKEY_USER} or \constant{HKEY_LOCAL_MACHINE} tree.
- This may or may not be true.
-\end{funcdesc}
-
-
-\begin{funcdesc}{OpenKey}{key, sub_key\optional{, res\code{ = 0}}\optional{, sam\code{ = \constant{KEY_READ}}}}
- Opens the specified key, returning a \dfn{handle object}
-
- \var{key} is an already open key, or any one of the predefined
- \constant{HKEY_*} constants.
-
- \var{sub_key} is a string that identifies the sub_key to open.
-
- \var{res} is a reserved integer, and must be zero. The default is zero.
-
- \var{sam} is an integer that specifies an access mask that describes
- the desired security access for the key. Default is \constant{KEY_READ}
-
- The result is a new handle to the specified key.
-
- If the function fails, \exception{EnvironmentError} is raised.
-\end{funcdesc}
-
-
-\begin{funcdesc}{OpenKeyEx}{}
- The functionality of \function{OpenKeyEx()} is provided via
- \function{OpenKey()}, by the use of default arguments.
-\end{funcdesc}
-
-
-\begin{funcdesc}{QueryInfoKey}{key}
- Returns information about a key, as a tuple.
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- The result is a tuple of 3 items:
-
- \begin{tableii}{c|p{3in}}{code}{Index}{Meaning}
- \lineii{0}{An integer giving the number of sub keys this key has.}
- \lineii{1}{An integer giving the number of values this key has.}
- \lineii{2}{A long integer giving when the key was last modified (if
- available) as 100's of nanoseconds since Jan 1, 1600.}
- \end{tableii}
-\end{funcdesc}
-
-
-\begin{funcdesc}{QueryValue}{key, sub_key}
- Retrieves the unnamed value for a key, as a string
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- \var{sub_key} is a string that holds the name of the subkey with which
- the value is associated. If this parameter is \code{None} or empty, the
- function retrieves the value set by the \function{SetValue()} method
- for the key identified by \var{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!!!
-\end{funcdesc}
-
-
-\begin{funcdesc}{QueryValueEx}{key, value_name}
- Retrieves the type and data for a specified value name associated with
- an open registry key.
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- \var{value_name} is a string indicating the value to query.
-
- The result is a tuple of 2 items:
-
- \begin{tableii}{c|p{3in}}{code}{Index}{Meaning}
- \lineii{0}{The value of the registry item.}
- \lineii{1}{An integer giving the registry type for this value.}
- \end{tableii}
-\end{funcdesc}
-
-
-\begin{funcdesc}{SaveKey}{key, file_name}
- Saves the specified key, and all its subkeys to the specified file.
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- \var{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
- \method{LoadKey()}, \method{ReplaceKey()} or
- \method{RestoreKey()} methods.
-
- If \var{key} represents a key on a remote computer, the path
- described by \var{file_name} is relative to the remote computer.
- The caller of this method must possess the \constant{SeBackupPrivilege}
- security privilege. Note that privileges are different than permissions
- - see the Win32 documentation for more details.
-
- This function passes NULL for \var{security_attributes} to the API.
-\end{funcdesc}
-
-
-\begin{funcdesc}{SetValue}{key, sub_key, type, value}
- Associates a value with a specified key.
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- \var{sub_key} is a string that names the subkey with which the value
- is associated.
-
- \var{type} is an integer that specifies the type of the data.
- Currently this must be \constant{REG_SZ}, meaning only strings are
- supported. Use the \function{SetValueEx()} function for support for
- other data types.
-
- \var{value} is a string that specifies the new value.
-
- If the key specified by the \var{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 \var{key} parameter must have been
- opened with \constant{KEY_SET_VALUE} access.
-\end{funcdesc}
-
-
-\begin{funcdesc}{SetValueEx}{key, value_name, reserved, type, value}
- Stores data in the value field of an open registry key.
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- \var{value_name} is a string that names the subkey with which the
- value is associated.
-
- \var{type} is an integer that specifies the type of the data.
- This should be one of the following constants defined in this module:
-
- \begin{tableii}{l|p{3in}}{constant}{Constant}{Meaning}
- \lineii{REG_BINARY}{Binary data in any form.}
- \lineii{REG_DWORD}{A 32-bit number.}
- \lineii{REG_DWORD_LITTLE_ENDIAN}{A 32-bit number in little-endian format.}
- \lineii{REG_DWORD_BIG_ENDIAN}{A 32-bit number in big-endian format.}
- \lineii{REG_EXPAND_SZ}{Null-terminated string containing references
- to environment variables (\samp{\%PATH\%}).}
- \lineii{REG_LINK}{A Unicode symbolic link.}
- \lineii{REG_MULTI_SZ}{A sequence of null-terminated strings,
- terminated by two null characters. (Python handles
- this termination automatically.)}
- \lineii{REG_NONE}{No defined value type.}
- \lineii{REG_RESOURCE_LIST}{A device-driver resource list.}
- \lineii{REG_SZ}{A null-terminated string.}
- \end{tableii}
-
- \var{reserved} can be anything - zero is always passed to the
- API.
-
- \var{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 \constant{KEY_SET_VALUE} access.
-
- To open the key, use the \function{CreateKeyEx()} or
- \function{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.
-\end{funcdesc}
-
-
-
-\subsection{Registry Handle Objects \label{handle-object}}
-
- This object wraps a Windows HKEY object, automatically closing it when
- the object is destroyed. To guarantee cleanup, you can call either
- the \method{Close()} method on the object, or the
- \function{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 \method{__bool__()} - thus
-\begin{verbatim}
- if handle:
- print "Yes"
-\end{verbatim}
- will print \code{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 \function{int()} function), in which case the underlying
- Windows handle value is returned. You can also use the
- \method{Detach()} method to return the integer handle, and
- also disconnect the Windows handle from the handle object.
-
-\begin{methoddesc}[PyHKEY]{Close}{}
- Closes the underlying Windows handle.
-
- If the handle is already closed, no error is raised.
-\end{methoddesc}
-
-
-\begin{methoddesc}[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.
-\end{methoddesc}
diff --git a/Doc/lib/libwinsound.tex b/Doc/lib/libwinsound.tex
deleted file mode 100644
index 5f5b15e..0000000
--- a/Doc/lib/libwinsound.tex
+++ /dev/null
@@ -1,142 +0,0 @@
-\section{\module{winsound} ---
- Sound-playing interface for Windows}
-
-\declaremodule{builtin}{winsound}
- \platform{Windows}
-\modulesynopsis{Access to the sound-playing machinery for Windows.}
-\moduleauthor{Toby Dickenson}{htrd90@zepler.org}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-\versionadded{1.5.2}
-
-The \module{winsound} module provides access to the basic
-sound-playing machinery provided by Windows platforms. It includes
-functions and several constants.
-
-
-\begin{funcdesc}{Beep}{frequency, duration}
- Beep the PC's speaker.
- The \var{frequency} parameter specifies frequency, in hertz, of the
- sound, and must be in the range 37 through 32,767.
- The \var{duration} parameter specifies the number of milliseconds the
- sound should last. If the system is not
- able to beep the speaker, \exception{RuntimeError} is raised.
- \note{Under Windows 95 and 98, the Windows \cfunction{Beep()}
- function exists but is useless (it ignores its arguments). In that
- case Python simulates it via direct port manipulation (added in version
- 2.1). It's unknown whether that will work on all systems.}
- \versionadded{1.6}
-\end{funcdesc}
-
-\begin{funcdesc}{PlaySound}{sound, flags}
- Call the underlying \cfunction{PlaySound()} function from the
- Platform API. The \var{sound} parameter may be a filename, audio
- data as a string, or \code{None}. Its interpretation depends on the
- value of \var{flags}, which can be a bit-wise ORed combination of
- the constants described below. If the system indicates an error,
- \exception{RuntimeError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{MessageBeep}{\optional{type=\code{MB_OK}}}
- Call the underlying \cfunction{MessageBeep()} function from the
- Platform API. This plays a sound as specified in the registry. The
- \var{type} argument specifies which sound to play; possible values
- are \code{-1}, \code{MB_ICONASTERISK}, \code{MB_ICONEXCLAMATION},
- \code{MB_ICONHAND}, \code{MB_ICONQUESTION}, and \code{MB_OK}, all
- described below. The value \code{-1} produces a ``simple beep'';
- this is the final fallback if a sound cannot be played otherwise.
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{datadesc}{SND_FILENAME}
- The \var{sound} parameter is the name of a WAV file.
- Do not use with \constant{SND_ALIAS}.
-\end{datadesc}
-
-\begin{datadesc}{SND_ALIAS}
- The \var{sound} parameter is a sound association name from the
- registry. If the registry contains no such name, play the system
- default sound unless \constant{SND_NODEFAULT} is also specified.
- If no default sound is registered, raise \exception{RuntimeError}.
- Do not use with \constant{SND_FILENAME}.
-
- All Win32 systems support at least the following; most systems support
- many more:
-
-\begin{tableii}{l|l}{code}
- {\function{PlaySound()} \var{name}}
- {Corresponding Control Panel Sound name}
- \lineii{'SystemAsterisk'} {Asterisk}
- \lineii{'SystemExclamation'}{Exclamation}
- \lineii{'SystemExit'} {Exit Windows}
- \lineii{'SystemHand'} {Critical Stop}
- \lineii{'SystemQuestion'} {Question}
-\end{tableii}
-
- For example:
-
-\begin{verbatim}
-import winsound
-# Play Windows exit sound.
-winsound.PlaySound("SystemExit", winsound.SND_ALIAS)
-
-# Probably play Windows default sound, if any is registered (because
-# "*" probably isn't the registered name of any sound).
-winsound.PlaySound("*", winsound.SND_ALIAS)
-\end{verbatim}
-\end{datadesc}
-
-\begin{datadesc}{SND_LOOP}
- Play the sound repeatedly. The \constant{SND_ASYNC} flag must also
- be used to avoid blocking. Cannot be used with \constant{SND_MEMORY}.
-\end{datadesc}
-
-\begin{datadesc}{SND_MEMORY}
- The \var{sound} parameter to \function{PlaySound()} is a memory
- image of a WAV file, as a string.
-
- \note{This module does not support playing from a memory
- image asynchronously, so a combination of this flag and
- \constant{SND_ASYNC} will raise \exception{RuntimeError}.}
-\end{datadesc}
-
-\begin{datadesc}{SND_PURGE}
- Stop playing all instances of the specified sound.
-\end{datadesc}
-
-\begin{datadesc}{SND_ASYNC}
- Return immediately, allowing sounds to play asynchronously.
-\end{datadesc}
-
-\begin{datadesc}{SND_NODEFAULT}
- If the specified sound cannot be found, do not play the system default
- sound.
-\end{datadesc}
-
-\begin{datadesc}{SND_NOSTOP}
- Do not interrupt sounds currently playing.
-\end{datadesc}
-
-\begin{datadesc}{SND_NOWAIT}
- Return immediately if the sound driver is busy.
-\end{datadesc}
-
-\begin{datadesc}{MB_ICONASTERISK}
- Play the \code{SystemDefault} sound.
-\end{datadesc}
-
-\begin{datadesc}{MB_ICONEXCLAMATION}
- Play the \code{SystemExclamation} sound.
-\end{datadesc}
-
-\begin{datadesc}{MB_ICONHAND}
- Play the \code{SystemHand} sound.
-\end{datadesc}
-
-\begin{datadesc}{MB_ICONQUESTION}
- Play the \code{SystemQuestion} sound.
-\end{datadesc}
-
-\begin{datadesc}{MB_OK}
- Play the \code{SystemDefault} sound.
-\end{datadesc}
diff --git a/Doc/lib/libwsgiref.tex b/Doc/lib/libwsgiref.tex
deleted file mode 100755
index 37ded9f..0000000
--- a/Doc/lib/libwsgiref.tex
+++ /dev/null
@@ -1,782 +0,0 @@
-\section{\module{wsgiref} --- WSGI Utilities and Reference
-Implementation}
-\declaremodule{}{wsgiref}
-\moduleauthor{Phillip J. Eby}{pje@telecommunity.com}
-\sectionauthor{Phillip J. Eby}{pje@telecommunity.com}
-\modulesynopsis{WSGI Utilities and Reference Implementation}
-
-\versionadded{2.5}
-
-The Web Server Gateway Interface (WSGI) is a standard interface
-between web server software and web applications written in Python.
-Having a standard interface makes it easy to use an application
-that supports WSGI with a number of different web servers.
-
-Only authors of web servers and programming frameworks need to know
-every detail and corner case of the WSGI design. You don't need to
-understand every detail of WSGI just to install a WSGI application or
-to write a web application using an existing framework.
-
-\module{wsgiref} is a reference implementation of the WSGI specification
-that can be used to add WSGI support to a web server or framework. It
-provides utilities for manipulating WSGI environment variables and
-response headers, base classes for implementing WSGI servers, a demo
-HTTP server that serves WSGI applications, and a validation tool that
-checks WSGI servers and applications for conformance to the
-WSGI specification (\pep{333}).
-
-% XXX If you're just trying to write a web application...
-
-See \url{http://www.wsgi.org} for more information about WSGI,
-and links to tutorials and other resources.
-
-
-
-
-
-
-
-
-
-
-
-
-
-\subsection{\module{wsgiref.util} -- WSGI environment utilities}
-\declaremodule{}{wsgiref.util}
-
-This module provides a variety of utility functions for working with
-WSGI environments. A WSGI environment is a dictionary containing
-HTTP request variables as described in \pep{333}. All of the functions
-taking an \var{environ} parameter expect a WSGI-compliant dictionary to
-be supplied; please see \pep{333} for a detailed specification.
-
-\begin{funcdesc}{guess_scheme}{environ}
-Return a guess for whether \code{wsgi.url_scheme} should be ``http'' or
-``https'', by checking for a \code{HTTPS} environment variable in the
-\var{environ} dictionary. The return value is a string.
-
-This function is useful when creating a gateway that wraps CGI or a
-CGI-like protocol such as FastCGI. Typically, servers providing such
-protocols will include a \code{HTTPS} variable with a value of ``1''
-``yes'', or ``on'' when a request is received via SSL. So, this
-function returns ``https'' if such a value is found, and ``http''
-otherwise.
-\end{funcdesc}
-
-\begin{funcdesc}{request_uri}{environ \optional{, include_query=1}}
-Return the full request URI, optionally including the query string,
-using the algorithm found in the ``URL Reconstruction'' section of
-\pep{333}. If \var{include_query} is false, the query string is
-not included in the resulting URI.
-\end{funcdesc}
-
-\begin{funcdesc}{application_uri}{environ}
-Similar to \function{request_uri}, except that the \code{PATH_INFO} and
-\code{QUERY_STRING} variables are ignored. The result is the base URI
-of the application object addressed by the request.
-\end{funcdesc}
-
-\begin{funcdesc}{shift_path_info}{environ}
-Shift a single name from \code{PATH_INFO} to \code{SCRIPT_NAME} and
-return the name. The \var{environ} dictionary is \emph{modified}
-in-place; use a copy if you need to keep the original \code{PATH_INFO}
-or \code{SCRIPT_NAME} intact.
-
-If there are no remaining path segments in \code{PATH_INFO}, \code{None}
-is returned.
-
-Typically, this routine is used to process each portion of a request
-URI path, for example to treat the path as a series of dictionary keys.
-This routine modifies the passed-in environment to make it suitable for
-invoking another WSGI application that is located at the target URI.
-For example, if there is a WSGI application at \code{/foo}, and the
-request URI path is \code{/foo/bar/baz}, and the WSGI application at
-\code{/foo} calls \function{shift_path_info}, it will receive the string
-``bar'', and the environment will be updated to be suitable for passing
-to a WSGI application at \code{/foo/bar}. That is, \code{SCRIPT_NAME}
-will change from \code{/foo} to \code{/foo/bar}, and \code{PATH_INFO}
-will change from \code{/bar/baz} to \code{/baz}.
-
-When \code{PATH_INFO} is just a ``/'', this routine returns an empty
-string and appends a trailing slash to \code{SCRIPT_NAME}, even though
-empty path segments are normally ignored, and \code{SCRIPT_NAME} doesn't
-normally end in a slash. This is intentional behavior, to ensure that
-an application can tell the difference between URIs ending in \code{/x}
-from ones ending in \code{/x/} when using this routine to do object
-traversal.
-
-\end{funcdesc}
-
-\begin{funcdesc}{setup_testing_defaults}{environ}
-Update \var{environ} with trivial defaults for testing purposes.
-
-This routine adds various parameters required for WSGI, including
-\code{HTTP_HOST}, \code{SERVER_NAME}, \code{SERVER_PORT},
-\code{REQUEST_METHOD}, \code{SCRIPT_NAME}, \code{PATH_INFO}, and all of
-the \pep{333}-defined \code{wsgi.*} variables. It only supplies default
-values, and does not replace any existing settings for these variables.
-
-This routine is intended to make it easier for unit tests of WSGI
-servers and applications to set up dummy environments. It should NOT
-be used by actual WSGI servers or applications, since the data is fake!
-\end{funcdesc}
-
-
-
-In addition to the environment functions above, the
-\module{wsgiref.util} module also provides these miscellaneous
-utilities:
-
-\begin{funcdesc}{is_hop_by_hop}{header_name}
-Return true if 'header_name' is an HTTP/1.1 ``Hop-by-Hop'' header, as
-defined by \rfc{2616}.
-\end{funcdesc}
-
-\begin{classdesc}{FileWrapper}{filelike \optional{, blksize=8192}}
-A wrapper to convert a file-like object to an iterator. The resulting
-objects support both \method{__getitem__} and \method{__iter__}
-iteration styles, for compatibility with Python 2.1 and Jython.
-As the object is iterated over, the optional \var{blksize} parameter
-will be repeatedly passed to the \var{filelike} object's \method{read()}
-method to obtain strings to yield. When \method{read()} returns an
-empty string, iteration is ended and is not resumable.
-
-If \var{filelike} has a \method{close()} method, the returned object
-will also have a \method{close()} method, and it will invoke the
-\var{filelike} object's \method{close()} method when called.
-\end{classdesc}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-\subsection{\module{wsgiref.headers} -- WSGI response header tools}
-\declaremodule{}{wsgiref.headers}
-
-This module provides a single class, \class{Headers}, for convenient
-manipulation of WSGI response headers using a mapping-like interface.
-
-\begin{classdesc}{Headers}{headers}
-Create a mapping-like object wrapping \var{headers}, which must be a
-list of header name/value tuples as described in \pep{333}. Any changes
-made to the new \class{Headers} object will directly update the
-\var{headers} list it was created with.
-
-\class{Headers} objects support typical mapping operations including
-\method{__getitem__}, \method{get}, \method{__setitem__},
-\method{setdefault}, \method{__delitem__}, \method{__contains__} and
-\method{has_key}. For each of these methods, the key is the header name
-(treated case-insensitively), and the value is the first value
-associated with that header name. Setting a header deletes any existing
-values for that header, then adds a new value at the end of the wrapped
-header list. Headers' existing order is generally maintained, with new
-headers added to the end of the wrapped list.
-
-Unlike a dictionary, \class{Headers} objects do not raise an error when
-you try to get or delete a key that isn't in the wrapped header list.
-Getting a nonexistent header just returns \code{None}, and deleting
-a nonexistent header does nothing.
-
-\class{Headers} objects also support \method{keys()}, \method{values()},
-and \method{items()} methods. The lists returned by \method{keys()}
-and \method{items()} can include the same key more than once if there
-is a multi-valued header. The \code{len()} of a \class{Headers} object
-is the same as the length of its \method{items()}, which is the same
-as the length of the wrapped header list. In fact, the \method{items()}
-method just returns a copy of the wrapped header list.
-
-Calling \code{str()} on a \class{Headers} object returns a formatted
-string suitable for transmission as HTTP response headers. Each header
-is placed on a line with its value, separated by a colon and a space.
-Each line is terminated by a carriage return and line feed, and the
-string is terminated with a blank line.
-
-In addition to their mapping interface and formatting features,
-\class{Headers} objects also have the following methods for querying
-and adding multi-valued headers, and for adding headers with MIME
-parameters:
-
-\begin{methoddesc}{get_all}{name}
-Return a list of all the values for the named header.
-
-The returned list will be sorted in the order they appeared in the
-original header list or were added to this instance, and may contain
-duplicates. Any fields deleted and re-inserted are always appended to
-the header list. If no fields exist with the given name, returns an
-empty list.
-\end{methoddesc}
-
-
-\begin{methoddesc}{add_header}{name, value, **_params}
-Add a (possibly multi-valued) header, with optional MIME parameters
-specified via keyword arguments.
-
-\var{name} is the header field to add. Keyword arguments can be used to
-set MIME parameters for the header field. Each parameter must be a
-string or \code{None}. Underscores in parameter names are converted to
-dashes, since dashes are illegal in Python identifiers, but many MIME
-parameter names include dashes. If the parameter value is a string, it
-is added to the header value parameters in the form \code{name="value"}.
-If it is \code{None}, only the parameter name is added. (This is used
-for MIME parameters without a value.) Example usage:
-
-\begin{verbatim}
-h.add_header('content-disposition', 'attachment', filename='bud.gif')
-\end{verbatim}
-
-The above will add a header that looks like this:
-
-\begin{verbatim}
-Content-Disposition: attachment; filename="bud.gif"
-\end{verbatim}
-\end{methoddesc}
-\end{classdesc}
-
-\subsection{\module{wsgiref.simple_server} -- a simple WSGI HTTP server}
-\declaremodule[wsgiref.simpleserver]{}{wsgiref.simple_server}
-
-This module implements a simple HTTP server (based on
-\module{BaseHTTPServer}) that serves WSGI applications. Each server
-instance serves a single WSGI application on a given host and port. If
-you want to serve multiple applications on a single host and port, you
-should create a WSGI application that parses \code{PATH_INFO} to select
-which application to invoke for each request. (E.g., using the
-\function{shift_path_info()} function from \module{wsgiref.util}.)
-
-
-\begin{funcdesc}{make_server}{host, port, app
-\optional{, server_class=\class{WSGIServer} \optional{,
-handler_class=\class{WSGIRequestHandler}}}}
-Create a new WSGI server listening on \var{host} and \var{port},
-accepting connections for \var{app}. The return value is an instance of
-the supplied \var{server_class}, and will process requests using the
-specified \var{handler_class}. \var{app} must be a WSGI application
-object, as defined by \pep{333}.
-
-Example usage:
-\begin{verbatim}from wsgiref.simple_server import make_server, demo_app
-
-httpd = make_server('', 8000, demo_app)
-print "Serving HTTP on port 8000..."
-
-# Respond to requests until process is killed
-httpd.serve_forever()
-
-# Alternative: serve one request, then exit
-##httpd.handle_request()
-\end{verbatim}
-
-\end{funcdesc}
-
-
-
-
-
-
-\begin{funcdesc}{demo_app}{environ, start_response}
-This function is a small but complete WSGI application that
-returns a text page containing the message ``Hello world!''
-and a list of the key/value pairs provided in the
-\var{environ} parameter. It's useful for verifying that a WSGI server
-(such as \module{wsgiref.simple_server}) is able to run a simple WSGI
-application correctly.
-\end{funcdesc}
-
-
-\begin{classdesc}{WSGIServer}{server_address, RequestHandlerClass}
-Create a \class{WSGIServer} instance. \var{server_address} should be
-a \code{(host,port)} tuple, and \var{RequestHandlerClass} should be
-the subclass of \class{BaseHTTPServer.BaseHTTPRequestHandler} that will
-be used to process requests.
-
-You do not normally need to call this constructor, as the
-\function{make_server()} function can handle all the details for you.
-
-\class{WSGIServer} is a subclass
-of \class{BaseHTTPServer.HTTPServer}, so all of its methods (such as
-\method{serve_forever()} and \method{handle_request()}) are available.
-\class{WSGIServer} also provides these WSGI-specific methods:
-
-\begin{methoddesc}{set_app}{application}
-Sets the callable \var{application} as the WSGI application that will
-receive requests.
-\end{methoddesc}
-
-\begin{methoddesc}{get_app}{}
-Returns the currently-set application callable.
-\end{methoddesc}
-
-Normally, however, you do not need to use these additional methods, as
-\method{set_app()} is normally called by \function{make_server()}, and
-the \method{get_app()} exists mainly for the benefit of request handler
-instances.
-\end{classdesc}
-
-
-
-\begin{classdesc}{WSGIRequestHandler}{request, client_address, server}
-Create an HTTP handler for the given \var{request} (i.e. a socket),
-\var{client_address} (a \code{(\var{host},\var{port})} tuple), and
-\var{server} (\class{WSGIServer} instance).
-
-You do not need to create instances of this class directly; they are
-automatically created as needed by \class{WSGIServer} objects. You
-can, however, subclass this class and supply it as a \var{handler_class}
-to the \function{make_server()} function. Some possibly relevant
-methods for overriding in subclasses:
-
-\begin{methoddesc}{get_environ}{}
-Returns a dictionary containing the WSGI environment for a request. The
-default implementation copies the contents of the \class{WSGIServer}
-object's \member{base_environ} dictionary attribute and then adds
-various headers derived from the HTTP request. Each call to this method
-should return a new dictionary containing all of the relevant CGI
-environment variables as specified in \pep{333}.
-\end{methoddesc}
-
-\begin{methoddesc}{get_stderr}{}
-Return the object that should be used as the \code{wsgi.errors} stream.
-The default implementation just returns \code{sys.stderr}.
-\end{methoddesc}
-
-\begin{methoddesc}{handle}{}
-Process the HTTP request. The default implementation creates a handler
-instance using a \module{wsgiref.handlers} class to implement the actual
-WSGI application interface.
-\end{methoddesc}
-
-\end{classdesc}
-
-
-
-
-
-
-
-
-
-\subsection{\module{wsgiref.validate} -- WSGI conformance checker}
-\declaremodule{}{wsgiref.validate}
-When creating new WSGI application objects, frameworks, servers, or
-middleware, it can be useful to validate the new code's conformance
-using \module{wsgiref.validate}. This module provides a function that
-creates WSGI application objects that validate communications between
-a WSGI server or gateway and a WSGI application object, to check both
-sides for protocol conformance.
-
-Note that this utility does not guarantee complete \pep{333} compliance;
-an absence of errors from this module does not necessarily mean that
-errors do not exist. However, if this module does produce an error,
-then it is virtually certain that either the server or application is
-not 100\% compliant.
-
-This module is based on the \module{paste.lint} module from Ian
-Bicking's ``Python Paste'' library.
-
-\begin{funcdesc}{validator}{application}
-Wrap \var{application} and return a new WSGI application object. The
-returned application will forward all requests to the original
-\var{application}, and will check that both the \var{application} and
-the server invoking it are conforming to the WSGI specification and to
-RFC 2616.
-
-Any detected nonconformance results in an \exception{AssertionError}
-being raised; note, however, that how these errors are handled is
-server-dependent. For example, \module{wsgiref.simple_server} and other
-servers based on \module{wsgiref.handlers} (that don't override the
-error handling methods to do something else) will simply output a
-message that an error has occurred, and dump the traceback to
-\code{sys.stderr} or some other error stream.
-
-This wrapper may also generate output using the \module{warnings} module
-to indicate behaviors that are questionable but which may not actually
-be prohibited by \pep{333}. Unless they are suppressed using Python
-command-line options or the \module{warnings} API, any such warnings
-will be written to \code{sys.stderr} (\emph{not} \code{wsgi.errors},
-unless they happen to be the same object).
-\end{funcdesc}
-
-\subsection{\module{wsgiref.handlers} -- server/gateway base classes}
-\declaremodule{}{wsgiref.handlers}
-
-This module provides base handler classes for implementing WSGI servers
-and gateways. These base classes handle most of the work of
-communicating with a WSGI application, as long as they are given a
-CGI-like environment, along with input, output, and error streams.
-
-
-\begin{classdesc}{CGIHandler}{}
-CGI-based invocation via \code{sys.stdin}, \code{sys.stdout},
-\code{sys.stderr} and \code{os.environ}. This is useful when you have
-a WSGI application and want to run it as a CGI script. Simply invoke
-\code{CGIHandler().run(app)}, where \code{app} is the WSGI application
-object you wish to invoke.
-
-This class is a subclass of \class{BaseCGIHandler} that sets
-\code{wsgi.run_once} to true, \code{wsgi.multithread} to false, and
-\code{wsgi.multiprocess} to true, and always uses \module{sys} and
-\module{os} to obtain the necessary CGI streams and environment.
-\end{classdesc}
-
-
-\begin{classdesc}{BaseCGIHandler}{stdin, stdout, stderr, environ
-\optional{, multithread=True \optional{, multiprocess=False}}}
-
-Similar to \class{CGIHandler}, but instead of using the \module{sys} and
-\module{os} modules, the CGI environment and I/O streams are specified
-explicitly. The \var{multithread} and \var{multiprocess} values are
-used to set the \code{wsgi.multithread} and \code{wsgi.multiprocess}
-flags for any applications run by the handler instance.
-
-This class is a subclass of \class{SimpleHandler} intended for use with
-software other than HTTP ``origin servers''. If you are writing a
-gateway protocol implementation (such as CGI, FastCGI, SCGI, etc.) that
-uses a \code{Status:} header to send an HTTP status, you probably want
-to subclass this instead of \class{SimpleHandler}.
-\end{classdesc}
-
-
-
-\begin{classdesc}{SimpleHandler}{stdin, stdout, stderr, environ
-\optional{,multithread=True \optional{, multiprocess=False}}}
-
-Similar to \class{BaseCGIHandler}, but designed for use with HTTP origin
-servers. If you are writing an HTTP server implementation, you will
-probably want to subclass this instead of \class{BaseCGIHandler}
-
-This class is a subclass of \class{BaseHandler}. It overrides the
-\method{__init__()}, \method{get_stdin()}, \method{get_stderr()},
-\method{add_cgi_vars()}, \method{_write()}, and \method{_flush()}
-methods to support explicitly setting the environment and streams via
-the constructor. The supplied environment and streams are stored in
-the \member{stdin}, \member{stdout}, \member{stderr}, and
-\member{environ} attributes.
-\end{classdesc}
-
-\begin{classdesc}{BaseHandler}{}
-This is an abstract base class for running WSGI applications. Each
-instance will handle a single HTTP request, although in principle you
-could create a subclass that was reusable for multiple requests.
-
-\class{BaseHandler} instances have only one method intended for external
-use:
-
-\begin{methoddesc}{run}{app}
-Run the specified WSGI application, \var{app}.
-\end{methoddesc}
-
-All of the other \class{BaseHandler} methods are invoked by this method
-in the process of running the application, and thus exist primarily to
-allow customizing the process.
-
-The following methods MUST be overridden in a subclass:
-
-\begin{methoddesc}{_write}{data}
-Buffer the string \var{data} for transmission to the client. It's okay
-if this method actually transmits the data; \class{BaseHandler}
-just separates write and flush operations for greater efficiency
-when the underlying system actually has such a distinction.
-\end{methoddesc}
-
-\begin{methoddesc}{_flush}{}
-Force buffered data to be transmitted to the client. It's okay if this
-method is a no-op (i.e., if \method{_write()} actually sends the data).
-\end{methoddesc}
-
-\begin{methoddesc}{get_stdin}{}
-Return an input stream object suitable for use as the \code{wsgi.input}
-of the request currently being processed.
-\end{methoddesc}
-
-\begin{methoddesc}{get_stderr}{}
-Return an output stream object suitable for use as the
-\code{wsgi.errors} of the request currently being processed.
-\end{methoddesc}
-
-\begin{methoddesc}{add_cgi_vars}{}
-Insert CGI variables for the current request into the \member{environ}
-attribute.
-\end{methoddesc}
-
-Here are some other methods and attributes you may wish to override.
-This list is only a summary, however, and does not include every method
-that can be overridden. You should consult the docstrings and source
-code for additional information before attempting to create a customized
-\class{BaseHandler} subclass.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Attributes and methods for customizing the WSGI environment:
-
-\begin{memberdesc}{wsgi_multithread}
-The value to be used for the \code{wsgi.multithread} environment
-variable. It defaults to true in \class{BaseHandler}, but may have
-a different default (or be set by the constructor) in the other
-subclasses.
-\end{memberdesc}
-
-\begin{memberdesc}{wsgi_multiprocess}
-The value to be used for the \code{wsgi.multiprocess} environment
-variable. It defaults to true in \class{BaseHandler}, but may have
-a different default (or be set by the constructor) in the other
-subclasses.
-\end{memberdesc}
-
-\begin{memberdesc}{wsgi_run_once}
-The value to be used for the \code{wsgi.run_once} environment
-variable. It defaults to false in \class{BaseHandler}, but
-\class{CGIHandler} sets it to true by default.
-\end{memberdesc}
-
-\begin{memberdesc}{os_environ}
-The default environment variables to be included in every request's
-WSGI environment. By default, this is a copy of \code{os.environ} at
-the time that \module{wsgiref.handlers} was imported, but subclasses can
-either create their own at the class or instance level. Note that the
-dictionary should be considered read-only, since the default value is
-shared between multiple classes and instances.
-\end{memberdesc}
-
-\begin{memberdesc}{server_software}
-If the \member{origin_server} attribute is set, this attribute's value
-is used to set the default \code{SERVER_SOFTWARE} WSGI environment
-variable, and also to set a default \code{Server:} header in HTTP
-responses. It is ignored for handlers (such as \class{BaseCGIHandler}
-and \class{CGIHandler}) that are not HTTP origin servers.
-\end{memberdesc}
-
-
-
-\begin{methoddesc}{get_scheme}{}
-Return the URL scheme being used for the current request. The default
-implementation uses the \function{guess_scheme()} function from
-\module{wsgiref.util} to guess whether the scheme should be ``http'' or
-``https'', based on the current request's \member{environ} variables.
-\end{methoddesc}
-
-\begin{methoddesc}{setup_environ}{}
-Set the \member{environ} attribute to a fully-populated WSGI
-environment. The default implementation uses all of the above methods
-and attributes, plus the \method{get_stdin()}, \method{get_stderr()},
-and \method{add_cgi_vars()} methods and the \member{wsgi_file_wrapper}
-attribute. It also inserts a \code{SERVER_SOFTWARE} key if not present,
-as long as the \member{origin_server} attribute is a true value and the
-\member{server_software} attribute is set.
-\end{methoddesc}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Methods and attributes for customizing exception handling:
-
-\begin{methoddesc}{log_exception}{exc_info}
-Log the \var{exc_info} tuple in the server log. \var{exc_info} is a
-\code{(\var{type}, \var{value}, \var{traceback})} tuple. The default
-implementation simply writes the traceback to the request's
-\code{wsgi.errors} stream and flushes it. Subclasses can override this
-method to change the format or retarget the output, mail the traceback
-to an administrator, or whatever other action may be deemed suitable.
-\end{methoddesc}
-
-\begin{memberdesc}{traceback_limit}
-The maximum number of frames to include in tracebacks output by the
-default \method{log_exception()} method. If \code{None}, all frames
-are included.
-\end{memberdesc}
-
-\begin{methoddesc}{error_output}{environ, start_response}
-This method is a WSGI application to generate an error page for the
-user. It is only invoked if an error occurs before headers are sent
-to the client.
-
-This method can access the current error information using
-\code{sys.exc_info()}, and should pass that information to
-\var{start_response} when calling it (as described in the ``Error
-Handling'' section of \pep{333}).
-
-The default implementation just uses the \member{error_status},
-\member{error_headers}, and \member{error_body} attributes to generate
-an output page. Subclasses can override this to produce more dynamic
-error output.
-
-Note, however, that it's not recommended from a security perspective to
-spit out diagnostics to any old user; ideally, you should have to do
-something special to enable diagnostic output, which is why the default
-implementation doesn't include any.
-\end{methoddesc}
-
-
-
-
-\begin{memberdesc}{error_status}
-The HTTP status used for error responses. This should be a status
-string as defined in \pep{333}; it defaults to a 500 code and message.
-\end{memberdesc}
-
-\begin{memberdesc}{error_headers}
-The HTTP headers used for error responses. This should be a list of
-WSGI response headers (\code{(\var{name}, \var{value})} tuples), as
-described in \pep{333}. The default list just sets the content type
-to \code{text/plain}.
-\end{memberdesc}
-
-\begin{memberdesc}{error_body}
-The error response body. This should be an HTTP response body string.
-It defaults to the plain text, ``A server error occurred. Please
-contact the administrator.''
-\end{memberdesc}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Methods and attributes for \pep{333}'s ``Optional Platform-Specific File
-Handling'' feature:
-
-\begin{memberdesc}{wsgi_file_wrapper}
-A \code{wsgi.file_wrapper} factory, or \code{None}. The default value
-of this attribute is the \class{FileWrapper} class from
-\module{wsgiref.util}.
-\end{memberdesc}
-
-\begin{methoddesc}{sendfile}{}
-Override to implement platform-specific file transmission. This method
-is called only if the application's return value is an instance of
-the class specified by the \member{wsgi_file_wrapper} attribute. It
-should return a true value if it was able to successfully transmit the
-file, so that the default transmission code will not be executed.
-The default implementation of this method just returns a false value.
-\end{methoddesc}
-
-
-Miscellaneous methods and attributes:
-
-\begin{memberdesc}{origin_server}
-This attribute should be set to a true value if the handler's
-\method{_write()} and \method{_flush()} are being used to communicate
-directly to the client, rather than via a CGI-like gateway protocol that
-wants the HTTP status in a special \code{Status:} header.
-
-This attribute's default value is true in \class{BaseHandler}, but
-false in \class{BaseCGIHandler} and \class{CGIHandler}.
-\end{memberdesc}
-
-\begin{memberdesc}{http_version}
-If \member{origin_server} is true, this string attribute is used to
-set the HTTP version of the response set to the client. It defaults to
-\code{"1.0"}.
-\end{memberdesc}
-
-
-
-
-
-\end{classdesc}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/Doc/lib/libxdrlib.tex b/Doc/lib/libxdrlib.tex
deleted file mode 100644
index 56474b7..0000000
--- a/Doc/lib/libxdrlib.tex
+++ /dev/null
@@ -1,251 +0,0 @@
-\section{\module{xdrlib} ---
- Encode and decode XDR data}
-
-\declaremodule{standard}{xdrlib}
-\modulesynopsis{Encoders and decoders for the External Data
- Representation (XDR).}
-
-\index{XDR}
-\index{External Data Representation}
-
-The \module{xdrlib} module supports the External Data Representation
-Standard as described in \rfc{1014}, written by Sun Microsystems,
-Inc. June 1987. It supports most of the data types described in the
-RFC.
-
-The \module{xdrlib} module defines two classes, one for packing
-variables into XDR representation, and another for unpacking from XDR
-representation. There are also two exception classes.
-
-\begin{classdesc}{Packer}{}
-\class{Packer} is the class for packing data into XDR representation.
-The \class{Packer} class is instantiated with no arguments.
-\end{classdesc}
-
-\begin{classdesc}{Unpacker}{data}
-\code{Unpacker} is the complementary class which unpacks XDR data
-values from a string buffer. The input buffer is given as
-\var{data}.
-\end{classdesc}
-
-
-\begin{seealso}
- \seerfc{1014}{XDR: External Data Representation Standard}{This RFC
- defined the encoding of data which was XDR at the time
- this module was originally written. It has
- apparently been obsoleted by \rfc{1832}.}
-
- \seerfc{1832}{XDR: External Data Representation Standard}{Newer RFC
- that provides a revised definition of XDR.}
-\end{seealso}
-
-
-\subsection{Packer Objects \label{xdr-packer-objects}}
-
-\class{Packer} instances have the following methods:
-
-\begin{methoddesc}[Packer]{get_buffer}{}
-Returns the current pack buffer as a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{reset}{}
-Resets the pack buffer to the empty string.
-\end{methoddesc}
-
-In general, you can pack any of the most common XDR data types by
-calling the appropriate \code{pack_\var{type}()} method. Each method
-takes a single argument, the value to pack. The following simple data
-type packing methods are supported: \method{pack_uint()},
-\method{pack_int()}, \method{pack_enum()}, \method{pack_bool()},
-\method{pack_uhyper()}, and \method{pack_hyper()}.
-
-\begin{methoddesc}[Packer]{pack_float}{value}
-Packs the single-precision floating point number \var{value}.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_double}{value}
-Packs the double-precision floating point number \var{value}.
-\end{methoddesc}
-
-The following methods support packing strings, bytes, and opaque data:
-
-\begin{methoddesc}[Packer]{pack_fstring}{n, s}
-Packs a fixed length string, \var{s}. \var{n} is the length of the
-string but it is \emph{not} packed into the data buffer. The string
-is padded with null bytes if necessary to guaranteed 4 byte alignment.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_fopaque}{n, data}
-Packs a fixed length opaque data stream, similarly to
-\method{pack_fstring()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_string}{s}
-Packs a variable length string, \var{s}. The length of the string is
-first packed as an unsigned integer, then the string data is packed
-with \method{pack_fstring()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_opaque}{data}
-Packs a variable length opaque data string, similarly to
-\method{pack_string()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_bytes}{bytes}
-Packs a variable length byte stream, similarly to \method{pack_string()}.
-\end{methoddesc}
-
-The following methods support packing arrays and lists:
-
-\begin{methoddesc}[Packer]{pack_list}{list, pack_item}
-Packs a \var{list} of homogeneous items. This method is useful for
-lists with an indeterminate size; i.e. the size is not available until
-the entire list has been walked. For each item in the list, an
-unsigned integer \code{1} is packed first, followed by the data value
-from the list. \var{pack_item} is the function that is called to pack
-the individual item. At the end of the list, an unsigned integer
-\code{0} is packed.
-
-For example, to pack a list of integers, the code might appear like
-this:
-
-\begin{verbatim}
-import xdrlib
-p = xdrlib.Packer()
-p.pack_list([1, 2, 3], p.pack_int)
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_farray}{n, array, pack_item}
-Packs a fixed length list (\var{array}) of homogeneous items. \var{n}
-is the length of the list; it is \emph{not} packed into the buffer,
-but a \exception{ValueError} exception is raised if
-\code{len(\var{array})} is not equal to \var{n}. As above,
-\var{pack_item} is the function used to pack each element.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_array}{list, pack_item}
-Packs a variable length \var{list} of homogeneous items. First, the
-length of the list is packed as an unsigned integer, then each element
-is packed as in \method{pack_farray()} above.
-\end{methoddesc}
-
-
-\subsection{Unpacker Objects \label{xdr-unpacker-objects}}
-
-The \class{Unpacker} class offers the following methods:
-
-\begin{methoddesc}[Unpacker]{reset}{data}
-Resets the string buffer with the given \var{data}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{get_position}{}
-Returns the current unpack position in the data buffer.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{set_position}{position}
-Sets the data buffer unpack position to \var{position}. You should be
-careful about using \method{get_position()} and \method{set_position()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{get_buffer}{}
-Returns the current unpack data buffer as a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{done}{}
-Indicates unpack completion. Raises an \exception{Error} exception
-if all of the data has not been unpacked.
-\end{methoddesc}
-
-In addition, every data type that can be packed with a \class{Packer},
-can be unpacked with an \class{Unpacker}. Unpacking methods are of the
-form \code{unpack_\var{type}()}, and take no arguments. They return the
-unpacked object.
-
-\begin{methoddesc}[Unpacker]{unpack_float}{}
-Unpacks a single-precision floating point number.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_double}{}
-Unpacks a double-precision floating point number, similarly to
-\method{unpack_float()}.
-\end{methoddesc}
-
-In addition, the following methods unpack strings, bytes, and opaque
-data:
-
-\begin{methoddesc}[Unpacker]{unpack_fstring}{n}
-Unpacks and returns a fixed length string. \var{n} is the number of
-characters expected. Padding with null bytes to guaranteed 4 byte
-alignment is assumed.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_fopaque}{n}
-Unpacks and returns a fixed length opaque data stream, similarly to
-\method{unpack_fstring()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_string}{}
-Unpacks and returns a variable length string. The length of the
-string is first unpacked as an unsigned integer, then the string data
-is unpacked with \method{unpack_fstring()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_opaque}{}
-Unpacks and returns a variable length opaque data string, similarly to
-\method{unpack_string()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_bytes}{}
-Unpacks and returns a variable length byte stream, similarly to
-\method{unpack_string()}.
-\end{methoddesc}
-
-The following methods support unpacking arrays and lists:
-
-\begin{methoddesc}[Unpacker]{unpack_list}{unpack_item}
-Unpacks and returns a list of homogeneous items. The list is unpacked
-one element at a time
-by first unpacking an unsigned integer flag. If the flag is \code{1},
-then the item is unpacked and appended to the list. A flag of
-\code{0} indicates the end of the list. \var{unpack_item} is the
-function that is called to unpack the items.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_farray}{n, unpack_item}
-Unpacks and returns (as a list) a fixed length array of homogeneous
-items. \var{n} is number of list elements to expect in the buffer.
-As above, \var{unpack_item} is the function used to unpack each element.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_array}{unpack_item}
-Unpacks and returns a variable length \var{list} of homogeneous items.
-First, the length of the list is unpacked as an unsigned integer, then
-each element is unpacked as in \method{unpack_farray()} above.
-\end{methoddesc}
-
-
-\subsection{Exceptions \label{xdr-exceptions}}
-
-Exceptions in this module are coded as class instances:
-
-\begin{excdesc}{Error}
-The base exception class. \exception{Error} has a single public data
-member \member{msg} containing the description of the error.
-\end{excdesc}
-
-\begin{excdesc}{ConversionError}
-Class derived from \exception{Error}. Contains no additional instance
-variables.
-\end{excdesc}
-
-Here is an example of how you would catch one of these exceptions:
-
-\begin{verbatim}
-import xdrlib
-p = xdrlib.Packer()
-try:
- p.pack_double(8.01)
-except xdrlib.ConversionError as instance:
- print 'packing the double failed:', instance.msg
-\end{verbatim}
diff --git a/Doc/lib/libxmlrpclib.tex b/Doc/lib/libxmlrpclib.tex
deleted file mode 100644
index 22f29b8..0000000
--- a/Doc/lib/libxmlrpclib.tex
+++ /dev/null
@@ -1,391 +0,0 @@
-\section{\module{xmlrpclib} --- XML-RPC client access}
-
-\declaremodule{standard}{xmlrpclib}
-\modulesynopsis{XML-RPC client access.}
-\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com}
-\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-
-% Not everything is documented yet. It might be good to describe
-% Marshaller, Unmarshaller, getparser, dumps, loads, and Transport.
-
-\versionadded{2.2}
-
-XML-RPC is a Remote Procedure Call method that uses XML passed via
-HTTP as a transport. With it, a client can call methods with
-parameters on a remote server (the server is named by a URI) and get back
-structured data. This module supports writing XML-RPC client code; it
-handles all the details of translating between conformable Python
-objects and XML on the wire.
-
-\begin{classdesc}{ServerProxy}{uri\optional{, transport\optional{,
- encoding\optional{, verbose\optional{,
- allow_none\optional{, use_datetime}}}}}}
-A \class{ServerProxy} instance is an object that manages communication
-with a remote XML-RPC server. The required first argument is a URI
-(Uniform Resource Indicator), and will normally be the URL of the
-server. The optional second argument is a transport factory instance;
-by default it is an internal \class{SafeTransport} instance for https:
-URLs and an internal HTTP \class{Transport} instance otherwise. The
-optional third argument is an encoding, by default UTF-8. The optional
-fourth argument is a debugging flag. If \var{allow_none} is true,
-the Python constant \code{None} will be translated into XML; the
-default behaviour is for \code{None} to raise a \exception{TypeError}.
-This is a commonly-used extension to the XML-RPC specification, but isn't
-supported by all clients and servers; see
-\url{http://ontosys.com/xml-rpc/extensions.php} for a description.
-The \var{use_datetime} flag can be used to cause date/time values to be
-presented as \class{\refmodule{datetime}.datetime} objects; this is false
-by default. \class{\refmodule{datetime}.datetime},
-\class{\refmodule{datetime}.date} and \class{\refmodule{datetime}.time}
-objects may be passed to calls. \class{\refmodule{datetime}.date} objects
-are converted with a time of ``00:00:00''.
-\class{\refmodule{datetime}.time} objects are converted using today's date.
-
-Both the HTTP and HTTPS transports support the URL syntax extension for
-HTTP Basic Authentication: \code{http://user:pass@host:port/path}. The
-\code{user:pass} portion will be base64-encoded as an HTTP `Authorization'
-header, and sent to the remote server as part of the connection process
-when invoking an XML-RPC method. You only need to use this if the
-remote server requires a Basic Authentication user and password.
-
-The returned instance is a proxy object with methods that can be used
-to invoke corresponding RPC calls on the remote server. If the remote
-server supports the introspection API, the proxy can also be used to query
-the remote server for the methods it supports (service discovery) and
-fetch other server-associated metadata.
-
-\class{ServerProxy} instance methods take Python basic types and objects as
-arguments and return Python basic types and classes. Types that are
-conformable (e.g. that can be marshalled through XML), include the
-following (and except where noted, they are unmarshalled as the same
-Python type):
-
-\begin{tableii}{l|l}{constant}{Name}{Meaning}
- \lineii{boolean}{The \constant{True} and \constant{False} constants}
- \lineii{integers}{Pass in directly}
- \lineii{floating-point numbers}{Pass in directly}
- \lineii{strings}{Pass in directly}
- \lineii{arrays}{Any Python sequence type containing conformable
- elements. Arrays are returned as lists}
- \lineii{structures}{A Python dictionary. Keys must be strings,
- values may be any conformable type. Objects
- of user-defined classes can be passed in;
- only their \var{__dict__} attribute is
- transmitted.}
- \lineii{dates}{in seconds since the epoch (pass in an instance of the
- \class{DateTime} class) or a
- \class{\refmodule{datetime}.datetime},
- \class{\refmodule{datetime}.date} or
- \class{\refmodule{datetime}.time} instance}
- \lineii{binary data}{pass in an instance of the \class{Binary}
- wrapper class}
-\end{tableii}
-
-This is the full set of data types supported by XML-RPC. Method calls
-may also raise a special \exception{Fault} instance, used to signal
-XML-RPC server errors, or \exception{ProtocolError} used to signal an
-error in the HTTP/HTTPS transport layer. Both \exception{Fault} and
-\exception{ProtocolError} derive from a base class called
-\exception{Error}. Note that even though starting with Python 2.2 you
-can subclass builtin types, the xmlrpclib module currently does not
-marshal instances of such subclasses.
-
-When passing strings, characters special to XML such as \samp{<},
-\samp{>}, and \samp{\&} will be automatically escaped. However, it's
-the caller's responsibility to ensure that the string is free of
-characters that aren't allowed in XML, such as the control characters
-with ASCII values between 0 and 31 (except, of course, tab, newline and
-carriage return); failing to do this will result in
-an XML-RPC request that isn't well-formed XML. If you have to pass
-arbitrary strings via XML-RPC, use the \class{Binary} wrapper class
-described below.
-
-\class{Server} is retained as an alias for \class{ServerProxy} for backwards
-compatibility. New code should use \class{ServerProxy}.
-
-\versionchanged[The \var{use_datetime} flag was added]{2.5}
-
-\versionchanged[Instances of new-style classes can be passed in
-if they have an \var{__dict__} attribute and don't have a base class
-that is marshalled in a special way]{2.6}
-\end{classdesc}
-
-
-\begin{seealso}
- \seetitle[http://www.tldp.org/HOWTO/XML-RPC-HOWTO/index.html]
- {XML-RPC HOWTO}{A good description of XML operation and
- client software in several languages. Contains pretty much
- everything an XML-RPC client developer needs to know.}
- \seetitle[http://xmlrpc-c.sourceforge.net/hacks.php]
- {XML-RPC Hacks page}{Extensions for various open-source
- libraries to support introspection and multicall.}
-\end{seealso}
-
-
-\subsection{ServerProxy Objects \label{serverproxy-objects}}
-
-A \class{ServerProxy} instance has a method corresponding to
-each remote procedure call accepted by the XML-RPC server. Calling
-the method performs an RPC, dispatched by both name and argument
-signature (e.g. the same method name can be overloaded with multiple
-argument signatures). The RPC finishes by returning a value, which
-may be either returned data in a conformant type or a \class{Fault} or
-\class{ProtocolError} object indicating an error.
-
-Servers that support the XML introspection API support some common
-methods grouped under the reserved \member{system} member:
-
-\begin{methoddesc}[ServerProxy]{system.listMethods}{}
-This method returns a list of strings, one for each (non-system)
-method supported by the XML-RPC server.
-\end{methoddesc}
-
-\begin{methoddesc}[ServerProxy]{system.methodSignature}{name}
-This method takes one parameter, the name of a method implemented by
-the XML-RPC server.It returns an array of possible signatures for this
-method. A signature is an array of types. The first of these types is
-the return type of the method, the rest are parameters.
-
-Because multiple signatures (ie. overloading) is permitted, this method
-returns a list of signatures rather than a singleton.
-
-Signatures themselves are restricted to the top level parameters
-expected by a method. For instance if a method expects one array of
-structs as a parameter, and it returns a string, its signature is
-simply "string, array". If it expects three integers and returns a
-string, its signature is "string, int, int, int".
-
-If no signature is defined for the method, a non-array value is
-returned. In Python this means that the type of the returned
-value will be something other that list.
-\end{methoddesc}
-
-\begin{methoddesc}[ServerProxy]{system.methodHelp}{name}
-This method takes one parameter, the name of a method implemented by
-the XML-RPC server. It returns a documentation string describing the
-use of that method. If no such string is available, an empty string is
-returned. The documentation string may contain HTML markup.
-\end{methoddesc}
-
-Introspection methods are currently supported by servers written in
-PHP, C and Microsoft .NET. Partial introspection support is included
-in recent updates to UserLand Frontier. Introspection support for
-Perl, Python and Java is available at the \ulink{XML-RPC
-Hacks}{http://xmlrpc-c.sourceforge.net/hacks.php} page.
-
-
-\subsection{Boolean Objects \label{boolean-objects}}
-
-This class may be initialized from any Python value; the instance
-returned depends only on its truth value. It supports various Python
-operators through \method{__cmp__()}, \method{__repr__()},
-\method{__int__()}, and \method{__bool__()} methods, all
-implemented in the obvious ways.
-
-It also has the following method, supported mainly for internal use by
-the unmarshalling code:
-
-\begin{methoddesc}[Boolean]{encode}{out}
-Write the XML-RPC encoding of this Boolean item to the out stream object.
-\end{methoddesc}
-
-
-\subsection{DateTime Objects \label{datetime-objects}}
-
-This class may be initialized with seconds since the epoch, a time tuple, an
-ISO 8601 time/date string, or a {}\class{\refmodule{datetime}.datetime},
-{}\class{\refmodule{datetime}.date} or {}\class{\refmodule{datetime}.time}
-instance. It has the following methods, supported mainly for internal use
-by the marshalling/unmarshalling code:
-
-\begin{methoddesc}[DateTime]{decode}{string}
-Accept a string as the instance's new time value.
-\end{methoddesc}
-
-\begin{methoddesc}[DateTime]{encode}{out}
-Write the XML-RPC encoding of this \class{DateTime} item to the
-\var{out} stream object.
-\end{methoddesc}
-
-It also supports certain of Python's built-in operators through
-\method{__cmp__()} and \method{__repr__()} methods.
-
-
-\subsection{Binary Objects \label{binary-objects}}
-
-This class may be initialized from string data (which may include NULs).
-The primary access to the content of a \class{Binary} object is
-provided by an attribute:
-
-\begin{memberdesc}[Binary]{data}
-The binary data encapsulated by the \class{Binary} instance. The data
-is provided as an 8-bit string.
-\end{memberdesc}
-
-\class{Binary} objects have the following methods, supported mainly
-for internal use by the marshalling/unmarshalling code:
-
-\begin{methoddesc}[Binary]{decode}{string}
-Accept a base64 string and decode it as the instance's new data.
-\end{methoddesc}
-
-\begin{methoddesc}[Binary]{encode}{out}
-Write the XML-RPC base 64 encoding of this binary item to the out
-stream object.
-\end{methoddesc}
-
-It also supports certain of Python's built-in operators through a
-\method{__cmp__()} method.
-
-
-\subsection{Fault Objects \label{fault-objects}}
-
-A \class{Fault} object encapsulates the content of an XML-RPC fault tag.
-Fault objects have the following members:
-
-\begin{memberdesc}[Fault]{faultCode}
-A string indicating the fault type.
-\end{memberdesc}
-
-\begin{memberdesc}[Fault]{faultString}
-A string containing a diagnostic message associated with the fault.
-\end{memberdesc}
-
-
-\subsection{ProtocolError Objects \label{protocol-error-objects}}
-
-A \class{ProtocolError} object describes a protocol error in the
-underlying transport layer (such as a 404 `not found' error if the
-server named by the URI does not exist). It has the following
-members:
-
-\begin{memberdesc}[ProtocolError]{url}
-The URI or URL that triggered the error.
-\end{memberdesc}
-
-\begin{memberdesc}[ProtocolError]{errcode}
-The error code.
-\end{memberdesc}
-
-\begin{memberdesc}[ProtocolError]{errmsg}
-The error message or diagnostic string.
-\end{memberdesc}
-
-\begin{memberdesc}[ProtocolError]{headers}
-A string containing the headers of the HTTP/HTTPS request that
-triggered the error.
-\end{memberdesc}
-
-\subsection{MultiCall Objects}
-
-\versionadded{2.4}
-
-In \url{http://www.xmlrpc.com/discuss/msgReader\%241208}, an approach
-is presented to encapsulate multiple calls to a remote server into a
-single request.
-
-\begin{classdesc}{MultiCall}{server}
-
-Create an object used to boxcar method calls. \var{server} is the
-eventual target of the call. Calls can be made to the result object,
-but they will immediately return \code{None}, and only store the
-call name and parameters in the \class{MultiCall} object. Calling
-the object itself causes all stored calls to be transmitted as
-a single \code{system.multicall} request. The result of this call
-is a generator; iterating over this generator yields the individual
-results.
-
-\end{classdesc}
-
-A usage example of this class is
-
-\begin{verbatim}
-multicall = MultiCall(server_proxy)
-multicall.add(2,3)
-multicall.get_address("Guido")
-add_result, address = multicall()
-\end{verbatim}
-
-\subsection{Convenience Functions}
-
-\begin{funcdesc}{boolean}{value}
-Convert any Python value to one of the XML-RPC Boolean constants,
-\code{True} or \code{False}.
-\end{funcdesc}
-
-\begin{funcdesc}{dumps}{params\optional{, methodname\optional{,
- methodresponse\optional{, encoding\optional{,
- allow_none}}}}}
-Convert \var{params} into an XML-RPC request.
-or into a response if \var{methodresponse} is true.
-\var{params} can be either a tuple of arguments or an instance of the
-\exception{Fault} exception class. If \var{methodresponse} is true,
-only a single value can be returned, meaning that \var{params} must be of length 1.
-\var{encoding}, if supplied, is the encoding to use in the generated
-XML; the default is UTF-8. Python's \constant{None} value cannot be
-used in standard XML-RPC; to allow using it via an extension,
-provide a true value for \var{allow_none}.
-\end{funcdesc}
-
-\begin{funcdesc}{loads}{data\optional{, use_datetime}}
-Convert an XML-RPC request or response into Python objects, a
-\code{(\var{params}, \var{methodname})}. \var{params} is a tuple of argument; \var{methodname}
-is a string, or \code{None} if no method name is present in the packet.
-If the XML-RPC packet represents a fault condition, this
-function will raise a \exception{Fault} exception.
-The \var{use_datetime} flag can be used to cause date/time values to be
-presented as \class{\refmodule{datetime}.datetime} objects; this is false
-by default.
-Note that even if you call an XML-RPC method with
-\class{\refmodule{datetime}.date} or \class{\refmodule{datetime}.time}
-objects, they are converted to \class{DateTime} objects internally, so only
-{}\class{\refmodule{datetime}.datetime} objects will be returned.
-
-\versionchanged[The \var{use_datetime} flag was added]{2.5}
-\end{funcdesc}
-
-
-
-\subsection{Example of Client Usage \label{xmlrpc-client-example}}
-
-\begin{verbatim}
-# simple test program (from the XML-RPC specification)
-from xmlrpclib import ServerProxy, Error
-
-# server = ServerProxy("http://localhost:8000") # local server
-server = ServerProxy("http://betty.userland.com")
-
-print server
-
-try:
- print server.examples.getStateName(41)
-except Error as v:
- print "ERROR", v
-\end{verbatim}
-
-To access an XML-RPC server through a proxy, you need to define
-a custom transport. The following example,
-written by NoboNobo, % fill in original author's name if we ever learn it
-shows how:
-
-% Example taken from http://lowlife.jp/nobonobo/wiki/xmlrpcwithproxy.html
-\begin{verbatim}
-import xmlrpclib, httplib
-
-class ProxiedTransport(xmlrpclib.Transport):
- def set_proxy(self, proxy):
- self.proxy = proxy
- def make_connection(self, host):
- self.realhost = host
- h = httplib.HTTP(self.proxy)
- return h
- def send_request(self, connection, handler, request_body):
- connection.putrequest("POST", 'http://%s%s' % (self.realhost, handler))
- def send_host(self, connection, host):
- connection.putheader('Host', self.realhost)
-
-p = ProxiedTransport()
-p.set_proxy('proxy-server:8080')
-server = xmlrpclib.Server('http://time.xmlrpc.com/RPC2', transport=p)
-print server.currentTime.getCurrentTime()
-\end{verbatim}
diff --git a/Doc/lib/libzipfile.tex b/Doc/lib/libzipfile.tex
deleted file mode 100644
index 366cee9..0000000
--- a/Doc/lib/libzipfile.tex
+++ /dev/null
@@ -1,371 +0,0 @@
-\section{\module{zipfile} ---
- Work with ZIP archives}
-
-\declaremodule{standard}{zipfile}
-\modulesynopsis{Read and write ZIP-format archive files.}
-\moduleauthor{James C. Ahlstrom}{jim@interet.com}
-\sectionauthor{James C. Ahlstrom}{jim@interet.com}
-% LaTeX markup by Fred L. Drake, Jr. <fdrake@acm.org>
-
-\versionadded{1.6}
-
-The ZIP file format is a common archive and compression standard.
-This module provides tools to create, read, write, append, and list a
-ZIP file. Any advanced use of this module will require an
-understanding of the format, as defined in
-\citetitle[http://www.pkware.com/business_and_developers/developer/appnote/]
-{PKZIP Application Note}.
-
-This module does not currently handle ZIP files which have appended
-comments, or multi-disk ZIP files. It can handle ZIP files that use
-the ZIP64 extensions (that is ZIP files that are more than 4 GByte in
-size). It supports decryption of encrypted files in ZIP archives, but
-it cannot currently create an encrypted file.
-
-The available attributes of this module are:
-
-\begin{excdesc}{BadZipfile}
- The error raised for bad ZIP files (old name: \code{zipfile.error}).
-\end{excdesc}
-
-\begin{excdesc}{LargeZipFile}
- The error raised when a ZIP file would require ZIP64 functionality but that
- has not been enabled.
-\end{excdesc}
-
-\begin{classdesc*}{ZipFile}
- The class for reading and writing ZIP files. See
- ``\citetitle{ZipFile Objects}'' (section \ref{zipfile-objects}) for
- constructor details.
-\end{classdesc*}
-
-\begin{classdesc*}{PyZipFile}
- Class for creating ZIP archives containing Python libraries.
-\end{classdesc*}
-
-\begin{classdesc}{ZipInfo}{\optional{filename\optional{, date_time}}}
- Class used to represent information about a member of an archive.
- Instances of this class are returned by the \method{getinfo()} and
- \method{infolist()} methods of \class{ZipFile} objects. Most users
- of the \module{zipfile} module will not need to create these, but
- only use those created by this module.
- \var{filename} should be the full name of the archive member, and
- \var{date_time} should be a tuple containing six fields which
- describe the time of the last modification to the file; the fields
- are described in section \ref{zipinfo-objects}, ``ZipInfo Objects.''
-\end{classdesc}
-
-\begin{funcdesc}{is_zipfile}{filename}
- Returns \code{True} if \var{filename} is a valid ZIP file based on its magic
- number, otherwise returns \code{False}. This module does not currently
- handle ZIP files which have appended comments.
-\end{funcdesc}
-
-\begin{datadesc}{ZIP_STORED}
- The numeric constant for an uncompressed archive member.
-\end{datadesc}
-
-\begin{datadesc}{ZIP_DEFLATED}
- The numeric constant for the usual ZIP compression method. This
- requires the zlib module. No other compression methods are
- currently supported.
-\end{datadesc}
-
-
-\begin{seealso}
- \seetitle[http://www.pkware.com/business_and_developers/developer/appnote/]
- {PKZIP Application Note}{Documentation on the ZIP file format by
- Phil Katz, the creator of the format and algorithms used.}
-
- \seetitle[http://www.info-zip.org/pub/infozip/]{Info-ZIP Home Page}{
- Information about the Info-ZIP project's ZIP archive
- programs and development libraries.}
-\end{seealso}
-
-
-\subsection{ZipFile Objects \label{zipfile-objects}}
-
-\begin{classdesc}{ZipFile}{file\optional{, mode\optional{, compression\optional{, allowZip64}}}}
- Open a ZIP file, where \var{file} can be either a path to a file
- (a string) or a file-like object. The \var{mode} parameter
- should be \code{'r'} to read an existing file, \code{'w'} to
- truncate and write a new file, or \code{'a'} to append to an
- existing file. If \var{mode} is \code{'a'} and \var{file}
- refers to an existing ZIP file, then additional files are added to
- it. If \var{file} does not refer to a ZIP file, then a new ZIP
- archive is appended to the file. This is meant for adding a ZIP
- archive to another file, such as \file{python.exe}. Using
-
-\begin{verbatim}
-cat myzip.zip >> python.exe
-\end{verbatim}
-
- also works, and at least \program{WinZip} can read such files.
- If \var{mode} is \code{a} and the file does not exist at all,
- it is created.
- \var{compression} is the ZIP compression method to use when writing
- the archive, and should be \constant{ZIP_STORED} or
- \constant{ZIP_DEFLATED}; unrecognized values will cause
- \exception{RuntimeError} to be raised. If \constant{ZIP_DEFLATED}
- is specified but the \refmodule{zlib} module is not available,
- \exception{RuntimeError} is also raised. The default is
- \constant{ZIP_STORED}.
- If \var{allowZip64} is \code{True} zipfile will create ZIP files that use
- the ZIP64 extensions when the zipfile is larger than 2 GB. If it is
- false (the default) \module{zipfile} will raise an exception when the
- ZIP file would require ZIP64 extensions. ZIP64 extensions are disabled by
- default because the default \program{zip} and \program{unzip} commands on
- \UNIX{} (the InfoZIP utilities) don't support these extensions.
-
- \versionchanged[If the file does not exist, it is created if the
- mode is 'a']{2.6}
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
- Close the archive file. You must call \method{close()} before
- exiting your program or essential records will not be written.
-\end{methoddesc}
-
-\begin{methoddesc}{getinfo}{name}
- Return a \class{ZipInfo} object with information about the archive
- member \var{name}. Calling \method{getinfo()} for a name not currently
- contained in the archive will raise a \exception{KeyError}.
-\end{methoddesc}
-
-\begin{methoddesc}{infolist}{}
- Return a list containing a \class{ZipInfo} object for each member of
- the archive. The objects are in the same order as their entries in
- the actual ZIP file on disk if an existing archive was opened.
-\end{methoddesc}
-
-\begin{methoddesc}{namelist}{}
- Return a list of archive members by name.
-\end{methoddesc}
-
-\begin{methoddesc}{open}{name\optional{, mode\optional{, pwd}}}
- Extract a member from the archive as a file-like object (ZipExtFile).
- \var{name} is the name of the file in the archive. The \var{mode}
- parameter, if included, must be one of the following: \code{'r'} (the
- default), \code{'U'}, or \code{'rU'}. Choosing \code{'U'} or
- \code{'rU'} will enable universal newline support in the read-only
- object. \var{pwd} is the password used for encrypted files. Calling
- \method{open()} on a closed ZipFile will raise a
- \exception{RuntimeError}.
- \begin{notice}
- The file-like object is read-only and provides the following methods:
- \method{read()}, \method{readline()}, \method{readlines()},
- \method{__iter__()}, \method{next()}.
- \end{notice}
- \begin{notice}
- If the ZipFile was created by passing in a file-like object as the
- first argument to the constructor, then the object returned by
- \method{open()} shares the ZipFile's file pointer. Under these
- circumstances, the object returned by \method{open()} should not
- be used after any additional operations are performed on the
- ZipFile object. If the ZipFile was created by passing in a string
- (the filename) as the first argument to the constructor, then
- \method{open()} will create a new file object that will be held
- by the ZipExtFile, allowing it to operate independently of the
- ZipFile.
- \end{notice}
-
- \versionadded{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}{printdir}{}
- Print a table of contents for the archive to \code{sys.stdout}.
-\end{methoddesc}
-
-\begin{methoddesc}{setpassword}{pwd}
- Set \var{pwd} as default password to extract encrypted files.
- \versionadded{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}{read}{name\optional{, pwd}}
- Return the bytes of the file in the archive. The archive must be
- open for read or append. \var{pwd} is the password used for encrypted
- files and, if specified, it will override the default password set with
- \method{setpassword()}. Calling \method{read()} on a closed ZipFile
- will raise a \exception{RuntimeError}.
-
- \versionchanged[\var{pwd} was added]{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}{testzip}{}
- Read all the files in the archive and check their CRC's and file
- headers. Return the name of the first bad file, or else return \code{None}.
- Calling \method{testzip()} on a closed ZipFile will raise a
- \exception{RuntimeError}.
-\end{methoddesc}
-
-\begin{methoddesc}{write}{filename\optional{, arcname\optional{,
- compress_type}}}
- Write the file named \var{filename} to the archive, giving it the
- archive name \var{arcname} (by default, this will be the same as
- \var{filename}, but without a drive letter and with leading path
- separators removed). If given, \var{compress_type} overrides the
- value given for the \var{compression} parameter to the constructor
- for the new entry. The archive must be open with mode \code{'w'}
- or \code{'a'} -- calling \method{write()} on a ZipFile created with
- mode \code{'r'} will raise a \exception{RuntimeError}. Calling
- \method{write()} on a closed ZipFile will raise a
- \exception{RuntimeError}.
-
- \note{There is no official file name encoding for ZIP files.
- If you have unicode file names, please convert them to byte strings
- in your desired encoding before passing them to \method{write()}.
- WinZip interprets all file names as encoded in CP437, also known
- as DOS Latin.}
-
- \note{Archive names should be relative to the archive root, that is,
- they should not start with a path separator.}
-
- \note{If \code{arcname} (or \code{filename}, if \code{arcname} is
- not given) contains a null byte, the name of the file in the archive will
- be truncated at the null byte.}
-
-\end{methoddesc}
-
-\begin{methoddesc}{writestr}{zinfo_or_arcname, bytes}
- Write the string \var{bytes} to the archive; \var{zinfo_or_arcname}
- is either the file name it will be given in the archive, or a
- \class{ZipInfo} instance. If it's an instance, at least the
- filename, date, and time must be given. If it's a name, the date
- and time is set to the current date and time. The archive must be
- opened with mode \code{'w'} or \code{'a'} -- calling
- \method{writestr()} on a ZipFile created with mode \code{'r'}
- will raise a \exception{RuntimeError}. Calling \method{writestr()}
- on a closed ZipFile will raise a \exception{RuntimeError}.
-\end{methoddesc}
-
-
-The following data attribute is also available:
-
-\begin{memberdesc}{debug}
- The level of debug output to use. This may be set from \code{0}
- (the default, no output) to \code{3} (the most output). Debugging
- information is written to \code{sys.stdout}.
-\end{memberdesc}
-
-
-\subsection{PyZipFile Objects \label{pyzipfile-objects}}
-
-The \class{PyZipFile} constructor takes the same parameters as the
-\class{ZipFile} constructor. Instances have one method in addition to
-those of \class{ZipFile} objects.
-
-\begin{methoddesc}[PyZipFile]{writepy}{pathname\optional{, basename}}
- Search for files \file{*.py} and add the corresponding file to the
- archive. The corresponding file is a \file{*.pyo} file if
- available, else a \file{*.pyc} file, compiling if necessary. If the
- pathname is a file, the filename must end with \file{.py}, and just
- the (corresponding \file{*.py[co]}) file is added at the top level
- (no path information). If the pathname is a file that does not end with
- \file{.py}, a \exception{RuntimeError} will be raised. If it is a
- directory, and the directory is not a package directory, then all the
- files \file{*.py[co]} are added at the top level. If the directory is
- a package directory, then all \file{*.py[co]} are added under the package
- name as a file path, and if any subdirectories are package directories, all
- of these are added recursively. \var{basename} is intended for
- internal use only. The \method{writepy()} method makes archives
- with file names like this:
-
-\begin{verbatim}
- string.pyc # Top level name
- test/__init__.pyc # Package directory
- test/testall.pyc # Module test.testall
- test/bogus/__init__.pyc # Subpackage directory
- test/bogus/myfile.pyc # Submodule test.bogus.myfile
-\end{verbatim}
-\end{methoddesc}
-
-
-\subsection{ZipInfo Objects \label{zipinfo-objects}}
-
-Instances of the \class{ZipInfo} class are returned by the
-\method{getinfo()} and \method{infolist()} methods of
-\class{ZipFile} objects. Each object stores information about a
-single member of the ZIP archive.
-
-Instances have the following attributes:
-
-\begin{memberdesc}[ZipInfo]{filename}
- Name of the file in the archive.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{date_time}
- The time and date of the last modification to the archive
- member. This is a tuple of six values:
-
-\begin{tableii}{c|l}{code}{Index}{Value}
- \lineii{0}{Year}
- \lineii{1}{Month (one-based)}
- \lineii{2}{Day of month (one-based)}
- \lineii{3}{Hours (zero-based)}
- \lineii{4}{Minutes (zero-based)}
- \lineii{5}{Seconds (zero-based)}
-\end{tableii}
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{compress_type}
- Type of compression for the archive member.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{comment}
- Comment for the individual archive member.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{extra}
- Expansion field data. The
- \citetitle[http://www.pkware.com/business_and_developers/developer/appnote/]
- {PKZIP Application Note} contains some comments on the internal
- structure of the data contained in this string.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{create_system}
- System which created ZIP archive.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{create_version}
- PKZIP version which created ZIP archive.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{extract_version}
- PKZIP version needed to extract archive.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{reserved}
- Must be zero.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{flag_bits}
- ZIP flag bits.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{volume}
- Volume number of file header.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{internal_attr}
- Internal attributes.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{external_attr}
- External file attributes.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{header_offset}
- Byte offset to the file header.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{CRC}
- CRC-32 of the uncompressed file.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{compress_size}
- Size of the compressed data.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{file_size}
- Size of the uncompressed file.
-\end{memberdesc}
diff --git a/Doc/lib/libzipimport.tex b/Doc/lib/libzipimport.tex
deleted file mode 100644
index 8ebe3c5..0000000
--- a/Doc/lib/libzipimport.tex
+++ /dev/null
@@ -1,128 +0,0 @@
-\section{\module{zipimport} ---
- Import modules from Zip archives}
-
-\declaremodule{standard}{zipimport}
-\modulesynopsis{support for importing Python modules from ZIP archives.}
-\moduleauthor{Just van Rossum}{just@letterror.com}
-
-\versionadded{2.3}
-
-This module adds the ability to import Python modules (\file{*.py},
-\file{*.py[co]}) and packages from ZIP-format archives. It is usually
-not needed to use the \module{zipimport} module explicitly; it is
-automatically used by the builtin \keyword{import} mechanism for
-\code{sys.path} items that are paths to ZIP archives.
-
-Typically, \code{sys.path} is a list of directory names as strings. This
-module also allows an item of \code{sys.path} to be a string naming a ZIP
-file archive. The ZIP archive can contain a subdirectory structure to
-support package imports, and a path within the archive can be specified to
-only import from a subdirectory. For example, the path
-\file{/tmp/example.zip/lib/} would only import from the
-\file{lib/} subdirectory within the archive.
-
-Any files may be present in the ZIP archive, but only files \file{.py} and
-\file{.py[co]} are available for import. ZIP import of dynamic modules
-(\file{.pyd}, \file{.so}) is disallowed. Note that if an archive only
-contains \file{.py} files, Python will not attempt to modify the archive
-by adding the corresponding \file{.pyc} or \file{.pyo} file, meaning that
-if a ZIP archive doesn't contain \file{.pyc} files, importing may be rather
-slow.
-
-The available attributes of this module are:
-
-\begin{excdesc}{ZipImportError}
- Exception raised by zipimporter objects. It's a subclass of
- \exception{ImportError}, so it can be caught as \exception{ImportError},
- too.
-\end{excdesc}
-
-\begin{classdesc*}{zipimporter}
- The class for importing ZIP files. See
- ``\citetitle{zipimporter Objects}'' (section \ref{zipimporter-objects})
- for constructor details.
-\end{classdesc*}
-
-
-\begin{seealso}
- \seetitle[http://www.pkware.com/business_and_developers/developer/appnote/]
- {PKZIP Application Note}{Documentation on the ZIP file format by
- Phil Katz, the creator of the format and algorithms used.}
-
- \seepep{0273}{Import Modules from Zip Archives}{Written by James C.
- Ahlstrom, who also provided an implementation. Python 2.3
- follows the specification in PEP 273, but uses an
- implementation written by Just van Rossum that uses the import
- hooks described in PEP 302.}
-
- \seepep{0302}{New Import Hooks}{The PEP to add the import hooks that help
- this module work.}
-\end{seealso}
-
-
-\subsection{zipimporter Objects \label{zipimporter-objects}}
-
-\begin{classdesc}{zipimporter}{archivepath}
- Create a new zipimporter instance. \var{archivepath} must be a path to
- a zipfile. \exception{ZipImportError} is raised if \var{archivepath}
- doesn't point to a valid ZIP archive.
-\end{classdesc}
-
-\begin{methoddesc}{find_module}{fullname\optional{, path}}
- Search for a module specified by \var{fullname}. \var{fullname} must be
- the fully qualified (dotted) module name. It returns the zipimporter
- instance itself if the module was found, or \constant{None} if it wasn't.
- The optional \var{path} argument is ignored---it's there for
- compatibility with the importer protocol.
-\end{methoddesc}
-
-\begin{methoddesc}{get_code}{fullname}
- Return the code object for the specified module. Raise
- \exception{ZipImportError} if the module couldn't be found.
-\end{methoddesc}
-
-\begin{methoddesc}{get_data}{pathname}
- Return the data associated with \var{pathname}. Raise \exception{IOError}
- if the file wasn't found.
-\end{methoddesc}
-
-\begin{methoddesc}{get_source}{fullname}
- Return the source code for the specified module. Raise
- \exception{ZipImportError} if the module couldn't be found, return
- \constant{None} if the archive does contain the module, but has
- no source for it.
-\end{methoddesc}
-
-\begin{methoddesc}{is_package}{fullname}
- Return True if the module specified by \var{fullname} is a package.
- Raise \exception{ZipImportError} if the module couldn't be found.
-\end{methoddesc}
-
-\begin{methoddesc}{load_module}{fullname}
- Load the module specified by \var{fullname}. \var{fullname} must be the
- fully qualified (dotted) module name. It returns the imported
- module, or raises \exception{ZipImportError} if it wasn't found.
-\end{methoddesc}
-
-\subsection{Examples}
-\nodename{zipimport Examples}
-
-Here is an example that imports a module from a ZIP archive - note that
-the \module{zipimport} module is not explicitly used.
-
-\begin{verbatim}
-$ unzip -l /tmp/example.zip
-Archive: /tmp/example.zip
- Length Date Time Name
- -------- ---- ---- ----
- 8467 11-26-02 22:30 jwzthreading.py
- -------- -------
- 8467 1 file
-$ ./python
-Python 2.3 (#1, Aug 1 2003, 19:54:32)
->>> import sys
->>> sys.path.insert(0, '/tmp/example.zip') # Add .zip file to front of path
->>> import jwzthreading
->>> jwzthreading.__file__
-'/tmp/example.zip/jwzthreading.py'
-\end{verbatim}
diff --git a/Doc/lib/libzlib.tex b/Doc/lib/libzlib.tex
deleted file mode 100644
index 3cc7b3c..0000000
--- a/Doc/lib/libzlib.tex
+++ /dev/null
@@ -1,197 +0,0 @@
-\section{\module{zlib} ---
- Compression compatible with \program{gzip}}
-
-\declaremodule{builtin}{zlib}
-\modulesynopsis{Low-level interface to compression and decompression
- routines compatible with \program{gzip}.}
-
-
-For applications that require data compression, the functions in this
-module allow compression and decompression, using the zlib library.
-The zlib library has its own home page at \url{http://www.zlib.net}.
-There are known incompatibilities between the Python module and
-versions of the zlib library earlier than 1.1.3; 1.1.3 has a security
-vulnerability, so we recommend using 1.1.4 or later.
-
-zlib's functions have many options and often need to be used in a
-particular order. This documentation doesn't attempt to cover all of
-the permutations; consult the zlib manual at
-\url{http://www.zlib.net/manual.html} for authoritative information.
-
-The available exception and functions in this module are:
-
-\begin{excdesc}{error}
- Exception raised on compression and decompression errors.
-\end{excdesc}
-
-
-\begin{funcdesc}{adler32}{string\optional{, value}}
- Computes a Adler-32 checksum of \var{string}. (An Adler-32
- checksum is almost as reliable as a CRC32 but can be computed much
- more quickly.) If \var{value} is present, it is used as the
- starting value of the checksum; otherwise, a fixed default value is
- used. This allows computing a running checksum over the
- concatenation of several input strings. The algorithm is not
- cryptographically strong, and should not be used for
- authentication or digital signatures. Since the algorithm is
- designed for use as a checksum algorithm, it is not suitable for
- use as a general hash algorithm.
-\end{funcdesc}
-
-\begin{funcdesc}{compress}{string\optional{, level}}
- Compresses the data in \var{string}, returning a string contained
- compressed data. \var{level} is an integer from \code{1} to
- \code{9} controlling the level of compression; \code{1} is fastest
- and produces the least compression, \code{9} is slowest and produces
- the most. The default value is \code{6}. Raises the
- \exception{error} exception if any error occurs.
-\end{funcdesc}
-
-\begin{funcdesc}{compressobj}{\optional{level}}
- Returns a compression object, to be used for compressing data streams
- that won't fit into memory at once. \var{level} is an integer from
- \code{1} to \code{9} controlling the level of compression; \code{1} is
- fastest and produces the least compression, \code{9} is slowest and
- produces the most. The default value is \code{6}.
-\end{funcdesc}
-
-\begin{funcdesc}{crc32}{string\optional{, value}}
- Computes a CRC (Cyclic Redundancy Check)%
- \index{Cyclic Redundancy Check}
- \index{checksum!Cyclic Redundancy Check}
- checksum of \var{string}. If
- \var{value} is present, it is used as the starting value of the
- checksum; otherwise, a fixed default value is used. This allows
- computing a running checksum over the concatenation of several
- input strings. The algorithm is not cryptographically strong, and
- should not be used for authentication or digital signatures. Since
- the algorithm is designed for use as a checksum algorithm, it is not
- suitable for use as a general hash algorithm.
-\end{funcdesc}
-
-\begin{funcdesc}{decompress}{string\optional{, wbits\optional{, bufsize}}}
- Decompresses the data in \var{string}, returning a string containing
- the uncompressed data. The \var{wbits} parameter controls the size of
- the window buffer. If \var{bufsize} is given, it is used as the
- initial size of the output buffer. Raises the \exception{error}
- exception if any error occurs.
-
-The absolute value of \var{wbits} is the base two logarithm of the
-size of the history buffer (the ``window size'') used when compressing
-data. Its absolute value should be between 8 and 15 for the most
-recent versions of the zlib library, larger values resulting in better
-compression at the expense of greater memory usage. The default value
-is 15. When \var{wbits} is negative, the standard
-\program{gzip} header is suppressed; this is an undocumented feature
-of the zlib library, used for compatibility with \program{unzip}'s
-compression file format.
-
-\var{bufsize} is the initial size of the buffer used to hold
-decompressed data. If more space is required, the buffer size will be
-increased as needed, so you don't have to get this value exactly
-right; tuning it will only save a few calls to \cfunction{malloc()}. The
-default size is 16384.
-
-\end{funcdesc}
-
-\begin{funcdesc}{decompressobj}{\optional{wbits}}
- Returns a decompression object, to be used for decompressing data
- streams that won't fit into memory at once. The \var{wbits}
- parameter controls the size of the window buffer.
-\end{funcdesc}
-
-Compression objects support the following methods:
-
-\begin{methoddesc}[Compress]{compress}{string}
-Compress \var{string}, returning a string containing compressed data
-for at least part of the data in \var{string}. This data should be
-concatenated to the output produced by any preceding calls to the
-\method{compress()} method. Some input may be kept in internal buffers
-for later processing.
-\end{methoddesc}
-
-\begin{methoddesc}[Compress]{flush}{\optional{mode}}
-All pending input is processed, and a string containing the remaining
-compressed output is returned. \var{mode} can be selected from the
-constants \constant{Z_SYNC_FLUSH}, \constant{Z_FULL_FLUSH}, or
-\constant{Z_FINISH}, defaulting to \constant{Z_FINISH}. \constant{Z_SYNC_FLUSH} and
-\constant{Z_FULL_FLUSH} allow compressing further strings of data, while
-\constant{Z_FINISH} finishes the compressed stream and
-prevents compressing any more data. After calling
-\method{flush()} with \var{mode} set to \constant{Z_FINISH}, the
-\method{compress()} method cannot be called again; the only realistic
-action is to delete the object.
-\end{methoddesc}
-
-\begin{methoddesc}[Compress]{copy}{}
-Returns a copy of the compression object. This can be used to efficiently
-compress a set of data that share a common initial prefix.
-\versionadded{2.5}
-\end{methoddesc}
-
-Decompression objects support the following methods, and two attributes:
-
-\begin{memberdesc}[Decompress]{unused_data}
-A string which contains any bytes past the end of the compressed data.
-That is, this remains \code{""} until the last byte that contains
-compression data is available. If the whole string turned out to
-contain compressed data, this is \code{""}, the empty string.
-
-The only way to determine where a string of compressed data ends is by
-actually decompressing it. This means that when compressed data is
-contained part of a larger file, you can only find the end of it by
-reading data and feeding it followed by some non-empty string into a
-decompression object's \method{decompress} method until the
-\member{unused_data} attribute is no longer the empty string.
-\end{memberdesc}
-
-\begin{memberdesc}[Decompress]{unconsumed_tail}
-A string that contains any data that was not consumed by the last
-\method{decompress} call because it exceeded the limit for the
-uncompressed data buffer. This data has not yet been seen by the zlib
-machinery, so you must feed it (possibly with further data
-concatenated to it) back to a subsequent \method{decompress} method
-call in order to get correct output.
-\end{memberdesc}
-
-
-\begin{methoddesc}[Decompress]{decompress}{string\optional{, max_length}}
-Decompress \var{string}, returning a string containing the
-uncompressed data corresponding to at least part of the data in
-\var{string}. This data should be concatenated to the output produced
-by any preceding calls to the
-\method{decompress()} method. Some of the input data may be preserved
-in internal buffers for later processing.
-
-If the optional parameter \var{max_length} is supplied then the return value
-will be no longer than \var{max_length}. This may mean that not all of the
-compressed input can be processed; and unconsumed data will be stored
-in the attribute \member{unconsumed_tail}. This string must be passed
-to a subsequent call to \method{decompress()} if decompression is to
-continue. If \var{max_length} is not supplied then the whole input is
-decompressed, and \member{unconsumed_tail} is an empty string.
-\end{methoddesc}
-
-\begin{methoddesc}[Decompress]{flush}{\optional{length}}
-All pending input is processed, and a string containing the remaining
-uncompressed output is returned. After calling \method{flush()}, the
-\method{decompress()} method cannot be called again; the only realistic
-action is to delete the object.
-
-The optional parameter \var{length} sets the initial size of the
-output buffer.
-\end{methoddesc}
-
-\begin{methoddesc}[Decompress]{copy}{}
-Returns a copy of the decompression object. This can be used to save the
-state of the decompressor midway through the data stream in order to speed up
-random seeks into the stream at a future point.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{seealso}
- \seemodule{gzip}{Reading and writing \program{gzip}-format files.}
- \seeurl{http://www.zlib.net}{The zlib library home page.}
- \seeurl{http://www.zlib.net/manual.html}{The zlib manual explains
- the semantics and usage of the library's many functions.}
-\end{seealso}
diff --git a/Doc/lib/markup.tex b/Doc/lib/markup.tex
deleted file mode 100644
index 0d923a7..0000000
--- a/Doc/lib/markup.tex
+++ /dev/null
@@ -1,29 +0,0 @@
-\chapter{Structured Markup Processing Tools
- \label{markup}}
-
-Python supports a variety of modules to work with various forms of
-structured data markup. This includes modules to work with the
-Standard Generalized Markup Language (SGML) and the Hypertext Markup
-Language (HTML), and several interfaces for working with the
-Extensible Markup Language (XML).
-
-It is important to note that modules in the \module{xml} package
-require that there be at least one SAX-compliant XML parser available.
-Starting with Python 2.3, the Expat parser is included with Python, so
-the \refmodule{xml.parsers.expat} module will always be available.
-You may still want to be aware of the \ulink{PyXML add-on
-package}{http://pyxml.sourceforge.net/}; that package provides an
-extended set of XML libraries for Python.
-
-The documentation for the \module{xml.dom} and \module{xml.sax}
-packages are the definition of the Python bindings for the DOM and SAX
-interfaces.
-
-\localmoduletable
-
-\begin{seealso}
- \seetitle[http://pyxml.sourceforge.net/]
- {Python/XML Libraries}
- {Home page for the PyXML package, containing an extension
- of \module{xml} package bundled with Python.}
-\end{seealso}
diff --git a/Doc/lib/mimelib.tex b/Doc/lib/mimelib.tex
deleted file mode 100644
index 491d844..0000000
--- a/Doc/lib/mimelib.tex
+++ /dev/null
@@ -1,65 +0,0 @@
-% This document is largely a stub used to allow the email package docs
-% to be formatted separately from the rest of the Python
-% documentation. This allows the documentation to be released
-% independently of the rest of Python since the email package is being
-% maintained for multiple Python versions, and on an accelerated
-% schedule.
-
-\documentclass{howto}
-
-\title{email Package Reference}
-\author{Barry Warsaw}
-\authoraddress{\email{barry@python.org}}
-
-\date{\today}
-\release{4.0} % software release, not documentation
-\setreleaseinfo{} % empty for final release
-\setshortversion{4.0} % major.minor only for software
-
-\begin{document}
-
-\maketitle
-
-\begin{abstract}
- The \module{email} package provides classes and utilities to create,
- parse, generate, and modify email messages, conforming to all the
- relevant email and MIME related RFCs.
-\end{abstract}
-
-% The ugly "%begin{latexonly}" pseudo-environment suppresses the table
-% of contents for HTML generation.
-%
-%begin{latexonly}
-\tableofcontents
-%end{latexonly}
-
-\section{Introduction}
-The \module{email} package provides classes and utilities to create,
-parse, generate, and modify email messages, conforming to all the
-relevant email and MIME related RFCs.
-
-This document describes version 4.0 of the \module{email} package, which is
-distributed with Python 2.5 and is available as a standalone distutils-based
-package for use with earlier Python versions. \module{email} 4.0 is not
-compatible with Python versions earlier than 2.3. For more information about
-the \module{email} package, including download links and mailing lists, see
-\ulink{Python's email SIG}{http://www.python.org/sigs/email-sig}.
-
-The documentation that follows was written for the Python project, so
-if you're reading this as part of the standalone \module{email}
-package documentation, there are a few notes to be aware of:
-
-\begin{itemize}
-\item Deprecation and ``version added'' notes are relative to the
- Python version a feature was added or deprecated. See
- the package history in section \ref{email-pkg-history} for details.
-
-\item If you're reading this documentation as part of the
- standalone \module{email} package, some of the internal links to
- other sections of the Python standard library may not resolve.
-
-\end{itemize}
-
-\input{email}
-
-\end{document}
diff --git a/Doc/lib/minidom-example.py b/Doc/lib/minidom-example.py
deleted file mode 100644
index c30c4e0..0000000
--- a/Doc/lib/minidom-example.py
+++ /dev/null
@@ -1,64 +0,0 @@
-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)
diff --git a/Doc/lib/modules.tex b/Doc/lib/modules.tex
deleted file mode 100644
index e23d051..0000000
--- a/Doc/lib/modules.tex
+++ /dev/null
@@ -1,9 +0,0 @@
-\chapter{Importing Modules}
-\label{modules}
-
-The modules described in this chapter provide new ways to import other
-Python modules and hooks for customizing the import process.
-
-The full list of modules described in this chapter is:
-
-\localmoduletable
diff --git a/Doc/lib/netdata.tex b/Doc/lib/netdata.tex
deleted file mode 100644
index 08062d0..0000000
--- a/Doc/lib/netdata.tex
+++ /dev/null
@@ -1,6 +0,0 @@
-\chapter{Internet Data Handling \label{netdata}}
-
-This chapter describes modules which support handling data formats
-commonly used on the Internet.
-
-\localmoduletable
diff --git a/Doc/lib/numeric.tex b/Doc/lib/numeric.tex
deleted file mode 100644
index a9a9e18..0000000
--- a/Doc/lib/numeric.tex
+++ /dev/null
@@ -1,13 +0,0 @@
-\chapter{Numeric and Mathematical Modules}
-\label{numeric}
-
-The modules described in this chapter provide
-numeric and math-related functions and data types.
-The \module{math} and \module{cmath} contain
-various mathematical functions for floating-point and complex numbers.
-For users more interested in decimal accuracy than in speed, the
-\module{decimal} module supports exact representations of decimal numbers.
-
-The following modules are documented in this chapter:
-
-\localmoduletable
diff --git a/Doc/lib/persistence.tex b/Doc/lib/persistence.tex
deleted file mode 100644
index 0bcdad2..0000000
--- a/Doc/lib/persistence.tex
+++ /dev/null
@@ -1,15 +0,0 @@
-\chapter{Data Persistence}
-\label{persistence}
-
-The modules described in this chapter support storing Python data in a
-persistent form on disk. The \module{pickle} and \module{marshal}
-modules can turn many Python data types into a stream of bytes and
-then recreate the objects from the bytes. The various DBM-related
-modules support a family of hash-based file formats that store a
-mapping of strings to other strings. The \module{bsddb} module also
-provides such disk-based string-to-string mappings based on hashing,
-and also supports B-Tree and record-based formats.
-
-The list of modules described in this chapter is:
-
-\localmoduletable
diff --git a/Doc/lib/required_1.py b/Doc/lib/required_1.py
deleted file mode 100755
index 6be5668..0000000
--- a/Doc/lib/required_1.py
+++ /dev/null
@@ -1,20 +0,0 @@
-import optparse
-
-class OptionParser (optparse.OptionParser):
-
- def check_required (self, opt):
- option = self.get_option(opt)
-
- # Assumes the option's 'default' is set to None!
- if getattr(self.values, option.dest) is None:
- self.error("%s option not supplied" % option)
-
-
-parser = OptionParser()
-parser.add_option("-v", action="count", dest="verbose")
-parser.add_option("-f", "--file", default=None)
-(options, args) = parser.parse_args()
-
-print "verbose:", options.verbose
-print "file:", options.file
-parser.check_required("-f")
diff --git a/Doc/lib/required_2.py b/Doc/lib/required_2.py
deleted file mode 100755
index 421514a..0000000
--- a/Doc/lib/required_2.py
+++ /dev/null
@@ -1,41 +0,0 @@
-import optparse
-
-class Option (optparse.Option):
- ATTRS = optparse.Option.ATTRS + ['required']
-
- def _check_required (self):
- if self.required and not self.takes_value():
- raise OptionError(
- "required flag set for option that doesn't take a value",
- self)
-
- # Make sure _check_required() is called from the constructor!
- CHECK_METHODS = optparse.Option.CHECK_METHODS + [_check_required]
-
- def process (self, opt, value, values, parser):
- optparse.Option.process(self, opt, value, values, parser)
- parser.option_seen[self] = 1
-
-
-class OptionParser (optparse.OptionParser):
-
- def _init_parsing_state (self):
- optparse.OptionParser._init_parsing_state(self)
- self.option_seen = {}
-
- def check_values (self, values, args):
- for option in self.option_list:
- if (isinstance(option, Option) and
- option.required and
- not self.option_seen.has_key(option)):
- self.error("%s not supplied" % option)
- return (values, args)
-
-
-parser = OptionParser(option_list=[
- Option("-v", action="count", dest="verbose"),
- Option("-f", "--file", required=1)])
-(options, args) = parser.parse_args()
-
-print "verbose:", options.verbose
-print "file:", options.file
diff --git a/Doc/lib/sqlite3/adapter_datetime.py b/Doc/lib/sqlite3/adapter_datetime.py
deleted file mode 100644
index 5869e22..0000000
--- a/Doc/lib/sqlite3/adapter_datetime.py
+++ /dev/null
@@ -1,14 +0,0 @@
-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])
diff --git a/Doc/lib/sqlite3/adapter_point_1.py b/Doc/lib/sqlite3/adapter_point_1.py
deleted file mode 100644
index 1343acd..0000000
--- a/Doc/lib/sqlite3/adapter_point_1.py
+++ /dev/null
@@ -1,16 +0,0 @@
-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])
diff --git a/Doc/lib/sqlite3/adapter_point_2.py b/Doc/lib/sqlite3/adapter_point_2.py
deleted file mode 100644
index 1e1719a..0000000
--- a/Doc/lib/sqlite3/adapter_point_2.py
+++ /dev/null
@@ -1,17 +0,0 @@
-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])
diff --git a/Doc/lib/sqlite3/collation_reverse.py b/Doc/lib/sqlite3/collation_reverse.py
deleted file mode 100644
index bfd7f5b..0000000
--- a/Doc/lib/sqlite3/collation_reverse.py
+++ /dev/null
@@ -1,15 +0,0 @@
-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()
diff --git a/Doc/lib/sqlite3/complete_statement.py b/Doc/lib/sqlite3/complete_statement.py
deleted file mode 100644
index cd38d73..0000000
--- a/Doc/lib/sqlite3/complete_statement.py
+++ /dev/null
@@ -1,30 +0,0 @@
-# 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 = 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 as e:
- print("An error occurred:", e.args[0])
- buffer = ""
-
-con.close()
diff --git a/Doc/lib/sqlite3/connect_db_1.py b/Doc/lib/sqlite3/connect_db_1.py
deleted file mode 100644
index 1b97523..0000000
--- a/Doc/lib/sqlite3/connect_db_1.py
+++ /dev/null
@@ -1,3 +0,0 @@
-import sqlite3
-
-con = sqlite3.connect("mydb")
diff --git a/Doc/lib/sqlite3/connect_db_2.py b/Doc/lib/sqlite3/connect_db_2.py
deleted file mode 100644
index f9728b3..0000000
--- a/Doc/lib/sqlite3/connect_db_2.py
+++ /dev/null
@@ -1,3 +0,0 @@
-import sqlite3
-
-con = sqlite3.connect(":memory:")
diff --git a/Doc/lib/sqlite3/converter_point.py b/Doc/lib/sqlite3/converter_point.py
deleted file mode 100644
index d0707ab..0000000
--- a/Doc/lib/sqlite3/converter_point.py
+++ /dev/null
@@ -1,47 +0,0 @@
-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 = list(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()
diff --git a/Doc/lib/sqlite3/countcursors.py b/Doc/lib/sqlite3/countcursors.py
deleted file mode 100644
index ef3e70a..0000000
--- a/Doc/lib/sqlite3/countcursors.py
+++ /dev/null
@@ -1,15 +0,0 @@
-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)
diff --git a/Doc/lib/sqlite3/createdb.py b/Doc/lib/sqlite3/createdb.py
deleted file mode 100644
index ee2950b..0000000
--- a/Doc/lib/sqlite3/createdb.py
+++ /dev/null
@@ -1,28 +0,0 @@
-# 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()
diff --git a/Doc/lib/sqlite3/execsql_fetchonerow.py b/Doc/lib/sqlite3/execsql_fetchonerow.py
deleted file mode 100644
index 078873b..0000000
--- a/Doc/lib/sqlite3/execsql_fetchonerow.py
+++ /dev/null
@@ -1,17 +0,0 @@
-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]))
diff --git a/Doc/lib/sqlite3/execsql_printall_1.py b/Doc/lib/sqlite3/execsql_printall_1.py
deleted file mode 100644
index a4ce5c5..0000000
--- a/Doc/lib/sqlite3/execsql_printall_1.py
+++ /dev/null
@@ -1,13 +0,0 @@
-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())
diff --git a/Doc/lib/sqlite3/execute_1.py b/Doc/lib/sqlite3/execute_1.py
deleted file mode 100644
index 3d08840..0000000
--- a/Doc/lib/sqlite3/execute_1.py
+++ /dev/null
@@ -1,11 +0,0 @@
-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())
diff --git a/Doc/lib/sqlite3/execute_2.py b/Doc/lib/sqlite3/execute_2.py
deleted file mode 100644
index 84734f9..0000000
--- a/Doc/lib/sqlite3/execute_2.py
+++ /dev/null
@@ -1,12 +0,0 @@
-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())
diff --git a/Doc/lib/sqlite3/execute_3.py b/Doc/lib/sqlite3/execute_3.py
deleted file mode 100644
index 0353683..0000000
--- a/Doc/lib/sqlite3/execute_3.py
+++ /dev/null
@@ -1,12 +0,0 @@
-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())
diff --git a/Doc/lib/sqlite3/executemany_1.py b/Doc/lib/sqlite3/executemany_1.py
deleted file mode 100644
index efae106..0000000
--- a/Doc/lib/sqlite3/executemany_1.py
+++ /dev/null
@@ -1,24 +0,0 @@
-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())
diff --git a/Doc/lib/sqlite3/executemany_2.py b/Doc/lib/sqlite3/executemany_2.py
deleted file mode 100644
index 518cd94..0000000
--- a/Doc/lib/sqlite3/executemany_2.py
+++ /dev/null
@@ -1,15 +0,0 @@
-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())
diff --git a/Doc/lib/sqlite3/executescript.py b/Doc/lib/sqlite3/executescript.py
deleted file mode 100644
index 7e53581..0000000
--- a/Doc/lib/sqlite3/executescript.py
+++ /dev/null
@@ -1,24 +0,0 @@
-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
- );
- """)
diff --git a/Doc/lib/sqlite3/insert_more_people.py b/Doc/lib/sqlite3/insert_more_people.py
deleted file mode 100644
index edbc79e..0000000
--- a/Doc/lib/sqlite3/insert_more_people.py
+++ /dev/null
@@ -1,16 +0,0 @@
-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()
diff --git a/Doc/lib/sqlite3/md5func.py b/Doc/lib/sqlite3/md5func.py
deleted file mode 100644
index b7bc05b..0000000
--- a/Doc/lib/sqlite3/md5func.py
+++ /dev/null
@@ -1,11 +0,0 @@
-import sqlite3
-import hashlib
-
-def md5sum(t):
- return hashlib.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])
diff --git a/Doc/lib/sqlite3/mysumaggr.py b/Doc/lib/sqlite3/mysumaggr.py
deleted file mode 100644
index d2dfd2c..0000000
--- a/Doc/lib/sqlite3/mysumaggr.py
+++ /dev/null
@@ -1,20 +0,0 @@
-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])
diff --git a/Doc/lib/sqlite3/parse_colnames.py b/Doc/lib/sqlite3/parse_colnames.py
deleted file mode 100644
index cc68c76..0000000
--- a/Doc/lib/sqlite3/parse_colnames.py
+++ /dev/null
@@ -1,8 +0,0 @@
-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))
diff --git a/Doc/lib/sqlite3/pysqlite_datetime.py b/Doc/lib/sqlite3/pysqlite_datetime.py
deleted file mode 100644
index 68d4935..0000000
--- a/Doc/lib/sqlite3/pysqlite_datetime.py
+++ /dev/null
@@ -1,20 +0,0 @@
-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]))
diff --git a/Doc/lib/sqlite3/row_factory.py b/Doc/lib/sqlite3/row_factory.py
deleted file mode 100644
index e436ffc..0000000
--- a/Doc/lib/sqlite3/row_factory.py
+++ /dev/null
@@ -1,13 +0,0 @@
-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"])
diff --git a/Doc/lib/sqlite3/rowclass.py b/Doc/lib/sqlite3/rowclass.py
deleted file mode 100644
index 3fa0b87..0000000
--- a/Doc/lib/sqlite3/rowclass.py
+++ /dev/null
@@ -1,12 +0,0 @@
-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"]
diff --git a/Doc/lib/sqlite3/shared_cache.py b/Doc/lib/sqlite3/shared_cache.py
deleted file mode 100644
index bf1d7b4..0000000
--- a/Doc/lib/sqlite3/shared_cache.py
+++ /dev/null
@@ -1,6 +0,0 @@
-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)
diff --git a/Doc/lib/sqlite3/shortcut_methods.py b/Doc/lib/sqlite3/shortcut_methods.py
deleted file mode 100644
index 596d87c..0000000
--- a/Doc/lib/sqlite3/shortcut_methods.py
+++ /dev/null
@@ -1,21 +0,0 @@
-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")
diff --git a/Doc/lib/sqlite3/simple_tableprinter.py b/Doc/lib/sqlite3/simple_tableprinter.py
deleted file mode 100644
index 231d872..0000000
--- a/Doc/lib/sqlite3/simple_tableprinter.py
+++ /dev/null
@@ -1,26 +0,0 @@
-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), end=' ')
-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), end=' ')
-
- print() # Finish the row with a newline.
diff --git a/Doc/lib/sqlite3/text_factory.py b/Doc/lib/sqlite3/text_factory.py
deleted file mode 100644
index 2dab8e4..0000000
--- a/Doc/lib/sqlite3/text_factory.py
+++ /dev/null
@@ -1,42 +0,0 @@
-import sqlite3
-
-con = sqlite3.connect(":memory:")
-cur = con.cursor()
-
-# Create the table
-con.execute("create table person(lastname, firstname)")
-
-AUSTRIA = "\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: str(x, "utf-8", "ignore")
-cur.execute("select ?", ("this is latin1 and would normally create errors" + "\xe4\xf6\xfc".encode("latin1"),))
-row = cur.fetchone()
-assert type(row[0]) == str
-
-# 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]) == str
-
-cur.execute("select ?", ("Germany",))
-row = cur.fetchone()
-assert type(row[0]) == str
diff --git a/Doc/lib/tkinter.tex b/Doc/lib/tkinter.tex
deleted file mode 100644
index 20b2373..0000000
--- a/Doc/lib/tkinter.tex
+++ /dev/null
@@ -1,1873 +0,0 @@
-\chapter{Graphical User Interfaces with Tk \label{tkinter}}
-
-\index{GUI}
-\index{Graphical User Interface}
-\index{Tkinter}
-\index{Tk}
-
-Tk/Tcl has long been an integral part of Python. It provides a robust
-and platform independent windowing toolkit, that is available to
-Python programmers using the \refmodule{Tkinter} module, and its
-extension, the \refmodule{Tix} module.
-
-The \refmodule{Tkinter} module is a thin object-oriented layer on top of
-Tcl/Tk. To use \refmodule{Tkinter}, you don't need to write Tcl code,
-but you will need to consult the Tk documentation, and occasionally
-the Tcl documentation. \refmodule{Tkinter} is a set of wrappers that
-implement the Tk widgets as Python classes. In addition, the internal
-module \module{\_tkinter} provides a threadsafe mechanism which allows
-Python and Tcl to interact.
-
-Tk is not the only GUI for Python; see
-section~\ref{other-gui-packages}, ``Other User Interface Modules and
-Packages,'' for more information on other GUI toolkits for Python.
-
-% Other sections I have in mind are
-% Tkinter internals
-% Freezing Tkinter applications
-
-\localmoduletable
-
-
-\section{\module{Tkinter} ---
- Python interface to Tcl/Tk}
-
-\declaremodule{standard}{Tkinter}
-\modulesynopsis{Interface to Tcl/Tk for graphical user interfaces}
-\moduleauthor{Guido van Rossum}{guido@Python.org}
-
-The \module{Tkinter} module (``Tk interface'') is the standard Python
-interface to the Tk GUI toolkit. Both Tk and \module{Tkinter} are
-available on most \UNIX{} platforms, as well as on Windows and
-Macintosh systems. (Tk itself is not part of Python; it is maintained
-at ActiveState.)
-
-\begin{seealso}
-\seetitle[http://www.python.org/topics/tkinter/]
- {Python Tkinter Resources}
- {The Python Tkinter Topic Guide provides a great
- deal of information on using Tk from Python and links to
- other sources of information on Tk.}
-
-\seetitle[http://www.pythonware.com/library/an-introduction-to-tkinter.htm]
- {An Introduction to Tkinter}
- {Fredrik Lundh's on-line reference material.}
-
-\seetitle[http://www.nmt.edu/tcc/help/pubs/lang.html]
- {Tkinter reference: a GUI for Python}
- {On-line reference material.}
-
-\seetitle[http://jtkinter.sourceforge.net]
- {Tkinter for JPython}
- {The Jython interface to Tkinter.}
-
-\seetitle[http://www.amazon.com/exec/obidos/ASIN/1884777813]
- {Python and Tkinter Programming}
- {The book by John Grayson (ISBN 1-884777-81-3).}
-\end{seealso}
-
-
-\subsection{Tkinter Modules}
-
-Most of the time, the \refmodule{Tkinter} module is all you really
-need, but a number of additional modules are available as well. The
-Tk interface is located in a binary module named \module{_tkinter}.
-This module contains the low-level interface to Tk, and should never
-be used directly by application programmers. It is usually a shared
-library (or DLL), but might in some cases be statically linked with
-the Python interpreter.
-
-In addition to the Tk interface module, \refmodule{Tkinter} includes a
-number of Python modules. The two most important modules are the
-\refmodule{Tkinter} module itself, and a module called
-\module{Tkconstants}. The former automatically imports the latter, so
-to use Tkinter, all you need to do is to import one module:
-
-\begin{verbatim}
-import Tkinter
-\end{verbatim}
-
-Or, more often:
-
-\begin{verbatim}
-from Tkinter import *
-\end{verbatim}
-
-\begin{classdesc}{Tk}{screenName=None, baseName=None, className='Tk', useTk=1}
-The \class{Tk} class is instantiated without arguments.
-This creates a toplevel widget of Tk which usually is the main window
-of an application. Each instance has its own associated Tcl interpreter.
-% FIXME: The following keyword arguments are currently recognized:
-\versionchanged[The \var{useTk} parameter was added]{2.4}
-\end{classdesc}
-
-\begin{funcdesc}{Tcl}{screenName=None, baseName=None, className='Tk', useTk=0}
-The \function{Tcl} function is a factory function which creates an
-object much like that created by the \class{Tk} class, except that it
-does not initialize the Tk subsystem. This is most often useful when
-driving the Tcl interpreter in an environment where one doesn't want
-to create extraneous toplevel windows, or where one cannot (such as
-\UNIX/Linux systems without an X server). An object created by the
-\function{Tcl} object can have a Toplevel window created (and the Tk
-subsystem initialized) by calling its \method{loadtk} method.
-\versionadded{2.4}
-\end{funcdesc}
-
-Other modules that provide Tk support include:
-
-\begin{description}
-% \declaremodule{standard}{Tkconstants}
-% \modulesynopsis{Constants used by Tkinter}
-% FIXME
-
-\item[\refmodule{ScrolledText}]
-Text widget with a vertical scroll bar built in.
-
-\item[\module{tkColorChooser}]
-Dialog to let the user choose a color.
-
-\item[\module{tkCommonDialog}]
-Base class for the dialogs defined in the other modules listed here.
-
-\item[\module{tkFileDialog}]
-Common dialogs to allow the user to specify a file to open or save.
-
-\item[\module{tkFont}]
-Utilities to help work with fonts.
-
-\item[\module{tkMessageBox}]
-Access to standard Tk dialog boxes.
-
-\item[\module{tkSimpleDialog}]
-Basic dialogs and convenience functions.
-
-\item[\module{Tkdnd}]
-Drag-and-drop support for \refmodule{Tkinter}.
-This is experimental and should become deprecated when it is replaced
-with the Tk DND.
-
-\item[\refmodule{turtle}]
-Turtle graphics in a Tk window.
-
-\end{description}
-
-\subsection{Tkinter Life Preserver}
-\sectionauthor{Matt Conway}{}
-% Converted to LaTeX by Mike Clarkson.
-
-This section is not designed to be an exhaustive tutorial on either
-Tk or Tkinter. Rather, it is intended as a stop gap, providing some
-introductory orientation on the system.
-
-Credits:
-\begin{itemize}
-\item Tkinter was written by Steen Lumholt and Guido van Rossum.
-\item Tk was written by John Ousterhout while at Berkeley.
-\item This Life Preserver was written by Matt Conway at
-the University of Virginia.
-\item The html rendering, and some liberal editing, was
-produced from a FrameMaker version by Ken Manheimer.
-\item Fredrik Lundh elaborated and revised the class interface descriptions,
-to get them current with Tk 4.2.
-\item Mike Clarkson converted the documentation to \LaTeX, and compiled the
-User Interface chapter of the reference manual.
-\end{itemize}
-
-
-\subsubsection{How To Use This Section}
-
-This section is designed in two parts: the first half (roughly) covers
-background material, while the second half can be taken to the
-keyboard as a handy reference.
-
-When trying to answer questions of the form ``how do I do blah'', it
-is often best to find out how to do``blah'' in straight Tk, and then
-convert this back into the corresponding \refmodule{Tkinter} call.
-Python programmers can often guess at the correct Python command by
-looking at the Tk documentation. This means that in order to use
-Tkinter, you will have to know a little bit about Tk. This document
-can't fulfill that role, so the best we can do is point you to the
-best documentation that exists. Here are some hints:
-
-\begin{itemize}
-\item The authors strongly suggest getting a copy of the Tk man
-pages. Specifically, the man pages in the \code{mann} directory are most
-useful. The \code{man3} man pages describe the C interface to the Tk
-library and thus are not especially helpful for script writers.
-
-\item Addison-Wesley publishes a book called \citetitle{Tcl and the
-Tk Toolkit} by John Ousterhout (ISBN 0-201-63337-X) which is a good
-introduction to Tcl and Tk for the novice. The book is not
-exhaustive, and for many details it defers to the man pages.
-
-\item \file{Tkinter.py} is a last resort for most, but can be a good
-place to go when nothing else makes sense.
-\end{itemize}
-
-\begin{seealso}
-\seetitle[http://tcl.activestate.com/]
- {ActiveState Tcl Home Page}
- {The Tk/Tcl development is largely taking place at
- ActiveState.}
-\seetitle[http://www.amazon.com/exec/obidos/ASIN/020163337X]
- {Tcl and the Tk Toolkit}
- {The book by John Ousterhout, the inventor of Tcl .}
-\seetitle[http://www.amazon.com/exec/obidos/ASIN/0130220280]
- {Practical Programming in Tcl and Tk}
- {Brent Welch's encyclopedic book.}
-\end{seealso}
-
-
-\subsubsection{A Simple Hello World Program} % HelloWorld.html
-
-%begin{latexonly}
-%\begin{figure}[hbtp]
-%\centerline{\epsfig{file=HelloWorld.gif,width=.9\textwidth}}
-%\vspace{.5cm}
-%\caption{HelloWorld gadget image}
-%\end{figure}
-%See also the hello-world \ulink{notes}{classes/HelloWorld-notes.html} and
-%\ulink{summary}{classes/HelloWorld-summary.html}.
-%end{latexonly}
-
-
-\begin{verbatim}
-from Tkinter import *
-
-class Application(Frame):
- def say_hi(self):
- print "hi there, everyone!"
-
- def createWidgets(self):
- self.QUIT = Button(self)
- self.QUIT["text"] = "QUIT"
- self.QUIT["fg"] = "red"
- self.QUIT["command"] = self.quit
-
- self.QUIT.pack({"side": "left"})
-
- self.hi_there = Button(self)
- self.hi_there["text"] = "Hello",
- self.hi_there["command"] = self.say_hi
-
- self.hi_there.pack({"side": "left"})
-
- def __init__(self, master=None):
- Frame.__init__(self, master)
- self.pack()
- self.createWidgets()
-
-root = Tk()
-app = Application(master=root)
-app.mainloop()
-root.destroy()
-\end{verbatim}
-
-
-\subsection{A (Very) Quick Look at Tcl/Tk} % BriefTclTk.html
-
-The class hierarchy looks complicated, but in actual practice,
-application programmers almost always refer to the classes at the very
-bottom of the hierarchy.
-
-Notes:
-\begin{itemize}
-\item These classes are provided for the purposes of
-organizing certain functions under one namespace. They aren't meant to
-be instantiated independently.
-
-\item The \class{Tk} class is meant to be instantiated only once in
-an application. Application programmers need not instantiate one
-explicitly, the system creates one whenever any of the other classes
-are instantiated.
-
-\item The \class{Widget} class is not meant to be instantiated, it
-is meant only for subclassing to make ``real'' widgets (in \Cpp, this
-is called an `abstract class').
-\end{itemize}
-
-To make use of this reference material, there will be times when you
-will need to know how to read short passages of Tk and how to identify
-the various parts of a Tk command.
-(See section~\ref{tkinter-basic-mapping} for the
-\refmodule{Tkinter} equivalents of what's below.)
-
-Tk scripts are Tcl programs. Like all Tcl programs, Tk scripts are
-just lists of tokens separated by spaces. A Tk widget is just its
-\emph{class}, the \emph{options} that help configure it, and the
-\emph{actions} that make it do useful things.
-
-To make a widget in Tk, the command is always of the form:
-
-\begin{verbatim}
- classCommand newPathname options
-\end{verbatim}
-
-\begin{description}
-\item[\var{classCommand}]
-denotes which kind of widget to make (a button, a label, a menu...)
-
-\item[\var{newPathname}]
-is the new name for this widget. All names in Tk must be unique. To
-help enforce this, widgets in Tk are named with \emph{pathnames}, just
-like files in a file system. The top level widget, the \emph{root},
-is called \code{.} (period) and children are delimited by more
-periods. For example, \code{.myApp.controlPanel.okButton} might be
-the name of a widget.
-
-\item[\var{options}]
-configure the widget's appearance and in some cases, its
-behavior. The options come in the form of a list of flags and values.
-Flags are preceded by a `-', like \UNIX{} shell command flags, and
-values are put in quotes if they are more than one word.
-\end{description}
-
-For example:
-
-\begin{verbatim}
- button .fred -fg red -text "hi there"
- ^ ^ \_____________________/
- | | |
- class new options
- command widget (-opt val -opt val ...)
-\end{verbatim}
-
-Once created, the pathname to the widget becomes a new command. This
-new \var{widget command} is the programmer's handle for getting the new
-widget to perform some \var{action}. In C, you'd express this as
-someAction(fred, someOptions), in \Cpp, you would express this as
-fred.someAction(someOptions), and in Tk, you say:
-
-\begin{verbatim}
- .fred someAction someOptions
-\end{verbatim}
-
-Note that the object name, \code{.fred}, starts with a dot.
-
-As you'd expect, the legal values for \var{someAction} will depend on
-the widget's class: \code{.fred disable} works if fred is a
-button (fred gets greyed out), but does not work if fred is a label
-(disabling of labels is not supported in Tk).
-
-The legal values of \var{someOptions} is action dependent. Some
-actions, like \code{disable}, require no arguments, others, like
-a text-entry box's \code{delete} command, would need arguments
-to specify what range of text to delete.
-
-
-\subsection{Mapping Basic Tk into Tkinter
- \label{tkinter-basic-mapping}}
-
-Class commands in Tk correspond to class constructors in Tkinter.
-
-\begin{verbatim}
- button .fred =====> fred = Button()
-\end{verbatim}
-
-The master of an object is implicit in the new name given to it at
-creation time. In Tkinter, masters are specified explicitly.
-
-\begin{verbatim}
- button .panel.fred =====> fred = Button(panel)
-\end{verbatim}
-
-The configuration options in Tk are given in lists of hyphened tags
-followed by values. In Tkinter, options are specified as
-keyword-arguments in the instance constructor, and keyword-args for
-configure calls or as instance indices, in dictionary style, for
-established instances. See section~\ref{tkinter-setting-options} on
-setting options.
-
-\begin{verbatim}
- button .fred -fg red =====> fred = Button(panel, fg = "red")
- .fred configure -fg red =====> fred["fg"] = red
- OR ==> fred.config(fg = "red")
-\end{verbatim}
-
-In Tk, to perform an action on a widget, use the widget name as a
-command, and follow it with an action name, possibly with arguments
-(options). In Tkinter, you call methods on the class instance to
-invoke actions on the widget. The actions (methods) that a given
-widget can perform are listed in the Tkinter.py module.
-
-\begin{verbatim}
- .fred invoke =====> fred.invoke()
-\end{verbatim}
-
-To give a widget to the packer (geometry manager), you call pack with
-optional arguments. In Tkinter, the Pack class holds all this
-functionality, and the various forms of the pack command are
-implemented as methods. All widgets in \refmodule{Tkinter} are
-subclassed from the Packer, and so inherit all the packing
-methods. See the \refmodule{Tix} module documentation for additional
-information on the Form geometry manager.
-
-\begin{verbatim}
- pack .fred -side left =====> fred.pack(side = "left")
-\end{verbatim}
-
-
-\subsection{How Tk and Tkinter are Related} % Relationship.html
-
-\note{This was derived from a graphical image; the image will be used
- more directly in a subsequent version of this document.}
-
-From the top down:
-\begin{description}
-\item[\b{Your App Here (Python)}]
-A Python application makes a \refmodule{Tkinter} call.
-
-\item[\b{Tkinter (Python Module)}]
-This call (say, for example, creating a button widget), is
-implemented in the \emph{Tkinter} module, which is written in
-Python. This Python function will parse the commands and the
-arguments and convert them into a form that makes them look as if they
-had come from a Tk script instead of a Python script.
-
-\item[\b{tkinter (C)}]
-These commands and their arguments will be passed to a C function
-in the \emph{tkinter} - note the lowercase - extension module.
-
-\item[\b{Tk Widgets} (C and Tcl)]
-This C function is able to make calls into other C modules,
-including the C functions that make up the Tk library. Tk is
-implemented in C and some Tcl. The Tcl part of the Tk widgets is used
-to bind certain default behaviors to widgets, and is executed once at
-the point where the Python \refmodule{Tkinter} module is
-imported. (The user never sees this stage).
-
-\item[\b{Tk (C)}]
-The Tk part of the Tk Widgets implement the final mapping to ...
-
-\item[\b{Xlib (C)}]
-the Xlib library to draw graphics on the screen.
-\end{description}
-
-
-\subsection{Handy Reference}
-
-\subsubsection{Setting Options
- \label{tkinter-setting-options}}
-
-Options control things like the color and border width of a widget.
-Options can be set in three ways:
-
-\begin{description}
-\item[At object creation time, using keyword arguments]:
-\begin{verbatim}
-fred = Button(self, fg = "red", bg = "blue")
-\end{verbatim}
-\item[After object creation, treating the option name like a dictionary index]:
-\begin{verbatim}
-fred["fg"] = "red"
-fred["bg"] = "blue"
-\end{verbatim}
-\item[Use the config() method to update multiple attrs subsequent to
-object creation]:
-\begin{verbatim}
-fred.config(fg = "red", bg = "blue")
-\end{verbatim}
-\end{description}
-
-For a complete explanation of a given option and its behavior, see the
-Tk man pages for the widget in question.
-
-Note that the man pages list "STANDARD OPTIONS" and "WIDGET SPECIFIC
-OPTIONS" for each widget. The former is a list of options that are
-common to many widgets, the latter are the options that are
-idiosyncratic to that particular widget. The Standard Options are
-documented on the \manpage{options}{3} man page.
-
-No distinction between standard and widget-specific options is made in
-this document. Some options don't apply to some kinds of widgets.
-Whether a given widget responds to a particular option depends on the
-class of the widget; buttons have a \code{command} option, labels do not.
-
-The options supported by a given widget are listed in that widget's
-man page, or can be queried at runtime by calling the
-\method{config()} method without arguments, or by calling the
-\method{keys()} method on that widget. The return value of these
-calls is a dictionary whose key is the name of the option as a string
-(for example, \code{'relief'}) and whose values are 5-tuples.
-
-Some options, like \code{bg} are synonyms for common options with long
-names (\code{bg} is shorthand for "background"). Passing the
-\code{config()} method the name of a shorthand option will return a
-2-tuple, not 5-tuple. The 2-tuple passed back will contain the name of
-the synonym and the ``real'' option (such as \code{('bg',
-'background')}).
-
-\begin{tableiii}{c|l|l}{textrm}{Index}{Meaning}{Example}
- \lineiii{0}{option name} {\code{'relief'}}
- \lineiii{1}{option name for database lookup} {\code{'relief'}}
- \lineiii{2}{option class for database lookup} {\code{'Relief'}}
- \lineiii{3}{default value} {\code{'raised'}}
- \lineiii{4}{current value} {\code{'groove'}}
-\end{tableiii}
-
-
-Example:
-
-\begin{verbatim}
->>> print fred.config()
-{'relief' : ('relief', 'relief', 'Relief', 'raised', 'groove')}
-\end{verbatim}
-
-Of course, the dictionary printed will include all the options
-available and their values. This is meant only as an example.
-
-
-\subsubsection{The Packer} % Packer.html
-\index{packing (widgets)}
-
-The packer is one of Tk's geometry-management mechanisms.
-% See also \citetitle[classes/ClassPacker.html]{the Packer class interface}.
-
-Geometry managers are used to specify the relative positioning of the
-positioning of widgets within their container - their mutual
-\emph{master}. In contrast to the more cumbersome \emph{placer}
-(which is used less commonly, and we do not cover here), the packer
-takes qualitative relationship specification - \emph{above}, \emph{to
-the left of}, \emph{filling}, etc - and works everything out to
-determine the exact placement coordinates for you.
-
-The size of any \emph{master} widget is determined by the size of
-the "slave widgets" inside. The packer is used to control where slave
-widgets appear inside the master into which they are packed. You can
-pack widgets into frames, and frames into other frames, in order to
-achieve the kind of layout you desire. Additionally, the arrangement
-is dynamically adjusted to accommodate incremental changes to the
-configuration, once it is packed.
-
-Note that widgets do not appear until they have had their geometry
-specified with a geometry manager. It's a common early mistake to
-leave out the geometry specification, and then be surprised when the
-widget is created but nothing appears. A widget will appear only
-after it has had, for example, the packer's \method{pack()} method
-applied to it.
-
-The pack() method can be called with keyword-option/value pairs that
-control where the widget is to appear within its container, and how it
-is to behave when the main application window is resized. Here are
-some examples:
-
-\begin{verbatim}
- fred.pack() # defaults to side = "top"
- fred.pack(side = "left")
- fred.pack(expand = 1)
-\end{verbatim}
-
-
-\subsubsection{Packer Options}
-
-For more extensive information on the packer and the options that it
-can take, see the man pages and page 183 of John Ousterhout's book.
-
-\begin{description}
-\item[\b{anchor }]
-Anchor type. Denotes where the packer is to place each slave in its
-parcel.
-
-\item[\b{expand}]
-Boolean, \code{0} or \code{1}.
-
-\item[\b{fill}]
-Legal values: \code{'x'}, \code{'y'}, \code{'both'}, \code{'none'}.
-
-\item[\b{ipadx} and \b{ipady}]
-A distance - designating internal padding on each side of the slave
-widget.
-
-\item[\b{padx} and \b{pady}]
-A distance - designating external padding on each side of the slave
-widget.
-
-\item[\b{side}]
-Legal values are: \code{'left'}, \code{'right'}, \code{'top'},
-\code{'bottom'}.
-\end{description}
-
-
-\subsubsection{Coupling Widget Variables} % VarCouplings.html
-
-The current-value setting of some widgets (like text entry widgets)
-can be connected directly to application variables by using special
-options. These options are \code{variable}, \code{textvariable},
-\code{onvalue}, \code{offvalue}, and \code{value}. This
-connection works both ways: if the variable changes for any reason,
-the widget it's connected to will be updated to reflect the new value.
-
-Unfortunately, in the current implementation of \refmodule{Tkinter} it is
-not possible to hand over an arbitrary Python variable to a widget
-through a \code{variable} or \code{textvariable} option. The only
-kinds of variables for which this works are variables that are
-subclassed from a class called Variable, defined in the
-\refmodule{Tkinter} module.
-
-There are many useful subclasses of Variable already defined:
-\class{StringVar}, \class{IntVar}, \class{DoubleVar}, and
-\class{BooleanVar}. To read the current value of such a variable,
-call the \method{get()} method on
-it, and to change its value you call the \method{set()} method. If
-you follow this protocol, the widget will always track the value of
-the variable, with no further intervention on your part.
-
-For example:
-\begin{verbatim}
-class App(Frame):
- def __init__(self, master=None):
- Frame.__init__(self, master)
- self.pack()
-
- self.entrythingy = Entry()
- self.entrythingy.pack()
-
- # here is the application variable
- self.contents = StringVar()
- # set it to some value
- self.contents.set("this is a variable")
- # tell the entry widget to watch this variable
- self.entrythingy["textvariable"] = self.contents
-
- # and here we get a callback when the user hits return.
- # we will have the program print out the value of the
- # application variable when the user hits return
- self.entrythingy.bind('<Key-Return>',
- self.print_contents)
-
- def print_contents(self, event):
- print "hi. contents of entry is now ---->", \
- self.contents.get()
-\end{verbatim}
-
-
-\subsubsection{The Window Manager} % WindowMgr.html
-\index{window manager (widgets)}
-
-In Tk, there is a utility command, \code{wm}, for interacting with the
-window manager. Options to the \code{wm} command allow you to control
-things like titles, placement, icon bitmaps, and the like. In
-\refmodule{Tkinter}, these commands have been implemented as methods
-on the \class{Wm} class. Toplevel widgets are subclassed from the
-\class{Wm} class, and so can call the \class{Wm} methods directly.
-
-%See also \citetitle[classes/ClassWm.html]{the Wm class interface}.
-
-To get at the toplevel window that contains a given widget, you can
-often just refer to the widget's master. Of course if the widget has
-been packed inside of a frame, the master won't represent a toplevel
-window. To get at the toplevel window that contains an arbitrary
-widget, you can call the \method{_root()} method. This
-method begins with an underscore to denote the fact that this function
-is part of the implementation, and not an interface to Tk functionality.
-
-Here are some examples of typical usage:
-
-\begin{verbatim}
-from Tkinter import *
-class App(Frame):
- def __init__(self, master=None):
- Frame.__init__(self, master)
- self.pack()
-
-
-# create the application
-myapp = App()
-
-#
-# here are method calls to the window manager class
-#
-myapp.master.title("My Do-Nothing Application")
-myapp.master.maxsize(1000, 400)
-
-# start the program
-myapp.mainloop()
-\end{verbatim}
-
-
-\subsubsection{Tk Option Data Types} % OptionTypes.html
-
-\index{Tk Option Data Types}
-
-\begin{description}
-\item[anchor]
-Legal values are points of the compass: \code{"n"},
-\code{"ne"}, \code{"e"}, \code{"se"}, \code{"s"},
-\code{"sw"}, \code{"w"}, \code{"nw"}, and also
-\code{"center"}.
-
-\item[bitmap]
-There are eight built-in, named bitmaps: \code{'error'}, \code{'gray25'},
-\code{'gray50'}, \code{'hourglass'}, \code{'info'}, \code{'questhead'},
-\code{'question'}, \code{'warning'}. To specify an X bitmap
-filename, give the full path to the file, preceded with an \code{@},
-as in \code{"@/usr/contrib/bitmap/gumby.bit"}.
-
-\item[boolean]
-You can pass integers 0 or 1 or the strings \code{"yes"} or \code{"no"} .
-
-\item[callback]
-This is any Python function that takes no arguments. For example:
-\begin{verbatim}
- def print_it():
- print "hi there"
- fred["command"] = print_it
-\end{verbatim}
-
-\item[color]
-Colors can be given as the names of X colors in the rgb.txt file,
-or as strings representing RGB values in 4 bit: \code{"\#RGB"}, 8
-bit: \code{"\#RRGGBB"}, 12 bit" \code{"\#RRRGGGBBB"}, or 16 bit
-\code{"\#RRRRGGGGBBBB"} ranges, where R,G,B here represent any
-legal hex digit. See page 160 of Ousterhout's book for details.
-
-\item[cursor]
-The standard X cursor names from \file{cursorfont.h} can be used,
-without the \code{XC_} prefix. For example to get a hand cursor
-(\constant{XC_hand2}), use the string \code{"hand2"}. You can also
-specify a bitmap and mask file of your own. See page 179 of
-Ousterhout's book.
-
-\item[distance]
-Screen distances can be specified in either pixels or absolute
-distances. Pixels are given as numbers and absolute distances as
-strings, with the trailing character denoting units: \code{c}
-for centimetres, \code{i} for inches, \code{m} for millimetres,
-\code{p} for printer's points. For example, 3.5 inches is expressed
-as \code{"3.5i"}.
-
-\item[font]
-Tk uses a list font name format, such as \code{\{courier 10 bold\}}.
-Font sizes with positive numbers are measured in points;
-sizes with negative numbers are measured in pixels.
-
-\item[geometry]
-This is a string of the form \samp{\var{width}x\var{height}}, where
-width and height are measured in pixels for most widgets (in
-characters for widgets displaying text). For example:
-\code{fred["geometry"] = "200x100"}.
-
-\item[justify]
-Legal values are the strings: \code{"left"},
-\code{"center"}, \code{"right"}, and \code{"fill"}.
-
-\item[region]
-This is a string with four space-delimited elements, each of
-which is a legal distance (see above). For example: \code{"2 3 4
-5"} and \code{"3i 2i 4.5i 2i"} and \code{"3c 2c 4c 10.43c"}
-are all legal regions.
-
-\item[relief]
-Determines what the border style of a widget will be. Legal
-values are: \code{"raised"}, \code{"sunken"},
-\code{"flat"}, \code{"groove"}, and \code{"ridge"}.
-
-\item[scrollcommand]
-This is almost always the \method{set()} method of some scrollbar
-widget, but can be any widget method that takes a single argument.
-Refer to the file \file{Demo/tkinter/matt/canvas-with-scrollbars.py}
-in the Python source distribution for an example.
-
-\item[wrap:]
-Must be one of: \code{"none"}, \code{"char"}, or \code{"word"}.
-\end{description}
-
-
-\subsubsection{Bindings and Events} % Bindings.html
-
-\index{bind (widgets)}
-\index{events (widgets)}
-
-The bind method from the widget command allows you to watch for
-certain events and to have a callback function trigger when that event
-type occurs. The form of the bind method is:
-
-\begin{verbatim}
- def bind(self, sequence, func, add=''):
-\end{verbatim}
-where:
-
-\begin{description}
-\item[sequence]
-is a string that denotes the target kind of event. (See the bind
-man page and page 201 of John Ousterhout's book for details).
-
-\item[func]
-is a Python function, taking one argument, to be invoked when the
-event occurs. An Event instance will be passed as the argument.
-(Functions deployed this way are commonly known as \var{callbacks}.)
-
-\item[add]
-is optional, either \samp{} or \samp{+}. Passing an empty string
-denotes that this binding is to replace any other bindings that this
-event is associated with. Preceeding with a \samp{+} means that this
-function is to be added to the list of functions bound to this event type.
-\end{description}
-
-For example:
-\begin{verbatim}
- def turnRed(self, event):
- event.widget["activeforeground"] = "red"
-
- self.button.bind("<Enter>", self.turnRed)
-\end{verbatim}
-
-Notice how the widget field of the event is being accessed in the
-\method{turnRed()} callback. This field contains the widget that
-caught the X event. The following table lists the other event fields
-you can access, and how they are denoted in Tk, which can be useful
-when referring to the Tk man pages.
-
-\begin{verbatim}
-Tk Tkinter Event Field Tk Tkinter Event Field
--- ------------------- -- -------------------
-%f focus %A char
-%h height %E send_event
-%k keycode %K keysym
-%s state %N keysym_num
-%t time %T type
-%w width %W widget
-%x x %X x_root
-%y y %Y y_root
-\end{verbatim}
-
-
-\subsubsection{The index Parameter} % Index.html
-
-A number of widgets require``index'' parameters to be passed. These
-are used to point at a specific place in a Text widget, or to
-particular characters in an Entry widget, or to particular menu items
-in a Menu widget.
-
-\begin{description}
-\item[\b{Entry widget indexes (index, view index, etc.)}]
-Entry widgets have options that refer to character positions in the
-text being displayed. You can use these \refmodule{Tkinter} functions
-to access these special points in text widgets:
-
-\begin{description}
-\item[AtEnd()]
-refers to the last position in the text
-
-\item[AtInsert()]
-refers to the point where the text cursor is
-
-\item[AtSelFirst()]
-indicates the beginning point of the selected text
-
-\item[AtSelLast()]
-denotes the last point of the selected text and finally
-
-\item[At(x\optional{, y})]
-refers to the character at pixel location \var{x}, \var{y} (with
-\var{y} not used in the case of a text entry widget, which contains a
-single line of text).
-\end{description}
-
-\item[\b{Text widget indexes}]
-The index notation for Text widgets is very rich and is best described
-in the Tk man pages.
-
-\item[\b{Menu indexes (menu.invoke(), menu.entryconfig(), etc.)}]
-
-Some options and methods for menus manipulate specific menu entries.
-Anytime a menu index is needed for an option or a parameter, you may
-pass in:
-\begin{itemize}
-\item an integer which refers to the numeric position of the entry in
-the widget, counted from the top, starting with 0;
-\item the string \code{'active'}, which refers to the menu position that is
-currently under the cursor;
-\item the string \code{"last"} which refers to the last menu
-item;
-\item An integer preceded by \code{@}, as in \code{@6}, where the integer is
-interpreted as a y pixel coordinate in the menu's coordinate system;
-\item the string \code{"none"}, which indicates no menu entry at all, most
-often used with menu.activate() to deactivate all entries, and
-finally,
-\item a text string that is pattern matched against the label of the
-menu entry, as scanned from the top of the menu to the bottom. Note
-that this index type is considered after all the others, which means
-that matches for menu items labelled \code{last}, \code{active}, or
-\code{none} may be interpreted as the above literals, instead.
-\end{itemize}
-\end{description}
-
-\subsubsection{Images}
-
-Bitmap/Pixelmap images can be created through the subclasses of
-\class{Tkinter.Image}:
-
-\begin{itemize}
-\item \class{BitmapImage} can be used for X11 bitmap data.
-\item \class{PhotoImage} can be used for GIF and PPM/PGM color bitmaps.
-\end{itemize}
-
-Either type of image is created through either the \code{file} or the
-\code{data} option (other options are available as well).
-
-The image object can then be used wherever an \code{image} option is
-supported by some widget (e.g. labels, buttons, menus). In these
-cases, Tk will not keep a reference to the image. When the last Python
-reference to the image object is deleted, the image data is deleted as
-well, and Tk will display an empty box wherever the image was used.
-
-\section{\module{Tix} ---
- Extension widgets for Tk}
-
-\declaremodule{standard}{Tix}
-\modulesynopsis{Tk Extension Widgets for Tkinter}
-\sectionauthor{Mike Clarkson}{mikeclarkson@users.sourceforge.net}
-
-\index{Tix}
-
-The \module{Tix} (Tk Interface Extension) module provides an
-additional rich set of widgets. Although the standard Tk library has
-many useful widgets, they are far from complete. The \module{Tix}
-library provides most of the commonly needed widgets that are missing
-from standard Tk: \class{HList}, \class{ComboBox}, \class{Control}
-(a.k.a. SpinBox) and an assortment of scrollable widgets. \module{Tix}
-also includes many more widgets that are generally useful in a wide
-range of applications: \class{NoteBook}, \class{FileEntry},
-\class{PanedWindow}, etc; there are more than 40 of them.
-
-With all these new widgets, you can introduce new interaction
-techniques into applications, creating more useful and more intuitive
-user interfaces. You can design your application by choosing the most
-appropriate widgets to match the special needs of your application and
-users.
-
-\begin{seealso}
-\seetitle[http://tix.sourceforge.net/]
- {Tix Homepage}
- {The home page for \module{Tix}. This includes links to
- additional documentation and downloads.}
-\seetitle[http://tix.sourceforge.net/dist/current/man/]
- {Tix Man Pages}
- {On-line version of the man pages and reference material.}
-\seetitle[http://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html]
- {Tix Programming Guide}
- {On-line version of the programmer's reference material.}
-\seetitle[http://tix.sourceforge.net/Tide/]
- {Tix Development Applications}
- {Tix applications for development of Tix and Tkinter programs.
- Tide applications work under Tk or Tkinter, and include
- \program{TixInspect}, an inspector to remotely modify and
- debug Tix/Tk/Tkinter applications.}
-\end{seealso}
-
-
-\subsection{Using Tix}
-
-\begin{classdesc}{Tix}{screenName\optional{, baseName\optional{, className}}}
- Toplevel widget of Tix which represents mostly the main window
- of an application. It has an associated Tcl interpreter.
-
-Classes in the \refmodule{Tix} module subclasses the classes in the
-\refmodule{Tkinter} module. The former imports the latter, so to use
-\refmodule{Tix} with Tkinter, all you need to do is to import one
-module. In general, you can just import \refmodule{Tix}, and replace
-the toplevel call to \class{Tkinter.Tk} with \class{Tix.Tk}:
-\begin{verbatim}
-import Tix
-from Tkconstants import *
-root = Tix.Tk()
-\end{verbatim}
-\end{classdesc}
-
-To use \refmodule{Tix}, you must have the \refmodule{Tix} widgets installed,
-usually alongside your installation of the Tk widgets.
-To test your installation, try the following:
-\begin{verbatim}
-import Tix
-root = Tix.Tk()
-root.tk.eval('package require Tix')
-\end{verbatim}
-
-If this fails, you have a Tk installation problem which must be
-resolved before proceeding. Use the environment variable \envvar{TIX_LIBRARY}
-to point to the installed \refmodule{Tix} library directory, and
-make sure you have the dynamic object library (\file{tix8183.dll} or
-\file{libtix8183.so}) in the same directory that contains your Tk
-dynamic object library (\file{tk8183.dll} or \file{libtk8183.so}). The
-directory with the dynamic object library should also have a file
-called \file{pkgIndex.tcl} (case sensitive), which contains the line:
-
-\begin{verbatim}
-package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix]
-\end{verbatim} % $ <-- bow to font-lock
-
-
-\subsection{Tix Widgets}
-
-\ulink{Tix}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm}
-introduces over 40 widget classes to the \refmodule{Tkinter}
-repertoire. There is a demo of all the \refmodule{Tix} widgets in the
-\file{Demo/tix} directory of the standard distribution.
-
-
-% The Python sample code is still being added to Python, hence commented out
-
-
-\subsubsection{Basic Widgets}
-
-\begin{classdesc}{Balloon}{}
-A \ulink{Balloon}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm}
-that pops up over a widget to provide help. When the user moves the
-cursor inside a widget to which a Balloon widget has been bound, a
-small pop-up window with a descriptive message will be shown on the
-screen.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl}
-
-\begin{classdesc}{ButtonBox}{}
-The \ulink{ButtonBox}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm}
-widget creates a box of buttons, such as is commonly used for \code{Ok
-Cancel}.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl}
-
-\begin{classdesc}{ComboBox}{}
-The \ulink{ComboBox}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm}
-widget is similar to the combo box control in MS Windows. The user can
-select a choice by either typing in the entry subwdget or selecting
-from the listbox subwidget.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl}
-
-\begin{classdesc}{Control}{}
-The \ulink{Control}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm}
-widget is also known as the \class{SpinBox} widget. The user can
-adjust the value by pressing the two arrow buttons or by entering the
-value directly into the entry. The new value will be checked against
-the user-defined upper and lower limits.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl}
-
-\begin{classdesc}{LabelEntry}{}
-The \ulink{LabelEntry}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm}
-widget packages an entry widget and a label into one mega widget. It
-can be used be used to simplify the creation of ``entry-form'' type of
-interface.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl}
-
-\begin{classdesc}{LabelFrame}{}
-The \ulink{LabelFrame}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm}
-widget packages a frame widget and a label into one mega widget. To
-create widgets inside a LabelFrame widget, one creates the new widgets
-relative to the \member{frame} subwidget and manage them inside the
-\member{frame} subwidget.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl}
-
-\begin{classdesc}{Meter}{}
-The \ulink{Meter}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm}
-widget can be used to show the progress of a background job which may
-take a long time to execute.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl}
-
-\begin{classdesc}{OptionMenu}{}
-The \ulink{OptionMenu}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm}
-creates a menu button of options.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl}
-
-\begin{classdesc}{PopupMenu}{}
-The \ulink{PopupMenu}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm}
-widget can be used as a replacement of the \code{tk_popup}
-command. The advantage of the \refmodule{Tix} \class{PopupMenu} widget
-is it requires less application code to manipulate.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl}
-
-\begin{classdesc}{Select}{}
-The \ulink{Select}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm}
-widget is a container of button subwidgets. It can be used to provide
-radio-box or check-box style of selection options for the user.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl}
-
-\begin{classdesc}{StdButtonBox}{}
-The \ulink{StdButtonBox}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm}
-widget is a group of standard buttons for Motif-like dialog boxes.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl}
-
-
-\subsubsection{File Selectors}
-
-\begin{classdesc}{DirList}{}
-The \ulink{DirList}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm} widget
-displays a list view of a directory, its previous directories and its
-sub-directories. The user can choose one of the directories displayed
-in the list or change to another directory.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl}
-
-\begin{classdesc}{DirTree}{}
-The \ulink{DirTree}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm}
-widget displays a tree view of a directory, its previous directories
-and its sub-directories. The user can choose one of the directories
-displayed in the list or change to another directory.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl}
-
-\begin{classdesc}{DirSelectDialog}{}
-The \ulink{DirSelectDialog}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.htm}
-widget presents the directories in the file system in a dialog
-window. The user can use this dialog window to navigate through the
-file system to select the desired directory.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl}
-
-\begin{classdesc}{DirSelectBox}{}
-The \class{DirSelectBox} is similar
-to the standard Motif(TM) directory-selection box. It is generally used for
-the user to choose a directory. DirSelectBox stores the directories mostly
-recently selected into a ComboBox widget so that they can be quickly
-selected again.
-\end{classdesc}
-
-\begin{classdesc}{ExFileSelectBox}{}
-The \ulink{ExFileSelectBox}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.htm}
-widget is usually embedded in a tixExFileSelectDialog widget. It
-provides an convenient method for the user to select files. The style
-of the \class{ExFileSelectBox} widget is very similar to the standard
-file dialog on MS Windows 3.1.
-\end{classdesc}
-
-% Python Demo of:
-%\ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl}
-
-\begin{classdesc}{FileSelectBox}{}
-The \ulink{FileSelectBox}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm}
-is similar to the standard Motif(TM) file-selection box. It is
-generally used for the user to choose a file. FileSelectBox stores the
-files mostly recently selected into a \class{ComboBox} widget so that
-they can be quickly selected again.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl}
-
-\begin{classdesc}{FileEntry}{}
-The \ulink{FileEntry}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm}
-widget can be used to input a filename. The user can type in the
-filename manually. Alternatively, the user can press the button widget
-that sits next to the entry, which will bring up a file selection
-dialog.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl}
-
-
-\subsubsection{Hierachical ListBox}
-
-\begin{classdesc}{HList}{}
-The \ulink{HList}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm}
-widget can be used to display any data that have a hierarchical
-structure, for example, file system directory trees. The list entries
-are indented and connected by branch lines according to their places
-in the hierarchy.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl}
-
-\begin{classdesc}{CheckList}{}
-The \ulink{CheckList}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm}
-widget displays a list of items to be selected by the user. CheckList
-acts similarly to the Tk checkbutton or radiobutton widgets, except it
-is capable of handling many more items than checkbuttons or
-radiobuttons.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tcl}
-% Python Demo of:
-% \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl}
-% Python Demo of:
-% \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl}
-
-\begin{classdesc}{Tree}{}
-The \ulink{Tree}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm}
-widget can be used to display hierarchical data in a tree form. The
-user can adjust the view of the tree by opening or closing parts of
-the tree.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl}
-
-% Python Demo of:
-% \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl}
-
-
-\subsubsection{Tabular ListBox}
-
-\begin{classdesc}{TList}{}
-The \ulink{TList}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm}
-widget can be used to display data in a tabular format. The list
-entries of a \class{TList} widget are similar to the entries in the Tk
-listbox widget. The main differences are (1) the \class{TList} widget
-can display the list entries in a two dimensional format and (2) you
-can use graphical images as well as multiple colors and fonts for the
-list entries.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl}
-% Python Demo of:
-% \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl}
-
-% Grid has yet to be added to Python
-% \subsubsection{Grid Widget}
-% Python Demo of:
-% \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl}
-% Python Demo of:
-% \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl}
-% Python Demo of:
-% \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl}
-
-
-\subsubsection{Manager Widgets}
-
-\begin{classdesc}{PanedWindow}{}
-The \ulink{PanedWindow}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm}
-widget allows the user to interactively manipulate the sizes of
-several panes. The panes can be arranged either vertically or
-horizontally. The user changes the sizes of the panes by dragging the
-resize handle between two panes.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl}
-
-\begin{classdesc}{ListNoteBook}{}
-The \ulink{ListNoteBook}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm}
-widget is very similar to the \class{TixNoteBook} widget: it can be
-used to display many windows in a limited space using a notebook
-metaphor. The notebook is divided into a stack of pages (windows). At
-one time only one of these pages can be shown. The user can navigate
-through these pages by choosing the name of the desired page in the
-\member{hlist} subwidget.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl}
-
-\begin{classdesc}{NoteBook}{}
-The \ulink{NoteBook}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm}
-widget can be used to display many windows in a limited space using a
-notebook metaphor. The notebook is divided into a stack of pages. At
-one time only one of these pages can be shown. The user can navigate
-through these pages by choosing the visual ``tabs'' at the top of the
-NoteBook widget.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl}
-
-
-% \subsubsection{Scrolled Widgets}
-% Python Demo of:
-% \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl}
-% Python Demo of:
-% \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl}
-% Python Demo of:
-% \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl}
-% Python Demo of:
-% \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl}
-
-
-\subsubsection{Image Types}
-
-The \refmodule{Tix} module adds:
-\begin{itemize}
-\item
-\ulink{pixmap}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm}
-capabilities to all \refmodule{Tix} and \refmodule{Tkinter} widgets to
-create color images from XPM files.
-
-% Python Demo of:
-% \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl}
-
-% Python Demo of:
-% \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl}
-
-\item
-\ulink{Compound}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.htm}
-image types can be used to create images that consists of multiple
-horizontal lines; each line is composed of a series of items (texts,
-bitmaps, images or spaces) arranged from left to right. For example, a
-compound image can be used to display a bitmap and a text string
-simultaneously in a Tk \class{Button} widget.
-
-% Python Demo of:
-% \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl}
-
-% Python Demo of:
-% \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl}
-
-% Python Demo of:
-% \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl}
-
-% Python Demo of:
-% \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl}
-\end{itemize}
-
-
-\subsubsection{Miscellaneous Widgets}
-
-\begin{classdesc}{InputOnly}{}
-The \ulink{InputOnly}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm}
-widgets are to accept inputs from the user, which can be done with the
-\code{bind} command (\UNIX{} only).
-\end{classdesc}
-
-\subsubsection{Form Geometry Manager}
-
-In addition, \refmodule{Tix} augments \refmodule{Tkinter} by providing:
-
-\begin{classdesc}{Form}{}
-The \ulink{Form}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm}
-geometry manager based on attachment rules for all Tk widgets.
-\end{classdesc}
-
-
-%begin{latexonly}
-%\subsection{Tix Class Structure}
-%
-%\begin{figure}[hbtp]
-%\centerline{\epsfig{file=hierarchy.png,width=.9\textwidth}}
-%\vspace{.5cm}
-%\caption{The Class Hierarchy of Tix Widgets}
-%\end{figure}
-%end{latexonly}
-
-\subsection{Tix Commands}
-
-\begin{classdesc}{tixCommand}{}
-The \ulink{tix commands}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tix.htm}
-provide access to miscellaneous elements of \refmodule{Tix}'s internal
-state and the \refmodule{Tix} application context. Most of the information
-manipulated by these methods pertains to the application as a whole,
-or to a screen or display, rather than to a particular window.
-
-To view the current settings, the common usage is:
-\begin{verbatim}
-import Tix
-root = Tix.Tk()
-print root.tix_configure()
-\end{verbatim}
-\end{classdesc}
-
-\begin{methoddesc}{tix_configure}{\optional{cnf,} **kw}
-Query or modify the configuration options of the Tix application
-context. If no option is specified, returns a dictionary all of the
-available options. If option is specified with no value, then the
-method returns a list describing the one named option (this list will
-be identical to the corresponding sublist of the value returned if no
-option is specified). If one or more option-value pairs are
-specified, then the method modifies the given option(s) to have the
-given value(s); in this case the method returns an empty string.
-Option may be any of the configuration options.
-\end{methoddesc}
-
-\begin{methoddesc}{tix_cget}{option}
-Returns the current value of the configuration option given by
-\var{option}. Option may be any of the configuration options.
-\end{methoddesc}
-
-\begin{methoddesc}{tix_getbitmap}{name}
-Locates a bitmap file of the name \code{name.xpm} or \code{name} in
-one of the bitmap directories (see the \method{tix_addbitmapdir()}
-method). By using \method{tix_getbitmap()}, you can avoid hard
-coding the pathnames of the bitmap files in your application. When
-successful, it returns the complete pathname of the bitmap file,
-prefixed with the character \samp{@}. The returned value can be used to
-configure the \code{bitmap} option of the Tk and Tix widgets.
-\end{methoddesc}
-
-\begin{methoddesc}{tix_addbitmapdir}{directory}
-Tix maintains a list of directories under which the
-\method{tix_getimage()} and \method{tix_getbitmap()} methods will
-search for image files. The standard bitmap directory is
-\file{\$TIX_LIBRARY/bitmaps}. The \method{tix_addbitmapdir()} method
-adds \var{directory} into this list. By using this method, the image
-files of an applications can also be located using the
-\method{tix_getimage()} or \method{tix_getbitmap()} method.
-\end{methoddesc}
-
-\begin{methoddesc}{tix_filedialog}{\optional{dlgclass}}
-Returns the file selection dialog that may be shared among different
-calls from this application. This method will create a file selection
-dialog widget when it is called the first time. This dialog will be
-returned by all subsequent calls to \method{tix_filedialog()}. An
-optional dlgclass parameter can be passed as a string to specified
-what type of file selection dialog widget is desired. Possible
-options are \code{tix}, \code{FileSelectDialog} or
-\code{tixExFileSelectDialog}.
-\end{methoddesc}
-
-
-\begin{methoddesc}{tix_getimage}{self, name}
-Locates an image file of the name \file{name.xpm}, \file{name.xbm} or
-\file{name.ppm} in one of the bitmap directories (see the
-\method{tix_addbitmapdir()} method above). If more than one file with
-the same name (but different extensions) exist, then the image type is
-chosen according to the depth of the X display: xbm images are chosen
-on monochrome displays and color images are chosen on color
-displays. By using \method{tix_getimage()}, you can avoid hard coding
-the pathnames of the image files in your application. When successful,
-this method returns the name of the newly created image, which can be
-used to configure the \code{image} option of the Tk and Tix widgets.
-\end{methoddesc}
-
-\begin{methoddesc}{tix_option_get}{name}
-Gets the options maintained by the Tix scheme mechanism.
-\end{methoddesc}
-
-\begin{methoddesc}{tix_resetoptions}{newScheme, newFontSet\optional{,
- newScmPrio}}
-Resets the scheme and fontset of the Tix application to
-\var{newScheme} and \var{newFontSet}, respectively. This affects only
-those widgets created after this call. Therefore, it is best to call
-the resetoptions method before the creation of any widgets in a Tix
-application.
-
-The optional parameter \var{newScmPrio} can be given to reset the
-priority level of the Tk options set by the Tix schemes.
-
-Because of the way Tk handles the X option database, after Tix has
-been has imported and inited, it is not possible to reset the color
-schemes and font sets using the \method{tix_config()} method.
-Instead, the \method{tix_resetoptions()} method must be used.
-\end{methoddesc}
-
-
-
-\section{\module{ScrolledText} ---
- Scrolled Text Widget}
-
-\declaremodule{standard}{ScrolledText}
- \platform{Tk}
-\modulesynopsis{Text widget with a vertical scroll bar.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-The \module{ScrolledText} module provides a class of the same name
-which implements a basic text widget which has a vertical scroll bar
-configured to do the ``right thing.'' Using the \class{ScrolledText}
-class is a lot easier than setting up a text widget and scroll bar
-directly. The constructor is the same as that of the
-\class{Tkinter.Text} class.
-
-The text widget and scrollbar are packed together in a \class{Frame},
-and the methods of the \class{Grid} and \class{Pack} geometry managers
-are acquired from the \class{Frame} object. This allows the
-\class{ScrolledText} widget to be used directly to achieve most normal
-geometry management behavior.
-
-Should more specific control be necessary, the following attributes
-are available:
-
-\begin{memberdesc}[ScrolledText]{frame}
- The frame which surrounds the text and scroll bar widgets.
-\end{memberdesc}
-
-\begin{memberdesc}[ScrolledText]{vbar}
- The scroll bar widget.
-\end{memberdesc}
-
-
-\input{libturtle}
-
-
-\section{Idle \label{idle}}
-
-%\declaremodule{standard}{idle}
-%\modulesynopsis{A Python Integrated Development Environment}
-\moduleauthor{Guido van Rossum}{guido@Python.org}
-
-Idle is the Python IDE built with the \refmodule{Tkinter} GUI toolkit.
-\index{Idle}
-\index{Python Editor}
-\index{Integrated Development Environment}
-
-
-IDLE has the following features:
-
-\begin{itemize}
-\item coded in 100\% pure Python, using the \refmodule{Tkinter} GUI toolkit
-
-\item cross-platform: works on Windows and \UNIX{} (on Mac OS, there are
-currently problems with Tcl/Tk)
-
-\item multi-window text editor with multiple undo, Python colorizing
-and many other features, e.g. smart indent and call tips
-
-\item Python shell window (a.k.a. interactive interpreter)
-
-\item debugger (not complete, but you can set breakpoints, view and step)
-\end{itemize}
-
-
-\subsection{Menus}
-
-\subsubsection{File menu}
-
-\begin{description}
-\item[New window] create a new editing window
-\item[Open...] open an existing file
-\item[Open module...] open an existing module (searches sys.path)
-\item[Class browser] show classes and methods in current file
-\item[Path browser] show sys.path directories, modules, classes and methods
-\end{description}
-\index{Class browser}
-\index{Path browser}
-
-\begin{description}
-\item[Save] save current window to the associated file (unsaved
-windows have a * before and after the window title)
-
-\item[Save As...] save current window to new file, which becomes
-the associated file
-\item[Save Copy As...] save current window to different file
-without changing the associated file
-\end{description}
-
-\begin{description}
-\item[Close] close current window (asks to save if unsaved)
-\item[Exit] close all windows and quit IDLE (asks to save if unsaved)
-\end{description}
-
-
-\subsubsection{Edit menu}
-
-\begin{description}
-\item[Undo] Undo last change to current window (max 1000 changes)
-\item[Redo] Redo last undone change to current window
-\end{description}
-
-\begin{description}
-\item[Cut] Copy selection into system-wide clipboard; then delete selection
-\item[Copy] Copy selection into system-wide clipboard
-\item[Paste] Insert system-wide clipboard into window
-\item[Select All] Select the entire contents of the edit buffer
-\end{description}
-
-\begin{description}
-\item[Find...] Open a search dialog box with many options
-\item[Find again] Repeat last search
-\item[Find selection] Search for the string in the selection
-\item[Find in Files...] Open a search dialog box for searching files
-\item[Replace...] Open a search-and-replace dialog box
-\item[Go to line] Ask for a line number and show that line
-\end{description}
-
-\begin{description}
-\item[Indent region] Shift selected lines right 4 spaces
-\item[Dedent region] Shift selected lines left 4 spaces
-\item[Comment out region] Insert \#\# in front of selected lines
-\item[Uncomment region] Remove leading \# or \#\# from selected lines
-\item[Tabify region] Turns \emph{leading} stretches of spaces into tabs
-\item[Untabify region] Turn \emph{all} tabs into the right number of spaces
-\item[Expand word] Expand the word you have typed to match another
- word in the same buffer; repeat to get a different expansion
-\item[Format Paragraph] Reformat the current blank-line-separated paragraph
-\end{description}
-
-\begin{description}
-\item[Import module] Import or reload the current module
-\item[Run script] Execute the current file in the __main__ namespace
-\end{description}
-
-\index{Import module}
-\index{Run script}
-
-
-\subsubsection{Windows menu}
-
-\begin{description}
-\item[Zoom Height] toggles the window between normal size (24x80)
- and maximum height.
-\end{description}
-
-The rest of this menu lists the names of all open windows; select one
-to bring it to the foreground (deiconifying it if necessary).
-
-
-\subsubsection{Debug menu (in the Python Shell window only)}
-
-\begin{description}
-\item[Go to file/line] look around the insert point for a filename
- and linenumber, open the file, and show the line.
-\item[Open stack viewer] show the stack traceback of the last exception
-\item[Debugger toggle] Run commands in the shell under the debugger
-\item[JIT Stack viewer toggle] Open stack viewer on traceback
-\end{description}
-
-\index{stack viewer}
-\index{debugger}
-
-
-\subsection{Basic editing and navigation}
-
-\begin{itemize}
-\item \kbd{Backspace} deletes to the left; \kbd{Del} deletes to the right
-\item Arrow keys and \kbd{Page Up}/\kbd{Page Down} to move around
-\item \kbd{Home}/\kbd{End} go to begin/end of line
-\item \kbd{C-Home}/\kbd{C-End} go to begin/end of file
-\item 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}
-\end{itemize}
-
-
-\subsubsection{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.
-
-
-\subsubsection{Python Shell window}
-
-\begin{itemize}
-\item \kbd{C-C} interrupts executing command
-\item \kbd{C-D} sends end-of-file; closes window if typed at
-a \samp{>>>~} prompt
-\end{itemize}
-
-\begin{itemize}
-\item \kbd{Alt-p} retrieves previous command matching what you have typed
-\item \kbd{Alt-n} retrieves next
-\item \kbd{Return} while on any previous command retrieves that command
-\item \kbd{Alt-/} (Expand word) is also useful here
-\end{itemize}
-
-\index{indentation}
-
-
-\subsection{Syntax colors}
-
-The coloring is applied in a background ``thread,'' so you may
-occasionally see uncolorized text. To change the color
-scheme, edit the \code{[Colors]} section in \file{config.txt}.
-
-\begin{description}
-\item[Python syntax colors:]
-
-\begin{description}
-\item[Keywords] orange
-\item[Strings ] green
-\item[Comments] red
-\item[Definitions] blue
-\end{description}
-
-\item[Shell colors:]
-\begin{description}
-\item[Console output] brown
-\item[stdout] blue
-\item[stderr] dark green
-\item[stdin] black
-\end{description}
-\end{description}
-
-
-\subsubsection{Command line usage}
-
-\begin{verbatim}
-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
-\end{verbatim}
-
-If there are arguments:
-
-\begin{enumerate}
-\item If \programopt{-e} is used, arguments are files opened for
- editing and \code{sys.argv} reflects the arguments passed to
- IDLE itself.
-
-\item Otherwise, if \programopt{-c} is used, all arguments are
- placed in \code{sys.argv[1:...]}, with \code{sys.argv[0]} set
- to \code{'-c'}.
-
-\item Otherwise, if neither \programopt{-e} nor \programopt{-c} is
- used, the first argument is a script which is executed with
- the remaining arguments in \code{sys.argv[1:...]} and
- \code{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
- \code{sys.argv}.
-\end{enumerate}
-
-
-\section{Other Graphical User Interface Packages
- \label{other-gui-packages}}
-
-
-There are an number of extension widget sets to \refmodule{Tkinter}.
-
-\begin{seealso*}
-\seetitle[http://pmw.sourceforge.net/]{Python megawidgets}{is a
-toolkit for building high-level compound widgets in Python using the
-\refmodule{Tkinter} module. It consists of a set of base classes and
-a library of flexible and extensible megawidgets built on this
-foundation. These megawidgets include notebooks, comboboxes, selection
-widgets, paned widgets, scrolled widgets, dialog windows, etc. Also,
-with the Pmw.Blt interface to BLT, the busy, graph, stripchart, tabset
-and vector commands are be available.
-
-The initial ideas for Pmw were taken from the Tk \code{itcl}
-extensions \code{[incr Tk]} by Michael McLennan and \code{[incr
-Widgets]} by Mark Ulferts. Several of the megawidgets are direct
-translations from the itcl to Python. It offers most of the range of
-widgets that \code{[incr Widgets]} does, and is almost as complete as
-Tix, lacking however Tix's fast \class{HList} widget for drawing trees.
-}
-
-\seetitle[http://tkinter.effbot.org/]{Tkinter3000 Widget Construction
- Kit (WCK)}{%
-is a library that allows you to write new Tkinter widgets in pure
-Python. The WCK framework gives you full control over widget
-creation, configuration, screen appearance, and event handling. WCK
-widgets can be very fast and light-weight, since they can operate
-directly on Python data structures, without having to transfer data
-through the Tk/Tcl layer.}
-\end{seealso*}
-
-Other GUI packages are also available for Python:
-
-\begin{seealso*}
-\seetitle[http://www.wxpython.org]{wxPython}{
-wxPython is a cross-platform GUI toolkit for Python that is built
-around the popular \ulink{wxWidgets}{http://www.wxwidgets.org/} \Cpp{}
-toolkit. It provides a native look and feel for applications on
-Windows, Mac OS X, and \UNIX{} systems by using each platform's native
-widgets where ever possible, (GTK+ on \UNIX-like systems). In
-addition to an extensive set of widgets, wxPython provides classes for
-online documentation and context sensitive help, printing, HTML
-viewing, low-level device context drawing, drag and drop, system
-clipboard access, an XML-based resource format and more, including an
-ever growing library of user-contributed modules. Both the wxWidgets
-and wxPython projects are under active development and continuous
-improvement, and have active and helpful user and developer
-communities.
-}
-\seetitle[http://www.amazon.com/exec/obidos/ASIN/1932394621]
-{wxPython in Action}{
-The wxPython book, by Noel Rappin and Robin Dunn.
-}
-\seetitle{PyQt}{
-PyQt is a \program{sip}-wrapped binding to the Qt toolkit. Qt is an
-extensive \Cpp{} GUI toolkit that is available for \UNIX, Windows and
-Mac OS X. \program{sip} is a tool for generating bindings for \Cpp{}
-libraries as Python classes, and is specifically designed for Python.
-An online manual is available at
-\url{http://www.opendocspublishing.com/pyqt/} (errata are located at
-\url{http://www.valdyas.org/python/book.html}).
-}
-\seetitle[http://www.riverbankcomputing.co.uk/pykde/index.php]{PyKDE}{
-PyKDE is a \program{sip}-wrapped interface to the KDE desktop
-libraries. KDE is a desktop environment for \UNIX{} computers; the
-graphical components are based on Qt.
-}
-\seetitle[http://fxpy.sourceforge.net/]{FXPy}{
-is a Python extension module which provides an interface to the
-\citetitle[http://www.cfdrc.com/FOX/fox.html]{FOX} GUI.
-FOX is a \Cpp{} based Toolkit for developing Graphical User Interfaces
-easily and effectively. It offers a wide, and growing, collection of
-Controls, and provides state of the art facilities such as drag and
-drop, selection, as well as OpenGL widgets for 3D graphical
-manipulation. FOX also implements icons, images, and user-convenience
-features such as status line help, and tooltips.
-
-Even though FOX offers a large collection of controls already, FOX
-leverages \Cpp{} to allow programmers to easily build additional Controls
-and GUI elements, simply by taking existing controls, and creating a
-derived class which simply adds or redefines the desired behavior.
-}
-\seetitle[http://www.daa.com.au/\textasciitilde james/software/pygtk/]{PyGTK}{
-is a set of bindings for the \ulink{GTK}{http://www.gtk.org/} widget set.
-It provides an object oriented interface that is slightly higher
-level than the C one. It automatically does all the type casting and
-reference counting that you would have to do normally with the C
-API. There are also
-\ulink{bindings}{http://www.daa.com.au/\textasciitilde james/gnome/}
-to \ulink{GNOME}{http://www.gnome.org}, and a
-\ulink{tutorial}
-{http://laguna.fmedic.unam.mx/\textasciitilde daniel/pygtutorial/pygtutorial/index.html}
-is available.
-}
-\end{seealso*}
-
-% XXX Reference URLs that compare the different UI packages
diff --git a/Doc/lib/tzinfo-examples.py b/Doc/lib/tzinfo-examples.py
deleted file mode 100644
index 5a2b8ad..0000000
--- a/Doc/lib/tzinfo-examples.py
+++ /dev/null
@@ -1,139 +0,0 @@
-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")
diff --git a/Doc/lib/windows.tex b/Doc/lib/windows.tex
deleted file mode 100644
index ced3559..0000000
--- a/Doc/lib/windows.tex
+++ /dev/null
@@ -1,8 +0,0 @@
-\chapter{MS Windows Specific Services}
-
-
-This chapter describes modules that are only available on MS Windows
-platforms.
-
-
-\localmoduletable
diff --git a/Doc/lib/xmldom.tex b/Doc/lib/xmldom.tex
deleted file mode 100644
index d651bf0..0000000
--- a/Doc/lib/xmldom.tex
+++ /dev/null
@@ -1,928 +0,0 @@
-\section{\module{xml.dom} ---
- The Document Object Model API}
-
-\declaremodule{standard}{xml.dom}
-\modulesynopsis{Document Object Model API for Python.}
-\sectionauthor{Paul Prescod}{paul@prescod.net}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\versionadded{2.0}
-
-The Document Object Model, or ``DOM,'' is a cross-language API from
-the World Wide Web Consortium (W3C) for accessing and modifying XML
-documents. A DOM implementation presents an XML document as a tree
-structure, or allows client code to build such a structure from
-scratch. It then gives access to the structure through a set of
-objects which provided well-known interfaces.
-
-The DOM is extremely useful for random-access applications. SAX only
-allows you a view of one bit of the document at a time. If you are
-looking at one SAX element, you have no access to another. If you are
-looking at a text node, you have no access to a containing element.
-When you write a SAX application, you need to keep track of your
-program's position in the document somewhere in your own code. SAX
-does not do it for you. Also, if you need to look ahead in the XML
-document, you are just out of luck.
-
-Some applications are simply impossible in an event driven model with
-no access to a tree. Of course you could build some sort of tree
-yourself in SAX events, but the DOM allows you to avoid writing that
-code. The DOM is a standard tree representation for XML data.
-
-%What if your needs are somewhere between SAX and the DOM? Perhaps
-%you cannot afford to load the entire tree in memory but you find the
-%SAX model somewhat cumbersome and low-level. There is also a module
-%called xml.dom.pulldom that allows you to build trees of only the
-%parts of a document that you need structured access to. It also has
-%features that allow you to find your way around the DOM.
-% See http://www.prescod.net/python/pulldom
-
-The Document Object Model is being defined by the W3C in stages, or
-``levels'' in their terminology. The Python mapping of the API is
-substantially based on the DOM Level~2 recommendation. The mapping of
-the Level~3 specification, currently only available in draft form, is
-being developed by the \ulink{Python XML Special Interest
-Group}{http://www.python.org/sigs/xml-sig/} as part of the
-\ulink{PyXML package}{http://pyxml.sourceforge.net/}. Refer to the
-documentation bundled with that package for information on the current
-state of DOM Level~3 support.
-
-DOM applications typically start by parsing some XML into a DOM. How
-this is accomplished is not covered at all by DOM Level~1, and Level~2
-provides only limited improvements: There is a
-\class{DOMImplementation} object class which provides access to
-\class{Document} creation methods, but no way to access an XML
-reader/parser/Document builder in an implementation-independent way.
-There is also no well-defined way to access these methods without an
-existing \class{Document} object. In Python, each DOM implementation
-will provide a function \function{getDOMImplementation()}. DOM Level~3
-adds a Load/Store specification, which defines an interface to the
-reader, but this is not yet available in the Python standard library.
-
-Once you have a DOM document object, you can access the parts of your
-XML document through its properties and methods. These properties are
-defined in the DOM specification; this portion of the reference manual
-describes the interpretation of the specification in Python.
-
-The specification provided by the W3C defines the DOM API for Java,
-ECMAScript, and OMG IDL. The Python mapping defined here is based in
-large part on the IDL version of the specification, but strict
-compliance is not required (though implementations are free to support
-the strict mapping from IDL). See section \ref{dom-conformance},
-``Conformance,'' for a detailed discussion of mapping requirements.
-
-
-\begin{seealso}
- \seetitle[http://www.w3.org/TR/DOM-Level-2-Core/]{Document Object
- Model (DOM) Level~2 Specification}
- {The W3C recommendation upon which the Python DOM API is
- based.}
- \seetitle[http://www.w3.org/TR/REC-DOM-Level-1/]{Document Object
- Model (DOM) Level~1 Specification}
- {The W3C recommendation for the
- DOM supported by \module{xml.dom.minidom}.}
- \seetitle[http://pyxml.sourceforge.net]{PyXML}{Users that require a
- full-featured implementation of DOM should use the PyXML
- package.}
- \seetitle[http://www.omg.org/docs/formal/02-11-05.pdf]{Python
- Language Mapping Specification}
- {This specifies the mapping from OMG IDL to Python.}
-\end{seealso}
-
-\subsection{Module Contents}
-
-The \module{xml.dom} contains the following functions:
-
-\begin{funcdesc}{registerDOMImplementation}{name, factory}
-Register the \var{factory} function with the name \var{name}. The
-factory function should return an object which implements the
-\class{DOMImplementation} interface. The factory function can return
-the same object every time, or a new one for each call, as appropriate
-for the specific implementation (e.g. if that implementation supports
-some customization).
-\end{funcdesc}
-
-\begin{funcdesc}{getDOMImplementation}{\optional{name\optional{, features}}}
-Return a suitable DOM implementation. The \var{name} is either
-well-known, the module name of a DOM implementation, or
-\code{None}. If it is not \code{None}, imports the corresponding
-module and returns a \class{DOMImplementation} object if the import
-succeeds. If no name is given, and if the environment variable
-\envvar{PYTHON_DOM} is set, this variable is used to find the
-implementation.
-
-If name is not given, this examines the available implementations to
-find one with the required feature set. If no implementation can be
-found, raise an \exception{ImportError}. The features list must be a
-sequence of \code{(\var{feature}, \var{version})} pairs which are
-passed to the \method{hasFeature()} method on available
-\class{DOMImplementation} objects.
-\end{funcdesc}
-
-
-Some convenience constants are also provided:
-
-\begin{datadesc}{EMPTY_NAMESPACE}
- The value used to indicate that no namespace is associated with a
- node in the DOM. This is typically found as the
- \member{namespaceURI} of a node, or used as the \var{namespaceURI}
- parameter to a namespaces-specific method.
- \versionadded{2.2}
-\end{datadesc}
-
-\begin{datadesc}{XML_NAMESPACE}
- The namespace URI associated with the reserved prefix \code{xml}, as
- defined by
- \citetitle[http://www.w3.org/TR/REC-xml-names/]{Namespaces in XML}
- (section~4).
- \versionadded{2.2}
-\end{datadesc}
-
-\begin{datadesc}{XMLNS_NAMESPACE}
- The namespace URI for namespace declarations, as defined by
- \citetitle[http://www.w3.org/TR/DOM-Level-2-Core/core.html]{Document
- Object Model (DOM) Level~2 Core Specification} (section~1.1.8).
- \versionadded{2.2}
-\end{datadesc}
-
-\begin{datadesc}{XHTML_NAMESPACE}
- The URI of the XHTML namespace as defined by
- \citetitle[http://www.w3.org/TR/xhtml1/]{XHTML 1.0: The Extensible
- HyperText Markup Language} (section~3.1.1).
- \versionadded{2.2}
-\end{datadesc}
-
-
-% Should the Node documentation go here?
-
-In addition, \module{xml.dom} contains a base \class{Node} class and
-the DOM exception classes. The \class{Node} class provided by this
-module does not implement any of the methods or attributes defined by
-the DOM specification; concrete DOM implementations must provide
-those. The \class{Node} class provided as part of this module does
-provide the constants used for the \member{nodeType} attribute on
-concrete \class{Node} objects; they are located within the class
-rather than at the module level to conform with the DOM
-specifications.
-
-
-\subsection{Objects in the DOM \label{dom-objects}}
-
-The definitive documentation for the DOM is the DOM specification from
-the W3C.
-
-Note that DOM attributes may also be manipulated as nodes instead of
-as simple strings. It is fairly rare that you must do this, however,
-so this usage is not yet documented.
-
-
-\begin{tableiii}{l|l|l}{class}{Interface}{Section}{Purpose}
- \lineiii{DOMImplementation}{\ref{dom-implementation-objects}}
- {Interface to the underlying implementation.}
- \lineiii{Node}{\ref{dom-node-objects}}
- {Base interface for most objects in a document.}
- \lineiii{NodeList}{\ref{dom-nodelist-objects}}
- {Interface for a sequence of nodes.}
- \lineiii{DocumentType}{\ref{dom-documenttype-objects}}
- {Information about the declarations needed to process a document.}
- \lineiii{Document}{\ref{dom-document-objects}}
- {Object which represents an entire document.}
- \lineiii{Element}{\ref{dom-element-objects}}
- {Element nodes in the document hierarchy.}
- \lineiii{Attr}{\ref{dom-attr-objects}}
- {Attribute value nodes on element nodes.}
- \lineiii{Comment}{\ref{dom-comment-objects}}
- {Representation of comments in the source document.}
- \lineiii{Text}{\ref{dom-text-objects}}
- {Nodes containing textual content from the document.}
- \lineiii{ProcessingInstruction}{\ref{dom-pi-objects}}
- {Processing instruction representation.}
-\end{tableiii}
-
-An additional section describes the exceptions defined for working
-with the DOM in Python.
-
-
-\subsubsection{DOMImplementation Objects
- \label{dom-implementation-objects}}
-
-The \class{DOMImplementation} interface provides a way for
-applications to determine the availability of particular features in
-the DOM they are using. DOM Level~2 added the ability to create new
-\class{Document} and \class{DocumentType} objects using the
-\class{DOMImplementation} as well.
-
-\begin{methoddesc}[DOMImplementation]{hasFeature}{feature, version}
-Return true if the feature identified by the pair of strings
-\var{feature} and \var{version} is implemented.
-\end{methoddesc}
-
-\begin{methoddesc}[DOMImplementation]{createDocument}{namespaceUri, qualifiedName, doctype}
-Return a new \class{Document} object (the root of the DOM), with a
-child \class{Element} object having the given \var{namespaceUri} and
-\var{qualifiedName}. The \var{doctype} must be a \class{DocumentType}
-object created by \method{createDocumentType()}, or \code{None}.
-In the Python DOM API, the first two arguments can also be \code{None}
-in order to indicate that no \class{Element} child is to be created.
-\end{methoddesc}
-
-\begin{methoddesc}[DOMImplementation]{createDocumentType}{qualifiedName, publicId, systemId}
-Return a new \class{DocumentType} object that encapsulates the given
-\var{qualifiedName}, \var{publicId}, and \var{systemId} strings,
-representing the information contained in an XML document type
-declaration.
-\end{methoddesc}
-
-
-\subsubsection{Node Objects \label{dom-node-objects}}
-
-All of the components of an XML document are subclasses of
-\class{Node}.
-
-\begin{memberdesc}[Node]{nodeType}
-An integer representing the node type. Symbolic constants for the
-types are on the \class{Node} object:
-\constant{ELEMENT_NODE}, \constant{ATTRIBUTE_NODE},
-\constant{TEXT_NODE}, \constant{CDATA_SECTION_NODE},
-\constant{ENTITY_NODE}, \constant{PROCESSING_INSTRUCTION_NODE},
-\constant{COMMENT_NODE}, \constant{DOCUMENT_NODE},
-\constant{DOCUMENT_TYPE_NODE}, \constant{NOTATION_NODE}.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{parentNode}
-The parent of the current node, or \code{None} for the document node.
-The value is always a \class{Node} object or \code{None}. For
-\class{Element} nodes, this will be the parent element, except for the
-root element, in which case it will be the \class{Document} object.
-For \class{Attr} nodes, this is always \code{None}.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{attributes}
-A \class{NamedNodeMap} of attribute objects. Only elements have
-actual values for this; others provide \code{None} for this attribute.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{previousSibling}
-The node that immediately precedes this one with the same parent. For
-instance the element with an end-tag that comes just before the
-\var{self} element's start-tag. Of course, XML documents are made
-up of more than just elements so the previous sibling could be text, a
-comment, or something else. If this node is the first child of the
-parent, this attribute will be \code{None}.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{nextSibling}
-The node that immediately follows this one with the same parent. See
-also \member{previousSibling}. If this is the last child of the
-parent, this attribute will be \code{None}.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{childNodes}
-A list of nodes contained within this node.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{firstChild}
-The first child of the node, if there are any, or \code{None}.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{lastChild}
-The last child of the node, if there are any, or \code{None}.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{localName}
-The part of the \member{tagName} following the colon if there is one,
-else the entire \member{tagName}. The value is a string.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{prefix}
-The part of the \member{tagName} preceding the colon if there is one,
-else the empty string. The value is a string, or \code{None}
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{namespaceURI}
-The namespace associated with the element name. This will be a
-string or \code{None}. This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{nodeName}
-This has a different meaning for each node type; see the DOM
-specification for details. You can always get the information you
-would get here from another property such as the \member{tagName}
-property for elements or the \member{name} property for attributes.
-For all node types, the value of this attribute will be either a
-string or \code{None}. This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{nodeValue}
-This has a different meaning for each node type; see the DOM
-specification for details. The situation is similar to that with
-\member{nodeName}. The value is a string or \code{None}.
-\end{memberdesc}
-
-\begin{methoddesc}[Node]{hasAttributes}{}
-Returns true if the node has any attributes.
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{hasChildNodes}{}
-Returns true if the node has any child nodes.
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{isSameNode}{other}
-Returns true if \var{other} refers to the same node as this node.
-This is especially useful for DOM implementations which use any sort
-of proxy architecture (because more than one object can refer to the
-same node).
-
-\begin{notice}
- This is based on a proposed DOM Level~3 API which is still in the
- ``working draft'' stage, but this particular interface appears
- uncontroversial. Changes from the W3C will not necessarily affect
- this method in the Python DOM interface (though any new W3C API for
- this would also be supported).
-\end{notice}
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{appendChild}{newChild}
-Add a new child node to this node at the end of the list of children,
-returning \var{newChild}.
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{insertBefore}{newChild, refChild}
-Insert a new child node before an existing child. It must be the case
-that \var{refChild} is a child of this node; if not,
-\exception{ValueError} is raised. \var{newChild} is returned. If
-\var{refChild} is \code{None}, it inserts \var{newChild} at the end of
-the children's list.
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{removeChild}{oldChild}
-Remove a child node. \var{oldChild} must be a child of this node; if
-not, \exception{ValueError} is raised. \var{oldChild} is returned on
-success. If \var{oldChild} will not be used further, its
-\method{unlink()} method should be called.
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{replaceChild}{newChild, oldChild}
-Replace an existing node with a new node. It must be the case that
-\var{oldChild} is a child of this node; if not,
-\exception{ValueError} is raised.
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{normalize}{}
-Join adjacent text nodes so that all stretches of text are stored as
-single \class{Text} instances. This simplifies processing text from a
-DOM tree for many applications.
-\versionadded{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{cloneNode}{deep}
-Clone this node. Setting \var{deep} means to clone all child nodes as
-well. This returns the clone.
-\end{methoddesc}
-
-
-\subsubsection{NodeList Objects \label{dom-nodelist-objects}}
-
-A \class{NodeList} represents a sequence of nodes. These objects are
-used in two ways in the DOM Core recommendation: the
-\class{Element} objects provides one as its list of child nodes, and
-the \method{getElementsByTagName()} and
-\method{getElementsByTagNameNS()} methods of \class{Node} return
-objects with this interface to represent query results.
-
-The DOM Level~2 recommendation defines one method and one attribute
-for these objects:
-
-\begin{methoddesc}[NodeList]{item}{i}
- Return the \var{i}'th item from the sequence, if there is one, or
- \code{None}. The index \var{i} is not allowed to be less then zero
- or greater than or equal to the length of the sequence.
-\end{methoddesc}
-
-\begin{memberdesc}[NodeList]{length}
- The number of nodes in the sequence.
-\end{memberdesc}
-
-In addition, the Python DOM interface requires that some additional
-support is provided to allow \class{NodeList} objects to be used as
-Python sequences. All \class{NodeList} implementations must include
-support for \method{__len__()} and \method{__getitem__()}; this allows
-iteration over the \class{NodeList} in \keyword{for} statements and
-proper support for the \function{len()} built-in function.
-
-If a DOM implementation supports modification of the document, the
-\class{NodeList} implementation must also support the
-\method{__setitem__()} and \method{__delitem__()} methods.
-
-
-\subsubsection{DocumentType Objects \label{dom-documenttype-objects}}
-
-Information about the notations and entities declared by a document
-(including the external subset if the parser uses it and can provide
-the information) is available from a \class{DocumentType} object. The
-\class{DocumentType} for a document is available from the
-\class{Document} object's \member{doctype} attribute; if there is no
-\code{DOCTYPE} declaration for the document, the document's
-\member{doctype} attribute will be set to \code{None} instead of an
-instance of this interface.
-
-\class{DocumentType} is a specialization of \class{Node}, and adds the
-following attributes:
-
-\begin{memberdesc}[DocumentType]{publicId}
- The public identifier for the external subset of the document type
- definition. This will be a string or \code{None}.
-\end{memberdesc}
-
-\begin{memberdesc}[DocumentType]{systemId}
- The system identifier for the external subset of the document type
- definition. This will be a URI as a string, or \code{None}.
-\end{memberdesc}
-
-\begin{memberdesc}[DocumentType]{internalSubset}
- A string giving the complete internal subset from the document.
- This does not include the brackets which enclose the subset. If the
- document has no internal subset, this should be \code{None}.
-\end{memberdesc}
-
-\begin{memberdesc}[DocumentType]{name}
- The name of the root element as given in the \code{DOCTYPE}
- declaration, if present.
-\end{memberdesc}
-
-\begin{memberdesc}[DocumentType]{entities}
- This is a \class{NamedNodeMap} giving the definitions of external
- entities. For entity names defined more than once, only the first
- definition is provided (others are ignored as required by the XML
- recommendation). This may be \code{None} if the information is not
- provided by the parser, or if no entities are defined.
-\end{memberdesc}
-
-\begin{memberdesc}[DocumentType]{notations}
- This is a \class{NamedNodeMap} giving the definitions of notations.
- For notation names defined more than once, only the first definition
- is provided (others are ignored as required by the XML
- recommendation). This may be \code{None} if the information is not
- provided by the parser, or if no notations are defined.
-\end{memberdesc}
-
-
-\subsubsection{Document Objects \label{dom-document-objects}}
-
-A \class{Document} represents an entire XML document, including its
-constituent elements, attributes, processing instructions, comments
-etc. Remeber that it inherits properties from \class{Node}.
-
-\begin{memberdesc}[Document]{documentElement}
-The one and only root element of the document.
-\end{memberdesc}
-
-\begin{methoddesc}[Document]{createElement}{tagName}
-Create and return a new element node. The element is not inserted
-into the document when it is created. You need to explicitly insert
-it with one of the other methods such as \method{insertBefore()} or
-\method{appendChild()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{createElementNS}{namespaceURI, tagName}
-Create and return a new element with a namespace. The
-\var{tagName} may have a prefix. The element is not inserted into the
-document when it is created. You need to explicitly insert it with
-one of the other methods such as \method{insertBefore()} or
-\method{appendChild()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{createTextNode}{data}
-Create and return a text node containing the data passed as a
-parameter. As with the other creation methods, this one does not
-insert the node into the tree.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{createComment}{data}
-Create and return a comment node containing the data passed as a
-parameter. As with the other creation methods, this one does not
-insert the node into the tree.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{createProcessingInstruction}{target, data}
-Create and return a processing instruction node containing the
-\var{target} and \var{data} passed as parameters. As with the other
-creation methods, this one does not insert the node into the tree.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{createAttribute}{name}
-Create and return an attribute node. This method does not associate
-the attribute node with any particular element. You must use
-\method{setAttributeNode()} on the appropriate \class{Element} object
-to use the newly created attribute instance.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{createAttributeNS}{namespaceURI, qualifiedName}
-Create and return an attribute node with a namespace. The
-\var{tagName} may have a prefix. This method does not associate the
-attribute node with any particular element. You must use
-\method{setAttributeNode()} on the appropriate \class{Element} object
-to use the newly created attribute instance.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{getElementsByTagName}{tagName}
-Search for all descendants (direct children, children's children,
-etc.) with a particular element type name.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{getElementsByTagNameNS}{namespaceURI, localName}
-Search for all descendants (direct children, children's children,
-etc.) with a particular namespace URI and localname. The localname is
-the part of the namespace after the prefix.
-\end{methoddesc}
-
-
-\subsubsection{Element Objects \label{dom-element-objects}}
-
-\class{Element} is a subclass of \class{Node}, so inherits all the
-attributes of that class.
-
-\begin{memberdesc}[Element]{tagName}
-The element type name. In a namespace-using document it may have
-colons in it. The value is a string.
-\end{memberdesc}
-
-\begin{methoddesc}[Element]{getElementsByTagName}{tagName}
-Same as equivalent method in the \class{Document} class.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{getElementsByTagNameNS}{tagName}
-Same as equivalent method in the \class{Document} class.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{hasAttribute}{name}
-Returns true if the element has an attribute named by \var{name}.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{hasAttributeNS}{namespaceURI, localName}
-Returns true if the element has an attribute named by
-\var{namespaceURI} and \var{localName}.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{getAttribute}{name}
-Return the value of the attribute named by \var{name} as a
-string. If no such attribute exists, an empty string is returned,
-as if the attribute had no value.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{getAttributeNode}{attrname}
-Return the \class{Attr} node for the attribute named by
-\var{attrname}.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{getAttributeNS}{namespaceURI, localName}
-Return the value of the attribute named by \var{namespaceURI} and
-\var{localName} as a string. If no such attribute exists, an empty
-string is returned, as if the attribute had no value.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{getAttributeNodeNS}{namespaceURI, localName}
-Return an attribute value as a node, given a \var{namespaceURI} and
-\var{localName}.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{removeAttribute}{name}
-Remove an attribute by name. No exception is raised if there is no
-matching attribute.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{removeAttributeNode}{oldAttr}
-Remove and return \var{oldAttr} from the attribute list, if present.
-If \var{oldAttr} is not present, \exception{NotFoundErr} is raised.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{removeAttributeNS}{namespaceURI, localName}
-Remove an attribute by name. Note that it uses a localName, not a
-qname. No exception is raised if there is no matching attribute.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{setAttribute}{name, value}
-Set an attribute value from a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{setAttributeNode}{newAttr}
-Add a new attribute node to the element, replacing an existing
-attribute if necessary if the \member{name} attribute matches. If a
-replacement occurs, the old attribute node will be returned. If
-\var{newAttr} is already in use, \exception{InuseAttributeErr} will be
-raised.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{setAttributeNodeNS}{newAttr}
-Add a new attribute node to the element, replacing an existing
-attribute if necessary if the \member{namespaceURI} and
-\member{localName} attributes match. If a replacement occurs, the old
-attribute node will be returned. If \var{newAttr} is already in use,
-\exception{InuseAttributeErr} will be raised.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{setAttributeNS}{namespaceURI, qname, value}
-Set an attribute value from a string, given a \var{namespaceURI} and a
-\var{qname}. Note that a qname is the whole attribute name. This is
-different than above.
-\end{methoddesc}
-
-
-\subsubsection{Attr Objects \label{dom-attr-objects}}
-
-\class{Attr} inherits from \class{Node}, so inherits all its
-attributes.
-
-\begin{memberdesc}[Attr]{name}
-The attribute name. In a namespace-using document it may have colons
-in it.
-\end{memberdesc}
-
-\begin{memberdesc}[Attr]{localName}
-The part of the name following the colon if there is one, else the
-entire name. This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Attr]{prefix}
-The part of the name preceding the colon if there is one, else the
-empty string.
-\end{memberdesc}
-
-
-\subsubsection{NamedNodeMap Objects \label{dom-attributelist-objects}}
-
-\class{NamedNodeMap} does \emph{not} inherit from \class{Node}.
-
-\begin{memberdesc}[NamedNodeMap]{length}
-The length of the attribute list.
-\end{memberdesc}
-
-\begin{methoddesc}[NamedNodeMap]{item}{index}
-Return an attribute with a particular index. The order you get the
-attributes in is arbitrary but will be consistent for the life of a
-DOM. Each item is an attribute node. Get its value with the
-\member{value} attribute.
-\end{methoddesc}
-
-There are also experimental methods that give this class more mapping
-behavior. You can use them or you can use the standardized
-\method{getAttribute*()} family of methods on the \class{Element}
-objects.
-
-
-\subsubsection{Comment Objects \label{dom-comment-objects}}
-
-\class{Comment} represents a comment in the XML document. It is a
-subclass of \class{Node}, but cannot have child nodes.
-
-\begin{memberdesc}[Comment]{data}
-The content of the comment as a string. The attribute contains all
-characters between the leading \code{<!-}\code{-} and trailing
-\code{-}\code{->}, but does not include them.
-\end{memberdesc}
-
-
-\subsubsection{Text and CDATASection Objects \label{dom-text-objects}}
-
-The \class{Text} interface represents text in the XML document. If
-the parser and DOM implementation support the DOM's XML extension,
-portions of the text enclosed in CDATA marked sections are stored in
-\class{CDATASection} objects. These two interfaces are identical, but
-provide different values for the \member{nodeType} attribute.
-
-These interfaces extend the \class{Node} interface. They cannot have
-child nodes.
-
-\begin{memberdesc}[Text]{data}
-The content of the text node as a string.
-\end{memberdesc}
-
-\begin{notice}
- The use of a \class{CDATASection} node does not indicate that the
- node represents a complete CDATA marked section, only that the
- content of the node was part of a CDATA section. A single CDATA
- section may be represented by more than one node in the document
- tree. There is no way to determine whether two adjacent
- \class{CDATASection} nodes represent different CDATA marked
- sections.
-\end{notice}
-
-
-\subsubsection{ProcessingInstruction Objects \label{dom-pi-objects}}
-
-Represents a processing instruction in the XML document; this inherits
-from the \class{Node} interface and cannot have child nodes.
-
-\begin{memberdesc}[ProcessingInstruction]{target}
-The content of the processing instruction up to the first whitespace
-character. This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[ProcessingInstruction]{data}
-The content of the processing instruction following the first
-whitespace character.
-\end{memberdesc}
-
-
-\subsubsection{Exceptions \label{dom-exceptions}}
-
-\versionadded{2.1}
-
-The DOM Level~2 recommendation defines a single exception,
-\exception{DOMException}, and a number of constants that allow
-applications to determine what sort of error occurred.
-\exception{DOMException} instances carry a \member{code} attribute
-that provides the appropriate value for the specific exception.
-
-The Python DOM interface provides the constants, but also expands the
-set of exceptions so that a specific exception exists for each of the
-exception codes defined by the DOM. The implementations must raise
-the appropriate specific exception, each of which carries the
-appropriate value for the \member{code} attribute.
-
-\begin{excdesc}{DOMException}
- Base exception class used for all specific DOM exceptions. This
- exception class cannot be directly instantiated.
-\end{excdesc}
-
-\begin{excdesc}{DomstringSizeErr}
- Raised when a specified range of text does not fit into a string.
- This is not known to be used in the Python DOM implementations, but
- may be received from DOM implementations not written in Python.
-\end{excdesc}
-
-\begin{excdesc}{HierarchyRequestErr}
- Raised when an attempt is made to insert a node where the node type
- is not allowed.
-\end{excdesc}
-
-\begin{excdesc}{IndexSizeErr}
- Raised when an index or size parameter to a method is negative or
- exceeds the allowed values.
-\end{excdesc}
-
-\begin{excdesc}{InuseAttributeErr}
- Raised when an attempt is made to insert an \class{Attr} node that
- is already present elsewhere in the document.
-\end{excdesc}
-
-\begin{excdesc}{InvalidAccessErr}
- Raised if a parameter or an operation is not supported on the
- underlying object.
-\end{excdesc}
-
-\begin{excdesc}{InvalidCharacterErr}
- This exception is raised when a string parameter contains a
- character that is not permitted in the context it's being used in by
- the XML 1.0 recommendation. For example, attempting to create an
- \class{Element} node with a space in the element type name will
- cause this error to be raised.
-\end{excdesc}
-
-\begin{excdesc}{InvalidModificationErr}
- Raised when an attempt is made to modify the type of a node.
-\end{excdesc}
-
-\begin{excdesc}{InvalidStateErr}
- Raised when an attempt is made to use an object that is not defined or is no
- longer usable.
-\end{excdesc}
-
-\begin{excdesc}{NamespaceErr}
- If an attempt is made to change any object in a way that is not
- permitted with regard to the
- \citetitle[http://www.w3.org/TR/REC-xml-names/]{Namespaces in XML}
- recommendation, this exception is raised.
-\end{excdesc}
-
-\begin{excdesc}{NotFoundErr}
- Exception when a node does not exist in the referenced context. For
- example, \method{NamedNodeMap.removeNamedItem()} will raise this if
- the node passed in does not exist in the map.
-\end{excdesc}
-
-\begin{excdesc}{NotSupportedErr}
- Raised when the implementation does not support the requested type
- of object or operation.
-\end{excdesc}
-
-\begin{excdesc}{NoDataAllowedErr}
- This is raised if data is specified for a node which does not
- support data.
- % XXX a better explanation is needed!
-\end{excdesc}
-
-\begin{excdesc}{NoModificationAllowedErr}
- Raised on attempts to modify an object where modifications are not
- allowed (such as for read-only nodes).
-\end{excdesc}
-
-\begin{excdesc}{SyntaxErr}
- Raised when an invalid or illegal string is specified.
- % XXX how is this different from InvalidCharacterErr ???
-\end{excdesc}
-
-\begin{excdesc}{WrongDocumentErr}
- Raised when a node is inserted in a different document than it
- currently belongs to, and the implementation does not support
- migrating the node from one document to the other.
-\end{excdesc}
-
-The exception codes defined in the DOM recommendation map to the
-exceptions described above according to this table:
-
-\begin{tableii}{l|l}{constant}{Constant}{Exception}
- \lineii{DOMSTRING_SIZE_ERR}{\exception{DomstringSizeErr}}
- \lineii{HIERARCHY_REQUEST_ERR}{\exception{HierarchyRequestErr}}
- \lineii{INDEX_SIZE_ERR}{\exception{IndexSizeErr}}
- \lineii{INUSE_ATTRIBUTE_ERR}{\exception{InuseAttributeErr}}
- \lineii{INVALID_ACCESS_ERR}{\exception{InvalidAccessErr}}
- \lineii{INVALID_CHARACTER_ERR}{\exception{InvalidCharacterErr}}
- \lineii{INVALID_MODIFICATION_ERR}{\exception{InvalidModificationErr}}
- \lineii{INVALID_STATE_ERR}{\exception{InvalidStateErr}}
- \lineii{NAMESPACE_ERR}{\exception{NamespaceErr}}
- \lineii{NOT_FOUND_ERR}{\exception{NotFoundErr}}
- \lineii{NOT_SUPPORTED_ERR}{\exception{NotSupportedErr}}
- \lineii{NO_DATA_ALLOWED_ERR}{\exception{NoDataAllowedErr}}
- \lineii{NO_MODIFICATION_ALLOWED_ERR}{\exception{NoModificationAllowedErr}}
- \lineii{SYNTAX_ERR}{\exception{SyntaxErr}}
- \lineii{WRONG_DOCUMENT_ERR}{\exception{WrongDocumentErr}}
-\end{tableii}
-
-
-\subsection{Conformance \label{dom-conformance}}
-
-This section describes the conformance requirements and relationships
-between the Python DOM API, the W3C DOM recommendations, and the OMG
-IDL mapping for Python.
-
-
-\subsubsection{Type Mapping \label{dom-type-mapping}}
-
-The primitive IDL types used in the DOM specification are mapped to
-Python types according to the following table.
-
-\begin{tableii}{l|l}{code}{IDL Type}{Python Type}
- \lineii{boolean}{\code{IntegerType} (with a value of \code{0} or \code{1})}
- \lineii{int}{\code{IntegerType}}
- \lineii{long int}{\code{IntegerType}}
- \lineii{unsigned int}{\code{IntegerType}}
-\end{tableii}
-
-Additionally, the \class{DOMString} defined in the recommendation is
-mapped to a Python string or Unicode string. Applications should
-be able to handle Unicode whenever a string is returned from the DOM.
-
-The IDL \keyword{null} value is mapped to \code{None}, which may be
-accepted or provided by the implementation whenever \keyword{null} is
-allowed by the API.
-
-
-\subsubsection{Accessor Methods \label{dom-accessor-methods}}
-
-The mapping from OMG IDL to Python defines accessor functions for IDL
-\keyword{attribute} declarations in much the way the Java mapping
-does. Mapping the IDL declarations
-
-\begin{verbatim}
-readonly attribute string someValue;
- attribute string anotherValue;
-\end{verbatim}
-
-yields three accessor functions: a ``get'' method for
-\member{someValue} (\method{_get_someValue()}), and ``get'' and
-``set'' methods for
-\member{anotherValue} (\method{_get_anotherValue()} and
-\method{_set_anotherValue()}). The mapping, in particular, does not
-require that the IDL attributes are accessible as normal Python
-attributes: \code{\var{object}.someValue} is \emph{not} required to
-work, and may raise an \exception{AttributeError}.
-
-The Python DOM API, however, \emph{does} require that normal attribute
-access work. This means that the typical surrogates generated by
-Python IDL compilers are not likely to work, and wrapper objects may
-be needed on the client if the DOM objects are accessed via CORBA.
-While this does require some additional consideration for CORBA DOM
-clients, the implementers with experience using DOM over CORBA from
-Python do not consider this a problem. Attributes that are declared
-\keyword{readonly} may not restrict write access in all DOM
-implementations.
-
-In the Python DOM API, accessor functions are not required. If provided,
-they should take the form defined by the Python IDL mapping, but
-these methods are considered unnecessary since the attributes are
-accessible directly from Python. ``Set'' accessors should never be
-provided for \keyword{readonly} attributes.
-
-The IDL definitions do not fully embody the requirements of the W3C DOM
-API, such as the notion of certain objects, such as the return value of
-\method{getElementsByTagName()}, being ``live''. The Python DOM API
-does not require implementations to enforce such requirements.
diff --git a/Doc/lib/xmldomminidom.tex b/Doc/lib/xmldomminidom.tex
deleted file mode 100644
index 093915f..0000000
--- a/Doc/lib/xmldomminidom.tex
+++ /dev/null
@@ -1,285 +0,0 @@
-\section{\module{xml.dom.minidom} ---
- Lightweight DOM implementation}
-
-\declaremodule{standard}{xml.dom.minidom}
-\modulesynopsis{Lightweight Document Object Model (DOM) implementation.}
-\moduleauthor{Paul Prescod}{paul@prescod.net}
-\sectionauthor{Paul Prescod}{paul@prescod.net}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\versionadded{2.0}
-
-\module{xml.dom.minidom} is a light-weight implementation of the
-Document Object Model interface. It is intended to be
-simpler than the full DOM and also significantly smaller.
-
-DOM applications typically start by parsing some XML into a DOM. With
-\module{xml.dom.minidom}, this is done through the parse functions:
-
-\begin{verbatim}
-from xml.dom.minidom import parse, parseString
-
-dom1 = parse('c:\\temp\\mydata.xml') # parse an XML file by name
-
-datasource = open('c:\\temp\\mydata.xml')
-dom2 = parse(datasource) # parse an open file
-
-dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>')
-\end{verbatim}
-
-The \function{parse()} function can take either a filename or an open
-file object.
-
-\begin{funcdesc}{parse}{filename_or_file{, parser}}
- Return a \class{Document} from the given input. \var{filename_or_file}
- may be either a file name, or a file-like object. \var{parser}, if
- given, must be a SAX2 parser object. This function will change the
- document handler of the parser and activate namespace support; other
- parser configuration (like setting an entity resolver) must have been
- done in advance.
-\end{funcdesc}
-
-If you have XML in a string, you can use the
-\function{parseString()} function instead:
-
-\begin{funcdesc}{parseString}{string\optional{, parser}}
- Return a \class{Document} that represents the \var{string}. This
- method creates a \class{StringIO} object for the string and passes
- that on to \function{parse}.
-\end{funcdesc}
-
-Both functions return a \class{Document} object representing the
-content of the document.
-
-What the \function{parse()} and \function{parseString()} functions do
-is connect an XML parser with a ``DOM builder'' that can accept parse
-events from any SAX parser and convert them into a DOM tree. The name
-of the functions are perhaps misleading, but are easy to grasp when
-learning the interfaces. The parsing of the document will be
-completed before these functions return; it's simply that these
-functions do not provide a parser implementation themselves.
-
-You can also create a \class{Document} by calling a method on a ``DOM
-Implementation'' object. You can get this object either by calling
-the \function{getDOMImplementation()} function in the
-\refmodule{xml.dom} package or the \module{xml.dom.minidom} module.
-Using the implementation from the \module{xml.dom.minidom} module will
-always return a \class{Document} instance from the minidom
-implementation, while the version from \refmodule{xml.dom} may provide
-an alternate implementation (this is likely if you have the
-\ulink{PyXML package}{http://pyxml.sourceforge.net/} installed). Once
-you have a \class{Document}, you can add child nodes to it to populate
-the DOM:
-
-\begin{verbatim}
-from xml.dom.minidom import getDOMImplementation
-
-impl = getDOMImplementation()
-
-newdoc = impl.createDocument(None, "some_tag", None)
-top_element = newdoc.documentElement
-text = newdoc.createTextNode('Some textual content.')
-top_element.appendChild(text)
-\end{verbatim}
-
-Once you have a DOM document object, you can access the parts of your
-XML document through its properties and methods. These properties are
-defined in the DOM specification. The main property of the document
-object is the \member{documentElement} property. It gives you the
-main element in the XML document: the one that holds all others. Here
-is an example program:
-
-\begin{verbatim}
-dom3 = parseString("<myxml>Some data</myxml>")
-assert dom3.documentElement.tagName == "myxml"
-\end{verbatim}
-
-When you are finished with a DOM, you should clean it up. This is
-necessary because some versions of Python do not support garbage
-collection of objects that refer to each other in a cycle. Until this
-restriction is removed from all versions of Python, it is safest to
-write your code as if cycles would not be cleaned up.
-
-The way to clean up a DOM is to call its \method{unlink()} method:
-
-\begin{verbatim}
-dom1.unlink()
-dom2.unlink()
-dom3.unlink()
-\end{verbatim}
-
-\method{unlink()} is a \module{xml.dom.minidom}-specific extension to
-the DOM API. After calling \method{unlink()} on a node, the node and
-its descendants are essentially useless.
-
-\begin{seealso}
- \seetitle[http://www.w3.org/TR/REC-DOM-Level-1/]{Document Object
- Model (DOM) Level 1 Specification}
- {The W3C recommendation for the
- DOM supported by \module{xml.dom.minidom}.}
-\end{seealso}
-
-
-\subsection{DOM Objects \label{dom-objects}}
-
-The definition of the DOM API for Python is given as part of the
-\refmodule{xml.dom} module documentation. This section lists the
-differences between the API and \refmodule{xml.dom.minidom}.
-
-
-\begin{methoddesc}[Node]{unlink}{}
-Break internal references within the DOM so that it will be garbage
-collected on versions of Python without cyclic GC. Even when cyclic
-GC is available, using this can make large amounts of memory available
-sooner, so calling this on DOM objects as soon as they are no longer
-needed is good practice. This only needs to be called on the
-\class{Document} object, but may be called on child nodes to discard
-children of that node.
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{writexml}{writer\optional{,indent=""\optional{,addindent=""\optional{,newl=""}}}}
-Write XML to the writer object. The writer should have a
-\method{write()} method which matches that of the file object
-interface. The \var{indent} parameter is the indentation of the current
-node. The \var{addindent} parameter is the incremental indentation to use
-for subnodes of the current one. The \var{newl} parameter specifies the
-string to use to terminate newlines.
-
-\versionchanged[The optional keyword parameters
-\var{indent}, \var{addindent}, and \var{newl} were added to support pretty
-output]{2.1}
-
-\versionchanged[For the \class{Document} node, an additional keyword
-argument \var{encoding} can be used to specify the encoding field of the XML
-header]{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{toxml}{\optional{encoding}}
-Return the XML that the DOM represents as a string.
-
-With no argument, the XML header does not specify an encoding, and the
-result is Unicode string if the default encoding cannot represent all
-characters in the document. Encoding this string in an encoding other
-than UTF-8 is likely incorrect, since UTF-8 is the default encoding of
-XML.
-
-With an explicit \var{encoding} argument, the result is a byte string
-in the specified encoding. It is recommended that this argument is
-always specified. To avoid \exception{UnicodeError} exceptions in case of
-unrepresentable text data, the encoding argument should be specified
-as "utf-8".
-
-\versionchanged[the \var{encoding} argument was introduced]{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{toprettyxml}{\optional{indent\optional{, newl}}}
-Return a pretty-printed version of the document. \var{indent} specifies
-the indentation string and defaults to a tabulator; \var{newl} specifies
-the string emitted at the end of each line and defaults to \code{\e n}.
-
-\versionadded{2.1}
-\versionchanged[the encoding argument; see \method{toxml()}]{2.3}
-\end{methoddesc}
-
-The following standard DOM methods have special considerations with
-\refmodule{xml.dom.minidom}:
-
-\begin{methoddesc}[Node]{cloneNode}{deep}
-Although this method was present in the version of
-\refmodule{xml.dom.minidom} packaged with Python 2.0, it was seriously
-broken. This has been corrected for subsequent releases.
-\end{methoddesc}
-
-
-\subsection{DOM Example \label{dom-example}}
-
-This example program is a fairly realistic example of a simple
-program. In this particular case, we do not take much advantage
-of the flexibility of the DOM.
-
-\verbatiminput{minidom-example.py}
-
-
-\subsection{minidom and the DOM standard \label{minidom-and-dom}}
-
-The \refmodule{xml.dom.minidom} module is essentially a DOM
-1.0-compatible DOM with some DOM 2 features (primarily namespace
-features).
-
-Usage of the DOM interface in Python is straight-forward. The
-following mapping rules apply:
-
-\begin{itemize}
-\item Interfaces are accessed through instance objects. Applications
- should not instantiate the classes themselves; they should use
- the creator functions available on the \class{Document} object.
- Derived interfaces support all operations (and attributes) from
- the base interfaces, plus any new operations.
-
-\item Operations are used as methods. Since the DOM uses only
- \keyword{in} parameters, the arguments are passed in normal
- order (from left to right). There are no optional
- arguments. \keyword{void} operations return \code{None}.
-
-\item IDL attributes map to instance attributes. For compatibility
- with the OMG IDL language mapping for Python, an attribute
- \code{foo} can also be accessed through accessor methods
- \method{_get_foo()} and \method{_set_foo()}. \keyword{readonly}
- attributes must not be changed; this is not enforced at
- runtime.
-
-\item The types \code{short int}, \code{unsigned int}, \code{unsigned
- long long}, and \code{boolean} all map to Python integer
- objects.
-
-\item The type \code{DOMString} maps to Python strings.
- \refmodule{xml.dom.minidom} supports either byte or Unicode
- strings, but will normally produce Unicode strings. Values
- of type \code{DOMString} may also be \code{None} where allowed
- to have the IDL \code{null} value by the DOM specification from
- the W3C.
-
-\item \keyword{const} declarations map to variables in their
- respective scope
- (e.g. \code{xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE});
- they must not be changed.
-
-\item \code{DOMException} is currently not supported in
- \refmodule{xml.dom.minidom}. Instead,
- \refmodule{xml.dom.minidom} uses standard Python exceptions such
- as \exception{TypeError} and \exception{AttributeError}.
-
-\item \class{NodeList} objects are implemented using Python's built-in
- list type. Starting with Python 2.2, these objects provide the
- interface defined in the DOM specification, but with earlier
- versions of Python they do not support the official API. They
- are, however, much more ``Pythonic'' than the interface defined
- in the W3C recommendations.
-\end{itemize}
-
-
-The following interfaces have no implementation in
-\refmodule{xml.dom.minidom}:
-
-\begin{itemize}
-\item \class{DOMTimeStamp}
-
-\item \class{DocumentType} (added in Python 2.1)
-
-\item \class{DOMImplementation} (added in Python 2.1)
-
-\item \class{CharacterData}
-
-\item \class{CDATASection}
-
-\item \class{Notation}
-
-\item \class{Entity}
-
-\item \class{EntityReference}
-
-\item \class{DocumentFragment}
-\end{itemize}
-
-Most of these reflect information in the XML document that is not of
-general utility to most DOM users.
diff --git a/Doc/lib/xmldompulldom.tex b/Doc/lib/xmldompulldom.tex
deleted file mode 100644
index a2ce667..0000000
--- a/Doc/lib/xmldompulldom.tex
+++ /dev/null
@@ -1,61 +0,0 @@
-\section{\module{xml.dom.pulldom} ---
- Support for building partial DOM trees}
-
-\declaremodule{standard}{xml.dom.pulldom}
-\modulesynopsis{Support for building partial DOM trees from SAX events.}
-\moduleauthor{Paul Prescod}{paul@prescod.net}
-
-\versionadded{2.0}
-
-\module{xml.dom.pulldom} allows building only selected portions of a
-Document Object Model representation of a document from SAX events.
-
-
-\begin{classdesc}{PullDOM}{\optional{documentFactory}}
- \class{xml.sax.handler.ContentHandler} implementation that ...
-\end{classdesc}
-
-
-\begin{classdesc}{DOMEventStream}{stream, parser, bufsize}
- ...
-\end{classdesc}
-
-
-\begin{classdesc}{SAX2DOM}{\optional{documentFactory}}
- \class{xml.sax.handler.ContentHandler} implementation that ...
-\end{classdesc}
-
-
-\begin{funcdesc}{parse}{stream_or_string\optional{,
- parser\optional{, bufsize}}}
- ...
-\end{funcdesc}
-
-
-\begin{funcdesc}{parseString}{string\optional{, parser}}
- ...
-\end{funcdesc}
-
-
-\begin{datadesc}{default_bufsize}
- Default value for the \var{bufsize} parameter to \function{parse()}.
- \versionchanged[The value of this variable can be changed before
- calling \function{parse()} and the new value will
- take effect]{2.1}
-\end{datadesc}
-
-
-\subsection{DOMEventStream Objects \label{domeventstream-objects}}
-
-
-\begin{methoddesc}[DOMEventStream]{getEvent}{}
- ...
-\end{methoddesc}
-
-\begin{methoddesc}[DOMEventStream]{expandNode}{node}
- ...
-\end{methoddesc}
-
-\begin{methoddesc}[DOMEventStream]{reset}{}
- ...
-\end{methoddesc}
diff --git a/Doc/lib/xmletree.tex b/Doc/lib/xmletree.tex
deleted file mode 100644
index 789062d..0000000
--- a/Doc/lib/xmletree.tex
+++ /dev/null
@@ -1,27 +0,0 @@
-\section{\module{xml.etree} ---
- The ElementTree API for XML}
-
-\declaremodule{standard}{xml.etree}
-\modulesynopsis{Package containing common ElementTree modules.}
-\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com}
-
-\versionadded{2.5}
-
-The ElementTree package is a simple, efficient, and quite popular
-library for XML manipulation in Python.
-
-The \module{xml.etree} package contains the most common components
-from the ElementTree API library.
-In the current release, this package contains the \module{ElementTree},
-\module{ElementPath}, and \module{ElementInclude} modules from the full
-ElementTree distribution.
-
-% XXX To be continued!
-
-\begin{seealso}
-\seetitle[http://effbot.org/tag/elementtree]
- {ElementTree Overview}
- {The home page for \module{ElementTree}. This includes links
- to additional documentation, alternative implementations, and
- other add-ons.}
-\end{seealso}
diff --git a/Doc/lib/xmlsax.tex b/Doc/lib/xmlsax.tex
deleted file mode 100644
index 838c279..0000000
--- a/Doc/lib/xmlsax.tex
+++ /dev/null
@@ -1,143 +0,0 @@
-\section{\module{xml.sax} ---
- Support for SAX2 parsers}
-
-\declaremodule{standard}{xml.sax}
-\modulesynopsis{Package containing SAX2 base classes and convenience
- functions.}
-\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\versionadded{2.0}
-
-
-The \module{xml.sax} package provides a number of modules which
-implement the Simple API for XML (SAX) interface for Python. The
-package itself provides the SAX exceptions and the convenience
-functions which will be most used by users of the SAX API.
-
-The convenience functions are:
-
-\begin{funcdesc}{make_parser}{\optional{parser_list}}
- Create and return a SAX \class{XMLReader} object. The first parser
- found will be used. If \var{parser_list} is provided, it must be a
- sequence of strings which name modules that have a function named
- \function{create_parser()}. Modules listed in \var{parser_list}
- will be used before modules in the default list of parsers.
-\end{funcdesc}
-
-\begin{funcdesc}{parse}{filename_or_stream, handler\optional{, error_handler}}
- Create a SAX parser and use it to parse a document. The document,
- passed in as \var{filename_or_stream}, can be a filename or a file
- object. The \var{handler} parameter needs to be a SAX
- \class{ContentHandler} instance. If \var{error_handler} is given,
- it must be a SAX \class{ErrorHandler} instance; if omitted,
- \exception{SAXParseException} will be raised on all errors. There
- is no return value; all work must be done by the \var{handler}
- passed in.
-\end{funcdesc}
-
-\begin{funcdesc}{parseString}{string, handler\optional{, error_handler}}
- Similar to \function{parse()}, but parses from a buffer \var{string}
- received as a parameter.
-\end{funcdesc}
-
-A typical SAX application uses three kinds of objects: readers,
-handlers and input sources. ``Reader'' in this context is another
-term for parser, i.e.\ some piece of code that reads the bytes or
-characters from the input source, and produces a sequence of events.
-The events then get distributed to the handler objects, i.e.\ the
-reader invokes a method on the handler. A SAX application must
-therefore obtain a reader object, create or open the input sources,
-create the handlers, and connect these objects all together. As the
-final step of preparation, the reader is called to parse the input.
-During parsing, methods on the handler objects are called based on
-structural and syntactic events from the input data.
-
-For these objects, only the interfaces are relevant; they are normally
-not instantiated by the application itself. Since Python does not have
-an explicit notion of interface, they are formally introduced as
-classes, but applications may use implementations which do not inherit
-from the provided classes. The \class{InputSource}, \class{Locator},
-\class{Attributes}, \class{AttributesNS}, and
-\class{XMLReader} interfaces are defined in the module
-\refmodule{xml.sax.xmlreader}. The handler interfaces are defined in
-\refmodule{xml.sax.handler}. For convenience, \class{InputSource}
-(which is often instantiated directly) and the handler classes are
-also available from \module{xml.sax}. These interfaces are described
-below.
-
-In addition to these classes, \module{xml.sax} provides the following
-exception classes.
-
-\begin{excclassdesc}{SAXException}{msg\optional{, exception}}
- Encapsulate an XML error or warning. This class can contain basic
- error or warning information from either the XML parser or the
- application: it can be subclassed to provide additional
- functionality or to add localization. Note that although the
- handlers defined in the \class{ErrorHandler} interface receive
- instances of this exception, it is not required to actually raise
- the exception --- it is also useful as a container for information.
-
- When instantiated, \var{msg} should be a human-readable description
- of the error. The optional \var{exception} parameter, if given,
- should be \code{None} or an exception that was caught by the parsing
- code and is being passed along as information.
-
- This is the base class for the other SAX exception classes.
-\end{excclassdesc}
-
-\begin{excclassdesc}{SAXParseException}{msg, exception, locator}
- Subclass of \exception{SAXException} raised on parse errors.
- Instances of this class are passed to the methods of the SAX
- \class{ErrorHandler} interface to provide information about the
- parse error. This class supports the SAX \class{Locator} interface
- as well as the \class{SAXException} interface.
-\end{excclassdesc}
-
-\begin{excclassdesc}{SAXNotRecognizedException}{msg\optional{, exception}}
- Subclass of \exception{SAXException} raised when a SAX
- \class{XMLReader} is confronted with an unrecognized feature or
- property. SAX applications and extensions may use this class for
- similar purposes.
-\end{excclassdesc}
-
-\begin{excclassdesc}{SAXNotSupportedException}{msg\optional{, exception}}
- Subclass of \exception{SAXException} raised when a SAX
- \class{XMLReader} is asked to enable a feature that is not
- supported, or to set a property to a value that the implementation
- does not support. SAX applications and extensions may use this
- class for similar purposes.
-\end{excclassdesc}
-
-
-\begin{seealso}
- \seetitle[http://www.saxproject.org/]{SAX: The Simple API for
- XML}{This site is the focal point for the definition of
- the SAX API. It provides a Java implementation and online
- documentation. Links to implementations and historical
- information are also available.}
-
- \seemodule{xml.sax.handler}{Definitions of the interfaces for
- application-provided objects.}
-
- \seemodule{xml.sax.saxutils}{Convenience functions for use in SAX
- applications.}
-
- \seemodule{xml.sax.xmlreader}{Definitions of the interfaces for
- parser-provided objects.}
-\end{seealso}
-
-
-\subsection{SAXException Objects \label{sax-exception-objects}}
-
-The \class{SAXException} exception class supports the following
-methods:
-
-\begin{methoddesc}[SAXException]{getMessage}{}
- Return a human-readable message describing the error condition.
-\end{methoddesc}
-
-\begin{methoddesc}[SAXException]{getException}{}
- Return an encapsulated exception object, or \code{None}.
-\end{methoddesc}
diff --git a/Doc/lib/xmlsaxhandler.tex b/Doc/lib/xmlsaxhandler.tex
deleted file mode 100644
index c3c72e7..0000000
--- a/Doc/lib/xmlsaxhandler.tex
+++ /dev/null
@@ -1,381 +0,0 @@
-\section{\module{xml.sax.handler} ---
- Base classes for SAX handlers}
-
-\declaremodule{standard}{xml.sax.handler}
-\modulesynopsis{Base classes for SAX event handlers.}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}
-
-\versionadded{2.0}
-
-
-The SAX API defines four kinds of handlers: content handlers, DTD
-handlers, error handlers, and entity resolvers. Applications normally
-only need to implement those interfaces whose events they are
-interested in; they can implement the interfaces in a single object or
-in multiple objects. Handler implementations should inherit from the
-base classes provided in the module \module{xml.sax.handler}, so that all
-methods get default implementations.
-
-\begin{classdesc*}{ContentHandler}
- This is the main callback interface in SAX, and the one most
- important to applications. The order of events in this interface
- mirrors the order of the information in the document.
-\end{classdesc*}
-
-\begin{classdesc*}{DTDHandler}
- Handle DTD events.
-
- This interface specifies only those DTD events required for basic
- parsing (unparsed entities and attributes).
-\end{classdesc*}
-
-\begin{classdesc*}{EntityResolver}
- Basic interface for resolving entities. If you create an object
- implementing this interface, then register the object with your
- Parser, the parser will call the method in your object to resolve all
- external entities.
-\end{classdesc*}
-
-\begin{classdesc*}{ErrorHandler}
- Interface used by the parser to present error and warning messages
- to the application. The methods of this object control whether errors
- are immediately converted to exceptions or are handled in some other
- way.
-\end{classdesc*}
-
-In addition to these classes, \module{xml.sax.handler} provides
-symbolic constants for the feature and property names.
-
-\begin{datadesc}{feature_namespaces}
- Value: \code{"http://xml.org/sax/features/namespaces"}\\
- true: Perform Namespace processing.\\
- false: Optionally do not perform Namespace processing
- (implies namespace-prefixes; default).\\
- access: (parsing) read-only; (not parsing) read/write
-\end{datadesc}
-
-\begin{datadesc}{feature_namespace_prefixes}
- Value: \code{"http://xml.org/sax/features/namespace-prefixes"}\\
- true: Report the original prefixed names and attributes used for Namespace
- declarations.\\
- false: Do not report attributes used for Namespace declarations, and
- optionally do not report original prefixed names (default).\\
- access: (parsing) read-only; (not parsing) read/write
-\end{datadesc}
-
-\begin{datadesc}{feature_string_interning}
- Value: \code{"http://xml.org/sax/features/string-interning"}\\
- true: All element names, prefixes, attribute names, Namespace URIs, and
- local names are interned using the built-in intern function.\\
- false: Names are not necessarily interned, although they may be (default).\\
- access: (parsing) read-only; (not parsing) read/write
-\end{datadesc}
-
-\begin{datadesc}{feature_validation}
- Value: \code{"http://xml.org/sax/features/validation"}\\
- true: Report all validation errors (implies external-general-entities and
- external-parameter-entities).\\
- false: Do not report validation errors.\\
- access: (parsing) read-only; (not parsing) read/write
-\end{datadesc}
-
-\begin{datadesc}{feature_external_ges}
- Value: \code{"http://xml.org/sax/features/external-general-entities"}\\
- true: Include all external general (text) entities.\\
- false: Do not include external general entities.\\
- access: (parsing) read-only; (not parsing) read/write
-\end{datadesc}
-
-\begin{datadesc}{feature_external_pes}
- Value: \code{"http://xml.org/sax/features/external-parameter-entities"}\\
- true: Include all external parameter entities, including the external
- DTD subset.\\
- false: Do not include any external parameter entities, even the external
- DTD subset.\\
- access: (parsing) read-only; (not parsing) read/write
-\end{datadesc}
-
-\begin{datadesc}{all_features}
- List of all features.
-\end{datadesc}
-
-\begin{datadesc}{property_lexical_handler}
- Value: \code{"http://xml.org/sax/properties/lexical-handler"}\\
- data type: xml.sax.sax2lib.LexicalHandler (not supported in Python 2)\\
- description: An optional extension handler for lexical events like comments.\\
- access: read/write
-\end{datadesc}
-
-\begin{datadesc}{property_declaration_handler}
- Value: \code{"http://xml.org/sax/properties/declaration-handler"}\\
- data type: xml.sax.sax2lib.DeclHandler (not supported in Python 2)\\
- description: An optional extension handler for DTD-related events other
- than notations and unparsed entities.\\
- access: read/write
-\end{datadesc}
-
-\begin{datadesc}{property_dom_node}
- Value: \code{"http://xml.org/sax/properties/dom-node"}\\
- data type: org.w3c.dom.Node (not supported in Python 2) \\
- description: When parsing, the current DOM node being visited if this is
- a DOM iterator; when not parsing, the root DOM node for
- iteration.\\
- access: (parsing) read-only; (not parsing) read/write
-\end{datadesc}
-
-\begin{datadesc}{property_xml_string}
- Value: \code{"http://xml.org/sax/properties/xml-string"}\\
- data type: String\\
- description: The literal string of characters that was the source for
- the current event.\\
- access: read-only
-\end{datadesc}
-
-\begin{datadesc}{all_properties}
- List of all known property names.
-\end{datadesc}
-
-
-\subsection{ContentHandler Objects \label{content-handler-objects}}
-
-Users are expected to subclass \class{ContentHandler} to support their
-application. The following methods are called by the parser on the
-appropriate events in the input document:
-
-\begin{methoddesc}[ContentHandler]{setDocumentLocator}{locator}
- Called by the parser to give the application a locator for locating
- the origin of document events.
-
- SAX parsers are strongly encouraged (though not absolutely required)
- to supply a locator: if it does so, it must supply the locator to
- the application by invoking this method before invoking any of the
- other methods in the DocumentHandler interface.
-
- The locator allows the application to determine the end position of
- any document-related event, even if the parser is not reporting an
- error. Typically, the application will use this information for
- reporting its own errors (such as character content that does not
- match an application's business rules). The information returned by
- the locator is probably not sufficient for use with a search engine.
-
- Note that the locator will return correct information only during
- the invocation of the events in this interface. The application
- should not attempt to use it at any other time.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{startDocument}{}
- Receive notification of the beginning of a document.
-
- The SAX parser will invoke this method only once, before any other
- methods in this interface or in DTDHandler (except for
- \method{setDocumentLocator()}).
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{endDocument}{}
- Receive notification of the end of a document.
-
- The SAX parser will invoke this method only once, and it will be the
- last method invoked during the parse. The parser shall not invoke
- this method until it has either abandoned parsing (because of an
- unrecoverable error) or reached the end of input.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{startPrefixMapping}{prefix, uri}
- Begin the scope of a prefix-URI Namespace mapping.
-
- The information from this event is not necessary for normal
- Namespace processing: the SAX XML reader will automatically replace
- prefixes for element and attribute names when the
- \code{feature_namespaces} feature is enabled (the default).
-
-%% XXX This is not really the default, is it? MvL
-
- There are cases, however, when applications need to use prefixes in
- character data or in attribute values, where they cannot safely be
- expanded automatically; the \method{startPrefixMapping()} and
- \method{endPrefixMapping()} events supply the information to the
- application to expand prefixes in those contexts itself, if
- necessary.
-
- Note that \method{startPrefixMapping()} and
- \method{endPrefixMapping()} events are not guaranteed to be properly
- nested relative to each-other: all \method{startPrefixMapping()}
- events will occur before the corresponding \method{startElement()}
- event, and all \method{endPrefixMapping()} events will occur after
- the corresponding \method{endElement()} event, but their order is
- not guaranteed.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{endPrefixMapping}{prefix}
- End the scope of a prefix-URI mapping.
-
- See \method{startPrefixMapping()} for details. This event will
- always occur after the corresponding \method{endElement()} event,
- but the order of \method{endPrefixMapping()} events is not otherwise
- guaranteed.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{startElement}{name, attrs}
- Signals the start of an element in non-namespace mode.
-
- The \var{name} parameter contains the raw XML 1.0 name of the
- element type as a string and the \var{attrs} parameter holds an
- object of the \ulink{\class{Attributes}
- interface}{attributes-objects.html} containing the attributes of the
- element. The object passed as \var{attrs} may be re-used by the
- parser; holding on to a reference to it is not a reliable way to
- keep a copy of the attributes. To keep a copy of the attributes,
- use the \method{copy()} method of the \var{attrs} object.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{endElement}{name}
- Signals the end of an element in non-namespace mode.
-
- The \var{name} parameter contains the name of the element type, just
- as with the \method{startElement()} event.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{startElementNS}{name, qname, attrs}
- Signals the start of an element in namespace mode.
-
- The \var{name} parameter contains the name of the element type as a
- \code{(\var{uri}, \var{localname})} tuple, the \var{qname} parameter
- contains the raw XML 1.0 name used in the source document, and the
- \var{attrs} parameter holds an instance of the
- \ulink{\class{AttributesNS} interface}{attributes-ns-objects.html}
- containing the attributes of the element. If no namespace is
- associated with the element, the \var{uri} component of \var{name}
- will be \code{None}. The object passed as \var{attrs} may be
- re-used by the parser; holding on to a reference to it is not a
- reliable way to keep a copy of the attributes. To keep a copy of
- the attributes, use the \method{copy()} method of the \var{attrs}
- object.
-
- Parsers may set the \var{qname} parameter to \code{None}, unless the
- \code{feature_namespace_prefixes} feature is activated.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{endElementNS}{name, qname}
- Signals the end of an element in namespace mode.
-
- The \var{name} parameter contains the name of the element type, just
- as with the \method{startElementNS()} method, likewise the
- \var{qname} parameter.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{characters}{content}
- Receive notification of character data.
-
- The Parser will call this method to report each chunk of character
- data. SAX parsers may return all contiguous character data in a
- single chunk, or they may split it into several chunks; however, all
- of the characters in any single event must come from the same
- external entity so that the Locator provides useful information.
-
- \var{content} may be a Unicode string or a byte string; the
- \code{expat} reader module produces always Unicode strings.
-
- \note{The earlier SAX 1 interface provided by the Python
- XML Special Interest Group used a more Java-like interface for this
- method. Since most parsers used from Python did not take advantage
- of the older interface, the simpler signature was chosen to replace
- it. To convert old code to the new interface, use \var{content}
- instead of slicing content with the old \var{offset} and
- \var{length} parameters.}
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{ignorableWhitespace}{whitespace}
- Receive notification of ignorable whitespace in element content.
-
- Validating Parsers must use this method to report each chunk
- of ignorable whitespace (see the W3C XML 1.0 recommendation,
- section 2.10): non-validating parsers may also use this method
- if they are capable of parsing and using content models.
-
- SAX parsers may return all contiguous whitespace in a single
- chunk, or they may split it into several chunks; however, all
- of the characters in any single event must come from the same
- external entity, so that the Locator provides useful
- information.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{processingInstruction}{target, data}
- Receive notification of a processing instruction.
-
- The Parser will invoke this method once for each processing
- instruction found: note that processing instructions may occur
- before or after the main document element.
-
- A SAX parser should never report an XML declaration (XML 1.0,
- section 2.8) or a text declaration (XML 1.0, section 4.3.1) using
- this method.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{skippedEntity}{name}
- Receive notification of a skipped entity.
-
- The Parser will invoke this method once for each entity
- skipped. Non-validating processors may skip entities if they have
- not seen the declarations (because, for example, the entity was
- declared in an external DTD subset). All processors may skip
- external entities, depending on the values of the
- \code{feature_external_ges} and the
- \code{feature_external_pes} properties.
-\end{methoddesc}
-
-
-\subsection{DTDHandler Objects \label{dtd-handler-objects}}
-
-\class{DTDHandler} instances provide the following methods:
-
-\begin{methoddesc}[DTDHandler]{notationDecl}{name, publicId, systemId}
- Handle a notation declaration event.
-\end{methoddesc}
-
-\begin{methoddesc}[DTDHandler]{unparsedEntityDecl}{name, publicId,
- systemId, ndata}
- Handle an unparsed entity declaration event.
-\end{methoddesc}
-
-
-\subsection{EntityResolver Objects \label{entity-resolver-objects}}
-
-\begin{methoddesc}[EntityResolver]{resolveEntity}{publicId, systemId}
- Resolve the system identifier of an entity and return either the
- system identifier to read from as a string, or an InputSource to
- read from. The default implementation returns \var{systemId}.
-\end{methoddesc}
-
-
-\subsection{ErrorHandler Objects \label{sax-error-handler}}
-
-Objects with this interface are used to receive error and warning
-information from the \class{XMLReader}. If you create an object that
-implements this interface, then register the object with your
-\class{XMLReader}, the parser will call the methods in your object to
-report all warnings and errors. There are three levels of errors
-available: warnings, (possibly) recoverable errors, and unrecoverable
-errors. All methods take a \exception{SAXParseException} as the only
-parameter. Errors and warnings may be converted to an exception by
-raising the passed-in exception object.
-
-\begin{methoddesc}[ErrorHandler]{error}{exception}
- Called when the parser encounters a recoverable error. If this method
- does not raise an exception, parsing may continue, but further document
- information should not be expected by the application. Allowing the
- parser to continue may allow additional errors to be discovered in the
- input document.
-\end{methoddesc}
-
-\begin{methoddesc}[ErrorHandler]{fatalError}{exception}
- Called when the parser encounters an error it cannot recover from;
- parsing is expected to terminate when this method returns.
-\end{methoddesc}
-
-\begin{methoddesc}[ErrorHandler]{warning}{exception}
- Called when the parser presents minor warning information to the
- application. Parsing is expected to continue when this method returns,
- and document information will continue to be passed to the application.
- Raising an exception in this method will cause parsing to end.
-\end{methoddesc}
diff --git a/Doc/lib/xmlsaxreader.tex b/Doc/lib/xmlsaxreader.tex
deleted file mode 100644
index d669581..0000000
--- a/Doc/lib/xmlsaxreader.tex
+++ /dev/null
@@ -1,351 +0,0 @@
-\section{\module{xml.sax.xmlreader} ---
- Interface for XML parsers}
-
-\declaremodule{standard}{xml.sax.xmlreader}
-\modulesynopsis{Interface which SAX-compliant XML parsers must implement.}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}
-
-\versionadded{2.0}
-
-
-SAX parsers implement the \class{XMLReader} interface. They are
-implemented in a Python module, which must provide a function
-\function{create_parser()}. This function is invoked by
-\function{xml.sax.make_parser()} with no arguments to create a new
-parser object.
-
-\begin{classdesc}{XMLReader}{}
- Base class which can be inherited by SAX parsers.
-\end{classdesc}
-
-\begin{classdesc}{IncrementalParser}{}
- In some cases, it is desirable not to parse an input source at once,
- but to feed chunks of the document as they get available. Note that
- the reader will normally not read the entire file, but read it in
- chunks as well; still \method{parse()} won't return until the entire
- document is processed. So these interfaces should be used if the
- blocking behaviour of \method{parse()} is not desirable.
-
- When the parser is instantiated it is ready to begin accepting data
- from the feed method immediately. After parsing has been finished
- with a call to close the reset method must be called to make the
- parser ready to accept new data, either from feed or using the parse
- method.
-
- Note that these methods must \emph{not} be called during parsing,
- that is, after parse has been called and before it returns.
-
- By default, the class also implements the parse method of the
- XMLReader interface using the feed, close and reset methods of the
- IncrementalParser interface as a convenience to SAX 2.0 driver
- writers.
-\end{classdesc}
-
-\begin{classdesc}{Locator}{}
- Interface for associating a SAX event with a document location. A
- locator object will return valid results only during calls to
- DocumentHandler methods; at any other time, the results are
- unpredictable. If information is not available, methods may return
- \code{None}.
-\end{classdesc}
-
-\begin{classdesc}{InputSource}{\optional{systemId}}
- Encapsulation of the information needed by the \class{XMLReader} to
- read entities.
-
- This class may include information about the public identifier,
- system identifier, byte stream (possibly with character encoding
- information) and/or the character stream of an entity.
-
- Applications will create objects of this class for use in the
- \method{XMLReader.parse()} method and for returning from
- EntityResolver.resolveEntity.
-
- An \class{InputSource} belongs to the application, the
- \class{XMLReader} is not allowed to modify \class{InputSource} objects
- passed to it from the application, although it may make copies and
- modify those.
-\end{classdesc}
-
-\begin{classdesc}{AttributesImpl}{attrs}
- This is an implementation of the \ulink{\class{Attributes}
- interface}{attributes-objects.html} (see
- section~\ref{attributes-objects}). This is a dictionary-like
- object which represents the element attributes in a
- \method{startElement()} call. In addition to the most useful
- dictionary operations, it supports a number of other methods as
- described by the interface. Objects of this class should be
- instantiated by readers; \var{attrs} must be a dictionary-like
- object containing a mapping from attribute names to attribute
- values.
-\end{classdesc}
-
-\begin{classdesc}{AttributesNSImpl}{attrs, qnames}
- Namespace-aware variant of \class{AttributesImpl}, which will be
- passed to \method{startElementNS()}. It is derived from
- \class{AttributesImpl}, but understands attribute names as
- two-tuples of \var{namespaceURI} and \var{localname}. In addition,
- it provides a number of methods expecting qualified names as they
- appear in the original document. This class implements the
- \ulink{\class{AttributesNS} interface}{attributes-ns-objects.html}
- (see section~\ref{attributes-ns-objects}).
-\end{classdesc}
-
-
-\subsection{XMLReader Objects \label{xmlreader-objects}}
-
-The \class{XMLReader} interface supports the following methods:
-
-\begin{methoddesc}[XMLReader]{parse}{source}
- Process an input source, producing SAX events. The \var{source}
- object can be a system identifier (a string identifying the
- input source -- typically a file name or an URL), a file-like
- object, or an \class{InputSource} object. When \method{parse()}
- returns, the input is completely processed, and the parser object
- can be discarded or reset. As a limitation, the current implementation
- only accepts byte streams; processing of character streams is for
- further study.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{getContentHandler}{}
- Return the current \class{ContentHandler}.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{setContentHandler}{handler}
- Set the current \class{ContentHandler}. If no
- \class{ContentHandler} is set, content events will be discarded.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{getDTDHandler}{}
- Return the current \class{DTDHandler}.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{setDTDHandler}{handler}
- Set the current \class{DTDHandler}. If no \class{DTDHandler} is
- set, DTD events will be discarded.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{getEntityResolver}{}
- Return the current \class{EntityResolver}.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{setEntityResolver}{handler}
- Set the current \class{EntityResolver}. If no
- \class{EntityResolver} is set, attempts to resolve an external
- entity will result in opening the system identifier for the entity,
- and fail if it is not available.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{getErrorHandler}{}
- Return the current \class{ErrorHandler}.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{setErrorHandler}{handler}
- Set the current error handler. If no \class{ErrorHandler} is set,
- errors will be raised as exceptions, and warnings will be printed.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{setLocale}{locale}
- Allow an application to set the locale for errors and warnings.
-
- SAX parsers are not required to provide localization for errors and
- warnings; if they cannot support the requested locale, however, they
- must throw a SAX exception. Applications may request a locale change
- in the middle of a parse.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{getFeature}{featurename}
- Return the current setting for feature \var{featurename}. If the
- feature is not recognized, \exception{SAXNotRecognizedException} is
- raised. The well-known featurenames are listed in the module
- \module{xml.sax.handler}.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{setFeature}{featurename, value}
- Set the \var{featurename} to \var{value}. If the feature is not
- recognized, \exception{SAXNotRecognizedException} is raised. If the
- feature or its setting is not supported by the parser,
- \var{SAXNotSupportedException} is raised.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{getProperty}{propertyname}
- Return the current setting for property \var{propertyname}. If the
- property is not recognized, a \exception{SAXNotRecognizedException}
- is raised. The well-known propertynames are listed in the module
- \module{xml.sax.handler}.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{setProperty}{propertyname, value}
- Set the \var{propertyname} to \var{value}. If the property is not
- recognized, \exception{SAXNotRecognizedException} is raised. If the
- property or its setting is not supported by the parser,
- \var{SAXNotSupportedException} is raised.
-\end{methoddesc}
-
-
-\subsection{IncrementalParser Objects
- \label{incremental-parser-objects}}
-
-Instances of \class{IncrementalParser} offer the following additional
-methods:
-
-\begin{methoddesc}[IncrementalParser]{feed}{data}
- Process a chunk of \var{data}.
-\end{methoddesc}
-
-\begin{methoddesc}[IncrementalParser]{close}{}
- Assume the end of the document. That will check well-formedness
- conditions that can be checked only at the end, invoke handlers, and
- may clean up resources allocated during parsing.
-\end{methoddesc}
-
-\begin{methoddesc}[IncrementalParser]{reset}{}
- This method is called after close has been called to reset the
- parser so that it is ready to parse new documents. The results of
- calling parse or feed after close without calling reset are
- undefined.
-\end{methoddesc}
-
-
-\subsection{Locator Objects \label{locator-objects}}
-
-Instances of \class{Locator} provide these methods:
-
-\begin{methoddesc}[Locator]{getColumnNumber}{}
- Return the column number where the current event ends.
-\end{methoddesc}
-
-\begin{methoddesc}[Locator]{getLineNumber}{}
- Return the line number where the current event ends.
-\end{methoddesc}
-
-\begin{methoddesc}[Locator]{getPublicId}{}
- Return the public identifier for the current event.
-\end{methoddesc}
-
-\begin{methoddesc}[Locator]{getSystemId}{}
- Return the system identifier for the current event.
-\end{methoddesc}
-
-
-\subsection{InputSource Objects \label{input-source-objects}}
-
-\begin{methoddesc}[InputSource]{setPublicId}{id}
- Sets the public identifier of this \class{InputSource}.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{getPublicId}{}
- Returns the public identifier of this \class{InputSource}.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{setSystemId}{id}
- Sets the system identifier of this \class{InputSource}.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{getSystemId}{}
- Returns the system identifier of this \class{InputSource}.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{setEncoding}{encoding}
- Sets the character encoding of this \class{InputSource}.
-
- The encoding must be a string acceptable for an XML encoding
- declaration (see section 4.3.3 of the XML recommendation).
-
- The encoding attribute of the \class{InputSource} is ignored if the
- \class{InputSource} also contains a character stream.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{getEncoding}{}
- Get the character encoding of this InputSource.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{setByteStream}{bytefile}
- Set the byte stream (a Python file-like object which does not
- perform byte-to-character conversion) for this input source.
-
- The SAX parser will ignore this if there is also a character stream
- specified, but it will use a byte stream in preference to opening a
- URI connection itself.
-
- If the application knows the character encoding of the byte stream,
- it should set it with the setEncoding method.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{getByteStream}{}
- Get the byte stream for this input source.
-
- The getEncoding method will return the character encoding for this
- byte stream, or None if unknown.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{setCharacterStream}{charfile}
- Set the character stream for this input source. (The stream must be
- a Python 1.6 Unicode-wrapped file-like that performs conversion to
- Unicode strings.)
-
- If there is a character stream specified, the SAX parser will ignore
- any byte stream and will not attempt to open a URI connection to the
- system identifier.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{getCharacterStream}{}
- Get the character stream for this input source.
-\end{methoddesc}
-
-
-\subsection{The \class{Attributes} Interface \label{attributes-objects}}
-
-\class{Attributes} objects implement a portion of the mapping
-protocol, including the methods \method{copy()}, \method{get()},
-\method{has_key()}, \method{items()}, \method{keys()}, and
-\method{values()}. The following methods are also provided:
-
-\begin{methoddesc}[Attributes]{getLength}{}
- Return the number of attributes.
-\end{methoddesc}
-
-\begin{methoddesc}[Attributes]{getNames}{}
- Return the names of the attributes.
-\end{methoddesc}
-
-\begin{methoddesc}[Attributes]{getType}{name}
- Returns the type of the attribute \var{name}, which is normally
- \code{'CDATA'}.
-\end{methoddesc}
-
-\begin{methoddesc}[Attributes]{getValue}{name}
- Return the value of attribute \var{name}.
-\end{methoddesc}
-
-% getValueByQName, getNameByQName, getQNameByName, getQNames available
-% here already, but documented only for derived class.
-
-
-\subsection{The \class{AttributesNS} Interface \label{attributes-ns-objects}}
-
-This interface is a subtype of the \ulink{\class{Attributes}
-interface}{attributes-objects.html} (see
-section~\ref{attributes-objects}). All methods supported by that
-interface are also available on \class{AttributesNS} objects.
-
-The following methods are also available:
-
-\begin{methoddesc}[AttributesNS]{getValueByQName}{name}
- Return the value for a qualified name.
-\end{methoddesc}
-
-\begin{methoddesc}[AttributesNS]{getNameByQName}{name}
- Return the \code{(\var{namespace}, \var{localname})} pair for a
- qualified \var{name}.
-\end{methoddesc}
-
-\begin{methoddesc}[AttributesNS]{getQNameByName}{name}
- Return the qualified name for a \code{(\var{namespace},
- \var{localname})} pair.
-\end{methoddesc}
-
-\begin{methoddesc}[AttributesNS]{getQNames}{}
- Return the qualified names of all attributes.
-\end{methoddesc}
diff --git a/Doc/lib/xmlsaxutils.tex b/Doc/lib/xmlsaxutils.tex
deleted file mode 100644
index 64221f5..0000000
--- a/Doc/lib/xmlsaxutils.tex
+++ /dev/null
@@ -1,81 +0,0 @@
-\section{\module{xml.sax.saxutils} ---
- SAX Utilities}
-
-\declaremodule{standard}{xml.sax.saxutils}
-\modulesynopsis{Convenience functions and classes for use with SAX.}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}
-
-\versionadded{2.0}
-
-
-The module \module{xml.sax.saxutils} contains a number of classes and
-functions that are commonly useful when creating SAX applications,
-either in direct use, or as base classes.
-
-\begin{funcdesc}{escape}{data\optional{, entities}}
- Escape \character{\&}, \character{<}, and \character{>} in a string
- of data.
-
- You can escape other strings of data by passing a dictionary as the
- optional \var{entities} parameter. The keys and values must all be
- strings; each key will be replaced with its corresponding value.
-\end{funcdesc}
-
-\begin{funcdesc}{unescape}{data\optional{, entities}}
- Unescape \character{\&}, \character{\<}, and \character{\>}
- in a string of data.
-
- You can unescape other strings of data by passing a dictionary as the
- optional \var{entities} parameter. The keys and values must all be
- strings; each key will be replaced with its corresponding value.
-
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{quoteattr}{data\optional{, entities}}
- Similar to \function{escape()}, but also prepares \var{data} to be
- used as an attribute value. The return value is a quoted version of
- \var{data} with any additional required replacements.
- \function{quoteattr()} will select a quote character based on the
- content of \var{data}, attempting to avoid encoding any quote
- characters in the string. If both single- and double-quote
- characters are already in \var{data}, the double-quote characters
- will be encoded and \var{data} will be wrapped in double-quotes. The
- resulting string can be used directly as an attribute value:
-
-\begin{verbatim}
->>> print "<element attr=%s>" % quoteattr("ab ' cd \" ef")
-<element attr="ab ' cd " ef">
-\end{verbatim}
-
- This function is useful when generating attribute values for HTML or
- any SGML using the reference concrete syntax.
- \versionadded{2.2}
-\end{funcdesc}
-
-\begin{classdesc}{XMLGenerator}{\optional{out\optional{, encoding}}}
- This class implements the \class{ContentHandler} interface by
- writing SAX events back into an XML document. In other words, using
- an \class{XMLGenerator} as the content handler will reproduce the
- original document being parsed. \var{out} should be a file-like
- object which will default to \var{sys.stdout}. \var{encoding} is the
- encoding of the output stream which defaults to \code{'iso-8859-1'}.
-\end{classdesc}
-
-\begin{classdesc}{XMLFilterBase}{base}
- This class is designed to sit between an \class{XMLReader} and the
- client application's event handlers. By default, it does nothing
- but pass requests up to the reader and events on to the handlers
- unmodified, but subclasses can override specific methods to modify
- the event stream or the configuration requests as they pass through.
-\end{classdesc}
-
-\begin{funcdesc}{prepare_input_source}{source\optional{, base}}
- This function takes an input source and an optional base URL and
- returns a fully resolved \class{InputSource} object ready for
- reading. The input source can be given as a string, a file-like
- object, or an \class{InputSource} object; parsers will use this
- function to implement the polymorphic \var{source} argument to their
- \method{parse()} method.
-\end{funcdesc}
diff --git a/Doc/mac/libaepack.tex b/Doc/mac/libaepack.tex
deleted file mode 100644
index 26a672e..0000000
--- a/Doc/mac/libaepack.tex
+++ /dev/null
@@ -1,82 +0,0 @@
-\section{\module{aepack} ---
- Conversion between Python variables and AppleEvent data containers}
-
-\declaremodule{standard}{aepack}
- \platform{Mac}
-%\moduleauthor{Jack Jansen?}{email}
-\modulesynopsis{Conversion between Python variables and AppleEvent
- data containers.}
-\sectionauthor{Vincent Marchetti}{vincem@en.com}
-
-
-The \module{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 \refmodule{Carbon.AE}.
-
-The \module{aepack} module defines the following functions:
-
-
-\begin{funcdesc}{pack}{x\optional{, forcetype}}
-Returns an \class{AEDesc} object containing a conversion of Python
-value x. If \var{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:
-
-\begin{tableii}{l|l}{textrm}{Python type}{descriptor type}
- \lineii{\class{FSSpec}}{typeFSS}
- \lineii{\class{FSRef}}{typeFSRef}
- \lineii{\class{Alias}}{typeAlias}
- \lineii{integer}{typeLong (32 bit integer)}
- \lineii{float}{typeFloat (64 bit floating point)}
- \lineii{string}{typeText}
- \lineii{unicode}{typeUnicodeText}
- \lineii{list}{typeAEList}
- \lineii{dictionary}{typeAERecord}
- \lineii{instance}{\emph{see below}}
-\end{tableii}
-
-If \var{x} is a Python instance then this function attempts to call an
-\method{__aepack__()} method. This method should return an
-\class{AEDesc} object.
-
-If the conversion \var{x} is not defined above, this function returns
-the Python string representation of a value (the repr() function)
-encoded as a text descriptor.
-\end{funcdesc}
-
-\begin{funcdesc}{unpack}{x\optional{, formodulename}}
- \var{x} must be an object of type \class{AEDesc}. This function
- returns a Python object representation of the data in the Apple
- Event descriptor \var{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. \code{line 3 of document 1}) are returned as instances of
- \class{aetypes.ObjectSpecifier}, unless \code{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 \code{formodulename} argument is used by the stub packages
- generated by \module{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 \code{Finder.Window} and not a generic
- \code{aetypes.Window}. The former knows about all the properties
- and elements a window has in the Finder, while the latter knows
- no such things.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{Carbon.AE}{Built-in access to Apple Event Manager routines.}
- \seemodule{aetypes}{Python definitions of codes for Apple Event
- descriptor types.}
- \seetitle[http://developer.apple.com/techpubs/mac/IAC/IAC-2.html]{
- Inside Macintosh: Interapplication
- Communication}{Information about inter-process
- communications on the Macintosh.}
-\end{seealso}
diff --git a/Doc/mac/libaetools.tex b/Doc/mac/libaetools.tex
deleted file mode 100644
index 463755b..0000000
--- a/Doc/mac/libaetools.tex
+++ /dev/null
@@ -1,83 +0,0 @@
-\section{\module{aetools} ---
- OSA client support}
-
-\declaremodule{standard}{aetools}
- \platform{Mac}
-%\moduleauthor{Jack Jansen?}{email}
-\modulesynopsis{Basic support for sending Apple Events}
-\sectionauthor{Jack Jansen}{Jack.Jansen@cwi.nl}
-
-
-The \module{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
-\module{aetypes} and \module{aepack} modules. The stub packages
-generated by \module{gensuitemodule} import the relevant
-portions of \module{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 \module{aetools} module itself uses the AppleEvent support
-provided by the \module{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 \module{aetools} module defines the following functions:
-
-\begin{funcdesc}{packevent}{ae, parameters, attributes}
-Stores parameters and attributes in a pre-created \code{Carbon.AE.AEDesc}
-object. \code{parameters} and \code{attributes} are
-dictionaries mapping 4-character OSA parameter keys to Python objects. The
-objects are packed using \code{aepack.pack()}.
-\end{funcdesc}
-
-\begin{funcdesc}{unpackevent}{ae\optional{, formodulename}}
-Recursively unpacks a \code{Carbon.AE.AEDesc} event to Python objects.
-The function returns the parameter dictionary and the attribute dictionary.
-The \code{formodulename} argument is used by generated stub packages to
-control where AppleScript classes are looked up.
-\end{funcdesc}
-
-\begin{funcdesc}{keysubst}{arguments, keydict}
-Converts a Python keyword argument dictionary \code{arguments} to
-the format required by \code{packevent} by replacing the keys,
-which are Python identifiers, by the four-character OSA keys according
-to the mapping specified in \code{keydict}. Used by the generated suite
-packages.
-\end{funcdesc}
-
-\begin{funcdesc}{enumsubst}{arguments, key, edict}
-If the \code{arguments} dictionary contains an entry for \code{key}
-convert the value for that entry according to dictionary \code{edict}.
-This converts human-readable Python enumeration names to the OSA 4-character
-codes.
-Used by the generated suite
-packages.
-\end{funcdesc}
-
-The \module{aetools} module defines the following class:
-
-\begin{classdesc}{TalkTo}{\optional{signature=None, start=0, timeout=0}}
-
-Base class for the proxy used to talk to an application. \code{signature}
-overrides the class attribute \code{_signature} (which is usually set by subclasses)
-and is the 4-char creator code defining the application to talk to.
-\code{start} can be set to true to enable running the application on
-class instantiation. \code{timeout} can be specified to change the
-default timeout used while waiting for an AppleEvent reply.
-\end{classdesc}
-
-\begin{methoddesc}{_start}{}
-Test whether the application is running, and attempt to start it if not.
-\end{methoddesc}
-
-\begin{methoddesc}{send}{code, subcode\optional{, parameters, attributes}}
-Create the AppleEvent \code{Carbon.AE.AEDesc} for the verb with
-the OSA designation \code{code, subcode} (which are the usual 4-character
-strings), pack the \code{parameters} and \code{attributes} into it, send it
-to the target application, wait for the reply, unpack the reply with
-\code{unpackevent} and return the reply appleevent, the unpacked return values
-as a dictionary and the return attributes.
-\end{methoddesc}
diff --git a/Doc/mac/libaetypes.tex b/Doc/mac/libaetypes.tex
deleted file mode 100644
index f7d8f8b..0000000
--- a/Doc/mac/libaetypes.tex
+++ /dev/null
@@ -1,135 +0,0 @@
-\section{\module{aetypes} ---
- AppleEvent objects}
-
-\declaremodule{standard}{aetypes}
- \platform{Mac}
-%\moduleauthor{Jack Jansen?}{email}
-\modulesynopsis{Python representation of the Apple Event Object Model.}
-\sectionauthor{Vincent Marchetti}{vincem@en.com}
-
-
-The \module{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: \code{typeText} in OSA is a Python string,
-\code{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 \module{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 \module{aetypes} module contains the base classes for OSA classes
-and properties, which are used by the packages generated by
-\module{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 \code{Document}, \code{Window}, \code{Character}, etc.
-
-
-
-The \module{AEObjects} module defines the following classes to represent
-Apple Event descriptor data:
-
-\begin{classdesc}{Unknown}{type, data}
-The representation of OSA descriptor data for which the \module{aepack}
-and \module{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.
-\end{classdesc}
-
-\begin{classdesc}{Enum}{enum}
-An enumeration value with the given 4-character string value.
-\end{classdesc}
-
-\begin{classdesc}{InsertionLoc}{of, pos}
-Position \code{pos} in object \code{of}.
-\end{classdesc}
-
-\begin{classdesc}{Boolean}{bool}
-A boolean.
-\end{classdesc}
-
-\begin{classdesc}{StyledText}{style, text}
-Text with style information (font, face, etc) included.
-\end{classdesc}
-
-\begin{classdesc}{AEText}{script, style, text}
-Text with script system and style information included.
-\end{classdesc}
-
-\begin{classdesc}{IntlText}{script, language, text}
-Text with script system and language information included.
-\end{classdesc}
-
-\begin{classdesc}{IntlWritingCode}{script, language}
-Script system and language information.
-\end{classdesc}
-
-\begin{classdesc}{QDPoint}{v, h}
-A quickdraw point.
-\end{classdesc}
-
-\begin{classdesc}{QDRectangle}{v0, h0, v1, h1}
-A quickdraw rectangle.
-\end{classdesc}
-
-\begin{classdesc}{RGBColor}{r, g, b}
-A color.
-\end{classdesc}
-
-\begin{classdesc}{Type}{type}
-An OSA type value with the given 4-character name.
-\end{classdesc}
-
-\begin{classdesc}{Keyword}{name}
-An OSA keyword with the given 4-character name.
-\end{classdesc}
-
-\begin{classdesc}{Range}{start, stop}
-A range.
-\end{classdesc}
-
-\begin{classdesc}{Ordinal}{abso}
-Non-numeric absolute positions, such as \code{"firs"}, first, or \code{"midd"},
-middle.
-\end{classdesc}
-
-\begin{classdesc}{Logical}{logc, term}
-The logical expression of applying operator \code{logc} to
-\code{term}.
-\end{classdesc}
-
-\begin{classdesc}{Comparison}{obj1, relo, obj2}
-The comparison \code{relo} of \code{obj1} to \code{obj2}.
-\end{classdesc}
-
-The following classes are used as base classes by the generated stub
-packages to represent AppleScript classes and properties in Python:
-
-\begin{classdesc}{ComponentItem}{which\optional{, fr}}
-Abstract baseclass for an OSA class. The subclass should set the class
-attribute \code{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
-\code{which}, and optionally a parent object in \code{fr}.
-\end{classdesc}
-
-\begin{classdesc}{NProperty}{fr}
-Abstract baseclass for an OSA property. The subclass should set the class
-attributes \code{want} and \code{which} to designate which property we
-are talking about. Instances of subclasses of this class are Object
-Specifiers.
-\end{classdesc}
-
-\begin{classdesc}{ObjectSpecifier}{want, form, seld\optional{, fr}}
-Base class of \code{ComponentItem} and \code{NProperty}, a general
-OSA Object Specifier. See the Apple Open Scripting Architecture
-documentation for the parameters. Note that this class is not abstract.
-\end{classdesc}
-
diff --git a/Doc/mac/libautogil.tex b/Doc/mac/libautogil.tex
deleted file mode 100644
index 002e872..0000000
--- a/Doc/mac/libautogil.tex
+++ /dev/null
@@ -1,26 +0,0 @@
-\section{\module{autoGIL} ---
- Global Interpreter Lock handling in event loops}
-
-\declaremodule{extension}{autoGIL}
- \platform{Mac}
-\modulesynopsis{Global Interpreter Lock handling in event loops.}
-\moduleauthor{Just van Rossum}{just@letterror.com}
-
-
-The \module{autoGIL} module provides a function \function{installAutoGIL} that
-automatically locks and unlocks Python's Global Interpreter Lock
-when running an event loop.
-
-\begin{excdesc}{AutoGILError}
-Raised if the observer callback cannot be installed, for example because
-the current thread does not have a run loop.
-\end{excdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
diff --git a/Doc/mac/libcolorpicker.tex b/Doc/mac/libcolorpicker.tex
deleted file mode 100644
index 596e9c2..0000000
--- a/Doc/mac/libcolorpicker.tex
+++ /dev/null
@@ -1,23 +0,0 @@
-\section{\module{ColorPicker} ---
- Color selection dialog}
-
-\declaremodule{extension}{ColorPicker}
- \platform{Mac}
-\modulesynopsis{Interface to the standard color selection dialog.}
-\moduleauthor{Just van Rossum}{just@letterror.com}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-The \module{ColorPicker} module provides access to the standard color
-picker dialog.
-
-
-\begin{funcdesc}{GetColor}{prompt, rgb}
- Show a standard color selection dialog and allow the user to select
- a color. The user is given instruction by the \var{prompt} string,
- and the default color is set to \var{rgb}. \var{rgb} must be a
- tuple giving the red, green, and blue components of the color.
- \function{GetColor()} returns a tuple giving the user's selected
- color and a flag indicating whether they accepted the selection of
- cancelled.
-\end{funcdesc}
diff --git a/Doc/mac/libframework.tex b/Doc/mac/libframework.tex
deleted file mode 100644
index edc76c1..0000000
--- a/Doc/mac/libframework.tex
+++ /dev/null
@@ -1,312 +0,0 @@
-\section{\module{FrameWork} ---
- Interactive application framework}
-
-\declaremodule{standard}{FrameWork}
- \platform{Mac}
-\modulesynopsis{Interactive application framework.}
-
-
-The \module{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 \module{FrameWork} has pretty much stopped, now that
-\module{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
-\module{FrameWork}:
-
-\begin{quotation}
-The strong point of \module{FrameWork} is that it allows you to break
-into the control-flow at many different places. \refmodule{W}, for
-instance, uses a different way to enable/disable menus and that plugs
-right in leaving the rest intact. The weak points of
-\module{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.
-\end{quotation}
-
-
-The \module{FrameWork} module defines the following functions:
-
-
-\begin{funcdesc}{Application}{}
-An object representing the complete application. See below for a
-description of the methods. The default \method{__init__()} routine
-creates an empty window dictionary and a menu bar with an apple menu.
-\end{funcdesc}
-
-\begin{funcdesc}{MenuBar}{}
-An object representing the menubar. This object is usually not created
-by the user.
-\end{funcdesc}
-
-\begin{funcdesc}{Menu}{bar, title\optional{, after}}
-An object representing a menu. Upon creation you pass the
-\code{MenuBar} the menu appears in, the \var{title} string and a
-position (1-based) \var{after} where the menu should appear (default:
-at the end).
-\end{funcdesc}
-
-\begin{funcdesc}{MenuItem}{menu, title\optional{, 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 \code{'domenu_'} prepended.
-
-Calling the \code{MenuBar} \method{fixmenudimstate()} method sets the
-correct dimming for all menu items based on the current front window.
-\end{funcdesc}
-
-\begin{funcdesc}{Separator}{menu}
-Add a separator to the end of a menu.
-\end{funcdesc}
-
-\begin{funcdesc}{SubMenu}{menu, label}
-Create a submenu named \var{label} under menu \var{menu}. The menu
-object is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{Window}{parent}
-Creates a (modeless) window. \var{Parent} is the application object to
-which the window belongs. The window is not displayed until later.
-\end{funcdesc}
-
-\begin{funcdesc}{DialogWindow}{parent}
-Creates a modeless dialog window.
-\end{funcdesc}
-
-\begin{funcdesc}{windowbounds}{width, height}
-Return a \code{(\var{left}, \var{top}, \var{right}, \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{setwatchcursor}{}
-Set the mouse cursor to a watch.
-\end{funcdesc}
-
-\begin{funcdesc}{setarrowcursor}{}
-Set the mouse cursor to an arrow.
-\end{funcdesc}
-
-
-\subsection{Application Objects \label{application-objects}}
-
-Application objects have the following methods, among others:
-
-
-\begin{methoddesc}[Application]{makeusermenus}{}
-Override this method if you need menus in your application. Append the
-menus to the attribute \member{menubar}.
-\end{methoddesc}
-
-\begin{methoddesc}[Application]{getabouttext}{}
-Override this method to return a text string describing your
-application. Alternatively, override the \method{do_about()} method
-for more elaborate ``about'' messages.
-\end{methoddesc}
-
-\begin{methoddesc}[Application]{mainloop}{\optional{mask\optional{, wait}}}
-This routine is the main event loop, call it to set your application
-rolling. \var{Mask} is the mask of events you want to handle,
-\var{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 \var{self} to exit the mainloop is still
-supported it is not recommended: call \code{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 \code{1} if the event is fully
-handled and \code{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 \function{MacOS.HandleEvent()} is not allowed within
-\var{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.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \var{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 \var{async_dispatch} will immediately
-call \var{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.
-\end{methoddesc}
-
-\begin{methoddesc}[Application]{_quit}{}
-Terminate the running \method{mainloop()} call at the next convenient
-moment.
-\end{methoddesc}
-
-\begin{methoddesc}[Application]{do_char}{c, event}
-The user typed character \var{c}. The complete details of the event
-can be found in the \var{event} structure. This method can also be
-provided in a \code{Window} object, which overrides the
-application-wide handler if the window is frontmost.
-\end{methoddesc}
-
-\begin{methoddesc}[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 \code{DialogWindow} object involved). Override if you
-need special handling of dialog events (keyboard shortcuts, etc).
-\end{methoddesc}
-
-\begin{methoddesc}[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).
-\end{methoddesc}
-
-
-\subsection{Window Objects \label{window-objects}}
-
-Window objects have the following methods, among others:
-
-\begin{methoddesc}[Window]{open}{}
-Override this method to open a window. Store the MacOS window-id in
-\member{self.wid} and call the \method{do_postopen()} method to
-register the window with the parent application.
-\end{methoddesc}
-
-\begin{methoddesc}[Window]{close}{}
-Override this method to do any special processing on window
-close. Call the \method{do_postclose()} method to cleanup the parent
-state.
-\end{methoddesc}
-
-\begin{methoddesc}[Window]{do_postresize}{width, height, macoswindowid}
-Called after the window is resized. Override if more needs to be done
-than calling \code{InvalRect}.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{methoddesc}[Window]{do_update}{macoswindowid, event}
-An update event for the window was received. Redraw the window.
-\end{methoddesc}
-
-\begin{methoddesc}[Window]{do_activate}{activate, event}
-The window was activated (\code{\var{activate} == 1}) or deactivated
-(\code{\var{activate} == 0}). Handle things like focus highlighting,
-etc.
-\end{methoddesc}
-
-
-\subsection{ControlsWindow Object \label{controlswindow-object}}
-
-ControlsWindow objects have the following methods besides those of
-\code{Window} objects:
-
-
-\begin{methoddesc}[ControlsWindow]{do_controlhit}{window, control,
- pcode, event}
-Part \var{pcode} of control \var{control} was hit by the
-user. Tracking and such has already been taken care of.
-\end{methoddesc}
-
-
-\subsection{ScrolledWindow Object \label{scrolledwindow-object}}
-
-ScrolledWindow objects are ControlsWindow objects with the following
-extra methods:
-
-
-\begin{methoddesc}[ScrolledWindow]{scrollbars}{\optional{wantx\optional{,
- wanty}}}
-Create (or destroy) horizontal and vertical scrollbars. The arguments
-specify which you want (default: both). The scrollbars always have
-minimum \code{0} and maximum \code{32767}.
-\end{methoddesc}
-
-\begin{methoddesc}[ScrolledWindow]{getscrollbarvalues}{}
-You must supply this method. It should return a tuple \code{(\var{x},
-\var{y})} giving the current position of the scrollbars (between
-\code{0} and \code{32767}). You can return \code{None} for either to
-indicate the whole document is visible in that direction.
-\end{methoddesc}
-
-\begin{methoddesc}[ScrolledWindow]{updatescrollbars}{}
-Call this method when the document has changed. It will call
-\method{getscrollbarvalues()} and update the scrollbars.
-\end{methoddesc}
-
-\begin{methoddesc}[ScrolledWindow]{scrollbar_callback}{which, what, value}
-Supplied by you and called after user interaction. \var{which} will
-be \code{'x'} or \code{'y'}, \var{what} will be \code{'-'},
-\code{'--'}, \code{'set'}, \code{'++'} or \code{'+'}. For
-\code{'set'}, \var{value} will contain the new scrollbar position.
-\end{methoddesc}
-
-\begin{methoddesc}[ScrolledWindow]{scalebarvalues}{absmin, absmax,
- curmin, curmax}
-Auxiliary method to help you calculate values to return from
-\method{getscrollbarvalues()}. You pass document minimum and maximum value
-and topmost (leftmost) and bottommost (rightmost) visible values and
-it returns the correct number or \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-\begin{methoddesc}[ScrolledWindow]{do_postresize}{width, height, window}
-Moves scrollbars to the correct position. Call this method initially
-if you override it.
-\end{methoddesc}
-
-\begin{methoddesc}[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.
-\end{methoddesc}
-
-
-\subsection{DialogWindow Objects \label{dialogwindow-objects}}
-
-DialogWindow objects have the following methods besides those of
-\code{Window} objects:
-
-
-\begin{methoddesc}[DialogWindow]{open}{resid}
-Create the dialog window, from the DLOG resource with id
-\var{resid}. The dialog object is stored in \member{self.wid}.
-\end{methoddesc}
-
-\begin{methoddesc}[DialogWindow]{do_itemhit}{item, event}
-Item number \var{item} was hit. You are responsible for redrawing
-toggle buttons, etc.
-\end{methoddesc}
diff --git a/Doc/mac/libgensuitemodule.tex b/Doc/mac/libgensuitemodule.tex
deleted file mode 100644
index 57ab587..0000000
--- a/Doc/mac/libgensuitemodule.tex
+++ /dev/null
@@ -1,64 +0,0 @@
-\section{\module{gensuitemodule} ---
- Generate OSA stub packages}
-
-\declaremodule{standard}{gensuitemodule}
- \platform{Mac}
-%\moduleauthor{Jack Jansen?}{email}
-\modulesynopsis{Create a stub package from an OSA dictionary}
-\sectionauthor{Jack Jansen}{Jack.Jansen@cwi.nl}
-
-The \module{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
-\longprogramopt{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:
-
-\begin{funcdesc}{is_scriptable}{application}
-Returns true if \code{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.
-\end{funcdesc}
-
-\begin{funcdesc}{processfile}{application\optional{, output, basepkgname,
- edit_modnames, creatorsignature, dump, verbose}}
-Create a stub package for \code{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.
-
-\code{output} is the pathname where the resulting package is stored, if
-not specified a standard "save file as" dialog is presented to
-the user. \code{basepkgname} is the base package on which this package
-will build, and defaults to \module{StdSuites}. Only when generating
-\module{StdSuites} itself do you need to specify this.
-\code{edit_modnames} is a dictionary that can be used to change
-modulenames that are too ugly after name mangling.
-\code{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 \code{dump} is
-given it should refer to a file object, and \code{processfile} will stop
-after decoding the resources and dump the Python representation of the
-terminology resources to this file. \code{verbose} should also be a file
-object, and specifying it will cause \code{processfile} to tell you what
-it is doing.
-\end{funcdesc}
-
-\begin{funcdesc}{processfile_fromresource}{application\optional{, output,
- basepkgname, edit_modnames, creatorsignature, dump, verbose}}
-This function does the same as \code{processfile}, except that it uses a
-different method to get the terminology resources. It opens \code{application}
-as a resource file and reads all \code{"aete"} and \code{"aeut"} resources
-from this file.
-\end{funcdesc}
-
diff --git a/Doc/mac/libmac.tex b/Doc/mac/libmac.tex
deleted file mode 100644
index 9dece8d..0000000
--- a/Doc/mac/libmac.tex
+++ /dev/null
@@ -1,29 +0,0 @@
-
-\section{\module{macpath} ---
- MacOS path manipulation functions}
-
-\declaremodule{standard}{macpath}
-% Could be labeled \platform{Mac}, but the module should work anywhere and
-% is distributed with the standard library.
-\modulesynopsis{MacOS path manipulation functions.}
-
-
-This module is the Mac OS 9 (and earlier) implementation of the \module{os.path}
-module. It can be used to manipulate old-style Macintosh pathnames on Mac OS
-X (or any other platform).
-Refer to the
-\citetitle[../lib/lib.html]{Python Library Reference} for
-documentation of \module{os.path}.
-
-The following functions are available in this module:
-\function{normcase()},
-\function{normpath()},
-\function{isabs()},
-\function{join()},
-\function{split()},
-\function{isdir()},
-\function{isfile()},
-\function{walk()},
-\function{exists()}.
-For other functions available in \module{os.path} dummy counterparts
-are available.
diff --git a/Doc/mac/libmacic.tex b/Doc/mac/libmacic.tex
deleted file mode 100644
index f8006f3..0000000
--- a/Doc/mac/libmacic.tex
+++ /dev/null
@@ -1,123 +0,0 @@
-\section{\module{ic} ---
- Access to Internet Config}
-
-\declaremodule{builtin}{ic}
- \platform{Mac}
-\modulesynopsis{Access to Internet Config.}
-
-
-This module provides access to various internet-related preferences
-set through \program{System Preferences} or the \program{Finder}.
-
-There is a low-level companion module
-\module{icglue}\refbimodindex{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 \module{ic} module defines the \exception{error} exception and
-symbolic names for all error codes Internet Config can produce; see
-the source for details.
-
-\begin{excdesc}{error}
-Exception raised on errors in the \module{ic} module.
-\end{excdesc}
-
-
-The \module{ic} module defines the following class and function:
-
-\begin{classdesc}{IC}{\optional{signature\optional{, ic}}}
-Create an Internet Config object. The signature is a 4-character creator
-code of the current application (default \code{'Pyth'}) which may
-influence some of ICs settings. The optional \var{ic} argument is a
-low-level \code{icglue.icinstance} created beforehand, this may be
-useful if you want to get preferences from a different config file,
-etc.
-\end{classdesc}
-
-\begin{funcdesc}{launchurl}{url\optional{, hint}}
-\funcline{parseurl}{data\optional{, start\optional{, end\optional{, hint}}}}
-\funcline{mapfile}{file}
-\funcline{maptypecreator}{type, creator\optional{, filename}}
-\funcline{settypecreator}{file}
-These functions are ``shortcuts'' to the methods of the same name,
-described below.
-\end{funcdesc}
-
-
-\subsection{IC Objects}
-
-\class{IC} objects have a mapping interface, hence to obtain the mail
-address you simply get \code{\var{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
-\module{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 \code{ICOpaqueData} type, with the raw data in its
-\member{data} attribute. Objects of this type are also acceptable values
-for assignment.
-
-Besides the dictionary interface, \class{IC} objects have the
-following methods:
-
-
-\begin{methoddesc}[IC]{launchurl}{url\optional{, hint}}
-Parse the given URL, launch the correct application and pass it the
-URL. The optional \var{hint} can be a scheme name such as
-\code{'mailto:'}, in which case incomplete URLs are completed with this
-scheme. If \var{hint} is not provided, incomplete URLs are invalid.
-\end{methoddesc}
-
-\begin{methoddesc}[IC]{parseurl}{data\optional{, start\optional{, end\optional{, hint}}}}
-Find an URL somewhere in \var{data} and return start position, end
-position and the URL. The optional \var{start} and \var{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
-\var{start} and this routine will return the whole URL in which the
-user clicked. As above, \var{hint} is an optional scheme used to
-complete incomplete URLs.
-\end{methoddesc}
-
-\begin{methoddesc}[IC]{mapfile}{file}
-Return the mapping entry for the given \var{file}, which can be passed
-as either a filename or an \function{FSSpec()} result, and which
-need not exist.
-
-The mapping entry is returned as a tuple \code{(\var{version},
-\var{type}, \var{creator}, \var{postcreator}, \var{flags},
-\var{extension}, \var{appname}, \var{postappname}, \var{mimetype},
-\var{entryname})}, where \var{version} is the entry version
-number, \var{type} is the 4-character filetype, \var{creator} is the
-4-character creator type, \var{postcreator} is the 4-character creator
-code of an
-optional application to post-process the file after downloading,
-\var{flags} are various bits specifying whether to transfer in binary
-or ascii and such, \var{extension} is the filename extension for this
-file type, \var{appname} is the printable name of the application to
-which this file belongs, \var{postappname} is the name of the
-postprocessing application, \var{mimetype} is the MIME type of this
-file and \var{entryname} is the name of this entry.
-\end{methoddesc}
-
-\begin{methoddesc}[IC]{maptypecreator}{type, creator\optional{, filename}}
-Return the mapping entry for files with given 4-character \var{type} and
-\var{creator} codes. The optional \var{filename} may be specified to
-further help finding the correct entry (if the creator code is
-\code{'????'}, for instance).
-
-The mapping entry is returned in the same format as for \var{mapfile}.
-\end{methoddesc}
-
-\begin{methoddesc}[IC]{settypecreator}{file}
-Given an existing \var{file}, specified either as a filename or as an
-\function{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.
-\end{methoddesc}
diff --git a/Doc/mac/libmacos.tex b/Doc/mac/libmacos.tex
deleted file mode 100644
index e50b99b..0000000
--- a/Doc/mac/libmacos.tex
+++ /dev/null
@@ -1,90 +0,0 @@
-\section{\module{MacOS} ---
- Access to Mac OS interpreter features}
-
-\declaremodule{builtin}{MacOS}
- \platform{Mac}
-\modulesynopsis{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.
-
-\begin{datadesc}{runtimemodel}
-Always \code{'macho'}, from Python 2.4 on.
-In earlier versions of Python the value could
-also be \code{'ppc'} for the classic Mac OS 8 runtime model or
-\code{'carbon'} for the Mac OS 9 runtime model.
-\end{datadesc}
-
-\begin{datadesc}{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 \code{'static'} for a
-statically linked Python, \code{'framework'} for Python in a Mac OS X framework,
-\code{'shared'} for Python in a standard \UNIX{} shared library.
-Older Pythons could also have the value
-\code{'cfm'} for Mac OS 9-compatible Python.
-\end{datadesc}
-
-\begin{excdesc}{Error}
-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 \refmodule{macerrors}.\refstmodindex{macerrors}
-\end{excdesc}
-
-
-\begin{funcdesc}{GetErrorString}{errno}
-Return the textual description of MacOS error code \var{errno}.
-\end{funcdesc}
-
-\begin{funcdesc}{DebugStr}{message \optional{, 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}.
-\end{funcdesc}
-
-\begin{funcdesc}{SysBeep}{}
-Ring the bell.
-\end{funcdesc}
-
-\begin{funcdesc}{GetTicks}{}
-Get the number of clock ticks (1/60th of a second) since system boot.
-\end{funcdesc}
-
-\begin{funcdesc}{GetCreatorAndType}{file}
-Return the file creator and file type as two four-character strings.
-The \var{file} parameter can be a pathname or an \code{FSSpec} or
-\code{FSRef} object.
-\end{funcdesc}
-
-\begin{funcdesc}{SetCreatorAndType}{file, creator, type}
-Set the file creator and file type.
-The \var{file} parameter can be a pathname or an \code{FSSpec} or
-\code{FSRef} object. \var{creator} and \var{type} must be four character
-strings.
-\end{funcdesc}
-
-\begin{funcdesc}{openrf}{name \optional{, mode}}
-Open the resource fork of a file. Arguments are the same as for the
-built-in function \function{open()}. The object returned has file-like
-semantics, but it is not a Python file object, so there may be subtle
-differences.
-\end{funcdesc}
-
-\begin{funcdesc}{WMAvailable}{}
-Checks whether the current process has access to the window manager.
-The method will return \code{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.
-\end{funcdesc}
diff --git a/Doc/mac/libmacostools.tex b/Doc/mac/libmacostools.tex
deleted file mode 100644
index 2754811..0000000
--- a/Doc/mac/libmacostools.tex
+++ /dev/null
@@ -1,106 +0,0 @@
-\section{\module{macostools} ---
- Convenience routines for file manipulation}
-
-\declaremodule{standard}{macostools}
- \platform{Mac}
-\modulesynopsis{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 \module{macostools} module defines the following functions:
-
-
-\begin{funcdesc}{copy}{src, dst\optional{, createpath\optional{, copytimes}}}
-Copy file \var{src} to \var{dst}. If \var{createpath} is non-zero
-the folders leading to \var{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.
-\end{funcdesc}
-
-\begin{funcdesc}{copytree}{src, dst}
-Recursively copy a file tree from \var{src} to \var{dst}, creating
-folders as needed. \var{src} and \var{dst} should be specified as
-pathnames.
-\end{funcdesc}
-
-\begin{funcdesc}{mkalias}{src, dst}
-Create a finder alias \var{dst} pointing to \var{src}.
-\end{funcdesc}
-
-\begin{funcdesc}{touched}{dst}
-Tell the finder that some bits of finder-information such as creator
-or type for file \var{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.}
-\end{funcdesc}
-
-\begin{datadesc}{BUFSIZ}
-The buffer size for \code{copy}, default 1 megabyte.
-\end{datadesc}
-
-Note that the process of creating finder aliases is not specified in
-the Apple documentation. Hence, aliases created with \function{mkalias()}
-could conceivably have incompatible behaviour in some cases.
-
-
-\section{\module{findertools} ---
- The \program{finder}'s Apple Events interface}
-
-\declaremodule{standard}{findertools}
- \platform{Mac}
-\modulesynopsis{Wrappers around the \program{finder}'s Apple Events interface.}
-
-
-This module contains routines that give Python programs access to some
-functionality provided by the finder. They are implemented as wrappers
-around the AppleEvent\index{AppleEvents} 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 \module{findertools} module defines the following functions:
-
-
-\begin{funcdesc}{launch}{file}
-Tell the finder to launch \var{file}. What launching means depends on the file:
-applications are started, folders are opened and documents are opened
-in the correct application.
-\end{funcdesc}
-
-\begin{funcdesc}{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.
-\end{funcdesc}
-
-\begin{funcdesc}{copy}{file, destdir}
-Tell the finder to copy a file or folder \var{file} to folder
-\var{destdir}. The function returns an \class{Alias} object pointing to
-the new file.
-\end{funcdesc}
-
-\begin{funcdesc}{move}{file, destdir}
-Tell the finder to move a file or folder \var{file} to folder
-\var{destdir}. The function returns an \class{Alias} object pointing to
-the new file.
-\end{funcdesc}
-
-\begin{funcdesc}{sleep}{}
-Tell the finder to put the Macintosh to sleep, if your machine
-supports it.
-\end{funcdesc}
-
-\begin{funcdesc}{restart}{}
-Tell the finder to perform an orderly restart of the machine.
-\end{funcdesc}
-
-\begin{funcdesc}{shutdown}{}
-Tell the finder to perform an orderly shutdown of the machine.
-\end{funcdesc}
diff --git a/Doc/mac/libmacui.tex b/Doc/mac/libmacui.tex
deleted file mode 100644
index db649ab..0000000
--- a/Doc/mac/libmacui.tex
+++ /dev/null
@@ -1,266 +0,0 @@
-\section{\module{EasyDialogs} ---
- Basic Macintosh dialogs}
-
-\declaremodule{standard}{EasyDialogs}
- \platform{Mac}
-\modulesynopsis{Basic Macintosh dialogs.}
-
-The \module{EasyDialogs} module contains some simple dialogs for the
-Macintosh. All routines take an optional resource ID parameter \var{id}
-with which one can override the \constant{DLOG} resource used for the
-dialog, provided that the dialog items correspond (both type and item
-number) to those in the default \constant{DLOG} resource. See source
-code for details.
-
-The \module{EasyDialogs} module defines the following functions:
-
-
-\begin{funcdesc}{Message}{str\optional{, id\optional{, ok}}}
-Displays a modal dialog with the message text \var{str}, which should be
-at most 255 characters long. The button text defaults to ``OK'', but is
-set to the string argument \var{ok} if the latter is supplied. Control
-is returned when the user clicks the ``OK'' button.
-\end{funcdesc}
-
-
-\begin{funcdesc}{AskString}{prompt\optional{, default\optional{,
- id\optional{, ok\optional{, cancel}}}}}
-Asks the user to input a string value via a modal dialog. \var{prompt}
-is the prompt message, and the optional \var{default} supplies the
-initial value for the string (otherwise \code{""} is used). The text of
-the ``OK'' and ``Cancel'' buttons can be changed with the \var{ok} and
-\var{cancel} arguments. All strings can be at most 255 bytes long.
-\function{AskString()} returns the string entered or \constant{None}
-in case the user cancelled.
-\end{funcdesc}
-
-
-\begin{funcdesc}{AskPassword}{prompt\optional{, default\optional{,
- id\optional{, ok\optional{, cancel}}}}}
-Asks the user to input a string value via a modal dialog. Like
-\function{AskString()}, but with the text shown as bullets. The
-arguments have the same meaning as for \function{AskString()}.
-\end{funcdesc}
-
-
-\begin{funcdesc}{AskYesNoCancel}{question\optional{, default\optional{,
- yes\optional{, no\optional{, cancel\optional{, id}}}}}}
-Presents a dialog with prompt \var{question} and three buttons labelled
-``Yes'', ``No'', and ``Cancel''. Returns \code{1} for ``Yes'', \code{0}
-for ``No'' and \code{-1} for ``Cancel''. The value of \var{default} (or
-\code{0} if \var{default} is not supplied) is returned when the
-\kbd{RETURN} key is pressed. The text of the buttons can be changed with
-the \var{yes}, \var{no}, and \var{cancel} arguments; to prevent a button
-from appearing, supply \code{""} for the corresponding argument.
-\end{funcdesc}
-
-
-\begin{funcdesc}{ProgressBar}{\optional{title\optional{, maxval\optional{,
- label\optional{, id}}}}}
-Displays a modeless progress-bar dialog. This is the constructor for the
-\class{ProgressBar} class described below. \var{title} is the text
-string displayed (default ``Working...''), \var{maxval} is the value at
-which progress is complete (default \code{0}, indicating that an
-indeterminate amount of work remains to be done), and \var{label} is
-the text that is displayed above the progress bar itself.
-\end{funcdesc}
-
-
-\begin{funcdesc}{GetArgv}{\optional{optionlist\optional{
- commandlist\optional{, addoldfile\optional{, addnewfile\optional{,
- addfolder\optional{, id}}}}}}}
-Displays a dialog which aids the user in constructing a command-line
-argument list. Returns the list in \code{sys.argv} format, suitable for
-passing as an argument to \function{getopt.getopt()}. \var{addoldfile},
-\var{addnewfile}, and \var{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
-\function{getopt.getopt()}.) Arguments containing spaces can be
-specified by enclosing them within single or double quotes. A
-\exception{SystemExit} exception is raised if the user presses the
-``Cancel'' button.
-
-\var{optionlist} is a list that determines a popup menu from which the
-allowed options are selected. Its items can take one of two forms:
-\var{optstr} or \code{(\var{optstr}, \var{descr})}. When present,
-\var{descr} is a short descriptive string that is displayed in the
-dialog while this option is selected in the popup menu. The
-correspondence between \var{optstr}s and command-line arguments is:
-
-\begin{tableii}{l|l}{textrm}{\var{optstr} format}{Command-line format}
-\lineii{\code{x}}
- {\programopt{-x} (short option)}
-\lineii{\code{x:} or \code{x=}}
- {\programopt{-x} (short option with value)}
-\lineii{\code{xyz}}
- {\longprogramopt{xyz} (long option)}
-\lineii{\code{xyz:} or \code{xyz=}}
- {\longprogramopt{xyz} (long option with value)}
-\end{tableii}
-
-\var{commandlist} is a list of items of the form \var{cmdstr} or
-\code{(\var{cmdstr}, \var{descr})}, where \var{descr} is as above. The
-\var{cmdstr}s will appear in a popup menu. When chosen, the text of
-\var{cmdstr} will be appended to the command line as is, except that a
-trailing \character{:} or \character{=} (if present) will be trimmed
-off.
-
-\versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{AskFileForOpen}{
- \optional{message}
- \optional{, typeList}
- \optional{, defaultLocation}
- \optional{, defaultOptionFlags}
- \optional{, location}
- \optional{, clientName}
- \optional{, windowTitle}
- \optional{, actionButtonLabel}
- \optional{, cancelButtonLabel}
- \optional{, preferenceKey}
- \optional{, popupExtension}
- \optional{, eventProc}
- \optional{, previewProc}
- \optional{, filterProc}
- \optional{, wanted}
- }
-Post a dialog asking the user for a file to open, and return the file
-selected or \constant{None} if the user cancelled.
-\var{message} is a text message to display,
-\var{typeList} is a list of 4-char filetypes allowable,
-\var{defaultLocation} is the pathname, \class{FSSpec} or \class{FSRef}
-of the folder to show initially,
-\var{location} is the \code{(x, y)} position on the screen where the
-dialog is shown,
-\var{actionButtonLabel} is a string to show instead of ``Open'' in the
-OK button,
-\var{cancelButtonLabel} is a string to show instead of ``Cancel'' in the
-cancel button,
-\var{wanted} is the type of value wanted as a return: \class{str},
-\class{unicode}, \class{FSSpec}, \class{FSRef} and subtypes thereof are
-acceptable.
-
-\index{Navigation Services}
-For a description of the other arguments please see the Apple Navigation
-Services documentation and the \module{EasyDialogs} source code.
-\end{funcdesc}
-
-\begin{funcdesc}{AskFileForSave}{
- \optional{message}
- \optional{, savedFileName}
- \optional{, defaultLocation}
- \optional{, defaultOptionFlags}
- \optional{, location}
- \optional{, clientName}
- \optional{, windowTitle}
- \optional{, actionButtonLabel}
- \optional{, cancelButtonLabel}
- \optional{, preferenceKey}
- \optional{, popupExtension}
- \optional{, fileType}
- \optional{, fileCreator}
- \optional{, eventProc}
- \optional{, wanted}
- }
-Post a dialog asking the user for a file to save to, and return the
-file selected or \constant{None} if the user cancelled.
-\var{savedFileName} is the default for the file name to save to (the
-return value). See \function{AskFileForOpen()} for a description of
-the other arguments.
-\end{funcdesc}
-
-\begin{funcdesc}{AskFolder}{
- \optional{message}
- \optional{, defaultLocation}
- \optional{, defaultOptionFlags}
- \optional{, location}
- \optional{, clientName}
- \optional{, windowTitle}
- \optional{, actionButtonLabel}
- \optional{, cancelButtonLabel}
- \optional{, preferenceKey}
- \optional{, popupExtension}
- \optional{, eventProc}
- \optional{, filterProc}
- \optional{, wanted}
- }
-Post a dialog asking the user to select a folder, and return the
-folder selected or \constant{None} if the user cancelled. See
-\function{AskFileForOpen()} for a description of the arguments.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seetitle
- [http://developer.apple.com/documentation/Carbon/Reference/Navigation_Services_Ref/]
- {Navigation Services Reference}{Programmer's reference documentation
- for the Navigation Services, a part of the Carbon framework.}
-\end{seealso}
-
-
-\subsection{ProgressBar Objects \label{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[Support for indeterminate-style progress bars was
- added]{2.2}
-
-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 \exception{KeyboardInterrupt} is
-raised (but note that this response does not occur until the progress
-bar is next updated, typically via a call to \method{inc()} or
-\method{set()}). Otherwise, the bar remains visible until the
-\class{ProgressBar} object is discarded.
-
-\class{ProgressBar} objects possess the following attributes and
-methods:
-
-\begin{memberdesc}[ProgressBar]{curval}
-The current value (of type integer or long integer) of the progress
-bar. The normal access methods coerce \member{curval} between
-\code{0} and \member{maxval}. This attribute should not be altered
-directly.
-\end{memberdesc}
-
-\begin{memberdesc}[ProgressBar]{maxval}
-The maximum value (of type integer or long integer) of the progress
-bar; the progress bar (thermometer style) is full when \member{curval}
-equals \member{maxval}. If \member{maxval} is \code{0}, the bar will
-be indeterminate (barber-pole). This attribute should not be altered
-directly.
-\end{memberdesc}
-
-\begin{methoddesc}[ProgressBar]{title}{\optional{newstr}}
-Sets the text in the title bar of the progress dialog to
-\var{newstr}.
-\end{methoddesc}
-
-\begin{methoddesc}[ProgressBar]{label}{\optional{newstr}}
-Sets the text in the progress box of the progress dialog to
-\var{newstr}.
-\end{methoddesc}
-
-\begin{methoddesc}[ProgressBar]{set}{value\optional{, max}}
-Sets the progress bar's \member{curval} to \var{value}, and also
-\member{maxval} to \var{max} if the latter is provided. \var{value}
-is first coerced between 0 and \member{maxval}. The thermometer bar
-is updated to reflect the changes, including a change from
-indeterminate to determinate or vice versa.
-\end{methoddesc}
-
-\begin{methoddesc}[ProgressBar]{inc}{\optional{n}}
-Increments the progress bar's \member{curval} by \var{n}, or by \code{1}
-if \var{n} is not provided. (Note that \var{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 \member{curval} is coerced
-between 0 and \member{maxval} if incrementing causes it to fall
-outside this range.
-\end{methoddesc}
diff --git a/Doc/mac/libminiae.tex b/Doc/mac/libminiae.tex
deleted file mode 100644
index 9d815f0..0000000
--- a/Doc/mac/libminiae.tex
+++ /dev/null
@@ -1,65 +0,0 @@
-\section{\module{MiniAEFrame} ---
- Open Scripting Architecture server support}
-
-\declaremodule{standard}{MiniAEFrame}
- \platform{Mac}
-\modulesynopsis{Support to act as an Open Scripting Architecture (OSA) server
-(``Apple Events'').}
-
-
-The module \module{MiniAEFrame} provides a framework for an application
-that can function as an Open Scripting Architecture
-\index{Open Scripting Architecture}
-(OSA) server, i.e. receive and process
-AppleEvents\index{AppleEvents}. It can be used in conjunction with
-\refmodule{FrameWork}\refstmodindex{FrameWork} or standalone. As an
-example, it is used in \program{PythonCGISlave}.
-
-
-The \module{MiniAEFrame} module defines the following classes:
-
-
-\begin{classdesc}{AEServer}{}
-A class that handles AppleEvent dispatch. Your application should
-subclass this class together with either
-\class{MiniApplication} or
-\class{FrameWork.Application}. Your \method{__init__()} method should
-call the \method{__init__()} method for both classes.
-\end{classdesc}
-
-\begin{classdesc}{MiniApplication}{}
-A class that is more or less compatible with
-\class{FrameWork.Application} but with less functionality. Its
-event loop supports the apple menu, command-dot and AppleEvents; other
-events are passed on to the Python interpreter and/or Sioux.
-Useful if your application wants to use \class{AEServer} but does not
-provide its own windows, etc.
-\end{classdesc}
-
-
-\subsection{AEServer Objects \label{aeserver-objects}}
-
-\begin{methoddesc}[AEServer]{installaehandler}{classe, type, callback}
-Installs an AppleEvent handler. \var{classe} and \var{type} are the
-four-character OSA Class and Type designators, \code{'****'} wildcards
-are allowed. When a matching AppleEvent is received the parameters are
-decoded and your callback is invoked.
-\end{methoddesc}
-
-\begin{methoddesc}[AEServer]{callback}{_object, **kwargs}
-Your callback is called with the OSA Direct Object as first positional
-parameter. The other parameters are passed as keyword arguments, with
-the 4-character designator as name. Three extra keyword parameters are
-passed: \code{_class} and \code{_type} are the Class and Type
-designators and \code{_attributes} is a dictionary with the AppleEvent
-attributes.
-
-The return value of your method is packed with
-\function{aetools.packevent()} and sent as reply.
-\end{methoddesc}
-
-Note that there are some serious problems with the current
-design. AppleEvents which have non-identifier 4-character designators
-for arguments are not implementable, and it is not possible to return
-an error to the originator. This will be addressed in a future
-release.
diff --git a/Doc/mac/libscrap.tex b/Doc/mac/libscrap.tex
deleted file mode 100644
index aa46278..0000000
--- a/Doc/mac/libscrap.tex
+++ /dev/null
@@ -1,42 +0,0 @@
-\section{\module{Carbon.Scrap} --- Scrap Manager}
-\declaremodule{standard}{Carbon.Scrap}
- \platform{Mac}
-\modulesynopsis{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.
-
-The Scrap\index{Scrap Manager} 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 \module{Scrap} module provides low-level access to the functions
-of the Scrap Manager. It contains the following functions:
-
-
-\begin{funcdesc}{InfoScrap}{}
- Return current information about the scrap. The information is
- encoded as a tuple containing the fields \code{(\var{size},
- \var{handle}, \var{count}, \var{state}, \var{path})}.
-
- \begin{tableii}{l|l}{var}{Field}{Meaning}
- \lineii{size}{Size of the scrap in bytes.}
- \lineii{handle}{Resource object representing the scrap.}
- \lineii{count}{Serial number of the scrap contents.}
- \lineii{state}{Integer; positive if in memory, \code{0} if on
- disk, negative if uninitialized.}
- \lineii{path}{Filename of the scrap when stored on disk.}
- \end{tableii}
-\end{funcdesc}
-
-
-
-\begin{seealso}
- \seetitle[http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-109.html]
- {Scrap Manager}{Apple's documentation for the Scrap Manager
- gives a lot of useful information about using the Scrap
- Manager in applications.}
-\end{seealso}
diff --git a/Doc/mac/mac.tex b/Doc/mac/mac.tex
deleted file mode 100644
index 7618057..0000000
--- a/Doc/mac/mac.tex
+++ /dev/null
@@ -1,88 +0,0 @@
-\documentclass{manual}
-
-\title{Macintosh Library Modules}
-
-\input{boilerplate}
-
-\makeindex % tell \index to actually write the .idx file
-\makemodindex % ... and the module index as well.
-
-
-\begin{document}
-
-\maketitle
-
-\ifhtml
-\chapter*{Front Matter\label{front}}
-\fi
-
-\input{copyright}
-
-\begin{abstract}
-
-\noindent
-This library reference manual documents Python's extensions for the
-Macintosh. It should be used in conjunction with the
-\citetitle[../lib/lib.html]{Python Library Reference}, which documents
-the standard library and built-in types.
-
-This manual assumes basic knowledge about the Python language. For an
-informal introduction to Python, see the
-\citetitle[../tut/tut.html]{Python Tutorial}; the
-\citetitle[../ref/ref.html]{Python Reference Manual} remains the
-highest authority on syntactic and semantic questions. Finally, the
-manual entitled \citetitle[../ext/ext.html]{Extending and Embedding
-the Python Interpreter} describes how to add new extensions to Python
-and how to embed it in other applications.
-
-\end{abstract}
-
-\tableofcontents
-
-
-\input{using.tex} % Using Python on the Macintosh
-
-
-\chapter{MacPython Modules \label{macpython-modules}}
-
-The following modules are only available on the Macintosh, and are
-documented here:
-
-\localmoduletable
-
-\input{libmac}
-\input{libmacic}
-\input{libmacos}
-\input{libmacostools}
-\input{libmacui}
-\input{libframework}
-\input{libautogil}
-
-\input{scripting}
-
-\input{toolbox} % MacOS Toolbox Modules
-\input{libcolorpicker}
-
-\input{undoc} % Undocumented Modules
-
-\appendix
-\chapter{History and License}
-\input{license}
-
-%
-% The ugly "%begin{latexonly}" pseudo-environments are really just to
-% keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
-% not really valuable.
-%
-
-%begin{latexonly}
-\renewcommand{\indexname}{Module Index}
-%end{latexonly}
-\input{modmac.ind} % Module Index
-
-%begin{latexonly}
-\renewcommand{\indexname}{Index}
-%end{latexonly}
-\input{mac.ind} % Index
-
-\end{document}
diff --git a/Doc/mac/scripting.tex b/Doc/mac/scripting.tex
deleted file mode 100644
index 5ec4978..0000000
--- a/Doc/mac/scripting.tex
+++ /dev/null
@@ -1,101 +0,0 @@
-\chapter{MacPython OSA Modules \label{scripting}}
-
-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:
-
-\begin{verbatim}
-tell application "Finder"
- get name of window 1
-end tell
-\end{verbatim}
-
-In Python, the following code fragment will do the same:
-
-\begin{verbatim}
-import Finder
-
-f = Finder.Finder()
-print f.get(f.window(1).name)
-\end{verbatim}
-
-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 \module{__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
-\module{Standard_Suite} that imports and re-exports everything from
-\module{StdSuites.Standard_Suite} but overrides the methods that have
-extra functionality. The output of \module{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
-\code{f.get(f.window(1).name)} instead of the more Pythonic
-\code{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:
-\begin{itemize}
- \item spaces are replaced with underscores
- \item other non-alphanumeric characters are replaced with
- \code{_xx_} where \code{xx} is the hexadecimal character value
- \item any Python reserved word gets an underscore appended
-\end{itemize}
-
-Python also has support for creating scriptable applications
-in Python, but
-The following modules are relevant to MacPython AppleScript support:
-
-\localmoduletable
-
-In addition, support modules have been pre-generated for
-\module{Finder}, \module{Terminal}, \module{Explorer},
-\module{Netscape}, \module{CodeWarrior}, \module{SystemEvents} and
-\module{StdSuites}.
-
-\input{libgensuitemodule}
-\input{libaetools}
-\input{libaepack}
-\input{libaetypes}
-\input{libminiae}
diff --git a/Doc/mac/toolbox.tex b/Doc/mac/toolbox.tex
deleted file mode 100644
index e7ce24f..0000000
--- a/Doc/mac/toolbox.tex
+++ /dev/null
@@ -1,173 +0,0 @@
-\chapter{MacOS Toolbox Modules \label{toolbox}}
-
-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 \member{__doc__} string describing their arguments
-and return values, and for additional description you are referred to
-\citetitle[http://developer.apple.com/documentation/macos8/mac8.html]{Inside
-Macintosh} or similar works.
-
-These modules all live in a package called \module{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
-
-\begin{verbatim}
-from Carbon import AE
-\end{verbatim}
-
-\strong{Warning!} These modules are not yet documented. If you
-wish to contribute documentation of any of these modules, please get
-in touch with \email{docs@python.org}.
-
-\localmoduletable
-
-
-%\section{Argument Handling for Toolbox Modules}
-
-
-\section{\module{Carbon.AE} --- Apple Events}
-\declaremodule{standard}{Carbon.AE}
- \platform{Mac}
-\modulesynopsis{Interface to the Apple Events toolbox.}
-
-\section{\module{Carbon.AH} --- Apple Help}
-\declaremodule{standard}{Carbon.AH}
- \platform{Mac}
-\modulesynopsis{Interface to the Apple Help manager.}
-
-
-\section{\module{Carbon.App} --- Appearance Manager}
-\declaremodule{standard}{Carbon.App}
- \platform{Mac}
-\modulesynopsis{Interface to the Appearance Manager.}
-
-
-\section{\module{Carbon.CF} --- Core Foundation}
-\declaremodule{standard}{Carbon.CF}
- \platform{Mac}
-\modulesynopsis{Interface to the Core Foundation.}
-
-The
-\code{CFBase}, \code{CFArray}, \code{CFData}, \code{CFDictionary},
-\code{CFString} and \code{CFURL} objects are supported, some
-only partially.
-
-\section{\module{Carbon.CG} --- Core Graphics}
-\declaremodule{standard}{Carbon.CG}
- \platform{Mac}
-\modulesynopsis{Interface to the Component Manager.}
-
-\section{\module{Carbon.CarbonEvt} --- Carbon Event Manager}
-\declaremodule{standard}{Carbon.CarbonEvt}
- \platform{Mac}
-\modulesynopsis{Interface to the Carbon Event Manager.}
-
-\section{\module{Carbon.Cm} --- Component Manager}
-\declaremodule{standard}{Carbon.Cm}
- \platform{Mac}
-\modulesynopsis{Interface to the Component Manager.}
-
-
-\section{\module{Carbon.Ctl} --- Control Manager}
-\declaremodule{standard}{Carbon.Ctl}
- \platform{Mac}
-\modulesynopsis{Interface to the Control Manager.}
-
-
-\section{\module{Carbon.Dlg} --- Dialog Manager}
-\declaremodule{standard}{Carbon.Dlg}
- \platform{Mac}
-\modulesynopsis{Interface to the Dialog Manager.}
-
-
-\section{\module{Carbon.Evt} --- Event Manager}
-\declaremodule{standard}{Carbon.Evt}
- \platform{Mac}
-\modulesynopsis{Interface to the classic Event Manager.}
-
-
-\section{\module{Carbon.Fm} --- Font Manager}
-\declaremodule{standard}{Carbon.Fm}
- \platform{Mac}
-\modulesynopsis{Interface to the Font Manager.}
-
-\section{\module{Carbon.Folder} --- Folder Manager}
-\declaremodule{standard}{Carbon.Folder}
- \platform{Mac}
-\modulesynopsis{Interface to the Folder Manager.}
-
-
-\section{\module{Carbon.Help} --- Help Manager}
-\declaremodule{standard}{Carbon.Help}
- \platform{Mac}
-\modulesynopsis{Interface to the Carbon Help Manager.}
-
-\section{\module{Carbon.List} --- List Manager}
-\declaremodule{standard}{Carbon.List}
- \platform{Mac}
-\modulesynopsis{Interface to the List Manager.}
-
-
-\section{\module{Carbon.Menu} --- Menu Manager}
-\declaremodule{standard}{Carbon.Menu}
- \platform{Mac}
-\modulesynopsis{Interface to the Menu Manager.}
-
-
-\section{\module{Carbon.Mlte} --- MultiLingual Text Editor}
-\declaremodule{standard}{Carbon.Mlte}
- \platform{Mac}
-\modulesynopsis{Interface to the MultiLingual Text Editor.}
-
-
-\section{\module{Carbon.Qd} --- QuickDraw}
-\declaremodule{builtin}{Carbon.Qd}
- \platform{Mac}
-\modulesynopsis{Interface to the QuickDraw toolbox.}
-
-
-\section{\module{Carbon.Qdoffs} --- QuickDraw Offscreen}
-\declaremodule{builtin}{Carbon.Qdoffs}
- \platform{Mac}
-\modulesynopsis{Interface to the QuickDraw Offscreen APIs.}
-
-
-\section{\module{Carbon.Qt} --- QuickTime}
-\declaremodule{standard}{Carbon.Qt}
- \platform{Mac}
-\modulesynopsis{Interface to the QuickTime toolbox.}
-
-
-\section{\module{Carbon.Res} --- Resource Manager and Handles}
-\declaremodule{standard}{Carbon.Res}
- \platform{Mac}
-\modulesynopsis{Interface to the Resource Manager and Handles.}
-
-\section{\module{Carbon.Scrap} --- Scrap Manager}
-\declaremodule{standard}{Carbon.Scrap}
- \platform{Mac}
-\modulesynopsis{Interface to the Carbon Scrap Manager.}
-
-\section{\module{Carbon.Snd} --- Sound Manager}
-\declaremodule{standard}{Carbon.Snd}
- \platform{Mac}
-\modulesynopsis{Interface to the Sound Manager.}
-
-
-\section{\module{Carbon.TE} --- TextEdit}
-\declaremodule{standard}{Carbon.TE}
- \platform{Mac}
-\modulesynopsis{Interface to TextEdit.}
-
-
-\section{\module{Carbon.Win} --- Window Manager}
-\declaremodule{standard}{Carbon.Win}
- \platform{Mac}
-\modulesynopsis{Interface to the Window Manager.}
diff --git a/Doc/mac/undoc.tex b/Doc/mac/undoc.tex
deleted file mode 100644
index adbf589..0000000
--- a/Doc/mac/undoc.tex
+++ /dev/null
@@ -1,85 +0,0 @@
-\chapter{Undocumented Modules \label{undocumented-modules}}
-
-
-The modules in this chapter are poorly documented (if at all). If you
-wish to contribute documentation of any of these modules, please get in
-touch with
-\ulink{\email{docs@python.org}}{mailto:docs@python.org}.
-
-\localmoduletable
-
-
-\section{\module{applesingle} --- AppleSingle decoder}
-\declaremodule{standard}{applesingle}
- \platform{Mac}
-\modulesynopsis{Rudimentary decoder for AppleSingle format files.}
-
-
-\section{\module{buildtools} --- Helper module for BuildApplet and Friends}
-\declaremodule{standard}{buildtools}
- \platform{Mac}
-\modulesynopsis{Helper module for BuildApplet, BuildApplication and
- macfreeze.}
-
-\deprecated{2.4}{}
-
-\section{\module{icopen} --- Internet Config replacement for \method{open()}}
-\declaremodule{standard}{icopen}
- \platform{Mac}
-\modulesynopsis{Internet Config replacement for \method{open()}.}
-
-Importing \module{icopen} will replace the builtin \method{open()}
-with a version that uses Internet Config to set file type and creator
-for new files.
-
-
-\section{\module{macerrors} --- Mac OS Errors}
-\declaremodule{standard}{macerrors}
- \platform{Mac}
-\modulesynopsis{Constant definitions for many Mac OS error codes.}
-
-\module{macerrors} contains constant definitions for many Mac OS error
-codes.
-
-
-\section{\module{macresource} --- Locate script resources}
-\declaremodule{standard}{macresource}
- \platform{Mac}
-\modulesynopsis{Locate script resources.}
-
-\module{macresource} helps scripts finding their resources, such as
-dialogs and menus, without requiring special case code for when the
-script is run under MacPython, as a MacPython applet or under OSX Python.
-
-\section{\module{Nav} --- NavServices calls}
-\declaremodule{standard}{Nav}
- \platform{Mac}
-\modulesynopsis{Interface to Navigation Services.}
-
-A low-level interface to Navigation Services.
-
-\section{\module{PixMapWrapper} --- Wrapper for PixMap objects}
-\declaremodule{standard}{PixMapWrapper}
- \platform{Mac}
-\modulesynopsis{Wrapper for PixMap objects.}
-
-\module{PixMapWrapper} wraps a PixMap object with a Python object that
-allows access to the fields by name. It also has methods to convert
-to and from \module{PIL} images.
-
-\section{\module{videoreader} --- Read QuickTime movies}
-\declaremodule{standard}{videoreader}
- \platform{Mac}
-\modulesynopsis{Read QuickTime movies frame by frame for further processing.}
-
-\module{videoreader} reads and decodes QuickTime movies and passes
-a stream of images to your program. It also provides some support for
-audio tracks.
-
-\section{\module{W} --- Widgets built on \module{FrameWork}}
-\declaremodule{standard}{W}
- \platform{Mac}
-\modulesynopsis{Widgets for the Mac, built on top of \refmodule{FrameWork}.}
-
-The \module{W} widgets are used extensively in the \program{IDE}.
-
diff --git a/Doc/mac/using.tex b/Doc/mac/using.tex
deleted file mode 100644
index ca522c6..0000000
--- a/Doc/mac/using.tex
+++ /dev/null
@@ -1,178 +0,0 @@
-\chapter{Using Python on a Macintosh \label{using}}
-\sectionauthor{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.
-
-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
-\url{http://www.cwi.nl/\textasciitilde jack/macpython} for installers
-for the latest 2.3 release for Mac OS 9 and related documentation.
-
-\section{Getting and Installing MacPython \label{getting-OSX}}
-
-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
-(\url{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:
-
-\begin{itemize}
-\item 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.
-
-\item 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/.
-\end{itemize}
-
-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.
-
-
-\subsection{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
-\url{http://www.barebones.com/products/bbedit/index.shtml}) are good choices, as
-is \program{TextMate} (see \url{http://macromates.com/}). Other editors include
-\program{Gvim} (\url{http://macvim.org}) and \program{Aquamacs}
-(\url{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:
-
-\begin{itemize}
-\item Drag it to \program{PythonLauncher}
-\item 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.
-\end{itemize}
-
-
-\subsection{Running scripts with a GUI \label{osx-gui-scripts}}
-
-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}.
-
-\subsection{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{\textasciitilde
- /.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}, ``Installing Additional Python Packages.''
-
-
-\section{The IDE\label{IDE}}
-
-MacPython ships with the standard IDLE development environment. A good
-introduction to using IDLE can be found at
-\url{http://hkn.eecs.berkeley.edu/~dyoo/python/idle_intro/index.html}.
-
-
-\section{Installing Additional Python Packages \label{mac-package-manager}}
-
-There are several methods to install additional Python packages:
-
-\begin{itemize}
-\item \url{http://pythonmac.org/packages/} contains selected compiled packages
- for Python 2.5, 2.4, and 2.3.
-\item Packages can be installed via the standard Python distutils mode
- (\samp{python setup.py install}).
-\item Many packages can also be installed via the \program{setuptools}
- extension.
-\end{itemize}
-
-
-\section{GUI Programming on the Mac}
-
-There are several options for building GUI applications on the Mac with Python.
-
-\emph{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 \url{http://pybojc.sourceforge.net}.
-
-The standard Python GUI toolkit is \module{Tkinter}, based on the cross-platform
-Tk toolkit (\url{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
-\url{http://www.activestate.com}; it can also be built from source.
-
-\emph{wxPython} is another popular cross-platform GUI toolkit that runs natively
-on Mac OS X. Packages and documentation are available from
-\url{http://www.wxpython.org}.
-
-\emph{PyQt} is another popular cross-platform GUI toolkit that runs natively on
-Mac OS X. More information can be found at
-\url{http://www.riverbankcomputing.co.uk/pyqt/}.
-
-
-\section{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 \url{http://undefined.org/python/\#py2app}.
-
-\section{Application Scripting}
-
-Python can also be used to script other Mac applications via Apple's Open
-Scripting Architecture (OSA); see
-\url{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 \emph{AppleScript} language for automating your Mac. A related
-package, \emph{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.
-
-\section{Other Resources}
-
-The MacPython mailing list is an excellent support resource for Python users and
-developers on the Mac:
-
-\url{http://www.python.org/community/sigs/current/pythonmac-sig/}
-
-Another useful resource is the MacPython wiki:
-
-\url{http://wiki.python.org/moin/MacPython}
diff --git a/Doc/paper-a4/pypaper.sty b/Doc/paper-a4/pypaper.sty
deleted file mode 100644
index 2415aad..0000000
--- a/Doc/paper-a4/pypaper.sty
+++ /dev/null
@@ -1,17 +0,0 @@
-%
-% Change this to say a4paper instead of letterpaper if you want A4.
-%
-\newcommand{\py@paper}{a4paper}
-\newcommand{\py@ptsize}{10pt}
-
-% These set up the fonts for the documents.
-%
-% The "times" package makes the default font the PostScript Times
-% font, which makes for smaller PostScript and a font that more people
-% like.
-%
-% The "avant" package causes the AvantGarde font to be used for
-% sans-serif text, instead of the uglier Helvetica set up by the "times"
-% package.
-%
-\RequirePackage{times}\typeout{Using Times instead of Computer Modern.}
diff --git a/Doc/perl/SynopsisTable.pm b/Doc/perl/SynopsisTable.pm
deleted file mode 100644
index 3c65a67..0000000
--- a/Doc/perl/SynopsisTable.pm
+++ /dev/null
@@ -1,95 +0,0 @@
-package SynopsisTable;
-
-sub new{
- return bless {names=>'', info=>{}, file=>''};
-}
-
-sub declare{
- my($self,$name,$key,$type) = @_;
- if ($self->{names}) {
- $self->{names} .= ",$name";
- }
- else {
- $self->{names} .= "$name";
- }
- $self->{info}{$name} = "$key,$type,";
-}
-
-# The 'file' attribute is used to store the filename of the node in which
-# the table will be presented; this assumes that each table will be presented
-# only once, which works for the current use of this object.
-
-sub set_file{
- my($self, $filename) = @_;
- $self->{file} = "$filename";
-}
-
-sub get_file{
- my $self = shift;
- return $self->{file};
-}
-
-sub set_synopsis{
- my($self,$name,$synopsis) = @_;
- my($key,$type,$unused) = split ',', $self->{info}{$name}, 3;
- $self->{info}{$name} = "$key,$type,$synopsis";
-}
-
-sub get{
- my($self,$name) = @_;
- return split /,/, $self->{info}{$name}, 3;
-}
-
-sub show{
- my $self = shift;
- my $name;
- print "names: ", $self->{names}, "\n\n";
- foreach $name (split /,/, $self->{names}) {
- my($key,$type,$synopsis) = $self->get($name);
- print "$name($key) is $type: $synopsis\n";
- }
-}
-
-sub tohtml{
- my $self = shift;
- my $oddrow = 1;
- my $data = "<table class='synopsistable' valign='baseline'>\n";
- my $name;
- foreach $name (split /,/, $self->{names}) {
- my($key,$type,$synopsis) = $self->get($name);
- my $link = "<a href='module-$key.html'>";
- $synopsis =~ s/<tex2html_percent_mark>/%/g;
- $synopsis =~ s/<tex2html_ampersand_mark>/\&/g;
- $data .= (' <tr'
- . ($oddrow ? " class='oddrow'>\n " : '>')
- . "<td><b><tt class='module'>$link$name</a></tt></b></td>\n"
- . " <td>\ </td>\n"
- . " <td class='synopsis'>$synopsis</td></tr>\n");
- $oddrow = !$oddrow;
- }
- $data .= "</table>\n";
- $data;
-}
-
-
-package testSynopsisTable;
-
-sub test{
- # this little test is mostly to debug the stuff above, since this is
- # my first Perl "object".
- my $st = SynopsisTable->new();
- $st->declare("sample", "sample", "standard");
- $st->set_synopsis("sample", "This is a little synopsis....");
- $st->declare("copy_reg", "copyreg", "standard");
- $st->set_synopsis("copy_reg", "pickle support stuff");
- $st->show();
-
- print "\n\n";
-
- my $st2 = SynopsisTable->new();
- $st2->declare("st2module", "st2module", "built-in");
- $st2->set_synopsis("st2module", "silly little synopsis");
- $st2->show();
-}
-
-1; # This must be the last line -- Perl is bogus!
diff --git a/Doc/perl/distutils.perl b/Doc/perl/distutils.perl
deleted file mode 100644
index afc2e4a..0000000
--- a/Doc/perl/distutils.perl
+++ /dev/null
@@ -1,21 +0,0 @@
-# LaTeX2HTML support for distutils.sty.
-
-package main;
-
-sub do_cmd_command {
- return use_wrappers(@_[0], '<code class="du-command">', '</code>');
-}
-
-sub do_cmd_option {
- return use_wrappers(@_[0], '<span class="du-option">', '</span>');
-}
-
-sub do_cmd_filevar {
- return use_wrappers(@_[0], '<span class="du-filevar">', '</span>');
-}
-
-sub do_cmd_XXX {
- return use_wrappers(@_[0], '<b class="du-xxx">', '</b>');
-}
-
-1; # Bad Perl.
diff --git a/Doc/perl/howto.perl b/Doc/perl/howto.perl
deleted file mode 100644
index 76791eb..0000000
--- a/Doc/perl/howto.perl
+++ /dev/null
@@ -1,12 +0,0 @@
-# -*- perl -*-
-#
-# This implements the Python howto class. All it really needs to do it
-# load the "python" style.
-
-package main;
-
-do_require_package("article");
-do_require_package("alltt");
-do_require_package("python");
-
-1; # sheesh....
diff --git a/Doc/perl/isilo.perl b/Doc/perl/isilo.perl
deleted file mode 100644
index e990b36..0000000
--- a/Doc/perl/isilo.perl
+++ /dev/null
@@ -1,12 +0,0 @@
-package main;
-
-$USING_STYLES = 0;
-$NO_NAVIGATION = 1;
-$INDEX_COLUMNS = 1;
-$MODULE_INDEX_COLUMNS = 1;
-
-sub child_line {
- return '';
-}
-
-1; # stupid perl...
diff --git a/Doc/perl/l2hinit.perl b/Doc/perl/l2hinit.perl
deleted file mode 100644
index 7c5d123..0000000
--- a/Doc/perl/l2hinit.perl
+++ /dev/null
@@ -1,801 +0,0 @@
-# LaTeX2HTML support base for use with Python documentation.
-
-package main;
-
-use L2hos;
-
-$HTML_VERSION = 4.01;
-$LOWER_CASE_TAGS = 1;
-$NO_FRENCH_QUOTES = 1;
-
-# '' in \code{...} is still converted, so we can't use this yet.
-#$USE_CURLY_QUOTES = 1;
-
-# Force Unicode support to be loaded; request UTF-8 output.
-do_require_extension('unicode');
-do_require_extension('utf8');
-$HTML_OPTIONS = 'utf8';
-
-$MAX_LINK_DEPTH = 2;
-$ADDRESS = '';
-
-$NO_FOOTNODE = 1;
-$NUMBERED_FOOTNOTES = 1;
-
-# Python documentation uses section numbers to support references to match
-# in the printed and online versions.
-#
-$SHOW_SECTION_NUMBERS = 1;
-
-$ICONSERVER = '.';
-$IMAGE_TYPE = 'gif';
-
-# Control where the navigation bars should show up:
-$TOP_NAVIGATION = 1;
-$BOTTOM_NAVIGATION = 1;
-$AUTO_NAVIGATION = 0;
-
-$BODYTEXT = '';
-$CHILDLINE = "\n<p><br /></p><hr class='online-navigation' />\n";
-$VERBOSITY = 0;
-
-# default # of columns for the indexes
-$INDEX_COLUMNS = 2;
-$MODULE_INDEX_COLUMNS = 4;
-
-$HAVE_MODULE_INDEX = 0;
-$HAVE_GENERAL_INDEX = 0;
-$HAVE_TABLE_OF_CONTENTS = 0;
-
-$AESOP_META_TYPE = 'information';
-
-
-# A little painful, but lets us clean up the top level directory a little,
-# and not be tied to the current directory (as far as I can tell). Testing
-# an existing definition of $mydir is needed since it cannot be computed when
-# run under mkhowto with recent versions of LaTeX2HTML, since this file is
-# not read directly by LaTeX2HTML any more. mkhowto is required to prepend
-# the required definition at the top of the actual input file.
-#
-if (!defined $mydir) {
- use Cwd;
- use File::Basename;
- ($myname, $mydir, $myext) = fileparse(__FILE__, '\..*');
- chop $mydir; # remove trailing '/'
- $mydir = getcwd() . "$dd$mydir"
- unless $mydir =~ s|^/|/|;
-}
-$LATEX2HTMLSTYLES = "$mydir$envkey$LATEX2HTMLSTYLES";
-push (@INC, $mydir);
-
-($myrootname, $myrootdir, $myext) = fileparse($mydir, '\..*');
-chop $myrootdir;
-
-
-# Hackish way to get the appropriate paper-*/ directory into $TEXINPUTS;
-# pass in the paper size (a4 or letter) as the environment variable PAPER
-# to add the right directory. If not given, the current directory is
-# added instead for use with HOWTO processing.
-#
-if (defined $ENV{'PAPER'}) {
- $mytexinputs = "$myrootdir${dd}paper-$ENV{'PAPER'}$envkey";
-}
-else {
- $mytexinputs = getcwd() . $envkey;
-}
-$mytexinputs .= "$myrootdir${dd}texinputs";
-
-
-# Change this variable to change the text added in "About this document...";
-# this should be an absolute pathname to get it right.
-#
-$ABOUT_FILE = "$myrootdir${dd}html${dd}stdabout.dat";
-
-
-sub custom_driver_hook {
- #
- # This adds the directory of the main input file to $TEXINPUTS; it
- # seems to be sufficiently general that it should be fine for HOWTO
- # processing.
- #
- # XXX This still isn't quite right; we should actually be inserting
- # $mytexinputs just before any empty entry in TEXINPUTS is one
- # exists instead of just concatenating the pieces like we do here.
- #
- my $file = $_[0];
- my($jobname, $dir, $ext) = fileparse($file, '\..*');
- $dir = L2hos->Make_directory_absolute($dir);
- $dir =~ s/$dd$//;
- $TEXINPUTS = "$dir$envkey$mytexinputs";
- # Push everything into $TEXINPUTS since LaTeX2HTML doesn't pick
- # this up on its own; we clear $ENV{'TEXINPUTS'} so the value set
- # for this by the main LaTeX2HTML script doesn't contain duplicate
- # directories.
- if ($ENV{'TEXINPUTS'}) {
- $TEXINPUTS .= "$envkey$ENV{'TEXINPUTS'}";
- $ENV{'TEXINPUTS'} = undef;
- }
- print "\nSetting \$TEXINPUTS to $TEXINPUTS\n";
-
- # Not sure why we need to deal with this both here and at the top,
- # but this is needed to actually make it work.
- do_require_extension('utf8');
- $charset = $utf8_str;
- $CHARSET = $utf8_str;
- $USE_UTF = 1;
-}
-
-
-# $CUSTOM_BUTTONS is only used for the module index link.
-$CUSTOM_BUTTONS = '';
-
-sub make_nav_sectref($$$) {
- my($label, $linktype, $title) = @_;
- if ($title) {
- if ($title =~ /\<[aA] /) {
- $title =~ s/\<[aA] /<a class="sectref" rel="$linktype" /;
- $title =~ s/ HREF=/ href=/;
- }
- else {
- $title = "<span class=\"sectref\">$title</span>";
- }
- return "<b class=\"navlabel\">$label:</b>\n$title\n";
- }
- return '';
-}
-
-@my_icon_tags = ();
-$my_icon_tags{'next'} = 'Next Page';
-$my_icon_tags{'next_page'} = 'Next Page';
-$my_icon_tags{'previous'} = 'Previous Page';
-$my_icon_tags{'previous_page'} = 'Previous Page';
-$my_icon_tags{'up'} = 'Up One Level';
-$my_icon_tags{'contents'} = 'Contents';
-$my_icon_tags{'index'} = 'Index';
-$my_icon_tags{'modules'} = 'Module Index';
-
-@my_icon_names = ();
-$my_icon_names{'previous_page'} = 'previous';
-$my_icon_names{'next_page'} = 'next';
-
-sub get_my_icon($) {
- my $name = $_[0];
- my $text = $my_icon_tags{$name};
- if ($my_icon_names{$name}) {
- $name = $my_icon_names{$name};
- }
- if ($text eq '') {
- $name = 'blank';
- }
- my $iconserver = ($ICONSERVER eq '.') ? '' : "$ICONSERVER/";
- return "<img src='$iconserver$name.$IMAGE_TYPE'\n border='0'"
- . " height='32' alt='$text' width='32' />";
-}
-
-sub unlinkify($) {
- my $text = "$_[0]";
- $text =~ s|</[aA]>||;
- $text =~ s|<a\s+[^>]*>||i;
- return $text;
-}
-
-sub use_icon($$$) {
- my($rel,$str,$title) = @_;
- if ($str) {
- my $s = "$str";
- if ($s =~ /\<tex2html_([a-z_]+)_visible_mark\>/) {
- my $r = get_my_icon($1);
- $s =~ s/\<tex2html_[a-z_]+_visible_mark\>/$r/;
- }
- $s =~ s/<[aA] /<a rel="$rel" title="$title"\n /;
- $s =~ s/ HREF=/ href=/;
- return $s;
- }
- else {
- return get_my_icon('blank');
- }
-}
-
-sub make_nav_panel() {
- my $s;
- # new iconic rel iconic page title
- my $next = use_icon('next', $NEXT, unlinkify($NEXT_TITLE));
- my $up = use_icon('parent', $UP, unlinkify($UP_TITLE));
- my $previous = use_icon('prev', $PREVIOUS, unlinkify($PREVIOUS_TITLE));
- my $contents = use_icon('contents', $CONTENTS, 'Table of Contents');
- my $index = use_icon('index', $INDEX, 'Index');
- if (!$CUSTOM_BUTTONS) {
- $CUSTOM_BUTTONS = get_my_icon('blank');
- }
- $s = ('<table align="center" width="100%" cellpadding="0" cellspacing="2">'
- . "\n<tr>"
- # left-hand side
- . "\n<td class='online-navigation'>$previous</td>"
- . "\n<td class='online-navigation'>$up</td>"
- . "\n<td class='online-navigation'>$next</td>"
- # title box
- . "\n<td align=\"center\" width=\"100%\">$t_title</td>"
- # right-hand side
- . "\n<td class='online-navigation'>$contents</td>"
- # module index
- . "\n<td class='online-navigation'>$CUSTOM_BUTTONS</td>"
- . "\n<td class='online-navigation'>$index</td>"
- . "\n</tr></table>\n"
- # textual navigation
- . "<div class='online-navigation'>\n"
- . make_nav_sectref("Previous", "prev", $PREVIOUS_TITLE)
- . make_nav_sectref("Up", "parent", $UP_TITLE)
- . make_nav_sectref("Next", "next", $NEXT_TITLE)
- . "</div>\n"
- );
- # remove these; they are unnecessary and cause errors from validation
- $s =~ s/ NAME="tex2html\d+"\n */ /g;
- return $s;
-}
-
-sub add_child_links {
- my $toc = add_real_child_links(@_);
- $toc =~ s|\s*</[aA]>|</a>|g;
- $toc =~ s/ NAME=\"tex2html\d+\"\s*href=/ href=/gi;
- $toc =~ s|</UL>(\s*<BR( /)?>)?|</ul>|gi;
- if ($toc =~ / NAME=["']CHILD_LINKS["']/) {
- return "<div class='online-navigation'>\n$toc</div>\n";
- }
- return $toc;
-}
-
-sub get_version_text() {
- if ($PACKAGE_VERSION ne '' && $t_date) {
- return ("<span class=\"release-info\">"
- . "Release $PACKAGE_VERSION$RELEASE_INFO,"
- . " documentation updated on $t_date.</span>");
- }
- if ($PACKAGE_VERSION ne '') {
- return ("<span class=\"release-info\">"
- . "Release $PACKAGE_VERSION$RELEASE_INFO.</span>");
- }
- if ($t_date) {
- return ("<span class=\"release-info\">Documentation released on "
- . "$t_date.</span>");
- }
- return '';
-}
-
-
-sub top_navigation_panel() {
- return "\n<div id='top-navigation-panel' xml:id='top-navigation-panel'>\n"
- . make_nav_panel()
- . "<hr /></div>\n";
-}
-
-sub bot_navigation_panel() {
- return "\n<div class='online-navigation'>\n"
- . "<p></p><hr />\n"
- . make_nav_panel()
- . "</div>\n"
- . "<hr />\n"
- . get_version_text()
- . "\n";
-}
-
-sub add_link {
- # Returns a pair (iconic link, textual link)
- my($icon, $current_file, @link) = @_;
- my($dummy, $file, $title) = split($delim,
- $section_info{join(' ',@link)});
- if ($icon =~ /\<tex2html_([_a-z]+)_visible_mark\>/) {
- my $r = get_my_icon($1);
- $icon =~ s/\<tex2html_[_a-z]+_visible_mark\>/$r/;
- }
- if ($title && ($file ne $current_file)) {
- $title = purify($title);
- $title = get_first_words($title, $WORDS_IN_NAVIGATION_PANEL_TITLES);
- return (make_href($file, $icon), make_href($file, "$title"))
- }
- elsif ($icon eq get_my_icon('up') && $EXTERNAL_UP_LINK) {
- return (make_href($EXTERNAL_UP_LINK, $icon),
- make_href($EXTERNAL_UP_LINK, "$EXTERNAL_UP_TITLE"))
- }
- elsif ($icon eq get_my_icon('previous')
- && $EXTERNAL_PREV_LINK && $EXTERNAL_PREV_TITLE) {
- return (make_href($EXTERNAL_PREV_LINK, $icon),
- make_href($EXTERNAL_PREV_LINK, "$EXTERNAL_PREV_TITLE"))
- }
- elsif ($icon eq get_my_icon('next')
- && $EXTERNAL_DOWN_LINK && $EXTERNAL_DOWN_TITLE) {
- return (make_href($EXTERNAL_DOWN_LINK, $icon),
- make_href($EXTERNAL_DOWN_LINK, "$EXTERNAL_DOWN_TITLE"))
- }
- return (&inactive_img($icon), "");
-}
-
-sub add_special_link($$$) {
- my($icon, $file, $current_file) = @_;
- if ($icon =~ /\<tex2html_([_a-z]+)_visible_mark\>/) {
- my $r = get_my_icon($1);
- $icon =~ s/\<tex2html_[_a-z]+_visible_mark\>/$r/;
- }
- return (($file && ($file ne $current_file))
- ? make_href($file, $icon)
- : undef)
-}
-
-# The img_tag() function seems only to be called with the parameter
-# 'anchor_invisible_mark', which we want to turn into ''. Since
-# replace_icon_marks() is the only interesting caller, and all it really
-# does is call img_tag(), we can just define the hook alternative to be
-# a no-op instead.
-#
-sub replace_icons_hook {}
-
-sub do_cmd_arabic {
- # get rid of that nasty <SPAN CLASS="arabic">...</SPAN>
- my($ctr, $val, $id, $text) = &read_counter_value($_[0]);
- return ($val ? farabic($val) : "0") . $text;
-}
-
-
-sub gen_index_id($$) {
- # this is used to ensure common index key generation and a stable sort
- my($str, $extra) = @_;
- sprintf('%s###%s%010d', $str, $extra, ++$global{'max_id'});
-}
-
-sub insert_index($$$$$) {
- my($mark, $datafile, $columns, $letters, $prefix) = @_;
- my $prog = "$myrootdir/tools/buildindex.py";
- my $index;
- if ($letters) {
- $index = `$prog --columns $columns --letters $datafile`;
- }
- else {
- $index = `$prog --columns $columns $datafile`;
- }
- if (!s/$mark/$prefix$index/) {
- print "\nCould not locate index mark: $mark";
- }
-}
-
-sub add_idx() {
- print "\nBuilding HTML for the index ...";
- close(IDXFILE);
- insert_index($idx_mark, 'index.dat', $INDEX_COLUMNS, 1, '');
-}
-
-
-$idx_module_mark = '<tex2html_idx_module_mark>';
-$idx_module_title = 'Module Index';
-
-sub add_module_idx() {
- print "\nBuilding HTML for the module index ...";
- my $key;
- my $first = 1;
- my $prevplat = '';
- my $allthesame = 1;
- my $prefix = '';
- foreach $key (keys %Modules) {
- $key =~ s/<tt>([a-zA-Z0-9._]*)<\/tt>/$1/;
- my $plat = "$ModulePlatforms{$key}";
- $plat = ''
- if ($plat eq $IGNORE_PLATFORM_ANNOTATION);
- if (!$first) {
- $allthesame = 0
- if ($prevplat ne $plat);
- }
- else { $first = 0; }
- $prevplat = $plat;
- }
- open(MODIDXFILE, '>modindex.dat') || die "\n$!\n";
- foreach $key (keys %Modules) {
- # dump the line in the data file; just use a dummy seqno field
- my $nkey = $1;
- my $moditem = "$Modules{$key}";
- my $plat = '';
- $key =~ s/<tt>([a-zA-Z0-9._]*)<\/tt>/$1/;
- if ($ModulePlatforms{$key} && !$allthesame) {
- $plat = (" <em>(<span class=\"platform\">$ModulePlatforms{$key}"
- . '</span>)</em>');
- }
- print MODIDXFILE $moditem . $IDXFILE_FIELD_SEP
- . "<tt class=\"module\">$key</tt>$plat###\n";
- }
- close(MODIDXFILE);
-
- if ($GLOBAL_MODULE_INDEX) {
- $prefix = <<MODULE_INDEX_PREFIX;
-
-<p> This index only lists modules documented in this manual.
- The <em class="citetitle"><a href="$GLOBAL_MODULE_INDEX">Global Module
- Index</a></em> lists all modules that are documented in this set
- of manuals.</p>
-MODULE_INDEX_PREFIX
- }
- if (!$allthesame) {
- $prefix .= <<PLAT_DISCUSS;
-
-<p> Some module names are followed by an annotation indicating what
-platform they are available on.</p>
-
-PLAT_DISCUSS
- }
- insert_index($idx_module_mark, 'modindex.dat', $MODULE_INDEX_COLUMNS, 0,
- $prefix);
-}
-
-# replace both indexes as needed:
-sub add_idx_hook {
- add_idx() if (/$idx_mark/);
- process_python_state();
- if ($MODULE_INDEX_FILE) {
- local ($_);
- open(MYFILE, "<$MODULE_INDEX_FILE");
- sysread(MYFILE, $_, 1024*1024);
- close(MYFILE);
- add_module_idx();
- open(MYFILE,">$MODULE_INDEX_FILE");
- print MYFILE $_;
- close(MYFILE);
- }
-}
-
-
-# In addition to the standard stuff, add label to allow named node files and
-# support suppression of the page complete (for HTML Help use).
-$MY_CONTENTS_PAGE = '';
-sub do_cmd_tableofcontents {
- local($_) = @_;
- $TITLE = $toc_title;
- $tocfile = $CURRENT_FILE;
- my($closures, $reopens) = preserve_open_tags();
- anchor_label('contents', $CURRENT_FILE, $_); # this is added
- $MY_CONTENTS_PAGE = "$CURRENT_FILE";
- join('', "\\tableofchildlinks[off]", $closures
- , make_section_heading($toc_title, 'h2'), $toc_mark
- , $reopens, $_);
-}
-# In addition to the standard stuff, add label to allow named node files.
-sub do_cmd_listoffigures {
- local($_) = @_;
- $TITLE = $lof_title;
- $loffile = $CURRENT_FILE;
- my($closures, $reopens) = preserve_open_tags();
- anchor_label('lof', $CURRENT_FILE, $_); # this is added
- join('', "<br />\n", $closures
- , make_section_heading($lof_title, 'h2'), $lof_mark
- , $reopens, $_);
-}
-# In addition to the standard stuff, add label to allow named node files.
-sub do_cmd_listoftables {
- local($_) = @_;
- $TITLE = $lot_title;
- $lotfile = $CURRENT_FILE;
- my($closures, $reopens) = preserve_open_tags();
- anchor_label('lot', $CURRENT_FILE, $_); # this is added
- join('', "<br />\n", $closures
- , make_section_heading($lot_title, 'h2'), $lot_mark
- , $reopens, $_);
-}
-# In addition to the standard stuff, add label to allow named node files.
-sub do_cmd_textohtmlinfopage {
- local($_) = @_;
- if ($INFO) { #
- anchor_label("about",$CURRENT_FILE,$_); # this is added
- } #
- my $the_version = ''; # and the rest is
- if ($t_date) { # mostly ours
- $the_version = ",\n$t_date";
- if ($PACKAGE_VERSION) {
- $the_version .= ", Release $PACKAGE_VERSION$RELEASE_INFO";
- }
- }
- my $about;
- open(ABOUT, "<$ABOUT_FILE") || die "\n$!\n";
- sysread(ABOUT, $about, 1024*1024);
- close(ABOUT);
- $_ = (($INFO == 1)
- ? join('',
- $close_all,
- "<strong>$t_title</strong>$the_version\n",
- $about,
- $open_all, $_)
- : join('', $close_all, $INFO,"\n", $open_all, $_));
- $_;
-}
-
-$GENERAL_INDEX_FILE = '';
-$MODULE_INDEX_FILE = '';
-
-# $idx_mark will be replaced with the real index at the end
-sub do_cmd_textohtmlindex {
- local($_) = @_;
- $TITLE = $idx_title;
- $idxfile = $CURRENT_FILE;
- $GENERAL_INDEX_FILE = "$CURRENT_FILE";
- if (%index_labels) { make_index_labels(); }
- if (($SHORT_INDEX) && (%index_segment)) { make_preindex(); }
- else { $preindex = ''; }
- my $heading = make_section_heading($idx_title, 'h2') . $idx_mark;
- my($pre, $post) = minimize_open_tags($heading);
- anchor_label('genindex',$CURRENT_FILE,$_); # this is added
- return "<br />\n" . $pre . $_;
-}
-
-# $idx_module_mark will be replaced with the real index at the end
-sub do_cmd_textohtmlmoduleindex {
- local($_) = @_;
- $TITLE = $idx_module_title;
- anchor_label('modindex', $CURRENT_FILE, $_);
- $MODULE_INDEX_FILE = "$CURRENT_FILE";
- $_ = ('<p></p>' . make_section_heading($idx_module_title, 'h2')
- . $idx_module_mark . $_);
- return $_;
-}
-
-# The bibliography and the index should be treated as separate
-# sections in their own HTML files. The \bibliography{} command acts
-# as a sectioning command that has the desired effect. But when the
-# bibliography is constructed manually using the thebibliography
-# environment, or when using the theindex environment it is not
-# possible to use the normal sectioning mechanism. This subroutine
-# inserts a \bibliography{} or a dummy \textohtmlindex command just
-# before the appropriate environments to force sectioning.
-
-# XXX This *assumes* that if there are two {theindex} environments,
-# the first is the module index and the second is the standard
-# index. This is sufficient for the current Python documentation,
-# but that's about it.
-
-sub add_bbl_and_idx_dummy_commands {
- my $id = $global{'max_id'};
-
- if (/[\\]tableofcontents/) {
- $HAVE_TABLE_OF_CONTENTS = 1;
- }
- s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg;
- s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo;
- my(@parts) = split(/\\begin\s*$O\d+$C\s*theindex/);
- if (scalar(@parts) == 3) {
- # Be careful to re-write the string in place, since $_ is *not*
- # returned explicity; *** nasty side-effect dependency! ***
- print "\nadd_bbl_and_idx_dummy_commands ==> adding general index";
- print "\nadd_bbl_and_idx_dummy_commands ==> adding module index";
- my $rx = "([\\\\]begin\\s*$O\\d+$C\\s*theindex[\\s\\S]*)"
- . "([\\\\]begin\\s*$O\\d+$C\\s*theindex)";
- s/$rx/\\textohtmlmoduleindex $1 \\textohtmlindex $2/o;
- # Add a button to the navigation areas:
- $CUSTOM_BUTTONS .= ('<a href="modindex.html" title="Module Index">'
- . get_my_icon('modules')
- . '</a>');
- $HAVE_MODULE_INDEX = 1;
- $HAVE_GENERAL_INDEX = 1;
- }
- elsif (scalar(@parts) == 2) {
- print "\nadd_bbl_and_idx_dummy_commands ==> adding general index";
- my $rx = "([\\\\]begin\\s*$O\\d+$C\\s*theindex)";
- s/$rx/\\textohtmlindex $1/o;
- $HAVE_GENERAL_INDEX = 1;
- }
- elsif (scalar(@parts) == 1) {
- print "\nadd_bbl_and_idx_dummy_commands ==> no index found";
- $CUSTOM_BUTTONS .= get_my_icon('blank');
- $global{'max_id'} = $id; # not sure why....
- s/([\\]begin\s*$O\d+$C\s*theindex)/\\textohtmlindex $1/o;
- s/[\\]printindex/\\textohtmlindex /o;
- }
- else {
- die "\n\nBad number of index environments!\n\n";
- }
- #----------------------------------------------------------------------
- lib_add_bbl_and_idx_dummy_commands()
- if defined(&lib_add_bbl_and_idx_dummy_commands);
-}
-
-# The bibliographic references, the appendices, the lists of figures
-# and tables etc. must appear in the contents table at the same level
-# as the outermost sectioning command. This subroutine finds what is
-# the outermost level and sets the above to the same level;
-
-sub set_depth_levels {
- # Sets $outermost_level
- my $level;
- #RRM: do not alter user-set value for $MAX_SPLIT_DEPTH
- foreach $level ("part", "chapter", "section", "subsection",
- "subsubsection", "paragraph") {
- last if (($outermost_level) = /\\($level)$delimiter_rx/);
- }
- $level = ($outermost_level ? $section_commands{$outermost_level} :
- do {$outermost_level = 'section'; 3;});
-
- #RRM: but calculate value for $MAX_SPLIT_DEPTH when a $REL_DEPTH was given
- if ($REL_DEPTH && $MAX_SPLIT_DEPTH) {
- $MAX_SPLIT_DEPTH = $level + $MAX_SPLIT_DEPTH;
- } elsif (!($MAX_SPLIT_DEPTH)) { $MAX_SPLIT_DEPTH = 1 };
-
- %unnumbered_section_commands = ('tableofcontents' => $level,
- 'listoffigures' => $level,
- 'listoftables' => $level,
- 'bibliography' => $level,
- 'textohtmlindex' => $level,
- 'textohtmlmoduleindex' => $level);
- $section_headings{'textohtmlmoduleindex'} = 'h1';
-
- %section_commands = (%unnumbered_section_commands,
- %section_commands);
-
- make_sections_rx();
-}
-
-
-# This changes the markup used for {verbatim} environments, and is the
-# best way I've found that ensures the <dl> goes on the outside of the
-# <pre>...</pre>.
-#
-# Note that this *must* be done in the init file, not the python.perl
-# style support file. The %declarations must be set before
-# initialize() is called in the main LaTeX2HTML script (which happens
-# before style files are loaded).
-#
-%declarations = ('preform' => '<div class="verbatim"><pre></pre></div>',
- %declarations);
-
-
-# This is a modified version of what's provided by LaTeX2HTML; see the
-# comment on the middle stanza for an explanation of why we keep our
-# own version.
-#
-# This routine must be called once on the text only,
-# else it will "eat up" sensitive constructs.
-sub text_cleanup {
- # MRO: replaced $* with /m
- s/(\s*\n){3,}/\n\n/gom; # Replace consecutive blank lines with one
- s/<(\/?)P>\s*(\w)/<$1P>\n$2/gom; # clean up paragraph starts and ends
- s/$O\d+$C//go; # Get rid of bracket id's
- s/$OP\d+$CP//go; # Get rid of processed bracket id's
- s/(<!)?--?(>)?/(length($1) || length($2)) ? "$1--$2" : "-"/ge;
- # Spacing commands
- s/\\( |$)/ /go;
- #JKR: There should be no more comments in the source now.
- #s/([^\\]?)%/$1/go; # Remove the comment character
- # Cannot treat \, as a command because , is a delimiter ...
- s/\\,/ /go;
- # Replace tilde's with non-breaking spaces
- s/ *~/ /g;
-
- # This is why we have this copy of this routine; the following
- # isn't so desirable as the author/maintainers of LaTeX2HTML seem
- # to think. It's not commented out in the main script, so we have
- # to override the whole thing. In particular, we don't want empty
- # table cells to disappear.
-
- ### DANGEROUS ?? ###
- # remove redundant (not <P></P>) empty tags, incl. with attributes
- #s/\n?<([^PD >][^>]*)>\s*<\/\1>//g;
- #s/\n?<([^PD >][^>]*)>\s*<\/\1>//g;
- # remove redundant empty tags (not </P><P> or <TD> or <TH>)
- #s/<\/(TT|[^PTH][A-Z]+)><\1>//g;
- #s/<([^PD ]+)(\s[^>]*)?>\n*<\/\1>//g;
-
- #JCL(jcl-hex)
- # Replace ^^ special chars (according to p.47 of the TeX book)
- # Useful when coming from the .aux file (german umlauts, etc.)
- s/\^\^([^0-9a-f])/chr((64+ord($1))&127)/ge;
- s/\^\^([0-9a-f][0-9a-f])/chr(hex($1))/ge;
-}
-
-# This is used to map the link rel attributes LaTeX2HTML uses to those
-# currently recommended by the W3C.
-sub custom_REL_hook {
- my($rel,$junk) = @_;
- return 'parent' if $rel eq 'up';
- return 'prev' if $rel eq 'previous';
- return $rel;
-}
-
-# This is added to get rid of the long comment that follows the
-# doctype declaration; MSIE5 on NT4 SP4 barfs on it and drops the
-# content of the page.
-$MY_PARTIAL_HEADER = '';
-sub make_head_and_body($$) {
- my($title, $body) = @_;
- $body = " $body" unless ($body eq '');
- my $DTDcomment = '';
- my($version, $isolanguage) = ($HTML_VERSION, 'EN');
- my %isolanguages = ( 'english', 'EN' , 'USenglish', 'EN.US'
- , 'original', 'EN' , 'german' , 'DE'
- , 'austrian', 'DE.AT', 'french' , 'FR'
- , 'spanish', 'ES');
- $isolanguage = $isolanguages{$default_language};
- $isolanguage = 'EN' unless $isolanguage;
- $title = &purify($title,1);
- eval("\$title = ". $default_title ) unless ($title);
-
- # allow user-modification of the <title> tag; thanks Dan Young
- if (defined &custom_TITLE_hook) {
- $title = &custom_TITLE_hook($title, $toc_sec_title);
- }
-
- if ($DOCTYPE =~ /\/\/[\w\.]+\s*$/) { # language spec included
- $DTDcomment = "<!DOCTYPE html PUBLIC \"$DOCTYPE\">\n";
- } else {
- $DTDcomment = "<!DOCTYPE html PUBLIC \"$DOCTYPE//"
- . ($ISO_LANGUAGE ? $ISO_LANGUAGE : $isolanguage) . "\">\n";
- }
- if ($MY_PARTIAL_HEADER eq '') {
- my $favicon = '';
- if ($FAVORITES_ICON) {
- my($myname, $mydir, $myext) = fileparse($FAVORITES_ICON, '\..*');
- my $favtype = '';
- if ($myext eq '.gif' || $myext eq '.png') {
- $myext =~ s/^[.]//;
- $favtype = " type=\"image/$myext\"";
- }
- $favicon = (
- "\n<link rel=\"SHORTCUT ICON\" href=\"$FAVORITES_ICON\""
- . "$favtype />");
- }
- $STYLESHEET = $FILE.".css" unless $STYLESHEET;
- $MY_PARTIAL_HEADER = join('',
- ($DOCTYPE ? $DTDcomment : ''),
- "<html>\n<head>",
- ($BASE ? "\n<base href=\"$BASE\" />" : ''),
- "\n<link rel=\"STYLESHEET\" href=\"$STYLESHEET\" type='text/css'",
- " />",
- $favicon,
- ($EXTERNAL_UP_LINK
- ? ("\n<link rel='start' href='" . $EXTERNAL_UP_LINK
- . ($EXTERNAL_UP_TITLE ?
- "' title='$EXTERNAL_UP_TITLE' />" : "' />"))
- : ''),
- "\n<link rel=\"first\" href=\"$FILE.html\"",
- ($t_title ? " title='$t_title'" : ''),
- ' />',
- ($HAVE_TABLE_OF_CONTENTS
- ? ("\n<link rel='contents' href='$MY_CONTENTS_PAGE'"
- . ' title="Contents" />')
- : ''),
- ($HAVE_GENERAL_INDEX
- ? ("\n<link rel='index' href='$GENERAL_INDEX_FILE'"
- . " title='Index' />")
- : ''),
- # disable for now -- Mozilla doesn't do well with multiple indexes
- # ($HAVE_MODULE_INDEX
- # ? ("<link rel="index" href='$MODULE_INDEX_FILE'"
- # . " title='Module Index' />\n")
- # : ''),
- ($INFO
- # XXX We can do this with the Python tools since the About...
- # page always gets copied to about.html, even when we use the
- # generated node###.html page names. Won't work with the
- # rest of the Python doc tools.
- ? ("\n<link rel='last' href='about.html'"
- . " title='About this document...' />"
- . "\n<link rel='help' href='about.html'"
- . " title='About this document...' />")
- : ''),
- $more_links_mark,
- "\n",
- ($CHARSET && $HTML_VERSION ge "2.1"
- ? ('<meta http-equiv="Content-Type" content="text/html; '
- . "charset=$CHARSET\" />\n")
- : ''),
- ($AESOP_META_TYPE
- ? "<meta name='aesop' content='$AESOP_META_TYPE' />\n" : ''));
- }
- if (!$charset && $CHARSET) {
- $charset = $CHARSET;
- $charset =~ s/_/\-/go;
- }
- join('',
- $MY_PARTIAL_HEADER,
- "<title>", $title, "</title>\n</head>\n<body$body>");
-}
-
-sub replace_morelinks {
- $more_links =~ s/ REL=/ rel=/g;
- $more_links =~ s/ HREF=/ href=/g;
- $more_links =~ s/<LINK /<link /g;
- $more_links =~ s/">/" \/>/g;
- $_ =~ s/$more_links_mark/$more_links/e;
-}
-
-1; # This must be the last line
diff --git a/Doc/perl/ltxmarkup.perl b/Doc/perl/ltxmarkup.perl
deleted file mode 100644
index 1a0f7e1..0000000
--- a/Doc/perl/ltxmarkup.perl
+++ /dev/null
@@ -1,67 +0,0 @@
-# LaTeX2HTML support for the ltxmarkup package. Doesn't do indexing.
-
-package main;
-
-
-sub ltx_next_argument{
- my $param;
- $param = missing_braces()
- unless ((s/$next_pair_pr_rx/$param=$2;''/eo)
- ||(s/$next_pair_rx/$param=$2;''/eo));
- return $param;
-}
-
-
-sub do_cmd_macro{
- local($_) = @_;
- my $macro = ltx_next_argument();
- return "<tt class='macro'>\$macro</tt>" . $_;
-}
-
-sub do_cmd_env{
- local($_) = @_;
- my $env = ltx_next_argument();
- return "<tt class='environment'>\$env</tt>" . $_;
-}
-
-sub ltx_process_params{
- # Handle processing of \p and \op for parameter specifications for
- # envdesc and macrodesc. It's done this way to avoid defining do_cmd_p()
- # and do_cmd_op() functions, which would be interpreted outside the context
- # in which these commands are legal, and cause LaTeX2HTML to think they're
- # defined. This way, other uses of \p and \op are properly flagged as
- # unknown macros.
- my $s = @_[0];
- $s =~ s%\\op<<(\d+)>>(.+)<<\1>>%<tt>[</tt><var>$2</var><tt>]</tt>%;
- while ($s =~ /\\p<<(\d+)>>(.+)<<\1>>/) {
- $s =~ s%\\p<<(\d+)>>(.+)<<\1>>%<tt>{</tt><var>$2</var><tt>}</tt>%;
- }
- return $s;
-}
-
-sub do_env_macrodesc{
- local($_) = @_;
- my $macro = ltx_next_argument();
- my $params = ltx_process_params(ltx_next_argument());
- return "\n<dl class='macrodesc'>"
- . "\n<dt><b><tt class='macro'>\$macro</tt></b>"
- . "\n $params</dt>"
- . "\n<dd>"
- . $_
- . '</dd></dl>';
-}
-
-sub do_env_envdesc{
- local($_) = @_;
- my $env = ltx_next_argument();
- my $params = ltx_process_params(ltx_next_argument());
- return "\n<dl class='envdesc'>"
- . "\n<dt><tt>\begin{<b class='environment'>$env</b>}</tt>"
- . "\n $params"
- . "\n<br /><tt>\end{<b class='environment'>$env</b>}</tt></dt>"
- . "\n<dd>"
- . $_
- . '</dd></dl>';
-}
-
-1; # Must end with this, because Perl is bogus.
diff --git a/Doc/perl/manual.perl b/Doc/perl/manual.perl
deleted file mode 100644
index ea65b36..0000000
--- a/Doc/perl/manual.perl
+++ /dev/null
@@ -1,15 +0,0 @@
-# -*- perl -*-
-#
-# This implements the Python manual class. All it really needs to do it
-# load the "python" style. The style code is not moved into the class code
-# at this time, since we expect additional document class to be developed
-# for the Python documentation in the future. Appropriate relocations will
-# be made at that time.
-
-package main;
-
-do_require_package("report");
-do_require_package("alltt");
-do_require_package("python");
-
-1; # sheesh....
diff --git a/Doc/perl/python.perl b/Doc/perl/python.perl
deleted file mode 100644
index 5e940e6..0000000
--- a/Doc/perl/python.perl
+++ /dev/null
@@ -1,2182 +0,0 @@
-# python.perl by Fred L. Drake, Jr. <fdrake@acm.org> -*- perl -*-
-#
-# Heavily based on Guido van Rossum's myformat.perl (now obsolete).
-#
-# Extension to LaTeX2HTML for documents using myformat.sty.
-# Subroutines of the form do_cmd_<name> here define translations
-# for LaTeX commands \<name> defined in the corresponding .sty file.
-
-package main;
-
-use warnings;
-use File::Basename;
-
-
-sub next_argument{
- my $param;
- $param = missing_braces()
- unless ((s/$next_pair_pr_rx/$param=$2;''/eo)
- ||(s/$next_pair_rx/$param=$2;''/eo));
- return $param;
-}
-
-sub next_optional_argument{
- my($param, $rx) = ('', "^\\s*(\\[([^]]*)\\])?");
- s/$rx/$param=$2;''/eo;
- return $param;
-}
-
-sub make_icon_filename($){
- my($myname, $mydir, $myext) = fileparse($_[0], '\..*');
- chop $mydir;
- if ($mydir eq '.') {
- $mydir = $ICONSERVER;
- }
- $myext = ".$IMAGE_TYPE"
- unless $myext;
- return "$mydir$dd$myname$myext";
-}
-
-sub get_link_icon($){
- my $url = $_[0];
- if ($OFF_SITE_LINK_ICON && ($url =~ /^[-a-zA-Z0-9.]+:/)) {
- # absolute URL; assume it points off-site
- my $icon = make_icon_filename($OFF_SITE_LINK_ICON);
- return (" <img src=\"$icon\"\n"
- . ' border="0" class="offsitelink"'
- . ($OFF_SITE_LINK_ICON_HEIGHT
- ? " height=\"$OFF_SITE_LINK_ICON_HEIGHT\""
- : '')
- . ($OFF_SITE_LINK_ICON_WIDTH
- ? " width=\"$OFF_SITE_LINK_ICON_WIDTH\""
- : '')
- . " alt=\"[off-site link]\"\n"
- . " />");
- }
- return '';
-}
-
-# This is a fairly simple hack; it supports \let when it is used to create
-# (or redefine) a macro to exactly be some other macro: \let\newname=\oldname.
-# Many possible uses of \let aren't supported or aren't supported correctly.
-#
-sub do_cmd_let{
- local($_) = @_;
- my $matched = 0;
- s/[\\]([a-zA-Z]+)\s*(=\s*)?[\\]([a-zA-Z]*)/$matched=1; ''/e;
- if ($matched) {
- my($new, $old) = ($1, $3);
- eval "sub do_cmd_$new { do_cmd_$old" . '(@_); }';
- print "\ndefining handler for \\$new using \\$old\n";
- }
- else {
- s/[\\]([a-zA-Z]+)\s*(=\s*)?([^\\])/$matched=1; ''/es;
- if ($matched) {
- my($new, $char) = ($1, $3);
- eval "sub do_cmd_$new { \"\\$char\" . \$_[0]; }";
- print "\ndefining handler for \\$new to insert '$char'\n";
- }
- else {
- write_warnings("Could not interpret \\let construct...");
- }
- }
- return $_;
-}
-
-
-# the older version of LaTeX2HTML we use doesn't support this, but we use it:
-
-sub do_cmd_textasciitilde{ '~' . $_[0]; }
-sub do_cmd_textasciicircum{ '^' . $_[0]; }
-sub do_cmd_textbar{ '|' . $_[0]; }
-sub do_cmd_texteuro { '€' . $_[0]; }
-sub do_cmd_textgreater{ '>' . $_[0]; }
-sub do_cmd_textless{ '<' . $_[0]; }
-sub do_cmd_textunderscore{ '_' . $_[0]; }
-sub do_cmd_infinity{ '∞' . $_[0]; }
-sub do_cmd_plusminus{ '±' . $_[0]; }
-sub do_cmd_guilabel{
- return use_wrappers($_[0]. '<span class="guilabel">', '</span>'); }
-sub do_cmd_menuselection{
- return use_wrappers($_[0], '<span class="guilabel">', '</span>'); }
-sub do_cmd_sub{
- return '</span> > <span class="guilabel">' . $_[0]; }
-
-
-# words typeset in a special way (not in HTML though)
-
-sub do_cmd_ABC{ 'ABC' . $_[0]; }
-sub do_cmd_UNIX{ '<span class="Unix">Unix</span>' . $_[0]; }
-sub do_cmd_LaTeX{ '<span class="LaTeX">LaTeX</span>' . $_[0]; }
-sub do_cmd_TeX{ '<span class="TeX">TeX</span>' . $_[0]; }
-sub do_cmd_ASCII{ 'ASCII' . $_[0]; }
-sub do_cmd_POSIX{ 'POSIX' . $_[0]; }
-sub do_cmd_C{ 'C' . $_[0]; }
-sub do_cmd_Cpp{ 'C++' . $_[0]; }
-sub do_cmd_EOF{ 'EOF' . $_[0]; }
-sub do_cmd_NULL{ '<tt class="constant">NULL</tt>' . $_[0]; }
-
-sub do_cmd_e{ '\' . $_[0]; }
-
-$DEVELOPER_ADDRESS = '';
-$SHORT_VERSION = '';
-$RELEASE_INFO = '';
-$PACKAGE_VERSION = '';
-
-sub do_cmd_version{ $PACKAGE_VERSION . $_[0]; }
-sub do_cmd_shortversion{ $SHORT_VERSION . $_[0]; }
-sub do_cmd_release{
- local($_) = @_;
- $PACKAGE_VERSION = next_argument();
- return $_;
-}
-
-sub do_cmd_setreleaseinfo{
- local($_) = @_;
- $RELEASE_INFO = next_argument();
- return $_;
-}
-
-sub do_cmd_setshortversion{
- local($_) = @_;
- $SHORT_VERSION = next_argument();
- return $_;
-}
-
-sub do_cmd_authoraddress{
- local($_) = @_;
- $DEVELOPER_ADDRESS = next_argument();
- return $_;
-}
-
-sub do_cmd_hackscore{
- local($_) = @_;
- next_argument();
- return '_' . $_;
-}
-
-# Helper used in many places that arbitrary code-like text appears:
-
-sub codetext($){
- my $text = "$_[0]";
- # Make sure that "---" is not converted to "--" later when
- # LaTeX2HTML tries converting em-dashes based on the conventional
- # TeX font ligatures:
- $text =~ s/--/-\-/go;
- return $text;
-}
-
-sub use_wrappers($$$){
- local($_,$before,$after) = @_;
- my $stuff = next_argument();
- return $before . $stuff . $after . $_;
-}
-
-sub use_code_wrappers($$$){
- local($_,$before,$after) = @_;
- my $stuff = codetext(next_argument());
- return $before . $stuff . $after . $_;
-}
-
-$IN_DESC_HANDLER = 0;
-sub do_cmd_optional{
- if ($IN_DESC_HANDLER) {
- return use_wrappers($_[0], "</var><big>\[</big><var>",
- "</var><big>\]</big><var>");
- }
- else {
- return use_wrappers($_[0], "<big>\[</big>", "<big>\]</big>");
- }
-}
-
-# Logical formatting (some based on texinfo), needs to be converted to
-# minimalist HTML. The "minimalist" is primarily to reduce the size of
-# output files for users that read them over the network rather than
-# from local repositories.
-
-sub do_cmd_pytype{ return $_[0]; }
-sub do_cmd_makevar{
- return use_wrappers($_[0], '<span class="makevar">', '</span>'); }
-sub do_cmd_code{
- return use_code_wrappers($_[0], '<code>', '</code>'); }
-sub do_cmd_module{
- return use_wrappers($_[0], '<tt class="module">', '</tt>'); }
-sub do_cmd_keyword{
- return use_wrappers($_[0], '<tt class="keyword">', '</tt>'); }
-sub do_cmd_exception{
- return use_wrappers($_[0], '<tt class="exception">', '</tt>'); }
-sub do_cmd_class{
- return use_wrappers($_[0], '<tt class="class">', '</tt>'); }
-sub do_cmd_function{
- return use_wrappers($_[0], '<tt class="function">', '</tt>'); }
-sub do_cmd_constant{
- return use_wrappers($_[0], '<tt class="constant">', '</tt>'); }
-sub do_cmd_member{
- return use_wrappers($_[0], '<tt class="member">', '</tt>'); }
-sub do_cmd_method{
- return use_wrappers($_[0], '<tt class="method">', '</tt>'); }
-sub do_cmd_cfunction{
- return use_wrappers($_[0], '<tt class="cfunction">', '</tt>'); }
-sub do_cmd_cdata{
- return use_wrappers($_[0], '<tt class="cdata">', '</tt>'); }
-sub do_cmd_ctype{
- return use_wrappers($_[0], '<tt class="ctype">', '</tt>'); }
-sub do_cmd_regexp{
- return use_code_wrappers($_[0], '<tt class="regexp">', '</tt>'); }
-sub do_cmd_character{
- return use_code_wrappers($_[0], '"<tt class="character">', '</tt>"'); }
-sub do_cmd_program{
- return use_wrappers($_[0], '<b class="program">', '</b>'); }
-sub do_cmd_programopt{
- return use_wrappers($_[0], '<b class="programopt">', '</b>'); }
-sub do_cmd_longprogramopt{
- # note that the --- will be later converted to -- by LaTeX2HTML
- return use_wrappers($_[0], '<b class="programopt">---', '</b>'); }
-sub do_cmd_email{
- return use_wrappers($_[0], '<span class="email">', '</span>'); }
-sub do_cmd_mailheader{
- return use_wrappers($_[0], '<span class="mailheader">', ':</span>'); }
-sub do_cmd_mimetype{
- return use_wrappers($_[0], '<span class="mimetype">', '</span>'); }
-sub do_cmd_var{
- return use_wrappers($_[0], "<var>", "</var>"); }
-sub do_cmd_dfn{
- return use_wrappers($_[0], '<i class="dfn">', '</i>'); }
-sub do_cmd_emph{
- return use_wrappers($_[0], '<em>', '</em>'); }
-sub do_cmd_file{
- return use_wrappers($_[0], '<span class="file">', '</span>'); }
-sub do_cmd_filenq{
- return do_cmd_file($_[0]); }
-sub do_cmd_samp{
- return use_code_wrappers($_[0], '"<tt class="samp">', '</tt>"'); }
-sub do_cmd_kbd{
- return use_wrappers($_[0], '<kbd>', '</kbd>'); }
-sub do_cmd_strong{
- return use_wrappers($_[0], '<strong>', '</strong>'); }
-sub do_cmd_textbf{
- return use_wrappers($_[0], '<b>', '</b>'); }
-sub do_cmd_textit{
- return use_wrappers($_[0], '<i>', '</i>'); }
-# This can be changed/overridden for translations:
-%NoticeNames = ('note' => 'Note:',
- 'warning' => 'Warning:',
- );
-
-sub do_cmd_note{
- my $label = $NoticeNames{'note'};
- return use_wrappers(
- $_[0],
- "<span class=\"note\"><b class=\"label\">$label</b>\n",
- '</span>'); }
-sub do_cmd_warning{
- my $label = $NoticeNames{'warning'};
- return use_wrappers(
- $_[0],
- "<span class=\"warning\"><b class=\"label\">$label</b>\n",
- '</span>'); }
-
-sub do_env_notice{
- local($_) = @_;
- my $notice = next_optional_argument();
- if (!$notice) {
- $notice = 'note';
- }
- my $label = $NoticeNames{$notice};
- return ("<div class=\"$notice\"><b class=\"label\">$label</b>\n"
- . $_
- . '</div>');
-}
-
-sub do_cmd_moreargs{
- return '...' . $_[0]; }
-sub do_cmd_unspecified{
- return '...' . $_[0]; }
-
-
-sub do_cmd_refmodule{
- # Insert the right magic to jump to the module definition.
- local($_) = @_;
- my $key = next_optional_argument();
- my $module = next_argument();
- $key = $module
- unless $key;
- return "<tt class=\"module\"><a href=\"module-$key.html\">$module</a></tt>"
- . $_;
-}
-
-sub do_cmd_newsgroup{
- local($_) = @_;
- my $newsgroup = next_argument();
- my $icon = get_link_icon("news:$newsgroup");
- my $stuff = ("<a class=\"newsgroup\" href=\"news:$newsgroup\">"
- . "$newsgroup$icon</a>");
- return $stuff . $_;
-}
-
-sub do_cmd_envvar{
- local($_) = @_;
- my $envvar = next_argument();
- my($name, $aname, $ahref) = new_link_info();
- # The <tt> here is really to keep buildindex.py from making
- # the variable name case-insensitive.
- add_index_entry("environment variables!$envvar@<tt>$envvar</tt>",
- $ahref);
- add_index_entry("$envvar (environment variable)", $ahref);
- $aname =~ s/<a/<a class="envvar"/;
- return "$aname$envvar</a>" . $_;
-}
-
-sub do_cmd_url{
- # use the URL as both text and hyperlink
- local($_) = @_;
- my $url = next_argument();
- my $icon = get_link_icon($url);
- $url =~ s/~/~/g;
- return "<a class=\"url\" href=\"$url\">$url$icon</a>" . $_;
-}
-
-sub do_cmd_manpage{
- # two parameters: \manpage{name}{section}
- local($_) = @_;
- my $page = next_argument();
- my $section = next_argument();
- return "<span class=\"manpage\"><i>$page</i>($section)</span>" . $_;
-}
-
-$PEP_FORMAT = "http://www.python.org/peps/pep-%04d.html";
-#$RFC_FORMAT = "http://www.ietf.org/rfc/rfc%04d.txt";
-$RFC_FORMAT = "http://www.faqs.org/rfcs/rfc%d.html";
-
-sub get_rfc_url($$){
- my($rfcnum, $format) = @_;
- return sprintf($format, $rfcnum);
-}
-
-sub do_cmd_pep{
- local($_) = @_;
- my $rfcnumber = next_argument();
- my $id = "rfcref-" . ++$global{'max_id'};
- my $href = get_rfc_url($rfcnumber, $PEP_FORMAT);
- my $icon = get_link_icon($href);
- # Save the reference
- my $nstr = gen_index_id("Python Enhancement Proposals!PEP $rfcnumber", '');
- $index{$nstr} .= make_half_href("$CURRENT_FILE#$id");
- return ("<a class=\"rfc\" id='$id' xml:id='$id'\n"
- . "href=\"$href\">PEP $rfcnumber$icon</a>" . $_);
-}
-
-sub do_cmd_rfc{
- local($_) = @_;
- my $rfcnumber = next_argument();
- my $id = "rfcref-" . ++$global{'max_id'};
- my $href = get_rfc_url($rfcnumber, $RFC_FORMAT);
- my $icon = get_link_icon($href);
- # Save the reference
- my $nstr = gen_index_id("RFC!RFC $rfcnumber", '');
- $index{$nstr} .= make_half_href("$CURRENT_FILE#$id");
- return ("<a class=\"rfc\" id='$id' xml:id='$id'\nhref=\"$href\">"
- . "RFC $rfcnumber$icon</a>" . $_);
-}
-
-sub do_cmd_ulink{
- local($_) = @_;
- my $text = next_argument();
- my $url = next_argument();
- return "<a class=\"ulink\" href=\"$url\"\n >$text</a>" . $_;
-}
-
-sub do_cmd_citetitle{
- local($_) = @_;
- my $url = next_optional_argument();
- my $title = next_argument();
- my $icon = get_link_icon($url);
- my $repl = '';
- if ($url) {
- my $titletext = strip_html_markup("$title");
- $repl = ("<em class=\"citetitle\"><a\n"
- . " href=\"$url\"\n"
- . " title=\"$titletext\"\n"
- . " >$title$icon</a></em>");
- }
- else {
- $repl = "<em class=\"citetitle\"\n >$title</em>";
- }
- return $repl . $_;
-}
-
-sub do_cmd_deprecated{
- # two parameters: \deprecated{version}{whattodo}
- local($_) = @_;
- my $release = next_argument();
- my $reason = next_argument();
- return ('<div class="versionnote">'
- . "<b>Deprecated since release $release.</b>"
- . "\n$reason</div><p></p>"
- . $_);
-}
-
-sub versionnote($$){
- # one or two parameters: \versionnote[explanation]{version}
- my $type = $_[0];
- local $_ = $_[1];
- my $explanation = next_optional_argument();
- my $release = next_argument();
- my $classes = "versionnote";
- if ($release =~ /^(\d+)\./) {
- $classes .= " versionnote$1";
- }
- my $text = "$type in version $release.";
- if ($explanation) {
- $text = "$type in version $release:\n$explanation.";
- }
- return "\n<span class=\"$classes\" \n>$text</span>\n" . $_;
-}
-
-sub do_cmd_versionadded{
- return versionnote('New', $_[0]);
-}
-
-sub do_cmd_versionchanged{
- return versionnote('Changed', $_[0]);
-}
-
-#
-# These function handle platform dependency tracking.
-#
-sub do_cmd_platform{
- local($_) = @_;
- my $platform = next_argument();
- $ModulePlatforms{"<tt class=\"module\">$THIS_MODULE</tt>"} = $platform;
- $platform = "Macintosh"
- if $platform eq 'Mac';
- return "\n<p class=\"availability\">Availability: <span"
- . "\n class=\"platform\">$platform</span>.</p>\n" . $_;
-}
-
-$IGNORE_PLATFORM_ANNOTATION = '';
-sub do_cmd_ignorePlatformAnnotation{
- local($_) = @_;
- $IGNORE_PLATFORM_ANNOTATION = next_argument();
- return $_;
-}
-
-
-# index commands
-
-$INDEX_SUBITEM = "";
-
-sub get_indexsubitem(){
- return $INDEX_SUBITEM ? " $INDEX_SUBITEM" : '';
-}
-
-sub do_cmd_setindexsubitem{
- local($_) = @_;
- $INDEX_SUBITEM = next_argument();
- return $_;
-}
-
-sub do_cmd_withsubitem{
- # We can't really do the right thing, because LaTeX2HTML doesn't
- # do things in the right order, but we need to at least strip this stuff
- # out, and leave anything that the second argument expanded out to.
- #
- local($_) = @_;
- my $oldsubitem = $INDEX_SUBITEM;
- $INDEX_SUBITEM = next_argument();
- my $stuff = next_argument();
- my $br_id = ++$globals{'max_id'};
- my $marker = "$O$br_id$C";
- $stuff =~ s/^\s+//;
- return
- $stuff
- . "\\setindexsubitem$marker$oldsubitem$marker"
- . $_;
-}
-
-# This is the prologue macro which is required to start writing the
-# mod\jobname.idx file; we can just ignore it. (Defining this suppresses
-# a warning that \makemodindex is unknown.)
-#
-sub do_cmd_makemodindex{ return $_[0]; }
-
-# We're in the document subdirectory when this happens!
-#
-open(IDXFILE, '>index.dat') || die "\n$!\n";
-open(INTLABELS, '>intlabels.pl') || die "\n$!\n";
-print INTLABELS "%internal_labels = ();\n";
-print INTLABELS "1; # hack in case there are no entries\n\n";
-
-# Using \0 for this is bad because we can't use common tools to work with the
-# resulting files. Things like grep can be useful with this stuff!
-#
-$IDXFILE_FIELD_SEP = "\1";
-
-sub write_idxfile($$){
- my($ahref, $str) = @_;
- print IDXFILE $ahref, $IDXFILE_FIELD_SEP, $str, "\n";
-}
-
-
-sub gen_link($$){
- my($node, $target) = @_;
- print INTLABELS "\$internal_labels{\"$target\"} = \"/$node\";\n";
- return "<a href=\"$node#$target\">";
-}
-
-sub add_index_entry($$){
- # add an entry to the index structures; ignore the return value
- my($str, $ahref) = @_;
- $str = gen_index_id($str, '');
- $index{$str} .= $ahref;
- write_idxfile($ahref, $str);
-}
-
-sub new_link_name_info(){
- my $name = "l2h-" . ++$globals{'max_id'};
- my $ahref = gen_link($CURRENT_FILE, $name);
- return ($name, $ahref);
-}
-
-sub new_link_info(){
- my($name, $ahref) = new_link_name_info();
- my $aname = "<a id='$name' xml:id='$name'>";
- return ($name, $aname, $ahref);
-}
-
-$IndexMacroPattern = '';
-sub define_indexing_macro(@){
- my $count = @_;
- my $i = 0;
- for (; $i < $count; ++$i) {
- my $name = $_[$i];
- my $cmd = "idx_cmd_$name";
- die "\nNo function $cmd() defined!\n"
- if (!defined &$cmd);
- eval ("sub do_cmd_$name { return process_index_macros("
- . "\$_[0], '$name'); }");
- if (length($IndexMacroPattern) == 0) {
- $IndexMacroPattern = "$name";
- }
- else {
- $IndexMacroPattern .= "|$name";
- }
- }
-}
-
-$DEBUG_INDEXING = 0;
-sub process_index_macros($$){
- local($_) = @_;
- my $cmdname = $_[1]; # This is what triggered us in the first place;
- # we know it's real, so just process it.
- my($name, $aname, $ahref) = new_link_info();
- my $cmd = "idx_cmd_$cmdname";
- print "\nIndexing: \\$cmdname"
- if $DEBUG_INDEXING;
- &$cmd($ahref); # modifies $_ and adds index entries
- while (/^[\s\n]*\\($IndexMacroPattern)</) {
- $cmdname = "$1";
- print " \\$cmdname"
- if $DEBUG_INDEXING;
- $cmd = "idx_cmd_$cmdname";
- if (!defined &$cmd) {
- last;
- }
- else {
- s/^[\s\n]*\\$cmdname//;
- &$cmd($ahref);
- }
- }
-# XXX I don't remember why I added this to begin with.
-# if (/^[ \t\r\n]/) {
-# $_ = substr($_, 1);
-# }
- return "$aname$anchor_invisible_mark</a>" . $_;
-}
-
-define_indexing_macro('index');
-sub idx_cmd_index($){
- my $str = next_argument();
- add_index_entry("$str", $_[0]);
-}
-
-define_indexing_macro('kwindex');
-sub idx_cmd_kwindex($){
- my $str = next_argument();
- add_index_entry("<tt>$str</tt>!keyword", $_[0]);
- add_index_entry("keyword!<tt>$str</tt>", $_[0]);
-}
-
-define_indexing_macro('indexii');
-sub idx_cmd_indexii($){
- my $str1 = next_argument();
- my $str2 = next_argument();
- add_index_entry("$str1!$str2", $_[0]);
- add_index_entry("$str2!$str1", $_[0]);
-}
-
-define_indexing_macro('indexiii');
-sub idx_cmd_indexiii($){
- my $str1 = next_argument();
- my $str2 = next_argument();
- my $str3 = next_argument();
- add_index_entry("$str1!$str2 $str3", $_[0]);
- add_index_entry("$str2!$str3, $str1", $_[0]);
- add_index_entry("$str3!$str1 $str2", $_[0]);
-}
-
-define_indexing_macro('indexiv');
-sub idx_cmd_indexiv($){
- my $str1 = next_argument();
- my $str2 = next_argument();
- my $str3 = next_argument();
- my $str4 = next_argument();
- add_index_entry("$str1!$str2 $str3 $str4", $_[0]);
- add_index_entry("$str2!$str3 $str4, $str1", $_[0]);
- add_index_entry("$str3!$str4, $str1 $str2", $_[0]);
- add_index_entry("$str4!$str1 $str2 $str3", $_[0]);
-}
-
-define_indexing_macro('ttindex');
-sub idx_cmd_ttindex($){
- my $str = codetext(next_argument());
- my $entry = $str . get_indexsubitem();
- add_index_entry($entry, $_[0]);
-}
-
-sub my_typed_index_helper($$){
- my($word, $ahref) = @_;
- my $str = next_argument();
- add_index_entry("$str $word", $ahref);
- add_index_entry("$word!$str", $ahref);
-}
-
-define_indexing_macro('stindex', 'opindex', 'exindex', 'obindex');
-sub idx_cmd_stindex($){ my_typed_index_helper('statement', $_[0]); }
-sub idx_cmd_opindex($){ my_typed_index_helper('operator', $_[0]); }
-sub idx_cmd_exindex($){ my_typed_index_helper('exception', $_[0]); }
-sub idx_cmd_obindex($){ my_typed_index_helper('object', $_[0]); }
-
-define_indexing_macro('bifuncindex');
-sub idx_cmd_bifuncindex($){
- my $str = next_argument();
- add_index_entry("<tt class=\"function\">$str()</tt> (built-in function)",
- $_[0]);
-}
-
-
-sub make_mod_index_entry($$){
- my($str, $define) = @_;
- my($name, $aname, $ahref) = new_link_info();
- # equivalent of add_index_entry() using $define instead of ''
- $ahref =~ s/\#[-_a-zA-Z0-9]*\"/\"/
- if ($define eq 'DEF');
- $str = gen_index_id($str, $define);
- $index{$str} .= $ahref;
- write_idxfile($ahref, $str);
-
- if ($define eq 'DEF') {
- # add to the module index
- $str =~ /(<tt.*<\/tt>)/;
- my $nstr = $1;
- $Modules{$nstr} .= $ahref;
- }
- return "$aname$anchor_invisible_mark2</a>";
-}
-
-
-$THIS_MODULE = '';
-$THIS_CLASS = '';
-
-sub define_module($$){
- my($word, $name) = @_;
- my $section_tag = join('', @curr_sec_id);
- if ($word ne "built-in" && $word ne "extension"
- && $word ne "standard" && $word ne "") {
- write_warnings("Bad module type '$word'"
- . " for \\declaremodule (module $name)");
- $word = "";
- }
- $word = "$word " if $word;
- $THIS_MODULE = "$name";
- $INDEX_SUBITEM = "(in module $name)";
- print "[$name]";
- return make_mod_index_entry(
- "<tt class=\"module\">$name</tt> (${word}module)", 'DEF');
-}
-
-sub my_module_index_helper($$){
- local($word, $_) = @_;
- my $name = next_argument();
- return define_module($word, $name) . $_;
-}
-
-sub do_cmd_modindex{ return my_module_index_helper('', $_[0]); }
-sub do_cmd_bimodindex{ return my_module_index_helper('built-in', $_[0]); }
-sub do_cmd_exmodindex{ return my_module_index_helper('extension', $_[0]); }
-sub do_cmd_stmodindex{ return my_module_index_helper('standard', $_[0]); }
-# local($_) = @_;
-# my $name = next_argument();
-# return define_module('standard', $name) . $_;
-# }
-
-sub ref_module_index_helper($$){
- my($word, $ahref) = @_;
- my $str = next_argument();
- $word = "$word " if $word;
- $str = "<tt class=\"module\">$str</tt> (${word}module)";
- # can't use add_index_entry() since the 2nd arg to gen_index_id() is used;
- # just inline it all here
- $str = gen_index_id($str, 'REF');
- $index{$str} .= $ahref;
- write_idxfile($ahref, $str);
-}
-
-# these should be adjusted a bit....
-define_indexing_macro('refmodindex', 'refbimodindex',
- 'refexmodindex', 'refstmodindex');
-sub idx_cmd_refmodindex($){
- return ref_module_index_helper('', $_[0]); }
-sub idx_cmd_refbimodindex($){
- return ref_module_index_helper('built-in', $_[0]); }
-sub idx_cmd_refexmodindex($){
- return ref_module_index_helper('extension', $_[0]);}
-sub idx_cmd_refstmodindex($){
- return ref_module_index_helper('standard', $_[0]); }
-
-sub do_cmd_nodename{ return do_cmd_label($_[0]); }
-
-sub init_myformat(){
- # This depends on the override of text_cleanup() in l2hinit.perl;
- # if that function cleans out empty tags, the first three of these
- # variables must be set to comments.
- #
- # Thanks to Dave Kuhlman for figuring why some named anchors were
- # being lost.
- $anchor_invisible_mark = '';
- $anchor_invisible_mark2 = '';
- $anchor_mark = '';
- $icons{'anchor_mark'} = '';
-}
-init_myformat();
-
-# Create an index entry, but include the string in the target anchor
-# instead of the dummy filler.
-#
-sub make_str_index_entry($){
- my $str = $_[0];
- my($name, $ahref) = new_link_name_info();
- add_index_entry($str, $ahref);
- if ($str =~ /^<[a-z]+\b/) {
- my $s = "$str";
- $s =~ s/^<([a-z]+)\b/<$1 id='$name' xml:id='$name'/;
- return $s;
- }
- else {
- return "<a id='$name' xml:id='$name'>$str</a>";
- }
-}
-
-
-%TokenToTargetMapping = (); # language:token -> link target
-%DefinedGrammars = (); # language -> full grammar text
-%BackpatchGrammarFiles = (); # file -> 1 (hash of files to fixup)
-
-sub do_cmd_token{
- local($_) = @_;
- my $token = next_argument();
- my $target = $TokenToTargetMapping{"$CURRENT_GRAMMAR:$token"};
- if ($token eq $CURRENT_TOKEN || $CURRENT_GRAMMAR eq '*') {
- # recursive definition or display-only productionlist
- return "$token";
- }
- if ($target eq '') {
- $target = "<pyGrammarToken><$CURRENT_GRAMMAR><$token>";
- if (! $BackpatchGrammarFiles{"$CURRENT_FILE"}) {
- print "Adding '$CURRENT_FILE' to back-patch list.\n";
- }
- $BackpatchGrammarFiles{"$CURRENT_FILE"} = 1;
- }
- return "<a class='grammartoken' href=\"$target\">$token</a>" . $_;
-}
-
-sub do_cmd_grammartoken{
- return do_cmd_token(@_);
-}
-
-sub do_env_productionlist{
- local($_) = @_;
- my $lang = next_optional_argument();
- my $filename = "grammar-$lang.txt";
- if ($lang eq '') {
- $filename = 'grammar.txt';
- }
- local($CURRENT_GRAMMAR) = $lang;
- $DefinedGrammars{$lang} .= $_;
- return ("<dl><dd class=\"grammar\">\n"
- . "<div class=\"productions\">\n"
- . "<table>\n"
- . translate_commands(translate_environments($_))
- . "</table>\n"
- . "</div>\n"
- . (($lang eq '*')
- ? ''
- : ("<a class=\"grammar-footer\"\n"
- . " href=\"$filename\" type=\"text/plain\"\n"
- . " >Download entire grammar as text.</a>\n"))
- . "</dd></dl>");
-}
-
-sub do_cmd_production{
- local($_) = @_;
- my $token = next_argument();
- my $defn = next_argument();
- my $lang = $CURRENT_GRAMMAR;
- local($CURRENT_TOKEN) = $token;
- if ($lang eq '*') {
- return ("<tr>\n"
- . " <td>$token</td>\n"
- . " <td>::=</td>\n"
- . " <td>"
- . translate_commands($defn)
- . "</td></tr>"
- . $_);
- }
- my $target;
- if ($lang eq '') {
- $target = "$CURRENT_FILE\#tok-$token";
- }
- else {
- $target = "$CURRENT_FILE\#tok-$lang-$token";
- }
- $TokenToTargetMapping{"$CURRENT_GRAMMAR:$token"} = $target;
- return ("<tr>\n"
- . " <td><a id='tok-$token' xml:id='tok-$token'>"
- . "$token</a></td>\n"
- . " <td>::=</td>\n"
- . " <td>"
- . translate_commands($defn)
- . "</td></tr>"
- . $_);
-}
-
-sub do_cmd_productioncont{
- local($_) = @_;
- my $defn = next_argument();
- $defn =~ s/^( +)/' ' x length $1/e;
- return ("<tr>\n"
- . " <td></td>\n"
- . " <td></td>\n"
- . " <td><code>"
- . translate_commands($defn)
- . "</code></td></tr>"
- . $_);
-}
-
-sub process_grammar_files(){
- my $lang;
- my $filename;
- local($_);
- print "process_grammar_files()\n";
- foreach $lang (keys %DefinedGrammars) {
- $filename = "grammar-$lang.txt";
- if ($lang eq '*') {
- next;
- }
- if ($lang eq '') {
- $filename = 'grammar.txt';
- }
- open(GRAMMAR, ">$filename") || die "\n$!\n";
- print GRAMMAR "##################################################\n";
- print GRAMMAR "# This file is only meant to be a guide, #\n";
- print GRAMMAR "# and differs in small ways from the real #\n";
- print GRAMMAR "# grammar. The exact reference is the file #\n";
- print GRAMMAR "# Grammar/Grammar distributed with the source. #\n";
- print GRAMMAR "##################################################\n";
- print GRAMMAR strip_grammar_markup($DefinedGrammars{$lang});
- close(GRAMMAR);
- print "Wrote grammar file $filename\n";
- }
- my $PATTERN = '<pyGrammarToken><([^>]*)><([^>]*)>';
- foreach $filename (keys %BackpatchGrammarFiles) {
- print "\nBack-patching grammar links in $filename\n";
- my $buffer;
- open(GRAMMAR, "<$filename") || die "\n$!\n";
- # read all of the file into the buffer
- sysread(GRAMMAR, $buffer, 1024*1024);
- close(GRAMMAR);
- while ($buffer =~ /$PATTERN/) {
- my($lang, $token) = ($1, $2);
- my $target = $TokenToTargetMapping{"$lang:$token"};
- my $source = "<pyGrammarToken><$lang><$token>";
- $buffer =~ s/$source/$target/g;
- }
- open(GRAMMAR, ">$filename") || die "\n$!\n";
- print GRAMMAR $buffer;
- close(GRAMMAR);
- }
-}
-
-sub strip_grammar_markup($){
- local($_) = @_;
- s/\\productioncont/ /g;
- s/\\production(<<\d+>>)(.+)\1/\n$2 ::= /g;
- s/\\token(<<\d+>>)(.+)\1/$2/g;
- s/\\e([^a-zA-Z])/\\$1/g;
- s/<<\d+>>//g;
- s/;SPMgt;/>/g;
- s/;SPMlt;/</g;
- s/;SPMquot;/\"/g;
- return $_;
-}
-
-
-$REFCOUNTS_LOADED = 0;
-
-sub load_refcounts(){
- $REFCOUNTS_LOADED = 1;
-
- my($myname, $mydir, $myext) = fileparse(__FILE__, '\..*');
- chop $mydir; # remove trailing '/'
- ($myname, $mydir, $myext) = fileparse($mydir, '\..*');
- chop $mydir; # remove trailing '/'
- $mydir = getcwd() . "$dd$mydir"
- unless $mydir =~ s|^/|/|;
- local $_;
- my $filename = "$mydir${dd}api${dd}refcounts.dat";
- open(REFCOUNT_FILE, "<$filename") || die "\n$!\n";
- print "[loading API refcount data]";
- while (<REFCOUNT_FILE>) {
- if (/([a-zA-Z0-9_]+):PyObject\*:([a-zA-Z0-9_]*):(0|[-+]1|null):(.*)$/) {
- my($func, $param, $count, $comment) = ($1, $2, $3, $4);
- #print "\n$func($param) --> $count";
- $REFCOUNTS{"$func:$param"} = $count;
- }
- }
-}
-
-sub get_refcount($$){
- my($func, $param) = @_;
- load_refcounts()
- unless $REFCOUNTS_LOADED;
- return $REFCOUNTS{"$func:$param"};
-}
-
-
-$TLSTART = '<span class="typelabel">';
-$TLEND = '</span> ';
-
-sub cfuncline_helper($$$){
- my($type, $name, $args) = @_;
- my $idx = make_str_index_entry(
- "<tt class=\"cfunction\">$name()</tt>" . get_indexsubitem());
- $idx =~ s/ \(.*\)//;
- $idx =~ s/\(\)//; # ???? - why both of these?
- $args =~ s/(\s|\*)([a-z_][a-z_0-9]*),/$1<var>$2<\/var>,/g;
- $args =~ s/(\s|\*)([a-z_][a-z_0-9]*)$/$1<var>$2<\/var>/s;
- return ('<table cellpadding="0" cellspacing="0"><tr valign="baseline">'
- . "<td><nobr>$type\ <b>$idx</b>(</nobr></td>"
- . "<td>$args)</td>"
- . '</tr></table>');
-}
-sub do_cmd_cfuncline{
- local($_) = @_;
- my $type = next_argument();
- my $name = next_argument();
- my $args = next_argument();
- my $siginfo = cfuncline_helper($type, $name, $args);
- return "<dt>$siginfo\n<dd>" . $_;
-}
-sub do_env_cfuncdesc{
- local($_) = @_;
- my $type = next_argument();
- my $name = next_argument();
- my $args = next_argument();
- my $siginfo = cfuncline_helper($type, $name, $args);
- my $result_rc = get_refcount($name, '');
- my $rcinfo = '';
- if ($result_rc eq '+1') {
- $rcinfo = 'New reference';
- }
- elsif ($result_rc eq '0') {
- $rcinfo = 'Borrowed reference';
- }
- elsif ($result_rc eq 'null') {
- $rcinfo = 'Always <tt class="constant">NULL</tt>';
- }
- if ($rcinfo ne '') {
- $rcinfo = ( "\n<div class=\"refcount-info\">"
- . "\n <span class=\"label\">Return value:</span>"
- . "\n <span class=\"value\">$rcinfo.</span>"
- . "\n</div>");
- }
- return "<dl><dt>$siginfo</dt>\n<dd>"
- . $rcinfo
- . $_
- . '</dd></dl>';
-}
-
-sub do_cmd_cmemberline{
- local($_) = @_;
- my $container = next_argument();
- my $type = next_argument();
- my $name = next_argument();
- my $idx = make_str_index_entry("<tt class=\"cmember\">$name</tt>"
- . " ($container member)");
- $idx =~ s/ \(.*\)//;
- return "<dt>$type <b>$idx</b></dt>\n<dd>"
- . $_;
-}
-sub do_env_cmemberdesc{
- local($_) = @_;
- my $container = next_argument();
- my $type = next_argument();
- my $name = next_argument();
- my $idx = make_str_index_entry("<tt class=\"cmember\">$name</tt>"
- . " ($container member)");
- $idx =~ s/ \(.*\)//;
- return "<dl><dt>$type <b>$idx</b></dt>\n<dd>"
- . $_
- . '</dl>';
-}
-
-sub do_env_csimplemacrodesc{
- local($_) = @_;
- my $name = next_argument();
- my $idx = make_str_index_entry("<tt class=\"macro\">$name</tt>");
- return "<dl><dt><b>$idx</b></dt>\n<dd>"
- . $_
- . '</dl>'
-}
-
-sub do_env_ctypedesc{
- local($_) = @_;
- my $index_name = next_optional_argument();
- my $type_name = next_argument();
- $index_name = $type_name
- unless $index_name;
- my($name, $aname, $ahref) = new_link_info();
- add_index_entry("<tt class=\"ctype\">$index_name</tt> (C type)", $ahref);
- return "<dl><dt><b><tt class=\"ctype\">$aname$type_name</a></tt></b></dt>"
- . "\n<dd>"
- . $_
- . '</dl>'
-}
-
-sub do_env_cvardesc{
- local($_) = @_;
- my $var_type = next_argument();
- my $var_name = next_argument();
- my $idx = make_str_index_entry("<tt class=\"cdata\">$var_name</tt>"
- . get_indexsubitem());
- $idx =~ s/ \(.*\)//;
- return "<dl><dt>$var_type <b>$idx</b></dt>\n"
- . '<dd>'
- . $_
- . '</dd></dl>';
-}
-
-sub convert_args($){
- local($IN_DESC_HANDLER) = 1;
- local($_) = @_;
- return translate_commands($_);
-}
-
-sub funcline_helper($$$){
- my($first, $idxitem, $arglist) = @_;
- return (($first ? '<dl>' : '')
- . '<dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">'
- . "\n <td><nobr><b>$idxitem</b>(</nobr></td>"
- . "\n <td><var>$arglist</var>)</td></tr></table></dt>\n<dd>");
-}
-
-sub do_env_funcdesc{
- local($_) = @_;
- my $function_name = next_argument();
- my $arg_list = convert_args(next_argument());
- my $idx = make_str_index_entry("<tt class=\"function\">$function_name()"
- . '</tt>'
- . get_indexsubitem());
- $idx =~ s/ \(.*\)//;
- $idx =~ s/\(\)<\/tt>/<\/tt>/;
- return funcline_helper(1, $idx, $arg_list) . $_ . '</dl>';
-}
-
-sub do_env_funcdescni{
- local($_) = @_;
- my $function_name = next_argument();
- my $arg_list = convert_args(next_argument());
- my $prefix = "<tt class=\"function\">$function_name</tt>";
- return funcline_helper(1, $prefix, $arg_list) . $_ . '</dl>';
-}
-
-sub do_cmd_funcline{
- local($_) = @_;
- my $function_name = next_argument();
- my $arg_list = convert_args(next_argument());
- my $prefix = "<tt class=\"function\">$function_name()</tt>";
- my $idx = make_str_index_entry($prefix . get_indexsubitem());
- $prefix =~ s/\(\)//;
-
- return funcline_helper(0, $prefix, $arg_list) . $_;
-}
-
-sub do_cmd_funclineni{
- local($_) = @_;
- my $function_name = next_argument();
- my $arg_list = convert_args(next_argument());
- my $prefix = "<tt class=\"function\">$function_name</tt>";
-
- return funcline_helper(0, $prefix, $arg_list) . $_;
-}
-
-# Change this flag to index the opcode entries. I don't think it's very
-# useful to index them, since they're only presented to describe the dis
-# module.
-#
-$INDEX_OPCODES = 0;
-
-sub do_env_opcodedesc{
- local($_) = @_;
- my $opcode_name = next_argument();
- my $arg_list = next_argument();
- my $idx;
- if ($INDEX_OPCODES) {
- $idx = make_str_index_entry("<tt class=\"opcode\">$opcode_name</tt>"
- . ' (byte code instruction)');
- $idx =~ s/ \(byte code instruction\)//;
- }
- else {
- $idx = "<tt class=\"opcode\">$opcode_name</tt>";
- }
- my $stuff = "<dl><dt><b>$idx</b>";
- if ($arg_list) {
- $stuff .= " <var>$arg_list</var>";
- }
- return $stuff . "</dt>\n<dd>" . $_ . '</dt></dl>';
-}
-
-sub do_env_datadesc{
- local($_) = @_;
- my $dataname = next_argument();
- my $idx = make_str_index_entry("<tt>$dataname</tt>" . get_indexsubitem());
- $idx =~ s/ \(.*\)//;
- return "<dl><dt><b>$idx</b></dt>\n<dd>"
- . $_
- . '</dd></dl>';
-}
-
-sub do_env_datadescni{
- local($_) = @_;
- my $idx = next_argument();
- if (! $STRING_INDEX_TT) {
- $idx = "<tt>$idx</tt>";
- }
- return "<dl><dt><b>$idx</b></dt>\n<dd>" . $_ . '</dd></dl>';
-}
-
-sub do_cmd_dataline{
- local($_) = @_;
- my $data_name = next_argument();
- my $idx = make_str_index_entry("<tt>$data_name</tt>" . get_indexsubitem());
- $idx =~ s/ \(.*\)//;
- return "<dt><b>$idx</b></dt><dd>" . $_;
-}
-
-sub do_cmd_datalineni{
- local($_) = @_;
- my $data_name = next_argument();
- return "<dt><b><tt>$data_name</tt></b></dt><dd>" . $_;
-}
-
-sub do_env_excdesc{
- local($_) = @_;
- my $excname = next_argument();
- my $idx = make_str_index_entry("<tt class=\"exception\">$excname</tt>");
- return ("<dl><dt><b>${TLSTART}exception$TLEND$idx</b></dt>"
- . "\n<dd>"
- . $_
- . '</dd></dl>');
-}
-
-sub do_env_fulllineitems{ return do_env_itemize(@_); }
-
-
-sub handle_classlike_descriptor($$){
- local($_, $what) = @_;
- $THIS_CLASS = next_argument();
- my $arg_list = convert_args(next_argument());
- $idx = make_str_index_entry(
- "<tt class=\"$what\">$THIS_CLASS</tt> ($what in $THIS_MODULE)" );
- $idx =~ s/ \(.*\)//;
- my $prefix = "$TLSTART$what$TLEND$idx";
- return funcline_helper(1, $prefix, $arg_list) . $_ . '</dl>';
-}
-
-sub do_env_classdesc{
- return handle_classlike_descriptor($_[0], "class");
-}
-
-sub do_env_classdescstar{
- local($_) = @_;
- $THIS_CLASS = next_argument();
- $idx = make_str_index_entry(
- "<tt class=\"class\">$THIS_CLASS</tt> (class in $THIS_MODULE)");
- $idx =~ s/ \(.*\)//;
- my $prefix = "${TLSTART}class$TLEND$idx";
- # Can't use funcline_helper() since there is no args list.
- return "<dl><dt><b>$prefix</b>\n<dd>" . $_ . '</dl>';
-}
-
-sub do_env_excclassdesc{
- return handle_classlike_descriptor($_[0], "exception");
-}
-
-
-sub do_env_methoddesc{
- local($_) = @_;
- my $class_name = next_optional_argument();
- $class_name = $THIS_CLASS
- unless $class_name;
- my $method = next_argument();
- my $arg_list = convert_args(next_argument());
- my $extra = '';
- if ($class_name) {
- $extra = " ($class_name method)";
- }
- my $idx = make_str_index_entry(
- "<tt class=\"method\">$method()</tt>$extra");
- $idx =~ s/ \(.*\)//;
- $idx =~ s/\(\)//;
- return funcline_helper(1, $idx, $arg_list) . $_ . '</dl>';
-}
-
-
-sub do_cmd_methodline{
- local($_) = @_;
- my $class_name = next_optional_argument();
- $class_name = $THIS_CLASS
- unless $class_name;
- my $method = next_argument();
- my $arg_list = convert_args(next_argument());
- my $extra = '';
- if ($class_name) {
- $extra = " ($class_name method)";
- }
- my $idx = make_str_index_entry(
- "<tt class=\"method\">$method()</tt>$extra");
- $idx =~ s/ \(.*\)//;
- $idx =~ s/\(\)//;
- return funcline_helper(0, $idx, $arg_list) . $_;
-}
-
-
-sub do_cmd_methodlineni{
- local($_) = @_;
- next_optional_argument();
- my $method = next_argument();
- my $arg_list = convert_args(next_argument());
- return funcline_helper(0, $method, $arg_list) . $_;
-}
-
-sub do_env_methoddescni{
- local($_) = @_;
- next_optional_argument();
- my $method = next_argument();
- my $arg_list = convert_args(next_argument());
- return funcline_helper(1, $method, $arg_list) . $_ . '</dl>';
-}
-
-
-sub do_env_memberdesc{
- local($_) = @_;
- my $class = next_optional_argument();
- my $member = next_argument();
- $class = $THIS_CLASS
- unless $class;
- my $extra = '';
- $extra = " ($class attribute)"
- if ($class ne '');
- my $idx = make_str_index_entry("<tt class=\"member\">$member</tt>$extra");
- $idx =~ s/ \(.*\)//;
- $idx =~ s/\(\)//;
- return "<dl><dt><b>$idx</b></dt>\n<dd>" . $_ . '</dl>';
-}
-
-
-sub do_cmd_memberline{
- local($_) = @_;
- my $class = next_optional_argument();
- my $member = next_argument();
- $class = $THIS_CLASS
- unless $class;
- my $extra = '';
- $extra = " ($class attribute)"
- if ($class ne '');
- my $idx = make_str_index_entry("<tt class=\"member\">$member</tt>$extra");
- $idx =~ s/ \(.*\)//;
- $idx =~ s/\(\)//;
- return "<dt><b>$idx</b></dt><dd>" . $_;
-}
-
-
-sub do_env_memberdescni{
- local($_) = @_;
- next_optional_argument();
- my $member = next_argument();
- return "<dl><dt><b><tt class=\"member\">$member</tt></b></dt>\n<dd>"
- . $_
- . '</dd></dl>';
-}
-
-
-sub do_cmd_memberlineni{
- local($_) = @_;
- next_optional_argument();
- my $member = next_argument();
- return "<dt><b><tt class=\"member\">$member</tt></b></dt>\n<dd>" . $_;
-}
-
-
-# For tables, we include a class on every cell to allow the CSS to set
-# the text-align property; this is because support for styling columns
-# via the <col> element appears nearly non-existant on even the latest
-# browsers (Mozilla 1.7 is stable at the time of this writing).
-# Hopefully this can be improved as browsers evolve.
-
-@col_aligns = ('<td>', '<td>', '<td>', '<td>', '<td>');
-
-%FontConversions = ('cdata' => 'tt class="cdata"',
- 'character' => 'tt class="character"',
- 'class' => 'tt class="class"',
- 'command' => 'code',
- 'constant' => 'tt class="constant"',
- 'exception' => 'tt class="exception"',
- 'file' => 'tt class="file"',
- 'filenq' => 'tt class="file"',
- 'kbd' => 'kbd',
- 'member' => 'tt class="member"',
- 'programopt' => 'b',
- 'textrm' => '',
- );
-
-sub fix_font($){
- # do a little magic on a font name to get the right behavior in the first
- # column of the output table
- my $font = $_[0];
- if (defined $FontConversions{$font}) {
- $font = $FontConversions{$font};
- }
- return $font;
-}
-
-sub figure_column_alignment($){
- my $a = $_[0];
- if (!defined $a) {
- return '';
- }
- my $mark = substr($a, 0, 1);
- my $r = '';
- if ($mark eq 'c')
- { $r = ' class="center"'; }
- elsif ($mark eq 'r')
- { $r = ' class="right" '; }
- elsif ($mark eq 'l')
- { $r = ' class="left" '; }
- elsif ($mark eq 'p')
- { $r = ' class="left" '; }
- return $r;
-}
-
-sub setup_column_alignments($){
- local($_) = @_;
- my($s1, $s2, $s3, $s4, $s5) = split(/[|]/,$_);
- my $a1 = figure_column_alignment($s1);
- my $a2 = figure_column_alignment($s2);
- my $a3 = figure_column_alignment($s3);
- my $a4 = figure_column_alignment($s4);
- my $a5 = figure_column_alignment($s5);
- $col_aligns[0] = "<td$a1 valign=\"baseline\">";
- $col_aligns[1] = "<td$a2>";
- $col_aligns[2] = "<td$a3>";
- $col_aligns[3] = "<td$a4>";
- $col_aligns[4] = "<td$a5>";
- # return the aligned header start tags
- return ("<th$a1>", "<th$a2>", "<th$a3>", "<th$a4>", "<th$a5>");
-}
-
-sub get_table_col1_fonts(){
- my $font = $globals{'lineifont'};
- my($sfont, $efont) = ('', '');
- if ($font) {
- $sfont = "<$font>";
- $efont = "</$font>";
- $efont =~ s/ .*>/>/;
- }
- return ($sfont, $efont);
-}
-
-sub do_env_tableii{
- local($_) = @_;
- my $arg = next_argument();
- my($th1, $th2, $th3, $th4, $th5) = setup_column_alignments($arg);
- my $font = fix_font(next_argument());
- my $h1 = next_argument();
- my $h2 = next_argument();
- s/[\s\n]+//;
- $globals{'lineifont'} = $font;
- my $a1 = $col_aligns[0];
- my $a2 = $col_aligns[1];
- s/\\lineii</\\lineii[$a1|$a2]</g;
- return '<div class="center"><table class="realtable">'
- . "\n <thead>"
- . "\n <tr>"
- . "\n $th1$h1</th>"
- . "\n $th2$h2</th>"
- . "\n </tr>"
- . "\n </thead>"
- . "\n <tbody>"
- . $_
- . "\n </tbody>"
- . "\n</table></div>";
-}
-
-sub do_env_longtableii{
- return do_env_tableii(@_);
-}
-
-sub do_cmd_lineii{
- local($_) = @_;
- my $aligns = next_optional_argument();
- my $c1 = next_argument();
- my $c2 = next_argument();
- s/[\s\n]+//;
- my($sfont, $efont) = get_table_col1_fonts();
- my($c1align, $c2align) = split('\|', $aligns);
- return "\n <tr>$c1align$sfont$c1$efont</td>\n"
- . " $c2align$c2</td></tr>"
- . $_;
-}
-
-sub do_env_tableiii{
- local($_) = @_;
- my $arg = next_argument();
- my($th1, $th2, $th3, $th4, $th5) = setup_column_alignments($arg);
- my $font = fix_font(next_argument());
- my $h1 = next_argument();
- my $h2 = next_argument();
- my $h3 = next_argument();
- s/[\s\n]+//;
- $globals{'lineifont'} = $font;
- my $a1 = $col_aligns[0];
- my $a2 = $col_aligns[1];
- my $a3 = $col_aligns[2];
- s/\\lineiii</\\lineiii[$a1|$a2|$a3]</g;
- return '<div class="center"><table class="realtable">'
- . "\n <thead>"
- . "\n <tr>"
- . "\n $th1$h1</th>"
- . "\n $th2$h2</th>"
- . "\n $th3$h3</th>"
- . "\n </tr>"
- . "\n </thead>"
- . "\n <tbody>"
- . $_
- . "\n </tbody>"
- . "\n</table></div>";
-}
-
-sub do_env_longtableiii{
- return do_env_tableiii(@_);
-}
-
-sub do_cmd_lineiii{
- local($_) = @_;
- my $aligns = next_optional_argument();
- my $c1 = next_argument();
- my $c2 = next_argument();
- my $c3 = next_argument();
- s/[\s\n]+//;
- my($sfont, $efont) = get_table_col1_fonts();
- my($c1align, $c2align, $c3align) = split('\|', $aligns);
- return "\n <tr>$c1align$sfont$c1$efont</td>\n"
- . " $c2align$c2</td>\n"
- . " $c3align$c3</td></tr>"
- . $_;
-}
-
-sub do_env_tableiv{
- local($_) = @_;
- my $arg = next_argument();
- my($th1, $th2, $th3, $th4, $th5) = setup_column_alignments($arg);
- my $font = fix_font(next_argument());
- my $h1 = next_argument();
- my $h2 = next_argument();
- my $h3 = next_argument();
- my $h4 = next_argument();
- s/[\s\n]+//;
- $globals{'lineifont'} = $font;
- my $a1 = $col_aligns[0];
- my $a2 = $col_aligns[1];
- my $a3 = $col_aligns[2];
- my $a4 = $col_aligns[3];
- s/\\lineiv</\\lineiv[$a1|$a2|$a3|$a4]</g;
- return '<div class="center"><table class="realtable">'
- . "\n <thead>"
- . "\n <tr>"
- . "\n $th1$h1</th>"
- . "\n $th2$h2</th>"
- . "\n $th3$h3</th>"
- . "\n $th4$h4</th>"
- . "\n </tr>"
- . "\n </thead>"
- . "\n <tbody>"
- . $_
- . "\n </tbody>"
- . "\n</table></div>";
-}
-
-sub do_env_longtableiv{
- return do_env_tableiv(@_);
-}
-
-sub do_cmd_lineiv{
- local($_) = @_;
- my $aligns = next_optional_argument();
- my $c1 = next_argument();
- my $c2 = next_argument();
- my $c3 = next_argument();
- my $c4 = next_argument();
- s/[\s\n]+//;
- my($sfont, $efont) = get_table_col1_fonts();
- my($c1align, $c2align, $c3align, $c4align) = split('\|', $aligns);
- return "\n <tr>$c1align$sfont$c1$efont</td>\n"
- . " $c2align$c2</td>\n"
- . " $c3align$c3</td>\n"
- . " $c4align$c4</td></tr>"
- . $_;
-}
-
-sub do_env_tablev{
- local($_) = @_;
- my $arg = next_argument();
- my($th1, $th2, $th3, $th4, $th5) = setup_column_alignments($arg);
- my $font = fix_font(next_argument());
- my $h1 = next_argument();
- my $h2 = next_argument();
- my $h3 = next_argument();
- my $h4 = next_argument();
- my $h5 = next_argument();
- s/[\s\n]+//;
- $globals{'lineifont'} = $font;
- my $a1 = $col_aligns[0];
- my $a2 = $col_aligns[1];
- my $a3 = $col_aligns[2];
- my $a4 = $col_aligns[3];
- my $a5 = $col_aligns[4];
- s/\\linev</\\linev[$a1|$a2|$a3|$a4|$a5]</g;
- return '<div class="center"><table class="realtable">'
- . "\n <thead>"
- . "\n <tr>"
- . "\n $th1$h1</th>"
- . "\n $th2$h2</th>"
- . "\n $th3$h3</th>"
- . "\n $th4$h4</th>"
- . "\n $th5$h5</th>"
- . "\n </tr>"
- . "\n </thead>"
- . "\n <tbody>"
- . $_
- . "\n </tbody>"
- . "\n</table></div>";
-}
-
-sub do_env_longtablev{
- return do_env_tablev(@_);
-}
-
-sub do_cmd_linev{
- local($_) = @_;
- my $aligns = next_optional_argument();
- my $c1 = next_argument();
- my $c2 = next_argument();
- my $c3 = next_argument();
- my $c4 = next_argument();
- my $c5 = next_argument();
- s/[\s\n]+//;
- my($sfont, $efont) = get_table_col1_fonts();
- my($c1align, $c2align, $c3align, $c4align, $c5align) = split('\|',$aligns);
- return "\n <tr>$c1align$sfont$c1$efont</td>\n"
- . " $c2align$c2</td>\n"
- . " $c3align$c3</td>\n"
- . " $c4align$c4</td>\n"
- . " $c5align$c5</td></tr>"
- . $_;
-}
-
-
-# These can be used to control the title page appearance;
-# they need a little bit of documentation.
-#
-# If $TITLE_PAGE_GRAPHIC is set, it should be the name of a file in the
-# $ICONSERVER directory, or include path information (other than "./"). The
-# default image type will be assumed if an extension is not provided.
-#
-# If specified, the "title page" will contain two colums: one containing the
-# title/author/etc., and the other containing the graphic. Use the other
-# four variables listed here to control specific details of the layout; all
-# are optional.
-#
-# $TITLE_PAGE_GRAPHIC = "my-company-logo";
-# $TITLE_PAGE_GRAPHIC_COLWIDTH = "30%";
-# $TITLE_PAGE_GRAPHIC_WIDTH = 150;
-# $TITLE_PAGE_GRAPHIC_HEIGHT = 150;
-# $TITLE_PAGE_GRAPHIC_ON_RIGHT = 0;
-
-sub make_my_titlepage(){
- my $the_title = "";
- if ($t_title) {
- $the_title .= "\n<h1>$t_title</h1>";
- }
- else {
- write_warnings("\nThis document has no title.");
- }
- if ($t_author) {
- if ($t_authorURL) {
- my $href = translate_commands($t_authorURL);
- $href = make_named_href('author', $href,
- "<b><font size=\"+2\">$t_author"
- . '</font></b>');
- $the_title .= "\n<p>$href</p>";
- }
- else {
- $the_title .= ("\n<p><b><font size=\"+2\">$t_author"
- . '</font></b></p>');
- }
- }
- else {
- write_warnings("\nThere is no author for this document.");
- }
- if ($t_institute) {
- $the_title .= "\n<p>$t_institute</p>";
- }
- if ($DEVELOPER_ADDRESS) {
- $the_title .= "\n<p>$DEVELOPER_ADDRESS</p>";
- }
- if ($t_affil) {
- $the_title .= "\n<p><i>$t_affil</i></p>";
- }
- if ($t_date) {
- $the_title .= "\n<p>";
- if ($PACKAGE_VERSION) {
- $the_title .= ('<strong>Release '
- . "$PACKAGE_VERSION$RELEASE_INFO</strong><br />\n");
- }
- $the_title .= "<strong>$t_date</strong></p>"
- }
- if ($t_address) {
- $the_title .= "\n<p>$t_address</p>";
- }
- else {
- $the_title .= "\n<p></p>";
- }
- if ($t_email) {
- $the_title .= "\n<p>$t_email</p>";
- }
- return $the_title;
-}
-
-sub make_my_titlegraphic(){
- my $filename = make_icon_filename($TITLE_PAGE_GRAPHIC);
- my $graphic = "<td class=\"titlegraphic\"";
- $graphic .= " width=\"$TITLE_PAGE_GRAPHIC_COLWIDTH\""
- if ($TITLE_PAGE_GRAPHIC_COLWIDTH);
- $graphic .= "><img";
- $graphic .= " width=\"$TITLE_PAGE_GRAPHIC_WIDTH\""
- if ($TITLE_PAGE_GRAPHIC_WIDTH);
- $graphic .= " height=\"$TITLE_PAGE_GRAPHIC_HEIGHT\""
- if ($TITLE_PAGE_GRAPHIC_HEIGHT);
- $graphic .= "\n src=\"$filename\" /></td>\n";
- return $graphic;
-}
-
-sub do_cmd_maketitle{
- local($_) = @_;
- my $the_title = "\n";
- if ($EXTERNAL_UP_LINK) {
- # This generates a <link> element in the wrong place (the
- # body), but I don't see any other way to get this generated
- # at all. Browsers like Mozilla, that support navigation
- # links, can make use of this.
- $the_title .= ("<link rel='up' href='$EXTERNAL_UP_LINK'"
- . ($EXTERNAL_UP_TITLE
- ? " title='$EXTERNAL_UP_TITLE'" : '')
- . " />\n");
- }
- $the_title .= '<div class="titlepage">';
- if ($TITLE_PAGE_GRAPHIC) {
- if ($TITLE_PAGE_GRAPHIC_ON_RIGHT) {
- $the_title .= ("\n<table border=\"0\" width=\"100%\">"
- . "<tr align=\"right\">\n<td>"
- . make_my_titlepage()
- . "</td>\n"
- . make_my_titlegraphic()
- . "</tr>\n</table>");
- }
- else {
- $the_title .= ("\n<table border=\"0\" width=\"100%\"><tr>\n"
- . make_my_titlegraphic()
- . "<td>"
- . make_my_titlepage()
- . "</td></tr>\n</table>");
- }
- }
- else {
- $the_title .= ("\n<div class='center'>"
- . make_my_titlepage()
- . "\n</div>");
- }
- $the_title .= "\n</div>";
- return $the_title . $_;
-}
-
-
-#
-# Module synopsis support
-#
-
-require SynopsisTable;
-
-sub get_chapter_id(){
- my $id = do_cmd_thechapter('');
- $id =~ s/<SPAN CLASS="arabic">(\d+)<\/SPAN>/$1/;
- $id =~ s/\.//;
- return $id;
-}
-
-# 'chapter' => 'SynopsisTable instance'
-%ModuleSynopses = ();
-
-sub get_synopsis_table($){
- my $chap = $_[0];
- my $key;
- foreach $key (keys %ModuleSynopses) {
- if ($key eq $chap) {
- return $ModuleSynopses{$chap};
- }
- }
- my $st = SynopsisTable->new();
- $ModuleSynopses{$chap} = $st;
- return $st;
-}
-
-sub do_cmd_moduleauthor{
- local($_) = @_;
- next_argument();
- next_argument();
- return $_;
-}
-
-sub do_cmd_sectionauthor{
- local($_) = @_;
- next_argument();
- next_argument();
- return $_;
-}
-
-sub do_cmd_declaremodule{
- local($_) = @_;
- my $key = next_optional_argument();
- my $type = next_argument();
- my $name = next_argument();
- my $st = get_synopsis_table(get_chapter_id());
- #
- $key = $name unless $key;
- $type = 'built-in' if $type eq 'builtin';
- $st->declare($name, $key, $type);
- define_module($type, $name);
- return anchor_label("module-$key",$CURRENT_FILE,$_)
-}
-
-sub do_cmd_modulesynopsis{
- local($_) = @_;
- my $st = get_synopsis_table(get_chapter_id());
- $st->set_synopsis($THIS_MODULE, translate_commands(next_argument()));
- return $_;
-}
-
-sub do_cmd_localmoduletable{
- local($_) = @_;
- my $chap = get_chapter_id();
- my $st = get_synopsis_table($chap);
- $st->set_file("$CURRENT_FILE");
- return "<tex2html-localmoduletable><$chap>\\tableofchildlinks[off]" . $_;
-}
-
-sub process_all_localmoduletables(){
- my $key;
- foreach $key (keys %ModuleSynopses) {
- my $st = $ModuleSynopses{$key};
- my $file = $st->get_file();
- if ($file) {
- process_localmoduletables_in_file($file);
- }
- else {
- print "\nsynopsis table $key has no file association\n";
- }
- }
-}
-
-sub process_localmoduletables_in_file($){
- my $file = $_[0];
- open(MYFILE, "<$file");
- local($_);
- sysread(MYFILE, $_, 1024*1024);
- close(MYFILE);
- # need to get contents of file in $_
- while (/<tex2html-localmoduletable><(\d+)>/) {
- my $match = $&;
- my $chap = $1;
- my $st = get_synopsis_table($chap);
- my $data = $st->tohtml();
- s/$match/$data/;
- }
- open(MYFILE,">$file");
- print MYFILE $_;
- close(MYFILE);
-}
-sub process_python_state(){
- process_all_localmoduletables();
- process_grammar_files();
-}
-
-
-#
-# "See also:" -- references placed at the end of a \section
-#
-
-sub do_env_seealso{
- return ("<div class=\"seealso\">\n "
- . "<p class=\"heading\">See Also:</p>\n"
- . $_[0]
- . '</div>');
-}
-
-sub do_env_seealsostar{
- return ("<div class=\"seealso-simple\">\n "
- . $_[0]
- . '</div>');
-}
-
-sub do_cmd_seemodule{
- # Insert the right magic to jump to the module definition. This should
- # work most of the time, at least for repeat builds....
- local($_) = @_;
- my $key = next_optional_argument();
- my $module = next_argument();
- my $text = next_argument();
- my $period = '.';
- $key = $module
- unless $key;
- if ($text =~ /\.$/) {
- $period = '';
- }
- return ('<dl compact="compact" class="seemodule">'
- . "\n <dt>Module <b><tt class=\"module\">"
- . "<a href=\"module-$key.html\">$module</a></tt>:</b>"
- . "\n <dd>$text$period\n </dl>"
- . $_);
-}
-
-sub strip_html_markup($){
- my $str = $_[0];
- my $s = "$str";
- $s =~ s/<[a-zA-Z0-9]+(\s+[a-zA-Z0-9]+(\s*=\s*(\'[^\']*\'|\"[^\"]*\"|[a-zA-Z0-9]+))?)*\s*>//g;
- $s =~ s/<\/[a-zA-Z0-9]+>//g;
- return $s;
-}
-
-sub handle_rfclike_reference($$$){
- local($_, $what, $format) = @_;
- my $rfcnum = next_argument();
- my $title = next_argument();
- my $text = next_argument();
- my $url = get_rfc_url($rfcnum, $format);
- my $icon = get_link_icon($url);
- my $attrtitle = strip_html_markup($title);
- return '<dl compact="compact" class="seerfc">'
- . "\n <dt><a href=\"$url\""
- . "\n title=\"$attrtitle\""
- . "\n >$what $rfcnum, <em>$title</em>$icon</a>"
- . "\n <dd>$text\n </dl>"
- . $_;
-}
-
-sub do_cmd_seepep{
- return handle_rfclike_reference($_[0], "PEP", $PEP_FORMAT);
-}
-
-sub do_cmd_seerfc{
- # XXX Would be nice to add links to the text/plain and PDF versions.
- return handle_rfclike_reference($_[0], "RFC", $RFC_FORMAT);
-}
-
-sub do_cmd_seetitle{
- local($_) = @_;
- my $url = next_optional_argument();
- my $title = next_argument();
- my $text = next_argument();
- if ($url) {
- my $icon = get_link_icon($url);
- return '<dl compact="compact" class="seetitle">'
- . "\n <dt><em class=\"citetitle\"><a href=\"$url\""
- . "\n >$title$icon</a></em></dt>"
- . "\n <dd>$text</dd>\n </dl>"
- . $_;
- }
- return '<dl compact="compact" class="seetitle">'
- . "\n <dt><em class=\"citetitle\""
- . "\n >$title</em></dt>"
- . "\n <dd>$text</dd>\n </dl>"
- . $_;
-}
-
-sub do_cmd_seelink{
- local($_) = @_;
- my $url = next_argument();
- my $linktext = next_argument();
- my $text = next_argument();
- my $icon = get_link_icon($url);
- return '<dl compact="compact" class="seeurl">'
- . "\n <dt><a href='$url'"
- . "\n >$linktext$icon</a></dt>"
- . "\n <dd>$text</dd>\n </dl>"
- . $_;
-}
-
-sub do_cmd_seeurl{
- local($_) = @_;
- my $url = next_argument();
- my $text = next_argument();
- my $icon = get_link_icon($url);
- return '<dl compact="compact" class="seeurl">'
- . "\n <dt><a href=\"$url\""
- . "\n class=\"url\">$url$icon</a></dt>"
- . "\n <dd>$text</dd>\n </dl>"
- . $_;
-}
-
-sub do_cmd_seetext{
- local($_) = @_;
- my $content = next_argument();
- return '<div class="seetext"><p>' . $content . '</p></div>' . $_;
-}
-
-
-#
-# Definition list support.
-#
-
-sub do_env_definitions{
- return '<dl class="definitions">' . $_[0] . "</dl>\n";
-}
-
-sub do_cmd_term{
- local($_) = @_;
- my $term = next_argument();
- my($name, $aname, $ahref) = new_link_info();
- # could easily add an index entry here...
- return "<dt><b>$aname" . $term . "</a></b></dt>\n<dd>" . $_;
-}
-
-
-# Commands listed here have process-order dependencies; these often
-# are related to indexing operations.
-# XXX Not sure why funclineni, methodlineni, and samp are here.
-#
-process_commands_wrap_deferred(<<_RAW_ARG_DEFERRED_CMDS_);
-declaremodule # [] # {} # {}
-funcline # {} # {}
-funclineni # {} # {}
-memberline # [] # {}
-methodline # [] # {} # {}
-methodlineni # [] # {} # {}
-modulesynopsis # {}
-bifuncindex # {}
-exindex # {}
-indexii # {} # {}
-indexiii # {} # {} # {}
-indexiv # {} # {} # {} # {}
-kwindex # {}
-obindex # {}
-opindex # {}
-stindex # {}
-platform # {}
-samp # {}
-setindexsubitem # {}
-withsubitem # {} # {}
-_RAW_ARG_DEFERRED_CMDS_
-
-
-$alltt_start = '<div class="verbatim"><pre>';
-$alltt_end = '</pre></div>';
-
-sub do_env_alltt{
- local ($_) = @_;
- local($closures,$reopens,@open_block_tags);
-
- # get the tag-strings for all open tags
- local(@keep_open_tags) = @$open_tags_R;
- ($closures,$reopens) = &preserve_open_tags() if (@$open_tags_R);
-
- # get the tags for text-level tags only
- $open_tags_R = [ @keep_open_tags ];
- local($local_closures, $local_reopens);
- ($local_closures, $local_reopens,@open_block_tags)
- = &preserve_open_block_tags
- if (@$open_tags_R);
-
- $open_tags_R = [ @open_block_tags ];
-
- do {
- local($open_tags_R) = [ @open_block_tags ];
- local(@save_open_tags) = ();
-
- local($cnt) = ++$global{'max_id'};
- $_ = join('',"$O$cnt$C\\tt$O", ++$global{'max_id'}, $C
- , $_ , $O, $global{'max_id'}, "$C$O$cnt$C");
-
- $_ = &translate_environments($_);
- $_ = &translate_commands($_) if (/\\/);
-
- # remove spurious <BR> someone sticks in; not sure where they
- # actually come from
- # XXX the replacement space is there to accomodate something
- # broken that inserts a space in front of the first line of
- # the environment
- s/<BR>/ /gi;
-
- $_ = join('', $closures, $alltt_start, $local_reopens
- , $_
- , &balance_tags() #, $local_closures
- , $alltt_end, $reopens);
- undef $open_tags_R; undef @save_open_tags;
- };
- $open_tags_R = [ @keep_open_tags ];
- return codetext($_);
-}
-
-# List of all filenames produced by do_cmd_verbatiminput()
-%VerbatimFiles = ();
-@VerbatimOutputs = ();
-
-sub get_verbatim_output_name($){
- my $file = $_[0];
- #
- # Re-write the source filename to always use a .txt extension
- # so that Web servers will present it as text/plain. This is
- # needed since there is no other even moderately reliable way
- # to get the right Content-Type header on text files for
- # servers which we can't configure (like python.org mirrors).
- #
- if (defined $VerbatimFiles{$file}) {
- # We've seen this one before; re-use the same output file.
- return $VerbatimFiles{$file};
- }
- my($srcname, $srcdir, $srcext) = fileparse($file, '\..*');
- $filename = "$srcname.txt";
- #
- # We need to determine if our default filename is already
- # being used, and find a new one it it is. If the name is in
- # used, this algorithm will first attempt to include the
- # source extension as part of the name, and if that is also in
- # use (if the same file is included multiple times, or if
- # another source file has that as the base name), a counter is
- # used instead.
- #
- my $found = 1;
- FIND:
- while ($found) {
- foreach $fn (@VerbatimOutputs) {
- if ($fn eq $filename) {
- if ($found == 1) {
- $srcext =~ s/^[.]//; # Remove '.' from extension
- $filename = "$srcname-$srcext.txt";
- }
- else {
- $filename = "$srcname-$found.txt";
- }
- ++$found;
- next FIND;
- }
- }
- $found = 0;
- }
- push @VerbatimOutputs, $filename;
- $VerbatimFiles{$file} = $filename;
- return $filename;
-}
-
-sub do_cmd_verbatiminput{
- local($_) = @_;
- my $fname = next_argument();
- my $file;
- my $found = 0;
- my $texpath;
- # Search TEXINPUTS for the input file, the way we're supposed to:
- foreach $texpath (split /$envkey/, $TEXINPUTS) {
- $file = "$texpath$dd$fname";
- last if ($found = (-f $file));
- }
- my $filename = '';
- my $text;
- if ($found) {
- open(MYFILE, "<$file") || die "\n$!\n";
- read(MYFILE, $text, 1024*1024);
- close(MYFILE);
- $filename = get_verbatim_output_name($file);
- # Now that we have a filename, write it out.
- open(MYFILE, ">$filename");
- print MYFILE $text;
- close(MYFILE);
- #
- # These rewrites convert the raw text to something that will
- # be properly visible as HTML and also will pass through the
- # vagaries of conversion through LaTeX2HTML. The order in
- # which the specific rewrites are performed is significant.
- #
- $text =~ s/\&/\&/g;
- # These need to happen before the normal < and > re-writes,
- # since we need to avoid LaTeX2HTML's attempt to perform
- # ligature processing without regard to context (since it
- # doesn't have font information).
- $text =~ s/--/-&\#45;/g;
- $text =~ s/<</\<\&\#60;/g;
- $text =~ s/>>/\>\&\#62;/g;
- # Just normal re-writes...
- $text =~ s/</\</g;
- $text =~ s/>/\>/g;
- # These last isn't needed for the HTML, but is needed to get
- # past LaTeX2HTML processing TeX macros. We use \ instead
- # of / since many browsers don't support that.
- $text =~ s/\\/\&\#92;/g;
- }
- else {
- return '<b>Could not locate requested file <i>$fname</i>!</b>\n';
- }
- my $note = 'Download as text.';
- if ($file ne $filename) {
- $note = ('Download as text (original file name: <span class="file">'
- . $fname
- . '</span>).');
- }
- return ("<div class=\"verbatim\">\n<pre>"
- . $text
- . "</pre>\n<div class=\"footer\">\n"
- . "<a href=\"$filename\" type=\"text/plain\""
- . ">$note</a>"
- . "\n</div></div>"
- . $_);
-}
-
-1; # This must be the last line
diff --git a/Doc/python-docs.txt b/Doc/python-docs.txt
deleted file mode 100644
index bf475b6..0000000
--- a/Doc/python-docs.txt
+++ /dev/null
@@ -1,183 +0,0 @@
-This message is being sent in response to your message to the Python
-documentation maintainers (docs@python.org). Your message will
-be handled by a human, but this message serves to answer the most
-common questions sent to this address.
-
-You will only receive this message if it has not been sent to you for
-at least three months.
-
-If your question is answered below, you may not receive an additional
-message from the documentation maintainers. If you feel the answers
-below are not sufficient and you do not receive an additional response
-within a week, please do send a note letting us know that your
-question has not been properly answered, and be specific regarding
-what additional information you are looking for.
-
-
- -Fred
-
-
-Frequently Asked Questions about the Python Documentation
----------------------------------------------------------
-
- 1. Can I download HTML/PDF/PostScript versions of the docs?
- 2. Where can I download Python?
- 3. I can't unpack a downloaded copy on Windows; what should I do?
- 4. I can't unpack a downloaded copy on Mac OS; what should I do?
- 5. What can I use Python for?
- 6. How do I use module/function/whatever XXX?
- 7. What about JPython?
- 8. I found a bug in the documentation, who should I tell?
- 9. Can I get an algorithm to do THIS in language THAT?
- 10. How do I decode an XXX file from my email on a YYY computer?
- 11. Acrobat Reader won't print the PDF. What's wrong?
- 12. Where can I find documentation in my native language?
- 13. Why is Python installed on my computer?
-
-
-Answers to the Questions
-------------------------
-
- 1. Can I download HTML/PDF/PostScript/<other> versions of the docs?
-
- Yes. These are available via the Web and traditional FTP. For
- Web access to the latest version, see:
-
- http://www.python.org/doc/
-
- For FTP access to the latest version and archives of previous
- versions, see:
-
- ftp.python.org:/pub/python/doc/
-
- 2. Where can I download Python?
-
- You can get Python in source form and as a Windows installer
- from the main Python website. You can also find information
- about pre-built packages for other platforms there as well.
-
- Downloading information at the website is at the URL:
-
- http://www.python.org/download/
-
- The sources and Windows installer can be downloaded from the FTP
- site as well:
-
- ftp://ftp.python.org/pub/python/
-
- 3. I can't unpack a downloaded archive on Windows; what should I do?
-
- Make sure the archive was saved with the .tgz extension; you may
- need to watch carefully when telling the browser where to save
- the file, as the default may change the extension to .tar or
- even .exe.
-
- Once you're sure the file has the right extension, use a recent
- version of WinZip to upack the file (version 7.0 works). Get
- WinZip from:
-
- http://www.winzip.com/
-
- 4. I can't unpack a downloaded archive on Mac OS; what should I do?
-
- Stuffit Expander 4.5 (and probably other versions) cannot handle
- the "tar" archive, although it can decompress it from the .tgz
- file. Expander Enhancer, which you have to pay for, can handle
- the tar archive.
-
- 5. What can I use Python for?
-
- Python is a general purpose programming language. See the
- Python home page at http://www.python.org/ for more information;
- introductory material is available at:
-
- http://www.python.org/doc/Intros.html
-
- 6. How do I use module/function/whatever XXX?
-
- Start by reading the documentation for XXX. If the
- documentation doesn't make sense or seems incomplete, please
- file a specific bug report to docs@python.org (the
- address you sent your question to). Otherwise, you probably
- sent your question to the wrong place (which does not preclude
- an answer, if I know it).
-
- If you're looking for examples or tutorial information on how to
- use a particular Python library component, check the Demo/
- directory of the source distribution or Windows installation;
- there might be an example. If that doesn't help, point your Web
- browser to http://www.python.org/doc/ and look around; there may
- be a link to some interesting examples online. After that, try
- searching the Python Web site at http://www.python.org/search/.
-
- If your question still hasn't been answered, you may send your
- query to the Python newsgroup (comp.lang.python) or the mailing
- list (see http://www.python.org/mailman/listinfo/python-list).
- If you'd rather not send you message to a public forum, you can
- try sending it to python-help@python.org. (This is typically
- slower than sending your question to the public list, however.)
-
- 7. What about Jython and JPython?
-
- If your question is specific to Jython or JPython, you should
- consult the Jython website at:
-
- http://www.jython.org/
-
- Chances are very good that the person who answers questions
- posted to docs@python.org doesn't use Jython very often,
- and won't be able to give you a meaningful answer beyond "Look
- at the Jython website." Sorry, I don't have *all* the answers!
-
- 8. I found a bug in the documentation, who should I tell?
-
- If you're reading this, you've found the right address! Send
- all documentation bug reports to docs@python.org. If
- you prefer to use a Web-based reporting mechanism, you can use
- the bug database at http://www.python.org/python-bugs/.
-
- 9. Can I get an algorithm to do THIS in language THAT?
-
- If THAT is Python, look in the standard library. If THAT isn't
- Python, use your favorite Internet search engine.
-
- 10. How do I decode an XXX file from my email on a YYY computer?
-
- I really, honestly do not know. I don't even know why this
- question gets asked here. Since I don't have a YYY computer,
- I couldn't even try a few things out for you.
-
- 11. Acrobat Reader won't print the PDF. What's wrong?
-
- Adobe has reportedly admitted that there is a bug in Acrobat Reader
- 5.0 which causes it not to print at least some PDF files
- generated by pdfTeX. This software is used to produce the PDF
- version of the Python documentation, and our documents
- definately trigger this bug in Acrobat Reader. To print the PDF
- files, use Acrobat Reader 4.x, ghostscript, or xpdf.
-
- Information on ghostscript can be found at:
-
- http://www.ghostscript.com/
-
- Information on xpdf can be found at:
-
- http://www.foolabs.com/xpdf/
-
- 12. Where can I find documentation in my native language?
-
- There is a lot of contributed documentation in languages other
- than English. Some of the documents are translations of English
- documents, and others were originally authored in other
- languages. If we know about it, it will be listed at:
-
- http://www.python.org/doc/NonEnglish.html
-
- 13. Why is Python installed on my computer?
-
- We're increasingly seeing Python being installed on computers
- as delivered by vendors. For more information on why, and
- whether it's safe to remove, see the "Why is Python Installed on
- my Computer?" FAQ, found at:
-
- http://www.python.org/doc/faq/installed/
diff --git a/Doc/ref/ref.tex b/Doc/ref/ref.tex
deleted file mode 100644
index 03c0acf..0000000
--- a/Doc/ref/ref.tex
+++ /dev/null
@@ -1,68 +0,0 @@
-\documentclass{manual}
-
-\title{Python Reference Manual}
-
-\input{boilerplate}
-
-\makeindex
-
-\begin{document}
-
-\maketitle
-
-\ifhtml
-\chapter*{Front Matter\label{front}}
-\fi
-
-\input{copyright}
-
-\begin{abstract}
-
-\noindent
-Python is an interpreted, object-oriented, high-level programming
-language with dynamic semantics. Its high-level built in data
-structures, combined with dynamic typing and dynamic binding, make it
-very attractive for rapid application development, as well as for use
-as a scripting or glue language to connect existing components
-together. Python's simple, easy to learn syntax emphasizes
-readability and therefore reduces the cost of program
-maintenance. Python supports modules and packages, which encourages
-program modularity and code reuse. The Python interpreter and the
-extensive standard library are available in source or binary form
-without charge for all major platforms, and can be freely distributed.
-
-This reference manual describes the syntax and ``core semantics'' of
-the language. It is terse, but attempts to be exact and complete.
-The semantics of non-essential built-in object types and of the
-built-in functions and modules are described in the
-\citetitle[../lib/lib.html]{Python Library Reference}. For an
-informal introduction to the language, see the
-\citetitle[../tut/tut.html]{Python Tutorial}. For C or
-\Cpp{} programmers, two additional manuals exist:
-\citetitle[../ext/ext.html]{Extending and Embedding the Python
-Interpreter} describes the high-level picture of how to write a Python
-extension module, and the \citetitle[../api/api.html]{Python/C API
-Reference Manual} describes the interfaces available to
-C/\Cpp{} programmers in detail.
-
-\end{abstract}
-
-\tableofcontents
-
-\input{ref1} % Introduction
-\input{ref2} % Lexical analysis
-\input{ref3} % Data model
-\input{ref4} % Execution model
-\input{ref5} % Expressions and conditions
-\input{ref6} % Simple statements
-\input{ref7} % Compound statements
-\input{ref8} % Top-level components
-
-\appendix
-
-\chapter{History and License}
-\input{license}
-
-\input{ref.ind}
-
-\end{document}
diff --git a/Doc/ref/ref1.tex b/Doc/ref/ref1.tex
deleted file mode 100644
index 6234716..0000000
--- a/Doc/ref/ref1.tex
+++ /dev/null
@@ -1,136 +0,0 @@
-\chapter{Introduction\label{introduction}}
-
-This reference manual describes the Python programming language.
-It is not intended as a tutorial.
-
-While I am trying to be as precise as possible, I chose to use English
-rather than formal specifications for everything except syntax and
-lexical analysis. This should make the document more understandable
-to the average reader, but will leave room for ambiguities.
-Consequently, if you were coming from Mars and tried to re-implement
-Python from this document alone, you might have to guess things and in
-fact you would probably end up implementing quite a different language.
-On the other hand, if you are using
-Python and wonder what the precise rules about a particular area of
-the language are, you should definitely be able to find them here.
-If you would like to see a more formal definition of the language,
-maybe you could volunteer your time --- or invent a cloning machine
-:-).
-
-It is dangerous to add too many implementation details to a language
-reference document --- the implementation may change, and other
-implementations of the same language may work differently. On the
-other hand, there is currently only one Python implementation in
-widespread use (although alternate implementations exist), and
-its particular quirks are sometimes worth being mentioned, especially
-where the implementation imposes additional limitations. Therefore,
-you'll find short ``implementation notes'' sprinkled throughout the
-text.
-
-Every Python implementation comes with a number of built-in and
-standard modules. These are not documented here, but in the separate
-\citetitle[../lib/lib.html]{Python Library Reference} document. A few
-built-in modules are mentioned when they interact in a significant way
-with the language definition.
-
-
-\section{Alternate Implementations\label{implementations}}
-
-Though there is one Python implementation which is by far the most
-popular, there are some alternate implementations which are of
-particular interest to different audiences.
-
-Known implementations include:
-
-\begin{itemize}
-\item[CPython]
-This is the original and most-maintained implementation of Python,
-written in C. New language features generally appear here first.
-
-\item[Jython]
-Python implemented in Java. This implementation can be used as a
-scripting language for Java applications, or can be used to create
-applications using the Java class libraries. It is also often used to
-create tests for Java libraries. More information can be found at
-\ulink{the Jython website}{http://www.jython.org/}.
-
-\item[Python for .NET]
-This implementation actually uses the CPython implementation, but is a
-managed .NET application and makes .NET libraries available. This was
-created by Brian Lloyd. For more information, see the \ulink{Python
-for .NET home page}{http://www.zope.org/Members/Brian/PythonNet}.
-
-\item[IronPython]
-An alternate Python for\ .NET. Unlike Python.NET, this is a complete
-Python implementation that generates IL, and compiles Python code
-directly to\ .NET assemblies. It was created by Jim Hugunin, the
-original creator of Jython. For more information, see \ulink{the
-IronPython website}{http://workspaces.gotdotnet.com/ironpython}.
-
-\item[PyPy]
-An implementation of Python written in Python; even the bytecode
-interpreter is written in Python. This is executed using CPython as
-the underlying interpreter. One of the goals of the project is to
-encourage experimentation with the language itself by making it easier
-to modify the interpreter (since it is written in Python). Additional
-information is available on \ulink{the PyPy project's home
-page}{http://codespeak.net/pypy/}.
-\end{itemize}
-
-Each of these implementations varies in some way from the language as
-documented in this manual, or introduces specific information beyond
-what's covered in the standard Python documentation. Please refer to
-the implementation-specific documentation to determine what else you
-need to know about the specific implementation you're using.
-
-
-\section{Notation\label{notation}}
-
-The descriptions of lexical analysis and syntax use a modified BNF
-grammar notation. This uses the following style of definition:
-\index{BNF}
-\index{grammar}
-\index{syntax}
-\index{notation}
-
-\begin{productionlist}[*]
- \production{name}{\token{lc_letter} (\token{lc_letter} | "_")*}
- \production{lc_letter}{"a"..."z"}
-\end{productionlist}
-
-The first line says that a \code{name} is an \code{lc_letter} followed by
-a sequence of zero or more \code{lc_letter}s and underscores. An
-\code{lc_letter} in turn is any of the single characters \character{a}
-through \character{z}. (This rule is actually adhered to for the
-names defined in lexical and grammar rules in this document.)
-
-Each rule begins with a name (which is the name defined by the rule)
-and \code{::=}. A vertical bar (\code{|}) is used to separate
-alternatives; it is the least binding operator in this notation. A
-star (\code{*}) means zero or more repetitions of the preceding item;
-likewise, a plus (\code{+}) means one or more repetitions, and a
-phrase enclosed in square brackets (\code{[ ]}) means zero or one
-occurrences (in other words, the enclosed phrase is optional). The
-\code{*} and \code{+} operators bind as tightly as possible;
-parentheses are used for grouping. Literal strings are enclosed in
-quotes. White space is only meaningful to separate tokens.
-Rules are normally contained on a single line; rules with many
-alternatives may be formatted alternatively with each line after the
-first beginning with a vertical bar.
-
-In lexical definitions (as the example above), two more conventions
-are used: Two literal characters separated by three dots mean a choice
-of any single character in the given (inclusive) range of \ASCII{}
-characters. A phrase between angular brackets (\code{<...>}) gives an
-informal description of the symbol defined; e.g., this could be used
-to describe the notion of `control character' if needed.
-\index{lexical definitions}
-\index{ASCII@\ASCII}
-
-Even though the notation used is almost the same, there is a big
-difference between the meaning of lexical and syntactic definitions:
-a lexical definition operates on the individual characters of the
-input source, while a syntax definition operates on the stream of
-tokens generated by the lexical analysis. All uses of BNF in the next
-chapter (``Lexical Analysis'') are lexical definitions; uses in
-subsequent chapters are syntactic definitions.
diff --git a/Doc/ref/ref2.tex b/Doc/ref/ref2.tex
deleted file mode 100644
index 7b70676..0000000
--- a/Doc/ref/ref2.tex
+++ /dev/null
@@ -1,725 +0,0 @@
-\chapter{Lexical analysis\label{lexical}}
-
-A Python program is read by a \emph{parser}. Input to the parser is a
-stream of \emph{tokens}, generated by the \emph{lexical analyzer}. This
-chapter describes how the lexical analyzer breaks a file into tokens.
-\index{lexical analysis}
-\index{parser}
-\index{token}
-
-Python uses the 7-bit \ASCII{} character set for program text.
-\versionadded[An encoding declaration can be used to indicate that
-string literals and comments use an encoding different from ASCII]{2.3}
-For compatibility with older versions, Python only warns if it finds
-8-bit characters; those warnings should be corrected by either declaring
-an explicit encoding, or using escape sequences if those bytes are binary
-data, instead of characters.
-
-
-The run-time character set depends on the I/O devices connected to the
-program but is generally a superset of \ASCII.
-
-\strong{Future compatibility note:} It may be tempting to assume that the
-character set for 8-bit characters is ISO Latin-1 (an \ASCII{}
-superset that covers most western languages that use the Latin
-alphabet), but it is possible that in the future Unicode text editors
-will become common. These generally use the UTF-8 encoding, which is
-also an \ASCII{} superset, but with very different use for the
-characters with ordinals 128-255. While there is no consensus on this
-subject yet, it is unwise to assume either Latin-1 or UTF-8, even
-though the current implementation appears to favor Latin-1. This
-applies both to the source character set and the run-time character
-set.
-
-
-\section{Line structure\label{line-structure}}
-
-A Python program is divided into a number of \emph{logical lines}.
-\index{line structure}
-
-
-\subsection{Logical lines\label{logical}}
-
-The end of
-a logical line is represented by the token NEWLINE. Statements cannot
-cross logical line boundaries except where NEWLINE is allowed by the
-syntax (e.g., between statements in compound statements).
-A logical line is constructed from one or more \emph{physical lines}
-by following the explicit or implicit \emph{line joining} rules.
-\index{logical line}
-\index{physical line}
-\index{line joining}
-\index{NEWLINE token}
-
-
-\subsection{Physical lines\label{physical}}
-
-A physical line is a sequence of characters terminated by an end-of-line
-sequence. In source files, any of the standard platform line
-termination sequences can be used - the \UNIX{} form using \ASCII{} LF
-(linefeed), the Windows form using the \ASCII{} sequence CR LF (return
-followed by linefeed), or the Macintosh form using the \ASCII{} CR
-(return) character. All of these forms can be used equally, regardless
-of platform.
-
-When embedding Python, source code strings should be passed to Python
-APIs using the standard C conventions for newline characters (the
-\code{\e n} character, representing \ASCII{} LF, is the line
-terminator).
-
-
-\subsection{Comments\label{comments}}
-
-A comment starts with a hash character (\code{\#}) that is not part of
-a string literal, and ends at the end of the physical line. A comment
-signifies the end of the logical line unless the implicit line joining
-rules are invoked.
-Comments are ignored by the syntax; they are not tokens.
-\index{comment}
-\index{hash character}
-
-
-\subsection{Encoding declarations\label{encodings}}
-\index{source character set}
-\index{encodings}
-
-If a comment in the first or second line of the Python script matches
-the regular expression \regexp{coding[=:]\e s*([-\e w.]+)}, this comment is
-processed as an encoding declaration; the first group of this
-expression names the encoding of the source code file. The recommended
-forms of this expression are
-
-\begin{verbatim}
-# -*- coding: <encoding-name> -*-
-\end{verbatim}
-
-which is recognized also by GNU Emacs, and
-
-\begin{verbatim}
-# vim:fileencoding=<encoding-name>
-\end{verbatim}
-
-which is recognized by Bram Moolenaar's VIM. In addition, if the first
-bytes of the file are the UTF-8 byte-order mark
-(\code{'\e xef\e xbb\e xbf'}), the declared file encoding is UTF-8
-(this is supported, among others, by Microsoft's \program{notepad}).
-
-If an encoding is declared, the encoding name must be recognized by
-Python. % XXX there should be a list of supported encodings.
-The encoding is used for all lexical analysis, in particular to find
-the end of a string, and to interpret the contents of Unicode literals.
-String literals are converted to Unicode for syntactical analysis,
-then converted back to their original encoding before interpretation
-starts. The encoding declaration must appear on a line of its own.
-
-\subsection{Explicit line joining\label{explicit-joining}}
-
-Two or more physical lines may be joined into logical lines using
-backslash characters (\code{\e}), as follows: when a physical line ends
-in a backslash that is not part of a string literal or comment, it is
-joined with the following forming a single logical line, deleting the
-backslash and the following end-of-line character. For example:
-\index{physical line}
-\index{line joining}
-\index{line continuation}
-\index{backslash character}
-%
-\begin{verbatim}
-if 1900 < year < 2100 and 1 <= month <= 12 \
- and 1 <= day <= 31 and 0 <= hour < 24 \
- and 0 <= minute < 60 and 0 <= second < 60: # Looks like a valid date
- return 1
-\end{verbatim}
-
-A line ending in a backslash cannot carry a comment. A backslash does
-not continue a comment. A backslash does not continue a token except
-for string literals (i.e., tokens other than string literals cannot be
-split across physical lines using a backslash). A backslash is
-illegal elsewhere on a line outside a string literal.
-
-
-\subsection{Implicit line joining\label{implicit-joining}}
-
-Expressions in parentheses, square brackets or curly braces can be
-split over more than one physical line without using backslashes.
-For example:
-
-\begin{verbatim}
-month_names = ['Januari', 'Februari', 'Maart', # These are the
- 'April', 'Mei', 'Juni', # Dutch names
- 'Juli', 'Augustus', 'September', # for the months
- 'Oktober', 'November', 'December'] # of the year
-\end{verbatim}
-
-Implicitly continued lines can carry comments. The indentation of the
-continuation lines is not important. Blank continuation lines are
-allowed. There is no NEWLINE token between implicit continuation
-lines. Implicitly continued lines can also occur within triple-quoted
-strings (see below); in that case they cannot carry comments.
-
-
-\subsection{Blank lines \label{blank-lines}}
-
-\index{blank line}
-A logical line that contains only spaces, tabs, formfeeds and possibly
-a comment, is ignored (i.e., no NEWLINE token is generated). During
-interactive input of statements, handling of a blank line may differ
-depending on the implementation of the read-eval-print loop. In the
-standard implementation, an entirely blank logical line (i.e.\ one
-containing not even whitespace or a comment) terminates a multi-line
-statement.
-
-
-\subsection{Indentation\label{indentation}}
-
-Leading whitespace (spaces and tabs) at the beginning of a logical
-line is used to compute the indentation level of the line, which in
-turn is used to determine the grouping of statements.
-\index{indentation}
-\index{whitespace}
-\index{leading whitespace}
-\index{space}
-\index{tab}
-\index{grouping}
-\index{statement grouping}
-
-First, tabs are replaced (from left to right) by one to eight spaces
-such that the total number of characters up to and including the
-replacement is a multiple of
-eight (this is intended to be the same rule as used by \UNIX). The
-total number of spaces preceding the first non-blank character then
-determines the line's indentation. Indentation cannot be split over
-multiple physical lines using backslashes; the whitespace up to the
-first backslash determines the indentation.
-
-\strong{Cross-platform compatibility note:} because of the nature of
-text editors on non-UNIX platforms, it is unwise to use a mixture of
-spaces and tabs for the indentation in a single source file. It
-should also be noted that different platforms may explicitly limit the
-maximum indentation level.
-
-A formfeed character may be present at the start of the line; it will
-be ignored for the indentation calculations above. Formfeed
-characters occurring elsewhere in the leading whitespace have an
-undefined effect (for instance, they may reset the space count to
-zero).
-
-The indentation levels of consecutive lines are used to generate
-INDENT and DEDENT tokens, using a stack, as follows.
-\index{INDENT token}
-\index{DEDENT token}
-
-Before the first line of the file is read, a single zero is pushed on
-the stack; this will never be popped off again. The numbers pushed on
-the stack will always be strictly increasing from bottom to top. At
-the beginning of each logical line, the line's indentation level is
-compared to the top of the stack. If it is equal, nothing happens.
-If it is larger, it is pushed on the stack, and one INDENT token is
-generated. If it is smaller, it \emph{must} be one of the numbers
-occurring on the stack; all numbers on the stack that are larger are
-popped off, and for each number popped off a DEDENT token is
-generated. At the end of the file, a DEDENT token is generated for
-each number remaining on the stack that is larger than zero.
-
-Here is an example of a correctly (though confusingly) indented piece
-of Python code:
-
-\begin{verbatim}
-def perm(l):
- # Compute the list of all permutations of l
- if len(l) <= 1:
- return [l]
- r = []
- for i in range(len(l)):
- s = l[:i] + l[i+1:]
- p = perm(s)
- for x in p:
- r.append(l[i:i+1] + x)
- return r
-\end{verbatim}
-
-The following example shows various indentation errors:
-
-\begin{verbatim}
- def perm(l): # error: first line indented
-for i in range(len(l)): # error: not indented
- s = l[:i] + l[i+1:]
- p = perm(l[:i] + l[i+1:]) # error: unexpected indent
- for x in p:
- r.append(l[i:i+1] + x)
- return r # error: inconsistent dedent
-\end{verbatim}
-
-(Actually, the first three errors are detected by the parser; only the
-last error is found by the lexical analyzer --- the indentation of
-\code{return r} does not match a level popped off the stack.)
-
-
-\subsection{Whitespace between tokens\label{whitespace}}
-
-Except at the beginning of a logical line or in string literals, the
-whitespace characters space, tab and formfeed can be used
-interchangeably to separate tokens. Whitespace is needed between two
-tokens only if their concatenation could otherwise be interpreted as a
-different token (e.g., ab is one token, but a b is two tokens).
-
-
-\section{Other tokens\label{other-tokens}}
-
-Besides NEWLINE, INDENT and DEDENT, the following categories of tokens
-exist: \emph{identifiers}, \emph{keywords}, \emph{literals},
-\emph{operators}, and \emph{delimiters}.
-Whitespace characters (other than line terminators, discussed earlier)
-are not tokens, but serve to delimit tokens.
-Where
-ambiguity exists, a token comprises the longest possible string that
-forms a legal token, when read from left to right.
-
-
-\section{Identifiers and keywords\label{identifiers}}
-
-Identifiers (also referred to as \emph{names}) are described by the following
-lexical definitions:
-\index{identifier}
-\index{name}
-
-\begin{productionlist}
- \production{identifier}
- {(\token{letter}|"_") (\token{letter} | \token{digit} | "_")*}
- \production{letter}
- {\token{lowercase} | \token{uppercase}}
- \production{lowercase}
- {"a"..."z"}
- \production{uppercase}
- {"A"..."Z"}
- \production{digit}
- {"0"..."9"}
-\end{productionlist}
-
-Identifiers are unlimited in length. Case is significant.
-
-
-\subsection{Keywords\label{keywords}}
-
-The following identifiers are used as reserved words, or
-\emph{keywords} of the language, and cannot be used as ordinary
-identifiers. They must be spelled exactly as written here:%
-\index{keyword}%
-\index{reserved word}
-
-\begin{verbatim}
-and def for is raise
-as del from lambda return
-assert elif global not try
-break else if or while
-class except import pass with
-continue finally in print yield
-\end{verbatim}
-
-% When adding keywords, use reswords.py for reformatting
-
-\versionchanged[\constant{None} became a constant and is now
-recognized by the compiler as a name for the built-in object
-\constant{None}. Although it is not a keyword, you cannot assign
-a different object to it]{2.4}
-
-\versionchanged[Both \keyword{as} and \keyword{with} are only recognized
-when the \code{with_statement} future feature has been enabled.
-It will always be enabled in Python 2.6. See section~\ref{with} for
-details. Note that using \keyword{as} and \keyword{with} as identifiers
-will always issue a warning, even when the \code{with_statement} future
-directive is not in effect]{2.5}
-
-
-\subsection{Reserved classes of identifiers\label{id-classes}}
-
-Certain classes of identifiers (besides keywords) have special
-meanings. These classes are identified by the patterns of leading and
-trailing underscore characters:
-
-\begin{description}
-
-\item[\code{_*}]
- Not imported by \samp{from \var{module} import *}. The special
- identifier \samp{_} is used in the interactive interpreter to store
- the result of the last evaluation; it is stored in the
- \module{__builtin__} module. When not in interactive mode, \samp{_}
- has no special meaning and is not defined.
- See section~\ref{import}, ``The \keyword{import} statement.''
-
- \note{The name \samp{_} is often used in conjunction with
- internationalization; refer to the documentation for the
- \ulink{\module{gettext} module}{../lib/module-gettext.html} for more
- information on this convention.}
-
-\item[\code{__*__}]
- System-defined names. These names are defined by the interpreter
- and its implementation (including the standard library);
- applications should not expect to define additional names using this
- convention. The set of names of this class defined by Python may be
- extended in future versions.
- See section~\ref{specialnames}, ``Special method names.''
-
-\item[\code{__*}]
- Class-private names. Names in this category, when used within the
- context of a class definition, are re-written to use a mangled form
- to help avoid name clashes between ``private'' attributes of base
- and derived classes.
- See section~\ref{atom-identifiers}, ``Identifiers (Names).''
-
-\end{description}
-
-
-\section{Literals\label{literals}}
-
-Literals are notations for constant values of some built-in types.
-\index{literal}
-\index{constant}
-
-
-\subsection{String literals\label{strings}}
-
-String literals are described by the following lexical definitions:
-\index{string literal}
-
-\index{ASCII@\ASCII}
-\begin{productionlist}
- \production{stringliteral}
- {[\token{stringprefix}](\token{shortstring} | \token{longstring})}
- \production{stringprefix}
- {"r" | "u" | "ur" | "R" | "U" | "UR" | "Ur" | "uR"}
- \production{shortstring}
- {"'" \token{shortstringitem}* "'"
- | '"' \token{shortstringitem}* '"'}
- \production{longstring}
- {"'''" \token{longstringitem}* "'''"}
- \productioncont{| '"""' \token{longstringitem}* '"""'}
- \production{shortstringitem}
- {\token{shortstringchar} | \token{escapeseq}}
- \production{longstringitem}
- {\token{longstringchar} | \token{escapeseq}}
- \production{shortstringchar}
- {<any source character except "\e" or newline or the quote>}
- \production{longstringchar}
- {<any source character except "\e">}
- \production{escapeseq}
- {"\e" <any ASCII character>}
-\end{productionlist}
-
-One syntactic restriction not indicated by these productions is that
-whitespace is not allowed between the \grammartoken{stringprefix} and
-the rest of the string literal. The source character set is defined
-by the encoding declaration; it is \ASCII{} if no encoding declaration
-is given in the source file; see section~\ref{encodings}.
-
-\index{triple-quoted string}
-\index{Unicode Consortium}
-\index{string!Unicode}
-In plain English: String literals can be enclosed in matching single
-quotes (\code{'}) or double quotes (\code{"}). They can also be
-enclosed in matching groups of three single or double quotes (these
-are generally referred to as \emph{triple-quoted strings}). The
-backslash (\code{\e}) character is used to escape characters that
-otherwise have a special meaning, such as newline, backslash itself,
-or the quote character. String literals may optionally be prefixed
-with a letter \character{r} or \character{R}; such strings are called
-\dfn{raw strings}\index{raw string} and use different rules for interpreting
-backslash escape sequences. A prefix of \character{u} or \character{U}
-makes the string a Unicode string. Unicode strings use the Unicode character
-set as defined by the Unicode Consortium and ISO~10646. Some additional
-escape sequences, described below, are available in Unicode strings.
-The two prefix characters may be combined; in this case, \character{u} must
-appear before \character{r}.
-
-In triple-quoted strings,
-unescaped newlines and quotes are allowed (and are retained), except
-that three unescaped quotes in a row terminate the string. (A
-``quote'' is the character used to open the string, i.e. either
-\code{'} or \code{"}.)
-
-Unless an \character{r} or \character{R} prefix is present, escape
-sequences in strings are interpreted according to rules similar
-to those used by Standard C. The recognized escape sequences are:
-\index{physical line}
-\index{escape sequence}
-\index{Standard C}
-\index{C}
-
-\begin{tableiii}{l|l|c}{code}{Escape Sequence}{Meaning}{Notes}
-\lineiii{\e\var{newline}} {Ignored}{}
-\lineiii{\e\e} {Backslash (\code{\e})}{}
-\lineiii{\e'} {Single quote (\code{'})}{}
-\lineiii{\e"} {Double quote (\code{"})}{}
-\lineiii{\e a} {\ASCII{} Bell (BEL)}{}
-\lineiii{\e b} {\ASCII{} Backspace (BS)}{}
-\lineiii{\e f} {\ASCII{} Formfeed (FF)}{}
-\lineiii{\e n} {\ASCII{} Linefeed (LF)}{}
-\lineiii{\e N\{\var{name}\}}
- {Character named \var{name} in the Unicode database (Unicode only)}{}
-\lineiii{\e r} {\ASCII{} Carriage Return (CR)}{}
-\lineiii{\e t} {\ASCII{} Horizontal Tab (TAB)}{}
-\lineiii{\e u\var{xxxx}}
- {Character with 16-bit hex value \var{xxxx} (Unicode only)}{(1)}
-\lineiii{\e U\var{xxxxxxxx}}
- {Character with 32-bit hex value \var{xxxxxxxx} (Unicode only)}{(2)}
-\lineiii{\e v} {\ASCII{} Vertical Tab (VT)}{}
-\lineiii{\e\var{ooo}} {Character with octal value \var{ooo}}{(3,5)}
-\lineiii{\e x\var{hh}} {Character with hex value \var{hh}}{(4,5)}
-\end{tableiii}
-\index{ASCII@\ASCII}
-
-\noindent
-Notes:
-
-\begin{itemize}
-\item[(1)]
- Individual code units which form parts of a surrogate pair can be
- encoded using this escape sequence.
-\item[(2)]
- Any Unicode character can be encoded this way, but characters
- outside the Basic Multilingual Plane (BMP) will be encoded using a
- surrogate pair if Python is compiled to use 16-bit code units (the
- default). Individual code units which form parts of a surrogate
- pair can be encoded using this escape sequence.
-\item[(3)]
- As in Standard C, up to three octal digits are accepted.
-\item[(4)]
- Unlike in Standard C, at most two hex digits are accepted.
-\item[(5)]
- In a string literal, hexadecimal and octal escapes denote the
- byte with the given value; it is not necessary that the byte
- encodes a character in the source character set. In a Unicode
- literal, these escapes denote a Unicode character with the given
- value.
-\end{itemize}
-
-
-Unlike Standard \index{unrecognized escape sequence}C,
-all unrecognized escape sequences are left in the string unchanged,
-i.e., \emph{the backslash is left in the string}. (This behavior is
-useful when debugging: if an escape sequence is mistyped, the
-resulting output is more easily recognized as broken.) It is also
-important to note that the escape sequences marked as ``(Unicode
-only)'' in the table above fall into the category of unrecognized
-escapes for non-Unicode string literals.
-
-When an \character{r} or \character{R} prefix is present, a character
-following a backslash is included in the string without change, and \emph{all
-backslashes are left in the string}. For example, the string literal
-\code{r"\e n"} consists of two characters: a backslash and a lowercase
-\character{n}. String quotes can be escaped with a backslash, but the
-backslash remains in the string; for example, \code{r"\e""} is a valid string
-literal consisting of two characters: a backslash and a double quote;
-\code{r"\e"} is not a valid string literal (even a raw string cannot
-end in an odd number of backslashes). Specifically, \emph{a raw
-string cannot end in a single backslash} (since the backslash would
-escape the following quote character). Note also that a single
-backslash followed by a newline is interpreted as those two characters
-as part of the string, \emph{not} as a line continuation.
-
-When an \character{r} or \character{R} prefix is used in conjunction
-with a \character{u} or \character{U} prefix, then the \code{\e uXXXX}
-and \code{\e UXXXXXXXX} escape sequences are processed while
-\emph{all other backslashes are left in the string}.
-For example, the string literal
-\code{ur"\e{}u0062\e n"} consists of three Unicode characters: `LATIN
-SMALL LETTER B', `REVERSE SOLIDUS', and `LATIN SMALL LETTER N'.
-Backslashes can be escaped with a preceding backslash; however, both
-remain in the string. As a result, \code{\e uXXXX} escape sequences
-are only recognized when there are an odd number of backslashes.
-
-\subsection{String literal concatenation\label{string-catenation}}
-
-Multiple adjacent string literals (delimited by whitespace), possibly
-using different quoting conventions, are allowed, and their meaning is
-the same as their concatenation. Thus, \code{"hello" 'world'} is
-equivalent to \code{"helloworld"}. This feature can be used to reduce
-the number of backslashes needed, to split long strings conveniently
-across long lines, or even to add comments to parts of strings, for
-example:
-
-\begin{verbatim}
-re.compile("[A-Za-z_]" # letter or underscore
- "[A-Za-z0-9_]*" # letter, digit or underscore
- )
-\end{verbatim}
-
-Note that this feature is defined at the syntactical level, but
-implemented at compile time. The `+' operator must be used to
-concatenate string expressions at run time. Also note that literal
-concatenation can use different quoting styles for each component
-(even mixing raw strings and triple quoted strings).
-
-
-\subsection{Numeric literals\label{numbers}}
-
-There are four types of numeric literals: plain integers, long
-integers, floating point numbers, and imaginary numbers. There are no
-complex literals (complex numbers can be formed by adding a real
-number and an imaginary number).
-\index{number}
-\index{numeric literal}
-\index{integer literal}
-\index{plain integer literal}
-\index{long integer literal}
-\index{floating point literal}
-\index{hexadecimal literal}
-\index{octal literal}
-\index{binary literal}
-\index{decimal literal}
-\index{imaginary literal}
-\index{complex!literal}
-
-Note that numeric literals do not include a sign; a phrase like
-\code{-1} is actually an expression composed of the unary operator
-`\code{-}' and the literal \code{1}.
-
-
-\subsection{Integer literals\label{integers}}
-
-Integer literals are described by the following
-lexical definitions:
-
-\begin{productionlist}
- \production{integer}
- {\token{decimalinteger} | \token{octinteger} | \token{hexinteger}}
- \production{decimalinteger}
- {\token{nonzerodigit} \token{digit}* | "0"+}
- \production{octinteger}
- {"0" ("o" | "O") \token{octdigit}+}
- \production{hexinteger}
- {"0" ("x" | "X") \token{hexdigit}+}
- \production{bininteger}
- {"0" ("b" | "B") \token{bindigit}+}
- \production{nonzerodigit}
- {"1"..."9"}
- \production{octdigit}
- {"0"..."7"}
- \production{hexdigit}
- {\token{digit} | "a"..."f" | "A"..."F"}
- \production{bindigit}
- {"0"..."1"}
-\end{productionlist}
-
-Plain integer literals that are above the largest representable plain
-integer (e.g., 2147483647 when using 32-bit arithmetic) are accepted
-as if they were long integers instead.\footnote{In versions of Python
-prior to 2.4, octal and hexadecimal literals in the range just above
-the largest representable plain integer but below the largest unsigned
-32-bit number (on a machine using 32-bit arithmetic), 4294967296, were
-taken as the negative plain integer obtained by subtracting 4294967296
-from their unsigned value.} There is no limit for long integer
-literals apart from what can be stored in available memory.
-
-Note that leading zeros in a non-zero decimal number are not allowed.
-This is for disambiguation with C-style octal literals, which Python
-used before version 3.0.
-
-Some examples of integer literals:
-
-\begin{verbatim}
-7 2147483647 0o177 0b100110111
-3 79228162514264337593543950336 0o377 0x100000000
- 79228162514264337593543950336 0xdeadbeef
-\end{verbatim}
-
-
-\subsection{Floating point literals\label{floating}}
-
-Floating point literals are described by the following lexical
-definitions:
-
-\begin{productionlist}
- \production{floatnumber}
- {\token{pointfloat} | \token{exponentfloat}}
- \production{pointfloat}
- {[\token{intpart}] \token{fraction} | \token{intpart} "."}
- \production{exponentfloat}
- {(\token{intpart} | \token{pointfloat})
- \token{exponent}}
- \production{intpart}
- {\token{digit}+}
- \production{fraction}
- {"." \token{digit}+}
- \production{exponent}
- {("e" | "E") ["+" | "-"] \token{digit}+}
-\end{productionlist}
-
-Note that the integer and exponent parts are always interpreted using
-radix 10. For example, \samp{077e010} is legal, and denotes the same
-number as \samp{77e10}.
-The allowed range of floating point literals is implementation-dependent.
-Some examples of floating point literals:
-
-\begin{verbatim}
-3.14 10. .001 1e100 3.14e-10 0e0
-\end{verbatim}
-
-Note that numeric literals do not include a sign; a phrase like
-\code{-1} is actually an expression composed of the unary operator
-\code{-} and the literal \code{1}.
-
-
-\subsection{Imaginary literals\label{imaginary}}
-
-Imaginary literals are described by the following lexical definitions:
-
-\begin{productionlist}
- \production{imagnumber}{(\token{floatnumber} | \token{intpart}) ("j" | "J")}
-\end{productionlist}
-
-An imaginary literal yields a complex number with a real part of
-0.0. Complex numbers are represented as a pair of floating point
-numbers and have the same restrictions on their range. To create a
-complex number with a nonzero real part, add a floating point number
-to it, e.g., \code{(3+4j)}. Some examples of imaginary literals:
-
-\begin{verbatim}
-3.14j 10.j 10j .001j 1e100j 3.14e-10j
-\end{verbatim}
-
-
-\section{Operators\label{operators}}
-
-The following tokens are operators:
-\index{operators}
-
-\begin{verbatim}
-+ - * ** / // %
-<< >> & | ^ ~
-< > <= >= == !=
-\end{verbatim}
-
-
-\section{Delimiters\label{delimiters}}
-
-The following tokens serve as delimiters in the grammar:
-\index{delimiters}
-
-\begin{verbatim}
-( ) [ ] { } @
-, : . ` = ;
-+= -= *= /= //= %=
-&= |= ^= >>= <<= **=
-\end{verbatim}
-
-The period can also occur in floating-point and imaginary literals. A
-sequence of three periods has a special meaning as an ellipsis in slices.
-The second half of the list, the augmented assignment operators, serve
-lexically as delimiters, but also perform an operation.
-
-The following printing \ASCII{} characters have special meaning as part
-of other tokens or are otherwise significant to the lexical analyzer:
-
-\begin{verbatim}
-' " # \
-\end{verbatim}
-
-The following printing \ASCII{} characters are not used in Python. Their
-occurrence outside string literals and comments is an unconditional
-error:
-\index{ASCII@\ASCII}
-
-\begin{verbatim}
-$ ?
-\end{verbatim}
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
deleted file mode 100644
index 2b556e4..0000000
--- a/Doc/ref/ref3.tex
+++ /dev/null
@@ -1,2093 +0,0 @@
-\chapter{Data model\label{datamodel}}
-
-
-\section{Objects, values and types\label{objects}}
-
-\dfn{Objects} are Python's abstraction for data. All data in a Python
-program is represented by objects or by relations between objects.
-(In a sense, and in conformance to Von Neumann's model of a
-``stored program computer,'' code is also represented by objects.)
-\index{object}
-\index{data}
-
-Every object has an identity, a type and a value. An object's
-\emph{identity} never changes once it has been created; you may think
-of it as the object's address in memory. The `\keyword{is}' operator
-compares the identity of two objects; the
-\function{id()}\bifuncindex{id} function returns an integer
-representing its identity (currently implemented as its address).
-An object's \dfn{type} is
-also unchangeable.\footnote{Since Python 2.2, a gradual merging of
-types and classes has been started that makes this and a few other
-assertions made in this manual not 100\% accurate and complete:
-for example, it \emph{is} now possible in some cases to change an
-object's type, under certain controlled conditions. Until this manual
-undergoes extensive revision, it must now be taken as authoritative
-only regarding ``classic classes'', that are still the default, for
-compatibility purposes, in Python 2.2 and 2.3. For more information,
-see \url{http://www.python.org/doc/newstyle.html}.}
-An object's type determines the operations that the object
-supports (e.g., ``does it have a length?'') and also defines the
-possible values for objects of that type. The
-\function{type()}\bifuncindex{type} function returns an object's type
-(which is an object itself). The \emph{value} of some
-objects can change. Objects whose value can change are said to be
-\emph{mutable}; objects whose value is unchangeable once they are
-created are called \emph{immutable}.
-(The value of an immutable container object that contains a reference
-to a mutable object can change when the latter's value is changed;
-however the container is still considered immutable, because the
-collection of objects it contains cannot be changed. So, immutability
-is not strictly the same as having an unchangeable value, it is more
-subtle.)
-An object's mutability is determined by its type; for instance,
-numbers, strings and tuples are immutable, while dictionaries and
-lists are mutable.
-\index{identity of an object}
-\index{value of an object}
-\index{type of an object}
-\index{mutable object}
-\index{immutable object}
-
-Objects are never explicitly destroyed; however, when they become
-unreachable they may be garbage-collected. An implementation is
-allowed to postpone garbage collection or omit it altogether --- it is
-a matter of implementation quality how garbage collection is
-implemented, as long as no objects are collected that are still
-reachable. (Implementation note: the current implementation uses a
-reference-counting scheme with (optional) delayed detection of
-cyclically linked garbage, which collects most objects as soon as they
-become unreachable, but is not guaranteed to collect garbage
-containing circular references. See the
-\citetitle[../lib/module-gc.html]{Python Library Reference} for
-information on controlling the collection of cyclic garbage.)
-\index{garbage collection}
-\index{reference counting}
-\index{unreachable object}
-
-Note that the use of the implementation's tracing or debugging
-facilities may keep objects alive that would normally be collectable.
-Also note that catching an exception with a
-`\keyword{try}...\keyword{except}' statement may keep objects alive.
-
-Some objects contain references to ``external'' resources such as open
-files or windows. It is understood that these resources are freed
-when the object is garbage-collected, but since garbage collection is
-not guaranteed to happen, such objects also provide an explicit way to
-release the external resource, usually a \method{close()} method.
-Programs are strongly recommended to explicitly close such
-objects. The `\keyword{try}...\keyword{finally}' statement provides
-a convenient way to do this.
-
-Some objects contain references to other objects; these are called
-\emph{containers}. Examples of containers are tuples, lists and
-dictionaries. The references are part of a container's value. In
-most cases, when we talk about the value of a container, we imply the
-values, not the identities of the contained objects; however, when we
-talk about the mutability of a container, only the identities of
-the immediately contained objects are implied. So, if an immutable
-container (like a tuple)
-contains a reference to a mutable object, its value changes
-if that mutable object is changed.
-\index{container}
-
-Types affect almost all aspects of object behavior. Even the importance
-of object identity is affected in some sense: for immutable types,
-operations that compute new values may actually return a reference to
-any existing object with the same type and value, while for mutable
-objects this is not allowed. E.g., after
-\samp{a = 1; b = 1},
-\code{a} and \code{b} may or may not refer to the same object with the
-value one, depending on the implementation, but after
-\samp{c = []; d = []}, \code{c} and \code{d}
-are guaranteed to refer to two different, unique, newly created empty
-lists.
-(Note that \samp{c = d = []} assigns the same object to both
-\code{c} and \code{d}.)
-
-
-\section{The standard type hierarchy\label{types}}
-
-Below is a list of the types that are built into Python. Extension
-modules (written in C, Java, or other languages, depending on
-the implementation) can define additional types. Future versions of
-Python may add types to the type hierarchy (e.g., rational
-numbers, efficiently stored arrays of integers, etc.).
-\index{type}
-\indexii{data}{type}
-\indexii{type}{hierarchy}
-\indexii{extension}{module}
-\indexii{C}{language}
-
-Some of the type descriptions below contain a paragraph listing
-`special attributes.' These are attributes that provide access to the
-implementation and are not intended for general use. Their definition
-may change in the future.
-\index{attribute}
-\indexii{special}{attribute}
-\indexiii{generic}{special}{attribute}
-
-\begin{description}
-
-\item[None]
-This type has a single value. There is a single object with this value.
-This object is accessed through the built-in name \code{None}.
-It is used to signify the absence of a value in many situations, e.g.,
-it is returned from functions that don't explicitly return anything.
-Its truth value is false.
-\obindex{None}
-
-\item[NotImplemented]
-This type has a single value. There is a single object with this value.
-This object is accessed through the built-in name \code{NotImplemented}.
-Numeric methods and rich comparison methods may return this value if
-they do not implement the operation for the operands provided. (The
-interpreter will then try the reflected operation, or some other
-fallback, depending on the operator.) Its truth value is true.
-\obindex{NotImplemented}
-
-\item[Ellipsis]
-This type has a single value. There is a single object with this value.
-This object is accessed through the literal \code{...} or the
-built-in name \code{Ellipsis}. Its truth value is true.
-\obindex{Ellipsis}
-
-\item[Numbers]
-These are created by numeric literals and returned as results by
-arithmetic operators and arithmetic built-in functions. Numeric
-objects are immutable; once created their value never changes. Python
-numbers are of course strongly related to mathematical numbers, but
-subject to the limitations of numerical representation in computers.
-\obindex{numeric}
-
-Python distinguishes between integers, floating point numbers, and
-complex numbers:
-
-\begin{description}
-\item[Integers]
-These represent elements from the mathematical set of integers
-(positive and negative).
-\obindex{integer}
-
-There are three types of integers:
-
-\begin{description}
-
-\item[Plain integers]
-These represent numbers in the range -2147483648 through 2147483647.
-(The range may be larger on machines with a larger natural word
-size, but not smaller.)
-When the result of an operation would fall outside this range, the
-result is normally returned as a long integer (in some cases, the
-exception \exception{OverflowError} is raised instead).
-For the purpose of shift and mask operations, integers are assumed to
-have a binary, 2's complement notation using 32 or more bits, and
-hiding no bits from the user (i.e., all 4294967296 different bit
-patterns correspond to different values).
-\obindex{plain integer}
-\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
-
-\item[Long integers]
-These represent numbers in an unlimited range, subject to available
-(virtual) memory only. For the purpose of shift and mask operations,
-a binary representation is assumed, and negative numbers are
-represented in a variant of 2's complement which gives the illusion of
-an infinite string of sign bits extending to the left.
-\obindex{long integer}
-
-\item[Booleans]
-These represent the truth values False and True. The two objects
-representing the values False and True are the only Boolean objects.
-The Boolean type is a subtype of plain integers, and Boolean values
-behave like the values 0 and 1, respectively, in almost all contexts,
-the exception being that when converted to a string, the strings
-\code{"False"} or \code{"True"} are returned, respectively.
-\obindex{Boolean}
-\ttindex{False}
-\ttindex{True}
-
-\end{description} % Integers
-
-The rules for integer representation are intended to give the most
-meaningful interpretation of shift and mask operations involving
-negative integers and the least surprises when switching between the
-plain and long integer domains. Any operation except left shift,
-if it yields a result in the plain integer domain without causing
-overflow, will yield the same result in the long integer domain or
-when using mixed operands.
-\indexii{integer}{representation}
-
-\item[Floating point numbers]
-These represent machine-level double precision floating point numbers.
-You are at the mercy of the underlying machine architecture (and
-C or Java implementation) for the accepted range and handling of overflow.
-Python does not support single-precision floating point numbers; the
-savings in processor and memory usage that are usually the reason for using
-these is dwarfed by the overhead of using objects in Python, so there
-is no reason to complicate the language with two kinds of floating
-point numbers.
-\obindex{floating point}
-\indexii{floating point}{number}
-\indexii{C}{language}
-\indexii{Java}{language}
-
-\item[Complex numbers]
-These represent complex numbers as a pair of machine-level double
-precision floating point numbers. The same caveats apply as for
-floating point numbers. The real and imaginary parts of a complex
-number \code{z} can be retrieved through the read-only attributes
-\code{z.real} and \code{z.imag}.
-\obindex{complex}
-\indexii{complex}{number}
-
-\end{description} % Numbers
-
-
-\item[Sequences]
-These represent finite ordered sets indexed by non-negative numbers.
-The built-in function \function{len()}\bifuncindex{len} returns the
-number of items of a sequence.
-When the length of a sequence is \var{n}, the
-index set contains the numbers 0, 1, \ldots, \var{n}-1. Item
-\var{i} of sequence \var{a} is selected by \code{\var{a}[\var{i}]}.
-\obindex{sequence}
-\index{index operation}
-\index{item selection}
-\index{subscription}
-
-Sequences also support slicing: \code{\var{a}[\var{i}:\var{j}]}
-selects all items with index \var{k} such that \var{i} \code{<=}
-\var{k} \code{<} \var{j}. When used as an expression, a slice is a
-sequence of the same type. This implies that the index set is
-renumbered so that it starts at 0.
-\index{slicing}
-
-Some sequences also support ``extended slicing'' with a third ``step''
-parameter: \code{\var{a}[\var{i}:\var{j}:\var{k}]} selects all items
-of \var{a} with index \var{x} where \code{\var{x} = \var{i} +
-\var{n}*\var{k}}, \var{n} \code{>=} \code{0} and \var{i} \code{<=}
-\var{x} \code{<} \var{j}.
-\index{extended slicing}
-
-Sequences are distinguished according to their mutability:
-
-\begin{description}
-
-\item[Immutable sequences]
-An object of an immutable sequence type cannot change once it is
-created. (If the object contains references to other objects,
-these other objects may be mutable and may be changed; however,
-the collection of objects directly referenced by an immutable object
-cannot change.)
-\obindex{immutable sequence}
-\obindex{immutable}
-
-The following types are immutable sequences:
-
-\begin{description}
-
-\item[Strings]
-The items of a string are characters. There is no separate
-character type; a character is represented by a string of one item.
-Characters represent (at least) 8-bit bytes. The built-in
-functions \function{chr()}\bifuncindex{chr} and
-\function{ord()}\bifuncindex{ord} convert between characters and
-nonnegative integers representing the byte values. Bytes with the
-values 0-127 usually represent the corresponding \ASCII{} values, but
-the interpretation of values is up to the program. The string
-data type is also used to represent arrays of bytes, e.g., to hold data
-read from a file.
-\obindex{string}
-\index{character}
-\index{byte}
-\index{ASCII@\ASCII}
-
-(On systems whose native character set is not \ASCII, strings may use
-EBCDIC in their internal representation, provided the functions
-\function{chr()} and \function{ord()} implement a mapping between \ASCII{} and
-EBCDIC, and string comparison preserves the \ASCII{} order.
-Or perhaps someone can propose a better rule?)
-\index{ASCII@\ASCII}
-\index{EBCDIC}
-\index{character set}
-\indexii{string}{comparison}
-\bifuncindex{chr}
-\bifuncindex{ord}
-
-\item[Unicode]
-The items of a Unicode object are Unicode code units. A Unicode code
-unit is represented by a Unicode object of one item and can hold
-either a 16-bit or 32-bit value representing a Unicode ordinal (the
-maximum value for the ordinal is given in \code{sys.maxunicode}, and
-depends on how Python is configured at compile time). Surrogate pairs
-may be present in the Unicode object, and will be reported as two
-separate items. The built-in functions
-\function{unichr()}\bifuncindex{unichr} and
-\function{ord()}\bifuncindex{ord} convert between code units and
-nonnegative integers representing the Unicode ordinals as defined in
-the Unicode Standard 3.0. Conversion from and to other encodings are
-possible through the Unicode method \method{encode()} and the built-in
-function \function{unicode()}.\bifuncindex{unicode}
-\obindex{unicode}
-\index{character}
-\index{integer}
-\index{Unicode}
-
-\item[Tuples]
-The items of a tuple are arbitrary Python objects.
-Tuples of two or more items are formed by comma-separated lists
-of expressions. A tuple of one item (a `singleton') can be formed
-by affixing a comma to an expression (an expression by itself does
-not create a tuple, since parentheses must be usable for grouping of
-expressions). An empty tuple can be formed by an empty pair of
-parentheses.
-\obindex{tuple}
-\indexii{singleton}{tuple}
-\indexii{empty}{tuple}
-
-\end{description} % Immutable sequences
-
-\item[Mutable sequences]
-Mutable sequences can be changed after they are created. The
-subscription and slicing notations can be used as the target of
-assignment and \keyword{del} (delete) statements.
-\obindex{mutable sequence}
-\obindex{mutable}
-\indexii{assignment}{statement}
-\index{delete}
-\stindex{del}
-\index{subscription}
-\index{slicing}
-
-There is currently a single intrinsic mutable sequence type:
-
-\begin{description}
-
-\item[Lists]
-The items of a list are arbitrary Python objects. Lists are formed
-by placing a comma-separated list of expressions in square brackets.
-(Note that there are no special cases needed to form lists of length 0
-or 1.)
-\obindex{list}
-
-\end{description} % Mutable sequences
-
-The extension module \module{array}\refstmodindex{array} provides an
-additional example of a mutable sequence type.
-
-
-\end{description} % Sequences
-
-
-\item[Set types]
-These represent unordered, finite sets of unique, immutable objects.
-As such, they cannot be indexed by any subscript. However, they can be
-iterated over, and the built-in function \function{len()} returns the
-number of items in a set. Common uses for sets are
-fast membership testing, removing duplicates from a sequence, and
-computing mathematical operations such as intersection, union, difference,
-and symmetric difference.
-\bifuncindex{len}
-\obindex{set type}
-
-For set elements, the same immutability rules apply as for dictionary
-keys. Note that numeric types obey the normal rules for numeric
-comparison: if two numbers compare equal (e.g., \code{1} and
-\code{1.0}), only one of them can be contained in a set.
-
-There are currently two intrinsic set types:
-
-\begin{description}
-
-\item[Sets]
-These\obindex{set} represent a mutable set. They are created by the
-built-in \function{set()} constructor and can be modified afterwards
-by several methods, such as \method{add()}.
-
-\item[Frozen sets]
-These\obindex{frozenset} represent an immutable set. They are created by
-the built-in \function{frozenset()} constructor. As a frozenset is
-immutable and hashable, it can be used again as an element of another set,
-or as a dictionary key.
-
-\end{description} % Set types
-
-
-\item[Mappings]
-These represent finite sets of objects indexed by arbitrary index sets.
-The subscript notation \code{a[k]} selects the item indexed
-by \code{k} from the mapping \code{a}; this can be used in
-expressions and as the target of assignments or \keyword{del} statements.
-The built-in function \function{len()} returns the number of items
-in a mapping.
-\bifuncindex{len}
-\index{subscription}
-\obindex{mapping}
-
-There is currently a single intrinsic mapping type:
-
-\begin{description}
-
-\item[Dictionaries]
-These\obindex{dictionary} represent finite sets of objects indexed by
-nearly arbitrary values. The only types of values not acceptable as
-keys are values containing lists or dictionaries or other mutable
-types that are compared by value rather than by object identity, the
-reason being that the efficient implementation of dictionaries
-requires a key's hash value to remain constant.
-Numeric types used for keys obey the normal rules for numeric
-comparison: if two numbers compare equal (e.g., \code{1} and
-\code{1.0}) then they can be used interchangeably to index the same
-dictionary entry.
-
-Dictionaries are mutable; they can be created by the
-\code{\{...\}} notation (see section~\ref{dict}, ``Dictionary
-Displays'').
-
-The extension modules \module{dbm}\refstmodindex{dbm},
-\module{gdbm}\refstmodindex{gdbm}, and
-\module{bsddb}\refstmodindex{bsddb} provide additional examples of
-mapping types.
-
-\end{description} % Mapping types
-
-\item[Callable types]
-These\obindex{callable} are the types to which the function call
-operation (see section~\ref{calls}, ``Calls'') can be applied:
-\indexii{function}{call}
-\index{invocation}
-\indexii{function}{argument}
-
-\begin{description}
-
-\item[User-defined functions]
-A user-defined function object is created by a function definition
-(see section~\ref{function}, ``Function definitions''). It should be
-called with an argument
-list containing the same number of items as the function's formal
-parameter list.
-\indexii{user-defined}{function}
-\obindex{function}
-\obindex{user-defined function}
-
-Special attributes:
-
-\begin{tableiii}{lll}{member}{Attribute}{Meaning}{}
- \lineiii{__doc__}{The function's documentation string, or
- \code{None} if unavailable}{Writable}
-
- \lineiii{__name__}{The function's name}{Writable}
-
- \lineiii{__module__}{The name of the module the function was defined
- in, or \code{None} if unavailable.}{Writable}
-
- \lineiii{__defaults__}{A tuple containing default argument values
- for those arguments that have defaults, or \code{None} if no
- arguments have a default value}{Writable}
-
- \lineiii{__code__}{The code object representing the compiled
- function body.}{Writable}
-
- \lineiii{__globals__}{A reference to the dictionary that holds the
- function's global variables --- the global namespace of the module
- in which the function was defined.}{Read-only}
-
- \lineiii{__dict__}{The namespace supporting arbitrary function
- attributes.}{Writable}
-
- \lineiii{__closure__}{\code{None} or a tuple of cells that contain
- bindings for the function's free variables.}{Read-only}
-
- \lineiii{__annotations__}{A dict containing annotations of parameters.
- The keys of the dict are the parameter names, or \code{'return'}
- for the return annotation, if provided.}{Writable}
-
- \lineiii{__kwdefaults__}{A dict containing defaults for keyword-only
- parameters.}{Writable}
-\end{tableiii}
-
-Most of the attributes labelled ``Writable'' check the type of the
-assigned value.
-
-\versionchanged[\code{__name__} is now writable]{2.4}
-
-Function objects also support getting and setting arbitrary
-attributes, which can be used, for example, to attach metadata to
-functions. Regular attribute dot-notation is used to get and set such
-attributes. \emph{Note that the current implementation only supports
-function attributes on user-defined functions. Function attributes on
-built-in functions may be supported in the future.}
-
-Additional information about a function's definition can be retrieved
-from its code object; see the description of internal types below.
-
-\withsubitem{(function attribute)}{
- \ttindex{__doc__}
- \ttindex{__name__}
- \ttindex{__module__}
- \ttindex{__dict__}
- \ttindex{__defaults__}
- \ttindex{__closure__}
- \ttindex{__code__}
- \ttindex{__globals__}
- \ttindex{__annotations__}
- \ttindex{__kwdefaults__}}
-\indexii{global}{namespace}
-
-\item[User-defined methods]
-A user-defined method object combines a class, a class instance (or
-\code{None}) and any callable object (normally a user-defined
-function).
-\obindex{method}
-\obindex{user-defined method}
-\indexii{user-defined}{method}
-
-Special read-only attributes: \member{im_self} is the class instance
-object, \member{im_func} is the function object;
-\member{im_class} is the class of \member{im_self} for bound methods
-or the class that asked for the method for unbound methods;
-\member{__doc__} is the method's documentation (same as
-\code{im_func.__doc__}); \member{__name__} is the method name (same as
-\code{im_func.__name__}); \member{__module__} is the name of the
-module the method was defined in, or \code{None} if unavailable.
-\versionchanged[\member{im_self} used to refer to the class that
- defined the method]{2.2}
-\withsubitem{(method attribute)}{
- \ttindex{__doc__}
- \ttindex{__name__}
- \ttindex{__module__}
- \ttindex{im_func}
- \ttindex{im_self}}
-
-Methods also support accessing (but not setting) the arbitrary
-function attributes on the underlying function object.
-
-User-defined method objects may be created when getting an attribute
-of a class (perhaps via an instance of that class), if that attribute
-is a user-defined function object, an unbound user-defined method object,
-or a class method object.
-When the attribute is a user-defined method object, a new
-method object is only created if the class from which it is being
-retrieved is the same as, or a derived class of, the class stored
-in the original method object; otherwise, the original method object
-is used as it is.
-
-When a user-defined method object is created by retrieving
-a user-defined function object from a class, its \member{im_self}
-attribute is \code{None} and the method object is said to be unbound.
-When one is created by retrieving a user-defined function object
-from a class via one of its instances, its \member{im_self} attribute
-is the instance, and the method object is said to be bound.
-In either case, the new method's \member{im_class} attribute
-is the class from which the retrieval takes place, and
-its \member{im_func} attribute is the original function object.
-\withsubitem{(method attribute)}{
- \ttindex{im_class}\ttindex{im_func}\ttindex{im_self}}
-
-When a user-defined method object is created by retrieving another
-method object from a class or instance, the behaviour is the same
-as for a function object, except that the \member{im_func} attribute
-of the new instance is not the original method object but its
-\member{im_func} attribute.
-\withsubitem{(method attribute)}{
- \ttindex{im_func}}
-
-When a user-defined method object is created by retrieving a
-class method object from a class or instance, its \member{im_self}
-attribute is the class itself (the same as the \member{im_class}
-attribute), and its \member{im_func} attribute is the function
-object underlying the class method.
-\withsubitem{(method attribute)}{
- \ttindex{im_class}\ttindex{im_func}\ttindex{im_self}}
-
-When an unbound user-defined method object is called, the underlying
-function (\member{im_func}) is called, with the restriction that the
-first argument must be an instance of the proper class
-(\member{im_class}) or of a derived class thereof.
-
-When a bound user-defined method object is called, the underlying
-function (\member{im_func}) is called, inserting the class instance
-(\member{im_self}) in front of the argument list. For instance, when
-\class{C} is a class which contains a definition for a function
-\method{f()}, and \code{x} is an instance of \class{C}, calling
-\code{x.f(1)} is equivalent to calling \code{C.f(x, 1)}.
-
-When a user-defined method object is derived from a class method object,
-the ``class instance'' stored in \member{im_self} will actually be the
-class itself, so that calling either \code{x.f(1)} or \code{C.f(1)} is
-equivalent to calling \code{f(C,1)} where \code{f} is the underlying
-function.
-
-Note that the transformation from function object to (unbound or
-bound) method object happens each time the attribute is retrieved from
-the class or instance. In some cases, a fruitful optimization is to
-assign the attribute to a local variable and call that local variable.
-Also notice that this transformation only happens for user-defined
-functions; other callable objects (and all non-callable objects) are
-retrieved without transformation. It is also important to note that
-user-defined functions which are attributes of a class instance are
-not converted to bound methods; this \emph{only} happens when the
-function is an attribute of the class.
-
-\item[Generator functions\index{generator!function}\index{generator!iterator}]
-A function or method which uses the \keyword{yield} statement (see
-section~\ref{yield}, ``The \keyword{yield} statement'') is called a
-\dfn{generator function}. Such a function, when called, always
-returns an iterator object which can be used to execute the body of
-the function: calling the iterator's \method{__next__()} method will
-cause the function to execute until it provides a value using the
-\keyword{yield} statement. When the function executes a
-\keyword{return} statement or falls off the end, a
-\exception{StopIteration} exception is raised and the iterator will
-have reached the end of the set of values to be returned.
-
-\item[Built-in functions]
-A built-in function object is a wrapper around a C function. Examples
-of built-in functions are \function{len()} and \function{math.sin()}
-(\module{math} is a standard built-in module).
-The number and type of the arguments are
-determined by the C function.
-Special read-only attributes: \member{__doc__} is the function's
-documentation string, or \code{None} if unavailable; \member{__name__}
-is the function's name; \member{__self__} is set to \code{None} (but see
-the next item); \member{__module__} is the name of the module the
-function was defined in or \code{None} if unavailable.
-\obindex{built-in function}
-\obindex{function}
-\indexii{C}{language}
-
-\item[Built-in methods]
-This is really a different disguise of a built-in function, this time
-containing an object passed to the C function as an implicit extra
-argument. An example of a built-in method is
-\code{\var{alist}.append()}, assuming
-\var{alist} is a list object.
-In this case, the special read-only attribute \member{__self__} is set
-to the object denoted by \var{list}.
-\obindex{built-in method}
-\obindex{method}
-\indexii{built-in}{method}
-
-\item[Class Types]
-Class types, or ``new-style classes,'' are callable. These objects
-normally act as factories for new instances of themselves, but
-variations are possible for class types that override
-\method{__new__()}. The arguments of the call are passed to
-\method{__new__()} and, in the typical case, to \method{__init__()} to
-initialize the new instance.
-
-\item[Classic Classes]
-Class objects are described below. When a class object is called,
-a new class instance (also described below) is created and
-returned. This implies a call to the class's \method{__init__()} method
-if it has one. Any arguments are passed on to the \method{__init__()}
-method. If there is no \method{__init__()} method, the class must be called
-without arguments.
-\withsubitem{(object method)}{\ttindex{__init__()}}
-\obindex{class}
-\obindex{class instance}
-\obindex{instance}
-\indexii{class object}{call}
-
-\item[Class instances]
-Class instances are described below. Class instances are callable
-only when the class has a \method{__call__()} method; \code{x(arguments)}
-is a shorthand for \code{x.__call__(arguments)}.
-
-\end{description}
-
-\item[Modules]
-Modules are imported by the \keyword{import} statement (see
-section~\ref{import}, ``The \keyword{import} statement'').%
-\stindex{import}\obindex{module}
-A module object has a namespace implemented by a dictionary object
-(this is the dictionary referenced by the __globals__ attribute of
-functions defined in the module). Attribute references are translated
-to lookups in this dictionary, e.g., \code{m.x} is equivalent to
-\code{m.__dict__["x"]}.
-A module object does not contain the code object used to
-initialize the module (since it isn't needed once the initialization
-is done).
-
-Attribute assignment updates the module's namespace dictionary,
-e.g., \samp{m.x = 1} is equivalent to \samp{m.__dict__["x"] = 1}.
-
-Special read-only attribute: \member{__dict__} is the module's
-namespace as a dictionary object.
-\withsubitem{(module attribute)}{\ttindex{__dict__}}
-
-Predefined (writable) attributes: \member{__name__}
-is the module's name; \member{__doc__} is the
-module's documentation string, or
-\code{None} if unavailable; \member{__file__} is the pathname of the
-file from which the module was loaded, if it was loaded from a file.
-The \member{__file__} attribute is not present for C{} modules that are
-statically linked into the interpreter; for extension modules loaded
-dynamically from a shared library, it is the pathname of the shared
-library file.
-\withsubitem{(module attribute)}{
- \ttindex{__name__}
- \ttindex{__doc__}
- \ttindex{__file__}}
-\indexii{module}{namespace}
-
-\item[Classes]
-Class objects are created by class definitions (see
-section~\ref{class}, ``Class definitions'').
-A class has a namespace implemented by a dictionary object.
-Class attribute references are translated to
-lookups in this dictionary,
-e.g., \samp{C.x} is translated to \samp{C.__dict__["x"]}.
-When the attribute name is not found
-there, the attribute search continues in the base classes. The search
-is depth-first, left-to-right in the order of occurrence in the
-base class list.
-
-When a class attribute reference (for class \class{C}, say)
-would yield a user-defined function object or
-an unbound user-defined method object whose associated class is either
-\class{C} or one of its base classes, it is transformed into an unbound
-user-defined method object whose \member{im_class} attribute is~\class{C}.
-When it would yield a class method object, it is transformed into
-a bound user-defined method object whose \member{im_class} and
-\member{im_self} attributes are both~\class{C}. When it would yield
-a static method object, it is transformed into the object wrapped
-by the static method object. See section~\ref{descriptors} for another
-way in which attributes retrieved from a class may differ from those
-actually contained in its \member{__dict__}.
-\obindex{class}
-\obindex{class instance}
-\obindex{instance}
-\indexii{class object}{call}
-\index{container}
-\obindex{dictionary}
-\indexii{class}{attribute}
-
-Class attribute assignments update the class's dictionary, never the
-dictionary of a base class.
-\indexiii{class}{attribute}{assignment}
-
-A class object can be called (see above) to yield a class instance (see
-below).
-\indexii{class object}{call}
-
-Special attributes: \member{__name__} is the class name;
-\member{__module__} is the module name in which the class was defined;
-\member{__dict__} is the dictionary containing the class's namespace;
-\member{__bases__} is a tuple (possibly empty or a singleton)
-containing the base classes, in the order of their occurrence in the
-base class list; \member{__doc__} is the class's documentation string,
-or None if undefined.
-\withsubitem{(class attribute)}{
- \ttindex{__name__}
- \ttindex{__module__}
- \ttindex{__dict__}
- \ttindex{__bases__}
- \ttindex{__doc__}}
-
-\item[Class instances]
-A class instance is created by calling a class object (see above).
-A class instance has a namespace implemented as a dictionary which
-is the first place in which
-attribute references are searched. When an attribute is not found
-there, and the instance's class has an attribute by that name,
-the search continues with the class attributes. If a class attribute
-is found that is a user-defined function object or an unbound
-user-defined method object whose associated class is the class
-(call it~\class{C}) of the instance for which the attribute reference
-was initiated or one of its bases,
-it is transformed into a bound user-defined method object whose
-\member{im_class} attribute is~\class{C} and whose \member{im_self} attribute
-is the instance. Static method and class method objects are also
-transformed, as if they had been retrieved from class~\class{C};
-see above under ``Classes''. See section~\ref{descriptors} for
-another way in which attributes of a class retrieved via its
-instances may differ from the objects actually stored in the
-class's \member{__dict__}.
-If no class attribute is found, and the object's class has a
-\method{__getattr__()} method, that is called to satisfy the lookup.
-\obindex{class instance}
-\obindex{instance}
-\indexii{class}{instance}
-\indexii{class instance}{attribute}
-
-Attribute assignments and deletions update the instance's dictionary,
-never a class's dictionary. If the class has a \method{__setattr__()} or
-\method{__delattr__()} method, this is called instead of updating the
-instance dictionary directly.
-\indexiii{class instance}{attribute}{assignment}
-
-Class instances can pretend to be numbers, sequences, or mappings if
-they have methods with certain special names. See
-section~\ref{specialnames}, ``Special method names.''
-\obindex{numeric}
-\obindex{sequence}
-\obindex{mapping}
-
-Special attributes: \member{__dict__} is the attribute
-dictionary; \member{__class__} is the instance's class.
-\withsubitem{(instance attribute)}{
- \ttindex{__dict__}
- \ttindex{__class__}}
-
-\item[Files]
-A file\obindex{file} object represents an open file. File objects are
-created by the \function{open()}\bifuncindex{open} built-in function,
-and also by
-\withsubitem{(in module os)}{\ttindex{popen()}}\function{os.popen()},
-\function{os.fdopen()}, and the
-\method{makefile()}\withsubitem{(socket method)}{\ttindex{makefile()}}
-method of socket objects (and perhaps by other functions or methods
-provided by extension modules). The objects
-\ttindex{sys.stdin}\code{sys.stdin},
-\ttindex{sys.stdout}\code{sys.stdout} and
-\ttindex{sys.stderr}\code{sys.stderr} are initialized to file objects
-corresponding to the interpreter's standard\index{stdio} input, output
-and error streams. See the \citetitle[../lib/lib.html]{Python Library
-Reference} for complete documentation of file objects.
-\withsubitem{(in module sys)}{
- \ttindex{stdin}
- \ttindex{stdout}
- \ttindex{stderr}}
-
-
-\item[Internal types]
-A few types used internally by the interpreter are exposed to the user.
-Their definitions may change with future versions of the interpreter,
-but they are mentioned here for completeness.
-\index{internal type}
-\index{types, internal}
-
-\begin{description}
-
-\item[Code objects]
-Code objects represent \emph{byte-compiled} executable Python code, or
-\emph{bytecode}.
-The difference between a code
-object and a function object is that the function object contains an
-explicit reference to the function's globals (the module in which it
-was defined), while a code object contains no context;
-also the default argument values are stored in the function object,
-not in the code object (because they represent values calculated at
-run-time). Unlike function objects, code objects are immutable and
-contain no references (directly or indirectly) to mutable objects.
-\index{bytecode}
-\obindex{code}
-
-Special read-only attributes: \member{co_name} gives the function
-name; \member{co_argcount} is the number of positional arguments
-(including arguments with default values); \member{co_nlocals} is the
-number of local variables used by the function (including arguments);
-\member{co_varnames} is a tuple containing the names of the local
-variables (starting with the argument names); \member{co_cellvars} is
-a tuple containing the names of local variables that are referenced by
-nested functions; \member{co_freevars} is a tuple containing the names
-of free variables; \member{co_code} is a string representing the
-sequence of bytecode instructions;
-\member{co_consts} is a tuple containing the literals used by the
-bytecode; \member{co_names} is a tuple containing the names used by
-the bytecode; \member{co_filename} is the filename from which the code
-was compiled; \member{co_firstlineno} is the first line number of the
-function; \member{co_lnotab} is a string encoding the mapping from
-byte code offsets to line numbers (for details see the source code of
-the interpreter); \member{co_stacksize} is the required stack size
-(including local variables); \member{co_flags} is an integer encoding
-a number of flags for the interpreter.
-
-\withsubitem{(code object attribute)}{
- \ttindex{co_argcount}
- \ttindex{co_code}
- \ttindex{co_consts}
- \ttindex{co_filename}
- \ttindex{co_firstlineno}
- \ttindex{co_flags}
- \ttindex{co_lnotab}
- \ttindex{co_name}
- \ttindex{co_names}
- \ttindex{co_nlocals}
- \ttindex{co_stacksize}
- \ttindex{co_varnames}
- \ttindex{co_cellvars}
- \ttindex{co_freevars}}
-
-The following flag bits are defined for \member{co_flags}: bit
-\code{0x04} is set if the function uses the \samp{*arguments} syntax
-to accept an arbitrary number of positional arguments; bit
-\code{0x08} is set if the function uses the \samp{**keywords} syntax
-to accept arbitrary keyword arguments; bit \code{0x20} is set if the
-function is a generator.
-\obindex{generator}
-
-Future feature declarations (\samp{from __future__ import division})
-also use bits in \member{co_flags} to indicate whether a code object
-was compiled with a particular feature enabled: bit \code{0x2000} is
-set if the function was compiled with future division enabled; bits
-\code{0x10} and \code{0x1000} were used in earlier versions of Python.
-
-Other bits in \member{co_flags} are reserved for internal use.
-
-If\index{documentation string} a code object represents a function,
-the first item in
-\member{co_consts} is the documentation string of the function, or
-\code{None} if undefined.
-
-\item[Frame objects]
-Frame objects represent execution frames. They may occur in traceback
-objects (see below).
-\obindex{frame}
-
-Special read-only attributes: \member{f_back} is to the previous
-stack frame (towards the caller), or \code{None} if this is the bottom
-stack frame; \member{f_code} is the code object being executed in this
-frame; \member{f_locals} is the dictionary used to look up local
-variables; \member{f_globals} is used for global variables;
-\member{f_builtins} is used for built-in (intrinsic) names;
- \member{f_lasti} gives the precise instruction (this is an index into
- the bytecode string of the code object).
-\withsubitem{(frame attribute)}{
- \ttindex{f_back}
- \ttindex{f_code}
- \ttindex{f_globals}
- \ttindex{f_locals}
- \ttindex{f_lasti}
- \ttindex{f_builtins}}
-
-Special writable attributes: \member{f_trace}, if not \code{None}, is
-a function called at the start of each source code line (this is used
-by the debugger); \member{f_exc_type}, \member{f_exc_value},
-\member{f_exc_traceback} represent the last exception raised in the
-parent frame provided another exception was ever raised in the current
-frame (in all other cases they are None); \member{f_lineno} is the
-current line number of the frame --- writing to this from within a
-trace function jumps to the given line (only for the bottom-most
-frame). A debugger can implement a Jump command (aka Set Next
-Statement) by writing to f_lineno.
-\withsubitem{(frame attribute)}{
- \ttindex{f_trace}
- \ttindex{f_exc_type}
- \ttindex{f_exc_value}
- \ttindex{f_exc_traceback}
- \ttindex{f_lineno}}
-
-\item[Traceback objects] \label{traceback}
-Traceback objects represent a stack trace of an exception. A
-traceback object is created when an exception occurs. When the search
-for an exception handler unwinds the execution stack, at each unwound
-level a traceback object is inserted in front of the current
-traceback. When an exception handler is entered, the stack trace is
-made available to the program.
-(See section~\ref{try}, ``The \code{try} statement.'')
-It is accessible as the third
-item of the tuple returned by \code{sys.exc_info()}.
-When the program contains no suitable handler, the stack trace is written
-(nicely formatted) to the standard error stream; if the interpreter is
-interactive, it is also made available to the user as
-\code{sys.last_traceback}.
-\obindex{traceback}
-\indexii{stack}{trace}
-\indexii{exception}{handler}
-\indexii{execution}{stack}
-\withsubitem{(in module sys)}{
- \ttindex{exc_info}
- \ttindex{exc_traceback}
- \ttindex{last_traceback}}
-\ttindex{sys.exc_info}
-\ttindex{sys.last_traceback}
-
-Special read-only attributes: \member{tb_next} is the next level in the
-stack trace (towards the frame where the exception occurred), or
-\code{None} if there is no next level; \member{tb_frame} points to the
-execution frame of the current level; \member{tb_lineno} gives the line
-number where the exception occurred; \member{tb_lasti} indicates the
-precise instruction. The line number and last instruction in the
-traceback may differ from the line number of its frame object if the
-exception occurred in a \keyword{try} statement with no matching
-except clause or with a finally clause.
-\withsubitem{(traceback attribute)}{
- \ttindex{tb_next}
- \ttindex{tb_frame}
- \ttindex{tb_lineno}
- \ttindex{tb_lasti}}
-\stindex{try}
-
-\item[Slice objects]
-Slice objects are used to represent slices when \emph{extended slice
-syntax} is used. This is a slice using two colons, or multiple slices
-or ellipses separated by commas, e.g., \code{a[i:j:step]}, \code{a[i:j,
-k:l]}, or \code{a[..., i:j]}. They are also created by the built-in
-\function{slice()}\bifuncindex{slice} function.
-
-Special read-only attributes: \member{start} is the lower bound;
-\member{stop} is the upper bound; \member{step} is the step value; each is
-\code{None} if omitted. These attributes can have any type.
-\withsubitem{(slice object attribute)}{
- \ttindex{start}
- \ttindex{stop}
- \ttindex{step}}
-
-Slice objects support one method:
-
-\begin{methoddesc}[slice]{indices}{self, length}
-This method takes a single integer argument \var{length} and computes
-information about the extended slice that the slice object would
-describe if applied to a sequence of \var{length} items. It returns a
-tuple of three integers; respectively these are the \var{start} and
-\var{stop} indices and the \var{step} or stride length of the slice.
-Missing or out-of-bounds indices are handled in a manner consistent
-with regular slices.
-\versionadded{2.3}
-\end{methoddesc}
-
-\item[Static method objects]
-Static method objects provide a way of defeating the transformation
-of function objects to method objects described above. A static method
-object is a wrapper around any other object, usually a user-defined
-method object. When a static method object is retrieved from a class
-or a class instance, the object actually returned is the wrapped object,
-which is not subject to any further transformation. Static method
-objects are not themselves callable, although the objects they
-wrap usually are. Static method objects are created by the built-in
-\function{staticmethod()} constructor.
-
-\item[Class method objects]
-A class method object, like a static method object, is a wrapper
-around another object that alters the way in which that object
-is retrieved from classes and class instances. The behaviour of
-class method objects upon such retrieval is described above,
-under ``User-defined methods''. Class method objects are created
-by the built-in \function{classmethod()} constructor.
-
-\end{description} % Internal types
-
-\end{description} % Types
-
-%=========================================================================
-\section{New-style and classic classes}
-
-Classes and instances come in two flavors: old-style or classic, and new-style.
-
-Up to Python 2.1, old-style classes were the only flavour available to the
-user. The concept of (old-style) class is unrelated to the concept of type: if
-\var{x} is an instance of an old-style class, then \code{x.__class__}
-designates the class of \var{x}, but \code{type(x)} is always \code{<type
-'instance'>}. This reflects the fact that all old-style instances,
-independently of their class, are implemented with a single built-in type,
-called \code{instance}.
-
-New-style classes were introduced in Python 2.2 to unify classes and types. A
-new-style class neither more nor less than a user-defined type. If \var{x} is
-an instance of a new-style class, then \code{type(x)} is the same as
-\code{x.__class__}.
-
-The major motivation for introducing new-style classes is to provide a unified
-object model with a full meta-model. It also has a number of immediate
-benefits, like the ability to subclass most built-in types, or the introduction
-of "descriptors", which enable computed properties.
-
-For compatibility reasons, classes are still old-style by default. New-style
-classes are created by specifying another new-style class (i.e.\ a type) as a
-parent class, or the "top-level type" \class{object} if no other parent is
-needed. The behaviour of new-style classes differs from that of old-style
-classes in a number of important details in addition to what \function{type}
-returns. Some of these changes are fundamental to the new object model, like
-the way special methods are invoked. Others are "fixes" that could not be
-implemented before for compatibility concerns, like the method resolution order
-in case of multiple inheritance.
-
-This manual is not up-to-date with respect to new-style classes. For now,
-please see \url{http://www.python.org/doc/newstyle.html} for more information.
-
-The plan is to eventually drop old-style classes, leaving only the semantics of
-new-style classes. This change will probably only be feasible in Python 3.0.
-\index{class}{new-style}
-\index{class}{classic}
-\index{class}{old-style}
-
-%=========================================================================
-\section{Special method names\label{specialnames}}
-
-A class can implement certain operations that are invoked by special
-syntax (such as arithmetic operations or subscripting and slicing) by
-defining methods with special names.\indexii{operator}{overloading}
-This is Python's approach to \dfn{operator overloading}, allowing
-classes to define their own behavior with respect to language
-operators. For instance, if a class defines
-a method named \method{__getitem__()}, and \code{x} is an instance of
-this class, then \code{x[i]} is equivalent\footnote{This, and other
-statements, are only roughly true for instances of new-style
-classes.} to
-\code{x.__getitem__(i)}. Except where mentioned, attempts to execute
-an operation raise an exception when no appropriate method is defined.
-\withsubitem{(mapping object method)}{\ttindex{__getitem__()}}
-
-When implementing a class that emulates any built-in type, it is
-important that the emulation only be implemented to the degree that it
-makes sense for the object being modelled. For example, some
-sequences may work well with retrieval of individual elements, but
-extracting a slice may not make sense. (One example of this is the
-\class{NodeList} interface in the W3C's Document Object Model.)
-
-
-\subsection{Basic customization\label{customization}}
-
-\begin{methoddesc}[object]{__new__}{cls\optional{, \moreargs}}
-Called to create a new instance of class \var{cls}. \method{__new__()}
-is a static method (special-cased so you need not declare it as such)
-that takes the class of which an instance was requested as its first
-argument. The remaining arguments are those passed to the object
-constructor expression (the call to the class). The return value of
-\method{__new__()} should be the new object instance (usually an
-instance of \var{cls}).
-
-Typical implementations create a new instance of the class by invoking
-the superclass's \method{__new__()} method using
-\samp{super(\var{currentclass}, \var{cls}).__new__(\var{cls}[, ...])}
-with appropriate arguments and then modifying the newly-created instance
-as necessary before returning it.
-
-If \method{__new__()} returns an instance of \var{cls}, then the new
-instance's \method{__init__()} method will be invoked like
-\samp{__init__(\var{self}[, ...])}, where \var{self} is the new instance
-and the remaining arguments are the same as were passed to
-\method{__new__()}.
-
-If \method{__new__()} does not return an instance of \var{cls}, then the
-new instance's \method{__init__()} method will not be invoked.
-
-\method{__new__()} is intended mainly to allow subclasses of
-immutable types (like int, str, or tuple) to customize instance
-creation.
-\end{methoddesc}
-
-\begin{methoddesc}[object]{__init__}{self\optional{, \moreargs}}
-Called\indexii{class}{constructor} when the instance is created. The
-arguments are those passed to the class constructor expression. If a
-base class has an \method{__init__()} method, the derived class's
-\method{__init__()} method, if any, must explicitly call it to ensure proper
-initialization of the base class part of the instance; for example:
-\samp{BaseClass.__init__(\var{self}, [\var{args}...])}. As a special
-constraint on constructors, no value may be returned; doing so will
-cause a \exception{TypeError} to be raised at runtime.
-\end{methoddesc}
-
-
-\begin{methoddesc}[object]{__del__}{self}
-Called when the instance is about to be destroyed. This is also
-called a destructor\index{destructor}. If a base class
-has a \method{__del__()} method, the derived class's \method{__del__()}
-method, if any,
-must explicitly call it to ensure proper deletion of the base class
-part of the instance. Note that it is possible (though not recommended!)
-for the \method{__del__()}
-method to postpone destruction of the instance by creating a new
-reference to it. It may then be called at a later time when this new
-reference is deleted. It is not guaranteed that
-\method{__del__()} methods are called for objects that still exist when
-the interpreter exits.
-\stindex{del}
-
-\begin{notice}
-\samp{del x} doesn't directly call
-\code{x.__del__()} --- the former decrements the reference count for
-\code{x} by one, and the latter is only called when \code{x}'s reference
-count reaches zero. Some common situations that may prevent the
-reference count of an object from going to zero include: circular
-references between objects (e.g., a doubly-linked list or a tree data
-structure with parent and child pointers); a reference to the object
-on the stack frame of a function that caught an exception (the
-traceback stored in \code{sys.exc_info()[2]} keeps the stack frame
-alive); or a reference to the object on the stack frame that raised an
-unhandled exception in interactive mode (the traceback stored in
-\code{sys.last_traceback} keeps the stack frame alive). The first
-situation can only be remedied by explicitly breaking the cycles; the
-latter two situations can be resolved by storing \code{None} in
-\code{sys.last_traceback}. Circular
-references which are garbage are detected when the option cycle
-detector is enabled (it's on by default), but can only be cleaned up
-if there are no Python-level \method{__del__()} methods involved.
-Refer to the documentation for the \ulink{\module{gc}
-module}{../lib/module-gc.html} for more information about how
-\method{__del__()} methods are handled by the cycle detector,
-particularly the description of the \code{garbage} value.
-\end{notice}
-
-\begin{notice}[warning]
-Due to the precarious circumstances under which
-\method{__del__()} methods are invoked, exceptions that occur during their
-execution are ignored, and a warning is printed to \code{sys.stderr}
-instead. Also, when \method{__del__()} is invoked in response to a module
-being deleted (e.g., when execution of the program is done), other
-globals referenced by the \method{__del__()} method may already have been
-deleted. For this reason, \method{__del__()} methods should do the
-absolute minimum needed to maintain external invariants. Starting with
-version 1.5, Python guarantees that globals whose name begins with a single
-underscore are deleted from their module before other globals are deleted;
-if no other references to such globals exist, this may help in assuring that
-imported modules are still available at the time when the
-\method{__del__()} method is called.
-\end{notice}
-\end{methoddesc}
-
-\begin{methoddesc}[object]{__repr__}{self}
-Called by the \function{repr()}\bifuncindex{repr} built-in function
-and by string conversions (reverse quotes) to compute the ``official''
-string representation of an object. If at all possible, this should
-look like a valid Python expression that could be used to recreate an
-object with the same value (given an appropriate environment). If
-this is not possible, a string of the form \samp{<\var{...some useful
-description...}>} should be returned. The return value must be a
-string object.
-If a class defines \method{__repr__()} but not \method{__str__()},
-then \method{__repr__()} is also used when an ``informal'' string
-representation of instances of that class is required.
-
-This is typically used for debugging, so it is important that the
-representation is information-rich and unambiguous.
-\indexii{string}{conversion}
-\indexii{reverse}{quotes}
-\indexii{backward}{quotes}
-\index{back-quotes}
-\end{methoddesc}
-
-\begin{methoddesc}[object]{__str__}{self}
-Called by the \function{str()}\bifuncindex{str} built-in function and
-by the \keyword{print}\stindex{print} statement to compute the
-``informal'' string representation of an object. This differs from
-\method{__repr__()} in that it does not have to be a valid Python
-expression: a more convenient or concise representation may be used
-instead. The return value must be a string object.
-\end{methoddesc}
-
-\begin{methoddesc}[object]{__lt__}{self, other}
-\methodline[object]{__le__}{self, other}
-\methodline[object]{__eq__}{self, other}
-\methodline[object]{__ne__}{self, other}
-\methodline[object]{__gt__}{self, other}
-\methodline[object]{__ge__}{self, other}
-\versionadded{2.1}
-These are the so-called ``rich comparison'' methods, and are called
-for comparison operators in preference to \method{__cmp__()} below.
-The correspondence between operator symbols and method names is as
-follows:
-\code{\var{x}<\var{y}} calls \code{\var{x}.__lt__(\var{y})},
-\code{\var{x}<=\var{y}} calls \code{\var{x}.__le__(\var{y})},
-\code{\var{x}==\var{y}} calls \code{\var{x}.__eq__(\var{y})},
-\code{\var{x}!=\var{y}} calls \code{\var{x}.__ne__(\var{y})},
-\code{\var{x}>\var{y}} calls \code{\var{x}.__gt__(\var{y})}, and
-\code{\var{x}>=\var{y}} calls \code{\var{x}.__ge__(\var{y})}.
-
-A rich comparison method may return the singleton \code{NotImplemented} if it
-does not implement the operation for a given pair of arguments.
-By convention, \code{False} and \code{True} are returned for a successful
-comparison. However, these methods can return any value, so if the
-comparison operator is used in a Boolean context (e.g., in the condition
-of an \code{if} statement), Python will call \function{bool()} on the
-value to determine if the result is true or false.
-
-There are no implied relationships among the comparison operators.
-The truth of \code{\var{x}==\var{y}} does not imply that \code{\var{x}!=\var{y}}
-is false. Accordingly, when defining \method{__eq__()}, one should also
-define \method{__ne__()} so that the operators will behave as expected.
-
-There are no reflected (swapped-argument) versions of these methods
-(to be used when the left argument does not support the operation but
-the right argument does); rather, \method{__lt__()} and
-\method{__gt__()} are each other's reflection, \method{__le__()} and
-\method{__ge__()} are each other's reflection, and \method{__eq__()}
-and \method{__ne__()} are their own reflection.
-
-Arguments to rich comparison methods are never coerced.
-\end{methoddesc}
-
-\begin{methoddesc}[object]{__cmp__}{self, other}
-Called by comparison operations if rich comparison (see above) is not
-defined. Should return a negative integer if \code{self < other},
-zero if \code{self == other}, a positive integer if \code{self >
-other}. If no \method{__cmp__()}, \method{__eq__()} or
-\method{__ne__()} operation is defined, class instances are compared
-by object identity (``address''). See also the description of
-\method{__hash__()} for some important notes on creating objects which
-support custom comparison operations and are usable as dictionary
-keys.
-(Note: the restriction that exceptions are not propagated by
-\method{__cmp__()} has been removed since Python 1.5.)
-\bifuncindex{cmp}
-\index{comparisons}
-\end{methoddesc}
-
-\begin{methoddesc}[object]{__rcmp__}{self, other}
- \versionchanged[No longer supported]{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[object]{__hash__}{self}
-Called for the key object for dictionary \obindex{dictionary}
-operations, and by the built-in function
-\function{hash()}\bifuncindex{hash}. Should return a 32-bit integer
-usable as a hash value
-for dictionary operations. The only required property is that objects
-which compare equal have the same hash value; it is advised to somehow
-mix together (e.g., using exclusive or) the hash values for the
-components of the object that also play a part in comparison of
-objects. If a class does not define a \method{__cmp__()} method it should
-not define a \method{__hash__()} operation either; if it defines
-\method{__cmp__()} or \method{__eq__()} but not \method{__hash__()},
-its instances will not be usable as dictionary keys. If a class
-defines mutable objects and implements a \method{__cmp__()} or
-\method{__eq__()} method, it should not implement \method{__hash__()},
-since the dictionary implementation requires that a key's hash value
-is immutable (if the object's hash value changes, it will be in the
-wrong hash bucket).
-
-\versionchanged[\method{__hash__()} may now also return a long
-integer object; the 32-bit integer is then derived from the hash
-of that object]{2.5}
-
-\withsubitem{(object method)}{\ttindex{__cmp__()}}
-\end{methoddesc}
-
-\begin{methoddesc}[object]{__bool__}{self}
-Called to implement truth value testing, and the built-in operation
-\code{bool()}; should return \code{False} or \code{True}.
-When this method is not defined, \method{__len__()} is
-called, if it is defined (see below) and \code{True} is returned when
-the length is not zero. If a class defines neither
-\method{__len__()} nor \method{__bool__()}, all its instances are
-considered true.
-\withsubitem{(mapping object method)}{\ttindex{__len__()}}
-\end{methoddesc}
-
-\begin{methoddesc}[object]{__unicode__}{self}
-Called to implement \function{unicode()}\bifuncindex{unicode} builtin;
-should return a Unicode object. When this method is not defined, string
-conversion is attempted, and the result of string conversion is converted
-to Unicode using the system default encoding.
-\end{methoddesc}
-
-
-\subsection{Customizing attribute access\label{attribute-access}}
-
-The following methods can be defined to customize the meaning of
-attribute access (use of, assignment to, or deletion of \code{x.name})
-for class instances.
-
-\begin{methoddesc}[object]{__getattr__}{self, name}
-Called when an attribute lookup has not found the attribute in the
-usual places (i.e. it is not an instance attribute nor is it found in
-the class tree for \code{self}). \code{name} is the attribute name.
-This method should return the (computed) attribute value or raise an
-\exception{AttributeError} exception.
-
-Note that if the attribute is found through the normal mechanism,
-\method{__getattr__()} is not called. (This is an intentional
-asymmetry between \method{__getattr__()} and \method{__setattr__()}.)
-This is done both for efficiency reasons and because otherwise
-\method{__setattr__()} would have no way to access other attributes of
-the instance. Note that at least for instance variables, you can fake
-total control by not inserting any values in the instance attribute
-dictionary (but instead inserting them in another object). See the
-\method{__getattribute__()} method below for a way to actually get
-total control in new-style classes.
-\withsubitem{(object method)}{\ttindex{__setattr__()}}
-\end{methoddesc}
-
-\begin{methoddesc}[object]{__setattr__}{self, name, value}
-Called when an attribute assignment is attempted. This is called
-instead of the normal mechanism (i.e.\ store the value in the instance
-dictionary). \var{name} is the attribute name, \var{value} is the
-value to be assigned to it.
-
-If \method{__setattr__()} wants to assign to an instance attribute, it
-should not simply execute \samp{self.\var{name} = value} --- this
-would cause a recursive call to itself. Instead, it should insert the
-value in the dictionary of instance attributes, e.g.,
-\samp{self.__dict__[\var{name}] = value}. For new-style classes,
-rather than accessing the instance dictionary, it should call the base
-class method with the same name, for example,
-\samp{object.__setattr__(self, name, value)}.
-\withsubitem{(instance attribute)}{\ttindex{__dict__}}
-\end{methoddesc}
-
-\begin{methoddesc}[object]{__delattr__}{self, name}
-Like \method{__setattr__()} but for attribute deletion instead of
-assignment. This should only be implemented if \samp{del
-obj.\var{name}} is meaningful for the object.
-\end{methoddesc}
-
-\subsubsection{More attribute access for new-style classes \label{new-style-attribute-access}}
-
-The following methods only apply to new-style classes.
-
-\begin{methoddesc}[object]{__getattribute__}{self, name}
-Called unconditionally to implement attribute accesses for instances
-of the class. If the class also defines \method{__getattr__()}, the latter
-will not be called unless \method{__getattribute__()} either calls it
-explicitly or raises an \exception{AttributeError}.
-This method should return the (computed) attribute
-value or raise an \exception{AttributeError} exception.
-In order to avoid infinite recursion in this method, its
-implementation should always call the base class method with the same
-name to access any attributes it needs, for example,
-\samp{object.__getattribute__(self, name)}.
-\end{methoddesc}
-
-\subsubsection{Implementing Descriptors \label{descriptors}}
-
-The following methods only apply when an instance of the class
-containing the method (a so-called \emph{descriptor} class) appears in
-the class dictionary of another new-style class, known as the
-\emph{owner} class. In the examples below, ``the attribute'' refers to
-the attribute whose name is the key of the property in the owner
-class' \code{__dict__}. Descriptors can only be implemented as
-new-style classes themselves.
-
-\begin{methoddesc}[object]{__get__}{self, instance, owner}
-Called to get the attribute of the owner class (class attribute access)
-or of an instance of that class (instance attribute access).
-\var{owner} is always the owner class, while \var{instance} is the
-instance that the attribute was accessed through, or \code{None} when
-the attribute is accessed through the \var{owner}. This method should
-return the (computed) attribute value or raise an
-\exception{AttributeError} exception.
-\end{methoddesc}
-
-\begin{methoddesc}[object]{__set__}{self, instance, value}
-Called to set the attribute on an instance \var{instance} of the owner
-class to a new value, \var{value}.
-\end{methoddesc}
-
-\begin{methoddesc}[object]{__delete__}{self, instance}
-Called to delete the attribute on an instance \var{instance} of the
-owner class.
-\end{methoddesc}
-
-
-\subsubsection{Invoking Descriptors \label{descriptor-invocation}}
-
-In general, a descriptor is an object attribute with ``binding behavior'',
-one whose attribute access has been overridden by methods in the descriptor
-protocol: \method{__get__()}, \method{__set__()}, and \method{__delete__()}.
-If any of those methods are defined for an object, it is said to be a
-descriptor.
-
-The default behavior for attribute access is to get, set, or delete the
-attribute from an object's dictionary. For instance, \code{a.x} has a
-lookup chain starting with \code{a.__dict__['x']}, then
-\code{type(a).__dict__['x']}, and continuing
-through the base classes of \code{type(a)} excluding metaclasses.
-
-However, if the looked-up value is an object defining one of the descriptor
-methods, then Python may override the default behavior and invoke the
-descriptor method instead. Where this occurs in the precedence chain depends
-on which descriptor methods were defined and how they were called. Note that
-descriptors are only invoked for new style objects or classes
-(ones that subclass \class{object()} or \class{type()}).
-
-The starting point for descriptor invocation is a binding, \code{a.x}.
-How the arguments are assembled depends on \code{a}:
-
-\begin{itemize}
-
- \item[Direct Call] The simplest and least common call is when user code
- directly invokes a descriptor method: \code{x.__get__(a)}.
-
- \item[Instance Binding] If binding to a new-style object instance,
- \code{a.x} is transformed into the call:
- \code{type(a).__dict__['x'].__get__(a, type(a))}.
-
- \item[Class Binding] If binding to a new-style class, \code{A.x}
- is transformed into the call: \code{A.__dict__['x'].__get__(None, A)}.
-
- \item[Super Binding] If \code{a} is an instance of \class{super},
- then the binding \code{super(B, obj).m()} searches
- \code{obj.__class__.__mro__} for the base class \code{A} immediately
- preceding \code{B} and then invokes the descriptor with the call:
- \code{A.__dict__['m'].__get__(obj, A)}.
-
-\end{itemize}
-
-For instance bindings, the precedence of descriptor invocation depends
-on the which descriptor methods are defined. Data descriptors define
-both \method{__get__()} and \method{__set__()}. Non-data descriptors have
-just the \method{__get__()} method. Data descriptors always override
-a redefinition in an instance dictionary. In contrast, non-data
-descriptors can be overridden by instances.
-
-Python methods (including \function{staticmethod()} and \function{classmethod()})
-are implemented as non-data descriptors. Accordingly, instances can
-redefine and override methods. This allows individual instances to acquire
-behaviors that differ from other instances of the same class.
-
-The \function{property()} function is implemented as a data descriptor.
-Accordingly, instances cannot override the behavior of a property.
-
-
-\subsubsection{__slots__\label{slots}}
-
-By default, instances of both old and new-style classes have a dictionary
-for attribute storage. This wastes space for objects having very few instance
-variables. The space consumption can become acute when creating large numbers
-of instances.
-
-The default can be overridden by defining \var{__slots__} in a new-style class
-definition. The \var{__slots__} declaration takes a sequence of instance
-variables and reserves just enough space in each instance to hold a value
-for each variable. Space is saved because \var{__dict__} is not created for
-each instance.
-
-\begin{datadesc}{__slots__}
-This class variable can be assigned a string, iterable, or sequence of strings
-with variable names used by instances. If defined in a new-style class,
-\var{__slots__} reserves space for the declared variables
-and prevents the automatic creation of \var{__dict__} and \var{__weakref__}
-for each instance.
-\versionadded{2.2}
-\end{datadesc}
-
-\noindent
-Notes on using \var{__slots__}
-
-\begin{itemize}
-
-\item Without a \var{__dict__} variable, instances cannot be assigned new
-variables not listed in the \var{__slots__} definition. Attempts to assign
-to an unlisted variable name raises \exception{AttributeError}. If dynamic
-assignment of new variables is desired, then add \code{'__dict__'} to the
-sequence of strings in the \var{__slots__} declaration.
-\versionchanged[Previously, adding \code{'__dict__'} to the \var{__slots__}
-declaration would not enable the assignment of new attributes not
-specifically listed in the sequence of instance variable names]{2.3}
-
-\item Without a \var{__weakref__} variable for each instance, classes
-defining \var{__slots__} do not support weak references to its instances.
-If weak reference support is needed, then add \code{'__weakref__'} to the
-sequence of strings in the \var{__slots__} declaration.
-\versionchanged[Previously, adding \code{'__weakref__'} to the \var{__slots__}
-declaration would not enable support for weak references]{2.3}
-
-\item \var{__slots__} are implemented at the class level by creating
-descriptors (\ref{descriptors}) for each variable name. As a result,
-class attributes cannot be used to set default values for instance
-variables defined by \var{__slots__}; otherwise, the class attribute would
-overwrite the descriptor assignment.
-
-\item If a class defines a slot also defined in a base class, the instance
-variable defined by the base class slot is inaccessible (except by retrieving
-its descriptor directly from the base class). This renders the meaning of the
-program undefined. In the future, a check may be added to prevent this.
-
-\item The action of a \var{__slots__} declaration is limited to the class
-where it is defined. As a result, subclasses will have a \var{__dict__}
-unless they also define \var{__slots__}.
-
-\item \var{__slots__} do not work for classes derived from ``variable-length''
-built-in types such as \class{long}, \class{str} and \class{tuple}.
-
-\item Any non-string iterable may be assigned to \var{__slots__}.
-Mappings may also be used; however, in the future, special meaning may
-be assigned to the values corresponding to each key.
-
-\item \var{__class__} assignment works only if both classes have the
-same \var{__slots__}.
-\versionchanged[Previously, \var{__class__} assignment raised an error
-if either new or old class had \var{__slots__}]{2.6}
-
-\end{itemize}
-
-
-\subsection{Customizing class creation\label{metaclasses}}
-
-By default, new-style classes are constructed using \function{type()}.
-A class definition is read into a separate namespace and the value
-of class name is bound to the result of \code{type(name, bases, dict)}.
-
-When the class definition is read, if \var{__metaclass__} is defined
-then the callable assigned to it will be called instead of \function{type()}.
-The allows classes or functions to be written which monitor or alter the class
-creation process:
-
-\begin{itemize}
-\item Modifying the class dictionary prior to the class being created.
-\item Returning an instance of another class -- essentially performing
-the role of a factory function.
-\end{itemize}
-
-\begin{datadesc}{__metaclass__}
-This variable can be any callable accepting arguments for \code{name},
-\code{bases}, and \code{dict}. Upon class creation, the callable is
-used instead of the built-in \function{type()}.
-\versionadded{2.2}
-\end{datadesc}
-
-The appropriate metaclass is determined by the following precedence rules:
-
-\begin{itemize}
-
-\item If \code{dict['__metaclass__']} exists, it is used.
-
-\item Otherwise, if there is at least one base class, its metaclass is used
-(this looks for a \var{__class__} attribute first and if not found, uses its
-type).
-
-\item Otherwise, if a global variable named __metaclass__ exists, it is used.
-
-\item Otherwise, the old-style, classic metaclass (types.ClassType) is used.
-
-\end{itemize}
-
-The potential uses for metaclasses are boundless. Some ideas that have
-been explored including logging, interface checking, automatic delegation,
-automatic property creation, proxies, frameworks, and automatic resource
-locking/synchronization.
-
-
-\subsection{Emulating callable objects\label{callable-types}}
-
-\begin{methoddesc}[object]{__call__}{self\optional{, args...}}
-Called when the instance is ``called'' as a function; if this method
-is defined, \code{\var{x}(arg1, arg2, ...)} is a shorthand for
-\code{\var{x}.__call__(arg1, arg2, ...)}.
-\indexii{call}{instance}
-\end{methoddesc}
-
-
-\subsection{Emulating container types\label{sequence-types}}
-
-The following methods can be defined to implement container
-objects. Containers usually are sequences (such as lists or tuples)
-or mappings (like dictionaries), but can represent other containers as
-well. The first set of methods is used either to emulate a
-sequence or to emulate a mapping; the difference is that for a
-sequence, the allowable keys should be the integers \var{k} for which
-\code{0 <= \var{k} < \var{N}} where \var{N} is the length of the
-sequence, or slice objects, which define a range of items. (For backwards
-compatibility, the method \method{__getslice__()} (see below) can also be
-defined to handle simple, but not extended slices.) It is also recommended
-that mappings provide the methods \method{keys()}, \method{values()},
-\method{items()}, \method{has_key()}, \method{get()}, \method{clear()},
-\method{setdefault()}, \method{iterkeys()}, \method{itervalues()},
-\method{iteritems()}, \method{pop()}, \method{popitem()},
-\method{copy()}, and \method{update()} behaving similar to those for
-Python's standard dictionary objects. The \module{UserDict} module
-provides a \class{DictMixin} class to help create those methods
-from a base set of \method{__getitem__()}, \method{__setitem__()},
-\method{__delitem__()}, and \method{keys()}.
-Mutable sequences should provide
-methods \method{append()}, \method{count()}, \method{index()},
-\method{extend()},
-\method{insert()}, \method{pop()}, \method{remove()}, \method{reverse()}
-and \method{sort()}, like Python standard list objects. Finally,
-sequence types should implement addition (meaning concatenation) and
-multiplication (meaning repetition) by defining the methods
-\method{__add__()}, \method{__radd__()}, \method{__iadd__()},
-\method{__mul__()}, \method{__rmul__()} and \method{__imul__()} described
-below; they should not define other numerical
-operators. It is recommended that both mappings and sequences
-implement the \method{__contains__()} method to allow efficient use of
-the \code{in} operator; for mappings, \code{in} should be equivalent
-of \method{has_key()}; for sequences, it should search through the
-values. It is further recommended that both mappings and sequences
-implement the \method{__iter__()} method to allow efficient iteration
-through the container; for mappings, \method{__iter__()} should be
-the same as \method{iterkeys()}; for sequences, it should iterate
-through the values.
-\withsubitem{(mapping object method)}{
- \ttindex{keys()}
- \ttindex{values()}
- \ttindex{items()}
- \ttindex{iterkeys()}
- \ttindex{itervalues()}
- \ttindex{iteritems()}
- \ttindex{has_key()}
- \ttindex{get()}
- \ttindex{setdefault()}
- \ttindex{pop()}
- \ttindex{popitem()}
- \ttindex{clear()}
- \ttindex{copy()}
- \ttindex{update()}
- \ttindex{__contains__()}}
-\withsubitem{(sequence object method)}{
- \ttindex{append()}
- \ttindex{count()}
- \ttindex{extend()}
- \ttindex{index()}
- \ttindex{insert()}
- \ttindex{pop()}
- \ttindex{remove()}
- \ttindex{reverse()}
- \ttindex{sort()}
- \ttindex{__add__()}
- \ttindex{__radd__()}
- \ttindex{__iadd__()}
- \ttindex{__mul__()}
- \ttindex{__rmul__()}
- \ttindex{__imul__()}
- \ttindex{__contains__()}
- \ttindex{__iter__()}}
-
-\begin{methoddesc}[container object]{__len__}{self}
-Called to implement the built-in function
-\function{len()}\bifuncindex{len}. Should return the length of the
-object, an integer \code{>=} 0. Also, an object that doesn't define a
-\method{__bool__()} method and whose \method{__len__()} method
-returns zero is considered to be false in a Boolean context.
-\withsubitem{(object method)}{\ttindex{__bool__()}}
-\end{methoddesc}
-
-\begin{methoddesc}[container object]{__getitem__}{self, key}
-Called to implement evaluation of \code{\var{self}[\var{key}]}.
-For sequence types, the accepted keys should be integers and slice
-objects.\obindex{slice} Note that
-the special interpretation of negative indexes (if the class wishes to
-emulate a sequence type) is up to the \method{__getitem__()} method.
-If \var{key} is of an inappropriate type, \exception{TypeError} may be
-raised; if of a value outside the set of indexes for the sequence
-(after any special interpretation of negative values),
-\exception{IndexError} should be raised.
-For mapping types, if \var{key} is missing (not in the container),
-\exception{KeyError} should be raised.
-\note{\keyword{for} loops expect that an
-\exception{IndexError} will be raised for illegal indexes to allow
-proper detection of the end of the sequence.}
-\end{methoddesc}
-
-\begin{methoddesc}[container object]{__setitem__}{self, key, value}
-Called to implement assignment to \code{\var{self}[\var{key}]}. Same
-note as for \method{__getitem__()}. This should only be implemented
-for mappings if the objects support changes to the values for keys, or
-if new keys can be added, or for sequences if elements can be
-replaced. The same exceptions should be raised for improper
-\var{key} values as for the \method{__getitem__()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[container object]{__delitem__}{self, key}
-Called to implement deletion of \code{\var{self}[\var{key}]}. Same
-note as for \method{__getitem__()}. This should only be implemented
-for mappings if the objects support removal of keys, or for sequences
-if elements can be removed from the sequence. The same exceptions
-should be raised for improper \var{key} values as for the
-\method{__getitem__()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[container object]{__iter__}{self}
-This method is called when an iterator is required for a container.
-This method should return a new iterator object that can iterate over
-all the objects in the container. For mappings, it should iterate
-over the keys of the container, and should also be made available as
-the method \method{iterkeys()}.
-
-Iterator objects also need to implement this method; they are required
-to return themselves. For more information on iterator objects, see
-``\ulink{Iterator Types}{../lib/typeiter.html}'' in the
-\citetitle[../lib/lib.html]{Python Library Reference}.
-\end{methoddesc}
-
-The membership test operators (\keyword{in} and \keyword{not in}) are
-normally implemented as an iteration through a sequence. However,
-container objects can supply the following special method with a more
-efficient implementation, which also does not require the object be a
-sequence.
-
-\begin{methoddesc}[container object]{__contains__}{self, item}
-Called to implement membership test operators. Should return true if
-\var{item} is in \var{self}, false otherwise. For mapping objects,
-this should consider the keys of the mapping rather than the values or
-the key-item pairs.
-\end{methoddesc}
-
-
-\subsection{Additional methods for emulation of sequence types
- \label{sequence-methods}}
-
-The following optional methods can be defined to further emulate sequence
-objects. Immutable sequences methods should at most only define
-\method{__getslice__()}; mutable sequences might define all three
-methods.
-
-\begin{methoddesc}[sequence object]{__getslice__}{self, i, j}
-\deprecated{2.0}{Support slice objects as parameters to the
-\method{__getitem__()} method.}
-Called to implement evaluation of \code{\var{self}[\var{i}:\var{j}]}.
-The returned object should be of the same type as \var{self}. Note
-that missing \var{i} or \var{j} in the slice expression are replaced
-by zero or \code{sys.maxint}, respectively. If negative indexes are
-used in the slice, the length of the sequence is added to that index.
-If the instance does not implement the \method{__len__()} method, an
-\exception{AttributeError} is raised.
-No guarantee is made that indexes adjusted this way are not still
-negative. Indexes which are greater than the length of the sequence
-are not modified.
-If no \method{__getslice__()} is found, a slice
-object is created instead, and passed to \method{__getitem__()} instead.
-\end{methoddesc}
-
-\begin{methoddesc}[sequence object]{__setslice__}{self, i, j, sequence}
-Called to implement assignment to \code{\var{self}[\var{i}:\var{j}]}.
-Same notes for \var{i} and \var{j} as for \method{__getslice__()}.
-
-This method is deprecated. If no \method{__setslice__()} is found,
-or for extended slicing of the form
-\code{\var{self}[\var{i}:\var{j}:\var{k}]}, a
-slice object is created, and passed to \method{__setitem__()},
-instead of \method{__setslice__()} being called.
-\end{methoddesc}
-
-\begin{methoddesc}[sequence object]{__delslice__}{self, i, j}
-Called to implement deletion of \code{\var{self}[\var{i}:\var{j}]}.
-Same notes for \var{i} and \var{j} as for \method{__getslice__()}.
-This method is deprecated. If no \method{__delslice__()} is found,
-or for extended slicing of the form
-\code{\var{self}[\var{i}:\var{j}:\var{k}]}, a
-slice object is created, and passed to \method{__delitem__()},
-instead of \method{__delslice__()} being called.
-\end{methoddesc}
-
-Notice that these methods are only invoked when a single slice with a
-single colon is used, and the slice method is available. For slice
-operations involving extended slice notation, or in absence of the
-slice methods, \method{__getitem__()}, \method{__setitem__()} or
-\method{__delitem__()} is called with a slice object as argument.
-
-The following example demonstrate how to make your program or module
-compatible with earlier versions of Python (assuming that methods
-\method{__getitem__()}, \method{__setitem__()} and \method{__delitem__()}
-support slice objects as arguments):
-
-\begin{verbatim}
-class MyClass:
- ...
- def __getitem__(self, index):
- ...
- def __setitem__(self, index, value):
- ...
- def __delitem__(self, index):
- ...
-
- if sys.version_info < (2, 0):
- # They won't be defined if version is at least 2.0 final
-
- def __getslice__(self, i, j):
- return self[max(0, i):max(0, j):]
- def __setslice__(self, i, j, seq):
- self[max(0, i):max(0, j):] = seq
- def __delslice__(self, i, j):
- del self[max(0, i):max(0, j):]
- ...
-\end{verbatim}
-
-Note the calls to \function{max()}; these are necessary because of
-the handling of negative indices before the
-\method{__*slice__()} methods are called. When negative indexes are
-used, the \method{__*item__()} methods receive them as provided, but
-the \method{__*slice__()} methods get a ``cooked'' form of the index
-values. For each negative index value, the length of the sequence is
-added to the index before calling the method (which may still result
-in a negative index); this is the customary handling of negative
-indexes by the built-in sequence types, and the \method{__*item__()}
-methods are expected to do this as well. However, since they should
-already be doing that, negative indexes cannot be passed in; they must
-be constrained to the bounds of the sequence before being passed to
-the \method{__*item__()} methods.
-Calling \code{max(0, i)} conveniently returns the proper value.
-
-
-\subsection{Emulating numeric types\label{numeric-types}}
-
-The following methods can be defined to emulate numeric objects.
-Methods corresponding to operations that are not supported by the
-particular kind of number implemented (e.g., bitwise operations for
-non-integral numbers) should be left undefined.
-
-\begin{methoddesc}[numeric object]{__add__}{self, other}
-\methodline[numeric object]{__sub__}{self, other}
-\methodline[numeric object]{__mul__}{self, other}
-\methodline[numeric object]{__floordiv__}{self, other}
-\methodline[numeric object]{__mod__}{self, other}
-\methodline[numeric object]{__divmod__}{self, other}
-\methodline[numeric object]{__pow__}{self, other\optional{, modulo}}
-\methodline[numeric object]{__lshift__}{self, other}
-\methodline[numeric object]{__rshift__}{self, other}
-\methodline[numeric object]{__and__}{self, other}
-\methodline[numeric object]{__xor__}{self, other}
-\methodline[numeric object]{__or__}{self, other}
-These methods are
-called to implement the binary arithmetic operations (\code{+},
-\code{-}, \code{*}, \code{//}, \code{\%},
-\function{divmod()}\bifuncindex{divmod},
-\function{pow()}\bifuncindex{pow}, \code{**}, \code{<<},
-\code{>>}, \code{\&}, \code{\^}, \code{|}). For instance, to
-evaluate the expression \var{x}\code{+}\var{y}, where \var{x} is an
-instance of a class that has an \method{__add__()} method,
-\code{\var{x}.__add__(\var{y})} is called. The \method{__divmod__()}
-method should be the equivalent to using \method{__floordiv__()} and
-\method{__mod__()}; it should not be related to \method{__truediv__()}
-(described below). Note that
-\method{__pow__()} should be defined to accept an optional third
-argument if the ternary version of the built-in
-\function{pow()}\bifuncindex{pow} function is to be supported.
-
-If one of those methods does not support the operation with the
-supplied arguments, it should return \code{NotImplemented}.
-\end{methoddesc}
-
-\begin{methoddesc}[numeric object]{__div__}{self, other}
-\methodline[numeric object]{__truediv__}{self, other}
-The division operator (\code{/}) is implemented by these methods. The
-\method{__truediv__()} method is used when \code{__future__.division}
-is in effect, otherwise \method{__div__()} is used. If only one of
-these two methods is defined, the object will not support division in
-the alternate context; \exception{TypeError} will be raised instead.
-\end{methoddesc}
-
-\begin{methoddesc}[numeric object]{__radd__}{self, other}
-\methodline[numeric object]{__rsub__}{self, other}
-\methodline[numeric object]{__rmul__}{self, other}
-\methodline[numeric object]{__rdiv__}{self, other}
-\methodline[numeric object]{__rtruediv__}{self, other}
-\methodline[numeric object]{__rfloordiv__}{self, other}
-\methodline[numeric object]{__rmod__}{self, other}
-\methodline[numeric object]{__rdivmod__}{self, other}
-\methodline[numeric object]{__rpow__}{self, other}
-\methodline[numeric object]{__rlshift__}{self, other}
-\methodline[numeric object]{__rrshift__}{self, other}
-\methodline[numeric object]{__rand__}{self, other}
-\methodline[numeric object]{__rxor__}{self, other}
-\methodline[numeric object]{__ror__}{self, other}
-These methods are
-called to implement the binary arithmetic operations (\code{+},
-\code{-}, \code{*}, \code{/}, \code{\%},
-\function{divmod()}\bifuncindex{divmod},
-\function{pow()}\bifuncindex{pow}, \code{**}, \code{<<},
-\code{>>}, \code{\&}, \code{\^}, \code{|}) with reflected
-(swapped) operands. These functions are only called if the left
-operand does not support the corresponding operation and the
-operands are of different types.\footnote{
- For operands of the same type, it is assumed that if the
- non-reflected method (such as \method{__add__()}) fails the
- operation is not supported, which is why the reflected method
- is not called.}
-For instance, to evaluate the expression \var{x}\code{-}\var{y},
-where \var{y} is an instance of a class that has an
-\method{__rsub__()} method, \code{\var{y}.__rsub__(\var{x})}
-is called if \code{\var{x}.__sub__(\var{y})} returns
-\var{NotImplemented}.
-
-Note that ternary
-\function{pow()}\bifuncindex{pow} will not try calling
-\method{__rpow__()} (the coercion rules would become too
-complicated).
-
-\note{If the right operand's type is a subclass of the left operand's
- type and that subclass provides the reflected method for the
- operation, this method will be called before the left operand's
- non-reflected method. This behavior allows subclasses to
- override their ancestors' operations.}
-\end{methoddesc}
-
-\begin{methoddesc}[numeric object]{__iadd__}{self, other}
-\methodline[numeric object]{__isub__}{self, other}
-\methodline[numeric object]{__imul__}{self, other}
-\methodline[numeric object]{__idiv__}{self, other}
-\methodline[numeric object]{__itruediv__}{self, other}
-\methodline[numeric object]{__ifloordiv__}{self, other}
-\methodline[numeric object]{__imod__}{self, other}
-\methodline[numeric object]{__ipow__}{self, other\optional{, modulo}}
-\methodline[numeric object]{__ilshift__}{self, other}
-\methodline[numeric object]{__irshift__}{self, other}
-\methodline[numeric object]{__iand__}{self, other}
-\methodline[numeric object]{__ixor__}{self, other}
-\methodline[numeric object]{__ior__}{self, other}
-These methods are called to implement the augmented arithmetic
-operations (\code{+=}, \code{-=}, \code{*=}, \code{/=}, \code{//=},
-\code{\%=}, \code{**=}, \code{<<=}, \code{>>=}, \code{\&=},
-\code{\textasciicircum=}, \code{|=}). These methods should attempt to do the
-operation in-place (modifying \var{self}) and return the result (which
-could be, but does not have to be, \var{self}). If a specific method
-is not defined, the augmented operation falls back to the normal
-methods. For instance, to evaluate the expression
-\var{x}\code{+=}\var{y}, where \var{x} is an instance of a class that
-has an \method{__iadd__()} method, \code{\var{x}.__iadd__(\var{y})} is
-called. If \var{x} is an instance of a class that does not define a
-\method{__iadd__()} method, \code{\var{x}.__add__(\var{y})} and
-\code{\var{y}.__radd__(\var{x})} are considered, as with the
-evaluation of \var{x}\code{+}\var{y}.
-\end{methoddesc}
-
-\begin{methoddesc}[numeric object]{__neg__}{self}
-\methodline[numeric object]{__pos__}{self}
-\methodline[numeric object]{__abs__}{self}
-\methodline[numeric object]{__invert__}{self}
-Called to implement the unary arithmetic operations (\code{-},
-\code{+}, \function{abs()}\bifuncindex{abs} and \code{\~{}}).
-\end{methoddesc}
-
-\begin{methoddesc}[numeric object]{__complex__}{self}
-\methodline[numeric object]{__int__}{self}
-\methodline[numeric object]{__long__}{self}
-\methodline[numeric object]{__float__}{self}
-Called to implement the built-in functions
-\function{complex()}\bifuncindex{complex},
-\function{int()}\bifuncindex{int}, \function{long()}\bifuncindex{long},
-and \function{float()}\bifuncindex{float}. Should return a value of
-the appropriate type.
-\end{methoddesc}
-
-\begin{methoddesc}[numeric object]{__index__}{self}
-Called to implement \function{operator.index()}. Also called whenever
-Python needs an integer object (such as in slicing, or in the built-in
-\function{bin()}, \function{hex()} and \function{oct()} functions).
-Must return an integer (int or long).
-\versionadded{2.5}
-\end{methoddesc}
-
-\subsection{With Statement Context Managers\label{context-managers}}
-
-\versionadded{2.5}
-
-A \dfn{context manager} is an object that defines the runtime
-context to be established when executing a \keyword{with}
-statement. The context manager handles the entry into,
-and the exit from, the desired runtime context for the execution
-of the block of code. Context managers are normally invoked using
-the \keyword{with} statement (described in section~\ref{with}), but
-can also be used by directly invoking their methods.
-
-\stindex{with}
-\index{context manager}
-
-Typical uses of context managers include saving and
-restoring various kinds of global state, locking and unlocking
-resources, closing opened files, etc.
-
-For more information on context managers, see
-``\ulink{Context Types}{../lib/typecontextmanager.html}'' in the
-\citetitle[../lib/lib.html]{Python Library Reference}.
-
-\begin{methoddesc}[context manager]{__enter__}{self}
-Enter the runtime context related to this object. The \keyword{with}
-statement will bind this method's return value to the target(s)
-specified in the \keyword{as} clause of the statement, if any.
-\end{methoddesc}
-
-\begin{methoddesc}[context manager]{__exit__}
-{self, exc_type, exc_value, traceback}
-Exit the runtime context related to this object. The parameters
-describe the exception that caused the context to be exited. If
-the context was exited without an exception, all three arguments
-will be \constant{None}.
-
-If an exception is supplied, and the method wishes to suppress the
-exception (i.e., prevent it from being propagated), it should return a
-true value. Otherwise, the exception will be processed normally upon
-exit from this method.
-
-Note that \method{__exit__} methods should not reraise the passed-in
-exception; this is the caller's responsibility.
-\end{methoddesc}
-
-\begin{seealso}
- \seepep{0343}{The "with" statement}
- {The specification, background, and examples for the
- Python \keyword{with} statement.}
-\end{seealso}
-
diff --git a/Doc/ref/ref4.tex b/Doc/ref/ref4.tex
deleted file mode 100644
index 6ec60f8..0000000
--- a/Doc/ref/ref4.tex
+++ /dev/null
@@ -1,208 +0,0 @@
-\chapter{Execution model \label{execmodel}}
-\index{execution model}
-
-
-\section{Naming and binding \label{naming}}
-\indexii{code}{block}
-\index{namespace}
-\index{scope}
-
-\dfn{Names}\index{name} refer to objects. Names are introduced by
-name binding operations. Each occurrence of a name in the program
-text refers to the \dfn{binding}\indexii{binding}{name} of that name
-established in the innermost function block containing the use.
-
-A \dfn{block}\index{block} is a piece of Python program text that is
-executed as a unit. The following are blocks: a module, a function
-body, and a class definition. Each command typed interactively is a
-block. A script file (a file given as standard input to the
-interpreter or specified on the interpreter command line the first
-argument) is a code block. A script command (a command specified on
-the interpreter command line with the `\strong{-c}' option) is a code
-block. The string argument passed to the built-in functions
-\function{eval()} and \function{exec()} is a code block.
-The expression read and evaluated by the built-in function
-\function{input()} is a code block.
-
-A code block is executed in an \dfn{execution
-frame}\indexii{execution}{frame}. A frame contains some
-administrative information (used for debugging) and determines where
-and how execution continues after the code block's execution has
-completed.
-
-A \dfn{scope}\index{scope} defines the visibility of a name within a
-block. If a local variable is defined in a block, its scope includes
-that block. If the definition occurs in a function block, the scope
-extends to any blocks contained within the defining one, unless a
-contained block introduces a different binding for the name. The
-scope of names defined in a class block is limited to the class block;
-it does not extend to the code blocks of methods.
-
-When a name is used in a code block, it is resolved using the nearest
-enclosing scope. The set of all such scopes visible to a code block
-is called the block's \dfn{environment}\index{environment}.
-
-If a name is bound in a block, it is a local variable of that block.
-If a name is bound at the module level, it is a global variable. (The
-variables of the module code block are local and global.) If a
-variable is used in a code block but not defined there, it is a
-\dfn{free variable}\indexii{free}{variable}.
-
-When a name is not found at all, a
-\exception{NameError}\withsubitem{(built-in
-exception)}{\ttindex{NameError}} exception is raised. If the name
-refers to a local variable that has not been bound, a
-\exception{UnboundLocalError}\ttindex{UnboundLocalError} exception is
-raised. \exception{UnboundLocalError} is a subclass of
-\exception{NameError}.
-
-The following constructs bind names: formal parameters to functions,
-\keyword{import} statements, class and function definitions (these
-bind the class or function name in the defining block), and targets
-that are identifiers if occurring in an assignment, \keyword{for} loop
-header, or in the second position of an \keyword{except} clause
-header. The \keyword{import} statement of the form ``\samp{from
-\ldots import *}''\stindex{from} binds all names defined in the
-imported module, except those beginning with an underscore. This form
-may only be used at the module level.
-
-A target occurring in a \keyword{del} statement is also considered bound
-for this purpose (though the actual semantics are to unbind the
-name). It is illegal to unbind a name that is referenced by an
-enclosing scope; the compiler will report a \exception{SyntaxError}.
-
-Each assignment or import statement occurs within a block defined by a
-class or function definition or at the module level (the top-level
-code block).
-
-If a name binding operation occurs anywhere within a code block, all
-uses of the name within the block are treated as references to the
-current block. This can lead to errors when a name is used within a
-block before it is bound.
-This rule is subtle. Python lacks declarations and allows
-name binding operations to occur anywhere within a code block. The
-local variables of a code block can be determined by scanning the
-entire text of the block for name binding operations.
-
-If the global statement occurs within a block, all uses of the name
-specified in the statement refer to the binding of that name in the
-top-level namespace. Names are resolved in the top-level namespace by
-searching the global namespace, i.e. the namespace of the module
-containing the code block, and the builtin namespace, the namespace of
-the module \module{__builtin__}. The global namespace is searched
-first. If the name is not found there, the builtin namespace is
-searched. The global statement must precede all uses of the name.
-
-The built-in namespace associated with the execution of a code block
-is actually found by looking up the name \code{__builtins__} in its
-global namespace; this should be a dictionary or a module (in the
-latter case the module's dictionary is used). By default, when in the
-\module{__main__} module, \code{__builtins__} is the built-in module
-\module{__builtin__} (note: no `s'); when in any other module,
-\code{__builtins__} is an alias for the dictionary of the
-\module{__builtin__} module itself. \code{__builtins__} can be set
-to a user-created dictionary to create a weak form of restricted
-execution\indexii{restricted}{execution}.
-
-\begin{notice}
- Users should not touch \code{__builtins__}; it is strictly an
- implementation detail. Users wanting to override values in the
- built-in namespace should \keyword{import} the \module{__builtin__}
- (no `s') module and modify its attributes appropriately.
-\end{notice}
-
-The namespace for a module is automatically created the first time a
-module is imported. The main module for a script is always called
-\module{__main__}\refbimodindex{__main__}.
-
-The global statement has the same scope as a name binding operation
-in the same block. If the nearest enclosing scope for a free variable
-contains a global statement, the free variable is treated as a global.
-
-A class definition is an executable statement that may use and define
-names. These references follow the normal rules for name resolution.
-The namespace of the class definition becomes the attribute dictionary
-of the class. Names defined at the class scope are not visible in
-methods.
-
-\subsection{Interaction with dynamic features \label{dynamic-features}}
-
-There are several cases where Python statements are illegal when
-used in conjunction with nested scopes that contain free
-variables.
-
-If a variable is referenced in an enclosing scope, it is illegal
-to delete the name. An error will be reported at compile time.
-
-If the wild card form of import --- \samp{import *} --- is used in a
-function and the function contains or is a nested block with free
-variables, the compiler will raise a \exception{SyntaxError}.
-
-The \function{eval()}, \function{exec()},
-and \function{input()} functions do not have access to the
-full environment for resolving names. Names may be resolved in the
-local and global namespaces of the caller. Free variables are not
-resolved in the nearest enclosing namespace, but in the global
-namespace.\footnote{This limitation occurs because the code that is
- executed by these operations is not available at the time the
- module is compiled.}
-The \function{exec()} and \function{eval()}
-functions have optional arguments to override
-the global and local namespace. If only one namespace is specified,
-it is used for both.
-
-\section{Exceptions \label{exceptions}}
-\index{exception}
-
-Exceptions are a means of breaking out of the normal flow of control
-of a code block in order to handle errors or other exceptional
-conditions. An exception is
-\emph{raised}\index{raise an exception} at the point where the error
-is detected; it may be \emph{handled}\index{handle an exception} by
-the surrounding code block or by any code block that directly or
-indirectly invoked the code block where the error occurred.
-\index{exception handler}
-\index{errors}
-\index{error handling}
-
-The Python interpreter raises an exception when it detects a run-time
-error (such as division by zero). A Python program can also
-explicitly raise an exception with the \keyword{raise} statement.
-Exception handlers are specified with the \keyword{try} ... \keyword{except}
-statement. The \keyword{try} ... \keyword{finally} statement
-specifies cleanup code which does not handle the exception, but is
-executed whether an exception occurred or not in the preceding code.
-
-Python uses the ``termination''\index{termination model} model of
-error handling: an exception handler can find out what happened and
-continue execution at an outer level, but it cannot repair the cause
-of the error and retry the failing operation (except by re-entering
-the offending piece of code from the top).
-
-When an exception is not handled at all, the interpreter terminates
-execution of the program, or returns to its interactive main loop. In
-either case, it prints a stack backtrace, except when the exception is
-\exception{SystemExit}\withsubitem{(built-in
-exception)}{\ttindex{SystemExit}}.
-
-Exceptions are identified by class instances. The \keyword{except}
-clause is selected depending on the class of the instance: it must
-reference the class of the instance or a base class thereof. The
-instance can be received by the handler and can carry additional
-information about the exceptional condition.
-
-Exceptions can also be identified by strings, in which case the
-\keyword{except} clause is selected by object identity. An arbitrary
-value can be raised along with the identifying string which can be
-passed to the handler.
-
-\begin{notice}[warning]
-Messages to exceptions are not part of the Python API. Their contents may
-change from one version of Python to the next without warning and should not
-be relied on by code which will run under multiple versions of the
-interpreter.
-\end{notice}
-
-See also the description of the \keyword{try} statement in
-section~\ref{try} and \keyword{raise} statement in
-section~\ref{raise}.
diff --git a/Doc/ref/ref5.tex b/Doc/ref/ref5.tex
deleted file mode 100644
index 95e66de..0000000
--- a/Doc/ref/ref5.tex
+++ /dev/null
@@ -1,1273 +0,0 @@
-\chapter{Expressions\label{expressions}}
-\index{expression}
-
-This chapter explains the meaning of the elements of expressions in
-Python.
-
-\strong{Syntax Notes:} In this and the following chapters, extended
-BNF\index{BNF} notation will be used to describe syntax, not lexical
-analysis. When (one alternative of) a syntax rule has the form
-
-\begin{productionlist}[*]
- \production{name}{\token{othername}}
-\end{productionlist}
-
-and no semantics are given, the semantics of this form of \code{name}
-are the same as for \code{othername}.
-\index{syntax}
-
-
-\section{Arithmetic conversions\label{conversions}}
-\indexii{arithmetic}{conversion}
-
-When a description of an arithmetic operator below uses the phrase
-``the numeric arguments are converted to a common type,'' the
-arguments are coerced using the coercion rules listed at
-~\ref{coercion-rules}. If both arguments are standard numeric types,
-the following coercions are applied:
-
-\begin{itemize}
-\item If either argument is a complex number, the other is converted
- to complex;
-\item otherwise, if either argument is a floating point number,
- the other is converted to floating point;
-\item otherwise, if either argument is a long integer,
- the other is converted to long integer;
-\item otherwise, both must be plain integers and no conversion
- is necessary.
-\end{itemize}
-
-Some additional rules apply for certain operators (e.g., a string left
-argument to the `\%' operator). Extensions can define their own
-coercions.
-
-
-\section{Atoms\label{atoms}}
-\index{atom}
-
-Atoms are the most basic elements of expressions. The simplest atoms
-are identifiers or literals. Forms enclosed in
-reverse quotes or in parentheses, brackets or braces are also
-categorized syntactically as atoms. The syntax for atoms is:
-
-\begin{productionlist}
- \production{atom}
- {\token{identifier} | \token{literal} | \token{enclosure}}
- \production{enclosure}
- {\token{parenth_form} | \token{list_display}}
- \productioncont{| \token{generator_expression} | \token{dict_display}}
- \productioncont{| \token{string_conversion} | \token{yield_atom}}
-\end{productionlist}
-
-
-\subsection{Identifiers (Names)\label{atom-identifiers}}
-\index{name}
-\index{identifier}
-
-An identifier occurring as an atom is a name. See
-section \ref{identifiers} for lexical definition and
-section~\ref{naming} for documentation of naming and binding.
-
-When the name is bound to an object, evaluation of the atom yields
-that object. When a name is not bound, an attempt to evaluate it
-raises a \exception{NameError} exception.
-\exindex{NameError}
-
-\strong{Private name mangling:}
-\indexii{name}{mangling}%
-\indexii{private}{names}%
-When an identifier that textually occurs in a class definition begins
-with two or more underscore characters and does not end in two or more
-underscores, it is considered a \dfn{private name} of that class.
-Private names are transformed to a longer form before code is
-generated for them. The transformation inserts the class name in
-front of the name, with leading underscores removed, and a single
-underscore inserted in front of the class name. For example, the
-identifier \code{__spam} occurring in a class named \code{Ham} will be
-transformed to \code{_Ham__spam}. This transformation is independent
-of the syntactical context in which the identifier is used. If the
-transformed name is extremely long (longer than 255 characters),
-implementation defined truncation may happen. If the class name
-consists only of underscores, no transformation is done.
-
-
-\subsection{Literals\label{atom-literals}}
-\index{literal}
-
-Python supports string literals and various numeric literals:
-
-\begin{productionlist}
- \production{literal}
- {\token{stringliteral} | \token{integer} | \token{longinteger}}
- \productioncont{| \token{floatnumber} | \token{imagnumber}}
-\end{productionlist}
-
-Evaluation of a literal yields an object of the given type (string,
-integer, long integer, floating point number, complex number) with the
-given value. The value may be approximated in the case of floating
-point and imaginary (complex) literals. See section \ref{literals}
-for details.
-
-All literals correspond to immutable data types, and hence the
-object's identity is less important than its value. Multiple
-evaluations of literals with the same value (either the same
-occurrence in the program text or a different occurrence) may obtain
-the same object or a different object with the same value.
-\indexiii{immutable}{data}{type}
-\indexii{immutable}{object}
-
-
-\subsection{Parenthesized forms\label{parenthesized}}
-\index{parenthesized form}
-
-A parenthesized form is an optional expression list enclosed in
-parentheses:
-
-\begin{productionlist}
- \production{parenth_form}
- {"(" [\token{expression_list}] ")"}
-\end{productionlist}
-
-A parenthesized expression list yields whatever that expression list
-yields: if the list contains at least one comma, it yields a tuple;
-otherwise, it yields the single expression that makes up the
-expression list.
-
-An empty pair of parentheses yields an empty tuple object. Since
-tuples are immutable, the rules for literals apply (i.e., two
-occurrences of the empty tuple may or may not yield the same object).
-\indexii{empty}{tuple}
-
-Note that tuples are not formed by the parentheses, but rather by use
-of the comma operator. The exception is the empty tuple, for which
-parentheses \emph{are} required --- allowing unparenthesized ``nothing''
-in expressions would cause ambiguities and allow common typos to
-pass uncaught.
-\index{comma}
-\indexii{tuple}{display}
-
-
-\subsection{List displays\label{lists}}
-\indexii{list}{display}
-\indexii{list}{comprehensions}
-
-A list display is a possibly empty series of expressions enclosed in
-square brackets:
-
-\begin{productionlist}
- \production{list_display}
- {"[" [\token{expression_list} | \token{list_comprehension}] "]"}
- \production{list_comprehension}
- {\token{expression} \token{list_for}}
- \production{list_for}
- {"for" \token{target_list} "in" \token{old_expression_list}
- [\token{list_iter}]}
- \production{old_expression_list}
- {\token{old_expression}
- [("," \token{old_expression})+ [","]]}
- \production{list_iter}
- {\token{list_for} | \token{list_if}}
- \production{list_if}
- {"if" \token{old_expression} [\token{list_iter}]}
-\end{productionlist}
-
-A list display yields a new list object. Its contents are specified
-by providing either a list of expressions or a list comprehension.
-\indexii{list}{comprehensions}
-When a comma-separated list of expressions is supplied, its elements are
-evaluated from left to right and placed into the list object in that
-order. When a list comprehension is supplied, it consists of a
-single expression followed by at least one \keyword{for} clause and zero or
-more \keyword{for} or \keyword{if} clauses. In this
-case, the elements of the new list are those that would be produced
-by considering each of the \keyword{for} or \keyword{if} clauses a block,
-nesting from
-left to right, and evaluating the expression to produce a list element
-each time the innermost block is reached\footnote{In Python 2.3, a
-list comprehension "leaks" the control variables of each
-\samp{for} it contains into the containing scope. However, this
-behavior is deprecated, and relying on it will not work once this
-bug is fixed in a future release}.
-\obindex{list}
-\indexii{empty}{list}
-
-
-\subsection{Generator expressions\label{genexpr}}
-\indexii{generator}{expression}
-
-A generator expression is a compact generator notation in parentheses:
-
-\begin{productionlist}
- \production{generator_expression}
- {"(" \token{expression} \token{genexpr_for} ")"}
- \production{genexpr_for}
- {"for" \token{target_list} "in" \token{or_test}
- [\token{genexpr_iter}]}
- \production{genexpr_iter}
- {\token{genexpr_for} | \token{genexpr_if}}
- \production{genexpr_if}
- {"if" \token{old_expression} [\token{genexpr_iter}]}
-\end{productionlist}
-
-A generator expression yields a new generator object.
-\obindex{generator}
-It consists of a single expression followed by at least one
-\keyword{for} clause and zero or more \keyword{for} or \keyword{if}
-clauses. The iterating values of the new generator are those that
-would be produced by considering each of the \keyword{for} or
-\keyword{if} clauses a block, nesting from left to right, and
-evaluating the expression to yield a value that is reached the
-innermost block for each iteration.
-
-Variables used in the generator expression are evaluated lazily
-when the \method{__next__()} method is called for generator object
-(in the same fashion as normal generators). However, the leftmost
-\keyword{for} clause is immediately evaluated so that error produced
-by it can be seen before any other possible error in the code that
-handles the generator expression.
-Subsequent \keyword{for} clauses cannot be evaluated immediately since
-they may depend on the previous \keyword{for} loop.
-For example: \samp{(x*y for x in range(10) for y in bar(x))}.
-
-The parentheses can be omitted on calls with only one argument.
-See section \ref{calls} for the detail.
-
-
-\subsection{Dictionary displays\label{dict}}
-\indexii{dictionary}{display}
-
-A dictionary display is a possibly empty series of key/datum pairs
-enclosed in curly braces:
-\index{key}
-\index{datum}
-\index{key/datum pair}
-
-\begin{productionlist}
- \production{dict_display}
- {"\{" [\token{key_datum_list}] "\}"}
- \production{key_datum_list}
- {\token{key_datum} ("," \token{key_datum})* [","]}
- \production{key_datum}
- {\token{expression} ":" \token{expression}}
-\end{productionlist}
-
-A dictionary display yields a new dictionary object.
-\obindex{dictionary}
-
-The key/datum pairs are evaluated from left to right to define the
-entries of the dictionary: each key object is used as a key into the
-dictionary to store the corresponding datum.
-
-Restrictions on the types of the key values are listed earlier in
-section \ref{types}. (To summarize, the key type should be hashable,
-which excludes all mutable objects.) Clashes between duplicate keys
-are not detected; the last datum (textually rightmost in the display)
-stored for a given key value prevails.
-\indexii{immutable}{object}
-
-
-\subsection{Yield expressions\label{yieldexpr}}
-\kwindex{yield}
-\indexii{yield}{expression}
-\indexii{generator}{function}
-
-\begin{productionlist}
- \production{yield_atom}
- {"(" \token{yield_expression} ")"}
- \production{yield_expression}
- {"yield" [\token{expression_list}]}
-\end{productionlist}
-
-\versionadded{2.5}
-
-The \keyword{yield} expression is only used when defining a generator
-function, and can only be used in the body of a function definition.
-Using a \keyword{yield} expression in a function definition is
-sufficient to cause that definition to create a generator function
-instead of a normal function.
-
-When a generator function is called, it returns an iterator known as a
-generator. That generator then controls the execution of a generator
-function. The execution starts when one of the generator's methods is
-called. At that time, the execution proceeds to the first
-\keyword{yield} expression, where it is suspended again, returning the
-value of \grammartoken{expression_list} to generator's caller. By
-suspended we mean that all local state is retained, including the
-current bindings of local variables, the instruction pointer, and the
-internal evaluation stack. When the execution is resumed by calling
-one of the generator's methods, the function can proceed exactly as
-if the \keyword{yield} expression was just another external call.
-The value of the \keyword{yield} expression after resuming depends on
-the method which resumed the execution.
-
-\index{coroutine}
-
-All of this makes generator functions quite similar to coroutines; they
-yield multiple times, they have more than one entry point and their
-execution can be suspended. The only difference is that a generator
-function cannot control where should the execution continue after it
-yields; the control is always transfered to the generator's caller.
-
-\obindex{generator}
-
-The following generator's methods can be used to control the execution
-of a generator function:
-
-\exindex{StopIteration}
-
-\begin{methoddesc}[generator]{next}{}
- Starts the execution of a generator function or resumes it at the
- last executed \keyword{yield} expression. When a generator function
- is resumed with a \method{next()} method, the current \keyword{yield}
- expression always evaluates to \constant{None}. The execution then
- continues to the next \keyword{yield} expression, where the generator
- is suspended again, and the value of the
- \grammartoken{expression_list} is returned to \method{next()}'s
- caller. If the generator exits without yielding another value, a
- \exception{StopIteration} exception is raised.
-\end{methoddesc}
-
-\begin{methoddesc}[generator]{send}{value}
- Resumes the execution and ``sends'' a value into the generator
- function. The \code{value} argument becomes the result of the
- current \keyword{yield} expression. The \method{send()} method
- returns the next value yielded by the generator, or raises
- \exception{StopIteration} if the generator exits without yielding
- another value.
- When \method{send()} is called to start the generator, it must be
- called with \constant{None} as the argument, because there is no
- \keyword{yield} expression that could receieve the value.
-\end{methoddesc}
-
-\begin{methoddesc}[generator]{throw}
- {type\optional{, value\optional{, traceback}}}
- Raises an exception of type \code{type} at the point where generator
- was paused, and returns the next value yielded by the generator
- function. If the generator exits without yielding another value, a
- \exception{StopIteration} exception is raised. If the generator
- function does not catch the passed-in exception, or raises a
- different exception, then that exception propagates to the caller.
-\end{methoddesc}
-
-\exindex{GeneratorExit}
-
-\begin{methoddesc}[generator]{close}{}
- Raises a \exception{GeneratorExit} at the point where the generator
- function was paused. If the generator function then raises
- \exception{StopIteration} (by exiting normally, or due to already
- being closed) or \exception{GeneratorExit} (by not catching the
- exception), close returns to its caller. If the generator yields a
- value, a \exception{RuntimeError} is raised. If the generator raises
- any other exception, it is propagated to the caller. \method{close}
- does nothing if the generator has already exited due to an exception
- or normal exit.
-\end{methoddesc}
-
-Here is a simple example that demonstrates the behavior of generators
-and generator functions:
-
-\begin{verbatim}
->>> def echo(value=None):
-... print "Execution starts when 'next()' is called for the first time."
-... try:
-... while True:
-... try:
-... value = (yield value)
-... except GeneratorExit:
-... # never catch GeneratorExit
-... raise
-... except Exception, e:
-... value = e
-... finally:
-... print "Don't forget to clean up when 'close()' is called."
-...
->>> generator = echo(1)
->>> print generator.next()
-Execution starts when 'next()' is called for the first time.
-1
->>> print generator.next()
-None
->>> print generator.send(2)
-2
->>> generator.throw(TypeError, "spam")
-TypeError('spam',)
->>> generator.close()
-Don't forget to clean up when 'close()' is called.
-\end{verbatim}
-
-\begin{seealso}
- \seepep{0342}{Coroutines via Enhanced Generators}
- {The proposal to enhance the API and syntax of generators,
- making them usable as simple coroutines.}
-\end{seealso}
-
-
-\section{Primaries\label{primaries}}
-\index{primary}
-
-Primaries represent the most tightly bound operations of the language.
-Their syntax is:
-
-\begin{productionlist}
- \production{primary}
- {\token{atom} | \token{attributeref}
- | \token{subscription} | \token{slicing} | \token{call}}
-\end{productionlist}
-
-
-\subsection{Attribute references\label{attribute-references}}
-\indexii{attribute}{reference}
-
-An attribute reference is a primary followed by a period and a name:
-
-\begin{productionlist}
- \production{attributeref}
- {\token{primary} "." \token{identifier}}
-\end{productionlist}
-
-The primary must evaluate to an object of a type that supports
-attribute references, e.g., a module, list, or an instance. This
-object is then asked to produce the attribute whose name is the
-identifier. If this attribute is not available, the exception
-\exception{AttributeError}\exindex{AttributeError} is raised.
-Otherwise, the type and value of the object produced is determined by
-the object. Multiple evaluations of the same attribute reference may
-yield different objects.
-\obindex{module}
-\obindex{list}
-
-
-\subsection{Subscriptions\label{subscriptions}}
-\index{subscription}
-
-A subscription selects an item of a sequence (string, tuple or list)
-or mapping (dictionary) object:
-\obindex{sequence}
-\obindex{mapping}
-\obindex{string}
-\obindex{tuple}
-\obindex{list}
-\obindex{dictionary}
-\indexii{sequence}{item}
-
-\begin{productionlist}
- \production{subscription}
- {\token{primary} "[" \token{expression_list} "]"}
-\end{productionlist}
-
-The primary must evaluate to an object of a sequence or mapping type.
-
-If the primary is a mapping, the expression list must evaluate to an
-object whose value is one of the keys of the mapping, and the
-subscription selects the value in the mapping that corresponds to that
-key. (The expression list is a tuple except if it has exactly one
-item.)
-
-If the primary is a sequence, the expression (list) must evaluate to a
-plain integer. If this value is negative, the length of the sequence
-is added to it (so that, e.g., \code{x[-1]} selects the last item of
-\code{x}.) The resulting value must be a nonnegative integer less
-than the number of items in the sequence, and the subscription selects
-the item whose index is that value (counting from zero).
-
-A string's items are characters. A character is not a separate data
-type but a string of exactly one character.
-\index{character}
-\indexii{string}{item}
-
-
-\subsection{Slicings\label{slicings}}
-\index{slicing}
-\index{slice}
-
-A slicing selects a range of items in a sequence object (e.g., a
-string, tuple or list). Slicings may be used as expressions or as
-targets in assignment or \keyword{del} statements. The syntax for a
-slicing:
-\obindex{sequence}
-\obindex{string}
-\obindex{tuple}
-\obindex{list}
-
-\begin{productionlist}
- \production{slicing}
- {\token{simple_slicing} | \token{extended_slicing}}
- \production{simple_slicing}
- {\token{primary} "[" \token{short_slice} "]"}
- \production{extended_slicing}
- {\token{primary} "[" \token{slice_list} "]" }
- \production{slice_list}
- {\token{slice_item} ("," \token{slice_item})* [","]}
- \production{slice_item}
- {\token{expression} | \token{proper_slice} | \token{ellipsis}}
- \production{proper_slice}
- {\token{short_slice} | \token{long_slice}}
- \production{short_slice}
- {[\token{lower_bound}] ":" [\token{upper_bound}]}
- \production{long_slice}
- {\token{short_slice} ":" [\token{stride}]}
- \production{lower_bound}
- {\token{expression}}
- \production{upper_bound}
- {\token{expression}}
- \production{stride}
- {\token{expression}}
- \production{ellipsis}
- {"..."}
-\end{productionlist}
-
-There is ambiguity in the formal syntax here: anything that looks like
-an expression list also looks like a slice list, so any subscription
-can be interpreted as a slicing. Rather than further complicating the
-syntax, this is disambiguated by defining that in this case the
-interpretation as a subscription takes priority over the
-interpretation as a slicing (this is the case if the slice list
-contains no proper slice nor ellipses). Similarly, when the slice
-list has exactly one short slice and no trailing comma, the
-interpretation as a simple slicing takes priority over that as an
-extended slicing.\indexii{extended}{slicing}
-
-The semantics for a simple slicing are as follows. The primary must
-evaluate to a sequence object. The lower and upper bound expressions,
-if present, must evaluate to plain integers; defaults are zero and the
-\code{sys.maxint}, respectively. If either bound is negative, the
-sequence's length is added to it. The slicing now selects all items
-with index \var{k} such that
-\code{\var{i} <= \var{k} < \var{j}} where \var{i}
-and \var{j} are the specified lower and upper bounds. This may be an
-empty sequence. It is not an error if \var{i} or \var{j} lie outside the
-range of valid indexes (such items don't exist so they aren't
-selected).
-
-The semantics for an extended slicing are as follows. The primary
-must evaluate to a mapping object, and it is indexed with a key that
-is constructed from the slice list, as follows. If the slice list
-contains at least one comma, the key is a tuple containing the
-conversion of the slice items; otherwise, the conversion of the lone
-slice item is the key. The conversion of a slice item that is an
-expression is that expression. The conversion of a
-proper slice is a slice object (see section \ref{types}) whose
-\member{start}, \member{stop} and \member{step} attributes are the
-values of the expressions given as lower bound, upper bound and
-stride, respectively, substituting \code{None} for missing
-expressions.
-\withsubitem{(slice object attribute)}{\ttindex{start}
- \ttindex{stop}\ttindex{step}}
-
-
-\subsection{Calls\label{calls}}
-\index{call}
-
-A call calls a callable object (e.g., a function) with a possibly empty
-series of arguments:
-\obindex{callable}
-
-\begin{productionlist}
- \production{call}
- {\token{primary} "(" [\token{argument_list} [","]}
- \productioncont{ | \token{expression} \token{genexpr_for}] ")"}
- \production{argument_list}
- {\token{positional_arguments} ["," \token{keyword_arguments}]}
- \productioncont{ ["," "*" \token{expression}]}
- \productioncont{ ["," "**" \token{expression}]}
- \productioncont{| \token{keyword_arguments} ["," "*" \token{expression}]}
- \productioncont{ ["," "**" \token{expression}]}
- \productioncont{| "*" \token{expression} ["," "**" \token{expression}]}
- \productioncont{| "**" \token{expression}}
- \production{positional_arguments}
- {\token{expression} ("," \token{expression})*}
- \production{keyword_arguments}
- {\token{keyword_item} ("," \token{keyword_item})*}
- \production{keyword_item}
- {\token{identifier} "=" \token{expression}}
-\end{productionlist}
-
-A trailing comma may be present after the positional and keyword
-arguments but does not affect the semantics.
-
-The primary must evaluate to a callable object (user-defined
-functions, built-in functions, methods of built-in objects, class
-objects, methods of class instances, and certain class instances
-themselves are callable; extensions may define additional callable
-object types). All argument expressions are evaluated before the call
-is attempted. Please refer to section \ref{function} for the syntax
-of formal parameter lists.
-
-If keyword arguments are present, they are first converted to
-positional arguments, as follows. First, a list of unfilled slots is
-created for the formal parameters. If there are N positional
-arguments, they are placed in the first N slots. Next, for each
-keyword argument, the identifier is used to determine the
-corresponding slot (if the identifier is the same as the first formal
-parameter name, the first slot is used, and so on). If the slot is
-already filled, a \exception{TypeError} exception is raised.
-Otherwise, the value of the argument is placed in the slot, filling it
-(even if the expression is \code{None}, it fills the slot). When all
-arguments have been processed, the slots that are still unfilled are
-filled with the corresponding default value from the function
-definition. (Default values are calculated, once, when the function
-is defined; thus, a mutable object such as a list or dictionary used
-as default value will be shared by all calls that don't specify an
-argument value for the corresponding slot; this should usually be
-avoided.) If there are any unfilled slots for which no default value
-is specified, a \exception{TypeError} exception is raised. Otherwise,
-the list of filled slots is used as the argument list for the call.
-
-If there are more positional arguments than there are formal parameter
-slots, a \exception{TypeError} exception is raised, unless a formal
-parameter using the syntax \samp{*identifier} is present; in this
-case, that formal parameter receives a tuple containing the excess
-positional arguments (or an empty tuple if there were no excess
-positional arguments).
-
-If any keyword argument does not correspond to a formal parameter
-name, a \exception{TypeError} exception is raised, unless a formal
-parameter using the syntax \samp{**identifier} is present; in this
-case, that formal parameter receives a dictionary containing the
-excess keyword arguments (using the keywords as keys and the argument
-values as corresponding values), or a (new) empty dictionary if there
-were no excess keyword arguments.
-
-If the syntax \samp{*expression} appears in the function call,
-\samp{expression} must evaluate to a sequence. Elements from this
-sequence are treated as if they were additional positional arguments;
-if there are postional arguments \var{x1},...,\var{xN} , and
-\samp{expression} evaluates to a sequence \var{y1},...,\var{yM}, this
-is equivalent to a call with M+N positional arguments
-\var{x1},...,\var{xN},\var{y1},...,\var{yM}.
-
-A consequence of this is that although the \samp{*expression} syntax
-appears \emph{after} any keyword arguments, it is processed
-\emph{before} the keyword arguments (and the
-\samp{**expression} argument, if any -- see below). So:
-
-\begin{verbatim}
->>> def f(a, b):
-... print a, b
-...
->>> f(b=1, *(2,))
-2 1
->>> f(a=1, *(2,))
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-TypeError: f() got multiple values for keyword argument 'a'
->>> f(1, *(2,))
-1 2
-\end{verbatim}
-
-It is unusual for both keyword arguments and the
-\samp{*expression} syntax to be used in the same call, so in practice
-this confusion does not arise.
-
-If the syntax \samp{**expression} appears in the function call,
-\samp{expression} must evaluate to a mapping, the
-contents of which are treated as additional keyword arguments. In the
-case of a keyword appearing in both \samp{expression} and as an
-explicit keyword argument, a \exception{TypeError} exception is
-raised.
-
-Formal parameters using the syntax \samp{*identifier} or
-\samp{**identifier} cannot be used as positional argument slots or
-as keyword argument names.
-
-A call always returns some value, possibly \code{None}, unless it
-raises an exception. How this value is computed depends on the type
-of the callable object.
-
-If it is---
-
-\begin{description}
-
-\item[a user-defined function:] The code block for the function is
-executed, passing it the argument list. The first thing the code
-block will do is bind the formal parameters to the arguments; this is
-described in section \ref{function}. When the code block executes a
-\keyword{return} statement, this specifies the return value of the
-function call.
-\indexii{function}{call}
-\indexiii{user-defined}{function}{call}
-\obindex{user-defined function}
-\obindex{function}
-
-\item[a built-in function or method:] The result is up to the
-interpreter; see the \citetitle[../lib/built-in-funcs.html]{Python
-Library Reference} for the descriptions of built-in functions and
-methods.
-\indexii{function}{call}
-\indexii{built-in function}{call}
-\indexii{method}{call}
-\indexii{built-in method}{call}
-\obindex{built-in method}
-\obindex{built-in function}
-\obindex{method}
-\obindex{function}
-
-\item[a class object:] A new instance of that class is returned.
-\obindex{class}
-\indexii{class object}{call}
-
-\item[a class instance method:] The corresponding user-defined
-function is called, with an argument list that is one longer than the
-argument list of the call: the instance becomes the first argument.
-\obindex{class instance}
-\obindex{instance}
-\indexii{class instance}{call}
-
-\item[a class instance:] The class must define a \method{__call__()}
-method; the effect is then the same as if that method was called.
-\indexii{instance}{call}
-\withsubitem{(object method)}{\ttindex{__call__()}}
-
-\end{description}
-
-
-\section{The power operator\label{power}}
-
-The power operator binds more tightly than unary operators on its
-left; it binds less tightly than unary operators on its right. The
-syntax is:
-
-\begin{productionlist}
- \production{power}
- {\token{primary} ["**" \token{u_expr}]}
-\end{productionlist}
-
-Thus, in an unparenthesized sequence of power and unary operators, the
-operators are evaluated from right to left (this does not constrain
-the evaluation order for the operands).
-
-The power operator has the same semantics as the built-in
-\function{pow()} function, when called with two arguments: it yields
-its left argument raised to the power of its right argument. The
-numeric arguments are first converted to a common type. The result
-type is that of the arguments after coercion.
-
-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, \code{10**2} returns \code{100},
-but \code{10**-2} returns \code{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).
-
-Raising \code{0.0} to a negative power results in a
-\exception{ZeroDivisionError}. Raising a negative number to a
-fractional power results in a \exception{ValueError}.
-
-
-\section{Unary arithmetic operations \label{unary}}
-\indexiii{unary}{arithmetic}{operation}
-\indexiii{unary}{bit-wise}{operation}
-
-All unary arithmetic (and bit-wise) operations have the same priority:
-
-\begin{productionlist}
- \production{u_expr}
- {\token{power} | "-" \token{u_expr}
- | "+" \token{u_expr} | "{\~}" \token{u_expr}}
-\end{productionlist}
-
-The unary \code{-} (minus) operator yields the negation of its
-numeric argument.
-\index{negation}
-\index{minus}
-
-The unary \code{+} (plus) operator yields its numeric argument
-unchanged.
-\index{plus}
-
-The unary \code{\~} (invert) operator yields the bit-wise inversion
-of its plain or long integer argument. The bit-wise inversion of
-\code{x} is defined as \code{-(x+1)}. It only applies to integral
-numbers.
-\index{inversion}
-
-In all three cases, if the argument does not have the proper type,
-a \exception{TypeError} exception is raised.
-\exindex{TypeError}
-
-
-\section{Binary arithmetic operations\label{binary}}
-\indexiii{binary}{arithmetic}{operation}
-
-The binary arithmetic operations have the conventional priority
-levels. Note that some of these operations also apply to certain
-non-numeric types. Apart from the power operator, there are only two
-levels, one for multiplicative operators and one for additive
-operators:
-
-\begin{productionlist}
- \production{m_expr}
- {\token{u_expr} | \token{m_expr} "*" \token{u_expr}
- | \token{m_expr} "//" \token{u_expr}
- | \token{m_expr} "/" \token{u_expr}}
- \productioncont{| \token{m_expr} "\%" \token{u_expr}}
- \production{a_expr}
- {\token{m_expr} | \token{a_expr} "+" \token{m_expr}
- | \token{a_expr} "-" \token{m_expr}}
-\end{productionlist}
-
-The \code{*} (multiplication) operator yields the product of its
-arguments. The arguments must either both be numbers, or one argument
-must be an integer (plain or long) and the other must be a sequence.
-In the former case, the numbers are converted to a common type and
-then multiplied together. In the latter case, sequence repetition is
-performed; a negative repetition factor yields an empty sequence.
-\index{multiplication}
-
-The \code{/} (division) and \code{//} (floor division) operators yield
-the quotient of their arguments. The numeric arguments are first
-converted to a common type. Plain or long integer division yields an
-integer of the same type; the result is that of mathematical division
-with the `floor' function applied to the result. Division by zero
-raises the
-\exception{ZeroDivisionError} exception.
-\exindex{ZeroDivisionError}
-\index{division}
-
-The \code{\%} (modulo) operator yields the remainder from the
-division of the first argument by the second. The numeric arguments
-are first converted to a common type. A zero right argument raises
-the \exception{ZeroDivisionError} exception. The arguments may be floating
-point numbers, e.g., \code{3.14\%0.7} equals \code{0.34} (since
-\code{3.14} equals \code{4*0.7 + 0.34}.) The modulo operator always
-yields a result with the same sign as its second operand (or zero);
-the absolute value of the result is strictly smaller than the absolute
-value of the second operand\footnote{
- While \code{abs(x\%y) < abs(y)} is true mathematically, for
- floats it may not be true numerically due to roundoff. For
- example, and assuming a platform on which a Python float is an
- IEEE 754 double-precision number, in order that \code{-1e-100 \% 1e100}
- have the same sign as \code{1e100}, the computed result is
- \code{-1e-100 + 1e100}, which is numerically exactly equal
- to \code{1e100}. Function \function{fmod()} in the \module{math}
- module returns a result whose sign matches the sign of the
- first argument instead, and so returns \code{-1e-100} in this case.
- Which approach is more appropriate depends on the application.
-}.
-\index{modulo}
-
-The integer division and modulo operators are connected by the
-following identity: \code{x == (x/y)*y + (x\%y)}. Integer division and
-modulo are also connected with the built-in function \function{divmod()}:
-\code{divmod(x, y) == (x/y, x\%y)}. These identities don't hold for
-floating point numbers; there similar identities hold
-approximately where \code{x/y} is replaced by \code{floor(x/y)} or
-\code{floor(x/y) - 1}\footnote{
- If x is very close to an exact integer multiple of y, it's
- possible for \code{floor(x/y)} to be one larger than
- \code{(x-x\%y)/y} due to rounding. In such cases, Python returns
- the latter result, in order to preserve that \code{divmod(x,y)[0]
- * y + x \%{} y} be very close to \code{x}.
-}.
-
-In addition to performing the modulo operation on numbers, the \code{\%}
-operator is also overloaded by string and unicode objects to perform
-string formatting (also known as interpolation). The syntax for string
-formatting is described in the
-\citetitle[../lib/typesseq-strings.html]{Python Library Reference},
-section ``Sequence Types''.
-
-\deprecated{2.3}{The floor division operator, the modulo operator,
-and the \function{divmod()} function are no longer defined for complex
-numbers. Instead, convert to a floating point number using the
-\function{abs()} function if appropriate.}
-
-The \code{+} (addition) operator yields the sum of its arguments.
-The arguments must either both be numbers or both sequences of the
-same type. In the former case, the numbers are converted to a common
-type and then added together. In the latter case, the sequences are
-concatenated.
-\index{addition}
-
-The \code{-} (subtraction) operator yields the difference of its
-arguments. The numeric arguments are first converted to a common
-type.
-\index{subtraction}
-
-
-\section{Shifting operations\label{shifting}}
-\indexii{shifting}{operation}
-
-The shifting operations have lower priority than the arithmetic
-operations:
-
-\begin{productionlist}
- \production{shift_expr}
- {\token{a_expr}
- | \token{shift_expr} ( "<<" | ">>" ) \token{a_expr}}
-\end{productionlist}
-
-These operators accept plain or long integers as arguments. The
-arguments are converted to a common type. They shift the first
-argument to the left or right by the number of bits given by the
-second argument.
-
-A right shift by \var{n} bits is defined as division by
-\code{pow(2,\var{n})}. A left shift by \var{n} bits is defined as
-multiplication with \code{pow(2,\var{n})}; for plain integers there is
-no overflow check so in that case the operation drops bits and flips
-the sign if the result is not less than \code{pow(2,31)} in absolute
-value. Negative shift counts raise a \exception{ValueError}
-exception.
-\exindex{ValueError}
-
-
-\section{Binary bit-wise operations\label{bitwise}}
-\indexiii{binary}{bit-wise}{operation}
-
-Each of the three bitwise operations has a different priority level:
-
-\begin{productionlist}
- \production{and_expr}
- {\token{shift_expr} | \token{and_expr} "\&" \token{shift_expr}}
- \production{xor_expr}
- {\token{and_expr} | \token{xor_expr} "\textasciicircum" \token{and_expr}}
- \production{or_expr}
- {\token{xor_expr} | \token{or_expr} "|" \token{xor_expr}}
-\end{productionlist}
-
-The \code{\&} operator yields the bitwise AND of its arguments, which
-must be plain or long integers. The arguments are converted to a
-common type.
-\indexii{bit-wise}{and}
-
-The \code{\^} operator yields the bitwise XOR (exclusive OR) of its
-arguments, which must be plain or long integers. The arguments are
-converted to a common type.
-\indexii{bit-wise}{xor}
-\indexii{exclusive}{or}
-
-The \code{|} operator yields the bitwise (inclusive) OR of its
-arguments, which must be plain or long integers. The arguments are
-converted to a common type.
-\indexii{bit-wise}{or}
-\indexii{inclusive}{or}
-
-
-\section{Comparisons\label{comparisons}}
-\index{comparison}
-
-Unlike C, all comparison operations in Python have the same priority,
-which is lower than that of any arithmetic, shifting or bitwise
-operation. Also unlike C, expressions like \code{a < b < c} have the
-interpretation that is conventional in mathematics:
-\indexii{C}{language}
-
-\begin{productionlist}
- \production{comparison}
- {\token{or_expr} ( \token{comp_operator} \token{or_expr} )*}
- \production{comp_operator}
- {"<" | ">" | "==" | ">=" | "<=" | "!="}
- \productioncont{| "is" ["not"] | ["not"] "in"}
-\end{productionlist}
-
-Comparisons yield boolean values: \code{True} or \code{False}.
-
-Comparisons can be chained arbitrarily, e.g., \code{x < y <= z} is
-equivalent to \code{x < y and y <= z}, except that \code{y} is
-evaluated only once (but in both cases \code{z} is not evaluated at all
-when \code{x < y} is found to be false).
-\indexii{chaining}{comparisons}
-
-Formally, if \var{a}, \var{b}, \var{c}, \ldots, \var{y}, \var{z} are
-expressions and \var{opa}, \var{opb}, \ldots, \var{opy} are comparison
-operators, then \var{a opa b opb c} \ldots \var{y opy z} is equivalent
-to \var{a opa b} \keyword{and} \var{b opb c} \keyword{and} \ldots
-\var{y opy z}, except that each expression is evaluated at most once.
-
-Note that \var{a opa b opb c} doesn't imply any kind of comparison
-between \var{a} and \var{c}, so that, e.g., \code{x < y > z} is
-perfectly legal (though perhaps not pretty).
-
-The operators \code{<}, \code{>}, \code{==}, \code{>=}, \code{<=}, and
-\code{!=} compare
-the values of two objects. The objects need not have the same type.
-If both are numbers, they are converted to a common type. Otherwise,
-objects of different types \emph{always} compare unequal, and are
-ordered consistently but arbitrarily. You can control comparison
-behavior of objects of non-builtin types by defining a \code{__cmp__}
-method or rich comparison methods like \code{__gt__}, described in
-section~\ref{specialnames}.
-
-(This unusual definition of comparison was used to simplify the
-definition of operations like sorting and the \keyword{in} and
-\keyword{not in} operators. In the future, the comparison rules for
-objects of different types are likely to change.)
-
-Comparison of objects of the same type depends on the type:
-
-\begin{itemize}
-
-\item
-Numbers are compared arithmetically.
-
-\item
-Strings are compared lexicographically using the numeric equivalents
-(the result of the built-in function \function{ord()}) of their
-characters. Unicode and 8-bit strings are fully interoperable in this
-behavior.
-
-\item
-Tuples and lists are compared lexicographically using comparison of
-corresponding elements. This means that to compare equal, each
-element must compare equal and the two sequences must be of the same
-type and have the same length.
-
-If not equal, the sequences are ordered the same as their first
-differing elements. For example, \code{cmp([1,2,x], [1,2,y])} returns
-the same as \code{cmp(x,y)}. If the corresponding element does not
-exist, the shorter sequence is ordered first (for example,
-\code{[1,2] < [1,2,3]}).
-
-\item
-Mappings (dictionaries) compare equal if and only if their sorted
-(key, value) lists compare equal.\footnote{The implementation computes
- this efficiently, without constructing lists or sorting.}
-Outcomes other than equality are resolved consistently, but are not
-otherwise defined.\footnote{Earlier versions of Python used
- lexicographic comparison of the sorted (key, value) lists, but this
- was very expensive for the common case of comparing for equality. An
- even earlier version of Python compared dictionaries by identity only,
- but this caused surprises because people expected to be able to test
- a dictionary for emptiness by comparing it to \code{\{\}}.}
-
-\item
-Most other objects of builtin types compare unequal unless they are
-the same object;
-the choice whether one object is considered smaller or larger than
-another one is made arbitrarily but consistently within one
-execution of a program.
-
-\end{itemize}
-
-The operators \keyword{in} and \keyword{not in} test for set
-membership. \code{\var{x} in \var{s}} evaluates to true if \var{x}
-is a member of the set \var{s}, and false otherwise. \code{\var{x}
-not in \var{s}} returns the negation of \code{\var{x} in \var{s}}.
-The set membership test has traditionally been bound to sequences; an
-object is a member of a set if the set is a sequence and contains an
-element equal to that object. However, it is possible for an object
-to support membership tests without being a sequence. In particular,
-dictionaries support membership testing as a nicer way of spelling
-\code{\var{key} in \var{dict}}; other mapping types may follow suit.
-
-For the list and tuple types, \code{\var{x} in \var{y}} is true if and
-only if there exists an index \var{i} such that
-\code{\var{x} == \var{y}[\var{i}]} is true.
-
-For the Unicode and string types, \code{\var{x} in \var{y}} is true if
-and only if \var{x} is a substring of \var{y}. An equivalent test is
-\code{y.find(x) != -1}. Note, \var{x} and \var{y} need not be the
-same type; consequently, \code{u'ab' in 'abc'} will return \code{True}.
-Empty strings are always considered to be a substring of any other string,
-so \code{"" in "abc"} will return \code{True}.
-\versionchanged[Previously, \var{x} was required to be a string of
-length \code{1}]{2.3}
-
-For user-defined classes which define the \method{__contains__()} method,
-\code{\var{x} in \var{y}} is true if and only if
-\code{\var{y}.__contains__(\var{x})} is true.
-
-For user-defined classes which do not define \method{__contains__()} and
-do define \method{__getitem__()}, \code{\var{x} in \var{y}} is true if
-and only if there is a non-negative integer index \var{i} such that
-\code{\var{x} == \var{y}[\var{i}]}, and all lower integer indices
-do not raise \exception{IndexError} exception. (If any other exception
-is raised, it is as if \keyword{in} raised that exception).
-
-The operator \keyword{not in} is defined to have the inverse true value
-of \keyword{in}.
-\opindex{in}
-\opindex{not in}
-\indexii{membership}{test}
-\obindex{sequence}
-
-The operators \keyword{is} and \keyword{is not} test for object identity:
-\code{\var{x} is \var{y}} is true if and only if \var{x} and \var{y}
-are the same object. \code{\var{x} is not \var{y}} yields the inverse
-truth value.
-\opindex{is}
-\opindex{is not}
-\indexii{identity}{test}
-
-
-\section{Boolean operations\label{Booleans}}
-\indexii{Conditional}{expression}
-\indexii{Boolean}{operation}
-
-Boolean operations have the lowest priority of all Python operations:
-
-\begin{productionlist}
- \production{expression}
- {\token{conditional_expression} | \token{lambda_form}}
- \production{old_expression}
- {\token{or_test} | \token{old_lambda_form}}
- \production{conditional_expression}
- {\token{or_test} ["if" \token{or_test} "else" \token{expression}]}
- \production{or_test}
- {\token{and_test} | \token{or_test} "or" \token{and_test}}
- \production{and_test}
- {\token{not_test} | \token{and_test} "and" \token{not_test}}
- \production{not_test}
- {\token{comparison} | "not" \token{not_test}}
-\end{productionlist}
-
-In the context of Boolean operations, and also when expressions are
-used by control flow statements, the following values are interpreted
-as false: \code{False}, \code{None}, numeric zero of all types, and empty
-strings and containers (including strings, tuples, lists, dictionaries,
-sets and frozensets). All other values are interpreted as true.
-
-The operator \keyword{not} yields \code{True} if its argument is false,
-\code{False} otherwise.
-\opindex{not}
-
-The expression \code{\var{x} if \var{C} else \var{y}} first evaluates
-\var{C} (\emph{not} \var{x}); if \var{C} is true, \var{x} is evaluated and
-its value is returned; otherwise, \var{y} is evaluated and its value is
-returned. \versionadded{2.5}
-
-The expression \code{\var{x} and \var{y}} first evaluates \var{x}; if
-\var{x} is false, its value is returned; otherwise, \var{y} is
-evaluated and the resulting value is returned.
-\opindex{and}
-
-The expression \code{\var{x} or \var{y}} first evaluates \var{x}; if
-\var{x} is true, its value is returned; otherwise, \var{y} is
-evaluated and the resulting value is returned.
-\opindex{or}
-
-(Note that neither \keyword{and} nor \keyword{or} restrict the value
-and type they return to \code{False} and \code{True}, but rather return the
-last evaluated argument.
-This is sometimes useful, e.g., if \code{s} is a string that should be
-replaced by a default value if it is empty, the expression
-\code{s or 'foo'} yields the desired value. Because \keyword{not} has to
-invent a value anyway, it does not bother to return a value of the
-same type as its argument, so e.g., \code{not 'foo'} yields \code{False},
-not \code{''}.)
-
-\section{Lambdas\label{lambdas}}
-\indexii{lambda}{expression}
-\indexii{lambda}{form}
-\indexii{anonymous}{function}
-
-\begin{productionlist}
- \production{lambda_form}
- {"lambda" [\token{parameter_list}]: \token{expression}}
- \production{old_lambda_form}
- {"lambda" [\token{parameter_list}]: \token{old_expression}}
-\end{productionlist}
-
-Lambda forms (lambda expressions) have the same syntactic position as
-expressions. They are a shorthand to create anonymous functions; the
-expression \code{lambda \var{arguments}: \var{expression}}
-yields a function object. The unnamed object behaves like a function
-object defined with
-
-\begin{verbatim}
-def name(arguments):
- return expression
-\end{verbatim}
-
-See section \ref{function} for the syntax of parameter lists. Note
-that functions created with lambda forms cannot contain statements
-or annotations.
-\label{lambda}
-
-\section{Expression lists\label{exprlists}}
-\indexii{expression}{list}
-
-\begin{productionlist}
- \production{expression_list}
- {\token{expression} ( "," \token{expression} )* [","]}
-\end{productionlist}
-
-An expression list containing at least one comma yields a
-tuple. The length of the tuple is the number of expressions in the
-list. The expressions are evaluated from left to right.
-\obindex{tuple}
-
-The trailing comma is required only to create a single tuple (a.k.a. a
-\emph{singleton}); it is optional in all other cases. A single
-expression without a trailing comma doesn't create a
-tuple, but rather yields the value of that expression.
-(To create an empty tuple, use an empty pair of parentheses:
-\code{()}.)
-\indexii{trailing}{comma}
-
-\section{Evaluation order\label{evalorder}}
-\indexii{evaluation}{order}
-
-Python evaluates expressions from left to right. Notice that while
-evaluating an assignment, the right-hand side is evaluated before
-the left-hand side.
-
-In the following lines, expressions will be evaluated in the
-arithmetic order of their suffixes:
-
-\begin{verbatim}
-expr1, expr2, expr3, expr4
-(expr1, expr2, expr3, expr4)
-{expr1: expr2, expr3: expr4}
-expr1 + expr2 * (expr3 - expr4)
-func(expr1, expr2, *expr3, **expr4)
-expr3, expr4 = expr1, expr2
-\end{verbatim}
-
-\section{Summary\label{summary}}
-
-The following table summarizes the operator
-precedences\indexii{operator}{precedence} in Python, from lowest
-precedence (least binding) to highest precedence (most binding).
-Operators in the same box have the same precedence. Unless the syntax
-is explicitly given, operators are binary. Operators in the same box
-group left to right (except for comparisons, including tests, which all
-have the same precedence and chain from left to right --- see section
-\ref{comparisons} -- and exponentiation, which groups from right to left).
-
-\begin{tableii}{c|l}{textrm}{Operator}{Description}
- \lineii{\keyword{lambda}} {Lambda expression}
- \hline
- \lineii{\keyword{or}} {Boolean OR}
- \hline
- \lineii{\keyword{and}} {Boolean AND}
- \hline
- \lineii{\keyword{not} \var{x}} {Boolean NOT}
- \hline
- \lineii{\keyword{in}, \keyword{not} \keyword{in}}{Membership tests}
- \lineii{\keyword{is}, \keyword{is not}}{Identity tests}
- \lineii{\code{<}, \code{<=}, \code{>}, \code{>=},
- \code{!=}, \code{==}}
- {Comparisons}
- \hline
- \lineii{\code{|}} {Bitwise OR}
- \hline
- \lineii{\code{\^}} {Bitwise XOR}
- \hline
- \lineii{\code{\&}} {Bitwise AND}
- \hline
- \lineii{\code{<<}, \code{>>}} {Shifts}
- \hline
- \lineii{\code{+}, \code{-}}{Addition and subtraction}
- \hline
- \lineii{\code{*}, \code{/}, \code{\%}}
- {Multiplication, division, remainder}
- \hline
- \lineii{\code{+\var{x}}, \code{-\var{x}}} {Positive, negative}
- \lineii{\code{\~\var{x}}} {Bitwise not}
- \hline
- \lineii{\code{**}} {Exponentiation}
- \hline
- \lineii{\code{\var{x}.\var{attribute}}} {Attribute reference}
- \lineii{\code{\var{x}[\var{index}]}} {Subscription}
- \lineii{\code{\var{x}[\var{index}:\var{index}]}} {Slicing}
- \lineii{\code{\var{f}(\var{arguments}...)}} {Function call}
- \hline
- \lineii{\code{(\var{expressions}\ldots)}} {Binding or tuple display}
- \lineii{\code{[\var{expressions}\ldots]}} {List display}
- \lineii{\code{\{\var{key}:\var{datum}\ldots\}}}{Dictionary display}
- \lineii{\code{`\var{expressions}\ldots`}} {String conversion}
-\end{tableii}
diff --git a/Doc/ref/ref6.tex b/Doc/ref/ref6.tex
deleted file mode 100644
index 1139005..0000000
--- a/Doc/ref/ref6.tex
+++ /dev/null
@@ -1,818 +0,0 @@
-\chapter{Simple statements \label{simple}}
-\indexii{simple}{statement}
-
-Simple statements are comprised within a single logical line.
-Several simple statements may occur on a single line separated
-by semicolons. The syntax for simple statements is:
-
-\begin{productionlist}
- \production{simple_stmt}{\token{expression_stmt}}
- \productioncont{| \token{assert_stmt}}
- \productioncont{| \token{assignment_stmt}}
- \productioncont{| \token{augmented_assignment_stmt}}
- \productioncont{| \token{pass_stmt}}
- \productioncont{| \token{del_stmt}}
- \productioncont{| \token{return_stmt}}
- \productioncont{| \token{yield_stmt}}
- \productioncont{| \token{raise_stmt}}
- \productioncont{| \token{break_stmt}}
- \productioncont{| \token{continue_stmt}}
- \productioncont{| \token{import_stmt}}
- \productioncont{| \token{global_stmt}}
-\end{productionlist}
-
-
-\section{Expression statements \label{exprstmts}}
-\indexii{expression}{statement}
-
-Expression statements are used (mostly interactively) to compute and
-write a value, or (usually) to call a procedure (a function that
-returns no meaningful result; in Python, procedures return the value
-\code{None}). Other uses of expression statements are allowed and
-occasionally useful. The syntax for an expression statement is:
-
-\begin{productionlist}
- \production{expression_stmt}
- {\token{expression_list}}
-\end{productionlist}
-
-An expression statement evaluates the expression list (which may be a
-single expression).
-\indexii{expression}{list}
-
-In interactive mode, if the value is not \code{None}, it is converted
-to a string using the built-in \function{repr()}\bifuncindex{repr}
-function and the resulting string is written to standard output (see
-section~\ref{print}) on a line by itself. (Expression statements
-yielding \code{None} are not written, so that procedure calls do not
-cause any output.)
-\obindex{None}
-\indexii{string}{conversion}
-\index{output}
-\indexii{standard}{output}
-\indexii{writing}{values}
-\indexii{procedure}{call}
-
-
-\section{Assert statements \label{assert}}
-
-Assert statements\stindex{assert} are a convenient way to insert
-debugging assertions\indexii{debugging}{assertions} into a program:
-
-\begin{productionlist}
- \production{assert_stmt}
- {"assert" \token{expression} ["," \token{expression}]}
-\end{productionlist}
-
-The simple form, \samp{assert expression}, is equivalent to
-
-\begin{verbatim}
-if __debug__:
- if not expression: raise AssertionError
-\end{verbatim}
-
-The extended form, \samp{assert expression1, expression2}, is
-equivalent to
-
-\begin{verbatim}
-if __debug__:
- if not expression1: raise AssertionError, expression2
-\end{verbatim}
-
-These equivalences assume that \code{__debug__}\ttindex{__debug__} and
-\exception{AssertionError}\exindex{AssertionError} refer to the built-in
-variables with those names. In the current implementation, the
-built-in variable \code{__debug__} is \code{True} under normal
-circumstances, \code{False} when optimization is requested (command line
-option -O). The current code generator emits no code for an assert
-statement when optimization is requested at compile time. Note that it
-is unnecessary to include the source code for the expression that failed
-in the error message;
-it will be displayed as part of the stack trace.
-
-Assignments to \code{__debug__} are illegal. The value for the
-built-in variable is determined when the interpreter starts.
-
-
-\section{Assignment statements \label{assignment}}
-
-Assignment statements\indexii{assignment}{statement} are used to
-(re)bind names to values and to modify attributes or items of mutable
-objects:
-\indexii{binding}{name}
-\indexii{rebinding}{name}
-\obindex{mutable}
-\indexii{attribute}{assignment}
-
-\begin{productionlist}
- \production{assignment_stmt}
- {(\token{target_list} "=")+
- (\token{expression_list} | \token{yield_expression})}
- \production{target_list}
- {\token{target} ("," \token{target})* [","]}
- \production{target}
- {\token{identifier}}
- \productioncont{| "(" \token{target_list} ")"}
- \productioncont{| "[" \token{target_list} "]"}
- \productioncont{| \token{attributeref}}
- \productioncont{| \token{subscription}}
- \productioncont{| \token{slicing}}
-\end{productionlist}
-
-(See section~\ref{primaries} for the syntax definitions for the last
-three symbols.)
-
-An assignment statement evaluates the expression list (remember that
-this can be a single expression or a comma-separated list, the latter
-yielding a tuple) and assigns the single resulting object to each of
-the target lists, from left to right.
-\indexii{expression}{list}
-
-Assignment is defined recursively depending on the form of the target
-(list). When a target is part of a mutable object (an attribute
-reference, subscription or slicing), the mutable object must
-ultimately perform the assignment and decide about its validity, and
-may raise an exception if the assignment is unacceptable. The rules
-observed by various types and the exceptions raised are given with the
-definition of the object types (see section~\ref{types}).
-\index{target}
-\indexii{target}{list}
-
-Assignment of an object to a target list is recursively defined as
-follows.
-\indexiii{target}{list}{assignment}
-
-\begin{itemize}
-\item
-If the target list is a single target: The object is assigned to that
-target.
-
-\item
-If the target list is a comma-separated list of targets: The object
-must be a sequence with the same number of items as there are
-targets in the target list, and the items are assigned, from left to
-right, to the corresponding targets. (This rule is relaxed as of
-Python 1.5; in earlier versions, the object had to be a tuple. Since
-strings are sequences, an assignment like \samp{a, b = "xy"} is
-now legal as long as the string has the right length.)
-
-\end{itemize}
-
-Assignment of an object to a single target is recursively defined as
-follows.
-
-\begin{itemize} % nested
-
-\item
-If the target is an identifier (name):
-
-\begin{itemize}
-
-\item
-If the name does not occur in a \keyword{global} statement in the current
-code block: the name is bound to the object in the current local
-namespace.
-\stindex{global}
-
-\item
-Otherwise: the name is bound to the object in the current global
-namespace.
-
-\end{itemize} % nested
-
-The name is rebound if it was already bound. This may cause the
-reference count for the object previously bound to the name to reach
-zero, causing the object to be deallocated and its
-destructor\index{destructor} (if it has one) to be called.
-
-\item
-If the target is a target list enclosed in parentheses or in square
-brackets: The object must be a sequence with the same number of items
-as there are targets in the target list, and its items are assigned,
-from left to right, to the corresponding targets.
-
-\item
-If the target is an attribute reference: The primary expression in the
-reference is evaluated. It should yield an object with assignable
-attributes; if this is not the case, \exception{TypeError} is raised. That
-object is then asked to assign the assigned object to the given
-attribute; if it cannot perform the assignment, it raises an exception
-(usually but not necessarily \exception{AttributeError}).
-\indexii{attribute}{assignment}
-
-\item
-If the target is a subscription: The primary expression in the
-reference is evaluated. It should yield either a mutable sequence
-object (such as a list) or a mapping object (such as a dictionary). Next,
-the subscript expression is evaluated.
-\indexii{subscription}{assignment}
-\obindex{mutable}
-
-If the primary is a mutable sequence object (such as a list), the subscript
-must yield a plain integer. If it is negative, the sequence's length
-is added to it. The resulting value must be a nonnegative integer
-less than the sequence's length, and the sequence is asked to assign
-the assigned object to its item with that index. If the index is out
-of range, \exception{IndexError} is raised (assignment to a subscripted
-sequence cannot add new items to a list).
-\obindex{sequence}
-\obindex{list}
-
-If the primary is a mapping object (such as a dictionary), the subscript must
-have a type compatible with the mapping's key type, and the mapping is
-then asked to create a key/datum pair which maps the subscript to
-the assigned object. This can either replace an existing key/value
-pair with the same key value, or insert a new key/value pair (if no
-key with the same value existed).
-\obindex{mapping}
-\obindex{dictionary}
-
-\item
-If the target is a slicing: The primary expression in the reference is
-evaluated. It should yield a mutable sequence object (such as a list). The
-assigned object should be a sequence object of the same type. Next,
-the lower and upper bound expressions are evaluated, insofar they are
-present; defaults are zero and the sequence's length. The bounds
-should evaluate to (small) integers. If either bound is negative, the
-sequence's length is added to it. The resulting bounds are clipped to
-lie between zero and the sequence's length, inclusive. Finally, the
-sequence object is asked to replace the slice with the items of the
-assigned sequence. The length of the slice may be different from the
-length of the assigned sequence, thus changing the length of the
-target sequence, if the object allows it.
-\indexii{slicing}{assignment}
-
-\end{itemize}
-
-(In the current implementation, the syntax for targets is taken
-to be the same as for expressions, and invalid syntax is rejected
-during the code generation phase, causing less detailed error
-messages.)
-
-WARNING: Although the definition of assignment implies that overlaps
-between the left-hand side and the right-hand side are `safe' (for example
-\samp{a, b = b, a} swaps two variables), overlaps \emph{within} the
-collection of assigned-to variables are not safe! For instance, the
-following program prints \samp{[0, 2]}:
-
-\begin{verbatim}
-x = [0, 1]
-i = 0
-i, x[i] = 1, 2
-print x
-\end{verbatim}
-
-
-\subsection{Augmented assignment statements \label{augassign}}
-
-Augmented assignment is the combination, in a single statement, of a binary
-operation and an assignment statement:
-\indexii{augmented}{assignment}
-\index{statement!assignment, augmented}
-
-\begin{productionlist}
- \production{augmented_assignment_stmt}
- {\token{target} \token{augop}
- (\token{expression_list} | \token{yield_expression})}
- \production{augop}
- {"+=" | "-=" | "*=" | "/=" | "\%=" | "**="}
- \productioncont{| ">>=" | "<<=" | "\&=" | "\textasciicircum=" | "|="}
-\end{productionlist}
-
-(See section~\ref{primaries} for the syntax definitions for the last
-three symbols.)
-
-An augmented assignment evaluates the target (which, unlike normal
-assignment statements, cannot be an unpacking) and the expression
-list, performs the binary operation specific to the type of assignment
-on the two operands, and assigns the result to the original
-target. The target is only evaluated once.
-
-An augmented assignment expression like \code{x += 1} can be rewritten as
-\code{x = x + 1} to achieve a similar, but not exactly equal effect. In the
-augmented version, \code{x} is only evaluated once. Also, when possible, the
-actual operation is performed \emph{in-place}, meaning that rather than
-creating a new object and assigning that to the target, the old object is
-modified instead.
-
-With the exception of assigning to tuples and multiple targets in a single
-statement, the assignment done by augmented assignment statements is handled
-the same way as normal assignments. Similarly, with the exception of the
-possible \emph{in-place} behavior, the binary operation performed by
-augmented assignment is the same as the normal binary operations.
-
-For targets which are attribute references, the initial value is
-retrieved with a \method{getattr()} and the result is assigned with a
-\method{setattr()}. Notice that the two methods do not necessarily
-refer to the same variable. When \method{getattr()} refers to a class
-variable, \method{setattr()} still writes to an instance variable.
-For example:
-
-\begin{verbatim}
-class A:
- x = 3 # class variable
-a = A()
-a.x += 1 # writes a.x as 4 leaving A.x as 3
-\end{verbatim}
-
-
-\section{The \keyword{pass} statement \label{pass}}
-\stindex{pass}
-
-\begin{productionlist}
- \production{pass_stmt}
- {"pass"}
-\end{productionlist}
-
-\keyword{pass} is a null operation --- when it is executed, nothing
-happens. It is useful as a placeholder when a statement is
-required syntactically, but no code needs to be executed, for example:
-\indexii{null}{operation}
-
-\begin{verbatim}
-def f(arg): pass # a function that does nothing (yet)
-
-class C: pass # a class with no methods (yet)
-\end{verbatim}
-
-
-\section{The \keyword{del} statement \label{del}}
-\stindex{del}
-
-\begin{productionlist}
- \production{del_stmt}
- {"del" \token{target_list}}
-\end{productionlist}
-
-Deletion is recursively defined very similar to the way assignment is
-defined. Rather that spelling it out in full details, here are some
-hints.
-\indexii{deletion}{target}
-\indexiii{deletion}{target}{list}
-
-Deletion of a target list recursively deletes each target, from left
-to right.
-
-Deletion of a name removes the binding of that name
-from the local or global namespace, depending on whether the name
-occurs in a \keyword{global} statement in the same code block. If the
-name is unbound, a \exception{NameError} exception will be raised.
-\stindex{global}
-\indexii{unbinding}{name}
-
-It is illegal to delete a name from the local namespace if it occurs
-as a free variable\indexii{free}{variable} in a nested block.
-
-Deletion of attribute references, subscriptions and slicings
-is passed to the primary object involved; deletion of a slicing
-is in general equivalent to assignment of an empty slice of the
-right type (but even this is determined by the sliced object).
-\indexii{attribute}{deletion}
-
-
-\section{The \keyword{return} statement \label{return}}
-\stindex{return}
-
-\begin{productionlist}
- \production{return_stmt}
- {"return" [\token{expression_list}]}
-\end{productionlist}
-
-\keyword{return} may only occur syntactically nested in a function
-definition, not within a nested class definition.
-\indexii{function}{definition}
-\indexii{class}{definition}
-
-If an expression list is present, it is evaluated, else \code{None}
-is substituted.
-
-\keyword{return} leaves the current function call with the expression
-list (or \code{None}) as return value.
-
-When \keyword{return} passes control out of a \keyword{try} statement
-with a \keyword{finally} clause, that \keyword{finally} clause is executed
-before really leaving the function.
-\kwindex{finally}
-
-In a generator function, the \keyword{return} statement is not allowed
-to include an \grammartoken{expression_list}. In that context, a bare
-\keyword{return} indicates that the generator is done and will cause
-\exception{StopIteration} to be raised.
-
-
-\section{The \keyword{yield} statement \label{yield}}
-\stindex{yield}
-
-\begin{productionlist}
- \production{yield_stmt}
- {\token{yield_expression}}
-\end{productionlist}
-
-\index{generator!function}
-\index{generator!iterator}
-\index{function!generator}
-\exindex{StopIteration}
-
-The \keyword{yield} statement is only used when defining a generator
-function, and is only used in the body of the generator function.
-Using a \keyword{yield} statement in a function definition is
-sufficient to cause that definition to create a generator function
-instead of a normal function.
-
-When a generator function is called, it returns an iterator known as a generator
-iterator, or more commonly, a generator. The body of the generator function is
-executed by calling the generator's \method{__next__()} method repeatedly until
-it raises an exception.
-
-When a \keyword{yield} statement is executed, the state of the generator is
-frozen and the value of \grammartoken{expression_list} is returned to
-\method{__next__()}'s caller. By ``frozen'' we mean that all local state is
-retained, including the current bindings of local variables, the instruction
-pointer, and the internal evaluation stack: enough information is saved so that
-the next time \method{__next__()} is invoked, the function can proceed exactly
-as if the \keyword{yield} statement were just another external call.
-
-As of Python version 2.5, the \keyword{yield} statement is now
-allowed in the \keyword{try} clause of a \keyword{try} ...\
-\keyword{finally} construct. If the generator is not resumed before
-it is finalized (by reaching a zero reference count or by being garbage
-collected), the generator-iterator's \method{close()} method will be
-called, allowing any pending \keyword{finally} clauses to execute.
-
-\begin{notice}
-In Python 2.2, the \keyword{yield} statement is only allowed
-when the \code{generators} feature has been enabled. It will always
-be enabled in Python 2.3. This \code{__future__} import statement can
-be used to enable the feature:
-
-\begin{verbatim}
-from __future__ import generators
-\end{verbatim}
-\end{notice}
-
-
-\begin{seealso}
- \seepep{0255}{Simple Generators}
- {The proposal for adding generators and the \keyword{yield}
- statement to Python.}
-
- \seepep{0342}{Coroutines via Enhanced Generators}
- {The proposal that, among other generator enhancements,
- proposed allowing \keyword{yield} to appear inside a
- \keyword{try} ... \keyword{finally} block.}
-\end{seealso}
-
-
-\section{The \keyword{raise} statement \label{raise}}
-\stindex{raise}
-
-\begin{productionlist}
- \production{raise_stmt}
- {"raise" [\token{expression} ["," \token{expression}
- ["," \token{expression}]]]}
-\end{productionlist}
-
-If no expressions are present, \keyword{raise} re-raises the last
-exception that was active in the current scope. If no exception is
-active in the current scope, a \exception{TypeError} exception is
-raised indicating that this is an error (if running under IDLE, a
-\exception{Queue.Empty} exception is raised instead).
-\index{exception}
-\indexii{raising}{exception}
-
-Otherwise, \keyword{raise} evaluates the expressions to get three
-objects, using \code{None} as the value of omitted expressions. The
-first two objects are used to determine the \emph{type} and
-\emph{value} of the exception.
-
-If the first object is an instance, the type of the exception is the
-class of the instance, the instance itself is the value, and the
-second object must be \code{None}.
-
-If the first object is a class, it becomes the type of the exception.
-The second object is used to determine the exception value: If it is
-an instance of the class, the instance becomes the exception value.
-If the second object is a tuple, it is used as the argument list for
-the class constructor; if it is \code{None}, an empty argument list is
-used, and any other object is treated as a single argument to the
-constructor. The instance so created by calling the constructor is
-used as the exception value.
-
-If a third object is present and not \code{None}, it must be a
-traceback\obindex{traceback} object (see section~\ref{traceback}), and
-it is substituted instead of the current location as the place where
-the exception occurred. If the third object is present and not a
-traceback object or \code{None}, a \exception{TypeError} exception is
-raised. The three-expression form of \keyword{raise} is useful to
-re-raise an exception transparently in an except clause, but
-\keyword{raise} with no expressions should be preferred if the
-exception to be re-raised was the most recently active exception in
-the current scope.
-
-Additional information on exceptions can be found in
-section~\ref{exceptions}, and information about handling exceptions is
-in section~\ref{try}.
-
-
-\section{The \keyword{break} statement \label{break}}
-\stindex{break}
-
-\begin{productionlist}
- \production{break_stmt}
- {"break"}
-\end{productionlist}
-
-\keyword{break} may only occur syntactically nested in a \keyword{for}
-or \keyword{while} loop, but not nested in a function or class definition
-within that loop.
-\stindex{for}
-\stindex{while}
-\indexii{loop}{statement}
-
-It terminates the nearest enclosing loop, skipping the optional
-\keyword{else} clause if the loop has one.
-\kwindex{else}
-
-If a \keyword{for} loop is terminated by \keyword{break}, the loop control
-target keeps its current value.
-\indexii{loop control}{target}
-
-When \keyword{break} passes control out of a \keyword{try} statement
-with a \keyword{finally} clause, that \keyword{finally} clause is executed
-before really leaving the loop.
-\kwindex{finally}
-
-
-\section{The \keyword{continue} statement \label{continue}}
-\stindex{continue}
-
-\begin{productionlist}
- \production{continue_stmt}
- {"continue"}
-\end{productionlist}
-
-\keyword{continue} may only occur syntactically nested in a \keyword{for} or
-\keyword{while} loop, but not nested in a function or class definition or
-\keyword{finally} statement within that loop.\footnote{It may
-occur within an \keyword{except} or \keyword{else} clause. The
-restriction on occurring in the \keyword{try} clause is implementor's
-laziness and will eventually be lifted.}
-It continues with the next cycle of the nearest enclosing loop.
-\stindex{for}
-\stindex{while}
-\indexii{loop}{statement}
-\kwindex{finally}
-
-
-\section{The \keyword{import} statement \label{import}}
-\stindex{import}
-\index{module!importing}
-\indexii{name}{binding}
-\kwindex{from}
-
-\begin{productionlist}
- \production{import_stmt}
- {"import" \token{module} ["as" \token{name}]
- ( "," \token{module} ["as" \token{name}] )*}
- \productioncont{| "from" \token{relative_module} "import" \token{identifier}
- ["as" \token{name}]}
- \productioncont{ ( "," \token{identifier} ["as" \token{name}] )*}
- \productioncont{| "from" \token{relative_module} "import" "("
- \token{identifier} ["as" \token{name}]}
- \productioncont{ ( "," \token{identifier} ["as" \token{name}] )* [","] ")"}
- \productioncont{| "from" \token{module} "import" "*"}
- \production{module}
- {(\token{identifier} ".")* \token{identifier}}
- \production{relative_module}
- {"."* \token{module} | "."+}
- \production{name}
- {\token{identifier}}
-\end{productionlist}
-
-Import statements are executed in two steps: (1) find a module, and
-initialize it if necessary; (2) define a name or names in the local
-namespace (of the scope where the \keyword{import} statement occurs).
-The first form (without \keyword{from}) repeats these steps for each
-identifier in the list. The form with \keyword{from} performs step
-(1) once, and then performs step (2) repeatedly.
-
-In this context, to ``initialize'' a built-in or extension module means to
-call an initialization function that the module must provide for the purpose
-(in the reference implementation, the function's name is obtained by
-prepending string ``init'' to the module's name); to ``initialize'' a
-Python-coded module means to execute the module's body.
-
-The system maintains a table of modules that have been or are being
-initialized,
-indexed by module name. This table is
-accessible as \code{sys.modules}. When a module name is found in
-this table, step (1) is finished. If not, a search for a module
-definition is started. When a module is found, it is loaded. Details
-of the module searching and loading process are implementation and
-platform specific. It generally involves searching for a ``built-in''
-module with the given name and then searching a list of locations
-given as \code{sys.path}.
-\withsubitem{(in module sys)}{\ttindex{modules}}
-\ttindex{sys.modules}
-\indexii{module}{name}
-\indexii{built-in}{module}
-\indexii{user-defined}{module}
-\refbimodindex{sys}
-\indexii{filename}{extension}
-\indexiii{module}{search}{path}
-
-If a built-in module is found,\indexii{module}{initialization} its
-built-in initialization code is executed and step (1) is finished. If
-no matching file is found,
-\exception{ImportError}\exindex{ImportError} is raised.
-\index{code block}If a file is found, it is parsed,
-yielding an executable code block. If a syntax error occurs,
-\exception{SyntaxError}\exindex{SyntaxError} is raised. Otherwise, an
-empty module of the given name is created and inserted in the module
-table, and then the code block is executed in the context of this
-module. Exceptions during this execution terminate step (1).
-
-When step (1) finishes without raising an exception, step (2) can
-begin.
-
-The first form of \keyword{import} statement binds the module name in
-the local namespace to the module object, and then goes on to import
-the next identifier, if any. If the module name is followed by
-\keyword{as}, the name following \keyword{as} is used as the local
-name for the module.
-
-The \keyword{from} form does not bind the module name: it goes through the
-list of identifiers, looks each one of them up in the module found in step
-(1), and binds the name in the local namespace to the object thus found.
-As with the first form of \keyword{import}, an alternate local name can be
-supplied by specifying "\keyword{as} localname". If a name is not found,
-\exception{ImportError} is raised. If the list of identifiers is replaced
-by a star (\character{*}), all public names defined in the module are
-bound in the local namespace of the \keyword{import} statement..
-\indexii{name}{binding}
-\exindex{ImportError}
-
-The \emph{public names} defined by a module are determined by checking
-the module's namespace for a variable named \code{__all__}; if
-defined, it must be a sequence of strings which are names defined or
-imported by that module. The names given in \code{__all__} are all
-considered public and are required to exist. If \code{__all__} is not
-defined, the set of public names includes all names found in the
-module's namespace which do not begin with an underscore character
-(\character{_}). \code{__all__} should contain the entire public API.
-It is intended to avoid accidentally exporting items that are not part
-of the API (such as library modules which were imported and used within
-the module).
-\withsubitem{(optional module attribute)}{\ttindex{__all__}}
-
-The \keyword{from} form with \samp{*} may only occur in a module
-scope. If the wild card form of import --- \samp{import *} --- is
-used in a function and the function contains or is a nested block with
-free variables, the compiler will raise a \exception{SyntaxError}.
-
-\kwindex{from}
-\stindex{from}
-
-\strong{Hierarchical module names:}\indexiii{hierarchical}{module}{names}
-when the module names contains one or more dots, the module search
-path is carried out differently. The sequence of identifiers up to
-the last dot is used to find a ``package''\index{packages}; the final
-identifier is then searched inside the package. A package is
-generally a subdirectory of a directory on \code{sys.path} that has a
-file \file{__init__.py}.\ttindex{__init__.py}
-%
-[XXX Can't be bothered to spell this out right now; see the URL
-\url{http://www.python.org/doc/essays/packages.html} for more details, also
-about how the module search works from inside a package.]
-
-The built-in function \function{__import__()} is provided to support
-applications that determine which modules need to be loaded
-dynamically; refer to \ulink{Built-in
-Functions}{../lib/built-in-funcs.html} in the
-\citetitle[../lib/lib.html]{Python Library Reference} for additional
-information.
-\bifuncindex{__import__}
-
-\subsection{Future statements \label{future}}
-
-A \dfn{future statement}\indexii{future}{statement} is a directive to
-the compiler that a particular module should be compiled using syntax
-or semantics that will be available in a specified future release of
-Python. The future statement is intended to ease migration to future
-versions of Python that introduce incompatible changes to the
-language. It allows use of the new features on a per-module basis
-before the release in which the feature becomes standard.
-
-\begin{productionlist}[*]
- \production{future_statement}
- {"from" "__future__" "import" feature ["as" name]}
- \productioncont{ ("," feature ["as" name])*}
- \productioncont{| "from" "__future__" "import" "(" feature ["as" name]}
- \productioncont{ ("," feature ["as" name])* [","] ")"}
- \production{feature}{identifier}
- \production{name}{identifier}
-\end{productionlist}
-
-A future statement must appear near the top of the module. The only
-lines that can appear before a future statement are:
-
-\begin{itemize}
-
-\item the module docstring (if any),
-\item comments,
-\item blank lines, and
-\item other future statements.
-
-\end{itemize}
-
-The features recognized by Python 2.5 are \samp{absolute_import},
-\samp{division}, \samp{generators}, \samp{nested_scopes} and
-\samp{with_statement}. \samp{generators} and \samp{nested_scopes}
-are redundant in Python version 2.3 and above because they are always
-enabled.
-
-A future statement is recognized and treated specially at compile
-time: Changes to the semantics of core constructs are often
-implemented by generating different code. It may even be the case
-that a new feature introduces new incompatible syntax (such as a new
-reserved word), in which case the compiler may need to parse the
-module differently. Such decisions cannot be pushed off until
-runtime.
-
-For any given release, the compiler knows which feature names have been
-defined, and raises a compile-time error if a future statement contains
-a feature not known to it.
-
-The direct runtime semantics are the same as for any import statement:
-there is a standard module \module{__future__}, described later, and
-it will be imported in the usual way at the time the future statement
-is executed.
-
-The interesting runtime semantics depend on the specific feature
-enabled by the future statement.
-
-Note that there is nothing special about the statement:
-
-\begin{verbatim}
-import __future__ [as name]
-\end{verbatim}
-
-That is not a future statement; it's an ordinary import statement with
-no special semantics or syntax restrictions.
-
-Code compiled by calls to the builtin functions \function{exec()} and
-\function{compile()} that occur in a module
-\module{M} containing a future statement will, by default, use the new
-syntax or semantics associated with the future statement. This can,
-starting with Python 2.2 be controlled by optional arguments to
-\function{compile()} --- see the documentation of that function in the
-\citetitle[../lib/built-in-funcs.html]{Python Library Reference} for
-details.
-
-A future statement typed at an interactive interpreter prompt will
-take effect for the rest of the interpreter session. If an
-interpreter is started with the \programopt{-i} option, is passed a
-script name to execute, and the script includes a future statement, it
-will be in effect in the interactive session started after the script
-is executed.
-
-\section{The \keyword{global} statement \label{global}}
-\stindex{global}
-
-\begin{productionlist}
- \production{global_stmt}
- {"global" \token{identifier} ("," \token{identifier})*}
-\end{productionlist}
-
-The \keyword{global} statement is a declaration which holds for the
-entire current code block. It means that the listed identifiers are to be
-interpreted as globals. It would be impossible to assign to a global
-variable without \keyword{global}, although free variables may refer
-to globals without being declared global.
-\indexiii{global}{name}{binding}
-
-Names listed in a \keyword{global} statement must not be used in the same
-code block textually preceding that \keyword{global} statement.
-
-Names listed in a \keyword{global} statement must not be defined as formal
-parameters or in a \keyword{for} loop control target, \keyword{class}
-definition, function definition, or \keyword{import} statement.
-
-(The current implementation does not enforce the latter two
-restrictions, but programs should not abuse this freedom, as future
-implementations may enforce them or silently change the meaning of the
-program.)
-
-\strong{Programmer's note:}
-the \keyword{global} is a directive to the parser. It
-applies only to code parsed at the same time as the \keyword{global}
-statement. In particular, a \keyword{global} statement contained in a
-string or code object supplied to the builtin \function{exec()} function
-does not affect the code block \emph{containing} the function call,
-and code contained in such a string is unaffected by \keyword{global}
-statements in the code containing the function call. The same applies to the
-\function{eval()} and \function{compile()} functions.
-\bifuncindex{exec}
-\bifuncindex{eval}
-\bifuncindex{compile}
-
diff --git a/Doc/ref/ref7.tex b/Doc/ref/ref7.tex
deleted file mode 100644
index 9294557..0000000
--- a/Doc/ref/ref7.tex
+++ /dev/null
@@ -1,552 +0,0 @@
-\chapter{Compound statements\label{compound}}
-\indexii{compound}{statement}
-
-Compound statements contain (groups of) other statements; they affect
-or control the execution of those other statements in some way. In
-general, compound statements span multiple lines, although in simple
-incarnations a whole compound statement may be contained in one line.
-
-The \keyword{if}, \keyword{while} and \keyword{for} statements implement
-traditional control flow constructs. \keyword{try} specifies exception
-handlers and/or cleanup code for a group of statements. Function and
-class definitions are also syntactically compound statements.
-
-Compound statements consist of one or more `clauses.' A clause
-consists of a header and a `suite.' The clause headers of a
-particular compound statement are all at the same indentation level.
-Each clause header begins with a uniquely identifying keyword and ends
-with a colon. A suite is a group of statements controlled by a
-clause. A suite can be one or more semicolon-separated simple
-statements on the same line as the header, following the header's
-colon, or it can be one or more indented statements on subsequent
-lines. Only the latter form of suite can contain nested compound
-statements; the following is illegal, mostly because it wouldn't be
-clear to which \keyword{if} clause a following \keyword{else} clause would
-belong:
-\index{clause}
-\index{suite}
-
-\begin{verbatim}
-if test1: if test2: print x
-\end{verbatim}
-
-Also note that the semicolon binds tighter than the colon in this
-context, so that in the following example, either all or none of the
-\keyword{print} statements are executed:
-
-\begin{verbatim}
-if x < y < z: print x; print y; print z
-\end{verbatim}
-
-Summarizing:
-
-\begin{productionlist}
- \production{compound_stmt}
- {\token{if_stmt}}
- \productioncont{| \token{while_stmt}}
- \productioncont{| \token{for_stmt}}
- \productioncont{| \token{try_stmt}}
- \productioncont{| \token{with_stmt}}
- \productioncont{| \token{funcdef}}
- \productioncont{| \token{classdef}}
- \production{suite}
- {\token{stmt_list} NEWLINE
- | NEWLINE INDENT \token{statement}+ DEDENT}
- \production{statement}
- {\token{stmt_list} NEWLINE | \token{compound_stmt}}
- \production{stmt_list}
- {\token{simple_stmt} (";" \token{simple_stmt})* [";"]}
-\end{productionlist}
-
-Note that statements always end in a
-\code{NEWLINE}\index{NEWLINE token} possibly followed by a
-\code{DEDENT}.\index{DEDENT token} Also note that optional
-continuation clauses always begin with a keyword that cannot start a
-statement, thus there are no ambiguities (the `dangling
-\keyword{else}' problem is solved in Python by requiring nested
-\keyword{if} statements to be indented).
-\indexii{dangling}{else}
-
-The formatting of the grammar rules in the following sections places
-each clause on a separate line for clarity.
-
-
-\section{The \keyword{if} statement\label{if}}
-\stindex{if}
-
-The \keyword{if} statement is used for conditional execution:
-
-\begin{productionlist}
- \production{if_stmt}
- {"if" \token{expression} ":" \token{suite}}
- \productioncont{( "elif" \token{expression} ":" \token{suite} )*}
- \productioncont{["else" ":" \token{suite}]}
-\end{productionlist}
-
-It selects exactly one of the suites by evaluating the expressions one
-by one until one is found to be true (see section~\ref{Booleans} for
-the definition of true and false); then that suite is executed (and no
-other part of the \keyword{if} statement is executed or evaluated). If
-all expressions are false, the suite of the \keyword{else} clause, if
-present, is executed.
-\kwindex{elif}
-\kwindex{else}
-
-
-\section{The \keyword{while} statement\label{while}}
-\stindex{while}
-\indexii{loop}{statement}
-
-The \keyword{while} statement is used for repeated execution as long
-as an expression is true:
-
-\begin{productionlist}
- \production{while_stmt}
- {"while" \token{expression} ":" \token{suite}}
- \productioncont{["else" ":" \token{suite}]}
-\end{productionlist}
-
-This repeatedly tests the expression and, if it is true, executes the
-first suite; if the expression is false (which may be the first time it
-is tested) the suite of the \keyword{else} clause, if present, is
-executed and the loop terminates.
-\kwindex{else}
-
-A \keyword{break} statement executed in the first suite terminates the
-loop without executing the \keyword{else} clause's suite. A
-\keyword{continue} statement executed in the first suite skips the rest
-of the suite and goes back to testing the expression.
-\stindex{break}
-\stindex{continue}
-
-
-\section{The \keyword{for} statement\label{for}}
-\stindex{for}
-\indexii{loop}{statement}
-
-The \keyword{for} statement is used to iterate over the elements of a
-sequence (such as a string, tuple or list) or other iterable object:
-\obindex{sequence}
-
-\begin{productionlist}
- \production{for_stmt}
- {"for" \token{target_list} "in" \token{expression_list}
- ":" \token{suite}}
- \productioncont{["else" ":" \token{suite}]}
-\end{productionlist}
-
-The expression list is evaluated once; it should yield an iterable
-object. An iterator is created for the result of the
-{}\code{expression_list}. The suite is then executed once for each
-item provided by the iterator, in the
-order of ascending indices. Each item in turn is assigned to the
-target list using the standard rules for assignments, and then the
-suite is executed. When the items are exhausted (which is immediately
-when the sequence is empty), the suite in the \keyword{else} clause, if
-present, is executed, and the loop terminates.
-\kwindex{in}
-\kwindex{else}
-\indexii{target}{list}
-
-A \keyword{break} statement executed in the first suite terminates the
-loop without executing the \keyword{else} clause's suite. A
-\keyword{continue} statement executed in the first suite skips the rest
-of the suite and continues with the next item, or with the \keyword{else}
-clause if there was no next item.
-\stindex{break}
-\stindex{continue}
-
-The suite may assign to the variable(s) in the target list; this does
-not affect the next item assigned to it.
-
-The target list is not deleted when the loop is finished, but if the
-sequence is empty, it will not have been assigned to at all by the
-loop. Hint: the built-in function \function{range()} returns a
-sequence of integers suitable to emulate the effect of Pascal's
-\code{for i := a to b do};
-e.g., \code{range(3)} returns the list \code{[0, 1, 2]}.
-\bifuncindex{range}
-\indexii{Pascal}{language}
-
-\warning{There is a subtlety when the sequence is being modified
-by the loop (this can only occur for mutable sequences, i.e. lists).
-An internal counter is used to keep track of which item is used next,
-and this is incremented on each iteration. When this counter has
-reached the length of the sequence the loop terminates. This means that
-if the suite deletes the current (or a previous) item from the
-sequence, the next item will be skipped (since it gets the index of
-the current item which has already been treated). Likewise, if the
-suite inserts an item in the sequence before the current item, the
-current item will be treated again the next time through the loop.
-This can lead to nasty bugs that can be avoided by making a temporary
-copy using a slice of the whole sequence, e.g.,
-\index{loop!over mutable sequence}
-\index{mutable sequence!loop over}}
-
-\begin{verbatim}
-for x in a[:]:
- if x < 0: a.remove(x)
-\end{verbatim}
-
-
-\section{The \keyword{try} statement\label{try}}
-\stindex{try}
-
-The \keyword{try} statement specifies exception handlers and/or cleanup
-code for a group of statements:
-
-\begin{productionlist}
- \production{try_stmt} {try1_stmt | try2_stmt}
- \production{try1_stmt}
- {"try" ":" \token{suite}}
- \productioncont{("except" [\token{expression}
- ["," \token{target}]] ":" \token{suite})+}
- \productioncont{["else" ":" \token{suite}]}
- \productioncont{["finally" ":" \token{suite}]}
- \production{try2_stmt}
- {"try" ":" \token{suite}}
- \productioncont{"finally" ":" \token{suite}}
-\end{productionlist}
-
-\versionchanged[In previous versions of Python,
-\keyword{try}...\keyword{except}...\keyword{finally} did not work.
-\keyword{try}...\keyword{except} had to be nested in
-\keyword{try}...\keyword{finally}]{2.5}
-
-The \keyword{except} clause(s) specify one or more exception handlers.
-When no exception occurs in the
-\keyword{try} clause, no exception handler is executed. When an
-exception occurs in the \keyword{try} suite, a search for an exception
-handler is started. This search inspects the except clauses in turn until
-one is found that matches the exception. An expression-less except
-clause, if present, must be last; it matches any exception. For an
-except clause with an expression, that expression is evaluated, and the
-clause matches the exception if the resulting object is ``compatible''
-with the exception. An object is compatible with an exception if it
-is the class or a base class of the exception object, a tuple
-containing an item compatible with the exception, or, in the
-(deprecated) case of string exceptions, is the raised string itself
-(note that the object identities must match, i.e. it must be the same
-string object, not just a string with the same value).
-\kwindex{except}
-
-If no except clause matches the exception, the search for an exception
-handler continues in the surrounding code and on the invocation stack.
-\footnote{The exception is propogated to the invocation stack only if
-there is no \keyword{finally} clause that negates the exception.}
-
-If the evaluation of an expression in the header of an except clause
-raises an exception, the original search for a handler is canceled
-and a search starts for the new exception in the surrounding code and
-on the call stack (it is treated as if the entire \keyword{try} statement
-raised the exception).
-
-When a matching except clause is found, the exception is assigned to
-the target specified in that except clause, if present, and the except
-clause's suite is executed. All except clauses must have an
-executable block. When the end of this block is reached, execution
-continues normally after the entire try statement. (This means that
-if two nested handlers exist for the same exception, and the exception
-occurs in the try clause of the inner handler, the outer handler will
-not handle the exception.)
-
-Before an except clause's suite is executed, details about the
-exception are stored in the \module{sys}\refbimodindex{sys} module
-and can be access via \function{sys.exc_info()}. \function{sys.exc_info()}
-returns a 3-tuple consisting of: \code{exc_type} receives
-the object identifying the exception; \code{exc_value} receives
-the exception's parameter; \code{exc_traceback} receives a
-traceback object\obindex{traceback} (see section~\ref{traceback})
-identifying the point in the program where the exception occurred.
-\function{sys.exc_info()} values are restored to their previous values
-(before the call) when returning from a function that handled an exception.
-
-The optional \keyword{else} clause is executed if and when control
-flows off the end of the \keyword{try} clause.\footnote{
- Currently, control ``flows off the end'' except in the case of an
- exception or the execution of a \keyword{return},
- \keyword{continue}, or \keyword{break} statement.
-} Exceptions in the \keyword{else} clause are not handled by the
-preceding \keyword{except} clauses.
-\kwindex{else}
-\stindex{return}
-\stindex{break}
-\stindex{continue}
-
-If \keyword{finally} is present, it specifies a `cleanup' handler. The
-\keyword{try} clause is executed, including any \keyword{except} and
-\keyword{else} clauses. If an exception occurs in any of the clauses
-and is not handled, the exception is temporarily saved. The
-\keyword{finally} clause is executed. If there is a saved exception,
-it is re-raised at the end of the \keyword{finally} clause.
-If the \keyword{finally} clause raises another exception or
-executes a \keyword{return} or \keyword{break} statement, the saved
-exception is lost. The exception information is not available to the
-program during execution of the \keyword{finally} clause.
-\kwindex{finally}
-
-When a \keyword{return}, \keyword{break} or \keyword{continue} statement is
-executed in the \keyword{try} suite of a \keyword{try}...\keyword{finally}
-statement, the \keyword{finally} clause is also executed `on the way out.' A
-\keyword{continue} statement is illegal in the \keyword{finally} clause.
-(The reason is a problem with the current implementation --- this
-restriction may be lifted in the future).
-\stindex{return}
-\stindex{break}
-\stindex{continue}
-
-Additional information on exceptions can be found in
-section~\ref{exceptions}, and information on using the \keyword{raise}
-statement to generate exceptions may be found in section~\ref{raise}.
-
-
-\section{The \keyword{with} statement\label{with}}
-\stindex{with}
-
-\versionadded{2.5}
-
-The \keyword{with} statement is used to wrap the execution of a block
-with methods defined by a context manager (see
-section~\ref{context-managers}). This allows common
-\keyword{try}...\keyword{except}...\keyword{finally} usage patterns to
-be encapsulated for convenient reuse.
-
-\begin{productionlist}
- \production{with_stmt}
- {"with" \token{expression} ["as" \token{target}] ":" \token{suite}}
-\end{productionlist}
-
-The execution of the \keyword{with} statement proceeds as follows:
-
-\begin{enumerate}
-
-\item The context expression is evaluated to obtain a context manager.
-
-\item The context manager's \method{__enter__()} method is invoked.
-
-\item If a target was included in the \keyword{with}
-statement, the return value from \method{__enter__()} is assigned to it.
-
-\note{The \keyword{with} statement guarantees that if the
-\method{__enter__()} method returns without an error, then
-\method{__exit__()} will always be called. Thus, if an error occurs
-during the assignment to the target list, it will be treated the same as
-an error occurring within the suite would be. See step 5 below.}
-
-\item The suite is executed.
-
-\item The context manager's \method{__exit__()} method is invoked. If
-an exception caused the suite to be exited, its type, value, and
-traceback are passed as arguments to \method{__exit__()}. Otherwise,
-three \constant{None} arguments are supplied.
-
-If the suite was exited due to an exception, and the return
-value from the \method{__exit__()} method was false, the exception is
-reraised. If the return value was true, the exception is suppressed, and
-execution continues with the statement following the \keyword{with}
-statement.
-
-If the suite was exited for any reason other than an exception, the
-return value from \method{__exit__()} is ignored, and execution proceeds
-at the normal location for the kind of exit that was taken.
-
-\end{enumerate}
-
-\begin{notice}
-In Python 2.5, the \keyword{with} statement is only allowed
-when the \code{with_statement} feature has been enabled. It will always
-be enabled in Python 2.6. This \code{__future__} import statement can
-be used to enable the feature:
-
-\begin{verbatim}
-from __future__ import with_statement
-\end{verbatim}
-\end{notice}
-
-\begin{seealso}
- \seepep{0343}{The "with" statement}
- {The specification, background, and examples for the
- Python \keyword{with} statement.}
-\end{seealso}
-
-\section{Function definitions\label{function}}
-\indexii{function}{definition}
-\stindex{def}
-
-A function definition defines a user-defined function object (see
-section~\ref{types}):
-\obindex{user-defined function}
-\obindex{function}
-
-\begin{productionlist}
- \production{funcdef}
- {[\token{decorators}] "def" \token{funcname} "(" [\token{parameter_list}] ")"
- ["->" \token{expression}]?
- ":" \token{suite}}
- \production{decorators}
- {\token{decorator}+}
- \production{decorator}
- {"@" \token{dotted_name} ["(" [\token{argument_list} [","]] ")"] NEWLINE}
- \production{dotted_name}
- {\token{identifier} ("." \token{identifier})*}
- \production{parameter_list}
- {(\token{defparameter} ",")*}
- \productioncont{(~~"*" [\token{parameter}] ("," \token{defparameter})*}
- \productioncont{ [, "**" \token{parameter}]}
- \productioncont{ | "**" \token{parameter}}
- \productioncont{ | \token{defparameter} [","] )}
- \production{parameter}
- {\token{identifier} [":" \token{expression}]}
- \production{defparameter}
- {\token{parameter} ["=" \token{expression}]}
- \production{funcname}
- {\token{identifier}}
-\end{productionlist}
-
-A function definition is an executable statement. Its execution binds
-the function name in the current local namespace to a function object
-(a wrapper around the executable code for the function). This
-function object contains a reference to the current global namespace
-as the global namespace to be used when the function is called.
-\indexii{function}{name}
-\indexii{name}{binding}
-
-The function definition does not execute the function body; this gets
-executed only when the function is called.
-
-A function definition may be wrapped by one or more decorator expressions.
-Decorator expressions are evaluated when the function is defined, in the scope
-that contains the function definition. The result must be a callable,
-which is invoked with the function object as the only argument.
-The returned value is bound to the function name instead of the function
-object. Multiple decorators are applied in nested fashion.
-For example, the following code:
-
-\begin{verbatim}
-@f1(arg)
-@f2
-def func(): pass
-\end{verbatim}
-
-is equivalent to:
-
-\begin{verbatim}
-def func(): pass
-func = f1(arg)(f2(func))
-\end{verbatim}
-
-When one or more parameters have the form \var{parameter}
-\code{=} \var{expression}, the function is said to have ``default
-parameter values.'' For a parameter with a
-default value, the corresponding argument may be omitted from a call,
-in which case the parameter's default value is substituted. If a
-parameter has a default value, all following parameters up until the
-``\code{*}'' must also have a default value --- this is a syntactic
-restriction that is not expressed by the grammar.
-\indexiii{default}{parameter}{value}
-
-\strong{Default parameter values are evaluated when the function
-definition is executed.} This means that the expression is evaluated
-once, when the function is defined, and that that same
-``pre-computed'' value is used for each call. This is especially
-important to understand when a default parameter is a mutable object,
-such as a list or a dictionary: if the function modifies the object
-(e.g. by appending an item to a list), the default value is in effect
-modified. This is generally not what was intended. A way around this
-is to use \code{None} as the default, and explicitly test for it in
-the body of the function, e.g.:
-
-\begin{verbatim}
-def whats_on_the_telly(penguin=None):
- if penguin is None:
- penguin = []
- penguin.append("property of the zoo")
- return penguin
-\end{verbatim}
-
-Function call semantics are described in more detail in
-section~\ref{calls}.
-A function call always assigns values to all parameters mentioned in
-the parameter list, either from position arguments, from keyword
-arguments, or from default values. If the form ``\code{*identifier}''
-is present, it is initialized to a tuple receiving any excess
-positional parameters, defaulting to the empty tuple. If the form
-``\code{**identifier}'' is present, it is initialized to a new
-dictionary receiving any excess keyword arguments, defaulting to a
-new empty dictionary. Parameters after ``\code{*}'' or ``\code{*identifier}''
-are keyword-only parameters and may only be passed used keyword arguments.
-
-Parameters may have annotations of the form ``\code{: expression}''
-following the parameter name. Any parameter may have an annotation even
-those of the form \code{*identifier} or \code{**identifier}.
-Functions may have ``return'' annotation of the form ``\code{-> expression}''
-after the parameter list. These annotations can be any valid Python
-expression and are evaluated when the function definition is executed.
-Annotations may be evaluated in a different order than they appear in the
-source code. The presence of annotations does not change the semantics of a
-function. The annotation values are available as values of a dictionary
-keyed by the parameters' names in the \member{__annotations__}
-attribute of the function object.
-\indexii{function}{annotations}
-
-It is also possible to create anonymous functions (functions not bound
-to a name), for immediate use in expressions. This uses lambda forms,
-described in section~\ref{lambda}. Note that the lambda form is
-merely a shorthand for a simplified function definition; a function
-defined in a ``\keyword{def}'' statement can be passed around or
-assigned to another name just like a function defined by a lambda
-form. The ``\keyword{def}'' form is actually more powerful since it
-allows the execution of multiple statements and annotations.
-\indexii{lambda}{form}
-
-\strong{Programmer's note:} Functions are first-class objects. A
-``\code{def}'' form executed inside a function definition defines a
-local function that can be returned or passed around. Free variables
-used in the nested function can access the local variables of the
-function containing the def. See section~\ref{naming} for details.
-
-
-\section{Class definitions\label{class}}
-\indexii{class}{definition}
-\stindex{class}
-
-A class definition defines a class object (see section~\ref{types}):
-\obindex{class}
-
-\begin{productionlist}
- \production{classdef}
- {"class" \token{classname} [\token{inheritance}] ":"
- \token{suite}}
- \production{inheritance}
- {"(" [\token{expression_list}] ")"}
- \production{classname}
- {\token{identifier}}
-\end{productionlist}
-
-A class definition is an executable statement. It first evaluates the
-inheritance list, if present. Each item in the inheritance list
-should evaluate to a class object or class type which allows
-subclassing. The class's suite is then executed
-in a new execution frame (see section~\ref{naming}), using a newly
-created local namespace and the original global namespace.
-(Usually, the suite contains only function definitions.) When the
-class's suite finishes execution, its execution frame is discarded but
-its local namespace is saved. A class object is then created using
-the inheritance list for the base classes and the saved local
-namespace for the attribute dictionary. The class name is bound to this
-class object in the original local namespace.
-\index{inheritance}
-\indexii{class}{name}
-\indexii{name}{binding}
-\indexii{execution}{frame}
-
-\strong{Programmer's note:} Variables defined in the class definition
-are class variables; they are shared by all instances. To define
-instance variables, they must be given a value in the
-\method{__init__()} method or in another method. Both class and
-instance variables are accessible through the notation
-``\code{self.name}'', and an instance variable hides a class variable
-with the same name when accessed in this way. Class variables with
-immutable values can be used as defaults for instance variables.
-For new-style classes, descriptors can be used to create instance
-variables with different implementation details.
diff --git a/Doc/ref/ref8.tex b/Doc/ref/ref8.tex
deleted file mode 100644
index 3fe4cc5..0000000
--- a/Doc/ref/ref8.tex
+++ /dev/null
@@ -1,109 +0,0 @@
-\chapter{Top-level components\label{top-level}}
-
-The Python interpreter can get its input from a number of sources:
-from a script passed to it as standard input or as program argument,
-typed in interactively, from a module source file, etc. This chapter
-gives the syntax used in these cases.
-\index{interpreter}
-
-
-\section{Complete Python programs\label{programs}}
-\index{program}
-
-While a language specification need not prescribe how the language
-interpreter is invoked, it is useful to have a notion of a complete
-Python program. A complete Python program is executed in a minimally
-initialized environment: all built-in and standard modules are
-available, but none have been initialized, except for \module{sys}
-(various system services), \module{__builtin__} (built-in functions,
-exceptions and \code{None}) and \module{__main__}. The latter is used
-to provide the local and global namespace for execution of the
-complete program.
-\refbimodindex{sys}
-\refbimodindex{__main__}
-\refbimodindex{__builtin__}
-
-The syntax for a complete Python program is that for file input,
-described in the next section.
-
-The interpreter may also be invoked in interactive mode; in this case,
-it does not read and execute a complete program but reads and executes
-one statement (possibly compound) at a time. The initial environment
-is identical to that of a complete program; each statement is executed
-in the namespace of \module{__main__}.
-\index{interactive mode}
-\refbimodindex{__main__}
-
-Under \UNIX, a complete program can be passed to the interpreter in
-three forms: with the \programopt{-c} \var{string} command line option, as a
-file passed as the first command line argument, or as standard input.
-If the file or standard input is a tty device, the interpreter enters
-interactive mode; otherwise, it executes the file as a complete
-program.
-\index{UNIX}
-\index{command line}
-\index{standard input}
-
-
-\section{File input\label{file-input}}
-
-All input read from non-interactive files has the same form:
-
-\begin{productionlist}
- \production{file_input}
- {(NEWLINE | \token{statement})*}
-\end{productionlist}
-
-This syntax is used in the following situations:
-
-\begin{itemize}
-
-\item when parsing a complete Python program (from a file or from a string);
-
-\item when parsing a module;
-
-\item when parsing a string passed to the \function{exec()} function;
-
-\end{itemize}
-
-
-\section{Interactive input\label{interactive}}
-
-Input in interactive mode is parsed using the following grammar:
-
-\begin{productionlist}
- \production{interactive_input}
- {[\token{stmt_list}] NEWLINE | \token{compound_stmt} NEWLINE}
-\end{productionlist}
-
-Note that a (top-level) compound statement must be followed by a blank
-line in interactive mode; this is needed to help the parser detect the
-end of the input.
-
-
-\section{Expression input\label{expression-input}}
-\index{input}
-
-There are two forms of expression input. Both ignore leading
-whitespace.
-The string argument to \function{eval()} must have the following form:
-\bifuncindex{eval}
-
-\begin{productionlist}
- \production{eval_input}
- {\token{expression_list} NEWLINE*}
-\end{productionlist}
-
-The input line read by \function{input()} must have the following form:
-\bifuncindex{input}
-
-\begin{productionlist}
- \production{input_input}
- {\token{expression_list} NEWLINE}
-\end{productionlist}
-
-Note: to read `raw' input line without interpretation, you can use the
-the \method{readline()} method of file objects, including \code{sys.stdin}.
-\obindex{file}
-\index{input!raw}
-\withsubitem{(file method)}{\ttindex{readline()}}
diff --git a/Doc/ref/reswords.py b/Doc/ref/reswords.py
deleted file mode 100644
index 53b8dc8..0000000
--- a/Doc/ref/reswords.py
+++ /dev/null
@@ -1,23 +0,0 @@
-"""Spit out the Python reserved words table."""
-
-import keyword
-
-ncols = 5
-
-def main():
- words = keyword.kwlist[:]
- words.sort()
- colwidth = 1 + max(map(len, words))
- nwords = len(words)
- nrows = (nwords + ncols - 1) // ncols
- for irow in range(nrows):
- for icol in range(ncols):
- i = irow + icol * nrows
- if 0 <= i < nwords:
- word = words[i]
- else:
- word = ""
- print "%-*s" % (colwidth, word),
- print
-
-main()
diff --git a/Doc/templates/howto.tex b/Doc/templates/howto.tex
deleted file mode 100644
index fdbb065..0000000
--- a/Doc/templates/howto.tex
+++ /dev/null
@@ -1,112 +0,0 @@
-% Complete documentation on the extended LaTeX markup used for Python
-% documentation is available in ``Documenting Python'', which is part
-% of the standard documentation for Python. It may be found online
-% at:
-%
-% http://www.python.org/doc/current/doc/doc.html
-
-\documentclass{howto}
-
-% This is a template for short or medium-size Python-related documents,
-% mostly notably the series of HOWTOs, but it can be used for any
-% document you like.
-
-% The title should be descriptive enough for people to be able to find
-% the relevant document.
-\title{Spammifying Sprockets in Python}
-
-% Increment the release number whenever significant changes are made.
-% The author and/or editor can define 'significant' however they like.
-\release{0.00}
-
-% At minimum, give your name and an email address. You can include a
-% snail-mail address if you like.
-\author{Me, 'cause I wrote it}
-\authoraddress{Me, 'cause I'm self-employed.}
-
-\begin{document}
-\maketitle
-
-% This makes the Abstract go on a separate page in the HTML version;
-% if a copyright notice is used, it should go immediately after this.
-%
-\ifhtml
-\chapter*{Front Matter\label{front}}
-\fi
-
-% Copyright statement should go here, if needed.
-% ...
-
-% The abstract should be a paragraph or two long, and describe the
-% scope of the document.
-\begin{abstract}
-\noindent
-This document describes how to spammify sprockets. It is a useful
-example of a Python HOWTO document. It is not dependent on any
-particular sprocket implementation, and includes a Python-based
-implementation in the \module{sprunkit} module.
-\end{abstract}
-
-\tableofcontents
-
-Spammifying sprockets from Python is both fun and entertaining.
-Applying the techniques described here, you can also fill your hard
-disk quite effectively.
-
-\section{What is Sprocket Spammification?}
-
-You have to ask? It's the only thing to do to your sprockets!
-
-
-\section{Why Use Python?}
-
-Python is an excellent language from which to spammify your sprockets
-since you can do it on any platform.
-
-
-\section{Software Requirements}
-
-You need to have the following software installed:
-
-% The {itemize} environment uses a bullet for each \item. If you want the
-% \item's numbered, use the {enumerate} environment instead.
-\begin{itemize}
- \item Python 1.9.
- \item Some sprocket definition files.
- \item At least one sprocket system implementation.
-\end{itemize}
-
-Note that the \module{sprunkit} is provided with this package and
-implements ActiveSprockets in Python.
-
-
-% The preceding sections will have been written in a gentler,
-% introductory style. You may also wish to include a reference
-% section, documenting all the functions/exceptions/constants.
-% Often, these will be placed in separate files and input like this:
-
-\input{module}
-
-
-\appendix
-
-\section{This is an Appendix}
-
-To create an appendix in a Python HOWTO document, use markup like
-this:
-
-\begin{verbatim}
-\appendix
-
-\section{This is an Appendix}
-
-To create an appendix in a Python HOWTO document, ....
-
-
-\section{This is another}
-
-Just add another \section{}, but don't say \appendix again.
-\end{verbatim}
-
-
-\end{document}
diff --git a/Doc/templates/manual.tex b/Doc/templates/manual.tex
deleted file mode 100644
index 19dec8b..0000000
--- a/Doc/templates/manual.tex
+++ /dev/null
@@ -1,89 +0,0 @@
-% Complete documentation on the extended LaTeX markup used for Python
-% documentation is available in ``Documenting Python'', which is part
-% of the standard documentation for Python. It may be found online
-% at:
-%
-% http://www.python.org/doc/current/doc/doc.html
-
-\documentclass{manual}
-
-\title{Big Python Manual}
-
-\author{Your Name Here}
-
-% Please at least include a long-lived email address;
-% the rest is at your discretion.
-\authoraddress{
- Organization name, if applicable \\
- Street address, if you want to use it \\
- Email: \email{your-email@your.domain}
-}
-
-\date{April 30, 1999} % update before release!
- % Use an explicit date so that reformatting
- % doesn't cause a new date to be used. Setting
- % the date to \today can be used during draft
- % stages to make it easier to handle versions.
-
-\release{x.y} % release version; this is used to define the
- % \version macro
-
-\makeindex % tell \index to actually write the .idx file
-\makemodindex % If this contains a lot of module sections.
-
-
-\begin{document}
-
-\maketitle
-
-% This makes the contents more accessible from the front page of the HTML.
-\ifhtml
-\chapter*{Front Matter\label{front}}
-\fi
-
-%\input{copyright}
-
-\begin{abstract}
-
-\noindent
-Big Python is a special version of Python for users who require larger
-keys on their keyboards. It accommodates their special needs by ...
-
-\end{abstract}
-
-\tableofcontents
-
-
-\chapter{...}
-
-My chapter.
-
-
-\appendix
-\chapter{...}
-
-My appendix.
-
-The \code{\e appendix} markup need not be repeated for additional
-appendices.
-
-
-%
-% The ugly "%begin{latexonly}" pseudo-environments are really just to
-% keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
-% not really valuable.
-%
-% If you don't want the Module Index, you can remove all of this up
-% until the second \input line.
-%
-%begin{latexonly}
-\renewcommand{\indexname}{Module Index}
-%end{latexonly}
-\input{mod\jobname.ind} % Module Index
-
-%begin{latexonly}
-\renewcommand{\indexname}{Index}
-%end{latexonly}
-\input{\jobname.ind} % Index
-
-\end{document}
diff --git a/Doc/templates/module.tex b/Doc/templates/module.tex
deleted file mode 100644
index 69e1b12..0000000
--- a/Doc/templates/module.tex
+++ /dev/null
@@ -1,170 +0,0 @@
-% Template for a library manual section.
-% PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE
-%
-% Complete documentation on the extended LaTeX markup used for Python
-% documentation is available in ``Documenting Python'', which is part
-% of the standard documentation for Python. It may be found online
-% at:
-%
-% http://www.python.org/doc/current/doc/doc.html
-
-% ==== 0. ====
-% Copy this file to <mydir>/lib<mymodule>.tex, and edit that file
-% according to the instructions below.
-
-
-% ==== 1. ====
-% The section prologue. Give the section a title and provide some
-% meta-information. References to the module should use
-% \refbimodindex, \refstmodindex, \refexmodindex or \refmodindex, as
-% appropriate.
-
-\section{\module{spam} ---
- Short description, for section title and table of contents}
-
-% Choose one of these to specify the module module name. If there's
-% an underscore in the name, use
-% \declaremodule[modname]{...}{mod_name} instead.
-%
-\declaremodule{builtin}{spam} % standard library, in C
-\declaremodule{standard}{spam} % standard library, in Python
-\declaremodule{extension}{spam} % not standard, in C
-\declaremodule{}{spam} % not standard, in Python
-
-% Portability statement: Uncomment and fill in the parameter to specify the
-% availability of the module. The parameter can be Unix, IRIX, SunOS, Mac,
-% Windows, or lots of other stuff. When ``Mac'' is specified, the availability
-% statement will say ``Macintosh'' and the Module Index may say ``Mac''.
-% Please use a name that has already been used whenever applicable. If this
-% is omitted, no availability statement is produced or implied.
-%
-% \platform{Unix}
-
-% These apply to all modules, and may be given more than once:
-
-\moduleauthor{name}{email} % Author of the module code;
- % omit if not known.
-\sectionauthor{name}{email} % Author of the documentation,
- % even if not a module section.
-
-
-% Leave at least one blank line after this, to simplify ad-hoc tools
-% that are sometimes used to massage these files.
-\modulesynopsis{This is a one-line description, for the chapter header.}
-
-
-% ==== 2. ====
-% Give a short overview of what the module does.
-% If it is platform specific, mention this.
-% Mention other important restrictions or general operating principles.
-% For example:
-
-The \module{spam} module defines operations for handling cans of Spam.
-It knows the four generally available Spam varieties and understands
-both can sizes.
-
-Because spamification requires \UNIX{} process management, the module
-is only available on genuine \UNIX{} systems.
-
-
-% ==== 3. ====
-% List the public functions defined by the module. Begin with a
-% standard phrase. You may also list the exceptions and other data
-% items defined in the module, insofar as they are important for the
-% user.
-
-The \module{spam} module defines the following functions:
-
-% ---- 3.1. ----
-% For each function, use a ``funcdesc'' block. This has exactly two
-% parameters (each parameters is contained in a set of curly braces):
-% the first parameter is the function name (this automatically
-% generates an index entry); the second parameter is the function's
-% argument list. If there are no arguments, use an empty pair of
-% curly braces. If there is more than one argument, separate the
-% arguments with backslash-comma. Optional parts of the parameter
-% list are contained in \optional{...} (this generates a set of square
-% brackets around its parameter). Arguments are automatically set in
-% italics in the parameter list. Each argument should be mentioned at
-% least once in the description; each usage (even inside \code{...})
-% should be enclosed in \var{...}.
-
-\begin{funcdesc}{open}{filename\optional{, mode\optional{, buffersize}}}
-Open the file \var{filename} as a can of Spam. The optional
-\var{mode} and \var{buffersize} arguments specify the read/write mode
-(\code{'r'} (default) or \code{'w'}) and the buffer size (default:
-system dependent).
-\end{funcdesc}
-
-% ---- 3.2. ----
-% Data items are described using a ``datadesc'' block. This has only
-% one parameter: the item's name.
-
-\begin{datadesc}{cansize}
-The default can size, in ounces. Legal values are 7 and 12. The
-default varies per supermarket. This variable should not be changed
-once the \function{open()} function has been called.
-\end{datadesc}
-
-% --- 3.3. ---
-% Exceptions are described using a ``excdesc'' block. This has only
-% one parameter: the exception name. Exceptions defined as classes in
-% the source code should be documented using this environment, but
-% constructor parameters must be omitted.
-
-\begin{excdesc}{error}
-Exception raised when an operation fails for a Spam specific reason.
-The exception argument is a string describing the reason of the
-failure.
-\end{excdesc}
-
-% ---- 3.4. ----
-% Other standard environments:
-%
-% classdesc - Python classes; same arguments are funcdesc
-% methoddesc - methods, like funcdesc but has an optional parameter
-% to give the type name: \begin{methoddesc}[mytype]{name}{args}
-% By default, the type name will be the name of the
-% last class defined using classdesc. The type name
-% is required if the type is implemented in C (because
-% there's no classdesc) or if the class isn't directly
-% documented (if it's private).
-% memberdesc - data members, like datadesc, but with an optional
-% type name like methoddesc.
-
-
-% ==== 4. ====
-% Now is probably a good time for a complete example. (Alternatively,
-% an example giving the flavor of the module may be given before the
-% detailed list of functions.)
-
-\subsection{Example \label{spam-example}}
-
-The following example demonstrates how to open a can of spam using the
-\module{spam} module.
-
-\begin{verbatim}
->>> import spam
->>> can = spam.open('/etc/passwd')
->>> can.empty()
->>> can.close()
-\end{verbatim}
-% Note that there is no trailing ">>> " prompt shown.
-
-% ==== 5. ====
-% If your module defines new object types (for a built-in module) or
-% classes (for a module written in Python), you should list the
-% methods and instance variables (if any) of each type or class in a
-% separate subsection.
-
-\subsection{Spam Objects}
-\label{spam-objects}
-% This label is generally useful for referencing this section, but is
-% also used to give a filename when generating HTML.
-
-Spam objects, as returned by \function{open()} above, have the
-following methods:
-
-\begin{methoddesc}[spam]{empty}{}
-Empty the can into the trash.
-\end{methoddesc}
diff --git a/Doc/templates/whatsnewXY.tex b/Doc/templates/whatsnewXY.tex
deleted file mode 100644
index 6f62b9c..0000000
--- a/Doc/templates/whatsnewXY.tex
+++ /dev/null
@@ -1,149 +0,0 @@
-\documentclass{howto}
-\usepackage{distutils}
-% $Id$
-
-% When creating a new ``What's New'' document, copy this to
-% ../whatsnew/whatsnewXY.tex, where X is replaced by the major version
-% number and Y, by the minor version number for the release of Python
-% being described.
-%
-% The following replacements need to be made in the text:
-%
-% X.Y -- the version of Python this document describes
-% X.Y-1 -- previous minor release (not a maintenance release)
-% X.Y-2 -- minor release before that one (optional; search the
-% template to see the usage
-%
-% Once done, write and edit to your heart's content!
-
-\title{What's New in Python X.Y}
-\release{0.0}
-\author{Young Author}
-\authoraddress{\email{ya@example.com}}
-
-\begin{document}
-\maketitle
-\tableofcontents
-
-This article explains the new features in Python X.Y. No release date
-for Python X.Y has been set; expect that this will happen next year.
-
-% Compare with previous release in 2 - 3 sentences here.
-
-This article doesn't attempt to provide a complete specification of
-the new features, but instead provides a convenient overview. For
-full details, you should refer to the documentation for Python X.Y.
-% add hyperlink when the documentation becomes available online.
-If you want to understand the complete implementation and design
-rationale, refer to the PEP for a particular new feature.
-
-
-%======================================================================
-
-% Large, PEP-level features and changes should be described here.
-
-
-%======================================================================
-\section{Other Language Changes}
-
-Here are all of the changes that Python X.Y makes to the core Python
-language.
-
-\begin{itemize}
-\item TBD
-
-\end{itemize}
-
-
-%======================================================================
-\subsection{Optimizations}
-
-\begin{itemize}
-
-\item Optimizations should be described here.
-
-\end{itemize}
-
-The net result of the X.Y optimizations is that Python X.Y runs the
-pystone benchmark around XX\% faster than Python X.Y-1.%
-% only use the next line if you want to do the extra work ;) :
-% and YY\% faster than Python X.Y-2.
-
-
-%======================================================================
-\section{New, Improved, and Deprecated Modules}
-
-As usual, Python's standard library received a number of enhancements and
-bug fixes. Here's a partial list of the most notable changes, sorted
-alphabetically by module name. Consult the
-\file{Misc/NEWS} file in the source tree for a more
-complete list of changes, or look through the CVS logs for all the
-details.
-
-\begin{itemize}
-
-\item Descriptions go here.
-
-\end{itemize}
-
-
-%======================================================================
-% whole new modules get described in \subsections here
-
-
-% ======================================================================
-\section{Build and C API Changes}
-
-Changes to Python's build process and to the C API include:
-
-\begin{itemize}
-
-\item Detailed changes are listed here.
-
-\end{itemize}
-
-
-%======================================================================
-\subsection{Port-Specific Changes}
-
-Platform-specific changes go here.
-
-
-%======================================================================
-\section{Other Changes and Fixes \label{section-other}}
-
-As usual, there were a bunch of other improvements and bugfixes
-scattered throughout the source tree. A search through the CVS change
-logs finds there were XXX patches applied and YYY bugs fixed between
-Python X.Y-1 and X.Y. Both figures are likely to be underestimates.
-
-Some of the more notable changes are:
-
-\begin{itemize}
-
-\item Details go here.
-
-\end{itemize}
-
-
-%======================================================================
-\section{Porting to Python X.Y}
-
-This section lists previously described changes that may require
-changes to your code:
-
-\begin{itemize}
-
-\item Everything is all in the details!
-
-\end{itemize}
-
-
-%======================================================================
-\section{Acknowledgements \label{acks}}
-
-The author would like to thank the following people for offering
-suggestions, corrections and assistance with various drafts of this
-article: .
-
-\end{document}
diff --git a/Doc/tests/math.tex b/Doc/tests/math.tex
deleted file mode 100644
index 11880e5..0000000
--- a/Doc/tests/math.tex
+++ /dev/null
@@ -1,16 +0,0 @@
-\documentclass{howto}
-
-\title{Test of python.sty with math}
-
-\begin{document}
-
-\maketitle
-
-\section{Subscripts in Math Mode}
-
-This contains an inline formula containing a subscript: $H_20$.
-This display doesn't make sense, but contains a subscript as well:
-
-$$\sum_1^2 = a_x$$
-
-\end{document}
diff --git a/Doc/texinputs/distutils.sty b/Doc/texinputs/distutils.sty
deleted file mode 100644
index 45e2ed1..0000000
--- a/Doc/texinputs/distutils.sty
+++ /dev/null
@@ -1,33 +0,0 @@
-%
-% LaTeX commands and macros needed for the two Distutils manuals,
-% inst.tex and dist.tex.
-%
-% $Id$
-%
-
-% My gripe list about the Python style files:
-% * I want italics in verbatim environments for variable
-% text (verbatim.sty?)
-% * I hate escaping underscores (url.sty fixes this)
-
-% '\command' is for Distutils commands which, depending on your
-% perspective, are just arguments to the setup script, or sub-
-% commands of the setup script, or the classes that implement
-% each "command".
-\newcommand{\command}[1]{\code{#1}}
-
-% '\option' is for Distutils options *in* the setup script. Command-
-% line options *to* the setup script are marked up in the usual
-% way, ie. with '\programopt' or '\longprogramopt'
-\newcommand{\option}[1]{\textsf{\small{#1}}}
-
-% '\filevar' is for variable components of file/path names -- eg.
-% when you put 'prefix' in a pathname, you mark it up with
-% '\filevar' so that it still looks pathname-ish, but is
-% distinguished from the literal part of the path. Fred says
-% this can be accomplished just fine with '\var', but I violently
-% disagree. Pistols at dawn will sort this one out.
-\newcommand{\filevar}[1]{{\textsl{\filenq{#1}}}}
-
-% Just while the code and docs are still under development.
-\newcommand{\XXX}[1]{\textbf{**#1**}}
diff --git a/Doc/texinputs/fancyhdr.sty b/Doc/texinputs/fancyhdr.sty
deleted file mode 100644
index c1026e9..0000000
--- a/Doc/texinputs/fancyhdr.sty
+++ /dev/null
@@ -1,329 +0,0 @@
-% fancyhdr.sty version 1.99d
-% Fancy headers and footers for LaTeX.
-% Piet van Oostrum, Dept of Computer Science, University of Utrecht
-% Padualaan 14, P.O. Box 80.089, 3508 TB Utrecht, The Netherlands
-% Telephone: +31 30 2532180. Email: piet@cs.ruu.nl
-% ========================================================================
-% LICENCE: This is free software. You are allowed to use and distribute
-% this software in any way you like. You are also allowed to make modified
-% versions of it, but you can distribute a modified version only if you
-% clearly indicate that it is a modified version and the person(s) who
-% modified it. This indication should be in a prominent place, e.g. in the
-% top of the file. If possible a contact address, preferably by email,
-% should be given for these persons. If that is feasible the modifications
-% should be indicated in the source code.
-% ========================================================================
-% MODIFICATION HISTORY:
-% Sep 16, 1994
-% version 1.4: Correction for use with \reversemargin
-% Sep 29, 1994:
-% version 1.5: Added the \iftopfloat, \ifbotfloat and \iffloatpage commands
-% Oct 4, 1994:
-% version 1.6: Reset single spacing in headers/footers for use with
-% setspace.sty or doublespace.sty
-% Oct 4, 1994:
-% version 1.7: changed \let\@mkboth\markboth to
-% \def\@mkboth{\protect\markboth} to make it more robust
-% Dec 5, 1994:
-% version 1.8: corrections for amsbook/amsart: define \@chapapp and (more
-% importantly) use the \chapter/sectionmark definitions from ps@headings if
-% they exist (which should be true for all standard classes).
-% May 31, 1995:
-% version 1.9: The proposed \renewcommand{\headrulewidth}{\iffloatpage...
-% construction in the doc did not work properly with the fancyplain style.
-% June 1, 1995:
-% version 1.91: The definition of \@mkboth wasn't restored on subsequent
-% \pagestyle{fancy}'s.
-% June 1, 1995:
-% version 1.92: The sequence \pagestyle{fancyplain} \pagestyle{plain}
-% \pagestyle{fancy} would erroneously select the plain version.
-% June 1, 1995:
-% version 1.93: \fancypagestyle command added.
-% Dec 11, 1995:
-% version 1.94: suggested by Conrad Hughes <chughes@maths.tcd.ie>
-% CJCH, Dec 11, 1995: added \footruleskip to allow control over footrule
-% position (old hardcoded value of .3\normalbaselineskip is far too high
-% when used with very small footer fonts).
-% Jan 31, 1996:
-% version 1.95: call \@normalsize in the reset code if that is defined,
-% otherwise \normalsize.
-% this is to solve a problem with ucthesis.cls, as this doesn't
-% define \@currsize. Unfortunately for latex209 calling \normalsize doesn't
-% work as this is optimized to do very little, so there \@normalsize should
-% be called. Hopefully this code works for all versions of LaTeX known to
-% mankind.
-% April 25, 1996:
-% version 1.96: initialize \headwidth to a magic (negative) value to catch
-% most common cases that people change it before calling \pagestyle{fancy}.
-% Note it can't be initialized when reading in this file, because
-% \textwidth could be changed afterwards. This is quite probable.
-% We also switch to \MakeUppercase rather than \uppercase and introduce a
-% \nouppercase command for use in headers. and footers.
-% May 3, 1996:
-% version 1.97: Two changes:
-% 1. Undo the change in version 1.8 (using the pagestyle{headings} defaults
-% for the chapter and section marks. The current version of amsbook and
-% amsart classes don't seem to need them anymore. Moreover the standard
-% latex classes don't use \markboth if twoside isn't selected, and this is
-% confusing as \leftmark doesn't work as expected.
-% 2. include a call to \ps@empty in ps@@fancy. This is to solve a problem
-% in the amsbook and amsart classes, that make global changes to \topskip,
-% which are reset in \ps@empty. Hopefully this doesn't break other things.
-% May 7, 1996:
-% version 1.98:
-% Added % after the line \def\nouppercase
-% May 7, 1996:
-% version 1.99: This is the alpha version of fancyhdr 2.0
-% Introduced the new commands \fancyhead, \fancyfoot, and \fancyhf.
-% Changed \headrulewidth, \footrulewidth, \footruleskip to
-% macros rather than length parameters, In this way they can be
-% conditionalized and they don't consume length registers. There is no need
-% to have them as length registers unless you want to do calculations with
-% them, which is unlikely. Note that this may make some uses of them
-% incompatible (i.e. if you have a file that uses \setlength or \xxxx=)
-% May 10, 1996:
-% version 1.99a:
-% Added a few more % signs
-% May 10, 1996:
-% version 1.99b:
-% Changed the syntax of \f@nfor to be resistent to catcode changes of :=
-% Removed the [1] from the defs of \lhead etc. because the parameter is
-% consumed by the \@[xy]lhead etc. macros.
-% June 24, 1997:
-% version 1.99c:
-% corrected \nouppercase to also include the protected form of \MakeUppercase
-% \global added to manipulation of \headwidth.
-% \iffootnote command added.
-% Some comments added about \@fancyhead and \@fancyfoot.
-% Aug 24, 1998
-% version 1.99d
-% Changed the default \ps@empty to \ps@@empty in order to allow
-% \fancypagestyle{empty} redefinition.
-
-\let\fancy@def\gdef
-
-\def\if@mpty#1#2#3{\def\temp@ty{#1}\ifx\@empty\temp@ty #2\else#3\fi}
-
-% Usage: \@forc \var{charstring}{command to be executed for each char}
-% This is similar to LaTeX's \@tfor, but expands the charstring.
-
-\def\@forc#1#2#3{\expandafter\f@rc\expandafter#1\expandafter{#2}{#3}}
-\def\f@rc#1#2#3{\def\temp@ty{#2}\ifx\@empty\temp@ty\else
- \f@@rc#1#2\f@@rc{#3}\fi}
-\def\f@@rc#1#2#3\f@@rc#4{\def#1{#2}#4\f@rc#1{#3}{#4}}
-
-% Usage: \f@nfor\name:=list\do{body}
-% Like LaTeX's \@for but an empty list is treated as a list with an empty
-% element
-
-\newcommand{\f@nfor}[3]{\edef\@fortmp{#2}%
- \expandafter\@forloop#2,\@nil,\@nil\@@#1{#3}}
-
-% Usage: \def@ult \cs{defaults}{argument}
-% sets \cs to the characters from defaults appearing in argument
-% or defaults if it would be empty. All characters are lowercased.
-
-\newcommand\def@ult[3]{%
- \edef\temp@a{\lowercase{\edef\noexpand\temp@a{#3}}}\temp@a
- \def#1{}%
- \@forc\tmpf@ra{#2}%
- {\expandafter\if@in\tmpf@ra\temp@a{\edef#1{#1\tmpf@ra}}{}}%
- \ifx\@empty#1\def#1{#2}\fi}
-%
-% \if@in <char><set><truecase><falsecase>
-%
-\newcommand{\if@in}[4]{%
- \edef\temp@a{#2}\def\temp@b##1#1##2\temp@b{\def\temp@b{##1}}%
- \expandafter\temp@b#2#1\temp@b\ifx\temp@a\temp@b #4\else #3\fi}
-
-\newcommand{\fancyhead}{\@ifnextchar[{\f@ncyhf h}{\f@ncyhf h[]}}
-\newcommand{\fancyfoot}{\@ifnextchar[{\f@ncyhf f}{\f@ncyhf f[]}}
-\newcommand{\fancyhf}{\@ifnextchar[{\f@ncyhf {}}{\f@ncyhf {}[]}}
-
-% The header and footer fields are stored in command sequences with
-% names of the form: \f@ncy<x><y><z> with <x> for [eo], <y> form [lcr]
-% and <z> from [hf].
-
-\def\f@ncyhf#1[#2]#3{%
- \def\temp@c{}%
- \@forc\tmpf@ra{#2}%
- {\expandafter\if@in\tmpf@ra{eolcrhf,EOLCRHF}%
- {}{\edef\temp@c{\temp@c\tmpf@ra}}}%
- \ifx\@empty\temp@c\else
- \ifx\PackageError\undefined
- \errmessage{Illegal char `\temp@c' in fancyhdr argument:
- [#2]}\else
- \PackageError{Fancyhdr}{Illegal char `\temp@c' in fancyhdr argument:
- [#2]}{}\fi
- \fi
- \f@nfor\temp@c{#2}%
- {\def@ult\f@@@eo{eo}\temp@c
- \def@ult\f@@@lcr{lcr}\temp@c
- \def@ult\f@@@hf{hf}{#1\temp@c}%
- \@forc\f@@eo\f@@@eo
- {\@forc\f@@lcr\f@@@lcr
- {\@forc\f@@hf\f@@@hf
- {\expandafter\fancy@def\csname
- f@ncy\f@@eo\f@@lcr\f@@hf\endcsname
- {#3}}}}}}
-
-% Fancyheadings version 1 commands. These are more or less deprecated,
-% but they continue to work.
-
-\newcommand{\lhead}{\@ifnextchar[{\@xlhead}{\@ylhead}}
-\def\@xlhead[#1]#2{\fancy@def\f@ncyelh{#1}\fancy@def\f@ncyolh{#2}}
-\def\@ylhead#1{\fancy@def\f@ncyelh{#1}\fancy@def\f@ncyolh{#1}}
-
-\newcommand{\chead}{\@ifnextchar[{\@xchead}{\@ychead}}
-\def\@xchead[#1]#2{\fancy@def\f@ncyech{#1}\fancy@def\f@ncyoch{#2}}
-\def\@ychead#1{\fancy@def\f@ncyech{#1}\fancy@def\f@ncyoch{#1}}
-
-\newcommand{\rhead}{\@ifnextchar[{\@xrhead}{\@yrhead}}
-\def\@xrhead[#1]#2{\fancy@def\f@ncyerh{#1}\fancy@def\f@ncyorh{#2}}
-\def\@yrhead#1{\fancy@def\f@ncyerh{#1}\fancy@def\f@ncyorh{#1}}
-
-\newcommand{\lfoot}{\@ifnextchar[{\@xlfoot}{\@ylfoot}}
-\def\@xlfoot[#1]#2{\fancy@def\f@ncyelf{#1}\fancy@def\f@ncyolf{#2}}
-\def\@ylfoot#1{\fancy@def\f@ncyelf{#1}\fancy@def\f@ncyolf{#1}}
-
-\newcommand{\cfoot}{\@ifnextchar[{\@xcfoot}{\@ycfoot}}
-\def\@xcfoot[#1]#2{\fancy@def\f@ncyecf{#1}\fancy@def\f@ncyocf{#2}}
-\def\@ycfoot#1{\fancy@def\f@ncyecf{#1}\fancy@def\f@ncyocf{#1}}
-
-\newcommand{\rfoot}{\@ifnextchar[{\@xrfoot}{\@yrfoot}}
-\def\@xrfoot[#1]#2{\fancy@def\f@ncyerf{#1}\fancy@def\f@ncyorf{#2}}
-\def\@yrfoot#1{\fancy@def\f@ncyerf{#1}\fancy@def\f@ncyorf{#1}}
-
-\newdimen\headwidth
-\newcommand{\headrulewidth}{0.4pt}
-\newcommand{\footrulewidth}{\z@skip}
-\newcommand{\footruleskip}{.3\normalbaselineskip}
-
-% Fancyplain stuff shouldn't be used anymore (rather
-% \fancypagestyle{plain} should be used), but it must be present for
-% compatibility reasons.
-
-\newcommand{\plainheadrulewidth}{\z@skip}
-\newcommand{\plainfootrulewidth}{\z@skip}
-\newif\if@fancyplain \@fancyplainfalse
-\def\fancyplain#1#2{\if@fancyplain#1\else#2\fi}
-
-\headwidth=-123456789sp %magic constant
-
-% Command to reset various things in the headers:
-% a.o. single spacing (taken from setspace.sty)
-% and the catcode of ^^M (so that epsf files in the header work if a
-% verbatim crosses a page boundary)
-% It also defines a \nouppercase command that disables \uppercase and
-% \Makeuppercase. It can only be used in the headers and footers.
-\def\fancy@reset{\restorecr
- \def\baselinestretch{1}%
- \def\nouppercase##1{{\let\uppercase\relax\let\MakeUppercase\relax
- \expandafter\let\csname MakeUppercase \endcsname\relax##1}}%
- \ifx\undefined\@newbaseline% NFSS not present; 2.09 or 2e
- \ifx\@normalsize\undefined \normalsize % for ucthesis.cls
- \else \@normalsize \fi
- \else% NFSS (2.09) present
- \@newbaseline%
- \fi}
-
-% Initialization of the head and foot text.
-
-% The default values still contain \fancyplain for compatibility.
-\fancyhf{} % clear all
-% lefthead empty on ``plain'' pages, \rightmark on even, \leftmark on odd pages
-% evenhead empty on ``plain'' pages, \leftmark on even, \rightmark on odd pages
-\fancyhead[el,or]{\fancyplain{}{\sl\rightmark}}
-\fancyhead[er,ol]{\fancyplain{}{\sl\leftmark}}
-\fancyfoot[c]{\rm\thepage} % page number
-
-% Put together a header or footer given the left, center and
-% right text, fillers at left and right and a rule.
-% The \lap commands put the text into an hbox of zero size,
-% so overlapping text does not generate an errormessage.
-% These macros have 5 parameters:
-% 1. \@lodd or \@rodd % This determines at which side the header will stick
-% out.
-% 2. \f@ncyolh, \f@ncyelh, \f@ncyolf or \f@ncyelf. This is the left component.
-% 3. \f@ncyoch, \f@ncyech, \f@ncyocf or \f@ncyecf. This is the middle comp.
-% 4. \f@ncyorh, \f@ncyerh, \f@ncyorf or \f@ncyerf. This is the right component.
-% 5. \@lodd or \@rodd % This determines at which side the header will stick
-% out. This is the reverse of parameter nr. 1. One of them is always
-% \relax and the other one is \hss (after expansion).
-
-\def\@fancyhead#1#2#3#4#5{#1\hbox to\headwidth{\fancy@reset\vbox{\hbox
-{\rlap{\parbox[b]{\headwidth}{\raggedright#2\strut}}\hfill
-\parbox[b]{\headwidth}{\centering#3\strut}\hfill
-\llap{\parbox[b]{\headwidth}{\raggedleft#4\strut}}}\headrule}}#5}
-
-\def\@fancyfoot#1#2#3#4#5{#1\hbox to\headwidth{\fancy@reset\vbox{\footrule
-\hbox{\rlap{\parbox[t]{\headwidth}{\raggedright#2\strut}}\hfill
-\parbox[t]{\headwidth}{\centering#3\strut}\hfill
-\llap{\parbox[t]{\headwidth}{\raggedleft#4\strut}}}}}#5}
-
-\def\headrule{{\if@fancyplain\let\headrulewidth\plainheadrulewidth\fi
-\hrule\@height\headrulewidth\@width\headwidth \vskip-\headrulewidth}}
-
-\def\footrule{{\if@fancyplain\let\footrulewidth\plainfootrulewidth\fi
-\vskip-\footruleskip\vskip-\footrulewidth
-\hrule\@width\headwidth\@height\footrulewidth\vskip\footruleskip}}
-
-\def\ps@fancy{%
-\@ifundefined{@chapapp}{\let\@chapapp\chaptername}{}%for amsbook
-%
-% Define \MakeUppercase for old LaTeXen.
-% Note: we used \def rather than \let, so that \let\uppercase\relax (from
-% the version 1 documentation) will still work.
-%
-\@ifundefined{MakeUppercase}{\def\MakeUppercase{\uppercase}}{}%
-\@ifundefined{chapter}{\def\sectionmark##1{\markboth
-{\MakeUppercase{\ifnum \c@secnumdepth>\z@
- \thesection\hskip 1em\relax \fi ##1}}{}}%
-\def\subsectionmark##1{\markright {\ifnum \c@secnumdepth >\@ne
- \thesubsection\hskip 1em\relax \fi ##1}}}%
-{\def\chaptermark##1{\markboth {\MakeUppercase{\ifnum \c@secnumdepth>\m@ne
- \@chapapp\ \thechapter. \ \fi ##1}}{}}%
-\def\sectionmark##1{\markright{\MakeUppercase{\ifnum \c@secnumdepth >\z@
- \thesection. \ \fi ##1}}}}%
-%\csname ps@headings\endcsname % use \ps@headings defaults if they exist
-\ps@@fancy
-\gdef\ps@fancy{\@fancyplainfalse\ps@@fancy}%
-% Initialize \headwidth if the user didn't
-%
-\ifdim\headwidth<0sp
-%
-% This catches the case that \headwidth hasn't been initialized and the
-% case that the user added something to \headwidth in the expectation that
-% it was initialized to \textwidth. We compensate this now. This loses if
-% the user intended to multiply it by a factor. But that case is more
-% likely done by saying something like \headwidth=1.2\textwidth.
-% The doc says you have to change \headwidth after the first call to
-% \pagestyle{fancy}. This code is just to catch the most common cases were
-% that requirement is violated.
-%
- \global\advance\headwidth123456789sp\global\advance\headwidth\textwidth
-\fi}
-\def\ps@fancyplain{\ps@fancy \let\ps@plain\ps@plain@fancy}
-\def\ps@plain@fancy{\@fancyplaintrue\ps@@fancy}
-\let\ps@@empty\ps@empty
-\def\ps@@fancy{%
-\ps@@empty % This is for amsbook/amsart, which do strange things with \topskip
-\def\@mkboth{\protect\markboth}%
-\def\@oddhead{\@fancyhead\@lodd\f@ncyolh\f@ncyoch\f@ncyorh\@rodd}%
-\def\@oddfoot{\@fancyfoot\@lodd\f@ncyolf\f@ncyocf\f@ncyorf\@rodd}%
-\def\@evenhead{\@fancyhead\@rodd\f@ncyelh\f@ncyech\f@ncyerh\@lodd}%
-\def\@evenfoot{\@fancyfoot\@rodd\f@ncyelf\f@ncyecf\f@ncyerf\@lodd}%
-}
-\def\@lodd{\if@reversemargin\hss\else\relax\fi}
-\def\@rodd{\if@reversemargin\relax\else\hss\fi}
-
-\newif\iffootnote
-\let\latex@makecol\@makecol
-\def\@makecol{\ifvoid\footins\footnotetrue\else\footnotefalse\fi
-\let\topfloat\@toplist\let\botfloat\@botlist\latex@makecol}
-\def\iftopfloat#1#2{\ifx\topfloat\empty #2\else #1\fi}
-\def\ifbotfloat#1#2{\ifx\botfloat\empty #2\else #1\fi}
-\def\iffloatpage#1#2{\if@fcolmade #1\else #2\fi}
-
-\newcommand{\fancypagestyle}[2]{%
- \@namedef{ps@#1}{\let\fancy@def\def#2\relax\ps@fancy}}
diff --git a/Doc/texinputs/fncychap.sty b/Doc/texinputs/fncychap.sty
deleted file mode 100644
index b0d7b76..0000000
--- a/Doc/texinputs/fncychap.sty
+++ /dev/null
@@ -1,433 +0,0 @@
-%%% Derived from the original fncychap.sty,
-%%% but changed ``TWELV'' to ``TWELVE''.
-
-%%% Copyright Ulf A. Lindgren
-%%% Department of Applied Electronics
-%%% Chalmers University of Technology
-%%% S-412 96 Gothenburg, Sweden
-%%% E-mail lindgren@ae.chalmers.se
-%%%
-%%% Note Permission is granted to modify this file under
-%%% the condition that it is saved using another
-%%% file and package name.
-%%%
-%%% Revision 1.1
-%%%
-%%% Jan. 8th Modified package name base date option
-%%% Jan. 22th Modified FmN and FmTi for error in book.cls
-%%% \MakeUppercase{#}->{\MakeUppercase#}
-%%% Apr. 6th Modified Lenny option to prevent undesired
-%%% skip of line.
-%%% Nov. 8th Fixed \@chapapp for AMS
-%%% Feb. 11th Fixed appendix problem related to Bjarne
-%%% Last modified Feb. 11th 1998
-
-\NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{fncychap}
- [1997/04/06 v1.11
- LaTeX package (Revised chapters)]
-
-%%%% DEFINITION OF Chapapp variables
-\newcommand{\CNV}{\huge\bfseries}
-\newcommand{\ChNameVar}[1]{\renewcommand{\CNV}{#1}}
-
-
-%%%% DEFINITION OF TheChapter variables
-\newcommand{\CNoV}{\huge\bfseries}
-\newcommand{\ChNumVar}[1]{\renewcommand{\CNoV}{#1}}
-
-\newif\ifUCN
-\UCNfalse
-\newif\ifLCN
-\LCNfalse
-\def\ChNameLowerCase{\LCNtrue\UCNfalse}
-\def\ChNameUpperCase{\UCNtrue\LCNfalse}
-\def\ChNameAsIs{\UCNfalse\LCNfalse}
-
-%%%%% Fix for AMSBook 971008
-
-\@ifundefined{@chapapp}{\let\@chapapp\chaptername}{}
-
-
-%%%%% Fix for Bjarne and appendix 980211
-
-\newif\ifinapp
-\inappfalse
-\renewcommand\appendix{\par
- \setcounter{chapter}{0}%
- \setcounter{section}{0}%
- \inapptrue%
- \renewcommand\@chapapp{\appendixname}%
- \renewcommand\thechapter{\@Alph\c@chapter}}
-
-%%%%%
-
-\newcommand{\FmN}[1]{%
-\ifUCN
- {\MakeUppercase#1}\LCNfalse
-\else
- \ifLCN
- {\MakeLowercase#1}\UCNfalse
- \else #1
- \fi
-\fi}
-
-
-%%%% DEFINITION OF Title variables
-\newcommand{\CTV}{\Huge\bfseries}
-\newcommand{\ChTitleVar}[1]{\renewcommand{\CTV}{#1}}
-
-%%%% DEFINITION OF the basic rule width
-\newlength{\RW}
-\setlength{\RW}{1pt}
-\newcommand{\ChRuleWidth}[1]{\setlength{\RW}{#1}}
-
-\newif\ifUCT
-\UCTfalse
-\newif\ifLCT
-\LCTfalse
-\def\ChTitleLowerCase{\LCTtrue\UCTfalse}
-\def\ChTitleUpperCase{\UCTtrue\LCTfalse}
-\def\ChTitleAsIs{\UCTfalse\LCTfalse}
-\newcommand{\FmTi}[1]{%
-\ifUCT
-
- {\MakeUppercase#1}\LCTfalse
-\else
- \ifLCT
- {\MakeLowercase#1}\UCTfalse
- \else #1
- \fi
-\fi}
-
-
-
-\newlength{\mylen}
-\newlength{\myhi}
-\newlength{\px}
-\newlength{\py}
-\newlength{\pyy}
-\newlength{\pxx}
-
-
-\def\mghrulefill#1{\leavevmode\leaders\hrule\@height #1\hfill\kern\z@}
-
-\newcommand{\DOCH}{%
- \CNV\FmN{\@chapapp}\space \CNoV\thechapter
- \par\nobreak
- \vskip 20\p@
- }
-\newcommand{\DOTI}[1]{%
- \CTV\FmTi{#1}\par\nobreak
- \vskip 40\p@
- }
-\newcommand{\DOTIS}[1]{%
- \CTV\FmTi{#1}\par\nobreak
- \vskip 40\p@
- }
-
-%%%%%% SONNY DEF
-
-\DeclareOption{Sonny}{%
- \ChNameVar{\Large\sf}
- \ChNumVar{\Huge}
- \ChTitleVar{\Large\sf}
- \ChRuleWidth{0.5pt}
- \ChNameUpperCase
- \renewcommand{\DOCH}{%
- \raggedleft
- \CNV\FmN{\@chapapp}\space \CNoV\thechapter
- \par\nobreak
- \vskip 40\p@}
- \renewcommand{\DOTI}[1]{%
- \CTV\raggedleft\mghrulefill{\RW}\par\nobreak
- \vskip 5\p@
- \CTV\FmTi{#1}\par\nobreak
- \mghrulefill{\RW}\par\nobreak
- \vskip 40\p@}
- \renewcommand{\DOTIS}[1]{%
- \CTV\raggedleft\mghrulefill{\RW}\par\nobreak
- \vskip 5\p@
- \CTV\FmTi{#1}\par\nobreak
- \mghrulefill{\RW}\par\nobreak
- \vskip 40\p@}
-}
-
-%%%%%% LENNY DEF
-
-\DeclareOption{Lenny}{%
-
- \ChNameVar{\fontsize{14}{16}\usefont{OT1}{phv}{m}{n}\selectfont}
- \ChNumVar{\fontsize{60}{62}\usefont{OT1}{ptm}{m}{n}\selectfont}
- \ChTitleVar{\Huge\bfseries\rm}
- \ChRuleWidth{1pt}
- \renewcommand{\DOCH}{%
- \settowidth{\px}{\CNV\FmN{\@chapapp}}
- \addtolength{\px}{2pt}
- \settoheight{\py}{\CNV\FmN{\@chapapp}}
- \addtolength{\py}{1pt}
-
- \settowidth{\mylen}{\CNV\FmN{\@chapapp}\space\CNoV\thechapter}
- \addtolength{\mylen}{1pt}
- \settowidth{\pxx}{\CNoV\thechapter}
- \addtolength{\pxx}{-1pt}
-
- \settoheight{\pyy}{\CNoV\thechapter}
- \addtolength{\pyy}{-2pt}
- \setlength{\myhi}{\pyy}
- \addtolength{\myhi}{-1\py}
- \par
- \parbox[b]{\textwidth}{%
- \rule[\py]{\RW}{\myhi}%
- \hskip -\RW%
- \rule[\pyy]{\px}{\RW}%
- \hskip -\px%
- \raggedright%
- \CNV\FmN{\@chapapp}\space\CNoV\thechapter%
- \hskip1pt%
- \mghrulefill{\RW}%
- \rule{\RW}{\pyy}\par\nobreak%
- \vskip -\baselineskip%
- \vskip -\pyy%
- \hskip \mylen%
- \mghrulefill{\RW}\par\nobreak%
- \vskip \pyy}%
- \vskip 20\p@}
-
-
- \renewcommand{\DOTI}[1]{%
- \raggedright
- \CTV\FmTi{#1}\par\nobreak
- \vskip 40\p@}
-
- \renewcommand{\DOTIS}[1]{%
- \raggedright
- \CTV\FmTi{#1}\par\nobreak
- \vskip 40\p@}
- }
-
-
-%%%%%%% GLENN DEF
-
-
-\DeclareOption{Glenn}{%
- \ChNameVar{\bfseries\Large\sf}
- \ChNumVar{\Huge}
- \ChTitleVar{\bfseries\Large\rm}
- \ChRuleWidth{1pt}
- \ChNameUpperCase
- \ChTitleUpperCase
- \renewcommand{\DOCH}{%
- \settoheight{\myhi}{\CTV\FmTi{Test}}
- \setlength{\py}{\baselineskip}
- \addtolength{\py}{\RW}
- \addtolength{\py}{\myhi}
- \setlength{\pyy}{\py}
- \addtolength{\pyy}{-1\RW}
-
- \raggedright
- \CNV\FmN{\@chapapp}\space\CNoV\thechapter
- \hskip 3pt\mghrulefill{\RW}\rule[-1\pyy]{2\RW}{\py}\par\nobreak}
-
- \renewcommand{\DOTI}[1]{%
- \addtolength{\pyy}{-4pt}
- \settoheight{\myhi}{\CTV\FmTi{#1}}
- \addtolength{\myhi}{\py}
- \addtolength{\myhi}{-1\RW}
- \vskip -1\pyy
- \rule{2\RW}{\myhi}\mghrulefill{\RW}\hskip 2pt
- \raggedleft\CTV\FmTi{#1}\par\nobreak
- \vskip 80\p@}
-
- \renewcommand{\DOTIS}[1]{%
- \setlength{\py}{10pt}
- \setlength{\pyy}{\py}
- \addtolength{\pyy}{\RW}
- \setlength{\myhi}{\baselineskip}
- \addtolength{\myhi}{\pyy}
- \mghrulefill{\RW}\rule[-1\py]{2\RW}{\pyy}\par\nobreak
-% \addtolength{}{}
-\vskip -1\baselineskip
- \rule{2\RW}{\myhi}\mghrulefill{\RW}\hskip 2pt
- \raggedleft\CTV\FmTi{#1}\par\nobreak
- \vskip 60\p@}
- }
-
-%%%%%%% CONNY DEF
-
-\DeclareOption{Conny}{%
- \ChNameUpperCase
- \ChTitleUpperCase
- \ChNameVar{\centering\Huge\rm\bfseries}
- \ChNumVar{\Huge}
- \ChTitleVar{\centering\Huge\rm}
- \ChRuleWidth{2pt}
-
- \renewcommand{\DOCH}{%
- \mghrulefill{3\RW}\par\nobreak
- \vskip -0.5\baselineskip
- \mghrulefill{\RW}\par\nobreak
- \CNV\FmN{\@chapapp}\space \CNoV\thechapter
- \par\nobreak
- \vskip -0.5\baselineskip
- }
- \renewcommand{\DOTI}[1]{%
- \mghrulefill{\RW}\par\nobreak
- \CTV\FmTi{#1}\par\nobreak
- \vskip 60\p@
- }
- \renewcommand{\DOTIS}[1]{%
- \mghrulefill{\RW}\par\nobreak
- \CTV\FmTi{#1}\par\nobreak
- \vskip 60\p@
- }
- }
-
-%%%%%%% REJNE DEF
-
-\DeclareOption{Rejne}{%
-
- \ChNameUpperCase
- \ChTitleUpperCase
- \ChNameVar{\centering\Large\rm}
- \ChNumVar{\Huge}
- \ChTitleVar{\centering\Huge\rm}
- \ChRuleWidth{1pt}
- \renewcommand{\DOCH}{%
- \settoheight{\py}{\CNoV\thechapter}
- \addtolength{\py}{-1pt}
- \CNV\FmN{\@chapapp}\par\nobreak
- \vskip 20\p@
- \setlength{\myhi}{2\baselineskip}
- \setlength{\px}{\myhi}
- \addtolength{\px}{-1\RW}
- \rule[-1\px]{\RW}{\myhi}\mghrulefill{\RW}\hskip
- 10pt\raisebox{-0.5\py}{\CNoV\thechapter}\hskip
-10pt\mghrulefill{\RW}\rule[-1\px]{\RW}{\myhi}\par\nobreak
- \vskip -1\p@
- }
- \renewcommand{\DOTI}[1]{%
- \setlength{\mylen}{\textwidth}
- \addtolength{\mylen}{-2\RW}
- {\vrule width\RW}\parbox{\mylen}{\CTV\FmTi{#1}}{\vrule
-width\RW}\par\nobreak
- \vskip
--1pt\rule{\RW}{2\baselineskip}\mghrulefill{\RW}\rule{\RW}{2\baselineskip}
- \vskip 60\p@
- }
- \renewcommand{\DOTIS}[1]{%
- \setlength{\py}{\fboxrule}
- \setlength{\fboxrule}{\RW}
- \setlength{\mylen}{\textwidth}
- \addtolength{\mylen}{-2\RW}
- \fbox{\parbox{\mylen}{\vskip
-2\baselineskip\CTV\FmTi{#1}\par\nobreak\vskip \baselineskip}}
- \setlength{\fboxrule}{\py}
- \vskip 60\p@
- }
- }
-
-
-%%%%%%% BJARNE DEF
-
-\DeclareOption{Bjarne}{%
- \ChNameUpperCase
- \ChTitleUpperCase
- \ChNameVar{\raggedleft\normalsize\rm}
- \ChNumVar{\raggedleft \bfseries\Large}
- \ChTitleVar{\raggedleft \Large\rm}
- \ChRuleWidth{1pt}
-
-
-%% Note thechapter -> c@chapter fix appendix bug
-
- \newcounter{AlphaCnt}
- \newcounter{AlphaDecCnt}
- \newcommand{\AlphaNo}{%
- \ifcase\number\theAlphaCnt
- \ifnum\c@chapter=0
- ZERO\else{}\fi
- \or ONE\or TWO\or THREE\or FOUR\or FIVE
- \or SIX\or SEVEN\or EIGHT\or NINE\or TEN
- \or ELEVEN\or TWELVE\or THIRTEEN\or FOURTEEN\or FIFTEEN
- \or SIXTEEN\or SEVENTEEN\or EIGHTEEN\or NINETEEN\fi
-}
-
- \newcommand{\AlphaDecNo}{%
- \setcounter{AlphaDecCnt}{0}
- \@whilenum\number\theAlphaCnt>0\do
- {\addtocounter{AlphaCnt}{-10}
- \addtocounter{AlphaDecCnt}{1}}
- \ifnum\number\theAlphaCnt=0
- \else
- \addtocounter{AlphaDecCnt}{-1}
- \addtocounter{AlphaCnt}{10}
- \fi
-
-
- \ifcase\number\theAlphaDecCnt\or TEN\or TWENTY\or THIRTY\or
- FORTY\or FIFTY\or SIXTY\or SEVENTY\or EIGHTY\or NINETY\fi
- }
- \newcommand{\TheAlphaChapter}{%
-
- \ifinapp
- \thechapter
- \else
- \setcounter{AlphaCnt}{\c@chapter}
- \ifnum\c@chapter<20
- \AlphaNo
- \else
- \AlphaDecNo\AlphaNo
- \fi
- \fi
- }
- \renewcommand{\DOCH}{%
- \mghrulefill{\RW}\par\nobreak
- \CNV\FmN{\@chapapp}\par\nobreak
- \CNoV\TheAlphaChapter\par\nobreak
- \vskip -1\baselineskip\vskip 5pt\mghrulefill{\RW}\par\nobreak
- \vskip 20\p@
- }
- \renewcommand{\DOTI}[1]{%
- \CTV\FmTi{#1}\par\nobreak
- \vskip 40\p@
- }
- \renewcommand{\DOTIS}[1]{%
- \CTV\FmTi{#1}\par\nobreak
- \vskip 40\p@
- }
-}
-
-\DeclareOption*{%
- \PackageWarning{fancychapter}{unknown style option}
- }
-
-\ProcessOptions* \relax
-
-\def\@makechapterhead#1{%
- \vspace*{50\p@}%
- {\parindent \z@ \raggedright \normalfont
- \ifnum \c@secnumdepth >\m@ne
- \DOCH
- \fi
- \interlinepenalty\@M
- \DOTI{#1}
- }}
-\def\@schapter#1{\if@twocolumn
- \@topnewpage[\@makeschapterhead{#1}]%
- \else
- \@makeschapterhead{#1}%
- \@afterheading
- \fi}
-\def\@makeschapterhead#1{%
- \vspace*{50\p@}%
- {\parindent \z@ \raggedright
- \normalfont
- \interlinepenalty\@M
- \DOTIS{#1}
- \vskip 40\p@
- }}
-
-\endinput
-
-
diff --git a/Doc/texinputs/howto.cls b/Doc/texinputs/howto.cls
deleted file mode 100644
index c9beb4a..0000000
--- a/Doc/texinputs/howto.cls
+++ /dev/null
@@ -1,109 +0,0 @@
-%
-% howto.cls for the Python documentation
-%
-
-\NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesClass{howto}
- [1998/02/25 Document class (Python HOWTO)]
-
-\RequirePackage{pypaper}
-\RequirePackage{fancybox}
-
-% Change the options here to get a different set of basic options, This
-% is where to add things like "a4paper" or "10pt".
-%
-\LoadClass[\py@paper,\py@ptsize,twoside]{article}
-
-\setcounter{secnumdepth}{1}
-
-% Optional packages:
-%
-% If processing of these documents fails at your TeX installation,
-% these may be commented out (independently) to make things work.
-% These are both supplied with the current version of the teTeX
-% distribution.
-%
-% The "fancyhdr" package makes nicer page footers reasonable to
-% implement, and is used to put the chapter and section information in
-% the footers.
-%
-\RequirePackage{fancyhdr}\typeout{Using fancier footers than usual.}
-
-
-% Required package:
-%
-% This gives us all the Python-specific markup that we really want.
-% This should come last. Do not change this.
-%
-\RequirePackage{python}
-
-% support for module synopsis sections:
-\newcommand{\py@ModSynopsisFilename}{\jobname.syn}
-
-
-% need to do one of these....
-\newcommand{\py@doHorizontalRule}{\rule{\textwidth}{1pt}}
-
-
-% Change the title page to look a bit better, and fit in with the
-% fncychap ``Bjarne'' style a bit better.
-%
-\renewcommand{\maketitle}{
- \py@doHorizontalRule
- \ifpdf
- \begingroup
- % This \def is required to deal with multi-line authors; it
- % changes \\ to ', ' (comma-space), making it pass muster for
- % generating document info in the PDF file.
- \def\\{, }
- \pdfinfo{
- /Author (\@author)
- /Title (\@title)
- }
- \endgroup
- \fi
- \begin{flushright}
- {\rm\Huge\py@HeaderFamily \@title} \par
- {\em\large\py@HeaderFamily \py@release\releaseinfo} \par
- \vspace{25pt}
- {\Large\py@HeaderFamily \@author} \par
- \vspace{25pt}
- \@date \par
- \py@authoraddress \par
- \end{flushright}
- \@thanks
- \setcounter{footnote}{0}
- \let\thanks\relax\let\maketitle\relax
- \gdef\@thanks{}\gdef\@author{}\gdef\@title{}
-}
-
-
-\let\py@OldTableofcontents=\tableofcontents
-\renewcommand{\tableofcontents}{
- \begingroup
- \parskip = 0mm
- \py@OldTableofcontents
- \endgroup
- \py@doHorizontalRule
- \vspace{12pt}
- \py@doing@page@targetstrue
-}
-
-% Fix the theindex environment to add an entry to the Table of
-% Contents; this is much nicer than just having to jump to the end of
-% the book and flip around, especially with multiple indexes.
-%
-\let\py@OldTheindex=\theindex
-\renewcommand{\theindex}{
- \clearpage
- \py@OldTheindex
- \addcontentsline{toc}{section}{\indexname}
-}
-
-\@ifundefined{fancyhf}{
- \pagestyle{plain}}{
- \pagestyle{normal}} % start this way; change for
-\pagenumbering{arabic} % ToC & chapters
-\setcounter{secnumdepth}{2}
-
-\thispagestyle{empty}
diff --git a/Doc/texinputs/ltxmarkup.sty b/Doc/texinputs/ltxmarkup.sty
deleted file mode 100644
index ace08cc..0000000
--- a/Doc/texinputs/ltxmarkup.sty
+++ /dev/null
@@ -1,40 +0,0 @@
-% Created by Fred L. Drake, Jr. <fdrake@acm.org>, as part of the
-% Python Documentation Project.
-%
-% Define some simple markup for the LaTeX command documentation:
-
-\ProvidesPackage{ltxmarkup}
-\RequirePackage{python} % fulllineitems environment
-
-% These two macros are used in constructing the last parameter to the
-% envdesc and macrodesc environments.
-
-\newcommand{\py@ltx@optparam}[1]{{[}\var{#1}{]}}
-\newcommand{\py@ltx@param}[1]{\{\var{#1}\}}
-
-\newenvironment{envdesc}[2]{
- \begin{fulllineitems}
- \item[\code{\e begin\{{\bfseries #1}\}{%
- \let\op=\py@ltx@optparam%
- \let\p=\py@ltx@param%
- \let\unspecified=\py@unspecified%
- \let\moreargs=\py@moreargs%
- #2}}]
- \item[\code{\e end\{{\bfseries #1}\}}]
- \index{#1 environment@\py@idxcode{#1} environment}
- \index{environments!#1@\py@idxcode{#1}}
-}{\end{fulllineitems}}
-
-\newenvironment{macrodesc}[2]{
- \begin{fulllineitems}
- \item[\code{{\e\bfseries#1}{%
- \let\op=\py@ltx@optparam%
- \let\p=\py@ltx@param%
- \let\unspecified=\py@unspecified%
- \let\moreargs=\py@moreargs%
- #2}}]
- \index{#1@\py@idxcode{#1}}
-}{\end{fulllineitems}}
-
-\newcommand{\env}[1]{\code{#1}}
-\newcommand{\macro}[1]{\code{\e#1}}
diff --git a/Doc/texinputs/manual.cls b/Doc/texinputs/manual.cls
deleted file mode 100644
index ddaa404..0000000
--- a/Doc/texinputs/manual.cls
+++ /dev/null
@@ -1,155 +0,0 @@
-%
-% manual.cls for the Python documentation
-%
-
-\NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesClass{manual}
- [1998/03/03 Document class (Python manual)]
-
-\RequirePackage{pypaper}
-\RequirePackage{fancybox}
-
-% Change the options here to get a different set of basic options, but only
-% if you have to. Paper and font size should be adjusted in pypaper.sty.
-%
-\LoadClass[\py@paper,\py@ptsize,twoside,openright]{report}
-
-\setcounter{secnumdepth}{2}
-
-% Optional packages:
-%
-% If processing of these documents fails at your TeX installation,
-% these may be commented out (independently) to make things work.
-% These are both supplied with the current version of the teTeX
-% distribution.
-%
-% The "fancyhdr" package makes nicer page footers reasonable to
-% implement, and is used to put the chapter and section information in
-% the footers.
-%
-\RequirePackage{fancyhdr}\typeout{Using fancier footers than usual.}
-
-
-% Required packages:
-%
-% The "fncychap" package is used to get the nice chapter headers. The
-% .sty file is distributed with Python, so you should not need to disable
-% it. You'd also end up with a mixed page style; uglier than stock LaTeX!
-%
-\RequirePackage[Bjarne]{fncychap}\typeout{Using fancy chapter headings.}
-% Do horizontal rules it this way to match:
-\newcommand{\py@doHorizontalRule}{\mghrulefill{\RW}}
-%
-%
-% This gives us all the Python-specific markup that we really want.
-% This should come last. Do not change this.
-%
-\RequirePackage{python}
-
-% support for module synopsis sections:
-\newcommand{\py@ModSynopsisFilename}{\jobname\thechapter.syn}
-\let\py@OldChapter=\chapter
-\renewcommand{\chapter}{
- \py@ProcessModSynopsis
- \py@closeModSynopsisFile
- \py@OldChapter
-}
-
-
-% Change the title page to look a bit better, and fit in with the
-% fncychap ``Bjarne'' style a bit better.
-%
-\renewcommand{\maketitle}{%
- \begin{titlepage}%
- \let\footnotesize\small
- \let\footnoterule\relax
- \py@doHorizontalRule%
- \ifpdf
- \begingroup
- % This \def is required to deal with multi-line authors; it
- % changes \\ to ', ' (comma-space), making it pass muster for
- % generating document info in the PDF file.
- \def\\{, }
- \pdfinfo{
- /Author (\@author)
- /Title (\@title)
- }
- \endgroup
- \fi
- \begin{flushright}%
- {\rm\Huge\py@HeaderFamily \@title \par}%
- {\em\LARGE\py@HeaderFamily \py@release\releaseinfo \par}
- \vfill
- {\LARGE\py@HeaderFamily \@author \par}
- \vfill\vfill
- {\large
- \@date \par
- \vfill
- \py@authoraddress \par
- }%
- \end{flushright}%\par
- \@thanks
- \end{titlepage}%
- \setcounter{footnote}{0}%
- \let\thanks\relax\let\maketitle\relax
- \gdef\@thanks{}\gdef\@author{}\gdef\@title{}
-}
-
-
-% Catch the end of the {abstract} environment, but here make sure the
-% abstract is followed by a blank page if the 'openright' option is used.
-%
-\let\py@OldEndAbstract=\endabstract
-\renewcommand{\endabstract}{
- \if@openright
- \ifodd\value{page}
- \typeout{Adding blank page after the abstract.}
- \vfil\pagebreak
- \fi
- \fi
- \py@OldEndAbstract
-}
-
-% This wraps the \tableofcontents macro with all the magic to get the
-% spacing right and have the right number of pages if the 'openright'
-% option has been used. This eliminates a fair amount of crud in the
-% individual document files.
-%
-\let\py@OldTableofcontents=\tableofcontents
-\renewcommand{\tableofcontents}{%
- \setcounter{page}{1}%
- \pagebreak%
- \pagestyle{plain}%
- {%
- \parskip = 0mm%
- \py@OldTableofcontents%
- \if@openright%
- \ifodd\value{page}%
- \typeout{Adding blank page after the table of contents.}%
- \pagebreak\hspace{0pt}%
- \fi%
- \fi%
- \cleardoublepage%
- }%
- \pagenumbering{arabic}%
- \@ifundefined{fancyhf}{}{\pagestyle{normal}}%
- \py@doing@page@targetstrue%
-}
-% This is needed to get the width of the section # area wide enough in the
-% library reference. Doing it here keeps it the same for all the manuals.
-%
-\renewcommand*\l@section{\@dottedtocline{1}{1.5em}{2.6em}}
-\renewcommand*\l@subsection{\@dottedtocline{2}{4.1em}{3.5em}}
-\setcounter{tocdepth}{1}
-
-
-% Fix the theindex environment to add an entry to the Table of
-% Contents; this is much nicer than just having to jump to the end of
-% the book and flip around, especially with multiple indexes.
-%
-\let\py@OldTheindex=\theindex
-\renewcommand{\theindex}{
- \cleardoublepage
- \py@OldTheindex
- \addcontentsline{toc}{chapter}{\indexname}
-}
diff --git a/Doc/texinputs/pypaper.sty b/Doc/texinputs/pypaper.sty
deleted file mode 100644
index 3959637..0000000
--- a/Doc/texinputs/pypaper.sty
+++ /dev/null
@@ -1,18 +0,0 @@
-%
-% Change this to say a4paper instead of letterpaper if you want A4. These
-% are the latex defaults.
-%
-\newcommand{\py@paper}{letterpaper}
-\newcommand{\py@ptsize}{10pt}
-
-% These set up the fonts for the documents.
-%
-% The "times" package makes the default font the PostScript Times
-% font, which makes for smaller PostScript and a font that more people
-% like.
-%
-% The "avant" package causes the AvantGarde font to be used for
-% sans-serif text, instead of the uglier Helvetica set up by the "times"
-% package.
-%
-\RequirePackage{times}\typeout{Using Times instead of Computer Modern.}
diff --git a/Doc/texinputs/python.ist b/Doc/texinputs/python.ist
deleted file mode 100644
index 9ffa0f9..0000000
--- a/Doc/texinputs/python.ist
+++ /dev/null
@@ -1,11 +0,0 @@
-line_max 100
-headings_flag 1
-heading_prefix " \\bigletter "
-
-preamble "\\begin{theindex}
-\\def\\bigletter#1{{\\Large\\sffamily#1}\\nopagebreak\\vspace{1mm}}
-
-"
-
-symhead_positive "{Symbols}"
-numhead_positive "{Numbers}"
diff --git a/Doc/texinputs/python.sty b/Doc/texinputs/python.sty
deleted file mode 100644
index 494323e..0000000
--- a/Doc/texinputs/python.sty
+++ /dev/null
@@ -1,1327 +0,0 @@
-%
-% python.sty for the Python docummentation [works only with Latex2e]
-%
-
-\NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{python}
- [1998/01/11 LaTeX package (Python markup)]
-
-\RequirePackage{longtable}
-\RequirePackage{underscore}
-
-% Uncomment these two lines to ignore the paper size and make the page
-% size more like a typical published manual.
-%\renewcommand{\paperheight}{9in}
-%\renewcommand{\paperwidth}{8.5in} % typical squarish manual
-%\renewcommand{\paperwidth}{7in} % O'Reilly ``Programmming Python''
-
-% These packages can be used to add marginal annotations which indicate
-% index entries and labels; useful for reviewing this messy documentation!
-%
-%\RequirePackage{showkeys}
-%\RequirePackage{showidx}
-
-% If we ever want to indent paragraphs, this needs to be changed.
-% This is used inside the macros defined here instead of coding
-% \noindent directly.
-\let\py@parindent=\noindent
-
-% for PDF output, use maximal compression & a lot of other stuff
-% (test for PDF recommended by Tanmoy Bhattacharya <tanmoy@qcd.lanl.gov>)
-%
-\newif\ifpy@doing@page@targets
-\py@doing@page@targetsfalse
-
-\newif\ifpdf\pdffalse
-\ifx\pdfoutput\undefined\else\ifcase\pdfoutput
-\else
- \pdftrue
- \input{pdfcolor}
- \let\py@LinkColor=\NavyBlue
- \let\py@NormalColor=\Black
- \pdfcompresslevel=9
- \pdfpagewidth=\paperwidth % page width of PDF output
- \pdfpageheight=\paperheight % page height of PDF output
- %
- % Pad the number with '0' to 3 digits wide so no page name is a prefix
- % of any other.
- %
- \newcommand{\py@targetno}[1]{\ifnum#1<100 0\fi\ifnum#1<10 0\fi#1}
- \newcommand{\py@pageno}{\py@targetno\thepage}
- %
- % This definition allows the entries in the page-view of the ToC to be
- % active links. Some work, some don't.
- %
- \let\py@OldContentsline=\contentsline
- %
- % Backward compatibility hack: pdfTeX 0.13 defined \pdfannotlink,
- % but it changed to \pdfstartlink in 0.14. This let's us use either
- % version and still get useful behavior.
- %
- \@ifundefined{pdfstartlink}{
- \let\pdfstartlink=\pdfannotlink
- }{}
- %
- % The \py@parindent here is a hack -- we're forcing pdfTeX into
- % horizontal mode since \pdfstartlink requires that.
- \def\py@pdfstartlink{%
- \ifvmode\py@parindent\fi%
- \pdfstartlink%
- }
- %
- % Macro that takes two args: the name to link to and the content of
- % the link. This takes care of the PDF magic, getting the colors
- % the same for each link, and avoids having lots of garbage all over
- % this style file.
- \newcommand{\py@linkToName}[2]{%
- \py@pdfstartlink attr{/Border [0 0 0]} goto name{#1}%
- \py@LinkColor#2\py@NormalColor%
- \pdfendlink%
- }
- % Compute the padded page number separately since we end up with a pair of
- % \relax tokens; this gets the right string computed and works.
- \renewcommand{\contentsline}[3]{%
- \def\my@pageno{\py@targetno{#3}}%
- \py@OldContentsline{#1}{\py@linkToName{page\my@pageno}{#2}}{#3}%
- }
- \AtEndDocument{
- \def\_{\string_}
- \InputIfFileExists{\jobname.bkm}{\pdfcatalog{/PageMode /UseOutlines}}{}
- }
- \newcommand{\py@target}[1]{%
- \ifpy@doing@page@targets%
- {\pdfdest name{#1} xyz}%
- \fi%
- }
- \let\py@OldLabel=\label
- \renewcommand{\label}[1]{%
- \py@OldLabel{#1}%
- \py@target{label-#1}%
- }
- % This stuff adds a page# destination to every PDF page, where # is three
- % digits wide, padded with leading zeros. This doesn't really help with
- % the frontmatter, but does fine with the body.
- %
- % This is *heavily* based on the hyperref package.
- %
- \def\@begindvi{%
- \unvbox \@begindvibox
- \@hyperfixhead
- }
- \def\@hyperfixhead{%
- \let\H@old@thehead\@thehead
- \global\def\@foo{\py@target{page\py@pageno}}%
- \expandafter\ifx\expandafter\@empty\H@old@thehead
- \def\H@old@thehead{\hfil}\fi
- \def\@thehead{\@foo\relax\H@old@thehead}%
- }
-\fi\fi
-
-% Increase printable page size (copied from fullpage.sty)
-\topmargin 0pt
-\advance \topmargin by -\headheight
-\advance \topmargin by -\headsep
-
-% attempt to work a little better for A4 users
-\textheight \paperheight
-\advance\textheight by -2in
-
-\oddsidemargin 0pt
-\evensidemargin 0pt
-%\evensidemargin -.25in % for ``manual size'' documents
-\marginparwidth 0.5in
-
-\textwidth \paperwidth
-\advance\textwidth by -2in
-
-
-% Style parameters and macros used by most documents here
-\raggedbottom
-\sloppy
-\parindent = 0mm
-\parskip = 2mm
-\hbadness = 5000 % don't print trivial gripes
-
-\pagestyle{empty} % start this way; change for
-\pagenumbering{roman} % ToC & chapters
-
-% Use this to set the font family for headers and other decor:
-\newcommand{\py@HeaderFamily}{\sffamily}
-
-% Set up abstract ways to get the normal and smaller font sizes that
-% work even in footnote context.
-\newif\ifpy@infootnote \py@infootnotefalse
-\let\py@oldmakefntext\@makefntext
-\def\@makefntext#1{%
- \bgroup%
- \py@infootnotetrue
- \py@oldmakefntext{#1}%
- \egroup%
-}
-\def\py@defaultsize{%
- \ifpy@infootnote\footnotesize\else\normalsize\fi%
-}
-\def\py@smallsize{%
- \ifpy@infootnote\scriptsize\else\small\fi%
-}
-
-% Redefine the 'normal' header/footer style when using "fancyhdr" package:
-\@ifundefined{fancyhf}{}{
- % Use \pagestyle{normal} as the primary pagestyle for text.
- \fancypagestyle{normal}{
- \fancyhf{}
- \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
- \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}}
- \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}}
- \renewcommand{\headrulewidth}{0pt}
- \renewcommand{\footrulewidth}{0.4pt}
- }
- % Update the plain style so we get the page number & footer line,
- % but not a chapter or section title. This is to keep the first
- % page of a chapter and the blank page between chapters `clean.'
- \fancypagestyle{plain}{
- \fancyhf{}
- \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
- \renewcommand{\headrulewidth}{0pt}
- \renewcommand{\footrulewidth}{0.4pt}
- }
- % Redefine \cleardoublepage so that the blank page between chapters
- % gets the plain style and not the fancy style. This is described
- % in the documentation for the fancyhdr package by Piet von Oostrum.
- \@ifundefined{chapter}{}{
- \renewcommand{\cleardoublepage}{
- \clearpage\if@openright \ifodd\c@page\else
- \hbox{}
- \thispagestyle{plain}
- \newpage
- \if@twocolumn\hbox{}\newpage\fi\fi\fi
- }
- }
-}
-
-% This sets up the {verbatim} environment to be indented and a minipage,
-% and to have all the other mostly nice properties that we want for
-% code samples.
-
-\let\py@OldVerbatim=\verbatim
-\let\py@OldEndVerbatim=\endverbatim
-\RequirePackage{verbatim}
-\let\py@OldVerbatimInput=\verbatiminput
-
-% Variable used by begin code command
-\newlength{\py@codewidth}
-
-\renewcommand{\verbatim}{%
- \setlength{\parindent}{1cm}%
- % Calculate the text width for the minipage:
- \setlength{\py@codewidth}{\linewidth}%
- \addtolength{\py@codewidth}{-\parindent}%
- %
- \par\indent%
- \begin{minipage}[t]{\py@codewidth}%
- \small%
- \py@OldVerbatim%
-}
-\renewcommand{\endverbatim}{%
- \py@OldEndVerbatim%
- \end{minipage}%
-}
-\renewcommand{\verbatiminput}[1]{%
- {\setlength{\parindent}{1cm}%
- % Calculate the text width for the minipage:
- \setlength{\py@codewidth}{\linewidth}%
- \addtolength{\py@codewidth}{-\parindent}%
- %
- \small%
- \begin{list}{}{\setlength{\leftmargin}{1cm}}
- \item%
- \py@OldVerbatimInput{#1}%
- \end{list}
- }%
-}
-
-% This does a similar thing for the {alltt} environment:
-\RequirePackage{alltt}
-\let\py@OldAllTT=\alltt
-\let\py@OldEndAllTT=\endalltt
-
-\renewcommand{\alltt}{%
- \setlength{\parindent}{1cm}%
- % Calculate the text width for the minipage:
- \setlength{\py@codewidth}{\linewidth}%
- \addtolength{\py@codewidth}{-\parindent}%
- \let\e=\textbackslash%
- %
- \par\indent%
- \begin{minipage}[t]{\py@codewidth}%
- \small%
- \py@OldAllTT%
-}
-\renewcommand{\endalltt}{%
- \py@OldEndAllTT%
- \end{minipage}%
-}
-
-
-\newcommand{\py@modulebadkey}{{--just-some-junk--}}
-
-
-%% Lots of index-entry generation support.
-
-% Command to wrap around stuff that refers to function / module /
-% attribute names in the index. Default behavior: like \code{}. To
-% just keep the index entries in the roman font, uncomment the second
-% definition; it matches O'Reilly style more.
-%
-\newcommand{\py@idxcode}[1]{\texttt{#1}}
-%\renewcommand{\py@idxcode}[1]{#1}
-
-% Command to generate two index entries (using subentries)
-\newcommand{\indexii}[2]{\index{#1!#2}\index{#2!#1}}
-
-% And three entries (using only one level of subentries)
-\newcommand{\indexiii}[3]{\index{#1!#2 #3}\index{#2!#3, #1}\index{#3!#1 #2}}
-
-% And four (again, using only one level of subentries)
-\newcommand{\indexiv}[4]{
-\index{#1!#2 #3 #4}
-\index{#2!#3 #4, #1}
-\index{#3!#4, #1 #2}
-\index{#4!#1 #2 #3}
-}
-
-% Command to generate a reference to a function, statement, keyword,
-% operator.
-\newcommand{\kwindex}[1]{\indexii{keyword}{#1@{\py@idxcode{#1}}}}
-\newcommand{\stindex}[1]{\indexii{statement}{#1@{\py@idxcode{#1}}}}
-\newcommand{\opindex}[1]{\indexii{operator}{#1@{\py@idxcode{#1}}}}
-\newcommand{\exindex}[1]{\indexii{exception}{#1@{\py@idxcode{#1}}}}
-\newcommand{\obindex}[1]{\indexii{object}{#1}}
-\newcommand{\bifuncindex}[1]{%
- \index{#1@{\py@idxcode{#1()}} (built-in function)}}
-
-% Add an index entry for a module
-\newcommand{\py@refmodule}[2]{\index{#1@{\py@idxcode{#1}} (#2module)}}
-\newcommand{\refmodindex}[1]{\py@refmodule{#1}{}}
-\newcommand{\refbimodindex}[1]{\py@refmodule{#1}{built-in }}
-\newcommand{\refexmodindex}[1]{\py@refmodule{#1}{extension }}
-\newcommand{\refstmodindex}[1]{\py@refmodule{#1}{standard }}
-
-% Refer to a module's documentation using a hyperlink of the module's
-% name, at least if we're building PDF:
-\ifpdf
- \newcommand{\refmodule}[2][\py@modulebadkey]{%
- \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
- \py@linkToName{label-module-\py@modulekey}{\module{#2}}%
- }
-\else
- \newcommand{\refmodule}[2][\py@modulebadkey]{\module{#2}}
-\fi
-
-% support for the module index
-\newif\ifpy@UseModuleIndex
-\py@UseModuleIndexfalse
-
-\newcommand{\makemodindex}{
- \newwrite\modindexfile
- \openout\modindexfile=mod\jobname.idx
- \py@UseModuleIndextrue
-}
-
-% Add the defining entry for a module
-\newcommand{\py@modindex}[2]{%
- \renewcommand{\py@thismodule}{#1}
- \setindexsubitem{(in module #1)}%
- \index{#1@{\py@idxcode{#1}} (#2module)|textbf}%
- \ifpy@UseModuleIndex%
- \@ifundefined{py@modplat@\py@thismodulekey}{
- \write\modindexfile{\protect\indexentry{#1@{\texttt{#1}}}{\thepage}}%
- }{\write\modindexfile{\protect\indexentry{#1@{\texttt{#1} %
- \emph{(\py@platformof[\py@thismodulekey]{})}}}{\thepage}}%
- }
- \fi%
-}
-
-% *** XXX *** THE NEXT FOUR MACROS ARE NOW OBSOLETE !!! ***
-
-% built-in & Python modules in the main distribution
-\newcommand{\bimodindex}[1]{\py@modindex{#1}{built-in }%
- \typeout{*** MACRO bimodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
-\newcommand{\stmodindex}[1]{\py@modindex{#1}{standard }%
- \typeout{*** MACRO stmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
-
-% Python & extension modules outside the main distribution
-\newcommand{\modindex}[1]{\py@modindex{#1}{}%
- \typeout{*** MACRO modindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
-\newcommand{\exmodindex}[1]{\py@modindex{#1}{extension }%
- \typeout{*** MACRO exmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
-
-% Additional string for an index entry
-\newif\ifpy@usingsubitem\py@usingsubitemfalse
-\newcommand{\py@indexsubitem}{}
-\newcommand{\setindexsubitem}[1]{\renewcommand{\py@indexsubitem}{ #1}%
- \py@usingsubitemtrue}
-\newcommand{\ttindex}[1]{%
- \ifpy@usingsubitem
- \index{#1@{\py@idxcode{#1}}\py@indexsubitem}%
- \else%
- \index{#1@{\py@idxcode{#1}}}%
- \fi%
-}
-\newcommand{\withsubitem}[2]{%
- \begingroup%
- \def\ttindex##1{\index{##1@{\py@idxcode{##1}} #1}}%
- #2%
- \endgroup%
-}
-
-
-% Module synopsis processing -----------------------------------------------
-%
-\newcommand{\py@thisclass}{}
-\newcommand{\py@thismodule}{}
-\newcommand{\py@thismodulekey}{}
-\newcommand{\py@thismoduletype}{}
-
-\newcommand{\py@standardIndexModule}[1]{\py@modindex{#1}{standard }}
-\newcommand{\py@builtinIndexModule}[1]{\py@modindex{#1}{built-in }}
-\newcommand{\py@extensionIndexModule}[1]{\py@modindex{#1}{extension }}
-\newcommand{\py@IndexModule}[1]{\py@modindex{#1}{}}
-
-\newif\ifpy@HaveModSynopsis \py@HaveModSynopsisfalse
-\newif\ifpy@ModSynopsisFileIsOpen \py@ModSynopsisFileIsOpenfalse
-\newif\ifpy@HaveModPlatform \py@HaveModPlatformfalse
-
-% \declaremodule[key]{type}{name}
-\newcommand{\declaremodule}[3][\py@modulebadkey]{
- \py@openModSynopsisFile
- \renewcommand{\py@thismoduletype}{#2}
- \ifx\py@modulebadkey#1
- \renewcommand{\py@thismodulekey}{#3}
- \else
- \renewcommand{\py@thismodulekey}{#1}
- \fi
- \@ifundefined{py@#2IndexModule}{%
- \typeout{*** MACRO declaremodule called with unknown module type: `#2'}
- \py@IndexModule{#3}%
- }{%
- \csname py@#2IndexModule\endcsname{#3}%
- }
- \label{module-\py@thismodulekey}
-}
-\newif\ifpy@ModPlatformFileIsOpen \py@ModPlatformFileIsOpenfalse
-\newcommand{\py@ModPlatformFilename}{\jobname.pla}
-\newcommand{\platform}[1]{
- \ifpy@ModPlatformFileIsOpen\else
- \newwrite\py@ModPlatformFile
- \openout\py@ModPlatformFile=\py@ModPlatformFilename
- \py@ModPlatformFileIsOpentrue
- \fi
-}
-\InputIfFileExists{\jobname.pla}{}{}
-\newcommand{\py@platformof}[2][\py@modulebadkey]{%
- \ifx\py@modulebadkey#1 \def\py@key{#2}%
- \else \def\py@key{#1}%
- \fi%
- \csname py@modplat@\py@key\endcsname%
-}
-\newcommand{\ignorePlatformAnnotation}[1]{}
-
-% \moduleauthor{name}{email}
-\newcommand{\moduleauthor}[2]{}
-
-% \sectionauthor{name}{email}
-\newcommand{\sectionauthor}[2]{}
-
-
-\newcommand{\py@defsynopsis}{Module has no synopsis.}
-\newcommand{\py@modulesynopsis}{\py@defsynopsis}
-\newcommand{\modulesynopsis}[1]{
- \py@HaveModSynopsistrue
- \renewcommand{\py@modulesynopsis}{#1}
-}
-
-% define the file
-\newwrite\py@ModSynopsisFile
-
-% hacked from \addtocontents from latex.ltx:
-\long\def\py@writeModSynopsisFile#1{%
- \protected@write\py@ModSynopsisFile%
- {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
- {\string#1}%
-}
-\newcommand{\py@closeModSynopsisFile}{
- \ifpy@ModSynopsisFileIsOpen
- \closeout\py@ModSynopsisFile
- \py@ModSynopsisFileIsOpenfalse
- \fi
-}
-\newcommand{\py@openModSynopsisFile}{
- \ifpy@ModSynopsisFileIsOpen\else
- \openout\py@ModSynopsisFile=\py@ModSynopsisFilename
- \py@ModSynopsisFileIsOpentrue
- \fi
-}
-
-\newcommand{\py@ProcessModSynopsis}{
- \ifpy@HaveModSynopsis
- \py@writeModSynopsisFile{\modulesynopsis%
- {\py@thismodulekey}{\py@thismodule}%
- {\py@thismoduletype}{\py@modulesynopsis}}%
- \py@HaveModSynopsisfalse
- \fi
- \renewcommand{\py@modulesynopsis}{\py@defsynopsis}
-}
-\AtEndDocument{\py@ProcessModSynopsis\py@closeModSynopsisFile}
-
-
-\long\def\py@writeModPlatformFile#1{%
- \protected@write\py@ModPlatformFile%
- {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
- {\string#1}%
-}
-
-
-\newcommand{\localmoduletable}{
- \IfFileExists{\py@ModSynopsisFilename}{
- \begin{synopsistable}
- \input{\py@ModSynopsisFilename}
- \end{synopsistable}
- }{}
-}
-
-\ifpdf
- \newcommand{\py@ModSynopsisSummary}[4]{%
- \py@linkToName{label-module-#1}{\bfcode{#2}} & #4\\
- }
-\else
- \newcommand{\py@ModSynopsisSummary}[4]{\bfcode{#2} & #4\\}
-\fi
-\newenvironment{synopsistable}{
- % key, name, type, synopsis
- \let\modulesynopsis=\py@ModSynopsisSummary
- \begin{tabular}{ll}
-}{
- \end{tabular}
-}
-%
-% --------------------------------------------------------------------------
-
-
-\newcommand{\py@reset}{
- \py@usingsubitemfalse
- \py@ProcessModSynopsis
- \renewcommand{\py@thisclass}{}
- \renewcommand{\py@thismodule}{}
- \renewcommand{\py@thismodulekey}{}
- \renewcommand{\py@thismoduletype}{}
-}
-
-% Augment the sectioning commands used to get our own font family in place,
-% and reset some internal data items:
-\renewcommand{\section}{\py@reset%
- \@startsection{section}{1}{\z@}%
- {-3.5ex \@plus -1ex \@minus -.2ex}%
- {2.3ex \@plus.2ex}%
- {\reset@font\Large\py@HeaderFamily}}
-\renewcommand{\subsection}{\@startsection{subsection}{2}{\z@}%
- {-3.25ex\@plus -1ex \@minus -.2ex}%
- {1.5ex \@plus .2ex}%
- {\reset@font\large\py@HeaderFamily}}
-\renewcommand{\subsubsection}{\@startsection{subsubsection}{3}{\z@}%
- {-3.25ex\@plus -1ex \@minus -.2ex}%
- {1.5ex \@plus .2ex}%
- {\reset@font\normalsize\py@HeaderFamily}}
-\renewcommand{\paragraph}{\@startsection{paragraph}{4}{\z@}%
- {3.25ex \@plus1ex \@minus.2ex}%
- {-1em}%
- {\reset@font\normalsize\py@HeaderFamily}}
-\renewcommand{\subparagraph}{\@startsection{subparagraph}{5}{\parindent}%
- {3.25ex \@plus1ex \@minus .2ex}%
- {-1em}%
- {\reset@font\normalsize\py@HeaderFamily}}
-
-
-% Now for a lot of semantically-loaded environments that do a ton of magical
-% things to get the right formatting and index entries for the stuff in
-% Python modules and C API.
-
-
-% {fulllineitems} is used in one place in libregex.tex, but is really for
-% internal use in this file.
-%
-\newcommand{\py@itemnewline}[1]{%
- \@tempdima\linewidth%
- \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}%
-}
-
-\newenvironment{fulllineitems}{
- \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt
- \rightmargin 0pt \topsep -\parskip \partopsep \parskip
- \itemsep -\parsep
- \let\makelabel=\py@itemnewline}
-}{\end{list}}
-
-% \optional is mostly for use in the arguments parameters to the various
-% {*desc} environments defined below, but may be used elsewhere. Known to
-% be used in the debugger chapter.
-%
-% Typical usage:
-%
-% \begin{funcdesc}{myfunc}{reqparm\optional{, optparm}}
-% ^^^ ^^^
-% No space here No space here
-%
-% When a function has multiple optional parameters, \optional should be
-% nested, not chained. This is right:
-%
-% \begin{funcdesc}{myfunc}{\optional{parm1\optional{, parm2}}}
-%
-\let\py@badkey=\@undefined
-
-\newcommand{\optional}[1]{%
- {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
-
-% This can be used when a function or method accepts an varying number
-% of arguments, such as by using the *args syntax in the parameter list.
-\newcommand{\py@moreargs}{...}
-
-% This can be used when you don't want to document the parameters to a
-% function or method, but simply state that it's an alias for
-% something else.
-\newcommand{\py@unspecified}{...}
-
-
-\newlength{\py@argswidth}
-\newcommand{\py@sigparams}[1]{%
- \parbox[t]{\py@argswidth}{\py@varvars{#1}\code{)}}}
-\newcommand{\py@sigline}[2]{%
- \settowidth{\py@argswidth}{#1\code{(}}%
- \addtolength{\py@argswidth}{-2\py@argswidth}%
- \addtolength{\py@argswidth}{\textwidth}%
- \item[#1\code{(}\py@sigparams{#2}]}
-
-% C functions ------------------------------------------------------------
-% \begin{cfuncdesc}[refcount]{type}{name}{arglist}
-% Note that the [refcount] slot should only be filled in by
-% tools/anno-api.py; it pulls the value from the refcounts database.
-\newcommand{\cfuncline}[3]{
- \py@sigline{\code{#1 \bfcode{#2}}}{#3}%
- \index{#2@{\py@idxcode{#2()}}}
-}
-\newenvironment{cfuncdesc}[4][\py@badkey]{
- \begin{fulllineitems}
- \cfuncline{#2}{#3}{#4}
- \ifx\@undefined#1\relax\else%
- \emph{Return value: \textbf{#1}.}\\
- \fi
-}{\end{fulllineitems}}
-
-% C variables ------------------------------------------------------------
-% \begin{cvardesc}{type}{name}
-\newenvironment{cvardesc}[2]{
- \begin{fulllineitems}
- \item[\code{#1 \bfcode{#2}}\index{#2@{\py@idxcode{#2}}}]
-}{\end{fulllineitems}}
-
-% C data types -----------------------------------------------------------
-% \begin{ctypedesc}[index name]{typedef name}
-\newenvironment{ctypedesc}[2][\py@badkey]{
- \begin{fulllineitems}
- \item[\bfcode{#2}%
- \ifx\@undefined#1\relax%
- \index{#2@{\py@idxcode{#2}} (C type)}
- \else%
- \index{#2@{\py@idxcode{#1}} (C type)}
- \fi]
-}{\end{fulllineitems}}
-
-% C type fields ----------------------------------------------------------
-% \begin{cmemberdesc}{container type}{ctype}{membername}
-\newcommand{\cmemberline}[3]{
- \item[\code{#2 \bfcode{#3}}]
- \index{#3@{\py@idxcode{#3}} (#1 member)}
-}
-\newenvironment{cmemberdesc}[3]{
- \begin{fulllineitems}
- \cmemberline{#1}{#2}{#3}
-}{\end{fulllineitems}}
-
-% Funky macros -----------------------------------------------------------
-% \begin{csimplemacrodesc}{name}
-% -- "simple" because it has no args; NOT for constant definitions!
-\newenvironment{csimplemacrodesc}[1]{
- \begin{fulllineitems}
- \item[\bfcode{#1}\index{#1@{\py@idxcode{#1}} (macro)}]
-}{\end{fulllineitems}}
-
-% simple functions (not methods) -----------------------------------------
-% \begin{funcdesc}{name}{args}
-\newcommand{\funcline}[2]{%
- \funclineni{#1}{#2}%
- \index{#1@{\py@idxcode{#1()}} (in module \py@thismodule)}}
-\newenvironment{funcdesc}[2]{
- \begin{fulllineitems}
- \funcline{#1}{#2}
-}{\end{fulllineitems}}
-
-% similar to {funcdesc}, but doesn't add to the index
-\newcommand{\funclineni}[2]{%
- \py@sigline{\bfcode{#1}}{#2}}
-\newenvironment{funcdescni}[2]{
- \begin{fulllineitems}
- \funclineni{#1}{#2}
-}{\end{fulllineitems}}
-
-% classes ----------------------------------------------------------------
-% \begin{classdesc}{name}{constructor args}
-\newenvironment{classdesc}[2]{
- % Using \renewcommand doesn't work for this, for unknown reasons:
- \global\def\py@thisclass{#1}
- \begin{fulllineitems}
- \py@sigline{\strong{class }\bfcode{#1}}{#2}%
- \index{#1@{\py@idxcode{#1}} (class in \py@thismodule)}
-}{\end{fulllineitems}}
-
-% \begin{classdesc*}{name}
-\newenvironment{classdesc*}[1]{
- % Using \renewcommand doesn't work for this, for unknown reasons:
- \global\def\py@thisclass{#1}
- \begin{fulllineitems}
- \item[\strong{class }\code{\bfcode{#1}}%
- \index{#1@{\py@idxcode{#1}} (class in \py@thismodule)}]
-}{\end{fulllineitems}}
-
-% \begin{excclassdesc}{name}{constructor args}
-% but indexes as an exception
-\newenvironment{excclassdesc}[2]{
- % Using \renewcommand doesn't work for this, for unknown reasons:
- \global\def\py@thisclass{#1}
- \begin{fulllineitems}
- \py@sigline{\strong{exception }\bfcode{#1}}{#2}%
- \index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}
-}{\end{fulllineitems}}
-
-% There is no corresponding {excclassdesc*} environment. To describe
-% a class exception without parameters, use the {excdesc} environment.
-
-
-\let\py@classbadkey=\@undefined
-
-% object method ----------------------------------------------------------
-% \begin{methoddesc}[classname]{methodname}{args}
-\newcommand{\methodline}[3][\@undefined]{
- \methodlineni{#2}{#3}
- \ifx\@undefined#1\relax
- \index{#2@{\py@idxcode{#2()}} (\py@thisclass\ method)}
- \else
- \index{#2@{\py@idxcode{#2()}} (#1 method)}
- \fi
-}
-\newenvironment{methoddesc}[3][\@undefined]{
- \begin{fulllineitems}
- \ifx\@undefined#1\relax
- \methodline{#2}{#3}
- \else
- \def\py@thisclass{#1}
- \methodline{#2}{#3}
- \fi
-}{\end{fulllineitems}}
-
-% similar to {methoddesc}, but doesn't add to the index
-% (never actually uses the optional argument)
-\newcommand{\methodlineni}[3][\py@classbadkey]{%
- \py@sigline{\bfcode{#2}}{#3}}
-\newenvironment{methoddescni}[3][\py@classbadkey]{
- \begin{fulllineitems}
- \methodlineni{#2}{#3}
-}{\end{fulllineitems}}
-
-% object data attribute --------------------------------------------------
-% \begin{memberdesc}[classname]{membername}
-\newcommand{\memberline}[2][\py@classbadkey]{%
- \ifx\@undefined#1\relax
- \memberlineni{#2}
- \index{#2@{\py@idxcode{#2}} (\py@thisclass\ attribute)}
- \else
- \memberlineni{#2}
- \index{#2@{\py@idxcode{#2}} (#1 attribute)}
- \fi
-}
-\newenvironment{memberdesc}[2][\py@classbadkey]{
- \begin{fulllineitems}
- \ifx\@undefined#1\relax
- \memberline{#2}
- \else
- \def\py@thisclass{#1}
- \memberline{#2}
- \fi
-}{\end{fulllineitems}}
-
-% similar to {memberdesc}, but doesn't add to the index
-% (never actually uses the optional argument)
-\newcommand{\memberlineni}[2][\py@classbadkey]{\item[\bfcode{#2}]}
-\newenvironment{memberdescni}[2][\py@classbadkey]{
- \begin{fulllineitems}
- \memberlineni{#2}
-}{\end{fulllineitems}}
-
-% For exceptions: --------------------------------------------------------
-% \begin{excdesc}{name}
-% -- for constructor information, use excclassdesc instead
-\newenvironment{excdesc}[1]{
- \begin{fulllineitems}
- \item[\strong{exception }\bfcode{#1}%
- \index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}]
-}{\end{fulllineitems}}
-
-% Module data or constants: ----------------------------------------------
-% \begin{datadesc}{name}
-\newcommand{\dataline}[1]{%
- \datalineni{#1}\index{#1@{\py@idxcode{#1}} (data in \py@thismodule)}}
-\newenvironment{datadesc}[1]{
- \begin{fulllineitems}
- \dataline{#1}
-}{\end{fulllineitems}}
-
-% similar to {datadesc}, but doesn't add to the index
-\newcommand{\datalineni}[1]{\item[\bfcode{#1}]\nopagebreak}
-\newenvironment{datadescni}[1]{
- \begin{fulllineitems}
- \datalineni{#1}
-}{\end{fulllineitems}}
-
-% bytecode instruction ---------------------------------------------------
-% \begin{opcodedesc}{name}{var}
-% -- {var} may be {}
-\newenvironment{opcodedesc}[2]{
- \begin{fulllineitems}
- \item[\bfcode{#1}\quad\var{#2}]
-}{\end{fulllineitems}}
-
-
-\newcommand{\nodename}[1]{\label{#1}}
-
-% For these commands, use \command{} to get the typography right, not
-% {\command}. This works better with the texinfo translation.
-\newcommand{\ABC}{{\sc abc}}
-\newcommand{\UNIX}{{\sc Unix}}
-\newcommand{\POSIX}{POSIX}
-\newcommand{\ASCII}{{\sc ascii}}
-\newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}}
-\newcommand{\C}{C}
-\newcommand{\EOF}{{\sc eof}}
-\newcommand{\NULL}{\constant{NULL}}
-\newcommand{\infinity}{\ensuremath{\infty}}
-\newcommand{\plusminus}{\ensuremath{\pm}}
-
-% \guilabel{Start}
-\newcommand{\guilabel}[1]{\textsf{#1}}
-% \menuselection{Start \sub Programs \sub Python}
-\newcommand{\menuselection}[1]{\guilabel{{\def\sub{ \ensuremath{>} }#1}}}
-
-% Also for consistency: spell Python "Python", not "python"!
-
-% code is the most difficult one...
-\newcommand{\code}[1]{\textrm{\@vobeyspaces\@noligs\def\{{\char`\{}\def\}{\char`\}}\def\~{\char`\~}\def\^{\char`\^}\def\e{\char`\\}\def\${\char`\$}\def\#{\char`\#}\def\&{\char`\&}\def\%{\char`\%}%
-\texttt{#1}}}
-
-\newcommand{\bfcode}[1]{\code{\bfseries#1}} % bold-faced code font
-\newcommand{\csimplemacro}[1]{\code{#1}}
-\newcommand{\kbd}[1]{\code{#1}}
-\newcommand{\samp}[1]{`\code{#1}'}
-\newcommand{\var}[1]{%
- \ifmmode%
- \hbox{\py@defaultsize\textrm{\textit{#1\/}}}%
- \else%
- \py@defaultsize\textrm{\textit{#1\/}}%
- \fi%
-}
-\renewcommand{\emph}[1]{{\em #1}}
-\newcommand{\dfn}[1]{\emph{#1}}
-\newcommand{\strong}[1]{{\bf #1}}
-% let's experiment with a new font:
-\newcommand{\file}[1]{`\filenq{#1}'}
-\newcommand{\filenq}[1]{{\py@smallsize\textsf{\let\e=\textbackslash#1}}}
-
-% Use this def/redef approach for \url{} since hyperref defined this already,
-% but only if we actually used hyperref:
-\ifpdf
- \newcommand{\url}[1]{{%
- \py@pdfstartlink%
- attr{ /Border [0 0 0] }%
- user{%
- /Subtype/Link%
- /A<<%
- /Type/Action%
- /S/URI%
- /URI(#1)%
- >>%
- }%
- \py@LinkColor% color of the link text
- \py@smallsize\sf #1%
- \py@NormalColor% Turn it back off; these are declarative
- \pdfendlink}% and don't appear bound to the current
- }% formatting "box".
-\else
- \newcommand{\url}[1]{\mbox{\py@smallsize\textsf{#1}}}
-\fi
-\newcommand{\email}[1]{{\py@smallsize\textsf{#1}}}
-\newcommand{\newsgroup}[1]{{\py@smallsize\textsf{#1}}}
-
-\newcommand{\py@varvars}[1]{{%
- {\let\unspecified=\py@unspecified%
- \let\moreargs=\py@moreargs%
- \var{#1}}}}
-
-% I'd really like to get rid of this!
-\newif\iftexi\texifalse
-
-% This is used to get l2h to put the copyright and abstract on
-% a separate HTML page.
-\newif\ifhtml\htmlfalse
-
-
-% These should be used for all references to identifiers which are
-% used to refer to instances of specific language constructs. See the
-% names for specific semantic assignments.
-%
-% For now, don't do anything really fancy with them; just use them as
-% logical markup. This might change in the future.
-%
-\newcommand{\module}[1]{\texttt{#1}}
-\newcommand{\keyword}[1]{\texttt{#1}}
-\newcommand{\exception}[1]{\texttt{#1}}
-\newcommand{\class}[1]{\texttt{#1}}
-\newcommand{\function}[1]{\texttt{#1}}
-\newcommand{\member}[1]{\texttt{#1}}
-\newcommand{\method}[1]{\texttt{#1}}
-
-\newcommand{\pytype}[1]{#1} % built-in Python type
-
-\newcommand{\cfunction}[1]{\texttt{#1}}
-\newcommand{\ctype}[1]{\texttt{#1}} % C struct or typedef name
-\newcommand{\cdata}[1]{\texttt{#1}} % C variable, typically global
-
-\newcommand{\mailheader}[1]{{\py@smallsize\textsf{#1:}}}
-\newcommand{\mimetype}[1]{{\py@smallsize\textsf{#1}}}
-% The \! is a "negative thin space" in math mode.
-\newcommand{\regexp}[1]{%
- {\tiny$^{^\lceil}\!\!$%
- {\py@defaultsize\code{#1}}%
- $\!\rfloor\!$%
- }}
-\newcommand{\envvar}[1]{%
- #1%
- \index{#1}%
- \index{environment variables!{#1}}%
-}
-\newcommand{\makevar}[1]{#1} % variable in a Makefile
-\newcommand{\character}[1]{\samp{#1}}
-
-% constants defined in Python modules or C headers, not language constants:
-\newcommand{\constant}[1]{\code{#1}} % manifest constant, not syntactic
-
-\newcommand{\manpage}[2]{{\emph{#1}(#2)}}
-\newcommand{\pep}[1]{PEP #1\index{Python Enhancement Proposals!PEP #1}}
-\newcommand{\rfc}[1]{RFC #1\index{RFC!RFC #1}}
-\newcommand{\program}[1]{\strong{#1}}
-\newcommand{\programopt}[1]{\strong{#1}}
-% Note that \longprogramopt provides the '--'!
-\newcommand{\longprogramopt}[1]{\strong{-{}-#1}}
-
-% \ulink{link text}{URL}
-\ifpdf
- \newcommand{\ulink}[2]{{%
- % For PDF, we *should* only generate a link when the URL is absolute.
- \py@pdfstartlink%
- attr{ /Border [0 0 0] }%
- user{%
- /Subtype/Link%
- /A<<%
- /Type/Action%
- /S/URI%
- /URI(#2)%
- >>%
- }%
- \py@LinkColor% color of the link text
- #1%
- \py@NormalColor% Turn it back off; these are declarative
- \pdfendlink}% and don't appear bound to the current
- }% formatting "box".
-\else
- \newcommand{\ulink}[2]{#1}
-\fi
-
-% cited titles: \citetitle{Title of Work}
-% online: \citetitle[url-to-resource]{Title of Work}
-\ifpdf
- \newcommand{\citetitle}[2][\py@modulebadkey]{%
- \ifx\py@modulebadkey#1\emph{#2}\else\ulink{\emph{#2}}{#1}\fi%
- }
-\else
- \newcommand{\citetitle}[2][URL]{\emph{#2}}
-\fi
-
-
-
-% This version is being checked in for the historical record; it shows
-% how I've managed to get some aspects of this to work. It will not
-% be used in practice, so a subsequent revision will change things
-% again. This version has problems, but shows how to do something
-% that proved more tedious than I'd expected, so I don't want to lose
-% the example completely.
-%
-\newcommand{\grammartoken}[1]{\texttt{#1}}
-\newenvironment{productionlist}[1][\py@badkey]{
- \def\optional##1{{\Large[}##1{\Large]}}
- \def\production##1##2{\code{##1}&::=&\code{##2}\\}
- \def\productioncont##1{& &\code{##1}\\}
- \def\token##1{##1}
- \let\grammartoken=\token
- \parindent=2em
- \indent
- \begin{tabular}{lcl}
-}{%
- \end{tabular}
-}
-
-\newlength{\py@noticelength}
-
-\newcommand{\py@heavybox}{
- \setlength{\fboxrule}{2pt}
- \setlength{\fboxsep}{7pt}
- \setlength{\py@noticelength}{\linewidth}
- \addtolength{\py@noticelength}{-2\fboxsep}
- \addtolength{\py@noticelength}{-2\fboxrule}
- \setlength{\shadowsize}{3pt}
- \Sbox
- \minipage{\py@noticelength}
-}
-\newcommand{\py@endheavybox}{
- \endminipage
- \endSbox
- \fbox{\TheSbox}
-}
-
-% a 'note' is as plain as it gets:
-\newcommand{\py@noticelabel@note}{Note:}
-\newcommand{\py@noticestart@note}{}
-\newcommand{\py@noticeend@note}{}
-
-% a 'warning' gets more visible distinction:
-\newcommand{\py@noticelabel@warning}{Warning:}
-\newcommand{\py@noticestart@warning}{\py@heavybox}
-\newcommand{\py@noticeend@warning}{\py@endheavybox}
-
-\newenvironment{notice}[1][note]{
- \def\py@noticetype{#1}
- \csname py@noticestart@#1\endcsname
- \par\strong{\csname py@noticelabel@#1\endcsname}
-}{\csname py@noticeend@\py@noticetype\endcsname}
-\newcommand{\note}[1]{\strong{\py@noticelabel@note} #1}
-\newcommand{\warning}[1]{\strong{\py@noticelabel@warning} #1}
-
-% Deprecation stuff.
-% Should be extended to allow an index / list of deprecated stuff. But
-% there's a lot of stuff that needs to be done to make that automatable.
-%
-% First parameter is the release number that deprecates the feature, the
-% second is the action the should be taken by users of the feature.
-%
-% Example:
-% \deprecated{1.5.1}{Use \method{frobnicate()} instead.}
-%
-\newcommand{\deprecated}[2]{%
- \strong{Deprecated since release #1.} #2\par}
-
-% New stuff.
-% This should be used to mark things which have been added to the
-% development tree but that aren't in the release, but are documented.
-% This allows release of documentation that already includes updated
-% descriptions. Place at end of descriptor environment.
-%
-% Example:
-% \versionadded{1.5.2}
-% \versionchanged[short explanation]{2.0}
-%
-\newcommand{\versionadded}[2][\py@badkey]{%
- \ifx\@undefined#1\relax%
- { New in version #2. }%
- \else%
- { New in version #2:\ #1. }%
- \fi%
-}
-\newcommand{\versionchanged}[2][\py@badkey]{%
- \ifx\@undefined#1\relax%
- { Changed in version #2. }%
- \else%
- { Changed in version #2:\ #1. }%
- \fi%
-}
-
-
-% Tables.
-%
-\newenvironment{tableii}[4]{%
- \begin{center}%
- \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}%
- \begin{tabular}{#1}\strong{#3}&\strong{#4} \\* \hline%
-}{%
- \end{tabular}%
- \end{center}%
-}
-
-\newenvironment{longtableii}[4]{%
- \begin{center}%
- \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}%
- \begin{longtable}[c]{#1}\strong{#3}&\strong{#4} \\* \hline\endhead%
-}{%
- \end{longtable}%
- \end{center}%
-}
-
-\newenvironment{tableiii}[5]{%
- \begin{center}%
- \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}%
- \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5} \\%
- \hline%
-}{%
- \end{tabular}%
- \end{center}%
-}
-
-\newenvironment{longtableiii}[5]{%
- \begin{center}%
- \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}%
- \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5} \\%
- \hline\endhead%
-}{%
- \end{longtable}%
- \end{center}%
-}
-
-\newenvironment{tableiv}[6]{%
- \begin{center}%
- \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}%
- \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6} \\%
- \hline%
-}{%
- \end{tabular}%
- \end{center}%
-}
-
-\newenvironment{longtableiv}[6]{%
- \begin{center}%
- \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}%
- \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}%
- \\%
- \hline\endhead%
-}{%
- \end{longtable}%
- \end{center}%
-}
-
-\newenvironment{tablev}[7]{%
- \begin{center}%
- \def\linev##1##2##3##4##5{\csname#2\endcsname{##1}&##2&##3&##4&##5\\}%
- \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}&\strong{#7} \\%
- \hline%
-}{%
- \end{tabular}%
- \end{center}%
-}
-
-\newenvironment{longtablev}[7]{%
- \begin{center}%
- \def\linev##1##2##3##4##5{\csname#2\endcsname{##1}&##2&##3&##4&##5\\}%
- \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}&\strong{#7}%
- \\%
- \hline\endhead%
-}{%
- \end{longtable}%
- \end{center}%
-}
-
-% XXX Don't think we can use this yet, though it cleans up some
-% tedious markup. There's no equivalent for the HTML transform yet,
-% and that needs to exist. I don't know how to write it.
-%
-% This should really have something that makes it easier to bind a
-% table's ``Notes'' column and an associated tablenotes environment,
-% and generates the right magic for getting the numbers right in the
-% table.
-%
-% So this is quite incomplete.
-%
-\newcounter{py@tablenotescounter}
-\newenvironment{tablenotes}{%
- \noindent Notes:
- \par
- \setcounter{py@tablenotescounter}{0}
- \begin{list}{(\arabic{py@tablenotescounter})}%
- {\usecounter{py@tablenotescounter}}
-}{\end{list}}
-
-
-% Cross-referencing (AMK, new impl. FLD)
-% Sample usage:
-% \begin{seealso}
-% \seemodule{rand}{Uniform random number generator.}; % Module xref
-% \seetext{\emph{Encyclopedia Britannica}}. % Ref to a book
-%
-% % A funky case: module name contains '_'; have to supply an optional key
-% \seemodule[copyreg]{copy_reg}{Interface constructor registration for
-% \module{pickle}.}
-% \end{seealso}
-%
-% Note that the last parameter for \seemodule and \seetext should be complete
-% sentences and be terminated with the proper punctuation.
-
-\ifpdf
- \newcommand{\py@seemodule}[3][\py@modulebadkey]{%
- \par%
- \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
- \begin{fulllineitems}
- \item[\py@linkToName{label-module-\py@modulekey}{Module \module{#2}}
- (section \ref{module-\py@modulekey}):]
- #3
- \end{fulllineitems}
- }
-\else
- \newcommand{\py@seemodule}[3][\py@modulebadkey]{%
- \par%
- \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
- \begin{fulllineitems}
- \item[Module \module{#2} (section \ref{module-\py@modulekey}):]
- #3
- \end{fulllineitems}
- }
-\fi
-
-% \seelink{url}{link text}{why it's interesting}
-\newcommand{\py@seelink}[3]{%
- \par
- \begin{fulllineitems}
- \item[\ulink{#2}{#1}]
- #3
- \end{fulllineitems}
-}
-% \seetitle[url]{title}{why it's interesting}
-\newcommand{\py@seetitle}[3][\py@modulebadkey]{%
- \par
- \begin{fulllineitems}
- \item[\citetitle{#2}]
- \ifx\py@modulebadkey#1\else
- \item[{\small{(\url{#1})}}]
- \fi
- #3
- \end{fulllineitems}
-}
-% \seepep{number}{title}{why it's interesting}
-\newcommand{\py@seepep}[3]{%
- \par%
- \begin{fulllineitems}
- \item[\pep{#1}, ``\emph{#2}'']
- #3
- \end{fulllineitems}
-}
-% \seerfc{number}{title}{why it's interesting}
-\newcommand{\py@seerfc}[3]{%
- \par%
- \begin{fulllineitems}
- \item[\rfc{#1}, ``\emph{#2}'']
- #3
- \end{fulllineitems}
-}
-% \seeurl{url}{why it's interesting}
-\newcommand{\py@seeurl}[2]{%
- \par%
- \begin{fulllineitems}
- \item[\url{#1}]
- #2
- \end{fulllineitems}
-}
-
-\newenvironment{seealso*}{
- \par
- \def\seetext##1{\par{##1}}
- \let\seemodule=\py@seemodule
- \let\seepep=\py@seepep
- \let\seerfc=\py@seerfc
- \let\seetitle=\py@seetitle
- \let\seeurl=\py@seeurl
- \let\seelink=\py@seelink
-}{\par}
-\newenvironment{seealso}{
- \par
- \strong{See Also:}
- \par
- \def\seetext##1{\par{##1}}
- \let\seemodule=\py@seemodule
- \let\seepep=\py@seepep
- \let\seerfc=\py@seerfc
- \let\seetitle=\py@seetitle
- \let\seeurl=\py@seeurl
- \let\seelink=\py@seelink
-}{\par}
-
-% Allow the Python release number to be specified independently of the
-% \date{}. This allows the date to reflect the document's date and
-% release to specify the Python release that is documented.
-%
-\newcommand{\py@release}{}
-\newcommand{\version}{}
-\newcommand{\shortversion}{}
-\newcommand{\releaseinfo}{}
-\newcommand{\releasename}{Release}
-\newcommand{\release}[1]{%
- \renewcommand{\py@release}{\releasename\space\version}%
- \renewcommand{\version}{#1}}
-\newcommand{\setshortversion}[1]{%
- \renewcommand{\shortversion}{#1}}
-\newcommand{\setreleaseinfo}[1]{%
- \renewcommand{\releaseinfo}{#1}}
-
-% Allow specification of the author's address separately from the
-% author's name. This can be used to format them differently, which
-% is a good thing.
-%
-\newcommand{\py@authoraddress}{}
-\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
-\let\developersaddress=\authoraddress
-\let\developer=\author
-\let\developers=\author
-
-% This sets up the fancy chapter headings that make the documents look
-% at least a little better than the usual LaTeX output.
-%
-\@ifundefined{ChTitleVar}{}{
- \ChNameVar{\raggedleft\normalsize\py@HeaderFamily}
- \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily}
- \ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily}
- % This creates chapter heads without the leading \vspace*{}:
- \def\@makechapterhead#1{%
- {\parindent \z@ \raggedright \normalfont
- \ifnum \c@secnumdepth >\m@ne
- \DOCH
- \fi
- \interlinepenalty\@M
- \DOTI{#1}
- }
- }
-}
-
-
-% Definition lists; requested by AMK for HOWTO documents. Probably useful
-% elsewhere as well, so keep in in the general style support.
-%
-\newenvironment{definitions}{%
- \begin{description}%
- \def\term##1{\item[##1]\mbox{}\\*[0mm]}
-}{%
- \end{description}%
-}
-
-% Tell TeX about pathological hyphenation cases:
-\hyphenation{Base-HTTP-Re-quest-Hand-ler}
diff --git a/Doc/texinputs/underscore.sty b/Doc/texinputs/underscore.sty
deleted file mode 100644
index a274b39..0000000
--- a/Doc/texinputs/underscore.sty
+++ /dev/null
@@ -1,232 +0,0 @@
-% underscore.sty 12-Oct-2001 Donald Arseneau asnd@triumf.ca
-% Make the "_" character print as "\textunderscore" in text.
-% Copyright 1998,2001 Donald Arseneau; Distribute freely if unchanged.
-% Instructions follow after the definitions.
-
-\ProvidesPackage{underscore}[2001/10/12]
-
-\begingroup
- \catcode`\_=\active
- \gdef_{% \relax % No relax gives a small vulnerability in alignments
- \ifx\if@safe@actives\iftrue % must be outermost test!
- \string_%
- \else
- \ifx\protect\@typeset@protect
- \ifmmode \sb \else \BreakableUnderscore \fi
- \else
- \ifx\protect\@unexpandable@protect \noexpand_%
- \else \protect_%
- \fi\fi
- \fi}
-\endgroup
-
-% At begin: set catcode; fix \long \ttdefault so I can use it in comparisons;
-\AtBeginDocument{%
- {\immediate\write\@auxout{\catcode\number\string`\_ \string\active}}%
- \catcode\string`\_\string=\active
- \edef\ttdefault{\ttdefault}%
-}
-
-\newcommand{\BreakableUnderscore}{\leavevmode\nobreak\hskip\z@skip
- \ifx\f@family\ttdefault \string_\else \textunderscore\fi
- \usc@dischyph\nobreak\hskip\z@skip}
-
-\DeclareRobustCommand{\_}{%
- \ifmmode \nfss@text{\textunderscore}\else \BreakableUnderscore \fi}
-
-\let\usc@dischyph\@dischyph
-\DeclareOption{nohyphen}{\def\usc@dischyph{\discretionary{}{}{}}}
-\DeclareOption{strings}{\catcode`\_=\active}
-
-\ProcessOptions
-\ifnum\catcode`\_=\active\else \endinput \fi
-
-%%%%%%%% Redefine commands that use character strings %%%%%%%%
-
-\@ifundefined{UnderscoreCommands}{\let\UnderscoreCommands\@empty}{}
-\expandafter\def\expandafter\UnderscoreCommands\expandafter{%
- \UnderscoreCommands
- \do\include \do\includeonly
- \do\@input \do\@iinput \do\InputIfFileExists
- \do\ref \do\pageref \do\newlabel
- \do\bibitem \do\@bibitem \do\cite \do\nocite \do\bibcite
-}
-
-% Macro to redefine a macro to pre-process its string argument
-% with \protect -> \string.
-\def\do#1{% Avoid double processing if user includes command twice!
- \@ifundefined{US\string_\expandafter\@gobble\string#1}{%
- \edef\@tempb{\meaning#1}% Check if macro is just a protection shell...
- \def\@tempc{\protect}%
- \edef\@tempc{\meaning\@tempc\string#1\space\space}%
- \ifx\@tempb\@tempc % just a shell: hook into the protected inner command
- \expandafter\do
- \csname \expandafter\@gobble\string#1 \expandafter\endcsname
- \else % Check if macro takes an optional argument
- \def\@tempc{\@ifnextchar[}%
- \edef\@tempa{\def\noexpand\@tempa####1\meaning\@tempc}%
- \@tempa##2##3\@tempa{##2\relax}%
- \edef\@tempb{\meaning#1\meaning\@tempc}%
- \edef\@tempc{\noexpand\@tempd \csname
- US\string_\expandafter\@gobble\string#1\endcsname}%
- \if \expandafter\@tempa\@tempb \relax 12\@tempa % then no optional arg
- \@tempc #1\US@prot
- \else % There is optional arg
- \@tempc #1\US@protopt
- \fi
- \fi
- }{}}
-
-\def\@tempd#1#2#3{\let#1#2\def#2{#3#1}}
-
-\def\US@prot#1#2{\let\@@protect\protect \let\protect\string
- \edef\US@temp##1{##1{#2}}\restore@protect\US@temp#1}
-\def\US@protopt#1{\@ifnextchar[{\US@protarg#1}{\US@prot#1}}
-\def\US@protarg #1[#2]{\US@prot{{#1[#2]}}}
-
-\UnderscoreCommands
-\let\do\relax \let\@tempd\relax % un-do
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\endinput
-
-underscore.sty 12-Oct-2001 Donald Arseneau
-
-Features:
-~~~~~~~~~
-\_ prints an underscore so that the hyphenation of constituent words
-is not affected and hyphenation is permitted after the underscore.
-For example, "compound\_fracture" hyphenates as com- pound_- frac- ture.
-If you prefer the underscore to break without a hyphen (but still with
-the same rules for explicit hyphen-breaks) then use the [nohyphen]
-package option.
-
-A simple _ acts just like \_ in text mode, but makes a subscript in
-math mode: activation_energy $E_a$
-
-Both forms use an underscore character if the font encoding contains
-one (e.g., "\usepackage[T1]{fontenc}" or typewriter fonts in any encoding),
-but they use a rule if the there is no proper character.
-
-Deficiencies:
-~~~~~~~~~~~~~
-The skips and penalties ruin any kerning with the underscore character
-(when a character is used). However, there doesn't seem to be much, if
-any, such kerning in the ec fonts, and there is never any kerning with
-a rule.
-
-You must avoid "_" in file names and in cite or ref tags, or you must use
-the babel package, with its active-character controls, or you must give
-the [strings] option, which attempts to redefine several commands (and
-may not work perfectly). Even without the [strings] option or babel, you
-can use occasional underscores like: "\include{file\string_name}".
-
-Option: [strings]
-~~~~~~~~~~~~~~~~~
-The default operation is quite simple and needs no customization; but
-you must avoid using "_" in any place where LaTeX uses an argument as
-a string of characters for some control function or as a name. These
-include the tags for \cite and \ref, file names for \input, \include,
-and \includegraphics, environment names, counter names, and placement
-parameters (like "[t]"). The problem with these contexts is that they
-are `moving arguments' but LaTeX does not `switch on' the \protect
-mechanism for them.
-
-If you need to use the underscore character in these places, the package
-option [strings] is provided to redefine commands taking a string argument
-so that the argument is protected (with \protect -> \string). The list
-of commands is given in "\UnderscoreCommands", with "\do" before each,
-covering \cite, \ref, \input, and their variants. Not included are many
-commands regarding font names, everything with counter names, environment
-names, page styles, and versions of \ref and \cite defined by external
-packages (e.g. \vref and \citeyear).
-
-You can add to the list of supported commands by defining \UnderscoreCommands
-before loading this package; e.g.
-
- \usepackage{chicago}
- \newcommand{\UnderscoreCommands}{% (\cite already done)
- \do\citeNP \do\citeA \do\citeANP \do\citeN \do\shortcite
- \do\shortciteNP \do\shortciteA \do\shortciteANP \do\shortciteN
- \do\citeyear \do\citeyearNP
- }
- \usepackage[strings]{underscore}
-
-Not all commands can be supported this way! Only commands that take a
-string argument *first* can be protected. One optional argument before
-the string argument is also permitted, as exemplified by \cite: both
-\cite{tags} and \cite[text]{tags} are allowed. A command like
-\@addtoreset which takes two counter names as arguments could not
-be protected by adding it to \UnderscoreCommands.
-
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-!! When you use the [strings] option, you must load this package !!
-!! last (or nearly last). !!
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-
-There are two reasons: 1) The redefinitions done for protection must come
-after other packages define their customized versions of those commands.
-2) The [strings] option requires the _ character to be activated immediately
-in order for the cite and ref tags to be read properly from the .aux file
-as plain strings, and this catcode setting might disrupt other packages.
-
-The babel package implements a protection mechanism for many commands,
-and will be a complete fix for most documents without the [strings] option.
-Many add-on packages are compatible with babel, so they will get the
-strings protection also. However, there are several commands that are
-not covered by babel, but can easily be supported by the [strings] and
-\UnderscoreCommands mechanism. Beware that using both [strings] and babel
-may lead to conflicts, but does appear to work (load babel last).
-
-Implementation Notes:
-~~~~~~~~~~~~~~~~~~~~~
-The first setting of "_" to be an active character is performed in a local
-group so as to not interfere with other packages. The catcode setting
-is repeated with \AtBeginDocument so the definition is in effect for the
-text. However, the catcode setting is repeated immediately when the
-[strings] option is detected.
-
-The definition of the active "_" is essentially:
- \ifmmode \sb \else \BreakableUnderscore \fi
-where "\sb" retains the normal subscript meaning of "_" and where
-"\BreakableUnderscore" is essentially "\_". The rest of the definition
-handles the "\protect"ion without causing \relax to be inserted before
-the character.
-
-\BreakableUnderscore uses "\nobreak\hskip\z@skip" to separate the
-underscore from surrounding words, thus allowing TeX to hyphenate them,
-but preventing free breaks around the underscore. Next, it checks the
-current font family, and uses the underscore character from tt fonts or
-otherwise \textunderscore (which is a character or rule depending on
-the font encoding). After the underscore, it inserts a discretionary
-hyphenation point as "\usc@dischyph", which is usually just "\-"
-except that it still works in the tabbing environment, although it
-will give "\discretionary{}{}{}" under the [nohyphen] option. After
-that, another piece of non-breaking interword glue is inserted.
-Ordinarily, the comparison "\ifx\f@family\ttdefault" will always fail
-because \ttdefault is `long' where \f@family is not (boooo hisss), but
-\ttdefault is redefined to be non-long by "\AtBeginDocument".
-
-The "\_" command is then defined to use "\BreakableUnderscore".
-
-If the [strings] option is not given, then that is all!
-
-Under the [strings] option, the list of special commands is processed to:
-- retain the original command as \US_command (\US_ref)
-- redefine the command as \US@prot\US_command for ordinary commands
- (\ref -> \US@prot\US_ref) or as \US@protopt\US_command when an optional
- argument is possible (\bibitem -> \US@protopt\US_bibitem).
-- self-protecting commands (\cite) retain their self-protection.
-Diagnosing the state of the pre-existing command is done by painful
-contortions involving \meaning.
-
-\US@prot and \US@protopt read the argument, process it with \protect
-enabled, then invoke the saved \US_command.
-
-Modifications:
-~~~~~~~~~~~~~~
-12-Oct-2001 Babel (safe@actives) compatibility and [nohyphen] option.
-
-Test file integrity: ASCII 32-57, 58-126: !"#$%&'()*+,-./0123456789
-:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~
diff --git a/Doc/tools/anno-api.py b/Doc/tools/anno-api.py
deleted file mode 100755
index b4b7f79..0000000
--- a/Doc/tools/anno-api.py
+++ /dev/null
@@ -1,71 +0,0 @@
-#! /usr/bin/env python
-"""Add reference count annotations to the Python/C API Reference."""
-__version__ = '$Revision$'
-
-import getopt
-import os
-import sys
-
-import refcounts
-
-
-PREFIX_1 = r"\begin{cfuncdesc}{PyObject*}{"
-PREFIX_2 = r"\begin{cfuncdesc}{PyVarObject*}{"
-
-
-def main():
- rcfile = os.path.join(os.path.dirname(refcounts.__file__), os.pardir,
- "api", "refcounts.dat")
- outfile = "-"
- opts, args = getopt.getopt(sys.argv[1:], "o:r:", ["output=", "refcounts="])
- for opt, arg in opts:
- if opt in ("-o", "--output"):
- outfile = arg
- elif opt in ("-r", "--refcounts"):
- rcfile = arg
- rcdict = refcounts.load(rcfile)
- if outfile == "-":
- output = sys.stdout
- else:
- output = open(outfile, "w")
- if not args:
- args = ["-"]
- for infile in args:
- if infile == "-":
- input = sys.stdin
- else:
- input = open(infile)
- while 1:
- line = input.readline()
- if not line:
- break
- prefix = None
- if line.startswith(PREFIX_1):
- prefix = PREFIX_1
- elif line.startswith(PREFIX_2):
- prefix = PREFIX_2
- if prefix:
- s = line[len(prefix):].split('}', 1)[0]
- try:
- info = rcdict[s]
- except KeyError:
- sys.stderr.write("No refcount data for %s\n" % s)
- else:
- if info.result_type in ("PyObject*", "PyVarObject*"):
- if info.result_refs is None:
- rc = "Always \NULL{}"
- else:
- rc = info.result_refs and "New" or "Borrowed"
- rc = rc + " reference"
- line = (r"\begin{cfuncdesc}[%s]{%s}{"
- % (rc, info.result_type)) \
- + line[len(prefix):]
- output.write(line)
- if infile != "-":
- input.close()
- if outfile != "-":
- output.close()
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/buildindex.py b/Doc/tools/buildindex.py
deleted file mode 100755
index 0e5ba84..0000000
--- a/Doc/tools/buildindex.py
+++ /dev/null
@@ -1,397 +0,0 @@
-#! /usr/bin/env python
-
-__version__ = '$Revision$'
-
-import os.path
-import re
-import string
-import sys
-
-from xml.sax.saxutils import quoteattr
-
-
-bang_join = "!".join
-null_join = "".join
-
-REPLACEMENTS = [
- # Hackish way to deal with macros replaced with simple text
- (re.compile(r"\\ABC\b"), "ABC"),
- (re.compile(r"\\ASCII\b"), "ASCII"),
- (re.compile(r"\\Cpp\b"), "C++"),
- (re.compile(r"\\EOF\b"), "EOF"),
- (re.compile(r"\\NULL\b"), "NULL"),
- (re.compile(r"\\POSIX\b"), "POSIX"),
- (re.compile(r"\\UNIX\b"), "Unix"),
- # deal with turds left over from LaTeX2HTML
- (re.compile(r"<#\d+#>"), ""),
- ]
-
-class Node:
- continuation = 0
-
- def __init__(self, link, str, seqno):
- self.links = [link]
- self.seqno = seqno
- for pattern, replacement in REPLACEMENTS:
- str = pattern.sub(replacement, str)
- # build up the text
- self.text = split_entry_text(str)
- self.key = list(split_entry_key(str))
-
- def __eq__(self, other):
- return cmp(self, other) == 0
-
- def __lt__(self, other):
- return cmp(self, other) == -1
-
- def __gt__(self, other):
- return cmp(self, other) == 1
-
- def __cmp__(self, other):
- """Comparison operator includes sequence number, for use with
- list.sort()."""
- return self.cmp_entry(other) or cmp(self.seqno, other.seqno)
-
- def cmp_entry(self, other):
- """Comparison 'operator' that ignores sequence number."""
- c = 0
- for i in range(min(len(self.key), len(other.key))):
- c = (cmp_part(self.key[i], other.key[i])
- or cmp_part(self.text[i], other.text[i]))
- if c:
- break
- return c or cmp(self.key, other.key) or cmp(self.text, other.text)
-
- def __repr__(self):
- return "<Node for %s (%s)>" % (bang_join(self.text), self.seqno)
-
- def __str__(self):
- return bang_join(self.key)
-
- def dump(self):
- return "%s\1%s###%s\n" \
- % ("\1".join(self.links),
- bang_join(self.text),
- self.seqno)
-
-
-def cmp_part(s1, s2):
- result = cmp(s1, s2)
- if result == 0:
- return 0
- l1 = s1.lower()
- l2 = s2.lower()
- minlen = min(len(s1), len(s2))
- if len(s1) < len(s2) and l1 == l2[:len(s1)]:
- result = -1
- elif len(s2) < len(s1) and l2 == l1[:len(s2)]:
- result = 1
- else:
- result = cmp(l1, l2) or cmp(s1, s2)
- return result
-
-
-def split_entry(str, which):
- stuff = []
- parts = str.split('!')
- parts = [part.split('@') for part in parts]
- for entry in parts:
- if len(entry) != 1:
- key = entry[which]
- else:
- key = entry[0]
- stuff.append(key)
- return stuff
-
-
-_rmtt = re.compile(r"""(.*)<tt(?: class=['"][a-z0-9]+["'])?>(.*)</tt>(.*)$""",
- re.IGNORECASE)
-_rmparens = re.compile(r"\(\)")
-
-def split_entry_key(str):
- parts = split_entry(str, 1)
- for i in range(len(parts)):
- m = _rmtt.match(parts[i])
- if m:
- parts[i] = null_join(m.group(1, 2, 3))
- else:
- parts[i] = parts[i].lower()
- # remove '()' from the key:
- parts[i] = _rmparens.sub('', parts[i])
- return map(trim_ignored_letters, parts)
-
-
-def split_entry_text(str):
- if '<' in str:
- m = _rmtt.match(str)
- if m:
- str = null_join(m.group(1, 2, 3))
- return split_entry(str, 1)
-
-
-def load(fp):
- nodes = []
- rx = re.compile("(.*)\1(.*)###(.*)$")
- while 1:
- line = fp.readline()
- if not line:
- break
- m = rx.match(line)
- if m:
- link, str, seqno = m.group(1, 2, 3)
- nodes.append(Node(link, str, seqno))
- return nodes
-
-
-def trim_ignored_letters(s):
- # ignore $ to keep environment variables with the
- # leading letter from the name
- if s.startswith("$"):
- return s[1:].lower()
- else:
- return s.lower()
-
-def get_first_letter(s):
- if s.startswith("<tex2html_percent_mark>"):
- return "%"
- else:
- return trim_ignored_letters(s)[0]
-
-
-def split_letters(nodes):
- letter_groups = []
- if nodes:
- group = []
- append = group.append
- letter = get_first_letter(nodes[0].text[0])
- letter_groups.append((letter, group))
- for node in nodes:
- nletter = get_first_letter(node.text[0])
- if letter != nletter:
- letter = nletter
- group = []
- letter_groups.append((letter, group))
- append = group.append
- append(node)
- return letter_groups
-
-
-def group_symbols(groups):
- entries = []
- ident_letters = string.ascii_letters + "_"
- while groups[0][0] not in ident_letters:
- entries += groups[0][1]
- del groups[0]
- if entries:
- groups.insert(0, ("Symbols", entries))
-
-
-# need a function to separate the nodes into columns...
-def split_columns(nodes, columns=1):
- if columns <= 1:
- return [nodes]
- # This is a rough height; we may have to increase to avoid breaks before
- # a subitem.
- colheight = int(len(nodes) / columns)
- numlong = int(len(nodes) % columns)
- if numlong:
- colheight = colheight + 1
- else:
- numlong = columns
- cols = []
- for i in range(numlong):
- start = i * colheight
- end = start + colheight
- cols.append(nodes[start:end])
- del nodes[:end]
- colheight = colheight - 1
- try:
- numshort = int(len(nodes) / colheight)
- except ZeroDivisionError:
- cols = cols + (columns - len(cols)) * [[]]
- else:
- for i in range(numshort):
- start = i * colheight
- end = start + colheight
- cols.append(nodes[start:end])
- #
- # If items continue across columns, make sure they are marked
- # as continuations so the user knows to look at the previous column.
- #
- for i in range(len(cols) - 1):
- try:
- prev = cols[i][-1]
- next = cols[i + 1][0]
- except IndexError:
- return cols
- else:
- n = min(len(prev.key), len(next.key))
- for j in range(n):
- if prev.key[j] != next.key[j]:
- break
- next.continuation = j + 1
- return cols
-
-
-DL_LEVEL_INDENT = " "
-
-def format_column(nodes):
- strings = ["<dl compact='compact'>"]
- append = strings.append
- level = 0
- previous = []
- for node in nodes:
- current = node.text
- count = 0
- for i in range(min(len(current), len(previous))):
- if previous[i] != current[i]:
- break
- count = i + 1
- if count > level:
- append("<dl compact='compact'>" * (count - level) + "\n")
- level = count
- elif level > count:
- append("\n")
- append(level * DL_LEVEL_INDENT)
- append("</dl>" * (level - count))
- level = count
- # else: level == count
- for i in range(count, len(current) - 1):
- term = node.text[i]
- level = level + 1
- if node.continuation > i:
- extra = " (continued)"
- else:
- extra = ""
- append("\n<dt>%s%s\n<dd>\n%s<dl compact='compact'>"
- % (term, extra, level * DL_LEVEL_INDENT))
- append("\n%s<dt>%s%s</a>"
- % (level * DL_LEVEL_INDENT, node.links[0], node.text[-1]))
- for link in node.links[1:]:
- append(",\n%s %s[Link]</a>" % (level * DL_LEVEL_INDENT, link))
- previous = current
- append("\n")
- append("</dl>" * (level + 1))
- return null_join(strings)
-
-
-def format_nodes(nodes, columns=1):
- strings = []
- append = strings.append
- if columns > 1:
- colnos = range(columns)
- colheight = int(len(nodes) / columns)
- if len(nodes) % columns:
- colheight = colheight + 1
- colwidth = int(100 / columns)
- append('<table width="100%"><tr valign="top">')
- for col in split_columns(nodes, columns):
- append('<td width="%d%%">\n' % colwidth)
- append(format_column(col))
- append("\n</td>")
- append("\n</tr></table>")
- else:
- append(format_column(nodes))
- return null_join(strings)
-
-
-def format_letter(letter):
- if letter == '.':
- lettername = ". (dot)"
- elif letter == '_':
- lettername = "_ (underscore)"
- else:
- lettername = letter.capitalize()
- return "\n<hr />\n<h2 id=%s>%s</h2>\n\n" \
- % (quoteattr("letter-" + letter), lettername)
-
-
-def format_html_letters(nodes, columns, group_symbol_nodes):
- letter_groups = split_letters(nodes)
- if group_symbol_nodes:
- group_symbols(letter_groups)
- items = []
- for letter, nodes in letter_groups:
- s = "<b><a href=\"#letter-%s\">%s</a></b>" % (letter, letter)
- items.append(s)
- s = ["<hr /><center>\n%s</center>\n" % " |\n".join(items)]
- for letter, nodes in letter_groups:
- s.append(format_letter(letter))
- s.append(format_nodes(nodes, columns))
- return null_join(s)
-
-def format_html(nodes, columns):
- return format_nodes(nodes, columns)
-
-
-def collapse(nodes):
- """Collapse sequences of nodes with matching keys into a single node.
- Destructive."""
- if len(nodes) < 2:
- return
- prev = nodes[0]
- i = 1
- while i < len(nodes):
- node = nodes[i]
- if not node.cmp_entry(prev):
- prev.links.append(node.links[0])
- del nodes[i]
- else:
- i = i + 1
- prev = node
-
-
-def dump(nodes, fp):
- for node in nodes:
- fp.write(node.dump())
-
-
-def process_nodes(nodes, columns, letters=0, group_symbol_nodes=0):
- nodes.sort()
- collapse(nodes)
- if letters:
- return format_html_letters(nodes, columns, group_symbol_nodes)
- else:
- return format_html(nodes, columns)
-
-
-def main():
- import getopt
- ifn = "-"
- ofn = "-"
- columns = 1
- letters = 0
- group_symbol_nodes = 1
- opts, args = getopt.getopt(sys.argv[1:], "c:lo:",
- ["columns=", "dont-group-symbols",
- "group-symbols", "letters", "output="])
- for opt, val in opts:
- if opt in ("-o", "--output"):
- ofn = val
- elif opt in ("-c", "--columns"):
- columns = int(val, 10)
- elif opt in ("-l", "--letters"):
- letters = 1
- elif opt == "--group-symbols":
- group_symbol_nodes = 1
- elif opt == "--dont-group-symbols":
- group_symbol_nodes = 0
- if not args:
- args = [ifn]
- nodes = []
- for fn in args:
- nodes = nodes + load(open(fn))
- num_nodes = len(nodes)
- html = process_nodes(nodes, columns, letters, group_symbol_nodes)
- program = os.path.basename(sys.argv[0])
- if ofn == "-":
- sys.stdout.write(html)
- sys.stderr.write("\n%s: %d index nodes" % (program, num_nodes))
- else:
- open(ofn, "w").write(html)
- print()
- print("%s: %d index nodes" % (program, num_nodes))
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/checkargs.pm b/Doc/tools/checkargs.pm
deleted file mode 100644
index 005d3c6..0000000
--- a/Doc/tools/checkargs.pm
+++ /dev/null
@@ -1,112 +0,0 @@
-#! /usr/bin/perl
-
-package checkargs;
-require 5.004; # uses "for my $var"
-require Exporter;
-@ISA = qw(Exporter);
-@EXPORT = qw(check_args check_args_range check_args_at_least);
-use strict;
-use Carp;
-
-=head1 NAME
-
-checkargs -- Provide rudimentary argument checking for perl5 functions
-
-=head1 SYNOPSIS
-
- check_args(cArgsExpected, @_)
- check_args_range(cArgsMin, cArgsMax, @_)
- check_args_at_least(cArgsMin, @_)
-where "@_" should be supplied literally.
-
-=head1 DESCRIPTION
-
-As the first line of user-written subroutine foo, do one of the following:
-
- my ($arg1, $arg2) = check_args(2, @_);
- my ($arg1, @rest) = check_args_range(1, 4, @_);
- my ($arg1, @rest) = check_args_at_least(1, @_);
- my @args = check_args_at_least(0, @_);
-
-These functions may also be called for side effect (put a call to one
-of the functions near the beginning of the subroutine), but using the
-argument checkers to set the argument list is the recommended usage.
-
-The number of arguments and their definedness are checked; if the wrong
-number are received, the program exits with an error message.
-
-=head1 AUTHOR
-
-Michael D. Ernst <F<mernst@cs.washington.edu>>
-
-=cut
-
-## Need to check that use of caller(1) really gives desired results.
-## Need to give input chunk information.
-## Is this obviated by Perl 5.003's declarations? Not entirely, I think.
-
-sub check_args ( $@ )
-{
- my ($num_formals, @args) = @_;
- my ($pack, $file_arg, $line_arg, $subname, $hasargs, $wantarr) = caller(1);
- if (@_ < 1) { croak "check_args needs at least 7 args, got ", scalar(@_), ": @_\n "; }
- if ((!wantarray) && ($num_formals != 0))
- { croak "check_args called in scalar context"; }
- # Can't use croak below here: it would only go out to caller, not its caller
- my $num_actuals = @args;
- if ($num_actuals != $num_formals)
- { die "$file_arg:$line_arg: function $subname expected $num_formals argument",
- (($num_formals == 1) ? "" : "s"),
- ", got $num_actuals",
- (($num_actuals == 0) ? "" : ": @args"),
- "\n"; }
- for my $index (0..$#args)
- { if (!defined($args[$index]))
- { die "$file_arg:$line_arg: function $subname undefined argument ", $index+1, ": @args[0..$index-1]\n"; } }
- return @args;
-}
-
-sub check_args_range ( $$@ )
-{
- my ($min_formals, $max_formals, @args) = @_;
- my ($pack, $file_arg, $line_arg, $subname, $hasargs, $wantarr) = caller(1);
- if (@_ < 2) { croak "check_args_range needs at least 8 args, got ", scalar(@_), ": @_"; }
- if ((!wantarray) && ($max_formals != 0) && ($min_formals !=0) )
- { croak "check_args_range called in scalar context"; }
- # Can't use croak below here: it would only go out to caller, not its caller
- my $num_actuals = @args;
- if (($num_actuals < $min_formals) || ($num_actuals > $max_formals))
- { die "$file_arg:$line_arg: function $subname expected $min_formals-$max_formals arguments, got $num_actuals",
- ($num_actuals == 0) ? "" : ": @args", "\n"; }
- for my $index (0..$#args)
- { if (!defined($args[$index]))
- { die "$file_arg:$line_arg: function $subname undefined argument ", $index+1, ": @args[0..$index-1]\n"; } }
- return @args;
-}
-
-sub check_args_at_least ( $@ )
-{
- my ($min_formals, @args) = @_;
- my ($pack, $file_arg, $line_arg, $subname, $hasargs, $wantarr) = caller(1);
- # Don't do this, because we want every sub to start with a call to check_args*
- # if ($min_formals == 0)
- # { die "Isn't it pointless to check for at least zero args to $subname?\n"; }
- if (scalar(@_) < 1)
- { croak "check_args_at_least needs at least 1 arg, got ", scalar(@_), ": @_"; }
- if ((!wantarray) && ($min_formals != 0))
- { croak "check_args_at_least called in scalar context"; }
- # Can't use croak below here: it would only go out to caller, not its caller
- my $num_actuals = @args;
- if ($num_actuals < $min_formals)
- { die "$file_arg:$line_arg: function $subname expected at least $min_formals argument",
- ($min_formals == 1) ? "" : "s",
- ", got $num_actuals",
- ($num_actuals == 0) ? "" : ": @args", "\n"; }
- for my $index (0..$#args)
- { if (!defined($args[$index]))
- { warn "$file_arg:$line_arg: function $subname undefined argument ", $index+1, ": @args[0..$index-1]\n"; last; } }
- return @args;
-}
-
-1; # successful import
-__END__
diff --git a/Doc/tools/cklatex b/Doc/tools/cklatex
deleted file mode 100755
index 396e914..0000000
--- a/Doc/tools/cklatex
+++ /dev/null
@@ -1,26 +0,0 @@
-#! /bin/sh
-# -*- ksh -*-
-
-# This script *helps* locate lines of normal content that end in '}';
-# this is useful since LaTeX2HTML (at least the old version that we
-# use) breaks on many lines that end that way.
-#
-# Usage: cklatex files... | less
-#
-# *Read* the output looking for suspicious lines!
-
-grep -n "[^ ]}\$" $@ | \
- grep -v '\\begin{' | \
- grep -v '\\end{' | \
- grep -v '\\input{' | \
- grep -v '\\documentclass{' | \
- grep -v '\\title{' | \
- grep -v '\\chapter{' | \
- grep -v '\\chapter\*{' | \
- grep -v '\\section{' | \
- grep -v '\\subsection{' | \
- grep -v '\\subsubsection{' | \
- grep -v '\\sectionauthor{' | \
- grep -v '\\moduleauthor{'
-
-exit $?
diff --git a/Doc/tools/cmpcsyms b/Doc/tools/cmpcsyms
deleted file mode 100755
index 55f9954..0000000
--- a/Doc/tools/cmpcsyms
+++ /dev/null
@@ -1,157 +0,0 @@
-#! /usr/bin/env python
-from __future__ import with_statement
-import errno
-import os
-import re
-import sys
-import string
-
-if __name__ == "__main__":
- _base = sys.argv[0]
-else:
- _base = __file__
-
-_script_home = os.path.abspath(os.path.dirname(_base))
-
-srcdir = os.path.dirname(os.path.dirname(_script_home))
-
-EXCLUDES = ["bitset.h", "cStringIO.h", "graminit.h", "grammar.h",
- "longintrepr.h", "metagrammar.h",
- "node.h", "opcode.h", "osdefs.h", "pgenheaders.h",
- "py_curses.h", "parsetok.h", "symtable.h", "token.h"]
-
-
-def list_headers():
- """Return a list of headers."""
- incdir = os.path.join(srcdir, "Include")
- return [os.path.join(incdir, fn) for fn in os.listdir(incdir)
- if fn.endswith(".h") and fn not in EXCLUDES]
-
-
-def matcher(pattern):
- return re.compile(pattern).search
-
-MATCHERS = [
- # XXX this should also deal with ctypedesc, cvardesc and cmemberdesc
- matcher(r"\\begin\{cfuncdesc\}\{(?P<result>[^}]*)\}\{(?P<sym>[^}]*)\}{(?P<params>[^}]*)\}"),
- matcher(r"\\cfuncline\{(?P<result>[^})]*)\}\{(?P<sym>[^}]*)\}{(?P<params>[^}]*)\}"),
- ]
-
-def list_documented_items():
- """Return a list of everything that's already documented."""
- apidir = os.path.join(srcdir, "Doc", "api")
- files = [fn for fn in os.listdir(apidir) if fn.endswith(".tex")]
- L = []
- for fn in files:
- fullname = os.path.join(apidir, fn)
- data = open(fullname).read()
- for matcher in MATCHERS:
- pos = 0
- while 1:
- m = matcher(data, pos)
- if not m: break
- pos = m.end()
- sym = m.group("sym")
- result = m.group("result")
- params = m.group("params")
- # replace all whitespace with a single one
- params = " ".join(params.split())
- L.append((sym, result, params, fn))
- return L
-
-def normalize_type(t):
- t = t.strip()
- s = t.rfind("*")
- if s != -1:
- # strip everything after the pointer name
- t = t[:s+1]
- # Drop the variable name
- s = t.split()
- typenames = 1
- if len(s)>1 and s[0]=='unsigned' and s[1]=='int':
- typenames = 2
- if len(s) > typenames and s[-1][0] in string.letters:
- del s[-1]
- if not s:
- print "XXX", t
- return ""
- # Drop register
- if s[0] == "register":
- del s[0]
- # discard all spaces
- return ''.join(s)
-
-def compare_type(t1, t2):
- t1 = normalize_type(t1)
- t2 = normalize_type(t2)
- if t1 == r'\moreargs' and t2 == '...':
- return False
- if t1 != t2:
- #print "different:", t1, t2
- return False
- return True
-
-
-def compare_types(ret, params, hret, hparams):
- if not compare_type(ret, hret):
- return False
- params = params.split(",")
- hparams = hparams.split(",")
- if not params and hparams == ['void']:
- return True
- if not hparams and params == ['void']:
- return True
- if len(params) != len(hparams):
- return False
- for p1, p2 in zip(params, hparams):
- if not compare_type(p1, p2):
- return False
- return True
-
-def main():
- headers = list_headers()
- documented = list_documented_items()
-
- lines = []
- for h in headers:
- data = open(h).read()
- data, n = re.subn(r"PyAPI_FUNC\(([^)]*)\)", r"\1", data)
- name = os.path.basename(h)
- with open(name, "w") as f:
- f.write(data)
- cmd = ("ctags -f - --file-scope=no --c-kinds=p --fields=S "
- "-Istaticforward -Istatichere=static " + name)
- with os.popen(cmd) as f:
- lines.extend(f.readlines())
- os.unlink(name)
- L = {}
- prevsym = None
- for line in lines:
- if not line:
- break
- sym, filename, signature = line.split(None, 2)
- if sym == prevsym:
- continue
- expr = "\^(.*)%s" % sym
- m = re.search(expr, signature)
- if not m:
- print "Could not split",signature, "using",expr
- rettype = m.group(1).strip()
- m = re.search("signature:\(([^)]*)\)", signature)
- if not m:
- print "Could not get signature from", signature
- params = m.group(1)
- L[sym] = (rettype, params)
-
- for sym, ret, params, fn in documented:
- if sym not in L:
- print "No declaration for '%s'" % sym
- continue
- hret, hparams = L[sym]
- if not compare_types(ret, params, hret, hparams):
- print "Declaration error for %s (%s):" % (sym, fn)
- print ret+": "+params
- print hret+": "+hparams
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/custlib.py b/Doc/tools/custlib.py
deleted file mode 100644
index 8224b2c..0000000
--- a/Doc/tools/custlib.py
+++ /dev/null
@@ -1,78 +0,0 @@
-# Generate custlib.tex, which is a site-specific library document.
-
-# Phase I: list all the things that can be imported
-
-import glob
-import os.path
-import sys
-
-modules = {}
-
-for modname in sys.builtin_module_names:
- modules[modname] = modname
-
-for dir in sys.path:
- # Look for *.py files
- filelist = glob.glob(os.path.join(dir, '*.py'))
- for file in filelist:
- path, file = os.path.split(file)
- base, ext = os.path.splitext(file)
- modules[base.lower()] = base
-
- # Look for shared library files
- filelist = (glob.glob(os.path.join(dir, '*.so')) +
- glob.glob(os.path.join(dir, '*.sl')) +
- glob.glob(os.path.join(dir, '*.o')) )
- for file in filelist:
- path, file = os.path.split(file)
- base, ext = os.path.splitext(file)
- if base[-6:] == 'module':
- base = base[:-6]
- modules[base.lower()] = base
-
-# Minor oddity: the types module is documented in libtypes2.tex
-if 'types' in modules:
- del modules['types']
- modules['types2'] = None
-
-# Phase II: find all documentation files (lib*.tex)
-# and eliminate modules that don't have one.
-
-docs = {}
-filelist = glob.glob('lib*.tex')
-for file in filelist:
- modname = file[3:-4]
- docs[modname] = modname
-
-mlist = list(modules.keys())
-mlist = filter(lambda x, docs=docs: x in docs, mlist)
-mlist.sort()
-mlist = map(lambda x, docs=docs: docs[x], mlist)
-
-modules = mlist
-
-# Phase III: write custlib.tex
-
-# Write the boilerplate
-# XXX should be fancied up.
-print("""\documentstyle[twoside,11pt,myformat]{report}
-\\title{Python Library Reference}
-\\input{boilerplate}
-\\makeindex % tell \\index to actually write the .idx file
-\\begin{document}
-\\pagenumbering{roman}
-\\maketitle
-\\input{copyright}
-\\begin{abstract}
-\\noindent This is a customized version of the Python Library Reference.
-\\end{abstract}
-\\pagebreak
-{\\parskip = 0mm \\tableofcontents}
-\\pagebreak\\pagenumbering{arabic}""")
-
-for modname in mlist:
- print("\\input{lib%s}" % (modname,))
-
-# Write the end
-print("""\\input{custlib.ind} % Index
-\\end{document}""")
diff --git a/Doc/tools/findcsyms b/Doc/tools/findcsyms
deleted file mode 100755
index d68c3ce..0000000
--- a/Doc/tools/findcsyms
+++ /dev/null
@@ -1,136 +0,0 @@
-#! /usr/bin/env python
-
-import errno
-import os
-import re
-import sys
-
-if __name__ == "__main__":
- _base = sys.argv[0]
-else:
- _base = __file__
-
-_script_home = os.path.abspath(os.path.dirname(_base))
-
-srcdir = os.path.dirname(os.path.dirname(_script_home))
-
-EXCLUDES = ["bitset.h", "cStringIO.h", "graminit.h", "grammar.h",
- "longintrepr.h", "metagrammar.h",
- "node.h", "opcode.h", "osdefs.h", "pgenheaders.h",
- "py_curses.h", "parsetok.h", "symtable.h", "token.h"]
-
-
-def list_headers():
- """Return a list of headers."""
- incdir = os.path.join(srcdir, "Include")
- return [fn for fn in os.listdir(incdir)
- if fn.endswith(".h") and fn not in EXCLUDES]
-
-
-def matcher(pattern):
- return re.compile(pattern).match
-
-MATCHERS = [
- matcher(r"\\begin\{cfuncdesc\}\{[^{]*\}\{(?P<sym>[^{]*)\}"),
- matcher(r"\\cfuncline\{[^{]*\}\{(?P<sym>[^{]*)\}"),
- matcher(r"\\begin\{ctypedesc\}(\[[^{]*\])?\{(?P<sym>[^{]*)\}"),
- matcher(r"\\begin\{cvardesc\}\{[^{]*\}\{(?P<sym>[^{]*)\}"),
- matcher(r"\\begin\{cmemberdesc\}\{[^{]*\}\{(?P<sym>[^{]*)\}"),
- matcher(r"\\cmemberline\{[^{]*\}\{(?P<sym>[^{]*)\}"),
- matcher(r"\\begin\{csimplemacrodesc\}\{(?P<sym>[^{]*)\}"),
- ]
-
-
-def list_documented_items():
- """Return a list of everything that's already documented."""
- apidir = os.path.join(srcdir, "Doc", "api")
- files = [fn for fn in os.listdir(apidir) if fn.endswith(".tex")]
- L = []
- for fn in files:
- fullname = os.path.join(apidir, fn)
- for line in open(fullname):
- line = line.lstrip()
- if not line.startswith("\\"):
- continue
- for matcher in MATCHERS:
- m = matcher(line)
- if m:
- L.append(m.group("sym"))
- break
- return L
-
-def split_documented(all, documented):
- """Split the list of all symbols into documented and undocumented
- categories."""
- doc = []
- undoc = []
- for t in all:
- if t[0] in documented:
- doc.append(t)
- else:
- undoc.append(t)
- return doc, undoc
-
-def print_list(L, title=None):
- """Dump a list to stdout."""
- if title:
- print title + ":"
- print "-" * (len(title) + 1)
- w = 0
- for sym, filename in L:
- w = max(w, len(sym))
- if w % 4 == 0:
- w += 4
- else:
- w += (4 - (w % 4))
- for sym, filename in L:
- print "%-*s%s" % (w, sym, filename)
-
-
-_spcjoin = ' '.join
-
-def main():
- args = sys.argv[1:]
- if args:
- headers = args
- documented = []
- else:
- os.chdir(os.path.join(srcdir, "Include"))
- headers = list_headers()
- documented = list_documented_items()
-
- cmd = ("ctags -f - --file-scope=no --c-types=dgpstux "
- "-Istaticforward -Istatichere=static "
- + _spcjoin(headers))
- fp = os.popen(cmd)
- L = []
- prevsym = None
- while 1:
- line = fp.readline()
- if not line:
- break
- sym, filename = line.split()[:2]
- if sym == prevsym:
- continue
- if not sym.endswith("_H"):
- L.append((sym, filename))
- prevsym = sym
- L.sort()
- fp.close()
-
- try:
- if documented:
- documented, undocumented = split_documented(L, documented)
- print_list(documented, "Documented symbols")
- if undocumented:
- print
- print_list(undocumented, "Undocumented symbols")
- else:
- print_list(L)
- except IOError as e:
- if e.errno != errno.EPIPE:
- raise
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/findmodrefs b/Doc/tools/findmodrefs
deleted file mode 100755
index 8c5f93f..0000000
--- a/Doc/tools/findmodrefs
+++ /dev/null
@@ -1,63 +0,0 @@
-#! /usr/bin/env python
-# -*- Python -*-
-
-import fileinput
-import getopt
-import glob
-import os
-import re
-import sys
-
-
-declare_rx = re.compile(
- r"\\declaremodule(?:\[[a-zA-Z0-9]*\]*)?{[a-zA-Z_0-9]+}{([a-zA-Z_0-9]+)}")
-
-module_rx = re.compile(r"\\module{([a-zA-Z_0-9]+)}")
-
-def main():
- try:
- just_list = 0
- print_lineno = 0
- opts, args = getopt.getopt(sys.argv[1:], "ln", ["list", "number"])
- for opt, arg in opts:
- if opt in ("-l", "--list"):
- just_list = 1
- elif opt in ("-n", "--number"):
- print_lineno = 1
- files = args
- if not files:
- files = glob.glob("*.tex")
- files.sort()
- modulename = None
- for line in fileinput.input(files):
- if line[:9] == r"\section{":
- modulename = None
- continue
- if line[:16] == r"\modulesynopsys{":
- continue
- m = declare_rx.match(line)
- if m:
- modulename = m.group(1)
- continue
- if not modulename:
- continue
- m = module_rx.search(line)
- if m:
- name = m.group(1)
- if name != modulename:
- filename = fileinput.filename()
- if just_list:
- print filename
- fileinput.nextfile()
- modulename = None
- elif print_lineno:
- print "%s(%d):%s" \
- % (filename, fileinput.filelineno(), line[:-1])
- else:
- print "%s:%s" % (filename, line[:-1])
- except KeyboardInterrupt:
- sys.exit(1)
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/findsyms b/Doc/tools/findsyms
deleted file mode 100755
index 3b0f709..0000000
--- a/Doc/tools/findsyms
+++ /dev/null
@@ -1,128 +0,0 @@
-#!/usr/bin/env python
-
-# Released to the public domain by Skip Montanaro, 28 March 2002
-
-"""
-findsyms.py - try to identify undocumented symbols exported by modules
-
-Usage: findsyms.py librefdir
-
-For each lib*.tex file in the libref manual source directory, identify which
-module is documented, import the module if possible, then search the LaTeX
-source for the symbols global to that module. Report any that don't seem to
-be documented.
-
-Certain exceptions are made to the list of undocumented symbols:
-
- * don't mention symbols in which all letters are upper case on the
- assumption they are manifest constants
-
- * don't mention symbols that are themselves modules
-
- * don't mention symbols that match those exported by os, math, string,
- types, or __builtin__ modules
-
-Finally, if a name is exported by the module but fails a getattr() lookup,
-that anomaly is reported.
-"""
-
-import __builtin__
-import getopt
-import glob
-import math
-import os
-import re
-import string
-import sys
-import types
-import warnings
-
-def usage():
- print >> sys.stderr, """
-usage: %s dir
-where 'dir' is the Library Reference Manual source directory.
-""" % os.path.basename(sys.argv[0])
-
-def main():
- try:
- opts, args = getopt.getopt(sys.argv[1:], "")
- except getopt.error:
- usage()
- return
-
- if not args:
- usage()
- return
-
- libdir = args[0]
-
- warnings.filterwarnings("error")
-
- pat = re.compile(r"\\declaremodule\s*{[^}]*}\s*{([^}]*)}")
-
- missing = []
- filelist = glob.glob(os.path.join(libdir, "lib*.tex"))
- filelist.sort()
- for f in filelist:
- mod = f[3:-4]
- if not mod: continue
- data = open(f).read()
- mods = re.findall(pat, data)
- if not mods:
- print "No module declarations found in", f
- continue
- for modname in mods:
- # skip special modules
- if modname.startswith("__"):
- continue
- try:
- mod = __import__(modname)
- except ImportError:
- missing.append(modname)
- continue
- except DeprecationWarning:
- print "Deprecated module:", modname
- continue
- if hasattr(mod, "__all__"):
- all = mod.__all__
- else:
- all = [k for k in dir(mod) if k[0] != "_"]
- mentioned = 0
- all.sort()
- for name in all:
- if data.find(name) == -1:
- # certain names are predominantly used for testing
- if name in ("main","test","_test"):
- continue
- # is it some sort of manifest constant?
- if name.upper() == name:
- continue
- try:
- item = getattr(mod, name)
- except AttributeError:
- print " ", name, "exposed, but not an attribute"
- continue
- # don't care about modules that might be exposed
- if type(item) == types.ModuleType:
- continue
- # check a few modules which tend to be import *'d
- isglobal = 0
- for m in (os, math, string, __builtin__, types):
- if hasattr(m, name) and item == getattr(m, name):
- isglobal = 1
- break
- if isglobal: continue
- if not mentioned:
- print "Not mentioned in", modname, "docs:"
- mentioned = 1
- print " ", name
- if missing:
- missing.sort()
- print "Could not import:"
- print " ", ", ".join(missing)
-
-if __name__ == "__main__":
- try:
- main()
- except KeyboardInterrupt:
- pass
diff --git a/Doc/tools/fix_hack b/Doc/tools/fix_hack
deleted file mode 100755
index 8dad111..0000000
--- a/Doc/tools/fix_hack
+++ /dev/null
@@ -1,2 +0,0 @@
-#!/bin/sh
-sed -e 's/{\\ptt[ ]*\\char[ ]*'"'"'137}/_/g' <"$1" > "@$1" && mv "@$1" $1
diff --git a/Doc/tools/fix_libaux.sed b/Doc/tools/fix_libaux.sed
deleted file mode 100755
index fb33cc5..0000000
--- a/Doc/tools/fix_libaux.sed
+++ /dev/null
@@ -1,3 +0,0 @@
-#! /bin/sed -f
-s/{\\tt \\hackscore {}\\hackscore {}/\\sectcode{__/
-s/\\hackscore {}\\hackscore {}/__/
diff --git a/Doc/tools/fixinfo.el b/Doc/tools/fixinfo.el
deleted file mode 100644
index 267a7e3..0000000
--- a/Doc/tools/fixinfo.el
+++ /dev/null
@@ -1,15 +0,0 @@
-(defun fix-python-texinfo ()
- (goto-char (point-min))
- (replace-regexp "\\(@setfilename \\)\\([-a-z]*\\)$"
- "\\1python-\\2.info")
- (replace-string "@node Front Matter\n@chapter Abstract\n"
- "@node Abstract\n@section Abstract\n")
- (mark-whole-buffer)
- (texinfo-master-menu 'update-all-nodes)
- (save-buffer)
- ) ;; fix-python-texinfo
-
-;; now really do it:
-(find-file (car command-line-args-left))
-(fix-python-texinfo)
-(kill-emacs)
diff --git a/Doc/tools/getpagecounts b/Doc/tools/getpagecounts
deleted file mode 100755
index 1adc470..0000000
--- a/Doc/tools/getpagecounts
+++ /dev/null
@@ -1,97 +0,0 @@
-#! /usr/bin/env python
-
-"""Generate a page count report of the PostScript version of the manuals."""
-
-__version__ = '$Revision$'
-
-import getopt
-import sys
-
-
-class PageCounter:
- def __init__(self):
- self.doclist = []
- self.total = 0
- self.title_width = 0
- self.version = ""
-
- def add_document(self, prefix, title):
- count = count_pages(prefix + ".ps")
- self.doclist.append((title, prefix, count))
- self.title_width = max(self.title_width, len(title))
- self.total = self.total + count
-
- def dump(self):
- fmt = "%%-%ds (%%s.ps, %%d pages)" % self.title_width
- for item in self.doclist:
- print fmt % item
- print
- print " Total page count: %d" % self.total
-
- def parse_options(self):
- opts, args = getopt.getopt(sys.argv[1:], "r:", ["release="])
- assert not args
- for opt, arg in opts:
- if opt in ("-r", "--release"):
- self.version = arg
-
- def run(self):
- self.parse_options()
- if self.version:
- version = self.version[:3]
- self.add_document("whatsnew" + version.replace(".", ""),
- "What's New in Python " + version)
- for prefix, title in [
- ("api", "Python/C API"),
- ("ext", "Extending and Embedding the Python Interpreter"),
- ("lib", "Python Library Reference"),
- ("mac", "Macintosh Module Reference"),
- ("ref", "Python Reference Manual"),
- ("tut", "Python Tutorial"),
- ("doc", "Documenting Python"),
- ("inst", "Installing Python Modules"),
- ("dist", "Distributing Python Modules"),
- ]:
- self.add_document(prefix, title)
- print self.PREFIX
- self.dump()
- print self.SUFFIX
-
- PREFIX = """\
-This is the PostScript version of the standard Python documentation.
-If you plan to print this, be aware that some of the documents are
-long. It is formatted for printing on two-sided paper; if you do plan
-to print this, *please* print two-sided if you have a printer capable
-of it! To locate published copies of the larger manuals, or other
-Python reference material, consult the Python Bookstore at:
-
- http://wiki.python.org/moin/PythonBooks
-
-The following manuals are included in this package:
-"""
- SUFFIX = """\
-
-
-If you have any questions, comments, or suggestions regarding these
-documents, please send them via email to docs@python.org.
-"""
-
-def count_pages(filename):
- fp = open(filename)
- count = 0
- while 1:
- lines = fp.readlines(1024*40)
- if not lines:
- break
- for line in lines:
- if line[:7] == "%%Page:":
- count = count + 1
- fp.close()
- return count
-
-
-def main():
- PageCounter().run()
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/getversioninfo b/Doc/tools/getversioninfo
deleted file mode 100755
index c1998d5..0000000
--- a/Doc/tools/getversioninfo
+++ /dev/null
@@ -1,71 +0,0 @@
-#! /usr/bin/env python
-
-import os
-import re
-import sys
-
-try:
- __file__
-except NameError:
- __file__ = sys.argv[0]
-
-tools = os.path.dirname(os.path.abspath(__file__))
-Doc = os.path.dirname(tools)
-src = os.path.dirname(Doc)
-patchlevel_h = os.path.join(src, "Include", "patchlevel.h")
-
-# This won't pick out all #defines, but it will pick up the ones we
-# care about.
-rx = re.compile(r"\s*#define\s+([a-zA-Z][a-zA-Z_0-9]*)\s+([a-zA-Z_0-9]+)")
-
-d = {}
-f = open(patchlevel_h)
-for line in f:
- m = rx.match(line)
- if m is not None:
- name, value = m.group(1, 2)
- d[name] = value
-f.close()
-
-release = "%s.%s" % (d["PY_MAJOR_VERSION"], d["PY_MINOR_VERSION"])
-micro = int(d["PY_MICRO_VERSION"])
-shortversion = release
-if micro != 0:
- release += "." + str(micro)
-level = d["PY_RELEASE_LEVEL"]
-
-suffixes = {
- "PY_RELEASE_LEVEL_ALPHA": "a",
- "PY_RELEASE_LEVEL_BETA": "b",
- "PY_RELEASE_LEVEL_GAMMA": "c",
- }
-
-releaseinfo = ""
-if level != "PY_RELEASE_LEVEL_FINAL":
- releaseinfo = suffixes[level] + str(int(d["PY_RELEASE_SERIAL"]))
-
-def write_file(name, text):
- """Write text to a file if the file doesn't exist or if text
- differs from any existing content."""
- if os.path.exists(name):
- f = open(name, "r")
- s = f.read()
- f.close()
- if s == text:
- return
- f = open(name, "w")
- f.write(text)
- f.close()
-
-patchlevel_tex = os.path.join(Doc, "commontex", "patchlevel.tex")
-
-write_file(patchlevel_tex,
- "%% This file is generated by ../tools/getversioninfo;\n"
- "%% do not edit manually.\n"
- "\n"
- "\\release{%s}\n"
- "\\setreleaseinfo{%s}\n"
- "\\setshortversion{%s}\n"
- % (release, releaseinfo, shortversion))
-
-print(release + releaseinfo)
diff --git a/Doc/tools/html2texi.pl b/Doc/tools/html2texi.pl
deleted file mode 100755
index 5dcfd46..0000000
--- a/Doc/tools/html2texi.pl
+++ /dev/null
@@ -1,1750 +0,0 @@
-#! /usr/bin/env perl
-# html2texi.pl -- Convert HTML documentation to Texinfo format
-# Michael Ernst <mernst@cs.washington.edu>
-# Time-stamp: <1999-01-12 21:34:27 mernst>
-
-# This program converts HTML documentation trees into Texinfo format.
-# Given the name of a main (or contents) HTML file, it processes that file,
-# and other files (transitively) referenced by it, into a Texinfo file
-# (whose name is chosen from the file or directory name of the argument).
-# For instance:
-# html2texi.pl api/index.html
-# produces file "api.texi".
-
-# Texinfo format can be easily converted to Info format (for browsing in
-# Emacs or the standalone Info browser), to a printed manual, or to HTML.
-# Thus, html2texi.pl permits conversion of HTML files to Info format, and
-# secondarily enables producing printed versions of Web page hierarchies.
-
-# Unlike HTML, Info format is searchable. Since Info is integrated into
-# Emacs, one can read documentation without starting a separate Web
-# browser. Additionally, Info browsers (including Emacs) contain
-# convenient features missing from Web browsers, such as easy index lookup
-# and mouse-free browsing.
-
-# Limitations:
-# html2texi.pl is currently tuned to latex2html output (and it corrects
-# several latex2html bugs), but should be extensible to arbitrary HTML
-# documents. It will be most useful for HTML with a hierarchical structure
-# and an index, and it recognizes those features as created by latex2html
-# (and possibly by some other tools). The HTML tree to be traversed must
-# be on local disk, rather than being accessed via HTTP.
-# This script requires the use of "checkargs.pm". To eliminate that
-# dependence, replace calls to check_args* by @_ (which is always the last
-# argument to those functions).
-# Also see the "to do" section, below.
-# Comments, suggestions, bug fixes, and enhancements are welcome.
-
-# Troubleshooting:
-# Malformed HTML can cause this program to abort, so
-# you should check your HTML files to make sure they are legal.
-
-
-###
-### Typical usage for the Python documentation:
-###
-
-# (Actually, most of this is in a Makefile instead.)
-# The resulting Info format Python documentation is currently available at
-# ftp://ftp.cs.washington.edu/homes/mernst/python-info.tar.gz
-
-# Fix up HTML problems, eg <DT><DL COMPACT><DD> should be <DT><DL COMPACT><DD>.
-
-# html2texi.pl /homes/fish/mernst/tmp/python-doc/html/api/index.html
-# html2texi.pl /homes/fish/mernst/tmp/python-doc/html/ext/index.html
-# html2texi.pl /homes/fish/mernst/tmp/python-doc/html/lib/index.html
-# html2texi.pl /homes/fish/mernst/tmp/python-doc/html/mac/index.html
-# html2texi.pl /homes/fish/mernst/tmp/python-doc/html/ref/index.html
-# html2texi.pl /homes/fish/mernst/tmp/python-doc/html/tut/index.html
-
-# Edit the generated .texi files:
-# * change @setfilename to prefix "python-"
-# * fix up any sectioning, such as for Abstract
-# * make Texinfo menus
-# * perhaps remove the @detailmenu ... @end detailmenu
-# In Emacs, to do all this:
-# (progn (goto-char (point-min)) (replace-regexp "\\(@setfilename \\)\\([-a-z]*\\)$" "\\1python-\\2.info") (replace-string "@node Front Matter\n@chapter Abstract\n" "@node Abstract\n@section Abstract\n") (progn (mark-whole-buffer) (texinfo-master-menu 'update-all-nodes)) (save-buffer))
-
-# makeinfo api.texi
-# makeinfo ext.texi
-# makeinfo lib.texi
-# makeinfo mac.texi
-# makeinfo ref.texi
-# makeinfo tut.texi
-
-
-###
-### Structure of the code
-###
-
-# To be written...
-
-
-###
-### Design decisions
-###
-
-# Source and destination languages
-# --------------------------------
-#
-# The goal is Info files; I create Texinfo, so I don't have to worry about
-# the finer details of Info file creation. (I'm not even sure of its exact
-# format.)
-#
-# Why not start from LaTeX rather than HTML?
-# I could hack latex2html itself to produce Texinfo instead, or fix up
-# partparse.py (which already translates LaTeX to Teinfo).
-# Pros:
-# * has high-level information such as index entries, original formatting
-# Cons:
-# * those programs are complicated to read and understand
-# * those programs try to handle arbitrary LaTeX input, track catcodes,
-# and more: I don't want to go to that effort. HTML isn't as powerful
-# as LaTeX, so there are fewer subtleties.
-# * the result wouldn't work for arbitrary HTML documents; it would be
-# nice to eventually extend this program to HTML produced from Docbook,
-# Frame, and more.
-
-# Parsing
-# -------
-#
-# I don't want to view the text as a linear stream; I'd rather parse the
-# whole thing and then do pattern matching over the parsed representation (to
-# find idioms such as indices, lists of child nodes, etc.).
-# * Perl provides HTML::TreeBuilder, which does just what I want.
-# * libwww-perl: http://www.linpro.no/lwp/
-# * TreeBuilder: HTML-Tree-0.51.tar.gz
-# * Python Parsers, Formatters, and Writers don't really provide the right
-# interface (and the version in Grail doesn't correspond to another
-# distributed version, so I'm confused about which to be using). I could
-# write something in Python that creates a parse tree, but why bother?
-
-# Other implementation language issues:
-# * Python lacks variable declarations, reasonable scoping, and static
-# checking tools. I've written some of the latter for myself that make
-# my Perl programming a lot safer than my Python programming will be until
-# I have a similar suite for that language.
-
-
-###########################################################################
-### To do
-###
-
-# Section names:
-# Fix the problem with multiple sections in a single file (eg, Abstract in
-# Front Matter section).
-# Deal with cross-references, as in /homes/fish/mernst/tmp/python-doc/html/ref/types.html:310
-# Index:
-# Perhaps double-check that every tag mentioned in the index is found
-# in the text.
-# Python: email to docs@python.org, to get their feedback.
-# Compare to existing lib/ Info manual
-# Write the hooks into info-look; replace pyliblookup1-1.tar.gz.
-# Postpass to remove extra quotation marks around typography already in
-# a different font (to avoid double delimiters as in "`code'"); or
-# perhaps consider using only font-based markup so that we don't get
-# the extra *bold* and `code' markup in Info.
-
-## Perhaps don't rely on automatic means for adding up, next, prev; I have
-## all that info available to me already, so it's not so much trouble to
-## add it. (Right?) But it is *so* easy to use Emacs instead...
-
-
-###########################################################################
-### Strictures
-###
-
-# man HTML::TreeBuilder
-# man HTML::Parser
-# man HTML::Element
-
-# require HTML::ParserWComment;
-require HTML::Parser;
-require HTML::TreeBuilder;
-require HTML::Element;
-
-use File::Basename;
-
-use strict;
-# use Carp;
-
-use checkargs;
-
-
-###########################################################################
-### Variables
-###
-
-my @section_stack = (); # elements are chapter/section/subsec nodetitles (I think)
-my $current_ref_tdf; # for the file currently being processed;
- # used in error messages
-my $html_directory;
-my %footnotes;
-
-# First element should not be used.
-my @sectionmarker = ("manual", "chapter", "section", "subsection", "subsubsection");
-
-my %inline_markup = ("b" => "strong",
- "code" => "code",
- "i" => "emph",
- "kbd" => "kbd",
- "samp" => "samp",
- "strong" => "strong",
- "tt" => "code",
- "var" => "var");
-
-my @deferred_index_entries = ();
-
-my @index_titles = (); # list of (filename, type) lists
-my %index_info = ("Index" => ["\@blindex", "bl"],
- "Concept Index" => ["\@cindex", "cp"],
- "Module Index" => ["\@mdindex", "md"]);
-
-
-###########################################################################
-### Main/contents page
-###
-
-# Process first-level page on its own, or just a contents page? Well, I do
-# want the title, author, etc., and the front matter... For now, just add
-# that by hand at the end.
-
-
-# data structure possibilities:
-# * tree-like (need some kind of stack when processing (or parent pointers))
-# * list of name and depth; remember old and new depths.
-
-# Each element is a reference to a list of (nodetitle, depth, filename).
-my @contents_list = ();
-
-# The problem with doing fixups on the fly is that some sections may have
-# already been processed (and no longer available) by the time we notice
-# others with the same name. It's probably better to fully construct the
-# contents list (reading in all files of interest) upfront; that will also
-# let me do a better job with cross-references, because again, all files
-# will already be read in.
-my %contents_hash = ();
-my %contents_fixups = ();
-
-my @current_contents_list = ();
-
-# Merge @current_contents_list into @contents_list,
-# and set @current_contents_list to be empty.
-sub merge_contents_lists ( )
-{ check_args(0, @_);
-
- # Three possibilities:
- # * @contents_list is empty: replace it by @current_contents_list.
- # * prefixes of the two lists are identical: do nothing
- # * @current_contents_list is all at lower level than $contents_list[0];
- # prefix @contents_list by @current_contents_list
-
- if (scalar(@current_contents_list) == 0)
- { die "empty current_contents_list"; }
-
- # if (scalar(@contents_list) == 0)
- # { @contents_list = @current_contents_list;
- # @current_contents_list = ();
- # return; }
-
- # if (($ {$contents_list[0]}[1]) < ($ {$current_contents_list[0]}[1]))
- # { unshift @contents_list, @current_contents_list;
- # @current_contents_list = ();
- # return; }
-
- for (my $i=0; $i<scalar(@current_contents_list); $i++)
- { my $ref_c_tdf = $current_contents_list[$i];
- if ($i >= scalar(@contents_list))
- { push @contents_list, $ref_c_tdf;
- my $title = $ {$ref_c_tdf}[0];
- if (defined $contents_hash{$title})
- { $contents_fixups{$title} = 1; }
- else
- { $contents_hash{$title} = 1; }
- next; }
- my $ref_tdf = $contents_list[$i];
- my ($title, $depth, $file) = @{$ref_tdf};
- my ($c_title, $c_depth, $c_file) = @{$ref_c_tdf};
-
- if (($title ne $c_title)
- && ($depth < $c_depth)
- && ($file ne $c_file))
- { splice @contents_list, $i, 0, $ref_c_tdf;
- if (defined $contents_hash{$c_title})
- { $contents_fixups{$c_title} = 1; }
- else
- { $contents_hash{$c_title} = 1; }
- next; }
-
- if (($title ne $c_title)
- || ($depth != $c_depth)
- || ($file ne $c_file))
- { die ("while processing $ {$current_ref_tdf}[2] at depth $ {$current_ref_tdf}[1], mismatch at index $i:",
- "\n main: <<<$title>>> $depth $file",
- "\n curr: <<<$c_title>>> $c_depth $c_file"); }
- }
- @current_contents_list = ();
-}
-
-
-
-# Set @current_contents_list to a list of (title, href, sectionlevel);
-# then merge that list into @contents_list.
-# Maybe this function should also produce a map
-# from title (or href) to sectionlevel (eg "chapter"?).
-sub process_child_links ( $ )
-{ my ($he) = check_args(1, @_);
-
- # $he->dump();
- if (scalar(@current_contents_list) != 0)
- { die "current_contents_list nonempty: @current_contents_list"; }
- $he->traverse(\&increment_current_contents_list, 'ignore text');
-
- # Normalize the depths; for instance, convert 1,3,5 into 0,1,2.
- my %depths = ();
- for my $ref_tdf (@current_contents_list)
- { $depths{$ {$ref_tdf}[1]} = 1; }
- my @sorted_depths = sort keys %depths;
- my $current_depth = scalar(@section_stack)-1;
- my $current_depth_2 = $ {$current_ref_tdf}[1];
- if ($current_depth != $current_depth_2)
- { die "mismatch in current depths: $current_depth $current_depth_2; ", join(", ", @section_stack); }
- for (my $i=0; $i<scalar(@sorted_depths); $i++)
- { $depths{$sorted_depths[$i]} = $i + $current_depth+1; }
- for my $ref_tdf (@current_contents_list)
- { $ {$ref_tdf}[1] = $depths{$ {$ref_tdf}[1]}; }
-
- # Eliminate uninteresting sections. Hard-coded hack for now.
- if ($ {$current_contents_list[-1]}[0] eq "About this document ...")
- { pop @current_contents_list; }
- if ((scalar(@current_contents_list) > 1)
- && ($ {$current_contents_list[1]}[0] eq "Contents"))
- { my $ref_first_tdf = shift @current_contents_list;
- $current_contents_list[0] = $ref_first_tdf; }
-
- for (my $i=0; $i<scalar(@current_contents_list); $i++)
- { my $ref_tdf = $current_contents_list[$i];
- my $title = $ {$ref_tdf}[0];
- if (exists $index_info{$title})
- { my $index_file = $ {$ref_tdf}[2];
- my ($indexing_command, $suffix) = @{$index_info{$title}};
- process_index_file($index_file, $indexing_command);
- print TEXI "\n\@defindex $suffix\n";
- push @index_titles, $title;
- splice @current_contents_list, $i, 1;
- $i--; }
- elsif ($title =~ /\bIndex$/)
- { print STDERR "Warning: \"$title\" might be an index; if so, edit \%index_info.\n"; } }
-
- merge_contents_lists();
-
- # print_contents_list();
- # print_index_info();
-}
-
-
-sub increment_current_contents_list ( $$$ )
-{ my ($he, $startflag, $depth) = check_args(3, @_);
- if (!$startflag)
- { return; }
-
- if ($he->tag eq "li")
- { my @li_content = @{$he->content};
- if ($li_content[0]->tag ne "a")
- { die "first element of <LI> should be <A>"; }
- my ($name, $href, @content) = anchor_info($li_content[0]);
- # unused $name
- my $title = join("", collect_texts($li_content[0]));
- $title = texi_remove_punctuation($title);
- # The problem with these is that they are formatted differently in
- # @menu and @node!
- $title =~ s/``/\"/g;
- $title =~ s/''/\"/g;
- $title =~ s/ -- / /g;
- push @current_contents_list, [ $title, $depth, $href ]; }
- return 1;
-}
-
-# Simple version for section titles
-sub html_to_texi ( $ )
-{ my ($he) = check_args(1, @_);
- if (!ref $he)
- { return $he; }
-
- my $tag = $he->tag;
- if (exists $inline_markup{$tag})
- { my $result = "\@$inline_markup{$tag}\{";
- for my $elt (@{$he->content})
- { $result .= html_to_texi($elt); }
- $result .= "\}";
- return $result; }
- else
- { $he->dump();
- die "html_to_texi confused by <$tag>"; }
-}
-
-
-
-sub print_contents_list ()
-{ check_args(0, @_);
- print STDERR "Contents list:\n";
- for my $ref_tdf (@contents_list)
- { my ($title, $depth, $file) = @{$ref_tdf};
- print STDERR "$title $depth $file\n"; }
-}
-
-
-
-###########################################################################
-### Index
-###
-
-my $l2h_broken_link_name = "l2h-";
-
-
-# map from file to (map from anchor name to (list of index texts))
-# (The list is needed when a single LaTeX command like \envvar
-# expands to multiple \index commands.)
-my %file_index_entries = ();
-my %this_index_entries; # map from anchor name to (list of index texts)
-
-my %file_index_entries_broken = (); # map from file to (list of index texts)
-my @this_index_entries_broken;
-
-my $index_prefix = "";
-my @index_prefixes = ();
-
-my $this_indexing_command;
-
-sub print_index_info ()
-{ check_args(0, @_);
- my ($key, $val);
- for my $file (sort keys %file_index_entries)
- { my %index_entries = %{$file_index_entries{$file}};
- print STDERR "file: $file\n";
- for my $aname (sort keys %index_entries)
- { my @entries = @{$index_entries{$aname}};
- if (scalar(@entries) == 1)
- { print STDERR " $aname : $entries[0]\n"; }
- else
- { print STDERR " $aname : ", join("\n " . (" " x length($aname)), @entries), "\n"; } } }
- for my $file (sort keys %file_index_entries_broken)
- { my @entries = @{$file_index_entries_broken{$file}};
- print STDERR "file: $file\n";
- for my $entry (@entries)
- { print STDERR " $entry\n"; }
- }
-}
-
-
-sub process_index_file ( $$ )
-{ my ($file, $indexing_command) = check_args(2, @_);
- # print "process_index_file $file $indexing_command\n";
-
- my $he = file_to_tree($html_directory . $file);
- # $he->dump();
-
- $this_indexing_command = $indexing_command;
- $he->traverse(\&process_if_index_dl_compact, 'ignore text');
- undef $this_indexing_command;
- # print "process_index_file done\n";
-}
-
-
-sub process_if_index_dl_compact ( $$$ )
-{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
- if (!$startflag)
- { return; }
-
- if (($he->tag() eq "dl") && (defined $he->attr('compact')))
- { process_index_dl_compact($he);
- return 0; }
- else
- { return 1; }
-}
-
-
-# The elements of a <DL COMPACT> list from a LaTeX2HTML index:
-# * a single space: text to be ignored
-# * <DT> elements with an optional <DD> element following each one
-# Two types of <DT> elements:
-# * Followed by a <DD> element: the <DT> contains a single
-# string, and the <DD> contains a whitespace string to be ignored, a
-# <DL COMPACT> to be recursively processed (with the <DT> string as a
-# prefix), and a whitespace string to be ignored.
-# * Not followed by a <DD> element: contains a list of anchors
-# and texts (ignore the texts, which are only whitespace and commas).
-# Optionally contains a <DL COMPACT> to be recursively processed (with
-# the <DT> string as a prefix)
-sub process_index_dl_compact ( $ )
-{ my ($h) = check_args(1, @_);
- my @content = @{$h->content()};
- for (my $i = 0; $i < scalar(@content); $i++)
- { my $this_he = $content[$i];
- if ($this_he->tag ne "dt")
- { $this_he->dump();
- die "Expected <DT> tag: " . $this_he->tag; }
- if (($i < scalar(@content) - 1) && ($content[$i+1]->tag eq "dd"))
- { process_index_dt_and_dd($this_he, $content[$i+1]);
- $i++; }
- else
- { process_index_lone_dt($this_he); } } }
-
-
-
-# Argument is a <DT> element. If it contains more than one anchor, then
-# the texts of all subsequent ones are "[Link]". Example:
-# <DT>
-# <A HREF="embedding.html#l2h-201">
-# "$PATH"
-# ", "
-# <A HREF="embedding.html#l2h-205">
-# "[Link]"
-# Optionally contains a <DL COMPACT> as well. Example:
-# <DT>
-# <A HREF="types.html#l2h-616">
-# "attribute"
-# <DL COMPACT>
-# <DT>
-# <A HREF="assignment.html#l2h-3074">
-# "assignment"
-# ", "
-# <A HREF="assignment.html#l2h-3099">
-# "[Link]"
-# <DT>
-# <A HREF="types.html#l2h-">
-# "assignment, class"
-
-sub process_index_lone_dt ( $ )
-{ my ($dt) = check_args(1, @_);
- my @dtcontent = @{$dt->content()};
- my $acontent;
- my $acontent_suffix;
- for my $a (@dtcontent)
- { if ($a eq ", ")
- { next; }
- if (!ref $a)
- { $dt->dump;
- die "Unexpected <DT> string element: $a"; }
-
- if ($a->tag eq "dl")
- { push @index_prefixes, $index_prefix;
- if (!defined $acontent_suffix)
- { die "acontent_suffix not yet defined"; }
- $index_prefix .= $acontent_suffix . ", ";
- process_index_dl_compact($a);
- $index_prefix = pop(@index_prefixes);
- return; }
-
- if ($a->tag ne "a")
- { $dt->dump;
- $a->dump;
- die "Expected anchor in lone <DT>"; }
-
- my ($aname, $ahref, @acontent) = anchor_info($a);
- # unused $aname
- if (scalar(@acontent) != 1)
- { die "Expected just one content of <A> in <DT>: @acontent"; }
- if (ref $acontent[0])
- { $acontent[0]->dump;
- die "Expected string content of <A> in <DT>: $acontent[0]"; }
- if (!defined($acontent))
- { $acontent = $index_prefix . $acontent[0];
- $acontent_suffix = $acontent[0]; }
- elsif (($acontent[0] ne "[Link]") && ($acontent ne ($index_prefix . $acontent[0])))
- { die "Differing content: <<<$acontent>>>, <<<$acontent[0]>>>"; }
-
- if (!defined $ahref)
- { $dt->dump;
- die "no HREF in nachor in <DT>"; }
- my ($ahref_file, $ahref_name) = split(/\#/, $ahref);
- if (!defined $ahref_name)
- { # Reference to entire file
- $ahref_name = ""; }
-
- if ($ahref_name eq $l2h_broken_link_name)
- { if (!exists $file_index_entries_broken{$ahref_file})
- { $file_index_entries_broken{$ahref_file} = []; }
- push @{$file_index_entries_broken{$ahref_file}}, "$this_indexing_command $acontent";
- next; }
-
- if (!exists $file_index_entries{$ahref_file})
- { $file_index_entries{$ahref_file} = {}; }
- # Don't do this! It appears to make a copy, which is not desired.
- # my %index_entries = %{$file_index_entries{$ahref_file}};
- if (!exists $ {$file_index_entries{$ahref_file}}{$ahref_name})
- { $ {$file_index_entries{$ahref_file}}{$ahref_name} = []; }
- # { my $oldcontent = $ {$file_index_entries{$ahref_file}}{$ahref_name};
- # if ($acontent eq $oldcontent)
- # { die "Multiple identical index entries?"; }
- # die "Trying to add $acontent, but already have index entry pointing at $ahref_file\#$ahref_name: ${$file_index_entries{$ahref_file}}{$ahref_name}"; }
-
- push @{$ {$file_index_entries{$ahref_file}}{$ahref_name}}, "$this_indexing_command $acontent";
- # print STDERR "keys: ", keys %{$file_index_entries{$ahref_file}}, "\n";
- }
-}
-
-sub process_index_dt_and_dd ( $$ )
-{ my ($dt, $dd) = check_args(2, @_);
- my $dtcontent;
- { my @dtcontent = @{$dt->content()};
- if ((scalar(@dtcontent) != 1) || (ref $dtcontent[0]))
- { $dd->dump;
- $dt->dump;
- die "Expected single string (actual size = " . scalar(@dtcontent) . ") in content of <DT>: @dtcontent"; }
- $dtcontent = $dtcontent[0];
- $dtcontent =~ s/ +$//; }
- my $ddcontent;
- { my @ddcontent = @{$dd->content()};
- if (scalar(@ddcontent) != 1)
- { die "Expected single <DD> content, got ", scalar(@ddcontent), " elements:\n", join("\n", @ddcontent), "\n "; }
- $ddcontent = $ddcontent[0]; }
- if ($ddcontent->tag ne "dl")
- { die "Expected <DL> as content of <DD>, but saw: $ddcontent"; }
-
- push @index_prefixes, $index_prefix;
- $index_prefix .= $dtcontent . ", ";
- process_index_dl_compact($ddcontent);
- $index_prefix = pop(@index_prefixes);
-}
-
-
-###########################################################################
-### Ordinary sections
-###
-
-sub process_section_file ( $$$ )
-{ my ($file, $depth, $nodetitle) = check_args(3, @_);
- my $he = file_to_tree(($file =~ /^\//) ? $file : $html_directory . $file);
-
- # print STDERR "process_section_file: $file $depth $nodetitle\n";
-
- # Equivalently:
- # while ($depth >= scalar(@section_stack)) { pop(@section_stack); }
- @section_stack = @section_stack[0..$depth-1];
-
- # Not a great nodename fixup scheme; need a more global view
- if ((defined $contents_fixups{$nodetitle})
- && (scalar(@section_stack) > 0))
- { my $up_title = $section_stack[$#section_stack];
- # hack for Python Standard Library
- $up_title =~ s/^(Built-in|Standard) Module //g;
- my ($up_first_word) = split(/ /, $up_title);
- $nodetitle = "$up_first_word $nodetitle";
- }
-
- push @section_stack, $nodetitle;
- # print STDERR "new section_stack: ", join(", ", @section_stack), "\n";
-
- $he->traverse(\&process_if_child_links, 'ignore text');
- %footnotes = ();
- # $he->dump;
- $he->traverse(\&process_if_footnotes, 'ignore text');
-
- # $he->dump;
-
- if (exists $file_index_entries{$file})
- { %this_index_entries = %{$file_index_entries{$file}};
- # print STDERR "this_index_entries:\n ", join("\n ", keys %this_index_entries), "\n";
- }
- else
- { # print STDERR "Warning: no index entries for file $file\n";
- %this_index_entries = (); }
-
- if (exists $file_index_entries_broken{$file})
- { @this_index_entries_broken = @{$file_index_entries_broken{$file}}; }
- else
- { # print STDERR "Warning: no index entries for file $file\n";
- @this_index_entries_broken = (); }
-
-
- if ($he->tag() ne "html")
- { die "Expected <HTML> at top level"; }
- my @content = @{$he->content()};
- if ((!ref $content[0]) or ($content[0]->tag ne "head"))
- { $he->dump;
- die "<HEAD> not first element of <HTML>"; }
- if ((!ref $content[1]) or ($content[1]->tag ne "body"))
- { $he->dump;
- die "<BODY> not second element of <HTML>"; }
-
- $content[1]->traverse(\&output_body);
-}
-
-# stack of things we're inside that are preventing indexing from occurring now.
-# These are "h1", "h2", "h3", "h4", "h5", "h6", "dt" (and possibly others?)
-my @index_deferrers = ();
-
-sub push_or_pop_index_deferrers ( $$ )
-{ my ($tag, $startflag) = check_args(2, @_);
- if ($startflag)
- { push @index_deferrers, $tag; }
- else
- { my $old_deferrer = pop @index_deferrers;
- if ($tag ne $old_deferrer)
- { die "Expected $tag at top of index_deferrers but saw $old_deferrer; remainder = ", join(" ", @index_deferrers); }
- do_deferred_index_entries(); }
-}
-
-
-sub label_add_index_entries ( $;$ )
-{ my ($label, $he) = check_args_range(1, 2, @_);
- # print ((exists $this_index_entries{$label}) ? "*" : " "), " label_add_index_entries $label\n";
- # $he is the anchor element
- if (exists $this_index_entries{$label})
- { push @deferred_index_entries, @{$this_index_entries{$label}};
- return; }
-
- if ($label eq $l2h_broken_link_name)
- { # Try to find some text to use in guessing which links should point here
- # I should probably only look at the previous element, or if that is
- # all punctuation, the one before it; collecting all the previous texts
- # is a bit of overkill.
- my @anchor_texts = collect_texts($he);
- my @previous_texts = collect_texts($he->parent, $he);
- # 4 elements is arbitrary; ought to filter out punctuation and small words
- # first, then perhaps keep fewer. Perhaps also filter out formatting so
- # that we can see a larger chunk of text? (Probably not.)
- # Also perhaps should do further chunking into words, in case the
- # index term isn't a chunk of its own (eg, was in <tt>...</tt>.
- my @candidate_texts = (@anchor_texts, (reverse(@previous_texts))[0..min(3,$#previous_texts)]);
-
- my $guessed = 0;
- for my $text (@candidate_texts)
- { # my $orig_text = $text;
- if ($text =~ /^[\"\`\'().?! ]*$/)
- { next; }
- if (length($text) <= 2)
- { next; }
- # hack for Python manual; maybe defer until failure first time around?
- $text =~ s/^sys\.//g;
- for my $iterm (@this_index_entries_broken)
- { # I could test for zero: LaTeX2HTML's failures in the Python
- # documentation are only for items of the form "... (built-in...)"
- if (index($iterm, $text) != -1)
- { push @deferred_index_entries, $iterm;
- # print STDERR "Guessing index term `$iterm' for text `$orig_text'\n";
- $guessed = 1;
- } } }
- if (!$guessed)
- { # print STDERR "No guess in `", join("'; `", @this_index_entries_broken), "' for texts:\n `", join("'\n `", @candidate_texts), "'\n";
- }
- }
-}
-
-
-# Need to add calls to this at various places.
-# Perhaps add HTML::Element argument and do the check for appropriateness
-# here (ie, no action if inside <H1>, etc.).
-sub do_deferred_index_entries ()
-{ check_args(0, @_);
- if ((scalar(@deferred_index_entries) > 0)
- && (scalar(@index_deferrers) == 0))
- { print TEXI "\n", join("\n", @deferred_index_entries), "\n";
- @deferred_index_entries = (); }
-}
-
-my $table_columns; # undefined if not in a table
-my $table_first_column; # boolean
-
-sub output_body ( $$$ )
-{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
-
- if (!ref $he)
- { my $space_index = index($he, " ");
- if ($space_index != -1)
- { # Why does
- # print TEXI texi_quote(substr($he, 0, $space_index+1));
- # give: Can't locate object method "TEXI" via package "texi_quote"
- # (Because the definition texi_quote hasn't been seen yet.)
- print TEXI &texi_quote(substr($he, 0, $space_index+1));
- do_deferred_index_entries();
- print TEXI &texi_quote(substr($he, $space_index+1)); }
- else
- { print TEXI &texi_quote($he); }
- return; }
-
- my $tag = $he->tag();
-
- # Ordinary text markup first
- if (exists $inline_markup{$tag})
- { if ($startflag)
- { print TEXI "\@$inline_markup{$tag}\{"; }
- else
- { print TEXI "\}"; } }
- elsif ($tag eq "a")
- { my ($name, $href, @content) = anchor_info($he);
- if (!$href)
- { # This anchor is only here for indexing/cross referencing purposes.
- if ($startflag)
- { label_add_index_entries($name, $he); }
- }
- elsif ($href =~ "^(ftp|http|news):")
- { if ($startflag)
- { # Should avoid second argument if it's identical to the URL.
- print TEXI "\@uref\{$href, "; }
- else
- { print TEXI "\}"; }
- }
- elsif ($href =~ /^\#(foot[0-9]+)$/)
- { # Footnote
- if ($startflag)
- { # Could double-check name and content, but I'm not
- # currently storing that information.
- print TEXI "\@footnote\{";
- $footnotes{$1}->traverse(\&output_body);
- print TEXI "\}";
- return 0; } }
- else
- { if ($startflag)
- { # cross-references are not active Info links, but no text is lost
- print STDERR "Can't deal with internal HREF anchors yet:\n";
- $he->dump; }
- }
- }
- elsif ($tag eq "br")
- { print TEXI "\@\n"; }
- elsif ($tag eq "body")
- { }
- elsif ($tag eq "center")
- { if (has_single_content_string($he)
- && ($ {$he->content}[0] =~ /^ *$/))
- { return 0; }
- if ($startflag)
- { print TEXI "\n\@center\n"; }
- else
- { print TEXI "\n\@end center\n"; }
- }
- elsif ($tag eq "div")
- { my $align = $he->attr('align');
- if (defined($align) && ($align eq "center"))
- { if (has_single_content_string($he)
- && ($ {$he->content}[0] =~ /^ *$/))
- { return 0; }
- if ($startflag)
- { print TEXI "\n\@center\n"; }
- else
- { print TEXI "\n\@end center\n"; } }
- }
- elsif ($tag eq "dl")
- { # Recognize "<dl><dd><pre> ... </pre></dl>" paradigm for "@example"
- if (has_single_content_with_tag($he, "dd"))
- { my $he_dd = $ {$he->content}[0];
- if (has_single_content_with_tag($he_dd, "pre"))
- { my $he_pre = $ {$he_dd->content}[0];
- print_pre($he_pre);
- return 0; } }
- if ($startflag)
- { # Could examine the elements, to be cleverer about formatting.
- # (Also to use ftable, vtable...)
- print TEXI "\n\@table \@asis\n"; }
- else
- { print TEXI "\n\@end table\n"; }
- }
- elsif ($tag eq "dt")
- { push_or_pop_index_deferrers($tag, $startflag);
- if ($startflag)
- { print TEXI "\n\@item "; }
- else
- { } }
- elsif ($tag eq "dd")
- { if ($startflag)
- { print TEXI "\n"; }
- else
- { }
- if (scalar(@index_deferrers) != 0)
- { $he->dump;
- die "Unexpected <$tag> while inside: (" . join(" ", @index_deferrers) . "); bad HTML?"; }
- do_deferred_index_entries();
- }
- elsif ($tag =~ /^(font|big|small)$/)
- { # Do nothing for now.
- }
- elsif ($tag =~ /^h[1-6]$/)
- { # We don't need this because we never recursively enter the heading content.
- # push_or_pop_index_deferrers($tag, $startflag);
- my $secname = "";
- my @seclabels = ();
- for my $elt (@{$he->content})
- { if (!ref $elt)
- { $secname .= $elt; }
- elsif ($elt->tag eq "br")
- { }
- elsif ($elt->tag eq "a")
- { my ($name, $href, @acontent) = anchor_info($elt);
- if ($href)
- { $he->dump;
- $elt->dump;
- die "Nonsimple anchor in <$tag>"; }
- if (!defined $name)
- { die "No NAME for anchor in $tag"; }
- push @seclabels, $name;
- for my $subelt (@acontent)
- { $secname .= html_to_texi($subelt); } }
- else
- { $secname .= html_to_texi($elt); } }
- if ($secname eq "")
- { die "No section name in <$tag>"; }
- if (scalar(@section_stack) == 1)
- { if ($section_stack[-1] ne "Top")
- { die "Not top? $section_stack[-1]"; }
- print TEXI "\@settitle $secname\n";
- print TEXI "\@c %**end of header\n";
- print TEXI "\n";
- print TEXI "\@node Top\n";
- print TEXI "\n"; }
- else
- { print TEXI "\n\@node $section_stack[-1]\n";
- print TEXI "\@$sectionmarker[scalar(@section_stack)-1] ", texi_remove_punctuation($secname), "\n"; }
- for my $seclabel (@seclabels)
- { label_add_index_entries($seclabel); }
- # This should only happen once per file.
- label_add_index_entries("");
- if (scalar(@index_deferrers) != 0)
- { $he->dump;
- die "Unexpected <$tag> while inside: (" . join(" ", @index_deferrers) . "); bad HTML?"; }
- do_deferred_index_entries();
- return 0;
- }
- elsif ($tag eq "hr")
- { }
- elsif ($tag eq "ignore")
- { # Hack for ignored elements
- return 0;
- }
- elsif ($tag eq "li")
- { if ($startflag)
- { print TEXI "\n\n\@item\n";
- do_deferred_index_entries(); } }
- elsif ($tag eq "ol")
- { if ($startflag)
- { print TEXI "\n\@enumerate \@bullet\n"; }
- else
- { print TEXI "\n\@end enumerate\n"; } }
- elsif ($tag eq "p")
- { if ($startflag)
- { print TEXI "\n\n"; }
- if (scalar(@index_deferrers) != 0)
- { $he->dump;
- die "Unexpected <$tag> while inside: (" . join(" ", @index_deferrers) . "); bad HTML?"; }
- do_deferred_index_entries(); }
- elsif ($tag eq "pre")
- { print_pre($he);
- return 0; }
- elsif ($tag eq "table")
- { # Could also indicate common formatting for first column, or
- # determine relative widths for columns (or determine a prototype row)
- if ($startflag)
- { if (defined $table_columns)
- { $he->dump;
- die "Can't deal with table nested inside $table_columns-column table"; }
- $table_columns = table_columns($he);
- if ($table_columns < 2)
- { $he->dump;
- die "Column with $table_columns columns?"; }
- elsif ($table_columns == 2)
- { print TEXI "\n\@table \@asis\n"; }
- else
- { print TEXI "\n\@multitable \@columnfractions";
- for (my $i=0; $i<$table_columns; $i++)
- { print TEXI " ", 1.0/$table_columns; }
- print TEXI "\n"; } }
- else
- { if ($table_columns == 2)
- { print TEXI "\n\@end table\n"; }
- else
- { print TEXI "\n\@end multitable\n"; }
- undef $table_columns; } }
- elsif (($tag eq "td") || ($tag eq "th"))
- { if ($startflag)
- { if ($table_first_column)
- { print TEXI "\n\@item ";
- $table_first_column = 0; }
- elsif ($table_columns > 2)
- { print TEXI "\n\@tab "; } }
- else
- { print TEXI "\n"; } }
- elsif ($tag eq "tr")
- { if ($startflag)
- { $table_first_column = 1; } }
- elsif ($tag eq "ul")
- { if ($startflag)
- { print TEXI "\n\@itemize \@bullet\n"; }
- else
- { print TEXI "\n\@end itemize\n"; } }
- else
- { # I used to have a newline before "output_body" here.
- print STDERR "output_body: ignoring <$tag> tag\n";
- $he->dump;
- return 0; }
-
- return 1;
-}
-
-sub print_pre ( $ )
-{ my ($he_pre) = check_args(1, @_);
- if (!has_single_content_string($he_pre))
- { die "Multiple or non-string content for <PRE>: ", @{$he_pre->content}; }
- my $pre_content = $ {$he_pre->content}[0];
- print TEXI "\n\@example";
- print TEXI &texi_quote($pre_content);
- print TEXI "\@end example\n";
-}
-
-sub table_columns ( $ )
-{ my ($table) = check_args(1, @_);
- my $result = 0;
- for my $row (@{$table->content})
- { if ($row->tag ne "tr")
- { $table->dump;
- $row->dump;
- die "Expected <TR> as table row."; }
- $result = max($result, scalar(@{$row->content})); }
- return $result;
-}
-
-
-###########################################################################
-### Utilities
-###
-
-sub min ( $$ )
-{ my ($x, $y) = check_args(2, @_);
- return ($x < $y) ? $x : $y;
-}
-
-sub max ( $$ )
-{ my ($x, $y) = check_args(2, @_);
- return ($x > $y) ? $x : $y;
-}
-
-sub file_to_tree ( $ )
-{ my ($file) = check_args(1, @_);
-
- my $tree = new HTML::TreeBuilder;
- $tree->ignore_unknown(1);
- # $tree->warn(1);
- $tree->parse_file($file);
- cleanup_parse_tree($tree);
- return $tree
-}
-
-
-sub has_single_content ( $ )
-{ my ($he) = check_args(1, @_);
- if (!ref $he)
- { # return 0;
- die "Non-reference argument: $he"; }
- my $ref_content = $he->content;
- if (!defined $ref_content)
- { return 0; }
- my @content = @{$ref_content};
- if (scalar(@content) != 1)
- { return 0; }
- return 1;
-}
-
-
-# Return true if the content of the element contains only one element itself,
-# and that inner element has the specified tag.
-sub has_single_content_with_tag ( $$ )
-{ my ($he, $tag) = check_args(2, @_);
- if (!has_single_content($he))
- { return 0; }
- my $content = $ {$he->content}[0];
- if (!ref $content)
- { return 0; }
- my $content_tag = $content->tag;
- if (!defined $content_tag)
- { return 0; }
- return $content_tag eq $tag;
-}
-
-sub has_single_content_string ( $ )
-{ my ($he) = check_args(1, @_);
- if (!has_single_content($he))
- { return 0; }
- my $content = $ {$he->content}[0];
- if (ref $content)
- { return 0; }
- return 1;
-}
-
-
-# Return name, href, content. First two may be undefined; third is an array.
-# I don't see how to determine if there are more attributes.
-sub anchor_info ( $ )
-{ my ($he) = check_args(1, @_);
- if ($he->tag ne "a")
- { $he->dump;
- die "passed non-anchor to anchor_info"; }
- my $name = $he->attr('name');
- my $href = $he->attr('href');
- my @content = ();
- { my $ref_content = $he->content;
- if (defined $ref_content)
- { @content = @{$ref_content}; } }
- return ($name, $href, @content);
-}
-
-
-sub texi_quote ( $ )
-{ my ($text) = check_args(1, @_);
- $text =~ s/([\@\{\}])/\@$1/g;
- $text =~ s/ -- / --- /g;
- return $text;
-}
-
-# Eliminate bad punctuation (that confuses Makeinfo or Info) for section titles.
-sub texi_remove_punctuation ( $ )
-{ my ($text) = check_args(1, @_);
-
- $text =~ s/^ +//g;
- $text =~ s/[ :]+$//g;
- $text =~ s/^[1-9][0-9.]* +//g;
- $text =~ s/,//g;
- # Both embedded colons and " -- " confuse makeinfo. (Perhaps " -- "
- # gets converted into " - ", just as "---" would be converted into " -- ",
- # so the names end up differing.)
- # $text =~ s/:/ -- /g;
- $text =~ s/://g;
- return $text;
-}
-
-
-## Do not use this inside `traverse': it throws off the traversal. Use
-## html_replace_by_ignore or html_replace_by_meta instead.
-# Returns 1 if success, 0 if failure.
-sub html_remove ( $;$ )
-{ my ($he, $parent) = check_args_range(1, 2, @_);
- if (!defined $parent)
- { $parent = $he->parent; }
- my $ref_pcontent = $parent->content;
- my @pcontent = @{$ref_pcontent};
- for (my $i=0; $i<scalar(@pcontent); $i++)
- { if ($pcontent[$i] eq $he)
- { splice @{$ref_pcontent}, $i, 1;
- $he->parent(undef);
- return 1; } }
- die "Didn't find $he in $parent";
-}
-
-
-sub html_replace ( $$;$ )
-{ my ($orig, $new, $parent) = check_args_range(2, 3, @_);
- if (!defined $parent)
- { $parent = $orig->parent; }
- my $ref_pcontent = $parent->content;
- my @pcontent = @{$ref_pcontent};
- for (my $i=0; $i<scalar(@pcontent); $i++)
- { if ($pcontent[$i] eq $orig)
- { $ {$ref_pcontent}[$i] = $new;
- $new->parent($parent);
- $orig->parent(undef);
- return 1; } }
- die "Didn't find $orig in $parent";
-}
-
-sub html_replace_by_meta ( $;$ )
-{ my ($orig, $parent) = check_args_range(1, 2, @_);
- my $meta = new HTML::Element "meta";
- if (!defined $parent)
- { $parent = $orig->parent; }
- return html_replace($orig, $meta, $parent);
-}
-
-sub html_replace_by_ignore ( $;$ )
-{ my ($orig, $parent) = check_args_range(1, 2, @_);
- my $ignore = new HTML::Element "ignore";
- if (!defined $parent)
- { $parent = $orig->parent; }
- return html_replace($orig, $ignore, $parent);
-}
-
-
-
-###
-### Collect text elements
-###
-
-my @collected_texts;
-my $collect_texts_stoppoint;
-my $done_collecting;
-
-sub collect_texts ( $;$ )
-{ my ($root, $stop) = check_args_range(1, 2, @_);
- # print STDERR "collect_texts: $root $stop\n";
- $collect_texts_stoppoint = $stop;
- $done_collecting = 0;
- @collected_texts = ();
- $root->traverse(\&collect_if_text); # process texts
- # print STDERR "collect_texts => ", join(";;;", @collected_texts), "\n";
- return @collected_texts;
-}
-
-sub collect_if_text ( $$$ )
-{ my $he = (check_args(3, @_))[0]; # ignore depth and startflag arguments
- if ($done_collecting)
- { return 0; }
- if (!defined $he)
- { return 0; }
- if (!ref $he)
- { push @collected_texts, $he;
- return 0; }
- if ((defined $collect_texts_stoppoint) && ($he eq $collect_texts_stoppoint))
- { $done_collecting = 1;
- return 0; }
- return 1;
-}
-
-
-###########################################################################
-### Clean up parse tree
-###
-
-sub cleanup_parse_tree ( $ )
-{ my ($he) = check_args(1, @_);
- $he->traverse(\&delete_if_navigation, 'ignore text');
- $he->traverse(\&delete_extra_spaces, 'ignore text');
- $he->traverse(\&merge_dl, 'ignore text');
- $he->traverse(\&reorder_dt_and_dl, 'ignore text');
- return $he;
-}
-
-
-## Simpler version that deletes contents but not the element itself.
-# sub delete_if_navigation ( $$$ )
-# { my $he = (check_args(3, @_))[0]; # ignore startflag and depth
-# if (($he->tag() eq "div") && ($he->attr('class') eq 'navigation'))
-# { $he->delete();
-# return 0; }
-# else
-# { return 1; }
-# }
-
-sub delete_if_navigation ( $$$ )
-{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
- if (!$startflag)
- { return; }
-
- if (($he->tag() eq "div") && (defined $he->attr('class')) && ($he->attr('class') eq 'navigation'))
- { my $ref_pcontent = $he->parent()->content();
- # Don't try to modify @pcontent, which appears to be a COPY.
- # my @pcontent = @{$ref_pcontent};
- for (my $i = 0; $i<scalar(@{$ref_pcontent}); $i++)
- { if (${$ref_pcontent}[$i] eq $he)
- { splice(@{$ref_pcontent}, $i, 1);
- last; } }
- $he->delete();
- return 0; }
- else
- { return 1; }
-}
-
-sub delete_extra_spaces ( $$$ )
-{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
- if (!$startflag)
- { return; }
-
- my $tag = $he->tag;
- if ($tag =~ /^(head|html|table|tr|ul)$/)
- { delete_child_spaces($he); }
- delete_trailing_spaces($he);
- return 1;
-}
-
-
-sub delete_child_spaces ( $ )
-{ my ($he) = check_args(1, @_);
- my $ref_content = $he->content();
- for (my $i = 0; $i<scalar(@{$ref_content}); $i++)
- { if ($ {$ref_content}[$i] =~ /^ *$/)
- { splice(@{$ref_content}, $i, 1);
- $i--; } }
-}
-
-sub delete_trailing_spaces ( $ )
-{ my ($he) = check_args(1, @_);
- my $ref_content = $he->content();
- if (! defined $ref_content)
- { return; }
- # Could also check for previous element = /^h[1-6]$/.
- for (my $i = 0; $i<scalar(@{$ref_content})-1; $i++)
- { if ($ {$ref_content}[$i] =~ /^ *$/)
- { my $next_elt = $ {$ref_content}[$i+1];
- if ((ref $next_elt) && ($next_elt->tag =~ /^(br|dd|dl|dt|hr|p|ul)$/))
- { splice(@{$ref_content}, $i, 1);
- $i--; } } }
- if ($he->tag =~ /^(dd|dt|^h[1-6]|li|p)$/)
- { my $last_elt = $ {$ref_content}[$#{$ref_content}];
- if ((defined $last_elt) && ($last_elt =~ /^ *$/))
- { pop @{$ref_content}; } }
-}
-
-
-# LaTeX2HTML sometimes creates
-# <DT>text
-# <DL COMPACT><DD>text
-# which should actually be:
-# <DL COMPACT>
-# <DT>text
-# <DD>text
-# Since a <DL> gets added, this ends up looking like
-# <P>
-# <DL>
-# <DT>
-# text1...
-# <DL COMPACT>
-# <DD>
-# text2...
-# dt_or_dd1...
-# dt_or_dd2...
-# which should become
-# <P>
-# <DL COMPACT>
-# <DT>
-# text1...
-# <DD>
-# text2...
-# dt_or_dd1...
-# dt_or_dd2...
-
-sub reorder_dt_and_dl ( $$$ )
-{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
- if (!$startflag)
- { return; }
-
- if ($he->tag() eq "p")
- { my $ref_pcontent = $he->content();
- if (defined $ref_pcontent)
- { my @pcontent = @{$ref_pcontent};
- # print "reorder_dt_and_dl found a <p>\n"; $he->dump();
- if ((scalar(@pcontent) >= 1)
- && (ref $pcontent[0]) && ($pcontent[0]->tag() eq "dl")
- && $pcontent[0]->implicit())
- { my $ref_dlcontent = $pcontent[0]->content();
- # print "reorder_dt_and_dl found a <p> and implicit <dl>\n";
- if (defined $ref_dlcontent)
- { my @dlcontent = @{$ref_dlcontent};
- if ((scalar(@dlcontent) >= 1)
- && (ref $dlcontent[0]) && ($dlcontent[0]->tag() eq "dt"))
- { my $ref_dtcontent = $dlcontent[0]->content();
- # print "reorder_dt_and_dl found a <p>, implicit <dl>, and <dt>\n";
- if (defined $ref_dtcontent)
- { my @dtcontent = @{$ref_dtcontent};
- if ((scalar(@dtcontent) > 0)
- && (ref $dtcontent[$#dtcontent])
- && ($dtcontent[$#dtcontent]->tag() eq "dl"))
- { my $ref_dl2content = $dtcontent[$#dtcontent]->content();
- # print "reorder_dt_and_dl found a <p>, implicit <dl>, <dt>, and <dl>\n";
- if (defined $ref_dl2content)
- { my @dl2content = @{$ref_dl2content};
- if ((scalar(@dl2content) > 0)
- && (ref ($dl2content[0]))
- && ($dl2content[0]->tag() eq "dd"))
- {
- # print "reorder_dt_and_dl found a <p>, implicit <dl>, <dt>, <dl>, and <dd>\n";
- # print STDERR "CHANGING\n"; $he->dump();
- html_replace_by_ignore($dtcontent[$#dtcontent]);
- splice(@{$ref_dlcontent}, 1, 0, @dl2content);
- # print STDERR "CHANGED TO:\n"; $he->dump();
- return 0; # don't traverse children
- } } } } } } } } }
- return 1;
-}
-
-
-# If we find a paragraph that looks like
-# <P>
-# <HR>
-# <UL>
-# then accumulate its links into a contents_list and delete the paragraph.
-sub process_if_child_links ( $$$ )
-{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
- if (!$startflag)
- { return; }
-
- if ($he->tag() eq "p")
- { my $ref_content = $he->content();
- if (defined $ref_content)
- { my @content = @{$ref_content};
- if ((scalar(@content) == 2)
- && (ref $content[0]) && $content[0]->tag() eq "hr"
- && (ref $content[1]) && $content[1]->tag() eq "ul")
- { process_child_links($he);
- $he->delete();
- return 0; } } }
- return 1;
-}
-
-
-# If we find
-# <H4>
-# "Footnotes"
-# <DL>
-# <DT>
-# <A NAME="foot560">
-# "...borrow"
-# <A HREF="refcountsInPython.html#tex2html2" NAME="foot560">
-# "1.2"
-# <DD>
-# "The metaphor of ``borrowing'' a reference is not completely correct: the owner still has a copy of the reference. "
-# ...
-# then record the footnote information and delete the section and list.
-
-my $process_if_footnotes_expect_dl_next = 0;
-
-sub process_if_footnotes ( $$$ )
-{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
- if (!$startflag)
- { return; }
-
- if (($he->tag() eq "h4")
- && has_single_content_string($he)
- && ($ {$he->content}[0] eq "Footnotes"))
- { html_replace_by_ignore($he);
- $process_if_footnotes_expect_dl_next = 1;
- return 0; }
-
- if ($process_if_footnotes_expect_dl_next && ($he->tag() eq "dl"))
- { my $ref_content = $he->content();
- if (defined $ref_content)
- { $process_if_footnotes_expect_dl_next = 0;
- my @content = @{$ref_content};
- for (my $i=0; $i<$#content; $i+=2)
- { my $he_dt = $content[$i];
- my $he_dd = $content[$i+1];
- if (($he_dt->tag ne "dt") || ($he_dd->tag ne "dd"))
- { $he->dump;
- die "expected <DT> and <DD> at positions $i and ", $i+1; }
- my @dt_content = @{$he_dt->content()};
- if ((scalar(@dt_content) != 2)
- || ($dt_content[0]->tag ne "a")
- || ($dt_content[1]->tag ne "a"))
- { $he_dt->dump;
- die "Expected 2 anchors as content of <DT>"; }
- my ($dt1_name, $dt1_href, $dt1_content) = anchor_info($dt_content[0]);
- my ($dt2_name, $dt2_href, $dt2_content) = anchor_info($dt_content[0]);
- # unused: $dt1_href, $dt1_content, $dt2_href, $dt2_content
- if ($dt1_name ne $dt2_name)
- { $he_dt->dump;
- die "Expected identical names for anchors"; }
- html_replace_by_ignore($he_dd);
- $he_dd->tag("div"); # has no effect
- $footnotes{$dt1_name} = $he_dd; }
- html_replace_by_ignore($he);
- return 0; } }
-
- if ($process_if_footnotes_expect_dl_next)
- { $he->dump;
- die "Expected <DL> for footnotes next"; }
-
- return 1;
-}
-
-
-
-## Merge two adjacent paragraphs containing <DL> items, such as:
-# <P>
-# <DL>
-# <DT>
-# ...
-# <DD>
-# ...
-# <P>
-# <DL>
-# <DT>
-# ...
-# <DD>
-# ...
-
-sub merge_dl ( $$$ )
-{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
- if (!$startflag)
- { return; }
-
- my $ref_content = $he->content;
- if (!defined $ref_content)
- { return; }
- my $i = 0;
- while ($i < scalar(@{$ref_content})-1)
- { my $p1 = $ {$ref_content}[$i];
- if ((ref $p1) && ($p1->tag eq "p")
- && has_single_content_with_tag($p1, "dl"))
- { my $dl1 = $ {$p1->content}[0];
- # In this loop, rhs, not lhs, of < comparison changes,
- # because we are removing elements from the content of $he.
- while ($i < scalar(@{$ref_content})-1)
- { my $p2 = $ {$ref_content}[$i+1];
- if (!((ref $p2) && ($p2->tag eq "p")
- && has_single_content_with_tag($p2, "dl")))
- { last; }
- # Merge these two elements.
- splice(@{$ref_content}, $i+1, 1); # remove $p2
- my $dl2 = $ {$p2->content}[0];
- $dl1->push_content(@{$dl2->content}); # put $dl2's content in $dl1
- }
- # extra increment because next element isn't a candidate for $p1
- $i++; }
- $i++; }
- return 1;
-}
-
-
-
-###########################################################################
-### Testing
-###
-
-sub test ( $$ )
-{ my ($action, $file) = check_args(2, @_);
-
- # General testing
- if (($action eq "view") || ($action eq ""))
- { # # $file = "/homes/gws/mernst/www/links.html";
- # # $file = "/homes/gws/mernst/www/index.html";
- # # $file = "/homes/fish/mernst/java/gud/doc/manual.html";
- # # $file = "/projects/cecil/cecil/doc/manuals/stdlib-man/stdlib/stdlib.html";
- # # $file = "/homes/fish/mernst/tmp/python-doc/html/index.html";
- # $file = "/homes/fish/mernst/tmp/python-doc/html/api/complexObjects.html";
- my $tree = file_to_tree($file);
-
- ## Testing
- # print STDERR $tree->as_HTML;
- $tree->dump();
-
- # print STDERR $tree->tag(), "\n";
- # print STDERR @{$tree->content()}, "\n";
- #
- # for (@{ $tree->extract_links(qw(a img)) }) {
- # my ($link, $linkelem) = @$_;
- # print STDERR "$link ", $linkelem->as_HTML;
- # }
- #
- # print STDERR @{$tree->extract_links()}, "\n";
-
- # my @top_level_elts = @{$tree->content()};
-
- # if scalar(@{$tree->content()})
- return;
- }
-
- elsif ($action eq "raw")
- { my $tree = new HTML::TreeBuilder;
- $tree->ignore_unknown(1);
- # $tree->warn(1);
- $tree->parse_file($file);
-
- $tree->dump();
-
- # cleanup_parse_tree($tree);
- # $tree->dump();
- return;
- }
-
- # Test dealing with a section.
- elsif ($action eq "section")
- { # my $file;
- # $file = "/homes/fish/mernst/tmp/python-doc/html/api/intro.html";
- # $file = "/homes/fish/mernst/tmp/python-doc/html/api/includes.html";
- # $file = "/homes/fish/mernst/tmp/python-doc/html/api/complexObjects.html";
- process_section_file($file, 0, "Title");
- }
-
- # Test dealing with many sections
- elsif (0)
- { my @files = ("/homes/fish/mernst/tmp/python-doc/html/api/about.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/abstract.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/api.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/cObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/complexObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/concrete.html",
- # "/homes/fish/mernst/tmp/python-doc/html/api/contents.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/countingRefs.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/debugging.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/dictObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/embedding.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/exceptionHandling.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/exceptions.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/fileObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/floatObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/front.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/fundamental.html",
- # "/homes/fish/mernst/tmp/python-doc/html/api/genindex.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/importing.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/includes.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/index.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/initialization.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/intObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/intro.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/listObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/longObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/mapObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/mapping.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/newTypes.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/node24.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/noneObject.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/number.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/numericObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/object.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/objects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/os.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/otherObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/processControl.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/refcountDetails.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/refcounts.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/sequence.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/sequenceObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/standardExceptions.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/stringObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/threads.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/tupleObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/typeObjects.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/types.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/utilities.html",
- "/homes/fish/mernst/tmp/python-doc/html/api/veryhigh.html");
- for my $file (@files)
- { print STDERR "\n", "=" x 75, "\n", "$file:\n";
- process_section_file($file, 0, "Title");
- }
- }
-
- # Test dealing with index.
- elsif ($action eq "index")
- { # my $file;
- # $file = "/homes/fish/mernst/tmp/python-doc/html/api/genindex.html";
-
- process_index_file($file, "\@cindex");
- print_index_info();
- }
-
- else
- { die "Unrecognized action `$action'"; }
-}
-
-
-###########################################################################
-### Main loop
-###
-
-sub process_contents_file ( $ )
-{ my ($file) = check_args(1, @_);
-
- # could also use File::Basename
- my $info_file = $file;
- $info_file =~ s/(\/?index)?\.html$//;
- if ($info_file eq "")
- { chomp($info_file = `pwd`); }
- $info_file =~ s/^.*\///; # not the most efficient way to remove dirs
-
- $html_directory = $file;
- $html_directory =~ s/(\/|^)[^\/]+$/$1/;
-
- my $texi_file = "$info_file.texi";
- open(TEXI, ">$texi_file");
-
- print TEXI "\\input texinfo \@c -*-texinfo-*-\n";
- print TEXI "\@c %**start of header\n";
- print TEXI "\@setfilename $info_file\n";
-
- # 2. Summary Description and Copyright
- # The "Summary Description and Copyright" segment describes the
- # document and contains the copyright notice and copying permissions
- # for the Info file. The segment must be enclosed between `@ifinfo'
- # and `@end ifinfo' commands so that the formatters place it only in
- # the Info file.
- #
- # The summary description and copyright segment does not appear in the
- # printed document.
- #
- # @ifinfo
- # This is a short example of a complete Texinfo file.
- #
- # Copyright @copyright{} 1990 Free Software Foundation, Inc.
- # @end ifinfo
-
-
- # 3. Title and Copyright
- # The "Title and Copyright" segment contains the title and copyright
- # pages and copying permissions for the printed manual. The segment
- # must be enclosed between `@titlepage' and `@end titlepage'
- # commands. The title and copyright page appear only in the printed
- # manual.
- #
- # The titlepage segment does not appear in the Info file.
- #
- # @titlepage
- # @sp 10
- # @comment The title is printed in a large font.
- # @center @titlefont{Sample Title}
- #
- # @c The following two commands start the copyright page.
- # @page
- # @vskip 0pt plus 1filll
- # Copyright @copyright{} 1990 Free Software Foundation, Inc.
- # @end titlepage
-
-
- # 4. `Top' Node and Master Menu
- # The "Master Menu" contains a complete menu of all the nodes in the
- # whole Info file. It appears only in the Info file, in the `Top'
- # node.
- #
- # The `Top' node contains the master menu for the Info file. Since a
- # printed manual uses a table of contents rather than a menu, the master
- # menu appears only in the Info file.
- #
- # @node Top, First Chapter, , (dir)
- # @comment node-name, next, previous, up
- #
- # @menu
- # * First Chapter:: The first chapter is the
- # only chapter in this sample.
- # * Concept Index:: This index has two entries.
- # @end menu
-
-
-
- $current_ref_tdf = [ "Top", 0, $ARGV[0] ];
- process_section_file($file, 0, "Top");
- while (scalar(@contents_list))
- { $current_ref_tdf = shift @contents_list;
- process_section_file($ {$current_ref_tdf}[2], $ {$current_ref_tdf}[1], $ {$current_ref_tdf}[0]);
- }
-
- print TEXI "\n";
- for my $indextitle (@index_titles)
- { print TEXI "\@node $indextitle\n";
- print TEXI "\@unnumbered $indextitle\n";
- print TEXI "\@printindex $ {$index_info{$indextitle}}[1]\n";
- print TEXI "\n"; }
-
- print TEXI "\@contents\n";
- print TEXI "\@bye\n";
- close(TEXI);
-}
-
-# This needs to be last so global variable initializations are reached.
-
-if (scalar(@ARGV) == 0)
-{ die "No arguments supplied to html2texi.pl"; }
-
-if ($ARGV[0] eq "-test")
-{ my @test_args = @ARGV[1..$#ARGV];
- if (scalar(@test_args) == 0)
- { test("", "index.html"); }
- elsif (scalar(@test_args) == 1)
- { test("", $test_args[0]); }
- elsif (scalar(@test_args) == 2)
- { test($test_args[0], $test_args[1]); }
- else
- { die "Too many test arguments passed to html2texi: ", join(" ", @ARGV); }
- exit();
-}
-
-if (scalar(@ARGV) != 1)
-{ die "Pass one argument, the main/contents page"; }
-
-process_contents_file($ARGV[0]);
-
-# end of html2texi.pl
diff --git a/Doc/tools/indfix.py b/Doc/tools/indfix.py
deleted file mode 100755
index 23f9e17..0000000
--- a/Doc/tools/indfix.py
+++ /dev/null
@@ -1,100 +0,0 @@
-#! /usr/bin/env python
-
-"""Combine similar index entries into an entry and subentries.
-
-For example:
-
- \item {foobar} (in module flotz), 23
- \item {foobar} (in module whackit), 4323
-
-becomes
-
- \item {foobar}
- \subitem in module flotz, 23
- \subitem in module whackit, 4323
-
-Note that an item which matches the format of a collapsable item but which
-isn't part of a group of similar items is not modified.
-"""
-__version__ = '$Revision$'
-
-import re
-import io
-import sys
-
-
-def cmp_entries(e1, e2):
- return cmp(e1[1].lower(), e2[1].lower()) or cmp(e1, e2)
-
-
-def dump_entries(write, entries):
- if len(entries) == 1:
- write(" \\item %s (%s)%s\n" % entries[0])
- return
- write(" \item %s\n" % entries[0][0])
- # now sort these in a case insensitive manner:
- if len(entries) > 0:
- entries.sort(cmp_entries)
- for xxx, subitem, pages in entries:
- write(" \subitem %s%s\n" % (subitem, pages))
-
-
-breakable_re = re.compile(
- r" \\item (.*) [(](.*)[)]((?:(?:, \d+)|(?:, \\[a-z]*\{\d+\}))+)")
-
-
-def process(ifn, ofn=None):
- if ifn == "-":
- ifp = sys.stdin
- else:
- ifp = open(ifn)
- if ofn is None:
- ofn = ifn
- ofp = io.StringIO()
- entries = []
- match = breakable_re.match
- write = ofp.write
- while 1:
- line = ifp.readline()
- if not line:
- break
- m = match(line)
- if m:
- entry = m.group(1, 2, 3)
- if entries and entries[-1][0] != entry[0]:
- dump_entries(write, entries)
- entries = []
- entries.append(entry)
- elif entries:
- dump_entries(write, entries)
- entries = []
- write(line)
- else:
- write(line)
- del write
- del match
- ifp.close()
- data = ofp.getvalue()
- ofp.close()
- if ofn == "-":
- ofp = sys.stdout
- else:
- ofp = open(ofn, "w")
- ofp.write(data)
- ofp.close()
-
-
-def main():
- import getopt
- outfile = None
- opts, args = getopt.getopt(sys.argv[1:], "o:")
- for opt, val in opts:
- if opt in ("-o", "--output"):
- outfile = val
- filename = args[0]
- outfile = outfile or filename
- process(filename, outfile)
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/keywords.py b/Doc/tools/keywords.py
deleted file mode 100644
index f9e4b03..0000000
--- a/Doc/tools/keywords.py
+++ /dev/null
@@ -1,25 +0,0 @@
-#! /usr/bin/env python
-
-# This Python program sorts and reformats the table of keywords in ref2.tex
-
-def raw_input(prompt):
- import sys
- sys.stdout.write(prompt)
- sys.stdout.flush()
- return sys.stdin.readline()
-
-l = []
-try:
- while 1:
- l = l + raw_input().split()
-except EOFError:
- pass
-l.sort()
-for x in l[:]:
- while l.count(x) > 1: l.remove(x)
-ncols = 5
-nrows = (len(l)+ncols-1)/ncols
-for i in range(nrows):
- for j in range(i, len(l), nrows):
- print(l[j].ljust(10), end=' ')
- print()
diff --git a/Doc/tools/listmodules b/Doc/tools/listmodules
deleted file mode 100755
index a60496b..0000000
--- a/Doc/tools/listmodules
+++ /dev/null
@@ -1,182 +0,0 @@
-#! /usr/bin/env python
-# -*- Python -*-
-#
-# This script can be used to identify undocumented modules in the Python
-# standard library. Use it like this:
-#
-# .../Doc/tools/listmodules --ignore-from .../Doc/paper-<paper>/modlib.idx
-
-"""%(program)s - list modules in the Python standard library
-
--a, --annotate Annotate the module names with the subdirectory they
- live in
--c, --categorize Group the modules by subdirectory
--i <file>,
-
---ignore-from <file> Ignore the modules listed in <file>. <file> may
- contain a list of module names or a module index file
- as produced when formatting the Python documentation
- (.idx or .html flavor).
-
-If neither -a nor -c are given, the modules are listed in alphabetical
-order.
-
-Note that -a and -c are mutually exclusive.
-
-Limitation: Modules loadable as shared objects may not be listed,
-though this script attempts to locate such modules.
-
-"""
-
-__version__ = '$Revision$'
-
-import getopt
-import glob
-import os
-import re
-import sys
-
-
-REMOVE_DIRS = ["encodings", "distutils",
- "lib-old", ""test"]
-
-
-def main():
- args = sys.argv[1:]
- annotate = 0
- builtin = 0
- categorize = 0
- ignore_dict = {}
- ignore = ignore_dict.has_key
- try:
- opts, args = getopt.getopt(
- args, "abchi:",
- ["annotate", "built-in", "categorize", "help", "ignore-from="])
- except getopt.error as msg:
- sys.stdout = sys.stderr
- print msg
- print
- usage()
- sys.exit(2)
- for opt, arg in opts:
- if opt in ("-a", "--annotate"):
- annotate = 1
- elif opt in ("-b", "--built-in"):
- builtin = 1
- elif opt in ("-c", "--categorize"):
- categorize = 1
- elif opt in ("-h", "--help"):
- usage()
- sys.exit()
- elif opt in ("-i", "--ignore-from"):
- data = open(arg).read()
- if data[:1] == "\\":
- ignore_from_idx(data, ignore_dict)
- else:
- ignore_from_modulelist(data, ignore_dict)
- if args or (annotate and categorize):
- usage()
- sys.exit(2)
- #
- # Populate the database:
- #
- srcdir = os.path.normpath(os.path.join(
- os.path.dirname(sys.argv[0]), os.pardir, os.pardir))
- os.chdir(srcdir)
- modules_by_name = {}
- modules_by_dir = {}
- if builtin:
- l = []
- modules_by_dir["<builtin>"] = l
- for name in sys.builtin_module_names:
- if not ignore(name):
- modules_by_name[name] = "<built-in>"
- l.append(name)
- rx = re.compile("Lib/plat-[a-zA-Z0-9]*/")
- fp = os.popen("find Lib -name \*.py -print", "r")
- while 1:
- line = fp.readline()
- if not line:
- break
- m = rx.match(line)
- if m:
- line = "Lib/plat-*/" + line[m.end():]
- line = line[4:-4] # strip off 'Lib/' and '.py\n'
- dir, name = os.path.split(line)
- dir = dir or "<standard>"
- if ignore(name):
- continue
- if dir not in REMOVE_DIRS:
- modules_by_name[name] = dir
- l = modules_by_dir.get(dir, [])
- modules_by_dir[dir] = l
- if name not in l:
- l.append(name)
- # load up extension modules:
- pwd = os.getcwd()
- try:
- os.chdir("Modules")
- dir = "<extension>"
- for line in glob.glob("*module.c"):
- name = line[:-8]
- if ignore(name) or modules_by_name.has_key(name) or name == "xx":
- continue
- modules_by_name[name] = dir
- l = modules_by_dir.get(dir, [])
- modules_by_dir[dir] = l
- if name not in l:
- l.append(name)
- finally:
- os.chdir(pwd)
- #
- # Dump the results:
- #
- if annotate:
- modules = modules_by_name.items()
- modules.sort()
- width = max(map(len, modules_by_name.keys()))
- format = "%%-%ds %%s" % width
- for name, dir in modules:
- if dir and dir[0] != "<":
- print format % (name, dir)
- else:
- print name
- elif categorize:
- modules = modules_by_dir.items()
- modules.sort()
- width = max(map(len, modules_by_dir.keys()))
- format = "%%-%ds %%s" % width
- for dir, names in modules:
- names.sort()
- print format % (dir, names[0])
- for name in names[1:]:
- print format % ('', name)
- print
- else:
- modules = modules_by_name.keys()
- modules.sort()
- print "\n".join(modules)
-
-
-def ignore_from_modulelist(data, ignore_dict):
- for name in data.split():
- ignore_dict[name] = name
-
-def ignore_from_idx(data, ignore_dict):
- data = data.replace(r"\hackscore {}", "_")
- rx = re.compile(r"\\indexentry\s*{([^@]*)@")
- for line in data.split("\n"):
- m = rx.match(line)
- if m:
- name = m.group(1)
- ignore_dict[name] = name
-
-
-def usage():
- vars = {}
- vars["program"] = os.path.basename(sys.argv[0])
- print __doc__ % vars
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/listmodules.py b/Doc/tools/listmodules.py
deleted file mode 100644
index 8acdf43..0000000
--- a/Doc/tools/listmodules.py
+++ /dev/null
@@ -1,125 +0,0 @@
-# $Id$
-#
-# Locate all standard modules available in this build.
-#
-# This script is designed to run on Python 1.5.2 and newer.
-#
-# Written by Fredrik Lundh, January 2005
-#
-
-import imp, sys, os, re, time
-
-identifier = "python-%s-%s" % (sys.version[:3], sys.platform)
-timestamp = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime(time.time()))
-
-# known test packages
-TEST_PACKAGES = "test.", "bsddb.test.", "distutils.tests."
-
-try:
- import platform
- platform = platform.platform()
-except:
- platform = None # unknown
-
-suffixes = imp.get_suffixes()
-
-def get_suffix(file):
- for suffix in suffixes:
- if file[-len(suffix[0]):] == suffix[0]:
- return suffix
- return None
-
-def main():
-
- path = getpath()
-
- modules = {}
- for m in sys.builtin_module_names:
- modules[m] = None
-
- for p in path:
- modules.update(getmodules(p))
-
- keys = sorted(modules.keys())
-
- # filter out known test packages
- def cb(m):
- for d in TEST_PACKAGES:
- if m[:len(d)] == d:
- return 0
- return 1
- keys = filter(cb, keys)
-
- try:
- outfile = sys.argv[1]
- if outfile == "-":
- outfile = None
- elif outfile == "-f":
- outfile = "modules-" + identifier + ".txt"
- except IndexError:
- outfile = None
-
- if not outfile:
- out = sys.stdout
- else:
- out = open(outfile, "w")
-
- out.write("# module list (generated by listmodules.py)\n")
- out.write("#\n")
- out.write("# timestamp=%s\n" % repr(timestamp))
- out.write("# sys.version=%s\n" % repr(sys.version))
- out.write("# sys.platform=%s\n" % repr(sys.platform))
- if platform:
- out.write("# platform=%s\n" % repr(platform))
- out.write("#\n")
-
- for k in keys:
- out.write(k + "\n")
-
- if out is not sys.stdout:
- out.close()
- print(out.name, "ok (%d modules)" % len(modules))
-
-def getmodules(p):
- # get modules in a given directory
- modules = {}
- for f in os.listdir(p):
- f = os.path.join(p, f)
- if os.path.isfile(f):
- m, e = os.path.splitext(f)
- suffix = get_suffix(f)
- if not suffix:
- continue
- m = os.path.basename(m)
- if re.compile("(?i)[a-z_]\w*$").match(m):
- if suffix[2] == imp.C_EXTENSION:
- # check that this extension can be imported
- try:
- __import__(m)
- except ImportError:
- continue
- modules[m] = f
- elif os.path.isdir(f):
- m = os.path.basename(f)
- if os.path.isfile(os.path.join(f, "__init__.py")):
- for mm, f in getmodules(f).items():
- modules[m + "." + mm] = f
- return modules
-
-def getpath():
- path = map(os.path.normcase, map(os.path.abspath, sys.path[:]))
- # get rid of site packages
- for p in path:
- if p[-13:] == "site-packages":
- def cb(p, site_package_path=os.path.abspath(p)):
- return p[:len(site_package_path)] != site_package_path
- path = filter(cb, path)
- break
- # get rid of non-existent directories and the current directory
- def cb(p, cwd=os.path.normcase(os.getcwd())):
- return os.path.isdir(p) and p != cwd
- path = filter(cb, path)
- return path
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/makesec.sh b/Doc/tools/makesec.sh
deleted file mode 100755
index 6159d6f..0000000
--- a/Doc/tools/makesec.sh
+++ /dev/null
@@ -1,129 +0,0 @@
-#!/bin/sh
-
-# Simple little checker for individual libref manual sections
-#
-# usage: makesec.sh section
-#
-
-# This script builds the minimal file necessary to run a single section
-# through latex, does so, then converts the resulting dvi file to ps or pdf
-# and feeds the result into a viewer. It's by no means foolproof, but seems
-# to work okay for me (knock wood). It sure beats manually commenting out
-# most of the man lib.tex file and running everything manually.
-
-# It attempts to locate an appropriate dvi converter and viewer for the
-# selected output format. It understands the following environment
-# variables:
-#
-# PYSRC - refers to the root of your build tree (dir containing Doc)
-# DVICVT - refers to a dvi converter like dvips or dvipdf
-# VIEWER - refers to an appropriate viewer for the ps/pdf file
-#
-# Of the three, only PYSRC is currently required. The other two can be set
-# to specify unusual tools which perform those tasks.
-
-# Known issues:
-# - It would be nice if the script could determine PYSRC on its own.
-# - Something about \seealso{}s blows the latex stack, so they need
-# to be commented out for now.
-
-if [ x$PYSRC = x ] ; then
- echo "PYSRC must refer to the Python source tree" 1>&2
- exit 1
-fi
-
-if [ ! -d $PYSRC/Doc ] ; then
- echo "Can't find a Doc subdirectory in $PYSRC" 1>&2
- exit 1
-fi
-
-if [ "$#" -ne 1 ] ; then
- echo "Must specify a single libref manual section on cmd line" 1>&2
- exit 1
-fi
-
-# settle on a dvi converter
-if [ x$DVICVT != x ] ; then
- converter=$DVICVT
- ext=`echo $DVICVT | sed -e 's/^dvi//'`
- result=lib.$ext
-elif [ x`which dvipdf` != x ] ; then
- converter=`which dvipdf`
- ext=.pdf
-elif [ x`which dvips` != x ] ; then
- converter=`which dvips`
- ext=.ps
-else
- echo "Can't find a reasonable dvi converter" 1>&2
- echo "Set DVICVT to refer to one" 1>&2
- exit 1
-fi
-
-# how about a viewer?
-if [ x$VIEWER != x ] ; then
- viewer=$VIEWER
-elif [ $ext = ".ps" -a x`which gv` != x ] ; then
- viewer=gv
-elif [ $ext = ".ps" -a x`which gs` != x ] ; then
- viewer=gs
-elif [ $ext = ".pdf" -a x`which acroread` != x ] ; then
- viewer=acroread
-elif [ $ext = ".pdf" -a "`uname`" = "Darwin" -a x`which open` != x ] ; then
- viewer=open
-elif [ $ext = ".pdf" -a x`which acroread` != x ] ; then
- viewer=acroread
-else
- echo "Can't find a reasonable viewer" 1>&2
- echo "Set VIEWER to refer to one" 1>&2
- exit 1
-fi
-
-# make sure necessary links are in place
-for f in howto.cls pypaper.sty ; do
- rm -f $f
- ln -s $PYSRC/Doc/$f
-done
-
-export TEXINPUTS=.:$PYSRC/Doc/texinputs:
-
-# strip extension in case they gave full filename
-inp=`basename $1 .tex`
-
-# create the minimal framework necessary to run section through latex
-tmpf=lib.tex
-cat > $tmpf <<EOF
-\documentclass{manual}
-
-% NOTE: this file controls which chapters/sections of the library
-% manual are actually printed. It is easy to customize your manual
-% by commenting out sections that you are not interested in.
-
-\title{Python Library Reference}
-
-\input{boilerplate}
-
-\makeindex % tell \index to actually write the
- % .idx file
-\makemodindex % ... and the module index as well.
-
-
-\begin{document}
-
-\maketitle
-
-\ifhtml
-\chapter*{Front Matter\label{front}}
-\fi
-
-\input{$inp}
-\end{document}
-EOF
-
-latex $tmpf
-
-$converter lib
-
-$viewer lib.pdf
-
-rm -f $tmpf howto.cls pypaper.sty *.idx *.syn
-rm -f lib.aux lib.log
diff --git a/Doc/tools/mkackshtml b/Doc/tools/mkackshtml
deleted file mode 100755
index ac126e0..0000000
--- a/Doc/tools/mkackshtml
+++ /dev/null
@@ -1,65 +0,0 @@
-#! /usr/bin/env python
-# -*- Python -*-
-
-import support
-import sys
-
-
-def collect(fp):
- names = []
- while 1:
- line = fp.readline()
- if not line:
- break
- line = line.strip()
- if line:
- names.append(line)
- else:
- names = []
- return names
-
-
-def main():
- options = support.Options()
- options.columns = 4
- options.variables["title"] = "Acknowledgements"
- options.parse(sys.argv[1:])
- names = collect(sys.stdin)
- percol = (len(names) + options.columns - 1) // options.columns
- colnums = []
- for i in range(options.columns):
- colnums.append(percol*i)
- options.aesop_type = "information"
- fp = options.get_output_file()
- fp.write(options.get_header().rstrip() + "\n")
- fp.write(THANKS + "\n")
- fp.write('<table width="100%" align="center">\n')
- for i in range(percol):
- fp.write(" <tr>\n")
- for j in colnums:
- try:
- fp.write(" <td>%s</td>\n" % names[i + j])
- except IndexError:
- pass
- fp.write(" </tr>\n")
- fp.write("</table>\n")
- fp.write(options.get_footer().rstrip() + "\n")
- fp.close()
-
-THANKS = '''\
-
-<p>These people have contributed in some way to the Python
-documentation. This list is probably not complete -- if you feel that
-you or anyone else should be on this list, please let us know (send
-email to <a
-href="mailto:docs@python.org">docs@python.org</a>), and
-we will be glad to correct the problem.</p>
-
-<p>It is only with the input and contributions of the Python community
-that Python has such wonderful documentation -- <b>Thank You!</b></p>
-
-'''
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/mkhowto b/Doc/tools/mkhowto
deleted file mode 100755
index fa259e0..0000000
--- a/Doc/tools/mkhowto
+++ /dev/null
@@ -1,659 +0,0 @@
-#! /usr/bin/env python
-# -*- Python -*-
-"""usage: %(program)s [options...] file ...
-
-Options specifying formats to build:
- --html HyperText Markup Language (default)
- --pdf Portable Document Format
- --ps PostScript
- --dvi 'DeVice Indepentent' format from TeX
- --text ASCII text (requires lynx)
-
- More than one output format may be specified, or --all.
-
-HTML options:
- --address, -a Specify an address for page footers.
- --dir Specify the directory for HTML output.
- --link Specify the number of levels to include on each page.
- --split, -s Specify a section level for page splitting, default: %(max_split_depth)s.
- --iconserver, -i Specify location of icons (default: ./).
- --image-type Specify the image type to use in HTML output;
- values: gif, png (default).
- --numeric Don't rename the HTML files; just keep node#.html for
- the filenames.
- --style Specify the CSS file to use for the output (filename,
- not a URL).
- --up-link URL to a parent document.
- --up-title Title of a parent document.
- --favicon Icon to display in the browsers location bar.
-
-Other options:
- --a4 Format for A4 paper.
- --letter Format for US letter paper (the default).
- --help, -H Show this text.
- --logging, -l Log stdout and stderr to a file (*.how).
- --debugging, -D Echo commands as they are executed.
- --keep, -k Keep temporary files around.
- --quiet, -q Do not print command output to stdout.
- (stderr is also lost, sorry; see *.how for errors)
-"""
-
-import getopt
-import glob
-import os
-import re
-import shutil
-import sys
-
-
-MYDIR = os.path.abspath(sys.path[0])
-TOPDIR = os.path.dirname(MYDIR)
-
-ISTFILE = os.path.join(TOPDIR, "texinputs", "python.ist")
-NODE2LABEL_SCRIPT = os.path.join(MYDIR, "node2label.pl")
-L2H_INIT_FILE = os.path.join(TOPDIR, "perl", "l2hinit.perl")
-
-BIBTEX_BINARY = "bibtex"
-DVIPS_BINARY = "dvips"
-LATEX_BINARY = "latex"
-LATEX2HTML_BINARY = "latex2html"
-LYNX_BINARY = "lynx"
-MAKEINDEX_BINARY = "makeindex"
-PDFLATEX_BINARY = "pdflatex"
-PERL_BINARY = "perl"
-PYTHON_BINARY = "python"
-
-
-def usage(options, file):
- print(__doc__ % options, file=file)
-
-def error(options, message, err=2):
- print(message, file=sys.stderr)
- print(file=sys.stderr)
- usage(options, sys.stderr)
- sys.exit(2)
-
-
-class Options:
- program = os.path.basename(sys.argv[0])
- #
- address = ''
- builddir = None
- debugging = 0
- discard_temps = 1
- have_temps = 0
- icon_server = "."
- image_type = "png"
- logging = 0
- max_link_depth = 3
- max_split_depth = 6
- paper = "letter"
- quiet = 0
- runs = 0
- numeric = 0
- global_module_index = None
- style_file = os.path.join(TOPDIR, "html", "style.css")
- about_file = os.path.join(TOPDIR, "html", "about.dat")
- up_link = None
- up_title = None
- favicon = None
- #
- # 'dvips_safe' is a weird option. It is used mostly to make
- # LaTeX2HTML not try to be too smart about protecting the user
- # from a bad version of dvips -- some versions would core dump if
- # the path to the source DVI contained a dot, and it's appearantly
- # difficult to determine if the version available has that bug.
- # This option gets set when PostScript output is requested
- # (because we're going to run dvips regardless, and we'll either
- # know it succeeds before LaTeX2HTML is run, or we'll have
- # detected the failure and bailed), or the user asserts that it's
- # safe from the command line.
- #
- # So, why does LaTeX2HTML think it appropriate to protect the user
- # from a dvips that's only potentially going to core dump? Only
- # because they want to avoid doing a lot of work just to have to
- # bail later with no useful intermediates. Unfortunately, they
- # bail *before* they know whether dvips will be needed at all.
- # I've gone around the bush a few times with the LaTeX2HTML
- # developers over whether this is appropriate behavior, and they
- # don't seem interested in changing their position.
- #
- dvips_safe = 0
- #
- DEFAULT_FORMATS = ("html",)
- ALL_FORMATS = ("dvi", "html", "pdf", "ps", "text")
-
- def __init__(self):
- self.formats = []
- self.l2h_init_files = []
-
- def __getitem__(self, key):
- # This is used when formatting the usage message.
- try:
- return getattr(self, key)
- except AttributeError:
- raise KeyError(key)
-
- def parse(self, args):
- opts, args = getopt.getopt(args, "Hi:a:s:lDkqr:",
- ["all", "postscript", "help", "iconserver=",
- "address=", "a4", "letter", "l2h-init=",
- "link=", "split=", "logging", "debugging",
- "keep", "quiet", "runs=", "image-type=",
- "about=", "numeric", "style=", "paper=",
- "up-link=", "up-title=", "dir=",
- "global-module-index=", "dvips-safe",
- "favicon="]
- + list(self.ALL_FORMATS))
- for opt, arg in opts:
- if opt == "--all":
- self.formats = list(self.ALL_FORMATS)
- self.dvips_safe = "ps" in self.formats
- elif opt in ("-H", "--help"):
- usage(self, sys.stdout)
- sys.exit()
- elif opt == "--iconserver":
- self.icon_server = arg
- elif opt in ("-a", "--address"):
- self.address = arg
- elif opt == "--a4":
- self.paper = "a4"
- elif opt == "--letter":
- self.paper = "letter"
- elif opt == "--link":
- self.max_link_depth = int(arg)
- elif opt in ("-s", "--split"):
- self.max_split_depth = int(arg)
- elif opt in ("-l", "--logging"):
- self.logging = self.logging + 1
- elif opt in ("-D", "--debugging"):
- self.debugging = self.debugging + 1
- elif opt in ("-k", "--keep"):
- self.discard_temps = 0
- elif opt in ("-q", "--quiet"):
- self.quiet = 1
- elif opt in ("-r", "--runs"):
- self.runs = int(arg)
- elif opt == "--image-type":
- self.image_type = arg
- elif opt == "--about":
- # always make this absolute:
- self.about_file = os.path.normpath(
- os.path.abspath(arg))
- elif opt == "--numeric":
- self.numeric = 1
- elif opt == "--style":
- self.style_file = os.path.abspath(arg)
- elif opt == "--l2h-init":
- self.l2h_init_files.append(os.path.abspath(arg))
- elif opt == "--favicon":
- self.favicon = arg
- elif opt == "--up-link":
- self.up_link = arg
- elif opt == "--up-title":
- self.up_title = arg
- elif opt == "--global-module-index":
- self.global_module_index = arg
- elif opt == "--dir":
- if os.sep == "\\":
- arg = re.sub("/", "\\\\", arg)
- self.builddir = os.path.expanduser(arg)
- elif opt == "--paper":
- self.paper = arg
- elif opt == "--dvips-safe":
- self.dvips_safe = 1
- #
- # Format specifiers:
- #
- elif opt[2:] in self.ALL_FORMATS:
- self.add_format(opt[2:])
- elif opt == "--postscript":
- # synonym for --ps
- self.add_format("ps")
- self.initialize()
- #
- # return the args to allow the caller access:
- #
- return args
-
- def add_format(self, format):
- """Add a format to the formats list if not present."""
- if not format in self.formats:
- if format == "ps":
- # assume this is safe since we're going to run it anyway
- self.dvips_safe = 1
- self.formats.append(format)
-
- def initialize(self):
- """Complete initialization. This is needed if parse() isn't used."""
- # add the default format if no formats were specified:
- if not self.formats:
- self.formats = self.DEFAULT_FORMATS
- # determine the base set of texinputs directories:
- texinputs = os.environ.get("TEXINPUTS", "").split(os.pathsep)
- if not texinputs:
- texinputs = ['']
- mydirs = [os.path.join(TOPDIR, "paper-" + self.paper),
- os.path.join(TOPDIR, "texinputs"),
- ]
- if '' in texinputs:
- i = texinputs.index('')
- texinputs[i:i] = mydirs
- else:
- texinputs += mydirs
- self.base_texinputs = texinputs
- if self.builddir:
- self.builddir = os.path.abspath(self.builddir)
-
-
-class Job:
- latex_runs = 0
-
- def __init__(self, options, path):
- self.options = options
- self.doctype = get_doctype(path)
- self.filedir, self.doc = split_pathname(path)
- self.builddir = os.path.abspath(options.builddir or self.doc)
- if ("html" in options.formats or "text" in options.formats):
- if not os.path.exists(self.builddir):
- os.mkdir(self.builddir)
- self.log_filename = os.path.join(self.builddir, self.doc + ".how")
- else:
- self.log_filename = os.path.abspath(self.doc + ".how")
- if os.path.exists(self.log_filename):
- os.unlink(self.log_filename)
- l2hconf = self.doc + ".l2h"
- if os.path.exists(l2hconf):
- if os.path.exists(l2hconf + "~"):
- os.unlink(l2hconf + "~")
- os.rename(l2hconf, l2hconf + "~")
- self.l2h_aux_init_file = self.doc + ".l2h"
- self.write_l2h_aux_init_file()
-
- def build(self):
- self.setup_texinputs()
- formats = self.options.formats
- if "dvi" in formats or "ps" in formats:
- self.build_dvi()
- if "pdf" in formats:
- self.build_pdf()
- if "ps" in formats:
- self.build_ps()
- if "html" in formats:
- self.require_temps()
- self.build_html(self.builddir)
- if self.options.icon_server == ".":
- pattern = os.path.join(TOPDIR, "html", "icons",
- "*." + self.options.image_type)
- imgs = glob.glob(pattern)
- if not imgs:
- self.warning(
- "Could not locate support images of type %s."
- % repr(self.options.image_type))
- for fn in imgs:
- new_fn = os.path.join(self.builddir, os.path.basename(fn))
- shutil.copyfile(fn, new_fn)
- if "text" in formats:
- self.require_temps()
- tempdir = self.doc
- need_html = "html" not in formats
- if self.options.max_split_depth != 1:
- fp = open(self.l2h_aux_init_file, "a")
- fp.write("# re-hack this file for --text:\n")
- l2hoption(fp, "MAX_SPLIT_DEPTH", "1")
- fp.write("1;\n")
- fp.close()
- tempdir = self.doc + "-temp-html"
- need_html = 1
- if need_html:
- self.build_html(tempdir, max_split_depth=1)
- self.build_text(tempdir)
- if self.options.discard_temps:
- self.cleanup()
-
- def setup_texinputs(self):
- texinputs = [self.filedir] + self.options.base_texinputs
- os.environ["TEXINPUTS"] = os.pathsep.join(texinputs)
- self.message("TEXINPUTS=" + os.environ["TEXINPUTS"])
-
- def build_aux(self, binary=None):
- if binary is None:
- binary = LATEX_BINARY
- new_index( "%s.ind" % self.doc, "genindex")
- new_index("mod%s.ind" % self.doc, "modindex")
- self.run("%s %s" % (binary, self.doc))
- self.use_bibtex = check_for_bibtex(self.doc + ".aux")
- self.latex_runs = 1
-
- def build_dvi(self):
- self.use_latex(LATEX_BINARY)
-
- def build_pdf(self):
- self.use_latex(PDFLATEX_BINARY)
-
- def use_latex(self, binary):
- self.require_temps(binary=binary)
- if self.latex_runs < 2:
- if os.path.isfile("mod%s.idx" % self.doc):
- self.run("%s mod%s.idx" % (MAKEINDEX_BINARY, self.doc))
- use_indfix = 0
- if os.path.isfile(self.doc + ".idx"):
- use_indfix = 1
- # call to Doc/tools/fix_hack omitted; doesn't appear necessary
- self.run("%s %s.idx" % (MAKEINDEX_BINARY, self.doc))
- import indfix
- indfix.process(self.doc + ".ind")
- if self.use_bibtex:
- self.run("%s %s" % (BIBTEX_BINARY, self.doc))
- self.process_synopsis_files()
- self.run("%s %s" % (binary, self.doc))
- self.latex_runs = self.latex_runs + 1
- if os.path.isfile("mod%s.idx" % self.doc):
- self.run("%s -s %s mod%s.idx"
- % (MAKEINDEX_BINARY, ISTFILE, self.doc))
- if use_indfix:
- self.run("%s -s %s %s.idx"
- % (MAKEINDEX_BINARY, ISTFILE, self.doc))
- indfix.process(self.doc + ".ind")
- self.process_synopsis_files()
- #
- # and now finish it off:
- #
- if os.path.isfile(self.doc + ".toc") and binary == PDFLATEX_BINARY:
- import toc2bkm
- if self.doctype == "manual":
- bigpart = "chapter"
- else:
- bigpart = "section"
- toc2bkm.process(self.doc + ".toc", self.doc + ".bkm", bigpart)
- if self.use_bibtex:
- self.run("%s %s" % (BIBTEX_BINARY, self.doc))
- self.run("%s %s" % (binary, self.doc))
- self.latex_runs = self.latex_runs + 1
-
- def process_synopsis_files(self):
- synopsis_files = glob.glob(self.doc + "*.syn")
- for path in synopsis_files:
- uniqify_module_table(path)
-
- def build_ps(self):
- self.run("%s -N0 -o %s.ps %s" % (DVIPS_BINARY, self.doc, self.doc))
-
- def build_html(self, builddir, max_split_depth=None):
- if max_split_depth is None:
- max_split_depth = self.options.max_split_depth
- texfile = None
- for p in os.environ["TEXINPUTS"].split(os.pathsep):
- fn = os.path.join(p, self.doc + ".tex")
- if os.path.isfile(fn):
- texfile = fn
- break
- if not texfile:
- self.warning("Could not locate %s.tex; aborting." % self.doc)
- sys.exit(1)
- # remove leading ./ (or equiv.); might avoid problems w/ dvips
- if texfile[:2] == os.curdir + os.sep:
- texfile = texfile[2:]
- # build the command line and run LaTeX2HTML:
- if not os.path.isdir(builddir):
- os.mkdir(builddir)
- else:
- for fname in glob.glob(os.path.join(builddir, "*.html")):
- os.unlink(fname)
- args = [LATEX2HTML_BINARY,
- "-init_file", self.l2h_aux_init_file,
- "-dir", builddir,
- texfile
- ]
- self.run(" ".join(args)) # XXX need quoting!
- # ... postprocess
- shutil.copyfile(self.options.style_file,
- os.path.join(builddir, self.doc + ".css"))
- shutil.copyfile(os.path.join(builddir, self.doc + ".html"),
- os.path.join(builddir, "index.html"))
- if max_split_depth != 1:
- label_file = os.path.join(builddir, "labels.pl")
- fp = open(label_file)
- about_node = None
- target = " = q/about/;\n"
- x = len(target)
- while 1:
- line = fp.readline()
- if not line:
- break
- if line[-x:] == target:
- line = fp.readline()
- m = re.search(r"\|(node\d+\.[a-z]+)\|", line)
- about_node = m.group(1)
- shutil.copyfile(os.path.join(builddir, about_node),
- os.path.join(builddir, "about.html"))
- break
- if not self.options.numeric:
- pwd = os.getcwd()
- try:
- os.chdir(builddir)
- self.run("%s %s *.html" % (PERL_BINARY, NODE2LABEL_SCRIPT))
- finally:
- os.chdir(pwd)
- # These files need to be cleaned up here since builddir there
- # can be more than one, so we clean each of them.
- if self.options.discard_temps:
- for fn in ("images.tex", "images.log", "images.aux"):
- safe_unlink(os.path.join(builddir, fn))
-
- def build_text(self, tempdir=None):
- if tempdir is None:
- tempdir = self.doc
- indexfile = os.path.join(tempdir, "index.html")
- self.run("%s -nolist -dump %s >%s.txt"
- % (LYNX_BINARY, indexfile, self.doc))
-
- def require_temps(self, binary=None):
- if not self.latex_runs:
- self.build_aux(binary=binary)
-
- def write_l2h_aux_init_file(self):
- options = self.options
- fp = open(self.l2h_aux_init_file, "w")
- d = string_to_perl(os.path.dirname(L2H_INIT_FILE))
- fp.write("package main;\n"
- "push (@INC, '%s');\n"
- "$mydir = '%s';\n"
- % (d, d))
- fp.write(open(L2H_INIT_FILE).read())
- for filename in options.l2h_init_files:
- fp.write("\n# initialization code incorporated from:\n# ")
- fp.write(filename)
- fp.write("\n")
- fp.write(open(filename).read())
- fp.write("\n"
- "# auxillary init file for latex2html\n"
- "# generated by mkhowto\n"
- "$NO_AUTO_LINK = 1;\n"
- )
- l2hoption(fp, "ABOUT_FILE", options.about_file)
- l2hoption(fp, "ICONSERVER", options.icon_server)
- l2hoption(fp, "IMAGE_TYPE", options.image_type)
- l2hoption(fp, "ADDRESS", options.address)
- l2hoption(fp, "MAX_LINK_DEPTH", options.max_link_depth)
- l2hoption(fp, "MAX_SPLIT_DEPTH", options.max_split_depth)
- l2hoption(fp, "EXTERNAL_UP_LINK", options.up_link)
- l2hoption(fp, "EXTERNAL_UP_TITLE", options.up_title)
- l2hoption(fp, "FAVORITES_ICON", options.favicon)
- l2hoption(fp, "GLOBAL_MODULE_INDEX", options.global_module_index)
- l2hoption(fp, "DVIPS_SAFE", options.dvips_safe)
- fp.write("1;\n")
- fp.close()
-
- def cleanup(self):
- self.__have_temps = 0
- for pattern in ("%s.aux", "%s.log", "%s.out", "%s.toc", "%s.bkm",
- "%s.idx", "%s.ilg", "%s.ind", "%s.pla",
- "%s.bbl", "%s.blg",
- "mod%s.idx", "mod%s.ind", "mod%s.ilg",
- ):
- safe_unlink(pattern % self.doc)
- map(safe_unlink, glob.glob(self.doc + "*.syn"))
- for spec in ("IMG*", "*.pl", "WARNINGS", "index.dat", "modindex.dat"):
- pattern = os.path.join(self.doc, spec)
- map(safe_unlink, glob.glob(pattern))
- if "dvi" not in self.options.formats:
- safe_unlink(self.doc + ".dvi")
- if os.path.isdir(self.doc + "-temp-html"):
- shutil.rmtree(self.doc + "-temp-html", ignore_errors=1)
- if not self.options.logging:
- os.unlink(self.log_filename)
- if not self.options.debugging:
- os.unlink(self.l2h_aux_init_file)
-
- def run(self, command):
- self.message(command)
- if sys.platform.startswith("win"):
- rc = os.system(command)
- else:
- rc = os.system("(%s) </dev/null >>%s 2>&1"
- % (command, self.log_filename))
- if rc:
- self.warning(
- "Session transcript and error messages are in %s."
- % self.log_filename)
- result = 1
- if hasattr(os, "WIFEXITED"):
- if os.WIFEXITED(rc):
- result = os.WEXITSTATUS(rc)
- self.warning("Exited with status %s." % result)
- else:
- self.warning("Killed by signal %s." % os.WSTOPSIG(rc))
- else:
- self.warning("Return code: %s" % rc)
- sys.stderr.write("The relevant lines from the transcript are:\n")
- sys.stderr.write("-" * 72 + "\n")
- sys.stderr.writelines(get_run_transcript(self.log_filename))
- sys.exit(result)
-
- def message(self, msg):
- msg = "+++ " + msg
- if not self.options.quiet:
- print(msg)
- self.log(msg + "\n")
-
- def warning(self, msg):
- msg = "*** %s\n" % msg
- sys.stderr.write(msg)
- self.log(msg)
-
- def log(self, msg):
- fp = open(self.log_filename, "a")
- fp.write(msg)
- fp.close()
-
-
-def get_run_transcript(filename):
- """Return lines from the transcript file for the most recent run() call."""
- fp = open(filename)
- lines = fp.readlines()
- fp.close()
- lines.reverse()
- L = []
- for line in lines:
- L.append(line)
- if line[:4] == "+++ ":
- break
- L.reverse()
- return L
-
-
-def safe_unlink(path):
- """Unlink a file without raising an error if it doesn't exist."""
- try:
- os.unlink(path)
- except os.error:
- pass
-
-
-def split_pathname(path):
- path = os.path.abspath(path)
- dirname, basename = os.path.split(path)
- if basename[-4:] == ".tex":
- basename = basename[:-4]
- return dirname, basename
-
-
-_doctype_rx = re.compile(r"\\documentclass(?:\[[^]]*\])?{([a-zA-Z]*)}")
-def get_doctype(path):
- fp = open(path)
- doctype = None
- while 1:
- line = fp.readline()
- if not line:
- break
- m = _doctype_rx.match(line)
- if m:
- doctype = m.group(1)
- break
- fp.close()
- return doctype
-
-
-def main():
- options = Options()
- try:
- args = options.parse(sys.argv[1:])
- except getopt.error as msg:
- error(options, msg)
- if not args:
- # attempt to locate single .tex file in current directory:
- args = glob.glob("*.tex")
- if not args:
- error(options, "No file to process.")
- if len(args) > 1:
- error(options, "Could not deduce which files should be processed.")
- #
- # parameters are processed, let's go!
- #
- for path in args:
- Job(options, path).build()
-
-
-def l2hoption(fp, option, value):
- if value:
- fp.write('$%s = "%s";\n' % (option, string_to_perl(str(value))))
-
-
-_to_perl = {}
-for c in map(chr, range(1, 256)):
- _to_perl[c] = c
-_to_perl["@"] = "\\@"
-_to_perl["$"] = "\\$"
-_to_perl['"'] = '\\"'
-
-def string_to_perl(s):
- return ''.join(map(_to_perl.get, s))
-
-
-def check_for_bibtex(filename):
- fp = open(filename)
- pos = fp.read().find(r"\bibdata{")
- fp.close()
- return pos >= 0
-
-def uniqify_module_table(filename):
- lines = open(filename).readlines()
- if len(lines) > 1:
- if lines[-1] == lines[-2]:
- del lines[-1]
- open(filename, "w").writelines(lines)
-
-
-def new_index(filename, label="genindex"):
- fp = open(filename, "w")
- fp.write(r"""\
-\begin{theindex}
-\label{%s}
-\end{theindex}
-""" % label)
- fp.close()
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/mkinfo b/Doc/tools/mkinfo
deleted file mode 100755
index be75168..0000000
--- a/Doc/tools/mkinfo
+++ /dev/null
@@ -1,65 +0,0 @@
-#! /bin/sh
-# -*- Ksh -*-
-
-# Script to drive the HTML-info conversion process.
-# Pass in upto three parameters:
-# - the name of the main tex file
-# - the name of the output file in texi format (optional)
-# - the name of the output file in info format (optional)
-#
-# Written by Fred L. Drake, Jr. <fdrake@acm.org>
-
-EMACS=${EMACS:-emacs}
-MAKEINFO=${MAKEINFO:-makeinfo}
-
-
-# Normalize file name since something called by html2texi.pl seems to
-# screw up with relative path names.
-FILENAME="$1"
-DOCDIR=`dirname "$FILENAME"`
-DOCFILE=`basename "$FILENAME"`
-DOCNAME=`basename "$FILENAME" .tex`
-if [ $# -gt 1 ]; then
- TEXINAME="$2"
-else
- TEXINAME="python-$DOCNAME.texi"
-fi
-if [ $# -gt 2 ]; then
- INFONAME="$3"
-else
- INFONAME="python-$DOCNAME.info"
-fi
-
-# Now build the real directory names, and locate our support stuff:
-WORKDIR=`pwd`
-cd `dirname $0`
-TOOLSDIR=`pwd`
-cd $DOCDIR
-DOCDIR=`pwd`
-cd $WORKDIR
-
-COMMONDIR="`dirname $DOCDIR`/commontex"
-
-
-run() {
- # show what we're doing, like make does:
- echo "$*"
- "$@" || exit $?
-}
-
-
-# generate the Texinfo file:
-
-run $EMACS -batch -q --no-site-file -l $TOOLSDIR/py2texi.el \
- --eval "(setq py2texi-dirs '(\"$DOCDIR\" \"$COMMONDIR\" \"../texinputs\"))" \
- --eval "(setq py2texi-texi-file-name \"$TEXINAME\")" \
- --eval "(setq py2texi-info-file-name \"$INFONAME\")" \
- --eval "(py2texi \"$DOCDIR/$DOCFILE\")" \
- -f kill-emacs
-echo Done
-
-
-# generate the .info files:
-
-run $MAKEINFO --footnote-style end --fill-column 72 \
- --paragraph-indent 0 --output=$INFONAME $TEXINAME
diff --git a/Doc/tools/mkmodindex b/Doc/tools/mkmodindex
deleted file mode 100755
index cdc9d42..0000000
--- a/Doc/tools/mkmodindex
+++ /dev/null
@@ -1,158 +0,0 @@
-#! /usr/bin/env python
-# -*- Python -*-
-
-"""usage: %(program)s [options] file...
-
-Supported options:
-
- --address addr
- -a addr Set the address text to include at the end of the generated
- HTML; this should be used for contact information.
- --columns cols
- -c cols Set the number of columns each index section should be
- displayed in. The default is 1.
- --help
- -h Display this help message.
- --letters
- -l Split the output into sections by letter.
- --output file
- -o file Write output to 'file' instead of standard out.
- --iconserver is Use 'is' as the directory containing icons for the
- navigation bar. The default is 'icons'.
- --title str Set the page title to 'str'. The default is 'Global
- Module Index'.
- --uplink url Set the upward link URL. The default is './'.
- --uptitle str Set the upward link title. The default is 'Python
- Documentation Index'.
-"""
-import os
-import re
-import sys
-
-from xml.sax.saxutils import quoteattr
-
-import buildindex
-import support
-
-
-class IndexOptions(support.Options):
- aesop_type = "links"
-
- def __init__(self):
- support.Options.__init__(self)
- self.add_args("l", ["letters"])
- self.letters = 0
-
- def handle_option(self, opt, val):
- if opt in ("-l", "--letters"):
- self.letters = 1
-
- def usage(self):
- program = os.path.basename(sys.argv[0])
- print(__doc__ % {"program": program})
-
- links = [
- ('author', 'acks.html', 'Acknowledgements'),
- ('help', 'about.html', 'About the Python Documentation'),
- ]
-
- def get_header(self):
- header = support.Options.get_header(self)
- s = ''
- for rel, href, title in self.links:
- s += '<link rel="%s" href="%s"' % (rel, href)
- if title:
- s += ' title=' + quoteattr(title)
- s += '>\n '
- return header.replace("<link ", s + "<link ", 1)
-
-
-class Node(buildindex.Node):
- def __init__(self, link, str, seqno, platinfo):
- self.annotation = platinfo or None
- if str[0][-5:] == "</tt>":
- str = str[:-5]
- self.modname = str
- buildindex.Node.__init__(self, link, self.modname, seqno)
- if platinfo:
- s = '<tt class="module">%s</tt> %s' \
- % (self.modname, self.annotation)
- else:
- s = '<tt class="module">%s</tt>' % str
- self.text = [s]
-
- def __str__(self):
- if self.annotation:
- return '<tt class="module">%s</tt> %s' \
- % (self.modname, self.annotation)
- else:
- return '<tt class="module">%s</tt>' % self.modname
-
-_rx = re.compile(
- "<dt><a href=['\"](module-.*\.html)(?:#l2h-\d+)?['\"]>"
- "<tt class=['\"]module['\"]>([a-zA-Z_][a-zA-Z0-9_.]*)</tt>\s*(<em>"
- "\(<span class=['\"]platform['\"]>.*</span>\)</em>)?</a>")
-
-def main():
- options = IndexOptions()
- options.variables["title"] = "Global Module Index"
- options.parse(sys.argv[1:])
- args = options.args
- if not args:
- args = ["-"]
- #
- # Collect the input data:
- #
- nodes = []
- has_plat_flag = 0
- for ifn in args:
- if ifn == "-":
- ifp = sys.stdin
- dirname = ''
- else:
- ifp = open(ifn)
- dirname = os.path.dirname(ifn)
- while 1:
- line = ifp.readline()
- if not line:
- break
- m = _rx.match(line)
- if m:
- # This line specifies a module!
- basename, modname, platinfo = m.group(1, 2, 3)
- has_plat_flag = has_plat_flag or platinfo
- linkfile = os.path.join(dirname, basename)
- nodes.append(Node('<a href="%s">' % linkfile, modname,
- len(nodes), platinfo))
- ifp.close()
- #
- # Generate all output:
- #
- num_nodes = len(nodes)
- # Here's the HTML generation:
- parts = [options.get_header(),
- buildindex.process_nodes(nodes, options.columns, options.letters),
- options.get_footer(),
- ]
- if has_plat_flag:
- parts.insert(1, PLAT_DISCUSS)
- html = ''.join(parts)
- program = os.path.basename(sys.argv[0])
- fp = options.get_output_file()
- fp.write(html.rstrip() + "\n")
- if options.outputfile == "-":
- sys.stderr.write("%s: %d index nodes\n" % (program, num_nodes))
- else:
- print()
- print("%s: %d index nodes" % (program, num_nodes))
-
-
-PLAT_DISCUSS = """
-<p> Some module names are followed by an annotation indicating what
-platform they are available on.</p>
-
-"""
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/mkpkglist b/Doc/tools/mkpkglist
deleted file mode 100755
index 1a1fd78..0000000
--- a/Doc/tools/mkpkglist
+++ /dev/null
@@ -1,85 +0,0 @@
-#! /usr/bin/env python
-#
-# Simple script to create the table that lists the packages available
-# for download. This expects the downloadable files and the Makefile
-# to be in the current directory.
-#
-# The output of this script can be pasted directly into the download
-# page for the documentation.
-
-import os
-import sys
-
-from os.path import isfile
-
-
-PKG_TYPES = [
- # human name, filename prefix
- ("HTML", "html"),
- ("PDF (US-Letter)", "pdf-letter"),
- ("PDF (A4)", "pdf-a4"),
- ("PostScript (US-Letter)", "postscript-letter"),
- ("PostScript (A4)", "postscript-a4"),
- ("GNU info", "info"),
- ("iSilo", "isilo"),
- ("LaTeX", "latex"),
- ]
-
-getversioninfo = os.path.join(os.path.dirname(__file__), "getversioninfo")
-fp = os.popen('"%s" "%s"' % (sys.executable, getversioninfo), "r")
-release = fp.readline().strip()
-fp.close()
-
-print '''\
-<table border="1" cellpadding="3" align="center">
- <thead>
- <tr bgcolor="#99ccff"><th rowspan="2">Content</th>
- <th colspan="3">Format</th></tr>
- <tr bgcolor="#99ccff"><th>ZIP</th><th>GZip</th><th>BZip2</th></tr>
- </thead>
- <tbody>'''
-
-# formatted using FILE_TEMPLATE % (release, prefix, release, extension)
-FILE_TEMPLATE = '''\
- <td><a href="../../ftp/python/doc/%s/%s-%s%s"
- >%dK</a></td>'''
-
-NO_FILE_TEMPLATE = '''\
- <td> </td>'''
-
-def get_size(prefix, ext):
- fn = "%s-%s%s" % (prefix, release, ext)
- return int(round(os.path.getsize(fn) / 1024.0))
-
-def get_file_cell(prefix, ext, have):
- if have:
- kb = get_size(prefix, ext)
- return FILE_TEMPLATE % (release, prefix, release, ext, kb)
- else:
- return NO_FILE_TEMPLATE
-
-for name, prefix in PKG_TYPES:
- zip_fn = "%s-%s.zip" % (prefix, release)
- tgz_fn = "%s-%s.tgz" % (prefix, release)
- bz2_fn = "%s-%s.tar.bz2" % (prefix, release)
-
- have_zip = isfile(zip_fn)
- have_tgz = isfile(tgz_fn)
- have_bz2 = isfile(bz2_fn)
-
- have_some = have_zip or have_tgz or have_bz2
-
- if not have_some:
- print " <!--"
- print " <tr><td>%s</td>" % name
- print get_file_cell(prefix, ".zip", have_zip)
- print get_file_cell(prefix, ".tgz", have_tgz)
- print get_file_cell(prefix, ".tar.bz2", have_bz2)
- print " </tr>"
- if not have_some:
- print " -->"
-
-print '''\
- </tbody>
-</table>
-'''
diff --git a/Doc/tools/mksourcepkg b/Doc/tools/mksourcepkg
deleted file mode 100755
index 7d5bd73..0000000
--- a/Doc/tools/mksourcepkg
+++ /dev/null
@@ -1,164 +0,0 @@
-#! /usr/bin/env python
-# -*- Python -*-
-
-"""%(program)s - script to create the latex source distribution
-
-usage:
- %(program)s [-t|--tools] release [tag]
-
-with -t|--tools: doesn't include the documents, only the framework
-
-without [tag]: generate from the current version that's checked in
- (*NOT* what's in the current directory!)
-
-with [tag]: generate from the named tag
-"""
-#* should be modified to get the Python version number automatically
-# from the Makefile or someplace.
-
-import getopt
-import glob
-import os
-import re
-import shutil
-import sys
-import tempfile
-
-try:
- __file__
-except NameError:
- __file__ = sys.argv[0]
-
-tools = os.path.dirname(os.path.abspath(__file__))
-Doc = os.path.dirname(tools)
-patchlevel_tex = os.path.join(Doc, "commontex", "patchlevel.tex")
-
-quiet = 0
-rx = re.compile(r":ext:(?:[a-zA-Z0-9]+@)?cvs\.([a-zA-Z0-9]+).sourceforge.net:"
- r"/cvsroot/\1")
-
-
-def main():
- global quiet
- anonymous = False
- try:
- opts, args = getopt.getopt(sys.argv[1:], "Aabgtzq",
- ["all", "bzip2", "gzip", "tools", "zip",
- "quiet", "anonymous"])
- except getopt.error as e:
- usage(warning=str(e))
- sys.exit(2)
- if len(args) not in (1, 2):
- usage(warning="wrong number of parameters")
- sys.exit(2)
- tools = 0
- formats = {}
- for opt, arg in opts:
- if opt in ("-t", "--tools"):
- tools = 1
- elif opt in ("-q", "--quiet"):
- quiet = quiet + 1
- elif opt in ("-b", "--bzip2"):
- formats["bzip2"] = 1
- elif opt in ("-g", "--gzip"):
- formats["gzip"] = 1
- elif opt in ("-z", "--zip"):
- formats["zip"] = 1
- elif opt in ("-a", "--all"):
- formats["bzip2"] = 1
- formats["gzip"] = 1
- formats["zip"] = 1
- elif opt in ("-A", "--anonymous"):
- anonymous = True
- if formats:
- # make order human-predictable
- formats = formats.keys()
- formats.sort()
- else:
- formats = ["gzip"]
- release = args[0]
- svntag = None
- if len(args) > 1:
- svntag = args[1]
- tempdir = tempfile.mktemp()
- os.mkdir(tempdir)
- pkgdir = os.path.join(tempdir, "Python-Docs-" + release)
- pwd = os.getcwd()
- mydir = os.path.abspath(os.path.dirname(sys.argv[0]))
- os.chdir(tempdir)
- if not quiet:
- print "--- current directory is:", tempdir
- if not svntag:
- svntag = "trunk"
- svnbase = "http://svn.python.org/projects/python"
- run("svn export %s/%s/Doc Python-Docs-%s"
- % (svnbase, svntag, release))
-
- # Copy in the version informtation, if we're not just going to
- # rip it back out:
- if not tools:
- if not os.path.exists(patchlevel_tex):
- run(os.path.join(here, "getversioninfo"))
- dest = os.path.join("Python-Docs-" + release, "commontex",
- "patchlevel.tex")
- shutil.copyfile(patchlevel_tex, dest)
-
- # Copy in the license file:
- LICENSE = os.path.normpath(
- os.path.join(mydir, os.pardir, os.pardir, "LICENSE"))
- shutil.copyfile(LICENSE, "LICENSE")
- if tools:
- archive = "doctools-" + release
- # we don't want the actual documents in this case:
- for d in ("api", "dist", "doc", "ext", "inst",
- "lib", "mac", "ref", "tut", "commontex"):
- shutil.rmtree(os.path.join(pkgdir, d))
- else:
- archive = "latex-" + release
-
- # XXX should also remove the .cvsignore files at this point
-
- os.chdir(tempdir)
- archive = os.path.join(pwd, archive)
- for format in formats:
- if format == "bzip2":
- run("tar cf - Python-Docs-%s | bzip2 -9 >%s.tar.bz2"
- % (release, archive))
- elif format == "gzip":
- run("tar cf - Python-Docs-%s | gzip -9 >%s.tgz"
- % (release, archive))
- elif format == "zip":
- if os.path.exists(archive + ".zip"):
- os.unlink(archive + ".zip")
- run("zip -q -r9 %s.zip Python-Docs-%s"
- % (archive, release))
-
- # clean up the work area:
- os.chdir(pwd)
- shutil.rmtree(tempdir)
-
-
-def run(cmd):
- if quiet < 2:
- print "+++", cmd
- if quiet:
- cmd = "%s >/dev/null" % cmd
- rc = os.system(cmd)
- if rc:
- sys.exit(rc)
-
-
-def usage(warning=None):
- stdout = sys.stdout
- sys.stdout = sys.stderr
- program = os.path.basename(sys.argv[0])
- try:
- if warning:
- print "%s: %s\n" % (program, warning)
- print __doc__ % {"program": program}
- finally:
- sys.stdout = stdout
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/node2label.pl b/Doc/tools/node2label.pl
deleted file mode 100755
index 6491b20..0000000
--- a/Doc/tools/node2label.pl
+++ /dev/null
@@ -1,71 +0,0 @@
-#! /usr/bin/env perl
-
-# On Cygwin, we actually have to generate a temporary file when doing
-# the inplace edit, or we'll get permission errors. Not sure who's
-# bug this is, except that it isn't ours. To deal with this, we
-# generate backups during the edit phase and remove them at the end.
-#
-use English;
-$INPLACE_EDIT = '.bak';
-
-# read the labels, then reverse the mappings
-require "labels.pl";
-
-%nodes = ();
-my $key;
-# sort so that we get a consistent assignment for nodes with multiple labels
-foreach $label (sort keys %external_labels) {
- #
- # If the label can't be used as a filename on non-Unix platforms,
- # skip it. Such labels may be used internally within the documentation,
- # but will never be used for filename generation.
- #
- if ($label =~ /^([-.a-zA-Z0-9]+)$/) {
- $key = $external_labels{$label};
- $key =~ s|^/||;
- $nodes{$key} = $label;
- }
-}
-
-# This adds the "internal" labels added for indexing. These labels will not
-# be used for file names.
-require "intlabels.pl";
-foreach $label (keys %internal_labels) {
- $key = $internal_labels{$label};
- $key =~ s|^/||;
- if (defined($nodes{$key})) {
- $nodes{$label} = $nodes{$key};
- }
-}
-
-# collect labels that have been used
-%newnames = ();
-
-while (<>) {
- # don't want to do one s/// per line per node
- # so look for lines with hrefs, then do s/// on nodes present
- if (/(HREF|href)=[\"\']node\d+\.html[\#\"\']/) {
- @parts = split(/(HREF|href)\=[\"\']/);
- shift @parts;
- for $node (@parts) {
- $node =~ s/[\#\"\'].*$//g;
- chomp($node);
- if (defined($nodes{$node})) {
- $label = $nodes{$node};
- if (s/(HREF|href)=([\"\'])$node([\#\"\'])/href=$2$label.html$3/g) {
- s/(HREF|href)=([\"\'])$label.html/href=$2$label.html/g;
- $newnames{$node} = "$label.html";
- }
- }
- }
- }
- print;
-}
-
-foreach $oldname (keys %newnames) {
- rename($oldname, $newnames{$oldname});
-}
-
-foreach $filename (glob('*.bak')) {
- unlink($filename);
-}
diff --git a/Doc/tools/prechm.py b/Doc/tools/prechm.py
deleted file mode 100644
index b24eea0..0000000
--- a/Doc/tools/prechm.py
+++ /dev/null
@@ -1,519 +0,0 @@
-"""
- Makes the necesary files to convert from plain html of
- Python 1.5 and 1.5.x Documentation to
- Microsoft HTML Help format version 1.1
- Doesn't change the html's docs.
-
- by hernan.foffani@iname.com
- no copyright and no responsabilities.
-
- modified by Dale Nagata for Python 1.5.2
-
- Renamed from make_chm.py to prechm.py, and checked into the Python
- project, 19-Apr-2002 by Tim Peters. Assorted modifications by Tim
- and Fred Drake. Obtained from Robin Dunn's .chm packaging of the
- Python 2.2 docs, at <http://alldunn.com/python/>.
-"""
-
-import sys
-import os
-from formatter import NullWriter, AbstractFormatter
-from htmllib import HTMLParser
-import getopt
-import cgi
-
-usage_mode = '''
-Usage: prechm.py [-c] [-k] [-p] [-v 1.5[.x]] filename
- -c: does not build filename.hhc (Table of Contents)
- -k: does not build filename.hhk (Index)
- -p: does not build filename.hhp (Project File)
- -v 1.5[.x]: makes help for the python 1.5[.x] docs
- (default is python 1.5.2 docs)
-'''
-
-# Project file (*.hhp) template. 'arch' is the file basename (like
-# the pythlp in pythlp.hhp); 'version' is the doc version number (like
-# the 2.2 in Python 2.2).
-# The magical numbers in the long line under [WINDOWS] set most of the
-# user-visible features (visible buttons, tabs, etc).
-# About 0x10384e: This defines the buttons in the help viewer. The
-# following defns are taken from htmlhelp.h. Not all possibilities
-# actually work, and not all those that work are available from the Help
-# Workshop GUI. In particular, the Zoom/Font button works and is not
-# available from the GUI. The ones we're using are marked with 'x':
-#
-# 0x000002 Hide/Show x
-# 0x000004 Back x
-# 0x000008 Forward x
-# 0x000010 Stop
-# 0x000020 Refresh
-# 0x000040 Home x
-# 0x000080 Forward
-# 0x000100 Back
-# 0x000200 Notes
-# 0x000400 Contents
-# 0x000800 Locate x
-# 0x001000 Options x
-# 0x002000 Print x
-# 0x004000 Index
-# 0x008000 Search
-# 0x010000 History
-# 0x020000 Favorites
-# 0x040000 Jump 1
-# 0x080000 Jump 2
-# 0x100000 Zoom/Font x
-# 0x200000 TOC Next
-# 0x400000 TOC Prev
-
-project_template = '''
-[OPTIONS]
-Compiled file=%(arch)s.chm
-Contents file=%(arch)s.hhc
-Default Window=%(arch)s
-Default topic=index.html
-Display compile progress=No
-Full text search stop list file=%(arch)s.stp
-Full-text search=Yes
-Index file=%(arch)s.hhk
-Language=0x409
-Title=Python %(version)s Documentation
-
-[WINDOWS]
-%(arch)s="Python %(version)s Documentation","%(arch)s.hhc","%(arch)s.hhk",\
-"index.html","index.html",,,,,0x63520,220,0x10384e,[0,0,1024,768],,,,,,,0
-
-[FILES]
-'''
-
-contents_header = '''\
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
-<HTML>
-<HEAD>
-<meta name="GENERATOR" content="Microsoft® HTML Help Workshop 4.1">
-<!-- Sitemap 1.0 -->
-</HEAD><BODY>
-<OBJECT type="text/site properties">
- <param name="Window Styles" value="0x801227">
- <param name="ImageType" value="Folder">
-</OBJECT>
-<UL>
-'''
-
-contents_footer = '''\
-</UL></BODY></HTML>
-'''
-
-object_sitemap = '''\
-<OBJECT type="text/sitemap">
- <param name="Name" value="%s">
- <param name="Local" value="%s">
-</OBJECT>
-'''
-
-# List of words the full text search facility shouldn't index. This
-# becomes file ARCH.stp. Note that this list must be pretty small!
-# Different versions of the MS docs claim the file has a maximum size of
-# 256 or 512 bytes (including \r\n at the end of each line).
-# Note that "and", "or", "not" and "near" are operators in the search
-# language, so no point indexing them even if we wanted to.
-stop_list = '''
-a and are as at
-be but by
-for
-if in into is it
-near no not
-of on or
-such
-that the their then there these they this to
-was will with
-'''
-
-# s is a string or None. If None or empty, return None. Else tack '.html'
-# on to the end, unless it's already there.
-def addhtml(s):
- if s:
- if not s.endswith('.html'):
- s += '.html'
- return s
-
-# Convenience class to hold info about "a book" in HTMLHelp terms == a doc
-# directory in Python terms.
-class Book:
- def __init__(self, directory, title, firstpage,
- contentpage=None, indexpage=None):
- self.directory = directory
- self.title = title
- self.firstpage = addhtml(firstpage)
- self.contentpage = addhtml(contentpage)
- self.indexpage = addhtml(indexpage)
-
-# Library Doc list of books:
-# each 'book' : (Dir, Title, First page, Content page, Index page)
-supported_libraries = {
- '2.5':
- [
- Book('.', 'Main page', 'index'),
- Book('.', 'Global Module Index', 'modindex'),
- Book('whatsnew', "What's New", 'index', 'contents'),
- Book('tut','Tutorial','tut','node2'),
- Book('lib','Library Reference','lib','contents','genindex'),
- Book('ref','Language Reference','ref','contents','genindex'),
- Book('mac','Macintosh Reference','mac','contents','genindex'),
- Book('ext','Extending and Embedding','ext','contents'),
- Book('api','Python/C API','api','contents','genindex'),
- Book('doc','Documenting Python','doc','contents'),
- Book('inst','Installing Python Modules', 'inst', 'index'),
- Book('dist','Distributing Python Modules', 'dist', 'index', 'genindex'),
- ],
-
- '2.4':
- [
- Book('.', 'Main page', 'index'),
- Book('.', 'Global Module Index', 'modindex'),
- Book('whatsnew', "What's New", 'index', 'contents'),
- Book('tut','Tutorial','tut','node2'),
- Book('lib','Library Reference','lib','contents','genindex'),
- Book('ref','Language Reference','ref','contents','genindex'),
- Book('mac','Macintosh Reference','mac','contents','genindex'),
- Book('ext','Extending and Embedding','ext','contents'),
- Book('api','Python/C API','api','contents','genindex'),
- Book('doc','Documenting Python','doc','contents'),
- Book('inst','Installing Python Modules', 'inst', 'index'),
- Book('dist','Distributing Python Modules', 'dist', 'index', 'genindex'),
- ],
-
- '2.3':
- [
- Book('.', 'Main page', 'index'),
- Book('.', 'Global Module Index', 'modindex'),
- Book('whatsnew', "What's New", 'index', 'contents'),
- Book('tut','Tutorial','tut','node2'),
- Book('lib','Library Reference','lib','contents','genindex'),
- Book('ref','Language Reference','ref','contents','genindex'),
- Book('mac','Macintosh Reference','mac','contents','genindex'),
- Book('ext','Extending and Embedding','ext','contents'),
- Book('api','Python/C API','api','contents','genindex'),
- Book('doc','Documenting Python','doc','contents'),
- Book('inst','Installing Python Modules', 'inst', 'index'),
- Book('dist','Distributing Python Modules', 'dist', 'index'),
- ],
-
- '2.2':
- [
- Book('.', 'Main page', 'index'),
- Book('.', 'Global Module Index', 'modindex'),
- Book('whatsnew', "What's New", 'index', 'contents'),
- Book('tut','Tutorial','tut','node2'),
- Book('lib','Library Reference','lib','contents','genindex'),
- Book('ref','Language Reference','ref','contents','genindex'),
- Book('mac','Macintosh Reference','mac','contents','genindex'),
- Book('ext','Extending and Embedding','ext','contents'),
- Book('api','Python/C API','api','contents','genindex'),
- Book('doc','Documenting Python','doc','contents'),
- Book('inst','Installing Python Modules', 'inst', 'index'),
- Book('dist','Distributing Python Modules', 'dist', 'index'),
- ],
-
- '2.1.1':
- [
- Book('.', 'Main page', 'index'),
- Book('.', 'Global Module Index', 'modindex'),
- Book('tut','Tutorial','tut','node2'),
- Book('lib','Library Reference','lib','contents','genindex'),
- Book('ref','Language Reference','ref','contents','genindex'),
- Book('mac','Macintosh Reference','mac','contents','genindex'),
- Book('ext','Extending and Embedding','ext','contents'),
- Book('api','Python/C API','api','contents','genindex'),
- Book('doc','Documenting Python','doc','contents'),
- Book('inst','Installing Python Modules', 'inst', 'index'),
- Book('dist','Distributing Python Modules', 'dist', 'index'),
- ],
-
- '2.0.0':
- [
- Book('.', 'Global Module Index', 'modindex'),
- Book('tut','Tutorial','tut','node2'),
- Book('lib','Library Reference','lib','contents','genindex'),
- Book('ref','Language Reference','ref','contents','genindex'),
- Book('mac','Macintosh Reference','mac','contents','genindex'),
- Book('ext','Extending and Embedding','ext','contents'),
- Book('api','Python/C API','api','contents','genindex'),
- Book('doc','Documenting Python','doc','contents'),
- Book('inst','Installing Python Modules', 'inst', 'contents'),
- Book('dist','Distributing Python Modules', 'dist', 'contents'),
- ],
-
- # <dnagata@creo.com> Apr 17/99: library for 1.5.2 version:
- # <hernan.foffani@iname.com> May 01/99: library for 1.5.2 (04/30/99):
- '1.5.2':
- [
- Book('tut','Tutorial','tut','node2'),
- Book('lib','Library Reference','lib','contents','genindex'),
- Book('ref','Language Reference','ref','contents','genindex'),
- Book('mac','Macintosh Reference','mac','contents','genindex'),
- Book('ext','Extending and Embedding','ext','contents'),
- Book('api','Python/C API','api','contents','genindex'),
- Book('doc','Documenting Python','doc','contents')
- ],
-
- # library for 1.5.1 version:
- '1.5.1':
- [
- Book('tut','Tutorial','tut','contents'),
- Book('lib','Library Reference','lib','contents','genindex'),
- Book('ref','Language Reference','ref-1','ref-2','ref-11'),
- Book('ext','Extending and Embedding','ext','contents'),
- Book('api','Python/C API','api','contents','genindex')
- ],
-
- # library for 1.5 version:
- '1.5':
- [
- Book('tut','Tutorial','tut','node1'),
- Book('lib','Library Reference','lib','node1','node268'),
- Book('ref','Language Reference','ref-1','ref-2','ref-11'),
- Book('ext','Extending and Embedding','ext','node1'),
- Book('api','Python/C API','api','node1','node48')
- ]
-}
-
-# AlmostNullWriter doesn't print anything; it just arranges to save the
-# text sent to send_flowing_data(). This is used to capture the text
-# between an anchor begin/end pair, e.g. for TOC entries.
-
-class AlmostNullWriter(NullWriter):
-
- def __init__(self):
- NullWriter.__init__(self)
- self.saved_clear()
-
- def send_flowing_data(self, data):
- stripped = data.strip()
- if stripped: # don't bother to save runs of whitespace
- self.saved.append(stripped)
-
- # Forget all saved text.
- def saved_clear(self):
- self.saved = []
-
- # Return all saved text as a string.
- def saved_get(self):
- return ' '.join(self.saved)
-
-class HelpHtmlParser(HTMLParser):
-
- def __init__(self, formatter, path, output):
- HTMLParser.__init__(self, formatter)
- self.path = path # relative path
- self.ft = output # output file
- self.indent = 0 # number of tabs for pretty printing of files
- self.proc = False # True when actively processing, else False
- # (headers, footers, etc)
- # XXX This shouldn't need to be a stack -- anchors shouldn't nest.
- # XXX See SF bug <http://www.python.org/sf/546579>.
- self.hrefstack = [] # stack of hrefs from anchor begins
-
- def begin_group(self):
- self.indent += 1
- self.proc = True
-
- def finish_group(self):
- self.indent -= 1
- # stop processing when back to top level
- self.proc = self.indent > 0
-
- def anchor_bgn(self, href, name, type):
- if self.proc:
- # XXX See SF bug <http://www.python.org/sf/546579>.
- # XXX index.html for the 2.2.1 language reference manual contains
- # XXX nested <a></a> tags in the entry for the section on blank
- # XXX lines. We want to ignore the nested part completely.
- if len(self.hrefstack) == 0:
- self.saved_clear()
- self.hrefstack.append(href)
-
- def anchor_end(self):
- if self.proc:
- # XXX See XXX above.
- if self.hrefstack:
- title = cgi.escape(self.saved_get(), True)
- path = self.path + '/' + self.hrefstack.pop()
- self.tab(object_sitemap % (title, path))
-
- def start_dl(self, atr_val):
- self.begin_group()
-
- def end_dl(self):
- self.finish_group()
-
- def do_dt(self, atr_val):
- # no trailing newline on purpose!
- self.tab("<LI>")
-
- # Write text to output file.
- def write(self, text):
- self.ft.write(text)
-
- # Write text to output file after indenting by self.indent tabs.
- def tab(self, text=''):
- self.write('\t' * self.indent)
- if text:
- self.write(text)
-
- # Forget all saved text.
- def saved_clear(self):
- self.formatter.writer.saved_clear()
-
- # Return all saved text as a string.
- def saved_get(self):
- return self.formatter.writer.saved_get()
-
-class IdxHlpHtmlParser(HelpHtmlParser):
- # nothing special here, seems enough with parent class
- pass
-
-class TocHlpHtmlParser(HelpHtmlParser):
-
- def start_dl(self, atr_val):
- self.begin_group()
- self.tab('<UL>\n')
-
- def end_dl(self):
- self.finish_group()
- self.tab('</UL>\n')
-
- def start_ul(self, atr_val):
- self.begin_group()
- self.tab('<UL>\n')
-
- def end_ul(self):
- self.finish_group()
- self.tab('</UL>\n')
-
- def do_li(self, atr_val):
- # no trailing newline on purpose!
- self.tab("<LI>")
-
-def index(path, indexpage, output):
- parser = IdxHlpHtmlParser(AbstractFormatter(AlmostNullWriter()),
- path, output)
- f = open(path + '/' + indexpage)
- parser.feed(f.read())
- parser.close()
- f.close()
-
-def content(path, contentpage, output):
- parser = TocHlpHtmlParser(AbstractFormatter(AlmostNullWriter()),
- path, output)
- f = open(path + '/' + contentpage)
- parser.feed(f.read())
- parser.close()
- f.close()
-
-def do_index(library, output):
- output.write('<UL>\n')
- for book in library:
- print('\t', book.title, '-', book.indexpage)
- if book.indexpage:
- index(book.directory, book.indexpage, output)
- output.write('</UL>\n')
-
-def do_content(library, version, output):
- output.write(contents_header)
- for book in library:
- print('\t', book.title, '-', book.firstpage)
- path = book.directory + "/" + book.firstpage
- output.write('<LI>')
- output.write(object_sitemap % (book.title, path))
- if book.contentpage:
- content(book.directory, book.contentpage, output)
- output.write(contents_footer)
-
-# Fill in the [FILES] section of the project (.hhp) file.
-# 'library' is the list of directory description tuples from
-# supported_libraries for the version of the docs getting generated.
-def do_project(library, output, arch, version):
- output.write(project_template % locals())
- pathseen = {}
- for book in library:
- directory = book.directory
- path = directory + '\\%s\n'
- for page in os.listdir(directory):
- if page.endswith('.html') or page.endswith('.css'):
- fullpath = path % page
- if fullpath not in pathseen:
- output.write(fullpath)
- pathseen[fullpath] = True
-
-def openfile(file):
- try:
- p = open(file, "w")
- except IOError as msg:
- print(file, ":", msg)
- sys.exit(1)
- return p
-
-def usage():
- print(usage_mode)
- sys.exit(0)
-
-def do_it(args = None):
- if not args:
- args = sys.argv[1:]
-
- if not args:
- usage()
-
- try:
- optlist, args = getopt.getopt(args, 'ckpv:')
- except getopt.error as msg:
- print(msg)
- usage()
-
- if not args or len(args) > 1:
- usage()
- arch = args[0]
-
- version = None
- for opt in optlist:
- if opt[0] == '-v':
- version = opt[1]
- break
- if not version:
- usage()
-
- library = supported_libraries[version]
-
- if not (('-p','') in optlist):
- fname = arch + '.stp'
- f = openfile(fname)
- print("Building stoplist", fname, "...")
- words = stop_list.split()
- words.sort()
- for word in words:
- print(word, file=f)
- f.close()
-
- f = openfile(arch + '.hhp')
- print("Building Project...")
- do_project(library, f, arch, version)
- if version == '2.0.0':
- for image in os.listdir('icons'):
- f.write('icons'+ '\\' + image + '\n')
-
- f.close()
-
- if not (('-c','') in optlist):
- f = openfile(arch + '.hhc')
- print("Building Table of Content...")
- do_content(library, version, f)
- f.close()
-
- if not (('-k','') in optlist):
- f = openfile(arch + '.hhk')
- print("Building Index...")
- do_index(library, f)
- f.close()
-
-if __name__ == '__main__':
- do_it()
diff --git a/Doc/tools/push-docs.sh b/Doc/tools/push-docs.sh
deleted file mode 100755
index 28a4b31..0000000
--- a/Doc/tools/push-docs.sh
+++ /dev/null
@@ -1,138 +0,0 @@
-#! /bin/sh
-
-# Script to push docs from my development area to SourceForge, where the
-# update-docs.sh script unpacks them into their final destination.
-
-TARGETHOST=www.python.org
-TARGETDIR=/usr/home/fdrake/tmp
-
-PKGTYPE="bzip" # must be one of: bzip, tar, zip ("tar" implies gzip)
-
-TARGET="$TARGETHOST:$TARGETDIR"
-
-ADDRESSES='python-dev@python.org doc-sig@python.org python-list@python.org'
-
-TOOLDIR="`dirname $0`"
-VERSION=`$TOOLDIR/getversioninfo`
-
-# Set $EXTRA to something non-empty if this is a non-trunk version:
-EXTRA=`echo "$VERSION" | sed 's/^[0-9][0-9]*\.[0-9][0-9]*//'`
-
-if echo "$EXTRA" | grep -q '[.]' ; then
- DOCLABEL="maintenance"
- DOCTYPE="maint"
-else
- DOCLABEL="development"
- DOCTYPE="devel"
-fi
-
-DOCTYPE_SPECIFIED=false
-EXPLANATION=''
-ANNOUNCE=true
-
-getopt -T >/dev/null
-if [ $? -eq 4 ] ; then
- # We have a sufficiently useful getopt(1) implementation.
- eval "set -- `getopt -ssh m:p:qt:F: \"$@\"`"
-else
- # This version of getopt doesn't support quoting of long options
- # with spaces, so let's not rely on it at all.
- :
-fi
-
-while [ "$#" -gt 0 ] ; do
- case "$1" in
- -m)
- EXPLANATION="$2"
- shift 2
- ;;
- -p)
- PKGTYPE="$2"
- shift 1
- ;;
- -q)
- ANNOUNCE=false
- shift 1
- ;;
- -t)
- DOCTYPE="$2"
- DOCTYPE_SPECIFIED=true
- shift 2
- ;;
- -F)
- EXPLANATION="`cat $2`"
- shift 2
- ;;
- --)
- shift 1
- break
- ;;
- -*)
- echo "Unknown option: $1" >&2
- exit 2
- ;;
- *)
- break
- ;;
- esac
-done
-if [ "$1" ] ; then
- if [ "$EXPLANATION" ] ; then
- echo "Explanation may only be given once!" >&2
- exit 2
- fi
- EXPLANATION="$1"
- shift
-fi
-
-START="`pwd`"
-MYDIR="`dirname $0`"
-cd "$MYDIR"
-MYDIR="`pwd`"
-
-if [ "$PKGTYPE" = bzip ] ; then
- PKGEXT=tar.bz2
-elif [ "$PKGTYPE" = tar ] ; then
- PKGEXT=tgz
-elif [ "$PKGTYPE" = zip ] ; then
- PKGEXT=zip
-else
- echo 1>&2 "unsupported package type: $PKGTYPE"
- exit 2
-fi
-
-# switch to .../Doc/
-cd ..
-
-# If $DOCTYPE was not specified explicitly, look for .doctype in
-# .../Doc/ and use the content of that file if present.
-if $DOCTYPE_SPECIFIED ; then
- :
-elif [ -f .doctype ] ; then
- DOCTYPE="`cat .doctype`"
-fi
-
-make --no-print-directory ${PKGTYPE}html || exit $?
-PACKAGE="html-$VERSION.$PKGEXT"
-scp "$PACKAGE" tools/update-docs.sh $TARGET/ || exit $?
-ssh "$TARGETHOST" tmp/update-docs.sh $DOCTYPE $PACKAGE '&&' rm tmp/update-docs.sh || exit $?
-
-if $ANNOUNCE ; then
- sendmail $ADDRESSES <<EOF
-To: $ADDRESSES
-From: "Fred L. Drake" <fdrake@acm.org>
-Subject: [$DOCLABEL doc updates]
-X-No-Archive: yes
-
-The $DOCLABEL version of the documentation has been updated:
-
- http://$TARGETHOST/dev/doc/$DOCTYPE/
-
-$EXPLANATION
-
-A downloadable package containing the HTML is also available:
-
- http://$TARGETHOST/dev/doc/python-docs-$DOCTYPE.$PKGEXT
-EOF
- exit $?
-fi
diff --git a/Doc/tools/py2texi.el b/Doc/tools/py2texi.el
deleted file mode 100644
index 404234f..0000000
--- a/Doc/tools/py2texi.el
+++ /dev/null
@@ -1,970 +0,0 @@
-;;; py2texi.el -- Conversion of Python LaTeX documentation to Texinfo
-
-;; Copyright (C) 2006 Jeroen Dekkers <jeroen@dekkers.cx>
-;; Copyright (C) 1998, 1999, 2001, 2002 Milan Zamazal
-
-;; Author: Milan Zamazal <pdm@zamazal.org>
-;; Version: $Id$
-;; Keywords: python
-
-;; COPYRIGHT NOTICE
-;;
-;; This program is free software; you can redistribute it and/or modify it
-;; under the terms of the GNU General Public License as published by the Free
-;; Software Foundation; either version 2, or (at your option) any later
-;; version.
-;;
-;; This program is distributed in the hope that it will be useful, but
-;; WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
-;; or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
-;; for more details.
-;;
-;; You can find the GNU General Public License at
-;; http://www.gnu.org/copyleft/gpl.html
-;; or you can write to the Free Software Foundation, Inc., 59 Temple Place,
-;; Suite 330, Boston, MA 02111-1307, USA.
-
-;;; Commentary:
-
-;; This is a Q&D hack for conversion of Python manuals to on-line help format.
-;; I desperately needed usable online documenta for Python, so I wrote this.
-;; The result code is ugly and need not contain complete information from
-;; Python manuals. I apologize for my ignorance, especially ignorance to
-;; python.sty. Improvements of this convertor are welcomed.
-
-;; How to use it:
-;; Load this file and apply `M-x py2texi'. You will be asked for name of a
-;; file to be converted.
-
-;; Where to find it:
-;; New versions of this code might be found at
-;; http://www.zamazal.org/software/python/py2texi/ .
-
-;;; Code:
-
-
-(require 'texinfo)
-(eval-when-compile
- (require 'cl))
-
-
-(defvar py2texi-python-version "2.2"
- "What to substitute for the \\version macro.")
-
-(defvar py2texi-python-short-version
- (progn
- (string-match "[0-9]+\\.[0-9]+" py2texi-python-version)
- (match-string 0 py2texi-python-version))
- "Short version number, usually set by the LaTeX commands.")
-
-(defvar py2texi-texi-file-name nil
- "If non-nil, that string is used as the name of the Texinfo file.
-Otherwise a generated Texinfo file name is used.")
-
-(defvar py2texi-info-file-name nil
- "If non-nil, that string is used as the name of the Info file.
-Otherwise a generated Info file name is used.")
-
-(defvar py2texi-stop-on-problems nil
- "*If non-nil, stop when you encouter soft problem.")
-
-(defconst py2texi-environments
- '(("abstract" 0 "@quotation" "@end quotation\n")
- ("center" 0 "" "")
- ("cfuncdesc" 3
- (progn (setq findex t)
- "\n@table @code\n@item \\1 \\2(\\3)\n@findex \\2\n")
- "@end table\n")
- ("cmemberdesc" 3
- "\n@table @code\n@item \\2 \\3\n"
- "@end table\n")
- ("classdesc" 2
- (progn (setq obindex t)
- "\n@table @code\n@item \\1(\\2)\n@obindex \\1\n")
- "@end table\n")
- ("classdesc*" 1
- (progn (setq obindex t)
- "\n@table @code\n@item \\1\n@obindex \\1\n")
- "@end table\n")
- ("comment" 0 "\n@ignore\n" "\n@end ignore\n")
- ("csimplemacrodesc" 1
- (progn (setq cindex t)
- "\n@table @code\n@item \\1\n@cindex \\1\n")
- "@end table\n")
- ("ctypedesc" 1
- (progn (setq cindex t)
- "\n@table @code\n@item \\1\n@cindex \\1\n")
- "@end table\n")
- ("cvardesc" 2
- (progn (setq findex t)
- "\n@table @code\n@item \\1 \\2\n@findex \\2\n")
- "@end table\n")
- ("datadesc" 1
- (progn (setq findex t)
- "\n@table @code\n@item \\1\n@findex \\1\n")
- "@end table\n")
- ("datadescni" 1 "\n@table @code\n@item \\1\n" "@end table\n")
- ("definitions" 0 "@table @dfn" "@end table\n")
- ("description" 0 "@table @samp" "@end table\n")
- ("displaymath" 0 "" "")
- ("document" 0
- (concat "@defcodeindex mo\n"
- "@defcodeindex ob\n"
- "@titlepage\n"
- (format "@title " title "\n")
- (format "@author " author "\n")
- "@page\n"
- author-address
- "@end titlepage\n"
- "@node Top, , , (dir)\n")
- (concat "@indices\n"
- "@contents\n"
- "@bye\n"))
- ("enumerate" 0 "@enumerate" "@end enumerate")
- ("envdesc" 2 (concat "\n@table @code"
- "\n@item @backslash{}begin@{\\1@}\\2")
- "@end table\n")
- ("excdesc" 1
- (progn (setq obindex t)
- "\n@table @code\n@item \\1\n@obindex \\1\n")
- "@end table\n")
- ("excclassdesc" 2
- (progn (setq obindex t)
- "\n@table @code\n@item \\1(\\2)\n@obindex \\1\n")
- "@end table\n")
- ("flushleft" 0 "" "")
- ("fulllineitems" 0 "\n@table @code\n" "@end table\n")
- ("funcdesc" 2
- (progn (setq findex t)
- "\n@table @code\n@item \\1(\\2)\n@findex \\1\n")
- "@end table\n")
- ("funcdescni" 2 "\n@table @code\n@item \\1(\\2)\n" "@end table\n")
- ("itemize" 0 "@itemize @bullet" "@end itemize\n")
- ("list" 2 "\n@table @code\n" "@end table\n")
- ("longtableii" 4 (concat "@multitable @columnfractions .5 .5\n"
- "@item \\3 @tab \\4\n"
- "@item ------- @tab ------ \n")
- "@end multitable\n")
- ("longtableiii" 5 (concat "@multitable @columnfractions .33 .33 .33\n"
- "@item \\3 @tab \\4 @tab \\5\n"
- "@item ------- @tab ------ @tab ------\n")
- "@end multitable\n")
- ("macrodesc" 2 (concat "\n@table @code"
- "\n@item \\1@{\\2@}")
- "@end table\n")
- ("memberdesc" 1
- (progn (setq findex t)
- "\n@table @code\n@item \\1\n@findex \\1\n")
- "@end table\n")
- ("memberdescni" 1 "\n@table @code\n@item \\1\n" "@end table\n")
- ("methoddesc" 2
- (progn (setq findex t)
- "\n@table @code\n@item \\1(\\2)\n@findex \\1\n")
- "@end table\n")
- ("methoddescni" 2 "\n@table @code\n@item \\1(\\2)\n" "@end table\n")
- ("notice" 0 "@emph{Notice:} " "")
- ("opcodedesc" 2
- (progn (setq findex t)
- "\n@table @code\n@item \\1 \\2\n@findex \\1\n")
- "@end table\n")
- ("productionlist" 0 "\n@table @code\n" "@end table\n")
- ("quotation" 0 "@quotation" "@end quotation")
- ("quote" 0 "@quotation" "@end quotation")
- ("seealso" 0 "See also:\n@table @emph\n" "@end table\n")
- ("seealso*" 0 "@table @emph\n" "@end table\n")
- ("sloppypar" 0 "" "")
- ("small" 0 "" "")
- ("tableii" 4 (concat "@multitable @columnfractions .5 .5\n"
- "@item \\3 @tab \\4\n"
- "@item ------- @tab ------ \n")
- "@end multitable\n")
- ("tableiii" 5 (concat "@multitable @columnfractions .33 .33 .33\n"
- "@item \\3 @tab \\4 @tab \\5\n"
- "@item ------- @tab ------ @tab ------\n")
- "@end multitable\n")
- ("tableiv" 6 (concat
- "@multitable @columnfractions .25 .25 .25 .25\n"
- "@item \\3 @tab \\4 @tab \\5 @tab \\6\n"
- "@item ------- @tab ------- @tab ------- @tab -------\n")
- "@end multitable\n")
- ("tablev" 7 (concat
- "@multitable @columnfractions .20 .20 .20 .20 .20\n"
- "@item \\3 @tab \\4 @tab \\5 @tab \\6 @tab \\7\n"
- "@item ------- @tab ------- @tab ------- @tab ------- @tab -------\n")
- "@end multitable\n")
- ("alltt" 0 "@example" "@end example")
- )
- "Associative list defining substitutions for environments.
-Each list item is of the form (ENVIRONMENT ARGNUM BEGIN END) where:
-- ENVIRONMENT is LaTeX environment name
-- ARGNUM is number of (required) macro arguments
-- BEGIN is substitution for \begin{ENVIRONMENT}
-- END is substitution for \end{ENVIRONMENT}
-Both BEGIN and END are evaled. Moreover, you can reference arguments through
-\N regular expression notation in strings of BEGIN.")
-
-(defconst py2texi-commands
- '(("AA" 0 "@AA{}")
- ("aa" 0 "@aa{}")
- ("ABC" 0 "ABC")
- ("appendix" 0 (progn (setq appendix t) ""))
- ("ASCII" 0 "ASCII")
- ("author" 1 (progn (setq author (match-string 1 string)) ""))
- ("authoraddress" 1
- (progn (setq author-address (match-string 1 string)) ""))
- ("b" 1 "@w{\\1}")
- ("backslash" 0 "@backslash{}")
- ("bf" 0 "@destroy")
- ("bifuncindex" 1 (progn (setq findex t) "@findex{\\1}"))
- ("C" 0 "C")
- ("c" 0 "@,")
- ("catcode" 0 "")
- ("cdata" 1 "@code{\\1}")
- ("centerline" 1 "@center \\1")
- ("cfuncline" 3 "@itemx \\1 \\2(\\3)\n@findex \\2")
- ("cfunction" 1 "@code{\\1}")
- ("chapter" 1 (format "@node \\1\n@%s \\1\n"
- (if appendix "appendix" "chapter")))
- ("chapter*" 1 "@node \\1\n@unnumbered \\1\n")
- ("character" 1 "@samp{\\1}")
- ("citetitle" 1 "@ref{Top,,,\\1}")
- ("class" 1 "@code{\\1}")
- ("cmemberline" 3 "@itemx \\2 \\3\n")
- ("code" 1 "@code{\\1}")
- ("command" 1 "@command{\\1}")
- ("constant" 1 "@code{\\1}")
- ("copyright" 1 "@copyright{}")
- ("Cpp" 0 "C++")
- ("csimplemacro" 1 "@code{\\1}")
- ("ctype" 1 "@code{\\1}")
- ("dataline" 1 (progn (setq findex t) "@item \\1\n@findex \\1\n"))
- ("date" 1 "\\1")
- ("declaremodule" 2 (progn (setq cindex t) "@label{\\2}@cindex{\\2}"))
- ("deprecated" 2 "@emph{This is deprecated in Python \\1. \\2}\n\n")
- ("dfn" 1 "@dfn{\\1}")
- ("documentclass" 1 py2texi-magic)
- ("e" 0 "@backslash{}")
- ("else" 0 (concat "@end ifinfo\n@" (setq last-if "iftex")))
- ("env" 1 "@code{\\1}")
- ("EOF" 0 "@code{EOF}")
- ("email" 1 "@email{\\1}")
- ("em" 1 "@emph{\\1}")
- ("emph" 1 "@emph{\\1}")
- ("envvar" 1 "@env{\\1}")
- ("exception" 1 "@code{\\1}")
- ("exindex" 1 (progn (setq obindex t) "@obindex{\\1}"))
- ("fi" 0 (if (equal last-if "ifx") "" (concat "@end " last-if)))
- ("file" 1 "@file{\\1}")
- ("filenq" 1 "@file{\\1}")
- ("filevar" 1 "@file{@var{\\1}}")
- ("footnote" 1 "@footnote{\\1}")
- ("frac" 0 "")
- ("funcline" 2 (progn (setq findex t) "@item \\1 \\2\n@findex \\1"))
- ("funclineni" 2 "@item \\1 \\2")
- ("function" 1 "@code{\\1}")
- ("grammartoken" 1 "@code{\\1}")
- ("guilabel" 1 "@strong{\\1}")
- ("hline" 0 "")
- ("ifx" 0 (progn (setq last-if "ifx") ""))
- ("ifhtml" 0 (concat "@" (setq last-if "ifinfo")))
- ("iftexi" 0 (concat "@" (setq last-if "ifinfo")))
- ("index" 1 (progn (setq cindex t) "@cindex{\\1}"))
- ("indexii" 2 (progn (setq cindex t) "@cindex{\\1 \\2}"))
- ("indexiii" 3 (progn (setq cindex t) "@cindex{\\1 \\2 \\3}"))
- ("indexiv" 3 (progn (setq cindex t) "@cindex{\\1 \\2 \\3 \\4}"))
- ("infinity" 0 "@emph{infinity}")
- ("it" 0 "@destroy")
- ("kbd" 1 "@key{\\1}")
- ("keyword" 1 "@code{\\1}")
- ("kwindex" 1 (progn (setq cindex t) "@cindex{\\1}"))
- ("label" 1 "@label{\\1}")
- ("Large" 0 "")
- ("LaTeX" 0 "La@TeX{}")
- ("large" 0 "")
- ("ldots" 0 "@dots{}")
- ("leftline" 1 "\\1")
- ("leq" 0 "<=")
- ("lineii" 2 "@item \\1 @tab \\2")
- ("lineiii" 3 "@item \\1 @tab \\2 @tab \\3")
- ("lineiv" 4 "@item \\1 @tab \\2 @tab \\3 @tab \\4")
- ("linev" 5 "@item \\1 @tab \\2 @tab \\3 @tab \\4 @tab \\5")
- ("locallinewidth" 0 "")
- ("localmoduletable" 0 "")
- ("longprogramopt" 1 "@option{--\\1}")
- ("macro" 1 "@code{@backslash{}\\1}")
- ("mailheader" 1 "@code{\\1}")
- ("makeindex" 0 "")
- ("makemodindex" 0 "")
- ("maketitle" 0 (concat "@top " title "\n"))
- ("makevar" 1 "@code{\\1}")
- ("manpage" 2 "@samp{\\1(\\2)}")
- ("mbox" 1 "@w{\\1}")
- ("member" 1 "@code{\\1}")
- ("memberline" 1 "@item \\1\n@findex \\1\n")
- ("menuselection" 1 "@samp{\\1}")
- ("method" 1 "@code{\\1}")
- ("methodline" 2 (progn (setq moindex t) "@item \\1(\\2)\n@moindex \\1\n"))
- ("methodlineni" 2 "@item \\1(\\2)\n")
- ("mimetype" 1 "@samp{\\1}")
- ("module" 1 "@samp{\\1}")
- ("moduleauthor" 2 "")
- ("modulesynopsis" 1 "\\1")
- ("moreargs" 0 "@dots{}")
- ("n" 0 "@backslash{}n")
- ("newcommand" 2 "")
- ("newlength" 1 "")
- ("newsgroup" 1 "@samp{\\1}")
- ("nodename" 1
- (save-excursion
- (save-match-data
- (re-search-backward "^@node "))
- (delete-region (point) (save-excursion (end-of-line) (point)))
- (insert "@node " (match-string 1 string))
- ""))
- ("noindent" 0 "@noindent ")
- ("note" 1 "@emph{Note:} \\1")
- ("NULL" 0 "@code{NULL}")
- ("obindex" 1 (progn (setq obindex t) "@obindex{\\1}"))
- ("opindex" 1 (progn (setq cindex t) "@cindex{\\1}"))
- ("option" 1 "@option{\\1}")
- ("optional" 1 "[\\1]")
- ("paragraph" 1 "@subsubheading \\1")
- ("pep" 1 (progn (setq cindex t) "PEP@ \\1@cindex PEP \\1\n"))
- ("pi" 0 "pi")
- ("platform" 1 "")
- ("plusminus" 0 "+-")
- ("POSIX" 0 "POSIX")
- ("production" 2 "@item \\1 \\2")
- ("productioncont" 1 "@item @w{} \\1")
- ("program" 1 "@command{\\1}")
- ("programopt" 1 "@option{\\1}")
- ("protect" 0 "")
- ("pytype" 1 "@code{\\1}")
- ("ref" 1 "@ref{\\1}")
- ("refbimodindex" 1 (progn (setq moindex t) "@moindex{\\1}"))
- ("refmodindex" 1 (progn (setq moindex t) "@moindex{\\1}"))
- ("refmodule" 1 "@samp{\\1}")
- ("refstmodindex" 1 (progn (setq moindex t) "@moindex{\\1}"))
- ("regexp" 1 "\"\\1\"")
- ("release" 1
- (progn (setq py2texi-python-version (match-string 1 string)) ""))
- ("renewcommand" 2 "")
- ("rfc" 1 (progn (setq cindex t) "RFC@ \\1@cindex RFC \\1\n"))
- ("rm" 0 "@destroy")
- ("samp" 1 "@samp{\\1}")
- ("section" 1 (let ((str (match-string 1 string)))
- (save-match-data
- (if (string-match "\\(.*\\)[ \t\n]*---[ \t\n]*\\(.*\\)"
- str)
- (format
- "@node %s\n@section %s\n"
- (py2texi-backslash-quote (match-string 1 str))
- (py2texi-backslash-quote (match-string 2 str)))
- "@node \\1\n@section \\1\n"))))
- ("sectionauthor" 2 "")
- ("seelink" 3 "\n@table @url\n@item @strong{\\1}\n(\\2)\n\\3\n@end table\n")
- ("seemodule" 2 "@ref{\\1} \\2")
- ("seepep" 3 "\n@table @strong\n@item PEP\\1 \\2\n\\3\n@end table\n")
- ("seerfc" 3 "\n@table @strong\n@item RFC\\1 \\2\n\\3\n@end table\n")
- ("seetext" 1 "\\1")
- ("seetitle" 1 "@cite{\\1}")
- ("seeurl" 2 "\n@table @url\n@item \\1\n\\2\n@end table\n")
- ("setindexsubitem" 1 (progn (setq cindex t) "@cindex \\1"))
- ("setlength" 2 "")
- ("setreleaseinfo" 1 (progn (setq py2texi-releaseinfo "")))
- ("setshortversion" 1
- (progn (setq py2texi-python-short-version (match-string 1 string)) ""))
- ("shortversion" 0 py2texi-python-short-version)
- ("sqrt" 0 "")
- ("stindex" 1 (progn (setq cindex t) "@cindex{\\1}"))
- ("stmodindex" 1 (progn (setq moindex t) "@moindex{\\1}"))
- ("strong" 1 "@strong{\\1}")
- ("sub" 0 "/")
- ("subsection" 1 "@node \\1\n@subsection \\1\n")
- ("subsubsection" 1 "@node \\1\n@subsubsection \\1\n")
- ("sum" 0 "")
- ("tableofcontents" 0 "")
- ("term" 1 "@item \\1")
- ("TeX" 0 "@TeX{}")
- ("textasciitilde" 0 "~")
- ("textasciicircum" 0 "^")
- ("textbackslash" 0 "@backslash{}")
- ("textbar" 0 "|")
- ("textbf" 1 "@strong{\\1}")
- ("texteuro" 0 "@euro{}")
- ; Unfortunately, this alternate spelling doesn't actually apply to
- ; the usage found in Python Tutorial, which actually requires a
- ; Euro symbol to make sense, so this is commented out as well.
- ; ("texteuro" 0 "Euro ")
- ("textgreater" 0 ">")
- ("textit" 1 "@i{\\1}")
- ("textless" 0 "<")
- ("textrm" 1 "\\1")
- ("texttt" 1 "@code{\\1}")
- ("textunderscore" 0 "_")
- ("tilde" 0 "~")
- ("title" 1 (progn (setq title (match-string 1 string)) "@settitle \\1"))
- ("today" 0 "@today{}")
- ("token" 1 "@code{\\1}")
- ("tt" 0 "@destroy")
- ("ttindex" 1 (progn (setq cindex t) "@cindex{\\1}"))
- ("u" 0 "@backslash{}u")
- ("ulink" 2 "\\1")
- ("UNIX" 0 "UNIX")
- ("undefined" 0 "")
- ("unspecified" 0 "@dots{}")
- ("url" 1 "@url{\\1}")
- ("usepackage" 1 "")
- ("var" 1 "@var{\\1}")
- ("verbatiminput" 1 "@code{\\1}")
- ("version" 0 py2texi-python-version)
- ("versionadded" 1 "@emph{Added in Python version \\1}")
- ("versionchanged" 1 "@emph{Changed in Python version \\1}")
- ("vskip" 1 "")
- ("vspace" 1 "")
- ("warning" 1 "@emph{\\1}")
- ("withsubitem" 2 "\\2")
- ("XXX" 1 "@strong{\\1}"))
- "Associative list of command substitutions.
-Each list item is of the form (COMMAND ARGNUM SUBSTITUTION) where:
-- COMMAND is LaTeX command name
-- ARGNUM is number of (required) command arguments
-- SUBSTITUTION substitution for the command. It is evaled and you can
- reference command arguments through the \\N regexp notation in strings.")
-
-(defvar py2texi-magic "@documentclass\n"
- "\"Magic\" string for auxiliary insertion at the beginning of document.")
-
-(defvar py2texi-dirs '("./" "../texinputs/")
- "Where to search LaTeX input files.")
-
-(defvar py2texi-buffer "*py2texi*"
- "The name of a buffer where Texinfo is generated.")
-
-(defconst py2texi-xemacs (string-match "^XEmacs" (emacs-version))
- "Running under XEmacs?")
-
-
-(defmacro py2texi-search (regexp &rest body)
- `(progn
- (goto-char (point-min))
- (while (re-search-forward ,regexp nil t)
- ,@body)))
-
-(defmacro py2texi-search-safe (regexp &rest body)
- `(py2texi-search ,regexp
- (unless (py2texi-protected)
- ,@body)))
-
-
-(defun py2texi-message (message)
- "Report message and stop if `py2texi-stop-on-problems' is non-nil."
- (if py2texi-stop-on-problems
- (error message)
- (message message)))
-
-
-(defun py2texi-backslash-quote (string)
- "Double backslahes in STRING."
- (let ((i 0))
- (save-match-data
- (while (setq i (string-match "\\\\" string i))
- (setq string (replace-match "\\\\\\\\" t nil string))
- (setq i (+ i 2))))
- string))
-
-
-(defun py2texi (file)
- "Convert Python LaTeX documentation FILE to Texinfo."
- (interactive "fFile to convert: ")
- (switch-to-buffer (get-buffer-create py2texi-buffer))
- (erase-buffer)
- (insert-file file)
- (let ((case-fold-search nil)
- (title "")
- (author "")
- (author-address "")
- (appendix nil)
- (findex nil)
- (obindex nil)
- (cindex nil)
- (moindex nil)
- last-if)
- (py2texi-process-verbatims)
- (py2texi-process-comments)
- (py2texi-process-includes)
- (py2texi-process-funnyas)
- (py2texi-process-environments)
- (py2texi-process-commands)
- (py2texi-fix-indentation)
- (py2texi-fix-nodes)
- (py2texi-fix-references)
- (py2texi-fix-indices)
- (py2texi-process-simple-commands)
- (py2texi-fix-fonts)
- (py2texi-fix-braces)
- (py2texi-fix-backslashes)
- (py2texi-destroy-empties)
- (py2texi-fix-newlines)
- (py2texi-adjust-level))
- (let* ((texi-file-name (or py2texi-texi-file-name
- (py2texi-texi-file-name file)))
- (info-file-name (or py2texi-info-file-name
- (py2texi-info-file-name texi-file-name))))
- (goto-char (point-min))
- (when (looking-at py2texi-magic)
- (delete-region (point) (progn (beginning-of-line 2) (point)))
- (insert "\\input texinfo @c -*-texinfo-*-\n")
- (insert "@setfilename " info-file-name))
- (when (re-search-forward "@chapter" nil t)
- (texinfo-all-menus-update t))
- (goto-char (point-min))
- (write-file texi-file-name)
- (message (format "You can apply `makeinfo %s' now." texi-file-name))))
-
-
-(defun py2texi-texi-file-name (filename)
- "Generate name of Texinfo file from original file name FILENAME."
- (concat filename
- (if (string-match "\\.tex$" filename) "i" ".texi")))
-
-
-(defun py2texi-info-file-name (filename)
- "Generate name of info file from original file name FILENAME."
- (setq filename (expand-file-name filename))
- (let ((directory (file-name-directory filename))
- (basename (file-name-nondirectory filename)))
- (concat directory "python-"
- (substring basename 0 (- (length basename) 4)) "info")))
-
-
-(defun py2texi-process-verbatims ()
- "Process and protect verbatim environments."
- (let (delimiter
- beg
- end)
- (py2texi-search-safe "\\\\begin{\\(verbatim\\|displaymath\\)}"
- (when (save-excursion
- ; Make sure we aren't looking at a commented out version
- ; of a verbatim environment
- (beginning-of-line)
- (not (looking-at "%")))
- (replace-match "@example ")
- (setq beg (copy-marker (point) nil))
- (re-search-forward "\\\\end{\\(verbatim\\|displaymath\\)}")
- (setq end (copy-marker (match-beginning 0) nil))
- (replace-match "@end example")
- (py2texi-texinfo-escape beg end)
- (put-text-property (- beg (length "@example "))
- (+ end (length "@end example"))
- 'py2texi-protected t)))
- (py2texi-search-safe "\\\\verb\\([^a-z]\\)"
- (setq delimiter (match-string 1))
- (replace-match "@code{")
- (setq beg (copy-marker (point) nil))
- (re-search-forward (regexp-quote delimiter))
- (setq end (copy-marker (match-beginning 0) nil))
- (replace-match "}")
- (put-text-property (- beg (length "@code{")) (+ end (length "}"))
- 'py2texi-protected t)
- (py2texi-texinfo-escape beg end))))
-
-
-(defun py2texi-process-comments ()
- "Remove comments."
- (let (point)
- (py2texi-search-safe "%"
- (setq point (point))
- (when (save-excursion
- (re-search-backward "\\(^\\|[^\\]\\(\\\\\\\\\\)*\\)%\\=" nil t))
- (delete-region (1- point)
- (save-excursion (beginning-of-line 2) (point)))))))
-
-
-(defun py2texi-process-includes ()
- "Include LaTeX input files.
-Do not include .ind files."
- (let ((path (file-name-directory file))
- filename
- dirs
- includefile)
- (py2texi-search-safe "\\\\input{\\([^}]+\\)}"
- (setq filename (match-string 1))
- (unless (save-match-data (string-match "\\.tex$" filename))
- (setq filename (concat filename ".tex")))
- (setq includefile (save-match-data
- (string-match "\\.ind\\.tex$" filename)))
- (setq dirs py2texi-dirs)
- (while (and (not includefile) dirs)
- (setq includefile
- (concat (file-name-as-directory (car dirs)) filename))
- (if (not (file-name-absolute-p includefile))
- (setq includefile
- (concat (file-name-as-directory path) includefile)))
- (unless (file-exists-p includefile)
- (setq includefile nil)
- (setq dirs (cdr dirs))))
- (if includefile
- (save-restriction
- (narrow-to-region (match-beginning 0) (match-end 0))
- (delete-region (point-min) (point-max))
- (when (stringp includefile)
- (insert-file-contents includefile)
- (goto-char (point-min))
- (insert "\n")
- (py2texi-process-verbatims)
- (py2texi-process-comments)
- (py2texi-process-includes)))
- (replace-match (format "\\\\emph{Included file %s}" filename))
- (py2texi-message (format "Input file %s not found" filename))))))
-
-
-(defun py2texi-process-funnyas ()
- "Convert @s."
- (py2texi-search-safe "@"
- (replace-match "@@")))
-
-
-(defun py2texi-process-environments ()
- "Process LaTeX environments."
- (let ((stack ())
- kind
- environment
- parameter
- arguments
- n
- string
- description)
- (py2texi-search-safe (concat "\\\\\\(begin\\|end\\|item\\)"
- "\\({\\([^}]*\\)}\\|[[]\\([^]]*\\)[]]\\|\\)")
- (setq kind (match-string 1)
- environment (match-string 3)
- parameter (match-string 4))
- (replace-match "")
- (cond
- ((string= kind "begin")
- (setq description (assoc environment py2texi-environments))
- (if description
- (progn
- (setq n (cadr description))
- (setq description (cddr description))
- (setq string (py2texi-tex-arguments n))
- (string-match (py2texi-regexp n) string)
- ; incorrect but sufficient
- (insert (replace-match (eval (car description))
- t nil string))
- (setq stack (cons (cadr description) stack)))
- (py2texi-message (format "Unknown environment: %s" environment))
- (setq stack (cons "" stack))))
- ((string= kind "end")
- (insert (eval (car stack)))
- (setq stack (cdr stack)))
- ((string= kind "item")
- (insert "\n@item " (or parameter "") "\n"))))
- (when stack
- (py2texi-message (format "Unclosed environment: %s" (car stack))))))
-
-
-(defun py2texi-process-commands ()
- "Process LaTeX commands."
- (let (done
- command
- command-info
- string
- n)
- (while (not done)
- (setq done t)
- (py2texi-search-safe "\\\\\\([a-zA-Z*]+\\)\\(\\[[^]]*\\]\\)?"
- (setq command (match-string 1))
- (setq command-info (assoc command py2texi-commands))
- (if command-info
- (progn
- (setq done nil)
- (replace-match "")
- (setq command-info (cdr command-info))
- (setq n (car command-info))
- (setq string (py2texi-tex-arguments n))
- (string-match (py2texi-regexp n) string)
- ; incorrect but sufficient
- (insert (replace-match (eval (cadr command-info))
- t nil string)))
- (py2texi-message (format "Unknown command: %s (not processed)"
- command)))))))
-
-
-(defun py2texi-argument-pattern (count)
- (let ((filler "\\(?:[^{}]\\|\\\\{\\|\\\\}\\)*"))
- (if (<= count 0)
- filler
- (concat filler "\\(?:{"
- (py2texi-argument-pattern (1- count))
- "}" filler "\\)*" filler))))
-(defconst py2texi-tex-argument
- (concat
- "{\\("
- (py2texi-argument-pattern 10) ;really at least 10!
- "\\)}[ \t%@c\n]*")
- "Regexp describing LaTeX command argument including argument separators.")
-
-
-(defun py2texi-regexp (n)
- "Make regexp matching N LaTeX command arguments."
- (if (= n 0)
- ""
- (let ((regexp "^[^{]*"))
- (while (> n 0)
- (setq regexp (concat regexp py2texi-tex-argument))
- (setq n (1- n)))
- regexp)))
-
-
-(defun py2texi-tex-arguments (n)
- "Remove N LaTeX command arguments and return them as a string."
- (let ((point (point))
- (i 0)
- result
- match)
- (if (= n 0)
- (progn
- (when (re-search-forward "\\=\\({}\\| *\\)" nil t)
- (replace-match ""))
- "")
- (while (> n 0)
- (unless (re-search-forward
- "\\(\\=\\|[^\\\\]\\)\\(\\\\\\\\\\)*\\([{}]\\)" nil t)
- (debug))
- (if (string= (match-string 3) "{")
- (setq i (1+ i))
- (setq i (1- i))
- (when (<= i 0)
- (setq n (1- n)))))
- (setq result (buffer-substring-no-properties point (point)))
- (while (string-match "\n[ \t]*" result)
- (setq result (replace-match " " t nil result)))
- (delete-region point (point))
- result)))
-
-
-(defun py2texi-process-simple-commands ()
- "Replace single character LaTeX commands."
- (let (char)
- (py2texi-search-safe "\\\\\\([^a-z]\\)"
- (setq char (match-string 1))
- (replace-match (format "%s%s"
- (if (or (string= char "{")
- (string= char "}")
- (string= char " "))
- "@"
- "")
- (if (string= char "\\")
- "\\\\"
- char))))))
-
-
-(defun py2texi-fix-indentation ()
- "Remove white space at the beginning of lines."
- (py2texi-search-safe "^[ \t]+"
- (replace-match "")))
-
-
-(defun py2texi-fix-nodes ()
- "Remove unwanted characters from nodes and make nodes unique."
- (let ((nodes (make-hash-table :test 'equal))
- id
- counter
- string
- label
- index)
- (py2texi-search "^@node +\\(.*\\)$"
- (setq string (match-string 1))
- (if py2texi-xemacs
- (replace-match "@node " t)
- (replace-match "" t nil nil 1))
- (while (string-match "@label{[^}]*}" string)
- (setq label (match-string 0 string))
- (setq string (replace-match "" t nil string)))
- (while (string-match "@..?index{[^}]*}" string)
- (setq index (match-string 0 string))
- (setq string (replace-match "" t nil string)))
- (while (string-match "@[a-zA-Z]+\\|[{}():]\\|``\\|''" string)
- (setq string (replace-match "" t nil string)))
- (while (string-match " -- " string)
- (setq string (replace-match " - " t nil string)))
- (while (string-match "\\." string)
- (setq string (replace-match "" t nil string)))
- (when (string-match " +$" string)
- (setq string (replace-match "" t nil string)))
- (when (string-match "^\\(Built-in\\|Standard\\) Module \\|The " string)
- (setq string (replace-match "" t nil string)))
- (string-match "^[^,]+" string)
- (setq id (match-string 0 string))
- (setq counter (gethash id nodes))
- (if counter
- (progn
- (setq counter (1+ counter))
- (setq string (replace-match (format "\\& %d" counter)
- t nil string)))
- (setq counter 1))
- (setf (gethash id nodes) counter)
- (insert string)
- (beginning-of-line 3)
- (when label
- (insert label "\n"))
- (when index
- (insert index "\n")))))
-
-
-(defun py2texi-fix-references ()
- "Process labels and make references to point to appropriate nodes."
- (let ((labels ())
- node)
- (py2texi-search-safe "@label{\\([^}]*\\)}"
- (setq node (save-excursion
- (save-match-data
- (and (re-search-backward "@node +\\([^,\n]+\\)" nil t)
- (match-string 1)))))
- (when node
- (setq labels (cons (cons (match-string 1) node) labels)))
- (replace-match ""))
- (py2texi-search-safe "@ref{\\([^}]*\\)}"
- (setq node (assoc (match-string 1) labels))
- (replace-match "")
- (when node
- (insert (format "@ref{%s}" (cdr node)))))))
-
-
-(defun py2texi-fix-indices ()
- "Remove unwanted characters from @*index commands and create final indices."
- (py2texi-search-safe "@..?index\\>[^\n]*\\(\\)\n"
- (replace-match "" t nil nil 1))
- (py2texi-search-safe "@..?index\\>[^\n]*\\(\\)"
- (replace-match "\n" t nil nil 1))
- (py2texi-search-safe "@..?index\\({\\)\\([^}]+\\)\\(}+\\)"
- (replace-match " " t nil nil 1)
- (replace-match "" t nil nil 3)
- (let ((string (match-string 2)))
- (save-match-data
- (while (string-match "@[a-z]+{" string)
- (setq string (replace-match "" nil nil string)))
- (while (string-match "{" string)
- (setq string (replace-match "" nil nil string))))
- (replace-match string t t nil 2)))
- (py2texi-search-safe "@..?index\\>.*\\([{}]\\|@[a-z]*\\)"
- (replace-match "" t nil nil 1)
- (goto-char (match-beginning 0)))
- (py2texi-search-safe "[^\n]\\(\\)@..?index\\>"
- (replace-match "\n" t nil nil 1))
- (goto-char (point-max))
- (re-search-backward "@indices")
- (replace-match "")
- (insert (if moindex
- (concat "@node Module Index\n"
- "@unnumbered Module Index\n"
- "@printindex mo\n")
- "")
- (if obindex
- (concat "@node Class-Exception-Object Index\n"
- "@unnumbered Class, Exception, and Object Index\n"
- "@printindex ob\n")
- "")
- (if findex
- (concat "@node Function-Method-Variable Index\n"
- "@unnumbered Function, Method, and Variable Index\n"
- "@printindex fn\n")
- "")
- (if cindex
- (concat "@node Miscellaneous Index\n"
- "@unnumbered Miscellaneous Index\n"
- "@printindex cp\n")
- "")))
-
-
-(defun py2texi-fix-backslashes ()
- "Make backslashes from auxiliary commands."
- (py2texi-search-safe "@backslash{}"
- (replace-match "\\\\")))
-
-
-(defun py2texi-fix-fonts ()
- "Remove garbage after unstructured font commands."
- (let (string)
- (py2texi-search-safe "@destroy"
- (replace-match "")
- (when (eq (preceding-char) ?{)
- (forward-char -1)
- (setq string (py2texi-tex-arguments 1))
- (insert (substring string 1 (1- (length string))))))))
-
-
-(defun py2texi-fix-braces ()
- "Escape braces for Texinfo."
- (py2texi-search "{@{}"
- (replace-match "@{"))
- (py2texi-search "{@}}"
- (replace-match "@}"))
- (let (string)
- (py2texi-search "{"
- (unless (or (py2texi-protected)
- (save-excursion
- (re-search-backward
- "@\\([a-zA-Z]*\\|multitable.*\\){\\=" nil t)))
- (forward-char -1)
- (setq string (py2texi-tex-arguments 1))
- (insert "@" (substring string 0 (1- (length string))) "@}")))))
-
-
-(defun py2texi-fix-newlines ()
- "Remove extra newlines."
- (py2texi-search "\n\n\n+"
- (replace-match "\n\n"))
- (py2texi-search-safe "@item.*\n\n"
- (delete-backward-char 1))
- (py2texi-search "@end example"
- (unless (looking-at "\n\n")
- (insert "\n"))))
-
-
-(defun py2texi-destroy-empties ()
- "Remove all comments.
-This avoids some makeinfo errors."
- (py2texi-search "@c\\>"
- (unless (eq (py2texi-protected) t)
- (delete-region (- (point) 2) (save-excursion (end-of-line) (point)))
- (cond
- ((looking-at "\n\n")
- (delete-char 1))
- ((save-excursion (re-search-backward "^[ \t]*\\=" nil t))
- (delete-region (save-excursion (beginning-of-line) (point))
- (1+ (point))))))))
-
-
-(defun py2texi-adjust-level ()
- "Increase heading level to @chapter, if needed.
-This is only needed for distutils, so it has a very simple form only."
- (goto-char (point-min))
- (unless (re-search-forward "@chapter\\>" nil t)
- (py2texi-search-safe "@section\\>"
- (replace-match "@chapter" t))
- (py2texi-search-safe "@\\(sub\\)\\(sub\\)?section\\>"
- (replace-match "" nil nil nil 1))))
-
-
-(defun py2texi-texinfo-escape (beg end)
- "Escape Texinfo special characters in region."
- (save-excursion
- (goto-char beg)
- (while (re-search-forward "[@{}]" end t)
- (replace-match "@\\&"))))
-
-
-(defun py2texi-protected ()
- "Return protection status of the point before current point."
- (get-text-property (1- (point)) 'py2texi-protected))
-
-
-;;; Announce
-
-(provide 'py2texi)
-
-
-;;; py2texi.el ends here
diff --git a/Doc/tools/refcounts.py b/Doc/tools/refcounts.py
deleted file mode 100644
index 9efb073..0000000
--- a/Doc/tools/refcounts.py
+++ /dev/null
@@ -1,97 +0,0 @@
-"""Support functions for loading the reference count data file."""
-__version__ = '$Revision$'
-
-import os
-import sys
-
-
-# Determine the expected location of the reference count file:
-try:
- p = os.path.dirname(__file__)
-except NameError:
- p = os.path.dirname(sys.argv[0])
-p = os.path.normpath(os.path.join(os.getcwd(), p, os.pardir,
- "api", "refcounts.dat"))
-DEFAULT_PATH = p
-del p
-
-
-def load(path=DEFAULT_PATH):
- return loadfile(open(path))
-
-
-def loadfile(fp):
- d = {}
- while 1:
- line = fp.readline()
- if not line:
- break
- line = line.strip()
- if line[:1] in ("", "#"):
- # blank lines and comments
- continue
- parts = line.split(":", 4)
- if len(parts) != 5:
- raise ValueError("Not enough fields in %r" % line)
- function, type, arg, refcount, comment = parts
- if refcount == "null":
- refcount = None
- elif refcount:
- refcount = int(refcount)
- else:
- refcount = None
- #
- # Get the entry, creating it if needed:
- #
- try:
- entry = d[function]
- except KeyError:
- entry = d[function] = Entry(function)
- #
- # Update the entry with the new parameter or the result information.
- #
- if arg:
- entry.args.append((arg, type, refcount))
- else:
- entry.result_type = type
- entry.result_refs = refcount
- return d
-
-
-class Entry:
- def __init__(self, name):
- self.name = name
- self.args = []
- self.result_type = ''
- self.result_refs = None
-
-
-def dump(d):
- """Dump the data in the 'canonical' format, with functions in
- sorted order."""
- items = sorted(d.items())
- first = 1
- for k, entry in items:
- if first:
- first = 0
- else:
- print()
- s = entry.name + ":%s:%s:%s:"
- if entry.result_refs is None:
- r = ""
- else:
- r = entry.result_refs
- print(s % (entry.result_type, "", r))
- for t, n, r in entry.args:
- if r is None:
- r = ""
- print(s % (t, n, r))
-
-
-def main():
- d = load()
- dump(d)
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/rewrite.py b/Doc/tools/rewrite.py
deleted file mode 100644
index 1acdd99..0000000
--- a/Doc/tools/rewrite.py
+++ /dev/null
@@ -1,54 +0,0 @@
-"""Simple script to replace @DATE@ and friends with real information.
-
-Usage: rewrite.py boilerplate.tex [VAR=value] ... <template >output
-"""
-
-import sys
-import time
-
-
-def get_info(fp):
- s = fp.read()
-
- d = {}
- start = s.find(r"\date{")
- if start >= 0:
- end = s.find("}", start)
- date = s[start+6:end]
- if date == r"\today":
- date = time.strftime("%B %d, %Y", time.localtime(time.time()))
- d["DATE"] = date
- return d
-
-
-def main():
- s = sys.stdin.read()
- if "@" in s:
- # yes, we actully need to load the replacement values
- d = get_info(open(sys.argv[1]))
- for arg in sys.argv[2:]:
- name, value = arg.split("=", 1)
- d[name] = value
- start = 0
- while 1:
- start = s.find("@", start)
- if start < 0:
- break
- end = s.find("@", start+1)
- name = s[start+1:end]
- if name:
- value = d.get(name)
- if value is None:
- start = end + 1
- else:
- s = s[:start] + value + s[end+1:]
- start = start + len(value)
- else:
- # "@@" --> "@"
- s = s[:start] + s[end:]
- start = end
- sys.stdout.write(s)
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/sgmlconv/Makefile b/Doc/tools/sgmlconv/Makefile
deleted file mode 100644
index d222933..0000000
--- a/Doc/tools/sgmlconv/Makefile
+++ /dev/null
@@ -1,67 +0,0 @@
-# Simple makefile to control XML generation for the entire document tree.
-# This should be used from the top-level directory (Doc/), not the directory
-# that actually contains this file:
-#
-# $ pwd
-# .../Doc
-# $ make -f tools/sgmlconv/Makefile
-
-TOPDIR=.
-TOOLSDIR=tools
-
-SGMLRULES=../$(TOOLSDIR)/sgmlconv/make.rules
-# The 'inst' and 'tut' directories break the conversion, so skip them for now.
-SUBDIRS=api dist ext lib mac ref
-SUBMAKE=$(MAKE) -f $(SGMLRULES) TOOLSDIR=../$(TOOLSDIR)
-
-all: xml
-
-.PHONY: esis xml
-.PHONY: $(SUBDIRS)
-
-xml:
- for DIR in $(SUBDIRS) ; do \
- (cd $$DIR && $(SUBMAKE) xml) || exit $$? ; done
-
-esis:
- for DIR in $(SUBDIRS) ; do \
- (cd $$DIR && $(SUBMAKE) esis) || exit $$? ; done
-
-esis1:
- for DIR in $(SUBDIRS) ; do \
- (cd $$DIR && $(SUBMAKE) esis1) || exit $$? ; done
-
-tarball: xml
- tar cf - tools/sgmlconv */*.xml | gzip -9 >xml-1.5.2b2.tgz
-
-api:
- cd api && $(SUBMAKE)
-
-dist:
- cd dist && $(SUBMAKE)
-
-ext:
- cd ext && $(SUBMAKE)
-
-inst:
- cd inst && $(SUBMAKE)
-
-lib:
- cd lib && $(SUBMAKE)
-
-mac:
- cd mac && $(SUBMAKE)
-
-ref:
- cd ref && $(SUBMAKE)
-
-tut:
- cd tut && $(SUBMAKE)
-
-clean:
- for DIR in $(SUBDIRS) ; do \
- (cd $$DIR && $(SUBMAKE) clean) || exit $$? ; done
-
-clobber:
- for DIR in $(SUBDIRS) ; do \
- (cd $$DIR && $(SUBMAKE) clobber) || exit $$? ; done
diff --git a/Doc/tools/sgmlconv/README b/Doc/tools/sgmlconv/README
deleted file mode 100644
index 02564eb..0000000
--- a/Doc/tools/sgmlconv/README
+++ /dev/null
@@ -1,58 +0,0 @@
-These scripts and Makefile fragment are used to convert the Python
-documentation in LaTeX format to XML.
-
-This material is preliminary and incomplete. Python 2.0 is required.
-
-To convert all documents to XML:
-
- cd Doc/
- make -f tools/sgmlconv/Makefile
-
-To convert one document to XML:
-
- cd Doc/<document-dir>
- make -f ../tools/sgmlconv/make.rules TOOLSDIR=../tools
-
-Please send comments and bug reports to docs@python.org.
-
-
-What do the tools do?
----------------------
-
-latex2esis.py
- Reads in a conversion specification written in XML
- (conversion.xml), reads a LaTeX document fragment, and interprets
- the markup according to the specification. The output is a stream
- of ESIS events like those created by the nsgmls SGML parser, but
- is *not* guaranteed to represent a single tree! This is done to
- allow conversion per entity rather than per document. Since many
- of the LaTeX files for the Python documentation contain two
- sections on closely related modules, it is important to allow both
- of the resulting <section> elements to exist in the same output
- stream. Additionally, since comments are not supported in ESIS,
- comments are converted to <COMMENT> elements, which might exist at
- the same level as the top-level content elements.
-
- The output of latex2esis.py gets saved as <filename>.esis1.
-
-docfixer.py
- This is the really painful part of the conversion. Well, it's the
- second really painful part, but more of the pain is specific to
- the structure of the Python documentation and desired output
- rather than to the parsing of LaTeX markup.
-
- This script loads the ESIS data created by latex2esis.py into a
- DOM document *fragment* (remember, the latex2esis.py output may
- not be well-formed). Once loaded, it walks over the tree many
- times looking for a variety of possible specific
- micro-conversions. Most of the code is not in any way "general".
- After processing the fragment, a new ESIS data stream is written
- out. Like the input, it may not represent a well-formed
- document, but does represent a parsed entity.
-
- The output of docfixer.py is what gets saved in <filename>.esis.
-
-esis2sgml.py
- Reads an ESIS stream and convert to SGML or XML. This also
- converts <COMMENT> elements to real comments. This works quickly
- because there's not much to actually do.
diff --git a/Doc/tools/sgmlconv/conversion.xml b/Doc/tools/sgmlconv/conversion.xml
deleted file mode 100644
index f0151f4..0000000
--- a/Doc/tools/sgmlconv/conversion.xml
+++ /dev/null
@@ -1,914 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<conversion>
- <!-- Miscellaneous. -->
- <macro name="declaremodule">
- <attribute name="id" optional="yes"/>
- <attribute name="type"/>
- <attribute name="name"/>
- </macro>
- <macro name="modulesynopsis">
- <content/>
- </macro>
- <macro name="platform">
- <content/>
- </macro>
- <macro name="deprecated">
- <attribute name="version"/>
- <content/>
- </macro>
- <macro name="label">
- <attribute name="id"/>
- </macro>
- <macro name="nodename" outputname="label">
- <attribute name="id"/>
- </macro>
- <macro name="localmoduletable"/>
- <macro name="manpage">
- <attribute name="name"/>
- <attribute name="section"/>
- </macro>
- <macro name="module">
- <content/>
- </macro>
- <macro name="moduleauthor">
- <attribute name="name"/>
- <attribute name="email"/>
- </macro>
- <macro name="citetitle">
- <attribute name="href" optional="yes"/>
- <content/>
- </macro>
- <macro name="pep">
- <attribute name="num"/>
- </macro>
- <macro name="rfc">
- <attribute name="num"/>
- </macro>
- <macro name="sectionauthor" outputname="author">
- <attribute name="name"/>
- <attribute name="email"/>
- </macro>
- <macro name="author">
- <attribute name="name"/>
- </macro>
- <macro name="authoraddress">
- <content/>
- </macro>
- <macro name="shortversion"/>
- <macro name="note">
- <content/>
- </macro>
- <macro name="warning">
- <content/>
- </macro>
- <environment name="notice">
- <attribute name="role" optional="yes"/>
- </environment>
-
- <macro name="menuselection">
- <content/>
- </macro>
- <macro name="sub"/>
-
- <!-- These are broken: we need to re-order the optional and required
- parameters, making the optional parameter the content for the
- element. latex2esis.py is not powerful enough to handle this.
- -->
- <macro name="versionadded">
- <attribute name="info" optional="yes"/>
- <attribute name="version"/>
- </macro>
- <macro name="versionchanged">
- <attribute name="info" optional="yes"/>
- <attribute name="version"/>
- </macro>
-
- <!-- Module referencing. -->
- <macro name="refmodule" outputname="module">
- <!-- this causes the optional parameter to \refmodule to be
- discarded -->
- <attribute name="" optional="yes"/>
- <content/>
- </macro>
-
- <!-- Information units. -->
- <!-- C things. -->
- <environment name="cfuncdesc">
- <attribute name="type"/>
- <attribute name="name"/>
- <child name="args"/>
- </environment>
- <environment name="csimplemacrodesc">
- <attribute name="name"/>
- </environment>
- <environment name="ctypedesc">
- <attribute name="tag" optional="yes"/>
- <attribute name="name"/>
- </environment>
- <environment name="cvardesc">
- <attribute name="type"/>
- <attribute name="name"/>
- </environment>
-
- <!-- Python things. -->
- <macro name="optional">
- <content/>
- </macro>
- <macro name="unspecified"/>
- <macro name="moreargs"/>
- <environment name="classdesc">
- <attribute name="name"/>
- <child name="args"/>
- </environment>
- <environment name="classdesc*" outputname="classdesc">
- <attribute name="name"/>
- </environment>
- <environment name="datadesc">
- <attribute name="name"/>
- </environment>
- <environment name="datadescni" outputname="datadesc">
- <attribute name="index">no</attribute>
- <attribute name="name"/>
- </environment>
- <macro name="dataline">
- <attribute name="name"/>
- </macro>
- <environment name="excclassdesc">
- <attribute name="name"/>
- <child name="args"/>
- </environment>
- <environment name="excdesc">
- <attribute name="name"/>
- </environment>
-
- <environment name="funcdesc">
- <attribute name="name"/>
- <child name="args"/>
- </environment>
- <macro name="funcline">
- <attribute name="name"/>
- <child name="args"/>
- </macro>
- <environment name="funcdescni" outputname="funcdesc">
- <attribute name="index">no</attribute>
- <attribute name="name"/>
- <child name="args"/>
- </environment>
- <macro name="funclineni" outputname="funcline">
- <attribute name="index">no</attribute>
- <attribute name="name"/>
- <child name="args"/>
- </macro>
-
- <environment name="memberdesc">
- <attribute name="class" optional="yes"/>
- <attribute name="name"/>
- </environment>
- <environment name="memberdescni" outputname="memberdesc">
- <attribute name="index">no</attribute>
- <attribute name="class" optional="yes"/>
- <attribute name="name"/>
- </environment>
- <macro name="memberline">
- <attribute name="name"/>
- </macro>
-
- <environment name="methoddesc">
- <attribute name="class" optional="yes"/>
- <attribute name="name"/>
- <child name="args"/>
- </environment>
- <macro name="methodline">
- <attribute name="class" optional="yes"/>
- <attribute name="name"/>
- <child name="args"/>
- </macro>
- <environment name="methoddescni">
- <attribute name="index">no</attribute>
- <attribute name="class" optional="yes"/>
- <attribute name="name"/>
- <child name="args"/>
- </environment>
- <macro name="methodlineni" outputname="methodline">
- <attribute name="index">no</attribute>
- <attribute name="class" optional="yes"/>
- <attribute name="name"/>
- <child name="args"/>
- </macro>
-
- <environment name="opcodedesc">
- <attribute name="name"/>
- <attribute name="var"/>
- </environment>
-
- <!-- "See also:" sections. -->
- <environment name="seealso*" outputname="seealso">
- <attribute name="sidebar">no</attribute>
- </environment>
- <macro name="seemodule">
- <!-- this causes the optional parameter to \seemodule to be
- discarded -->
- <attribute name="" optional="yes"/>
- <attribute name="name"/>
- <child name="description"/>
- </macro>
- <macro name="seepep">
- <attribute name="number"/>
- <child name="title"/>
- <child name="description"/>
- </macro>
- <macro name="seerfc">
- <attribute name="number"/>
- <child name="title"/>
- <child name="description"/>
- </macro>
- <macro name="seetext">
- <child name="description"/>
- </macro>
- <macro name="seetitle">
- <attribute name="href" optional="yes"/>
- <child name="title"/>
- <child name="description"/>
- </macro>
- <macro name="seeurl">
- <attribute name="href"/>
- <child name="description"/>
- </macro>
-
- <!-- Index-generating markup. -->
- <macro name="index" outputname="indexterm">
- <attribute name="term1"/>
- </macro>
- <macro name="indexii" outputname="indexterm">
- <attribute name="term1"/>
- <attribute name="term2"/>
- </macro>
- <macro name="indexiii" outputname="indexterm">
- <attribute name="term1"/>
- <attribute name="term2"/>
- <attribute name="term3"/>
- </macro>
- <macro name="indexiv" outputname="indexterm">
- <attribute name="term1"/>
- <attribute name="term2"/>
- <attribute name="term3"/>
- <attribute name="term4"/>
- </macro>
-
- <macro name="ttindex" outputname="indexterm">
- <attribute name="style">tt</attribute>
- <attribute name="term1"/>
- </macro>
-
- <macro name="refmodindex">
- <attribute name="module"/>
- </macro>
- <macro name="stmodindex">
- <attribute name="module"/>
- </macro>
- <macro name="refbimodindex" outputname="refmodindex">
- <attribute name="module"/>
- </macro>
- <macro name="refexmodindex" outputname="refmodindex">
- <attribute name="module"/>
- </macro>
- <macro name="refstmodindex" outputname="refmodindex">
- <attribute name="module"/>
- </macro>
-
- <macro name="bifuncindex">
- <attribute name="name"/>
- </macro>
- <macro name="exindex">
- <attribute name="name"/>
- </macro>
- <macro name="obindex">
- <attribute name="name"/>
- </macro>
- <macro name="kwindex">
- <attribute name="name"/>
- </macro>
- <macro name="opindex">
- <attribute name="type"/>
- </macro>
- <macro name="stindex">
- <attribute name="type"/>
- </macro>
- <macro name="withsubitem">
- <attribute name="text"/>
- <content/>
- </macro>
- <macro name="setindexsubitem">
- <attribute name="text"/>
- </macro>
-
- <!-- Entity management. -->
- <macro name="include" outputname="xi:include">
- <attribute name="href"/>
- </macro>
- <macro name="input" outputname="xi:include">
- <attribute name="href"/>
- </macro>
-
- <!-- Large-scale document structure. -->
- <macro name="documentclass">
- <attribute name="classname"/>
- </macro>
-
- <macro name="usepackage">
- <attribute name="options" optional="yes"/>
- <attribute name="pkg"/>
- </macro>
-
- <environment name="document"
- endcloses="chapter chapter* section section*
- subsection subsection*
- subsubsection subsubsection*
- paragraph paragraph* subparagraph
- subparagraph*">
- <attribute name="xmlns:xi"
- >http://www.w3.org/2001/XInclude</attribute>
- </environment>
-
- <macro name="chapter"
- closes="chapter chapter* section section* subsection subsection*
- subsubsection subsubsection*
- paragraph paragraph* subparagraph subparagraph*">
- <text>
-</text>
- <child name="title"/>
- <content implied="yes"/>
- </macro>
- <macro name="chapter*" outputname="chapter"
- closes="chapter chapter* section section* subsection subsection*
- subsubsection subsubsection*
- paragraph paragraph* subparagraph subparagraph*">
- <attribute name="numbered">no</attribute>
- <text>
-</text>
- <child name="title"/>
- <content implied="yes"/>
- </macro>
-
- <macro name="section"
- closes="section section* subsection subsection*
- subsubsection subsubsection*
- paragraph paragraph* subparagraph subparagraph*">
- <text>
-</text>
- <child name="title"/>
- <content implied="yes"/>
- </macro>
- <macro name="section*" outputname="section"
- closes="section section* subsection subsection*
- subsubsection subsubsection*
- paragraph paragraph* subparagraph subparagraph*">
- <attribute name="numbered">no</attribute>
- <text>
-</text>
- <child name="title"/>
- <content implied="yes"/>
- </macro>
-
- <macro name="subsection"
- closes="subsection subsection* subsubsection subsubsection*
- paragraph paragraph* subparagraph subparagraph*">
- <text>
-</text>
- <child name="title"/>
- <content implied="yes"/>
- </macro>
- <macro name="subsection*" outputname="subsection"
- closes="subsection subsection* subsubsection subsubsection*
- paragraph paragraph* subparagraph subparagraph*">
- <attribute name="numbered">no</attribute>
- <text>
-</text>
- <child name="title"/>
- <content implied="yes"/>
- </macro>
-
- <macro name="subsubsection"
- closes="subsubsection subsubsection*
- paragraph paragraph* subparagraph subparagraph*">
- <text>
-</text>
- <child name="title"/>
- <content implied="yes"/>
- </macro>
- <macro name="subsubsection*" outputname="subsubsection"
- closes="subsubsection subsubsection*
- paragraph paragraph* subparagraph subparagraph*">
- <attribute name="numbered">no</attribute>
- <text>
-</text>
- <child name="title"/>
- <content implied="yes"/>
- </macro>
-
- <macro name="paragraph"
- closes="paragraph paragraph* subparagraph subparagraph*">
- <text>
-</text>
- <child name="title"/>
- <content implied="yes"/>
- </macro>
- <macro name="paragraph*" outputname="paragraph"
- closes="paragraph paragraph* subparagraph subparagraph*">
- <attribute name="numbered">no</attribute>
- <text>
-</text>
- <child name="title"/>
- <content implied="yes"/>
- </macro>
-
- <macro name="subparagraph"
- closes="subparagraph subparagraph*">
- <text>
-</text>
- <child name="title"/>
- <content implied="yes"/>
- </macro>
- <macro name="subparagraph*" outputname="subparagraph"
- closes="subparagraph subparagraph*">
- <attribute name="numbered">no</attribute>
- <text>
-</text>
- <child name="title"/>
- <content implied="yes"/>
- </macro>
- <macro name="title">
- <content/>
- </macro>
-
- <macro name="appendix" outputname="back-matter"
- closes="chapter chapter* section subsection subsubsection
- paragraph subparagraph"/>
-
- <environment name="list"
- endcloses="item">
- <attribute name="bullet"/>
- <attribute name="init"/>
- </environment>
- <macro name="item" closes="item">
- <child name="leader" optional="yes"/>
- <content implied="yes"/>
- </macro>
-
- <macro name="ref">
- <attribute name="ref"/>
- </macro>
-
- <environment name="description" outputname="descriptionlist"
- endcloses="item"/>
-
- <environment name="enumerate" outputname="enumeration"
- endcloses="item"/>
-
- <environment name="fulllineitems"
- endcloses="item"/>
-
- <environment name="itemize"
- endcloses="item"/>
-
- <environment name="definitions" outputname="definitionlist"
- encloses="term"/>
- <macro name="term" closes="definition">
- <!-- not really optional, but uses the [] syntax -->
- <child name="term" optional="yes"/>
- <child name="definition" implied="yes"/>
- </macro>
-
- <environment name="alltt" outputname="verbatim"/>
- <environment name="comment" verbatim="yes"/>
- <environment name="verbatim" verbatim="yes"/>
- <environment name="verbatim*" verbatim="yes">
- <!-- not used anywhere, but it's a standard LaTeXism -->
- <attribute name="spaces">visible</attribute>
- </environment>
- <macro name="verbatiminput" ouptutname="xi:include">
- <attribute name="parse">text</attribute>
- <attribute name="href"/>
- </macro>
-
- <!-- Table markup. -->
- <macro name="hline"/>
- <environment name="tableii" outputname="table">
- <attribute name="cols">2</attribute>
- <attribute name="colspec"/>
- <attribute name="style"/>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- </environment>
- <environment name="longtableii" outputname="table">
- <attribute name="cols">2</attribute>
- <attribute name="colspec"/>
- <attribute name="style"/>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- </environment>
- <macro name="lineii" outputname="row">
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- </macro>
-
- <environment name="tableiii" outputname="table">
- <attribute name="cols">3</attribute>
- <attribute name="colspec"/>
- <attribute name="style"/>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- </environment>
- <environment name="longtableiii" outputname="table">
- <attribute name="cols">3</attribute>
- <attribute name="colspec"/>
- <attribute name="style"/>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- </environment>
- <macro name="lineiii" outputname="row">
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- </macro>
-
- <environment name="tableiv" outputname="table">
- <attribute name="cols">4</attribute>
- <attribute name="colspec"/>
- <attribute name="style"/>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- </environment>
- <environment name="longtableiv" outputname="table">
- <attribute name="cols">4</attribute>
- <attribute name="colspec"/>
- <attribute name="style"/>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- </environment>
- <macro name="lineiv" outputname="row">
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- </macro>
-
- <environment name="tablev" outputname="table">
- <attribute name="cols">4</attribute>
- <attribute name="colspec"/>
- <attribute name="style"/>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- </environment>
- <environment name="longtablev" outputname="table">
- <attribute name="cols">4</attribute>
- <attribute name="colspec"/>
- <attribute name="style"/>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- </environment>
- <macro name="linev" outputname="row">
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- <text>
- </text>
- <child name="entry"/>
- </macro>
-
- <!-- These are handled at a later translation stage, at least for now. -->
- <macro name="Cpp" outputname="">
- <text>C++</text>
- </macro>
- <macro name="geq" outputname="">
- <entityref name="geq"/>
- </macro>
- <macro name="infinity" outputname="">
- <entityref name="infin"/>
- </macro>
- <macro name="LaTeX" outputname="">
- <text>LaTeX</text>
- </macro>
- <macro name="ldots" outputname="">
- <text>...</text>
- </macro>
- <macro name="leq" outputname="">
- <entityref name="leq"/>
- </macro>
- <macro name="plusminus" outputname="">
- <entityref name="plusmn"/>
- </macro>
- <macro name="TeX" outputname="">
- <text>TeX</text>
- </macro>
- <macro name="version"/>
-
- <!-- Distutils things. -->
- <macro name="command">
- <content/>
- </macro>
- <macro name="option">
- <content/>
- </macro>
- <macro name="filevar" outputname="var">
- <content/>
- </macro>
- <macro name="XXX" outputname="editorial-comment">
- <content/>
- </macro>
-
- <!-- Grammar production lists -->
- <environment name="productionlist">
- <attribute name="grammar" optional="yes"/>
- </environment>
- <macro name="production">
- <attribute name="token"/>
- <content/>
- </macro>
- <macro name="productioncont">
- <content/>
- </macro>
- <macro name="token" outputname="grammartoken">
- <content/>
- </macro>
- <macro name="grammartoken">
- <content/>
- </macro>
-
- <!-- Misc. -->
- <macro name="emph">
- <content/>
- </macro>
- <macro name="strong">
- <content/>
- </macro>
- <macro name="textrm">
- <content/>
- </macro>
- <macro name="texttt">
- <content/>
- </macro>
- <macro name="code">
- <content/>
- </macro>
- <macro name="exception">
- <content/>
- </macro>
- <macro name="keyword">
- <content/>
- </macro>
- <macro name="samp">
- <content/>
- </macro>
- <macro name="class">
- <content/>
- </macro>
- <macro name="cdata">
- <content/>
- </macro>
- <macro name="cfunction">
- <content/>
- </macro>
- <macro name="csimplemacro">
- <content/>
- </macro>
- <macro name="ctype">
- <content/>
- </macro>
- <macro name="pytype">
- <content/>
- </macro>
- <macro name="character">
- <content/>
- </macro>
- <macro name="constant">
- <content/>
- </macro>
- <macro name="envvar" outputname="envar">
- <content/>
- </macro>
- <macro name="file" outputname="filename">
- <content/>
- </macro>
- <macro name="filenq" outputname="filename">
- <attribute name="quote">no</attribute>
- <content/>
- </macro>
- <macro name="function">
- <content/>
- </macro>
- <macro name="kbd" outputname="keysym">
- <content/>
- </macro>
- <macro name="mailheader">
- <content/>
- </macro>
- <macro name="makevar">
- <content/>
- </macro>
- <macro name="method">
- <content/>
- </macro>
- <macro name="member">
- <content/>
- </macro>
- <macro name="mimetype">
- <content/>
- </macro>
- <macro name="newsgroup">
- <content/>
- </macro>
- <macro name="program" outputname="command">
- <content/>
- </macro>
- <macro name="programopt" outputname="option">
- <content/>
- </macro>
- <macro name="longprogramopt" outputname="longoption">
- <content/>
- </macro>
- <macro name="regexp">
- <content/>
- </macro>
- <macro name="var">
- <content/>
- </macro>
- <macro name="email">
- <content/>
- </macro>
- <macro name="ulink">
- <!-- order of the parameters makes this difficult;
- we'll need to fix it up to <ulink href="...">...</ulink>
- in docfixer.py.
- -->
- <child name="text"/>
- <child name="href"/>
- </macro>
- <macro name="url">
- <content/>
- </macro>
- <macro name="footnote">
- <content/>
- </macro>
- <macro name="dfn" outputname="definedterm">
- <content/>
- </macro>
-
- <macro name="mbox">
- <content/>
- </macro>
-
- <!-- minimal math stuff to get by -->
- <macro name="pi"/>
- <macro name="sqrt">
- <content/>
- </macro>
- <macro name="frac" outputname="fraction">
- <child name="numerator"/>
- <child name="denominator"/>
- </macro>
- <macro name="sum">
- <content/>
- </macro>
-
- <macro name="leftline" outputname="">
- <content/>
- </macro>
-
- <!-- Conversions to text; perhaps could be different? There's -->
- <!-- no way for a style sheet to work with these this way. -->
- <macro name="ABC" outputname="">
- <text>ABC</text>
- </macro>
- <macro name="ASCII" outputname="">
- <text>ASCII</text>
- </macro>
- <macro name="C" outputname="">
- <text>C</text>
- </macro>
- <macro name="EOF" outputname="">
- <text>EOF</text>
- </macro>
- <macro name="e" outputname="">
- <text>\</text>
- </macro>
- <macro name="NULL" outputname="constant">
- <text>NULL</text>
- </macro>
- <macro name="POSIX" outputname="">
- <text>POSIX</text>
- </macro>
- <macro name="UNIX" outputname="">
- <text>Unix</text>
- </macro>
- <macro name="textasciicircum" outputname="">
- <text>^</text>
- </macro>
- <macro name="textasciitilde" outputname="">
- <text>~</text>
- </macro>
- <macro name="textbackslash" outputname="">
- <text>\</text>
- </macro>
- <macro name="textbar" outputname="">
- <text>|</text>
- </macro>
- <macro name="textgreater" outputname="">
- <text>></text>
- </macro>
- <macro name="textless" outputname="">
- <text><</text>
- </macro>
-
- <!-- These will end up disappearing as well! -->
- <macro name="catcode" outputname=""/>
- <macro name="fi" outputname=""/>
- <macro name="ifhtml" outputname=""/>
- <macro name="indexname" outputname=""/>
- <macro name="labelwidth" outputname=""/>
- <macro name="large" outputname=""/>
- <macro name="leftmargin" outputname=""/>
- <macro name="makeindex" outputname=""/>
- <macro name="makemodindex" outputname=""/>
- <macro name="maketitle" outputname=""/>
- <macro name="noindent" outputname=""/>
- <macro name="protect" outputname=""/>
- <macro name="textwidth"/>
- <macro name="renewcommand">
- <attribute name="macro"/>
- <attribute name="nargs" optional="yes"/>
- <content/>
- </macro>
- <macro name="tableofcontents" outputname=""/>
- <macro name="vspace">
- <attribute name="size"/>
- </macro>
-</conversion>
diff --git a/Doc/tools/sgmlconv/docfixer.py b/Doc/tools/sgmlconv/docfixer.py
deleted file mode 100755
index 8459fa2..0000000
--- a/Doc/tools/sgmlconv/docfixer.py
+++ /dev/null
@@ -1,1072 +0,0 @@
-#! /usr/bin/env python
-
-"""Perform massive transformations on a document tree created from the LaTeX
-of the Python documentation, and dump the ESIS data for the transformed tree.
-"""
-
-
-import errno
-import esistools
-import re
-import sys
-import xml.dom
-import xml.dom.minidom
-
-ELEMENT = xml.dom.Node.ELEMENT_NODE
-ENTITY_REFERENCE = xml.dom.Node.ENTITY_REFERENCE_NODE
-TEXT = xml.dom.Node.TEXT_NODE
-
-
-class ConversionError(Exception):
- pass
-
-
-ewrite = sys.stderr.write
-try:
- # We can only do this trick on Unix (if tput is on $PATH)!
- if sys.platform != "posix" or not sys.stderr.isatty():
- raise ImportError
- import commands
-except ImportError:
- bwrite = ewrite
-else:
- def bwrite(s, BOLDON=commands.getoutput("tput bold"),
- BOLDOFF=commands.getoutput("tput sgr0")):
- ewrite("%s%s%s" % (BOLDON, s, BOLDOFF))
-
-
-PARA_ELEMENT = "para"
-
-DEBUG_PARA_FIXER = 0
-
-if DEBUG_PARA_FIXER:
- def para_msg(s):
- ewrite("*** %s\n" % s)
-else:
- def para_msg(s):
- pass
-
-
-def get_first_element(doc, gi):
- for n in doc.childNodes:
- if n.nodeName == gi:
- return n
-
-def extract_first_element(doc, gi):
- node = get_first_element(doc, gi)
- if node is not None:
- doc.removeChild(node)
- return node
-
-
-def get_documentElement(node):
- result = None
- for child in node.childNodes:
- if child.nodeType == ELEMENT:
- result = child
- return result
-
-
-def set_tagName(elem, gi):
- elem.nodeName = elem.tagName = gi
-
-
-def find_all_elements(doc, gi):
- nodes = []
- if doc.nodeName == gi:
- nodes.append(doc)
- for child in doc.childNodes:
- if child.nodeType == ELEMENT:
- if child.tagName == gi:
- nodes.append(child)
- for node in child.getElementsByTagName(gi):
- nodes.append(node)
- return nodes
-
-def find_all_child_elements(doc, gi):
- nodes = []
- for child in doc.childNodes:
- if child.nodeName == gi:
- nodes.append(child)
- return nodes
-
-
-def find_all_elements_from_set(doc, gi_set):
- return __find_all_elements_from_set(doc, gi_set, [])
-
-def __find_all_elements_from_set(doc, gi_set, nodes):
- if doc.nodeName in gi_set:
- nodes.append(doc)
- for child in doc.childNodes:
- if child.nodeType == ELEMENT:
- __find_all_elements_from_set(child, gi_set, nodes)
- return nodes
-
-
-def simplify(doc, fragment):
- # Try to rationalize the document a bit, since these things are simply
- # not valid SGML/XML documents as they stand, and need a little work.
- documentclass = "document"
- inputs = []
- node = extract_first_element(fragment, "documentclass")
- if node is not None:
- documentclass = node.getAttribute("classname")
- node = extract_first_element(fragment, "title")
- if node is not None:
- inputs.append(node)
- # update the name of the root element
- node = get_first_element(fragment, "document")
- if node is not None:
- set_tagName(node, documentclass)
- # Move everything that comes before this node into this node;
- # this will be the document element.
- nodelist = fragment.childNodes
- point = node.firstChild
- while not nodelist[0].isSameNode(node):
- node.insertBefore(nodelist[0], point)
- while 1:
- node = extract_first_element(fragment, "input")
- if node is None:
- break
- inputs.append(node)
- if inputs:
- docelem = get_documentElement(fragment)
- inputs.reverse()
- for node in inputs:
- text = doc.createTextNode("\n")
- docelem.insertBefore(text, docelem.firstChild)
- docelem.insertBefore(node, text)
- docelem.insertBefore(doc.createTextNode("\n"), docelem.firstChild)
- while fragment.firstChild and fragment.firstChild.nodeType == TEXT:
- fragment.removeChild(fragment.firstChild)
-
-
-def cleanup_root_text(doc):
- discards = []
- skip = 0
- for n in doc.childNodes:
- prevskip = skip
- skip = 0
- if n.nodeType == TEXT and not prevskip:
- discards.append(n)
- elif n.nodeName == "COMMENT":
- skip = 1
- for node in discards:
- doc.removeChild(node)
-
-
-DESCRIPTOR_ELEMENTS = (
- "cfuncdesc", "cvardesc", "ctypedesc",
- "classdesc", "memberdesc", "memberdescni", "methoddesc", "methoddescni",
- "excdesc", "funcdesc", "funcdescni", "opcodedesc",
- "datadesc", "datadescni",
- )
-
-def fixup_descriptors(doc, fragment):
- sections = find_all_elements(fragment, "section")
- for section in sections:
- find_and_fix_descriptors(doc, section)
-
-
-def find_and_fix_descriptors(doc, container):
- children = container.childNodes
- for child in children:
- if child.nodeType == ELEMENT:
- tagName = child.tagName
- if tagName in DESCRIPTOR_ELEMENTS:
- rewrite_descriptor(doc, child)
- elif tagName == "subsection":
- find_and_fix_descriptors(doc, child)
-
-
-def rewrite_descriptor(doc, descriptor):
- #
- # Do these things:
- # 1. Add an "index='no'" attribute to the element if the tagName
- # ends in 'ni', removing the 'ni' from the name.
- # 2. Create a <signature> from the name attribute
- # 2a.Create an <args> if it appears to be available.
- # 3. Create additional <signature>s from <*line{,ni}> elements,
- # if found.
- # 4. If a <versionadded> is found, move it to an attribute on the
- # descriptor.
- # 5. Move remaining child nodes to a <description> element.
- # 6. Put it back together.
- #
- # 1.
- descname = descriptor.tagName
- index = descriptor.getAttribute("name") != "no"
- desctype = descname[:-4] # remove 'desc'
- linename = desctype + "line"
- if not index:
- linename = linename + "ni"
- # 2.
- signature = doc.createElement("signature")
- name = doc.createElement("name")
- signature.appendChild(doc.createTextNode("\n "))
- signature.appendChild(name)
- name.appendChild(doc.createTextNode(descriptor.getAttribute("name")))
- descriptor.removeAttribute("name")
- # 2a.
- if descriptor.hasAttribute("var"):
- if descname != "opcodedesc":
- raise RuntimeError("got 'var' attribute on descriptor other than opcodedesc")
- variable = descriptor.getAttribute("var")
- if variable:
- args = doc.createElement("args")
- args.appendChild(doc.createTextNode(variable))
- signature.appendChild(doc.createTextNode("\n "))
- signature.appendChild(args)
- descriptor.removeAttribute("var")
- newchildren = [signature]
- children = descriptor.childNodes
- pos = skip_leading_nodes(children)
- if pos < len(children):
- child = children[pos]
- if child.nodeName == "args":
- # move <args> to <signature>, or remove if empty:
- child.parentNode.removeChild(child)
- if len(child.childNodes):
- signature.appendChild(doc.createTextNode("\n "))
- signature.appendChild(child)
- signature.appendChild(doc.createTextNode("\n "))
- # 3, 4.
- pos = skip_leading_nodes(children, pos)
- while pos < len(children) \
- and children[pos].nodeName in (linename, "versionadded"):
- if children[pos].tagName == linename:
- # this is really a supplemental signature, create <signature>
- oldchild = children[pos].cloneNode(1)
- try:
- sig = methodline_to_signature(doc, children[pos])
- except KeyError:
- print(oldchild.toxml())
- raise
- newchildren.append(sig)
- else:
- # <versionadded added=...>
- descriptor.setAttribute(
- "added", children[pos].getAttribute("version"))
- pos = skip_leading_nodes(children, pos + 1)
- # 5.
- description = doc.createElement("description")
- description.appendChild(doc.createTextNode("\n"))
- newchildren.append(description)
- move_children(descriptor, description, pos)
- last = description.childNodes[-1]
- if last.nodeType == TEXT:
- last.data = last.data.rstrip() + "\n "
- # 6.
- # should have nothing but whitespace and signature lines in <descriptor>;
- # discard them
- while descriptor.childNodes:
- descriptor.removeChild(descriptor.childNodes[0])
- for node in newchildren:
- descriptor.appendChild(doc.createTextNode("\n "))
- descriptor.appendChild(node)
- descriptor.appendChild(doc.createTextNode("\n"))
-
-
-def methodline_to_signature(doc, methodline):
- signature = doc.createElement("signature")
- signature.appendChild(doc.createTextNode("\n "))
- name = doc.createElement("name")
- name.appendChild(doc.createTextNode(methodline.getAttribute("name")))
- methodline.removeAttribute("name")
- signature.appendChild(name)
- if len(methodline.childNodes):
- args = doc.createElement("args")
- signature.appendChild(doc.createTextNode("\n "))
- signature.appendChild(args)
- move_children(methodline, args)
- signature.appendChild(doc.createTextNode("\n "))
- return signature
-
-
-def move_children(origin, dest, start=0):
- children = origin.childNodes
- while start < len(children):
- node = children[start]
- origin.removeChild(node)
- dest.appendChild(node)
-
-
-def handle_appendix(doc, fragment):
- # must be called after simplfy() if document is multi-rooted to begin with
- docelem = get_documentElement(fragment)
- toplevel = docelem.tagName == "manual" and "chapter" or "section"
- appendices = 0
- nodes = []
- for node in docelem.childNodes:
- if appendices:
- nodes.append(node)
- elif node.nodeType == ELEMENT:
- appnodes = node.getElementsByTagName("appendix")
- if appnodes:
- appendices = 1
- parent = appnodes[0].parentNode
- parent.removeChild(appnodes[0])
- parent.normalize()
- if nodes:
- map(docelem.removeChild, nodes)
- docelem.appendChild(doc.createTextNode("\n\n\n"))
- back = doc.createElement("back-matter")
- docelem.appendChild(back)
- back.appendChild(doc.createTextNode("\n"))
- while nodes and nodes[0].nodeType == TEXT \
- and not nodes[0].data.strip():
- del nodes[0]
- map(back.appendChild, nodes)
- docelem.appendChild(doc.createTextNode("\n"))
-
-
-def handle_labels(doc, fragment):
- for label in find_all_elements(fragment, "label"):
- id = label.getAttribute("id")
- if not id:
- continue
- parent = label.parentNode
- parentTagName = parent.tagName
- if parentTagName == "title":
- parent.parentNode.setAttribute("id", id)
- else:
- parent.setAttribute("id", id)
- # now, remove <label id="..."/> from parent:
- parent.removeChild(label)
- if parentTagName == "title":
- parent.normalize()
- children = parent.childNodes
- if children[-1].nodeType == TEXT:
- children[-1].data = children[-1].data.rstrip()
-
-
-def fixup_trailing_whitespace(doc, fragment, wsmap):
- queue = [fragment]
- fixups = []
- while queue:
- node = queue[0]
- del queue[0]
- if node.nodeName in wsmap:
- fixups.append(node)
- for child in node.childNodes:
- if child.nodeType == ELEMENT:
- queue.append(child)
-
- # reverse the list to process from the inside out
- fixups.reverse()
- for node in fixups:
- node.parentNode.normalize()
- lastchild = node.lastChild
- before, after = wsmap[node.tagName]
- if lastchild.nodeType == TEXT:
- data = lastchild.data.rstrip() + before
- lastchild.data = data
- norm = 0
- if wsmap[node.tagName]:
- nextnode = node.nextSibling
- if nextnode and nextnode.nodeType == TEXT:
- nextnode.data = after + nextnode.data.lstrip()
- else:
- wsnode = doc.createTextNode(after)
- node.parentNode.insertBefore(wsnode, nextnode)
- # hack to get the title in place:
- if node.tagName == "title" \
- and node.parentNode.firstChild.nodeType == ELEMENT:
- node.parentNode.insertBefore(doc.createTextNode("\n "),
- node.parentNode.firstChild)
- node.parentNode.normalize()
-
-
-def normalize(doc):
- for node in doc.childNodes:
- if node.nodeType == ELEMENT:
- node.normalize()
-
-
-def cleanup_trailing_parens(doc, element_names):
- d = {}
- for gi in element_names:
- d[gi] = gi
- rewrite_element = d.has_key
- queue = [node for node in doc.childNodes if node.nodeType == ELEMENT]
- while queue:
- node = queue[0]
- del queue[0]
- if rewrite_element(node.tagName):
- lastchild = node.lastChild
- if lastchild and lastchild.nodeType == TEXT:
- data = lastchild.data
- if data.endswith("()"):
- lastchild.data = data[:-2]
- else:
- for child in node.childNodes:
- if child.nodeType == ELEMENT:
- queue.append(child)
-
-
-def contents_match(left, right):
- left_children = left.childNodes
- right_children = right.childNodes
- if len(left_children) != len(right_children):
- return 0
- for l, r in map(None, left_children, right_children):
- nodeType = l.nodeType
- if nodeType != r.nodeType:
- return 0
- if nodeType == ELEMENT:
- if l.tagName != r.tagName:
- return 0
- # should check attributes, but that's not a problem here
- if not contents_match(l, r):
- return 0
- elif nodeType == TEXT:
- if l.data != r.data:
- return 0
- else:
- # not quite right, but good enough
- return 0
- return 1
-
-
-def create_module_info(doc, section):
- # Heavy.
- node = extract_first_element(section, "modulesynopsis")
- if node is None:
- return
- set_tagName(node, "synopsis")
- lastchild = node.childNodes[-1]
- if lastchild.nodeType == TEXT \
- and lastchild.data[-1:] == ".":
- lastchild.data = lastchild.data[:-1]
- modauthor = extract_first_element(section, "moduleauthor")
- if modauthor:
- set_tagName(modauthor, "author")
- modauthor.appendChild(doc.createTextNode(
- modauthor.getAttribute("name")))
- modauthor.removeAttribute("name")
- platform = extract_first_element(section, "platform")
- if section.tagName == "section":
- modinfo_pos = 2
- modinfo = doc.createElement("moduleinfo")
- moddecl = extract_first_element(section, "declaremodule")
- name = None
- if moddecl:
- modinfo.appendChild(doc.createTextNode("\n "))
- name = moddecl.attributes["name"].value
- namenode = doc.createElement("name")
- namenode.appendChild(doc.createTextNode(name))
- modinfo.appendChild(namenode)
- type = moddecl.attributes.get("type")
- if type:
- type = type.value
- modinfo.appendChild(doc.createTextNode("\n "))
- typenode = doc.createElement("type")
- typenode.appendChild(doc.createTextNode(type))
- modinfo.appendChild(typenode)
- versionadded = extract_first_element(section, "versionadded")
- if versionadded:
- modinfo.setAttribute("added", versionadded.getAttribute("version"))
- title = get_first_element(section, "title")
- if title:
- children = title.childNodes
- if len(children) >= 2 \
- and children[0].nodeName == "module" \
- and children[0].childNodes[0].data == name:
- # this is it; morph the <title> into <short-synopsis>
- first_data = children[1]
- if first_data.data[:4] == " ---":
- first_data.data = first_data.data[4:].lstrip()
- set_tagName(title, "short-synopsis")
- if children[-1].nodeType == TEXT \
- and children[-1].data[-1:] == ".":
- children[-1].data = children[-1].data[:-1]
- section.removeChild(title)
- section.removeChild(section.childNodes[0])
- title.removeChild(children[0])
- modinfo_pos = 0
- else:
- ewrite("module name in title doesn't match"
- " <declaremodule/>; no <short-synopsis/>\n")
- else:
- ewrite("Unexpected condition: <section/> without <title/>\n")
- modinfo.appendChild(doc.createTextNode("\n "))
- modinfo.appendChild(node)
- if title and not contents_match(title, node):
- # The short synopsis is actually different,
- # and needs to be stored:
- modinfo.appendChild(doc.createTextNode("\n "))
- modinfo.appendChild(title)
- if modauthor:
- modinfo.appendChild(doc.createTextNode("\n "))
- modinfo.appendChild(modauthor)
- if platform:
- modinfo.appendChild(doc.createTextNode("\n "))
- modinfo.appendChild(platform)
- modinfo.appendChild(doc.createTextNode("\n "))
- section.insertBefore(modinfo, section.childNodes[modinfo_pos])
- section.insertBefore(doc.createTextNode("\n "), modinfo)
- #
- # The rest of this removes extra newlines from where we cut out
- # a lot of elements. A lot of code for minimal value, but keeps
- # keeps the generated *ML from being too funny looking.
- #
- section.normalize()
- children = section.childNodes
- for i in range(len(children)):
- node = children[i]
- if node.nodeName == "moduleinfo":
- nextnode = children[i+1]
- if nextnode.nodeType == TEXT:
- data = nextnode.data
- s = data.lstrip()
- if len(s) < (len(data) - 4):
- nextnode.data = "\n\n\n" + s
-
-
-def cleanup_synopses(doc, fragment):
- for node in find_all_elements(fragment, "section"):
- create_module_info(doc, node)
-
-
-def fixup_table_structures(doc, fragment):
- for table in find_all_elements(fragment, "table"):
- fixup_table(doc, table)
-
-
-def fixup_table(doc, table):
- # create the table head
- thead = doc.createElement("thead")
- row = doc.createElement("row")
- move_elements_by_name(doc, table, row, "entry")
- thead.appendChild(doc.createTextNode("\n "))
- thead.appendChild(row)
- thead.appendChild(doc.createTextNode("\n "))
- # create the table body
- tbody = doc.createElement("tbody")
- prev_row = None
- last_was_hline = 0
- children = table.childNodes
- for child in children:
- if child.nodeType == ELEMENT:
- tagName = child.tagName
- if tagName == "hline" and prev_row is not None:
- prev_row.setAttribute("rowsep", "1")
- elif tagName == "row":
- prev_row = child
- # save the rows:
- tbody.appendChild(doc.createTextNode("\n "))
- move_elements_by_name(doc, table, tbody, "row", sep="\n ")
- # and toss the rest:
- while children:
- child = children[0]
- nodeType = child.nodeType
- if nodeType == TEXT:
- if child.data.strip():
- raise ConversionError("unexpected free data in <%s>: %r"
- % (table.tagName, child.data))
- table.removeChild(child)
- continue
- if nodeType == ELEMENT:
- if child.tagName != "hline":
- raise ConversionError(
- "unexpected <%s> in table" % child.tagName)
- table.removeChild(child)
- continue
- raise ConversionError(
- "unexpected %s node in table" % child.__class__.__name__)
- # nothing left in the <table>; add the <thead> and <tbody>
- tgroup = doc.createElement("tgroup")
- tgroup.appendChild(doc.createTextNode("\n "))
- tgroup.appendChild(thead)
- tgroup.appendChild(doc.createTextNode("\n "))
- tgroup.appendChild(tbody)
- tgroup.appendChild(doc.createTextNode("\n "))
- table.appendChild(tgroup)
- # now make the <entry>s look nice:
- for row in table.getElementsByTagName("row"):
- fixup_row(doc, row)
-
-
-def fixup_row(doc, row):
- entries = []
- map(entries.append, row.childNodes[1:])
- for entry in entries:
- row.insertBefore(doc.createTextNode("\n "), entry)
-# row.appendChild(doc.createTextNode("\n "))
-
-
-def move_elements_by_name(doc, source, dest, name, sep=None):
- nodes = []
- for child in source.childNodes:
- if child.nodeName == name:
- nodes.append(child)
- for node in nodes:
- source.removeChild(node)
- dest.appendChild(node)
- if sep:
- dest.appendChild(doc.createTextNode(sep))
-
-
-RECURSE_INTO_PARA_CONTAINERS = (
- "chapter", "abstract", "enumerate",
- "section", "subsection", "subsubsection",
- "paragraph", "subparagraph", "back-matter",
- "howto", "manual",
- "item", "itemize", "fulllineitems", "enumeration", "descriptionlist",
- "definitionlist", "definition",
- )
-
-PARA_LEVEL_ELEMENTS = (
- "moduleinfo", "title", "verbatim", "enumerate", "item",
- "interpreter-session", "back-matter", "interactive-session",
- "opcodedesc", "classdesc", "datadesc",
- "cfuncdesc", "ctypedesc", "cvardesc",
- "funcdesc", "methoddesc", "excdesc", "memberdesc", "membderdescni",
- "funcdescni", "methoddescni", "excdescni",
- "tableii", "tableiii", "tableiv", "localmoduletable",
- "sectionauthor", "seealso", "itemize",
- # include <para>, so we can just do it again to get subsequent paras:
- PARA_ELEMENT,
- )
-
-PARA_LEVEL_PRECEEDERS = (
- "setindexsubitem", "author",
- "stindex", "obindex", "COMMENT", "label", "xi:include", "title",
- "versionadded", "versionchanged", "declaremodule", "modulesynopsis",
- "moduleauthor", "indexterm", "leader",
- )
-
-
-def fixup_paras(doc, fragment):
- for child in fragment.childNodes:
- if child.nodeName in RECURSE_INTO_PARA_CONTAINERS:
- fixup_paras_helper(doc, child)
- descriptions = find_all_elements(fragment, "description")
- for description in descriptions:
- fixup_paras_helper(doc, description)
-
-
-def fixup_paras_helper(doc, container, depth=0):
- # document is already normalized
- children = container.childNodes
- start = skip_leading_nodes(children)
- while len(children) > start:
- if children[start].nodeName in RECURSE_INTO_PARA_CONTAINERS:
- # Something to recurse into:
- fixup_paras_helper(doc, children[start])
- else:
- # Paragraph material:
- build_para(doc, container, start, len(children))
- if DEBUG_PARA_FIXER and depth == 10:
- sys.exit(1)
- start = skip_leading_nodes(children, start + 1)
-
-
-def build_para(doc, parent, start, i):
- children = parent.childNodes
- after = start + 1
- have_last = 0
- BREAK_ELEMENTS = PARA_LEVEL_ELEMENTS + RECURSE_INTO_PARA_CONTAINERS
- # Collect all children until \n\n+ is found in a text node or a
- # member of BREAK_ELEMENTS is found.
- for j in range(start, i):
- after = j + 1
- child = children[j]
- nodeType = child.nodeType
- if nodeType == ELEMENT:
- if child.tagName in BREAK_ELEMENTS:
- after = j
- break
- elif nodeType == TEXT:
- pos = child.data.find("\n\n")
- if pos == 0:
- after = j
- break
- if pos >= 1:
- child.splitText(pos)
- break
- else:
- have_last = 1
- if (start + 1) > after:
- raise ConversionError(
- "build_para() could not identify content to turn into a paragraph")
- if children[after - 1].nodeType == TEXT:
- # we may need to split off trailing white space:
- child = children[after - 1]
- data = child.data
- if data.rstrip() != data:
- have_last = 0
- child.splitText(len(data.rstrip()))
- para = doc.createElement(PARA_ELEMENT)
- prev = None
- indexes = range(start, after)
- indexes.reverse()
- for j in indexes:
- node = parent.childNodes[j]
- parent.removeChild(node)
- para.insertBefore(node, prev)
- prev = node
- if have_last:
- parent.appendChild(para)
- parent.appendChild(doc.createTextNode("\n\n"))
- return len(parent.childNodes)
- else:
- nextnode = parent.childNodes[start]
- if nextnode.nodeType == TEXT:
- if nextnode.data and nextnode.data[0] != "\n":
- nextnode.data = "\n" + nextnode.data
- else:
- newnode = doc.createTextNode("\n")
- parent.insertBefore(newnode, nextnode)
- nextnode = newnode
- start = start + 1
- parent.insertBefore(para, nextnode)
- return start + 1
-
-
-def skip_leading_nodes(children, start=0):
- """Return index into children of a node at which paragraph building should
- begin or a recursive call to fixup_paras_helper() should be made (for
- subsections, etc.).
-
- When the return value >= len(children), we've built all the paras we can
- from this list of children.
- """
- i = len(children)
- while i > start:
- # skip over leading comments and whitespace:
- child = children[start]
- nodeType = child.nodeType
- if nodeType == TEXT:
- data = child.data
- shortened = data.lstrip()
- if shortened:
- if data != shortened:
- # break into two nodes: whitespace and non-whitespace
- child.splitText(len(data) - len(shortened))
- return start + 1
- return start
- # all whitespace, just skip
- elif nodeType == ELEMENT:
- tagName = child.tagName
- if tagName in RECURSE_INTO_PARA_CONTAINERS:
- return start
- if tagName not in PARA_LEVEL_ELEMENTS + PARA_LEVEL_PRECEEDERS:
- return start
- start = start + 1
- return start
-
-
-def fixup_rfc_references(doc, fragment):
- for rfcnode in find_all_elements_from_set(fragment, ("pep", "rfc")):
- rfcnode.appendChild(doc.createTextNode(
- rfcnode.tagName.upper() + " " + rfcnode.getAttribute("num")))
-
-
-def fixup_signatures(doc, fragment):
- for child in fragment.childNodes:
- if child.nodeType == ELEMENT:
- args = child.getElementsByTagName("args")
- for arg in args:
- rewrite_args(doc, arg)
- args = child.getElementsByTagName("constructor-args")
- for arg in args:
- rewrite_args(doc, arg)
-
-def rewrite_args(doc, arglist):
- fixup_args(doc, arglist)
- arglist.normalize()
- if arglist.childNodes.length == 1 and arglist.firstChild.nodeType == TEXT:
- node = arglist.firstChild
- node.data = ' '.join(node.data.split())
-
-def fixup_args(doc, arglist):
- for child in arglist.childNodes:
- if child.nodeName == "optional":
- # found it; fix and return
- arglist.insertBefore(doc.createTextNode("["), child)
- optkids = child.childNodes
- while optkids:
- arglist.insertBefore(child.firstChild, child)
- arglist.insertBefore(doc.createTextNode("]"), child)
- arglist.removeChild(child)
- return fixup_args(doc, arglist)
-
-
-def fixup_sectionauthors(doc, fragment):
- for sectauth in find_all_elements(fragment, "sectionauthor"):
- section = sectauth.parentNode
- section.removeChild(sectauth)
- set_tagName(sectauth, "author")
- sectauth.appendChild(doc.createTextNode(
- sectauth.getAttribute("name")))
- sectauth.removeAttribute("name")
- after = section.childNodes[2]
- title = section.childNodes[1]
- if title.nodeName != "title":
- after = section.childNodes[0]
- section.insertBefore(doc.createTextNode("\n "), after)
- section.insertBefore(sectauth, after)
-
-
-def fixup_verbatims(doc):
- for verbatim in find_all_elements(doc, "verbatim"):
- child = verbatim.childNodes[0]
- if child.nodeType == TEXT \
- and child.data.lstrip().startswith(">>>"):
- set_tagName(verbatim, "interactive-session")
-
-
-def add_node_ids(fragment, counter=0):
- fragment.node_id = counter
- for node in fragment.childNodes:
- counter = counter + 1
- if node.nodeType == ELEMENT:
- counter = add_node_ids(node, counter)
- else:
- node.node_id = counter
- return counter + 1
-
-
-def fixup_ulink(doc, fragment):
- for ulink in find_all_elements(fragment, "ulink"):
- children = ulink.childNodes
- assert len(children) == 2
- text = children[0]
- href = children[1]
- href.normalize()
- assert len(href.childNodes) == 1
- assert href.childNodes[0].nodeType == TEXT
- url = href.childNodes[0].data
- ulink.setAttribute("href", url)
- ulink.removeChild(href)
- content = text.childNodes
- while len(content):
- ulink.appendChild(content[0])
- ulink.removeChild(text)
-
-
-REFMODINDEX_ELEMENTS = ('refmodindex', 'refbimodindex',
- 'refexmodindex', 'refstmodindex')
-
-def fixup_refmodindexes(fragment):
- # Locate <ref*modindex>...</> co-located with <module>...</>, and
- # remove the <ref*modindex>, replacing it with index=index on the
- # <module> element.
- nodes = find_all_elements_from_set(fragment, REFMODINDEX_ELEMENTS)
- d = {}
- for node in nodes:
- parent = node.parentNode
- d[parent.node_id] = parent
- del nodes
- map(fixup_refmodindexes_chunk, d.values())
-
-
-def fixup_refmodindexes_chunk(container):
- # node is probably a <para>; let's see how often it isn't:
- if container.tagName != PARA_ELEMENT:
- bwrite("--- fixup_refmodindexes_chunk(%s)\n" % container)
- module_entries = find_all_elements(container, "module")
- if not module_entries:
- return
- index_entries = find_all_elements_from_set(container, REFMODINDEX_ELEMENTS)
- removes = []
- for entry in index_entries:
- children = entry.childNodes
- if len(children) != 0:
- bwrite("--- unexpected number of children for %s node:\n"
- % entry.tagName)
- ewrite(entry.toxml() + "\n")
- continue
- found = 0
- module_name = entry.getAttribute("module")
- for node in module_entries:
- if len(node.childNodes) != 1:
- continue
- this_name = node.childNodes[0].data
- if this_name == module_name:
- found = 1
- node.setAttribute("index", "yes")
- if found:
- removes.append(entry)
- for node in removes:
- container.removeChild(node)
-
-
-def fixup_bifuncindexes(fragment):
- nodes = find_all_elements(fragment, 'bifuncindex')
- d = {}
- # make sure that each parent is only processed once:
- for node in nodes:
- parent = node.parentNode
- d[parent.node_id] = parent
- del nodes
- map(fixup_bifuncindexes_chunk, d.values())
-
-
-def fixup_bifuncindexes_chunk(container):
- removes = []
- entries = find_all_child_elements(container, "bifuncindex")
- function_entries = find_all_child_elements(container, "function")
- for entry in entries:
- function_name = entry.getAttribute("name")
- found = 0
- for func_entry in function_entries:
- t2 = func_entry.childNodes[0].data
- if t2[-2:] != "()":
- continue
- t2 = t2[:-2]
- if t2 == function_name:
- func_entry.setAttribute("index", "yes")
- func_entry.setAttribute("module", "__builtin__")
- if not found:
- found = 1
- removes.append(entry)
- for entry in removes:
- container.removeChild(entry)
-
-
-def join_adjacent_elements(container, gi):
- queue = [container]
- while queue:
- parent = queue.pop()
- i = 0
- children = parent.childNodes
- nchildren = len(children)
- while i < (nchildren - 1):
- child = children[i]
- if child.nodeName == gi:
- if children[i+1].nodeName == gi:
- ewrite("--- merging two <%s/> elements\n" % gi)
- child = children[i]
- nextchild = children[i+1]
- nextchildren = nextchild.childNodes
- while len(nextchildren):
- node = nextchildren[0]
- nextchild.removeChild(node)
- child.appendChild(node)
- parent.removeChild(nextchild)
- continue
- if child.nodeType == ELEMENT:
- queue.append(child)
- i = i + 1
-
-
-_token_rx = re.compile(r"[a-zA-Z][a-zA-Z0-9.-]*$")
-
-def write_esis(doc, ofp, knownempty):
- for node in doc.childNodes:
- nodeType = node.nodeType
- if nodeType == ELEMENT:
- gi = node.tagName
- if knownempty(gi):
- if node.hasChildNodes():
- raise ValueError("declared-empty node <%s> has children" % gi)
- ofp.write("e\n")
- for k, value in node.attributes.items():
- if _token_rx.match(value):
- dtype = "TOKEN"
- else:
- dtype = "CDATA"
- ofp.write("A%s %s %s\n" % (k, dtype, esistools.encode(value)))
- ofp.write("(%s\n" % gi)
- write_esis(node, ofp, knownempty)
- ofp.write(")%s\n" % gi)
- elif nodeType == TEXT:
- ofp.write("-%s\n" % esistools.encode(node.data))
- elif nodeType == ENTITY_REFERENCE:
- ofp.write("&%s\n" % node.nodeName)
- else:
- raise RuntimeError("unsupported node type: %s" % nodeType)
-
-
-def convert(ifp, ofp):
- events = esistools.parse(ifp)
- toktype, doc = events.getEvent()
- fragment = doc.createDocumentFragment()
- events.expandNode(fragment)
-
- normalize(fragment)
- simplify(doc, fragment)
- handle_labels(doc, fragment)
- handle_appendix(doc, fragment)
- fixup_trailing_whitespace(doc, fragment, {
- # element -> (before-end-tag, after-end-tag)
- "abstract": ("\n", "\n"),
- "title": ("", "\n"),
- "chapter": ("\n", "\n\n\n"),
- "section": ("\n", "\n\n\n"),
- "subsection": ("\n", "\n\n"),
- "subsubsection": ("\n", "\n\n"),
- "paragraph": ("\n", "\n\n"),
- "subparagraph": ("\n", "\n\n"),
- "description": ("\n", "\n\n"),
- "enumeration": ("\n", "\n\n"),
- "item": ("\n", "\n\n"),
- })
- cleanup_root_text(doc)
- cleanup_trailing_parens(fragment, ["function", "method", "cfunction"])
- cleanup_synopses(doc, fragment)
- fixup_descriptors(doc, fragment)
- fixup_verbatims(fragment)
- normalize(fragment)
- fixup_paras(doc, fragment)
- fixup_sectionauthors(doc, fragment)
- fixup_table_structures(doc, fragment)
- fixup_rfc_references(doc, fragment)
- fixup_signatures(doc, fragment)
- fixup_ulink(doc, fragment)
- add_node_ids(fragment)
- fixup_refmodindexes(fragment)
- fixup_bifuncindexes(fragment)
- # Take care of ugly hacks in the LaTeX markup to avoid LaTeX and
- # LaTeX2HTML screwing with GNU-style long options (the '--' problem).
- join_adjacent_elements(fragment, "option")
- # Attempt to avoid trailing blank lines:
- fragment.normalize()
- if fragment.lastChild.data[-1:] == "\n":
- fragment.lastChild.data = fragment.lastChild.data.rstrip() + "\n"
- #
- d = {}
- for gi in events.parser.get_empties():
- d[gi] = gi
- for key in ("author", "pep", "rfc"):
- if key in d:
- del d[key]
- knownempty = d.has_key
- #
- try:
- write_esis(fragment, ofp, knownempty)
- except IOError as e:
- (err, msg) = e
- # Ignore EPIPE; it just means that whoever we're writing to stopped
- # reading. The rest of the output would be ignored. All other errors
- # should still be reported,
- if err != errno.EPIPE:
- raise
-
-
-def main():
- if len(sys.argv) == 1:
- ifp = sys.stdin
- ofp = sys.stdout
- elif len(sys.argv) == 2:
- ifp = open(sys.argv[1])
- ofp = sys.stdout
- elif len(sys.argv) == 3:
- ifp = open(sys.argv[1])
- import io
- ofp = io.StringIO()
- else:
- usage()
- sys.exit(2)
- convert(ifp, ofp)
- if len(sys.argv) == 3:
- fp = open(sys.argv[2], "w")
- fp.write(ofp.getvalue())
- fp.close()
- ofp.close()
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/sgmlconv/esis2sgml.py b/Doc/tools/sgmlconv/esis2sgml.py
deleted file mode 100755
index 10ec83a..0000000
--- a/Doc/tools/sgmlconv/esis2sgml.py
+++ /dev/null
@@ -1,263 +0,0 @@
-#! /usr/bin/env python
-
-"""Convert ESIS events to SGML or XML markup.
-
-This is limited, but seems sufficient for the ESIS generated by the
-latex2esis.py script when run over the Python documentation.
-"""
-
-# This should have an explicit option to indicate whether the *INPUT* was
-# generated from an SGML or an XML application.
-
-import errno
-import os
-import re
-import string
-
-from xml.sax.saxutils import escape
-
-import esistools
-
-
-AUTOCLOSE = ()
-
-EMPTIES_FILENAME = "../sgml/empties.dat"
-LIST_EMPTIES = 0
-
-
-_elem_map = {}
-_attr_map = {}
-_token_map = {}
-
-_normalize_case = str
-
-def map_gi(sgmlgi, map):
- uncased = _normalize_case(sgmlgi)
- try:
- return map[uncased]
- except IndexError:
- map[uncased] = sgmlgi
- return sgmlgi
-
-def null_map_gi(sgmlgi, map):
- return sgmlgi
-
-
-def format_attrs(attrs, xml=0):
- attrs = sorted(attrs.items())
- parts = []
- append = parts.append
- for name, value in attrs:
- if xml:
- append('%s="%s"' % (name, escape(value)))
- else:
- # this is a little bogus, but should do for now
- if name == value and isnmtoken(value):
- append(value)
- elif istoken(value):
- if value == "no" + name:
- append(value)
- else:
- append("%s=%s" % (name, value))
- else:
- append('%s="%s"' % (name, escape(value)))
- if parts:
- parts.insert(0, '')
- return " ".join(parts)
-
-
-_nmtoken_rx = re.compile("[a-z][-._a-z0-9]*$", re.IGNORECASE)
-def isnmtoken(s):
- return _nmtoken_rx.match(s) is not None
-
-_token_rx = re.compile("[a-z0-9][-._a-z0-9]*$", re.IGNORECASE)
-def istoken(s):
- return _token_rx.match(s) is not None
-
-
-def convert(ifp, ofp, xml=0, autoclose=(), verbatims=()):
- if xml:
- autoclose = ()
- attrs = {}
- lastopened = None
- knownempties = []
- knownempty = 0
- lastempty = 0
- inverbatim = 0
- while 1:
- line = ifp.readline()
- if not line:
- break
-
- type = line[0]
- data = line[1:]
- if data and data[-1] == "\n":
- data = data[:-1]
- if type == "-":
- data = esistools.decode(data)
- data = escape(data)
- if not inverbatim:
- data = data.replace("---", "—")
- ofp.write(data)
- if "\n" in data:
- lastopened = None
- knownempty = 0
- lastempty = 0
- elif type == "(":
- if data == "COMMENT":
- ofp.write("<!--")
- continue
- data = map_gi(data, _elem_map)
- if knownempty and xml:
- ofp.write("<%s%s/>" % (data, format_attrs(attrs, xml)))
- else:
- ofp.write("<%s%s>" % (data, format_attrs(attrs, xml)))
- if knownempty and data not in knownempties:
- # accumulate knowledge!
- knownempties.append(data)
- attrs = {}
- lastopened = data
- lastempty = knownempty
- knownempty = 0
- inverbatim = data in verbatims
- elif type == ")":
- if data == "COMMENT":
- ofp.write("-->")
- continue
- data = map_gi(data, _elem_map)
- if xml:
- if not lastempty:
- ofp.write("</%s>" % data)
- elif data not in knownempties:
- if data in autoclose:
- pass
- elif lastopened == data:
- ofp.write("</>")
- else:
- ofp.write("</%s>" % data)
- lastopened = None
- lastempty = 0
- inverbatim = 0
- elif type == "A":
- name, type, value = data.split(" ", 2)
- name = map_gi(name, _attr_map)
- attrs[name] = esistools.decode(value)
- elif type == "e":
- knownempty = 1
- elif type == "&":
- ofp.write("&%s;" % data)
- knownempty = 0
- else:
- raise RuntimeError("unrecognized ESIS event type: '%s'" % type)
-
- if LIST_EMPTIES:
- dump_empty_element_names(knownempties)
-
-
-def dump_empty_element_names(knownempties):
- d = {}
- for gi in knownempties:
- d[gi] = gi
- knownempties.append("")
- if os.path.isfile(EMPTIES_FILENAME):
- fp = open(EMPTIES_FILENAME)
- while 1:
- line = fp.readline()
- if not line:
- break
- gi = line.strip()
- if gi:
- d[gi] = gi
- fp = open(EMPTIES_FILENAME, "w")
- gilist = sorted(d.keys())
- fp.write("\n".join(gilist))
- fp.write("\n")
- fp.close()
-
-
-def update_gi_map(map, names, fromsgml=1):
- for name in names.split(","):
- if fromsgml:
- uncased = name.lower()
- else:
- uncased = name
- map[uncased] = name
-
-
-def main():
- import getopt
- import sys
- #
- autoclose = AUTOCLOSE
- xml = 1
- xmldecl = 0
- elem_names = ''
- attr_names = ''
- value_names = ''
- verbatims = ('verbatim', 'interactive-session')
- opts, args = getopt.getopt(sys.argv[1:], "adesx",
- ["autoclose=", "declare", "sgml", "xml",
- "elements-map=", "attributes-map",
- "values-map="])
- for opt, arg in opts:
- if opt in ("-d", "--declare"):
- xmldecl = 1
- elif opt == "-e":
- global LIST_EMPTIES
- LIST_EMPTIES = 1
- elif opt in ("-s", "--sgml"):
- xml = 0
- elif opt in ("-x", "--xml"):
- xml = 1
- elif opt in ("-a", "--autoclose"):
- autoclose = arg.split(",")
- elif opt == "--elements-map":
- elem_names = ("%s,%s" % (elem_names, arg))[1:]
- elif opt == "--attributes-map":
- attr_names = ("%s,%s" % (attr_names, arg))[1:]
- elif opt == "--values-map":
- value_names = ("%s,%s" % (value_names, arg))[1:]
- #
- # open input streams:
- #
- if len(args) == 0:
- ifp = sys.stdin
- ofp = sys.stdout
- elif len(args) == 1:
- ifp = open(args[0])
- ofp = sys.stdout
- elif len(args) == 2:
- ifp = open(args[0])
- ofp = open(args[1], "w")
- else:
- usage()
- sys.exit(2)
- #
- # setup the name maps:
- #
- if elem_names or attr_names or value_names:
- # assume the origin was SGML; ignore case of the names from the ESIS
- # stream but set up conversion tables to get the case right on output
- global _normalize_case
- _normalize_case = string.lower
- update_gi_map(_elem_map, elem_names.split(","))
- update_gi_map(_attr_map, attr_names.split(","))
- update_gi_map(_values_map, value_names.split(","))
- else:
- global map_gi
- map_gi = null_map_gi
- #
- # run the conversion:
- #
- try:
- if xml and xmldecl:
- opf.write('<?xml version="1.0" encoding="iso8859-1"?>\n')
- convert(ifp, ofp, xml=xml, autoclose=autoclose, verbatims=verbatims)
- except IOError as e:
- (err, msg) = e
- if err != errno.EPIPE:
- raise
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/sgmlconv/esistools.py b/Doc/tools/sgmlconv/esistools.py
deleted file mode 100644
index 11f458e..0000000
--- a/Doc/tools/sgmlconv/esistools.py
+++ /dev/null
@@ -1,312 +0,0 @@
-"""Miscellaneous utility functions useful for dealing with ESIS streams."""
-
-import re
-
-import xml.dom.pulldom
-
-import xml.sax
-import xml.sax.handler
-import xml.sax.xmlreader
-
-
-_data_match = re.compile(r"[^\\][^\\]*").match
-
-def decode(s):
- r = ''
- while s:
- m = _data_match(s)
- if m:
- r = r + m.group()
- s = s[m.end():]
- elif s[1] == "\\":
- r = r + "\\"
- s = s[2:]
- elif s[1] == "n":
- r = r + "\n"
- s = s[2:]
- elif s[1] == "%":
- s = s[2:]
- n, s = s.split(";", 1)
- r = r + unichr(int(n))
- else:
- raise ValueError("can't handle %r" % s)
- return r
-
-
-_charmap = {}
-for c in range(128):
- _charmap[chr(c)] = chr(c)
- _charmap[unichr(c + 128)] = chr(c + 128)
-_charmap["\n"] = r"\n"
-_charmap["\\"] = r"\\"
-del c
-
-_null_join = ''.join
-def encode(s):
- try:
- return _null_join(map(_charmap.get, s))
- except TypeError:
- raise Exception("could not encode %r: %r" % (s, map(_charmap.get, s)))
-
-
-class ESISReader(xml.sax.xmlreader.XMLReader):
- """SAX Reader which reads from an ESIS stream.
-
- No verification of the document structure is performed by the
- reader; a general verifier could be used as the target
- ContentHandler instance.
-
- """
- _decl_handler = None
- _lexical_handler = None
-
- _public_id = None
- _system_id = None
-
- _buffer = ""
- _is_empty = 0
- _lineno = 0
- _started = 0
-
- def __init__(self, contentHandler=None, errorHandler=None):
- xml.sax.xmlreader.XMLReader.__init__(self)
- self._attrs = {}
- self._attributes = Attributes(self._attrs)
- self._locator = Locator()
- self._empties = {}
- if contentHandler:
- self.setContentHandler(contentHandler)
- if errorHandler:
- self.setErrorHandler(errorHandler)
-
- def get_empties(self):
- return list(self._empties.keys())
-
- #
- # XMLReader interface
- #
-
- def parse(self, source):
- raise RuntimeError
- self._locator._public_id = source.getPublicId()
- self._locator._system_id = source.getSystemId()
- fp = source.getByteStream()
- handler = self.getContentHandler()
- if handler:
- handler.startDocument()
- lineno = 0
- while 1:
- token, data = self._get_token(fp)
- if token is None:
- break
- lineno = lineno + 1
- self._locator._lineno = lineno
- self._handle_token(token, data)
- handler = self.getContentHandler()
- if handler:
- handler.startDocument()
-
- def feed(self, data):
- if not self._started:
- handler = self.getContentHandler()
- if handler:
- handler.startDocument()
- self._started = 1
- data = self._buffer + data
- self._buffer = None
- lines = data.split("\n")
- if lines:
- for line in lines[:-1]:
- self._lineno = self._lineno + 1
- self._locator._lineno = self._lineno
- if not line:
- e = xml.sax.SAXParseException(
- "ESIS input line contains no token type mark",
- None, self._locator)
- self.getErrorHandler().error(e)
- else:
- self._handle_token(line[0], line[1:])
- self._buffer = lines[-1]
- else:
- self._buffer = ""
-
- def close(self):
- handler = self.getContentHandler()
- if handler:
- handler.endDocument()
- self._buffer = ""
-
- def _get_token(self, fp):
- try:
- line = fp.readline()
- except IOError as e:
- e = SAXException("I/O error reading input stream", e)
- self.getErrorHandler().fatalError(e)
- return
- if not line:
- return None, None
- if line[-1] == "\n":
- line = line[:-1]
- if not line:
- e = xml.sax.SAXParseException(
- "ESIS input line contains no token type mark",
- None, self._locator)
- self.getErrorHandler().error(e)
- return
- return line[0], line[1:]
-
- def _handle_token(self, token, data):
- handler = self.getContentHandler()
- if token == '-':
- if data and handler:
- handler.characters(decode(data))
- elif token == ')':
- if handler:
- handler.endElement(decode(data))
- elif token == '(':
- if self._is_empty:
- self._empties[data] = 1
- self._is_empty = 0
- if handler:
- handler.startElement(data, self._attributes)
- self._attrs.clear()
- elif token == 'A':
- name, value = data.split(' ', 1)
- if value != "IMPLIED":
- type, value = value.split(' ', 1)
- self._attrs[name] = (decode(value), type)
- elif token == '&':
- # entity reference in SAX?
- pass
- elif token == '?':
- if handler:
- if ' ' in data:
- target, data = data.split(None, 1)
- else:
- target, data = data, ""
- handler.processingInstruction(target, decode(data))
- elif token == 'N':
- handler = self.getDTDHandler()
- if handler:
- handler.notationDecl(data, self._public_id, self._system_id)
- self._public_id = None
- self._system_id = None
- elif token == 'p':
- self._public_id = decode(data)
- elif token == 's':
- self._system_id = decode(data)
- elif token == 'e':
- self._is_empty = 1
- elif token == 'C':
- pass
- else:
- e = SAXParseException("unknown ESIS token in event stream",
- None, self._locator)
- self.getErrorHandler().error(e)
-
- def setContentHandler(self, handler):
- old = self.getContentHandler()
- if old:
- old.setDocumentLocator(None)
- if handler:
- handler.setDocumentLocator(self._locator)
- xml.sax.xmlreader.XMLReader.setContentHandler(self, handler)
-
- def getProperty(self, property):
- if property == xml.sax.handler.property_lexical_handler:
- return self._lexical_handler
-
- elif property == xml.sax.handler.property_declaration_handler:
- return self._decl_handler
-
- else:
- raise xml.sax.SAXNotRecognizedException("unknown property %r"
- % (property, ))
-
- def setProperty(self, property, value):
- if property == xml.sax.handler.property_lexical_handler:
- if self._lexical_handler:
- self._lexical_handler.setDocumentLocator(None)
- if value:
- value.setDocumentLocator(self._locator)
- self._lexical_handler = value
-
- elif property == xml.sax.handler.property_declaration_handler:
- if self._decl_handler:
- self._decl_handler.setDocumentLocator(None)
- if value:
- value.setDocumentLocator(self._locator)
- self._decl_handler = value
-
- else:
- raise xml.sax.SAXNotRecognizedException()
-
- def getFeature(self, feature):
- if feature == xml.sax.handler.feature_namespaces:
- return 1
- else:
- return xml.sax.xmlreader.XMLReader.getFeature(self, feature)
-
- def setFeature(self, feature, enabled):
- if feature == xml.sax.handler.feature_namespaces:
- pass
- else:
- xml.sax.xmlreader.XMLReader.setFeature(self, feature, enabled)
-
-
-class Attributes(xml.sax.xmlreader.AttributesImpl):
- # self._attrs has the form {name: (value, type)}
-
- def getType(self, name):
- return self._attrs[name][1]
-
- def getValue(self, name):
- return self._attrs[name][0]
-
- def getValueByQName(self, name):
- return self._attrs[name][0]
-
- def __getitem__(self, name):
- return self._attrs[name][0]
-
- def get(self, name, default=None):
- if name in self._attrs:
- return self._attrs[name][0]
- return default
-
- def items(self):
- L = []
- for name, (value, type) in self._attrs.items():
- L.append((name, value))
- return L
-
- def values(self):
- L = []
- for value, type in list(self._attrs.values()):
- L.append(value)
- return L
-
-
-class Locator(xml.sax.xmlreader.Locator):
- _lineno = -1
- _public_id = None
- _system_id = None
-
- def getLineNumber(self):
- return self._lineno
-
- def getPublicId(self):
- return self._public_id
-
- def getSystemId(self):
- return self._system_id
-
-
-def parse(stream_or_string, parser=None):
- if type(stream_or_string) in [type(""), type(u"")]:
- stream = open(stream_or_string)
- else:
- stream = stream_or_string
- if not parser:
- parser = ESISReader()
- return xml.dom.pulldom.DOMEventStream(stream, parser, (2 ** 14) - 20)
diff --git a/Doc/tools/sgmlconv/latex2esis.py b/Doc/tools/sgmlconv/latex2esis.py
deleted file mode 100755
index 3ee86e3..0000000
--- a/Doc/tools/sgmlconv/latex2esis.py
+++ /dev/null
@@ -1,566 +0,0 @@
-#! /usr/bin/env python
-
-"""Generate ESIS events based on a LaTeX source document and
-configuration data.
-
-The conversion is not strong enough to work with arbitrary LaTeX
-documents; it has only been designed to work with the highly stylized
-markup used in the standard Python documentation. A lot of
-information about specific markup is encoded in the control table
-passed to the convert() function; changing this table can allow this
-tool to support additional LaTeX markups.
-
-The format of the table is largely undocumented; see the commented
-headers where the table is specified in main(). There is no provision
-to load an alternate table from an external file.
-"""
-
-import errno
-import getopt
-import os
-import re
-import sys
-import xml.sax
-import xml.sax.saxutils
-
-from esistools import encode
-
-
-DEBUG = 0
-
-
-class LaTeXFormatError(Exception):
- pass
-
-
-class LaTeXStackError(LaTeXFormatError):
- def __init__(self, found, stack):
- msg = "environment close for %s doesn't match;\n stack = %s" \
- % (found, stack)
- self.found = found
- self.stack = stack[:]
- LaTeXFormatError.__init__(self, msg)
-
-
-_begin_env_rx = re.compile(r"[\\]begin{([^}]*)}")
-_end_env_rx = re.compile(r"[\\]end{([^}]*)}")
-_begin_macro_rx = re.compile(r"[\\]([a-zA-Z]+[*]?) ?({|\s*\n?)")
-_comment_rx = re.compile("%+ ?(.*)\n[ \t]*")
-_text_rx = re.compile(r"[^]~%\\{}]+")
-_optional_rx = re.compile(r"\s*[[]([^]]*)[]]", re.MULTILINE)
-# _parameter_rx is this complicated to allow {...} inside a parameter;
-# this is useful to match tabular layout specifications like {c|p{24pt}}
-_parameter_rx = re.compile("[ \n]*{(([^{}}]|{[^}]*})*)}")
-_token_rx = re.compile(r"[a-zA-Z][a-zA-Z0-9.-]*$")
-_start_group_rx = re.compile("[ \n]*{")
-_start_optional_rx = re.compile("[ \n]*[[]")
-
-
-ESCAPED_CHARS = "$%#^ {}&~"
-
-
-def dbgmsg(msg):
- if DEBUG:
- sys.stderr.write(msg + "\n")
-
-def pushing(name, point, depth):
- dbgmsg("pushing <%s> at %s" % (name, point))
-
-def popping(name, point, depth):
- dbgmsg("popping </%s> at %s" % (name, point))
-
-
-class _Stack(list):
- def append(self, entry):
- if not isinstance(entry, str):
- raise LaTeXFormatError("cannot push non-string on stack: %r"
- % (entry, ))
- #dbgmsg("%s<%s>" % (" "*len(self.data), entry))
- list.append(self, entry)
-
- def pop(self, index=-1):
- entry = self[index]
- del self[index]
- #dbgmsg("%s</%s>" % (" " * len(self), entry))
-
- def __delitem__(self, index):
- entry = self[index]
- list.__delitem__(self, index)
- #dbgmsg("%s</%s>" % (" " * len(self), entry))
-
-
-def new_stack():
- if DEBUG:
- return _Stack()
- else:
- return []
-
-
-class Conversion:
- def __init__(self, ifp, ofp, table):
- self.write = ofp.write
- self.ofp = ofp
- self.table = table
- L = [s.rstrip() for s in ifp.readlines()]
- L.append("")
- self.line = "\n".join(L)
- self.preamble = 1
-
- def convert(self):
- self.subconvert()
-
- def subconvert(self, endchar=None, depth=0):
- #
- # Parses content, including sub-structures, until the character
- # 'endchar' is found (with no open structures), or until the end
- # of the input data is endchar is None.
- #
- stack = new_stack()
- line = self.line
- while line:
- if line[0] == endchar and not stack:
- self.line = line
- return line
- m = _comment_rx.match(line)
- if m:
- text = m.group(1)
- if text:
- self.write("(COMMENT\n- %s \n)COMMENT\n-\\n\n"
- % encode(text))
- line = line[m.end():]
- continue
- m = _begin_env_rx.match(line)
- if m:
- name = m.group(1)
- entry = self.get_env_entry(name)
- # re-write to use the macro handler
- line = r"\%s %s" % (name, line[m.end():])
- continue
- m = _end_env_rx.match(line)
- if m:
- # end of environment
- envname = m.group(1)
- entry = self.get_entry(envname)
- while stack and envname != stack[-1] \
- and stack[-1] in entry.endcloses:
- self.write(")%s\n" % stack.pop())
- if stack and envname == stack[-1]:
- self.write(")%s\n" % entry.outputname)
- del stack[-1]
- else:
- raise LaTeXStackError(envname, stack)
- line = line[m.end():]
- continue
- m = _begin_macro_rx.match(line)
- if m:
- # start of macro
- macroname = m.group(1)
- if macroname == "c":
- # Ugh! This is a combining character...
- endpos = m.end()
- self.combining_char("c", line[endpos])
- line = line[endpos + 1:]
- continue
- entry = self.get_entry(macroname)
- if entry.verbatim:
- # magic case!
- pos = line.find("\\end{%s}" % macroname)
- text = line[m.end(1):pos]
- stack.append(entry.name)
- self.write("(%s\n" % entry.outputname)
- self.write("-%s\n" % encode(text))
- self.write(")%s\n" % entry.outputname)
- stack.pop()
- line = line[pos + len("\\end{%s}" % macroname):]
- continue
- while stack and stack[-1] in entry.closes:
- top = stack.pop()
- topentry = self.get_entry(top)
- if topentry.outputname:
- self.write(")%s\n-\\n\n" % topentry.outputname)
- #
- if entry.outputname and entry.empty:
- self.write("e\n")
- #
- params, optional, empty = self.start_macro(macroname)
- # rip off the macroname
- if params:
- line = line[m.end(1):]
- elif empty:
- line = line[m.end(1):]
- else:
- line = line[m.end():]
- opened = 0
- implied_content = 0
-
- # handle attribute mappings here:
- for pentry in params:
- if pentry.type == "attribute":
- if pentry.optional:
- m = _optional_rx.match(line)
- if m and entry.outputname:
- line = line[m.end():]
- self.dump_attr(pentry, m.group(1))
- elif pentry.text and entry.outputname:
- # value supplied by conversion spec:
- self.dump_attr(pentry, pentry.text)
- else:
- m = _parameter_rx.match(line)
- if not m:
- raise LaTeXFormatError(
- "could not extract parameter %s for %s: %r"
- % (pentry.name, macroname, line[:100]))
- if entry.outputname:
- self.dump_attr(pentry, m.group(1))
- line = line[m.end():]
- elif pentry.type == "child":
- if pentry.optional:
- m = _optional_rx.match(line)
- if m:
- line = line[m.end():]
- if entry.outputname and not opened:
- opened = 1
- self.write("(%s\n" % entry.outputname)
- stack.append(macroname)
- stack.append(pentry.name)
- self.write("(%s\n" % pentry.name)
- self.write("-%s\n" % encode(m.group(1)))
- self.write(")%s\n" % pentry.name)
- stack.pop()
- else:
- if entry.outputname and not opened:
- opened = 1
- self.write("(%s\n" % entry.outputname)
- stack.append(entry.name)
- self.write("(%s\n" % pentry.name)
- stack.append(pentry.name)
- self.line = skip_white(line)[1:]
- line = self.subconvert(
- "}", len(stack) + depth + 1)[1:]
- self.write(")%s\n" % stack.pop())
- elif pentry.type == "content":
- if pentry.implied:
- implied_content = 1
- else:
- if entry.outputname and not opened:
- opened = 1
- self.write("(%s\n" % entry.outputname)
- stack.append(entry.name)
- line = skip_white(line)
- if line[0] != "{":
- raise LaTeXFormatError(
- "missing content for " + macroname)
- self.line = line[1:]
- line = self.subconvert("}", len(stack) + depth + 1)
- if line and line[0] == "}":
- line = line[1:]
- elif pentry.type == "text" and pentry.text:
- if entry.outputname and not opened:
- opened = 1
- stack.append(entry.name)
- self.write("(%s\n" % entry.outputname)
- #dbgmsg("--- text: %r" % pentry.text)
- self.write("-%s\n" % encode(pentry.text))
- elif pentry.type == "entityref":
- self.write("&%s\n" % pentry.name)
- if entry.outputname:
- if not opened:
- self.write("(%s\n" % entry.outputname)
- stack.append(entry.name)
- if not implied_content:
- self.write(")%s\n" % entry.outputname)
- stack.pop()
- continue
- if line[0] == endchar and not stack:
- self.line = line[1:]
- return self.line
- if line[0] == "}":
- # end of macro or group
- macroname = stack[-1]
- if macroname:
- conversion = self.table[macroname]
- if conversion.outputname:
- # otherwise, it was just a bare group
- self.write(")%s\n" % conversion.outputname)
- del stack[-1]
- line = line[1:]
- continue
- if line[0] == "~":
- # don't worry about the "tie" aspect of this command
- line = line[1:]
- self.write("- \n")
- continue
- if line[0] == "{":
- stack.append("")
- line = line[1:]
- continue
- if line[0] == "\\" and line[1] in ESCAPED_CHARS:
- self.write("-%s\n" % encode(line[1]))
- line = line[2:]
- continue
- if line[:2] == r"\\":
- self.write("(BREAK\n)BREAK\n")
- line = line[2:]
- continue
- if line[:2] == r"\_":
- line = "_" + line[2:]
- continue
- if line[:2] in (r"\'", r'\"'):
- # combining characters...
- self.combining_char(line[1], line[2])
- line = line[3:]
- continue
- m = _text_rx.match(line)
- if m:
- text = encode(m.group())
- self.write("-%s\n" % text)
- line = line[m.end():]
- continue
- # special case because of \item[]
- # XXX can we axe this???
- if line[0] == "]":
- self.write("-]\n")
- line = line[1:]
- continue
- # avoid infinite loops
- extra = ""
- if len(line) > 100:
- extra = "..."
- raise LaTeXFormatError("could not identify markup: %r%s"
- % (line[:100], extra))
- while stack:
- entry = self.get_entry(stack[-1])
- if entry.closes:
- self.write(")%s\n-%s\n" % (entry.outputname, encode("\n")))
- del stack[-1]
- else:
- break
- if stack:
- raise LaTeXFormatError("elements remain on stack: "
- + ", ".join(stack))
- # otherwise we just ran out of input here...
-
- # This is a really limited table of combinations, but it will have
- # to do for now.
- _combinations = {
- ("c", "c"): 0x00E7,
- ("'", "e"): 0x00E9,
- ('"', "o"): 0x00F6,
- }
-
- def combining_char(self, prefix, char):
- ordinal = self._combinations[(prefix, char)]
- self.write("-\\%%%d;\n" % ordinal)
-
- def start_macro(self, name):
- conversion = self.get_entry(name)
- parameters = conversion.parameters
- optional = parameters and parameters[0].optional
- return parameters, optional, conversion.empty
-
- def get_entry(self, name):
- entry = self.table.get(name)
- if entry is None:
- dbgmsg("get_entry(%r) failing; building default entry!" % (name, ))
- # not defined; build a default entry:
- entry = TableEntry(name)
- entry.has_content = 1
- entry.parameters.append(Parameter("content"))
- self.table[name] = entry
- return entry
-
- def get_env_entry(self, name):
- entry = self.table.get(name)
- if entry is None:
- # not defined; build a default entry:
- entry = TableEntry(name, 1)
- entry.has_content = 1
- entry.parameters.append(Parameter("content"))
- entry.parameters[-1].implied = 1
- self.table[name] = entry
- elif not entry.environment:
- raise LaTeXFormatError(
- name + " is defined as a macro; expected environment")
- return entry
-
- def dump_attr(self, pentry, value):
- if not (pentry.name and value):
- return
- if _token_rx.match(value):
- dtype = "TOKEN"
- else:
- dtype = "CDATA"
- self.write("A%s %s %s\n" % (pentry.name, dtype, encode(value)))
-
-
-def convert(ifp, ofp, table):
- c = Conversion(ifp, ofp, table)
- try:
- c.convert()
- except IOError as e:
- (err, msg) = e
- if err != errno.EPIPE:
- raise
-
-
-def skip_white(line):
- while line and line[0] in " %\n\t\r":
- line = line[1:].lstrip()
- return line
-
-
-
-class TableEntry:
- def __init__(self, name, environment=0):
- self.name = name
- self.outputname = name
- self.environment = environment
- self.empty = not environment
- self.has_content = 0
- self.verbatim = 0
- self.auto_close = 0
- self.parameters = []
- self.closes = []
- self.endcloses = []
-
-class Parameter:
- def __init__(self, type, name=None, optional=0):
- self.type = type
- self.name = name
- self.optional = optional
- self.text = ''
- self.implied = 0
-
-
-class TableHandler(xml.sax.handler.ContentHandler):
- def __init__(self):
- self.__table = {}
- self.__buffer = ''
- self.__methods = {}
-
- def get_table(self):
- for entry in self.__table.values():
- if entry.environment and not entry.has_content:
- p = Parameter("content")
- p.implied = 1
- entry.parameters.append(p)
- entry.has_content = 1
- return self.__table
-
- def startElement(self, tag, attrs):
- try:
- start, end = self.__methods[tag]
- except KeyError:
- start = getattr(self, "start_" + tag, None)
- end = getattr(self, "end_" + tag, None)
- self.__methods[tag] = (start, end)
- if start:
- start(attrs)
-
- def endElement(self, tag):
- start, end = self.__methods[tag]
- if end:
- end()
-
- def endDocument(self):
- self.__methods.clear()
-
- def characters(self, data):
- self.__buffer += data
-
- def start_environment(self, attrs):
- name = attrs["name"]
- self.__current = TableEntry(name, environment=1)
- self.__current.verbatim = attrs.get("verbatim") == "yes"
- if "outputname" in attrs:
- self.__current.outputname = attrs.get("outputname")
- self.__current.endcloses = attrs.get("endcloses", "").split()
- def end_environment(self):
- self.end_macro()
-
- def start_macro(self, attrs):
- name = attrs["name"]
- self.__current = TableEntry(name)
- self.__current.closes = attrs.get("closes", "").split()
- if "outputname" in attrs:
- self.__current.outputname = attrs.get("outputname")
- def end_macro(self):
- name = self.__current.name
- if name in self.__table:
- raise ValueError("name %r already in use" % (name,))
- self.__table[name] = self.__current
- self.__current = None
-
- def start_attribute(self, attrs):
- name = attrs.get("name")
- optional = attrs.get("optional") == "yes"
- if name:
- p = Parameter("attribute", name, optional=optional)
- else:
- p = Parameter("attribute", optional=optional)
- self.__current.parameters.append(p)
- self.__buffer = ''
- def end_attribute(self):
- self.__current.parameters[-1].text = self.__buffer
-
- def start_entityref(self, attrs):
- name = attrs["name"]
- p = Parameter("entityref", name)
- self.__current.parameters.append(p)
-
- def start_child(self, attrs):
- name = attrs["name"]
- p = Parameter("child", name, attrs.get("optional") == "yes")
- self.__current.parameters.append(p)
- self.__current.empty = 0
-
- def start_content(self, attrs):
- p = Parameter("content")
- p.implied = attrs.get("implied") == "yes"
- if self.__current.environment:
- p.implied = 1
- self.__current.parameters.append(p)
- self.__current.has_content = 1
- self.__current.empty = 0
-
- def start_text(self, attrs):
- self.__current.empty = 0
- self.__buffer = ''
- def end_text(self):
- p = Parameter("text")
- p.text = self.__buffer
- self.__current.parameters.append(p)
-
-
-def load_table(fp):
- ch = TableHandler()
- xml.sax.parse(fp, ch)
- return ch.get_table()
-
-
-def main():
- global DEBUG
- #
- opts, args = getopt.getopt(sys.argv[1:], "D", ["debug"])
- for opt, arg in opts:
- if opt in ("-D", "--debug"):
- DEBUG += 1
- if len(args) == 0:
- ifp = sys.stdin
- ofp = sys.stdout
- elif len(args) == 1:
- ifp = open(args[0])
- ofp = sys.stdout
- elif len(args) == 2:
- ifp = open(args[0])
- ofp = open(args[1], "w")
- else:
- usage()
- sys.exit(2)
-
- table = load_table(open(os.path.join(sys.path[0], 'conversion.xml')))
- convert(ifp, ofp, table)
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/sgmlconv/make.rules b/Doc/tools/sgmlconv/make.rules
deleted file mode 100644
index 93579c5..0000000
--- a/Doc/tools/sgmlconv/make.rules
+++ /dev/null
@@ -1,48 +0,0 @@
-# -*- makefile -*-
-#
-# Extra magic needed by the LaTeX->XML conversion process. This requires
-# $(TOOLSDIR) to be properly defined.
-
-DOCFIXER= $(TOOLSDIR)/sgmlconv/docfixer.py
-ESIS2ML= $(TOOLSDIR)/sgmlconv/esis2sgml.py
-LATEX2ESIS= $(TOOLSDIR)/sgmlconv/latex2esis.py
-CONVERSION= $(TOOLSDIR)/sgmlconv/conversion.xml
-
-ESISTARGETS= $(patsubst %.tex,%.esis,$(wildcard *.tex))
-ESIS1TARGETS= $(patsubst %.tex,%.esis1,$(wildcard *.tex))
-XMLTARGETS= $(patsubst %.tex,%.xml,$(wildcard *.tex))
-
-L2EFLAGS=
-
-all: xml
-
-esis: $(ESISTARGETS)
-esis1: $(ESIS1TARGETS)
-xml: $(XMLTARGETS)
-
-ESISTOOLS= $(TOOLSDIR)/sgmlconv/esistools.py
-
-$(ESISTARGETS): $(LATEX2ESIS) $(DOCFIXER) $(ESISTOOLS) $(CONVERSION)
-$(ESIS1TARGETS): $(LATEX2ESIS) $(CONVERSION)
-# This variant is easier to work with while debugging the conversion spec:
-#$(ESISTARGETS): $(LATEX2ESIS) $(DOCFIXER) $(ESISTOOLS)
-$(XMLTARGETS): $(ESIS2ML)
-
-
-.SUFFIXES: .esis .esis1 .tex .xml
-
-.tex.esis1:
- $(LATEX2ESIS) $(L2EFLAGS) $< $@
-
-.esis1.esis:
- $(DOCFIXER) $< $@
-
-.esis.xml:
- $(ESIS2ML) --xml $< $@
-
-
-clean:
- rm -f *.esis *.esis1
-
-clobber: clean
- rm -f *.xml
diff --git a/Doc/tools/support.py b/Doc/tools/support.py
deleted file mode 100644
index fc4cafa..0000000
--- a/Doc/tools/support.py
+++ /dev/null
@@ -1,202 +0,0 @@
-"""Miscellaneous support code shared by some of the tool scripts.
-
-This includes option parsing code, HTML formatting code, and a couple of
-useful helpers.
-
-"""
-__version__ = '$Revision$'
-
-
-import getopt
-import os.path
-import sys
-
-
-class Options:
- __short_args = "a:c:ho:"
- __long_args = [
- # script controls
- "columns=", "help", "output=",
-
- # content components
- "address=", "iconserver=", "favicon=",
- "title=", "uplink=", "uptitle=",
- "image-type=",
- ]
-
- outputfile = "-"
- columns = 1
- letters = 0
- uplink = "index.html"
- uptitle = "Python Documentation Index"
- favicon = None
-
- # The "Aesop Meta Tag" is poorly described, and may only be used
- # by the Aesop search engine (www.aesop.com), but doesn't hurt.
- #
- # There are a number of values this may take to roughly categorize
- # a page. A page should be marked according to its primary
- # category. Known values are:
- # 'personal' -- personal-info
- # 'information' -- information
- # 'interactive' -- interactive media
- # 'multimedia' -- multimedia presenetation (non-sales)
- # 'sales' -- sales material
- # 'links' -- links to other information pages
- #
- # Setting the aesop_type value to one of these strings will cause
- # get_header() to add the appropriate <meta> tag to the <head>.
- #
- aesop_type = None
-
- def __init__(self):
- self.args = []
- self.variables = {"address": "",
- "iconserver": "icons",
- "imgtype": "png",
- "title": "Global Module Index",
- }
-
- def add_args(self, short=None, long=None):
- if short:
- self.__short_args = self.__short_args + short
- if long:
- self.__long_args = self.__long_args + long
-
- def parse(self, args):
- try:
- opts, args = getopt.getopt(args, self.__short_args,
- self.__long_args)
- except getopt.error:
- sys.stdout = sys.stderr
- self.usage()
- sys.exit(2)
- self.args = self.args + args
- for opt, val in opts:
- if opt in ("-a", "--address"):
- val = val.strip()
- if val:
- val = "<address>\n%s\n</address>\n" % val
- self.variables["address"] = val
- elif opt in ("-h", "--help"):
- self.usage()
- sys.exit()
- elif opt in ("-o", "--output"):
- self.outputfile = val
- elif opt in ("-c", "--columns"):
- self.columns = int(val)
- elif opt == "--title":
- self.variables["title"] = val.strip()
- elif opt == "--uplink":
- self.uplink = val.strip()
- elif opt == "--uptitle":
- self.uptitle = val.strip()
- elif opt == "--iconserver":
- self.variables["iconserver"] = val.strip() or "."
- elif opt == "--favicon":
- self.favicon = val.strip()
- elif opt == "--image-type":
- self.variables["imgtype"] = val.strip()
- else:
- self.handle_option(opt, val)
- if self.uplink and self.uptitle:
- self.variables["uplinkalt"] = "up"
- self.variables["uplinkicon"] = "up"
- else:
- self.variables["uplinkalt"] = ""
- self.variables["uplinkicon"] = "blank"
- self.variables["uplink"] = self.uplink
- self.variables["uptitle"] = self.uptitle
-
- def handle_option(self, opt, val):
- raise getopt.error("option %s not recognized" % opt)
-
- def get_header(self):
- s = HEAD % self.variables
- if self.uplink:
- if self.uptitle:
- link = ('<link rel="up" href="%s" title="%s">\n '
- '<link rel="start" href="%s" title="%s">'
- % (self.uplink, self.uptitle,
- self.uplink, self.uptitle))
- else:
- link = ('<link rel="up" href="%s">\n '
- '<link rel="start" href="%s">'
- % (self.uplink, self.uplink))
- repl = " %s\n</head>" % link
- s = s.replace("</head>", repl, 1)
- if self.aesop_type:
- meta = '<meta name="aesop" content="%s">\n ' % self.aesop_type
- # Insert this in the middle of the head that's been
- # generated so far, keeping <meta> and <link> elements in
- # neat groups:
- s = s.replace("<link ", meta + "<link ", 1)
- if self.favicon:
- ext = os.path.splitext(self.favicon)[1]
- if ext in (".gif", ".png"):
- type = ' type="image/%s"' % ext[1:]
- else:
- type = ''
- link = ('<link rel="SHORTCUT ICON" href="%s"%s>\n '
- % (self.favicon, type))
- s = s.replace("<link ", link + "<link ", 1)
- return s
-
- def get_footer(self):
- return TAIL % self.variables
-
- def get_output_file(self, filename=None):
- if filename is None:
- filename = self.outputfile
- if filename == "-":
- return sys.stdout
- else:
- return open(filename, "w")
-
-
-NAVIGATION = '''\
-<div class="navigation">
-<table width="100%%" cellpadding="0" cellspacing="2">
-<tr>
-<td><img width="32" height="32" align="bottom" border="0" alt=""
- src="%(iconserver)s/blank.%(imgtype)s"></td>
-<td><a href="%(uplink)s"
- title="%(uptitle)s"><img width="32" height="32" align="bottom" border="0"
- alt="%(uplinkalt)s"
- src="%(iconserver)s/%(uplinkicon)s.%(imgtype)s"></a></td>
-<td><img width="32" height="32" align="bottom" border="0" alt=""
- src="%(iconserver)s/blank.%(imgtype)s"></td>
-<td align="center" width="100%%">%(title)s</td>
-<td><img width="32" height="32" align="bottom" border="0" alt=""
- src="%(iconserver)s/blank.%(imgtype)s"></td>
-<td><img width="32" height="32" align="bottom" border="0" alt=""
- src="%(iconserver)s/blank.%(imgtype)s"></td>
-<td><img width="32" height="32" align="bottom" border="0" alt=""
- src="%(iconserver)s/blank.%(imgtype)s"></td>
-</tr></table>
-<b class="navlabel">Up:</b> <span class="sectref"><a href="%(uplink)s"
- title="%(uptitle)s">%(uptitle)s</A></span>
-<br></div>
-'''
-
-HEAD = '''\
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<html>
-<head>
- <title>%(title)s</title>
- <meta name="description" content="%(title)s">
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <link rel="STYLESHEET" href="lib/lib.css">
-</head>
-<body>
-''' + NAVIGATION + '''\
-<hr>
-
-<h2>%(title)s</h2>
-
-'''
-
-TAIL = "<hr>\n" + NAVIGATION + '''\
-%(address)s</body>
-</html>
-'''
diff --git a/Doc/tools/toc2bkm.py b/Doc/tools/toc2bkm.py
deleted file mode 100755
index ab669ba..0000000
--- a/Doc/tools/toc2bkm.py
+++ /dev/null
@@ -1,160 +0,0 @@
-#! /usr/bin/env python
-
-"""Convert a LaTeX .toc file to some PDFTeX magic to create that neat outline.
-
-The output file has an extension of '.bkm' instead of '.out', since hyperref
-already uses that extension.
-"""
-
-import getopt
-import os
-import re
-import string
-import sys
-
-
-# Ench item in an entry is a tuple of:
-#
-# Section #, Title String, Page #, List of Sub-entries
-#
-# The return value of parse_toc() is such a tuple.
-
-cline_re = r"""^
-\\contentsline\ \{([a-z]*)} # type of section in $1
-\{(?:\\numberline\ \{([0-9.A-Z]+)})? # section number
-(.*)} # title string
-\{(\d+)}$""" # page number
-
-cline_rx = re.compile(cline_re, re.VERBOSE)
-
-OUTER_TO_INNER = -1
-
-_transition_map = {
- ('chapter', 'section'): OUTER_TO_INNER,
- ('section', 'subsection'): OUTER_TO_INNER,
- ('subsection', 'subsubsection'): OUTER_TO_INNER,
- ('subsubsection', 'subsection'): 1,
- ('subsection', 'section'): 1,
- ('section', 'chapter'): 1,
- ('subsection', 'chapter'): 2,
- ('subsubsection', 'section'): 2,
- ('subsubsection', 'chapter'): 3,
- }
-
-INCLUDED_LEVELS = ("chapter", "section", "subsection", "subsubsection")
-
-
-class BadSectionNesting(Exception):
- """Raised for unsupported section level transitions."""
-
- def __init__(self, level, newsection, path, lineno):
- self.level = level
- self.newsection = newsection
- self.path = path
- self.lineno = lineno
-
- def __str__(self):
- return ("illegal transition from %s to %s at %s (line %s)"
- % (self.level, self.newsection, self.path, self.lineno))
-
-
-def parse_toc(fp, bigpart=None):
- toc = top = []
- stack = [toc]
- level = bigpart or 'chapter'
- lineno = 0
- while 1:
- line = fp.readline()
- if not line:
- break
- lineno = lineno + 1
- m = cline_rx.match(line)
- if m:
- stype, snum, title, pageno = m.group(1, 2, 3, 4)
- title = clean_title(title)
- entry = (stype, snum, title, int(pageno), [])
- if stype == level:
- toc.append(entry)
- else:
- if stype not in INCLUDED_LEVELS:
- # we don't want paragraphs & subparagraphs
- continue
- try:
- direction = _transition_map[(level, stype)]
- except KeyError:
- raise BadSectionNesting(level, stype, fp.name, lineno)
- if direction == OUTER_TO_INNER:
- toc = toc[-1][-1]
- stack.insert(0, toc)
- toc.append(entry)
- else:
- for i in range(direction):
- del stack[0]
- toc = stack[0]
- toc.append(entry)
- level = stype
- else:
- sys.stderr.write("l.%s: " + line)
- return top
-
-
-hackscore_rx = re.compile(r"\\hackscore\s*{[^}]*}")
-raisebox_rx = re.compile(r"\\raisebox\s*{[^}]*}")
-title_rx = re.compile(r"\\([a-zA-Z])+\s+")
-title_trans = string.maketrans("", "")
-
-def clean_title(title):
- title = raisebox_rx.sub("", title)
- title = hackscore_rx.sub(r"\\_", title)
- pos = 0
- while 1:
- m = title_rx.search(title, pos)
- if m:
- start = m.start()
- if title[start:start+15] != "\\textunderscore":
- title = title[:start] + title[m.end():]
- pos = start + 1
- else:
- break
- title = title.translate(title_trans, "{}")
- return title
-
-
-def write_toc(toc, fp):
- for entry in toc:
- write_toc_entry(entry, fp, 0)
-
-def write_toc_entry(entry, fp, layer):
- stype, snum, title, pageno, toc = entry
- s = "\\pdfoutline goto name{page%03d}" % pageno
- if toc:
- s = "%s count -%d" % (s, len(toc))
- if snum:
- title = "%s %s" % (snum, title)
- s = "%s {%s}\n" % (s, title)
- fp.write(s)
- for entry in toc:
- write_toc_entry(entry, fp, layer + 1)
-
-
-def process(ifn, ofn, bigpart=None):
- toc = parse_toc(open(ifn), bigpart)
- write_toc(toc, open(ofn, "w"))
-
-
-def main():
- bigpart = None
- opts, args = getopt.getopt(sys.argv[1:], "c:")
- if opts:
- bigpart = opts[0][1]
- if not args:
- usage()
- sys.exit(2)
- for filename in args:
- base, ext = os.path.splitext(filename)
- ext = ext or ".toc"
- process(base + ext, base + ".bkm", bigpart)
-
-
-if __name__ == "__main__":
- main()
diff --git a/Doc/tools/undoc_symbols.py b/Doc/tools/undoc_symbols.py
deleted file mode 100644
index 14cb941..0000000
--- a/Doc/tools/undoc_symbols.py
+++ /dev/null
@@ -1,93 +0,0 @@
-#! /usr/bin/env python
-
-"""\
-This script prints out a list of undocumented symbols found in
-Python include files, prefixed by their tag kind.
-
-Pass Python's include files to ctags, parse the output into a
-dictionary mapping symbol names to tag kinds.
-
-Then, the .tex files from Python docs are read into a giant string.
-
-Finally all symbols not found in the docs are written to standard
-output, prefixed with their tag kind.
-"""
-
-# Which kind of tags do we need?
-TAG_KINDS = "dpst"
-
-# Doc sections to use
-DOCSECTIONS = ["api"]# ["api", "ext"]
-
-# Only print symbols starting with this prefix,
-# to get all symbols, use an empty string
-PREFIXES = ("Py", "PY")
-
-INCLUDEPATTERN = "*.h"
-
-# end of customization section
-
-
-# Tested with EXUBERANT CTAGS
-# see http://ctags.sourceforge.net
-#
-# ctags fields are separated by tabs.
-# The first field is the name, the last field the type:
-# d macro definitions (and #undef names)
-# e enumerators
-# f function definitions
-# g enumeration names
-# m class, struct, or union members
-# n namespaces
-# p function prototypes and declarations
-# s structure names
-# t typedefs
-# u union names
-# v variable definitions
-# x extern and forward variable declarations
-
-import os, glob, re, sys
-
-def findnames(file, prefixes=()):
- names = {}
- for line in file:
- if line[0] == '!':
- continue
- fields = line.split()
- name, tag = fields[0], fields[-1]
- if tag == 'd' and name.endswith('_H'):
- continue
- if prefixes:
- sw = name.startswith
- for prefix in prefixes:
- if sw(prefix):
- names[name] = tag
- else:
- names[name] = tag
- return names
-
-def print_undoc_symbols(prefix, docdir, incdir):
- docs = []
-
- for sect in DOCSECTIONS:
- for file in glob.glob(os.path.join(docdir, sect, "*.tex")):
- docs.append(open(file).read())
-
- docs = "\n".join(docs)
-
- incfiles = os.path.join(incdir, INCLUDEPATTERN)
-
- fp = os.popen("ctags -IPyAPI_FUNC -IPy_GCC_ATTRIBUTE --c-types=%s -f - %s"
- % (TAG_KINDS, incfiles))
- dict = findnames(fp, prefix)
- names = sorted(dict.keys())
- for name in names:
- if not re.search("%s\\W" % name, docs):
- print(dict[name], name)
-
-if __name__ == '__main__':
- srcdir = os.path.dirname(sys.argv[0])
- incdir = os.path.normpath(os.path.join(srcdir, "../../Include"))
- docdir = os.path.normpath(os.path.join(srcdir, ".."))
-
- print_undoc_symbols(PREFIXES, docdir, incdir)
diff --git a/Doc/tools/update-docs.sh b/Doc/tools/update-docs.sh
deleted file mode 100755
index 6599c64..0000000
--- a/Doc/tools/update-docs.sh
+++ /dev/null
@@ -1,31 +0,0 @@
-#! /bin/sh
-
-# Script which installs a development snapshot of the documentation
-# into the development website.
-#
-# The push-docs.sh script pushes this to the server when needed
-# and removes it when done.
-
-if [ -z "$HOME" ] ; then
- HOME=`grep "$LOGNAME" /etc/passwd | sed 's|^.*:\([^:]*\):[^:]*$|\1|'`
- export HOME
-fi
-
-DOCTYPE="$1"
-UPDATES="$HOME/tmp/$2"
-
-TMPDIR="$$-docs"
-
-cd /ftp/ftp.python.org/pub/www.python.org/dev/doc/ || exit $?
-mkdir $TMPDIR || exit $?
-cd $TMPDIR || exit $?
-(bzip2 -dc "$UPDATES" | tar xf -) || exit $?
-cd .. || exit $?
-
-if [ -d $DOCTYPE ] ; then
- mv $DOCTYPE $DOCTYPE-temp
-fi
-mv $TMPDIR/Python-Docs-* $DOCTYPE
-rmdir $TMPDIR
-rm -rf $DOCTYPE-temp || exit $?
-mv "$UPDATES" python-docs-$DOCTYPE.tar.bz2 || exit $?
diff --git a/Doc/tools/whichlibs b/Doc/tools/whichlibs
deleted file mode 100755
index 10d44ee..0000000
--- a/Doc/tools/whichlibs
+++ /dev/null
@@ -1,2 +0,0 @@
-#!/bin/sh
-sed -n 's%^\\input{\(lib[a-zA-Z0-9_]*\)}.*%../lib/\1.tex%p' ../lib/lib.tex
diff --git a/Doc/tut/glossary.tex b/Doc/tut/glossary.tex
deleted file mode 100644
index a19416b..0000000
--- a/Doc/tut/glossary.tex
+++ /dev/null
@@ -1,327 +0,0 @@
-\chapter{Glossary\label{glossary}}
-
-%%% keep the entries sorted and include at least one \index{} item for each
-%%% cross-references are marked with \emph{entry}
-
-\begin{description}
-
-
-\index{>>>}
-\item[\code{>>>}]
-The typical Python prompt of the interactive shell. Often seen for
-code examples that can be tried right away in the interpreter.
-
-\index{...}
-\item[\code{.\code{.}.}]
-The typical Python prompt of the interactive shell when entering code
-for an indented code block.
-
-\index{BDFL}
-\item[BDFL]
-Benevolent Dictator For Life, a.k.a. \ulink{Guido van
-Rossum}{http://www.python.org/\textasciitilde{}guido/}, Python's creator.
-
-\index{byte code}
-\item[byte code]
-The internal representation of a Python program in the interpreter.
-The byte code is also cached in \code{.pyc} and \code{.pyo}
-files so that executing the same file is faster the second time
-(recompilation from source to byte code can be avoided). This
-``intermediate language'' is said to run on a ``virtual
-machine'' that calls the subroutines corresponding to each bytecode.
-
-\index{classic class}
-\item[classic class]
-Any class which does not inherit from \class{object}. See
-\emph{new-style class}.
-
-\index{complex number}
-\item[complex number]
-An extension of the familiar real number system in which all numbers are
-expressed as a sum of a real part and an imaginary part. Imaginary numbers
-are real multiples of the imaginary unit (the square root of {}\code{-1}),
-often written {}\code{i} in mathematics or {}\code{j} in engineering.
-Python has builtin support for complex numbers, which are written with this
-latter notation; the imaginary part is written with a {}\code{j} suffix,
-e.g., {}\code{3+1j}. To get access to complex equivalents of the
-{}\module{math} module, use {}\module{cmath}. Use of complex numbers is a
-fairly advanced mathematical feature. If you're not aware of a need for them,
-it's almost certain you can safely ignore them.
-
-\index{descriptor}
-\item[descriptor]
-Any \emph{new-style} object that defines the methods
-{}\method{__get__()}, \method{__set__()}, or \method{__delete__()}.
-When a class attribute is a descriptor, its special binding behavior
-is triggered upon attribute lookup. Normally, writing \var{a.b} looks
-up the object \var{b} in the class dictionary for \var{a}, but if
-{}\var{b} is a descriptor, the defined method gets called.
-Understanding descriptors is a key to a deep understanding of Python
-because they are the basis for many features including functions,
-methods, properties, class methods, static methods, and reference to
-super classes.
-
-\index{dictionary}
-\item[dictionary]
-An associative array, where arbitrary keys are mapped to values. The
-use of \class{dict} much resembles that for \class{list}, but the keys
-can be any object with a \method{__hash__()} function, not just
-integers starting from zero. Called a hash in Perl.
-
-\index{duck-typing}
-\item[duck-typing]
-Pythonic programming style that determines an object's type by inspection
-of its method or attribute signature rather than by explicit relationship
-to some type object ("If it looks like a duck and quacks like a duck, it
-must be a duck.") By emphasizing interfaces rather than specific types,
-well-designed code improves its flexibility by allowing polymorphic
-substitution. Duck-typing avoids tests using \function{type()} or
-\function{isinstance()}. Instead, it typically employs
-\function{hasattr()} tests or {}\emph{EAFP} programming.
-
-\index{EAFP}
-\item[EAFP]
-Easier to ask for forgiveness than permission. This common Python
-coding style assumes the existence of valid keys or attributes and
-catches exceptions if the assumption proves false. This clean and
-fast style is characterized by the presence of many \keyword{try} and
-{}\keyword{except} statements. The technique contrasts with the
-{}\emph{LBYL} style that is common in many other languages such as C.
-
-\index{__future__}
-\item[__future__]
-A pseudo module which programmers can use to enable new language
-features which are not compatible with the current interpreter.
-To enable \code{new_feature}
-
-\begin{verbatim}
-from __future__ import new_feature
-\end{verbatim}
-
-By importing the \ulink{\module{__future__}}{../lib/module-future.html}
-module and evaluating its variables, you can see when a new feature
-was first added to the language and when it will become the default:
-
-\begin{verbatim}
->>> import __future__
->>> __future__.division
-_Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)
-\end{verbatim}
-
-\index{generator}
-\item[generator]
-A function that returns an iterator. It looks like a normal function except
-that values are returned to the caller using a \keyword{yield} statement
-instead of a {}\keyword{return} statement. Generator functions often
-contain one or more {}\keyword{for} or \keyword{while} loops that
-\keyword{yield} elements back to the caller. The function execution is
-stopped at the {}\keyword{yield} keyword (returning the result) and is
-resumed there when the next element is requested by calling the
-\method{__next__()} method of the returned iterator.
-
-\index{generator expression}
-\item[generator expression]
-An expression that returns a generator. It looks like a normal expression
-followed by a \keyword{for} expression defining a loop variable, range, and
-an optional \keyword{if} expression. The combined expression generates
-values for an enclosing function:
-
-\begin{verbatim}
->>> sum(i*i for i in range(10)) # sum of squares 0, 1, 4, ... 81
-285
-\end{verbatim}
-
-\index{GIL}
-\item[GIL]
-See \emph{global interpreter lock}.
-
-\index{global interpreter lock}
-\item[global interpreter lock]
-The lock used by Python threads to assure that only one thread can be
-run at a time. This simplifies Python by assuring that no two
-processes can access the same memory at the same time. Locking the
-entire interpreter makes it easier for the interpreter to be
-multi-threaded, at the expense of some parallelism on multi-processor
-machines. Efforts have been made in the past to create a
-``free-threaded'' interpreter (one which locks shared data at a much
-finer granularity), but performance suffered in the common
-single-processor case.
-
-\index{IDLE}
-\item[IDLE]
-An Integrated Development Environment for Python. IDLE is a
-basic editor and interpreter environment that ships with the standard
-distribution of Python. Good for beginners, it also serves as clear
-example code for those wanting to implement a moderately
-sophisticated, multi-platform GUI application.
-
-\index{immutable}
-\item[immutable]
-An object with fixed value. Immutable objects are numbers, strings or
-tuples (and more). Such an object cannot be altered. A new object
-has to be created if a different value has to be stored. They play an
-important role in places where a constant hash value is needed, for
-example as a key in a dictionary.
-
-\index{integer division}
-\item[integer division]
-Mathematical division including any remainder. The result will always
-be a float. For example, the expression \code{11/4} evaluates to \code{2.75}.
-Integer division can be forced by using the \code{//} operator instead
-of the \code{/} operator.
-
-\index{interactive}
-\item[interactive]
-Python has an interactive interpreter which means that you can try out
-things and immediately see their results. Just launch \code{python} with no
-arguments (possibly by selecting it from your computer's main menu).
-It is a very powerful way to test out new ideas or inspect modules and
-packages (remember \code{help(x)}).
-
-\index{interpreted}
-\item[interpreted]
-Python is an interpreted language, as opposed to a compiled one. This means
-that the source files can be run directly without first creating an
-executable which is then run. Interpreted languages typically have a
-shorter development/debug cycle than compiled ones, though their programs
-generally also run more slowly. See also {}\emph{interactive}.
-
-\index{iterable}
-\item[iterable]
-A container object capable of returning its members one at a time.
-Examples of iterables include all sequence types (such as \class{list},
-{}\class{str}, and \class{tuple}) and some non-sequence types like
-{}\class{dict} and \class{file} and objects of any classes you define
-with an \method{__iter__()} or \method{__getitem__()} method. Iterables
-can be used in a \keyword{for} loop and in many other places where a
-sequence is needed (\function{zip()}, \function{map()}, ...). When an
-iterable object is passed as an argument to the builtin function
-{}\function{iter()}, it returns an iterator for the object. This
-iterator is good for one pass over the set of values. When using
-iterables, it is usually not necessary to call \function{iter()} or
-deal with iterator objects yourself. The \code{for} statement does
-that automatically for you, creating a temporary unnamed variable to
-hold the iterator for the duration of the loop. See also
-{}\emph{iterator}, \emph{sequence}, and \emph{generator}.
-
-\index{iterator}
-\item[iterator]
-An object representing a stream of data. Repeated calls to the
-iterator's \method{__next__()} method return successive items in the
-stream. When no more data is available a \exception{StopIteration}
-exception is raised instead. At this point, the iterator object is
-exhausted and any further calls to its \method{__next__()} method just
-raise \exception{StopIteration} again. Iterators are required to have
-an \method{__iter__()} method that returns the iterator object
-itself so every iterator is also iterable and may be used in most
-places where other iterables are accepted. One notable exception is
-code that attempts multiple iteration passes. A container object
-(such as a \class{list}) produces a fresh new iterator each time you
-pass it to the \function{iter()} function or use it in a
-{}\keyword{for} loop. Attempting this with an iterator will just
-return the same exhausted iterator object used in the previous iteration
-pass, making it appear like an empty container.
-
-\index{LBYL}
-\item[LBYL]
-Look before you leap. This coding style explicitly tests for
-pre-conditions before making calls or lookups. This style contrasts
-with the \emph{EAFP} approach and is characterized by the presence of
-many \keyword{if} statements.
-
-\index{list comprehension}
-\item[list comprehension]
-A compact way to process all or a subset of elements in a sequence and
-return a list with the results. \code{result = ["0x\%02x"
-\% x for x in range(256) if x \% 2 == 0]} generates a list of strings
-containing hex numbers (0x..) that are even and in the range from 0 to 255.
-The \keyword{if} clause is optional. If omitted, all elements in
-{}\code{range(256)} are processed.
-
-\index{mapping}
-\item[mapping]
-A container object (such as \class{dict}) that supports arbitrary key
-lookups using the special method \method{__getitem__()}.
-
-\index{metaclass}
-\item[metaclass]
-The class of a class. Class definitions create a class name, a class
-dictionary, and a list of base classes. The metaclass is responsible
-for taking those three arguments and creating the class. Most object
-oriented programming languages provide a default implementation. What
-makes Python special is that it is possible to create custom
-metaclasses. Most users never need this tool, but when the need
-arises, metaclasses can provide powerful, elegant solutions. They
-have been used for logging attribute access, adding thread-safety,
-tracking object creation, implementing singletons, and many other
-tasks.
-
-\index{mutable}
-\item[mutable]
-Mutable objects can change their value but keep their \function{id()}.
-See also \emph{immutable}.
-
-\index{namespace}
-\item[namespace]
-The place where a variable is stored. Namespaces are implemented as
-dictionaries. There are the local, global and builtin namespaces
-as well as nested namespaces in objects (in methods). Namespaces support
-modularity by preventing naming conflicts. For instance, the
-functions \function{__builtin__.open()} and \function{os.open()} are
-distinguished by their namespaces. Namespaces also aid readability
-and maintainability by making it clear which module implements a
-function. For instance, writing \function{random.seed()} or
-{}\function{itertools.izip()} makes it clear that those functions are
-implemented by the \ulink{\module{random}}{../lib/module-random.html}
-and \ulink{\module{itertools}}{../lib/module-itertools.html} modules
-respectively.
-
-\index{nested scope}
-\item[nested scope]
-The ability to refer to a variable in an enclosing definition. For
-instance, a function defined inside another function can refer to
-variables in the outer function. Note that nested scopes work only
-for reference and not for assignment which will always write to the
-innermost scope. In contrast, local variables both read and write in
-the innermost scope. Likewise, global variables read and write to the
-global namespace.
-
-\index{new-style class}
-\item[new-style class]
-Any class that inherits from \class{object}. This includes all
-built-in types like \class{list} and \class{dict}. Only new-style
-classes can use Python's newer, versatile features like
-{}\method{__slots__}, descriptors, properties,
-\method{__getattribute__()}, class methods, and static methods.
-
-\index{Python3000}
-\item[Python3000]
-A mythical python release, not required to be backward compatible, with
-telepathic interface.
-
-\index{__slots__}
-\item[__slots__]
-A declaration inside a \emph{new-style class} that saves memory by
-pre-declaring space for instance attributes and eliminating instance
-dictionaries. Though popular, the technique is somewhat tricky to get
-right and is best reserved for rare cases where there are large
-numbers of instances in a memory-critical application.
-
-\index{sequence}
-\item[sequence]
-An \emph{iterable} which supports efficient element access using
-integer indices via the \method{__getitem__()} and
-{}\method{__len__()} special methods. Some built-in sequence types
-are \class{list}, \class{str}, \class{tuple}, and \class{unicode}.
-Note that \class{dict} also supports \method{__getitem__()} and
-{}\method{__len__()}, but is considered a mapping rather than a
-sequence because the lookups use arbitrary \emph{immutable} keys
-rather than integers.
-
-\index{Zen of Python}
-\item[Zen of Python]
-Listing of Python design principles and philosophies that are helpful
-in understanding and using the language. The listing can be found by
-typing ``\code{import this}'' at the interactive prompt.
-
-\end{description}
diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex
deleted file mode 100644
index b39cd47..0000000
--- a/Doc/tut/tut.tex
+++ /dev/null
@@ -1,5935 +0,0 @@
-\documentclass{manual}
-\usepackage[T1]{fontenc}
-\usepackage{textcomp}
-
-% Things to do:
-% Should really move the Python startup file info to an appendix
-
-\title{Python Tutorial}
-
-\input{boilerplate}
-
-\makeindex
-
-\begin{document}
-
-\maketitle
-
-\ifhtml
-\chapter*{Front Matter\label{front}}
-\fi
-
-\input{copyright}
-
-\begin{abstract}
-
-\noindent
-Python is an easy to learn, powerful programming language. It has
-efficient high-level data structures and a simple but effective
-approach to object-oriented programming. Python's elegant syntax and
-dynamic typing, together with its interpreted nature, make it an ideal
-language for scripting and rapid application development in many areas
-on most platforms.
-
-The Python interpreter and the extensive standard library are freely
-available in source or binary form for all major platforms from the
-Python Web site, \url{http://www.python.org/}, and may be freely
-distributed. The same site also contains distributions of and
-pointers to many free third party Python modules, programs and tools,
-and additional documentation.
-
-The Python interpreter is easily extended with new functions and data
-types implemented in C or \Cpp{} (or other languages callable from C).
-Python is also suitable as an extension language for customizable
-applications.
-
-This tutorial introduces the reader informally to the basic concepts
-and features of the Python language and system. It helps to have a
-Python interpreter handy for hands-on experience, but all examples are
-self-contained, so the tutorial can be read off-line as well.
-
-For a description of standard objects and modules, see the
-\citetitle[../lib/lib.html]{Python Library Reference} document. The
-\citetitle[../ref/ref.html]{Python Reference Manual} gives a more
-formal definition of the language. To write extensions in C or
-\Cpp, read \citetitle[../ext/ext.html]{Extending and Embedding the
-Python Interpreter} and \citetitle[../api/api.html]{Python/C API
-Reference}. There are also several books covering Python in depth.
-
-This tutorial does not attempt to be comprehensive and cover every
-single feature, or even every commonly used feature. Instead, it
-introduces many of Python's most noteworthy features, and will give
-you a good idea of the language's flavor and style. After reading it,
-you will be able to read and write Python modules and programs, and
-you will be ready to learn more about the various Python library
-modules described in the \citetitle[../lib/lib.html]{Python Library
-Reference}.
-
-\end{abstract}
-
-\tableofcontents
-
-
-\chapter{Whetting Your Appetite \label{intro}}
-
-If you do much work on computers, eventually you find that there's
-some task you'd like to automate. For example, you may wish to
-perform a search-and-replace over a large number of text files, or
-rename and rearrange a bunch of photo files in a complicated way.
-Perhaps you'd like to write a small custom database, or a specialized
-GUI application, or a simple game.
-
-If you're a professional software developer, you may have to work with
-several C/\Cpp/Java libraries but find the usual
-write/compile/test/re-compile cycle is too slow. Perhaps you're
-writing a test suite for such a library and find writing the testing
-code a tedious task. Or maybe you've written a program that could use
-an extension language, and you don't want to design and implement a
-whole new language for your application.
-
-Python is just the language for you.
-
-You could write a {\UNIX} shell script or Windows batch files for some
-of these tasks, but shell scripts are best at moving around files and
-changing text data, not well-suited for GUI applications or games.
-You could write a C/{\Cpp}/Java program, but it can take a lot of
-development time to get even a first-draft program. Python is simpler
-to use, available on Windows, MacOS X, and {\UNIX} operating systems,
-and will help you get the job done more quickly.
-
-Python is simple to use, but it is a real programming language,
-offering much more structure and support for large programs than shell
-scripts or batch files can offer. On the other hand, Python also
-offers much more error checking than C, and, being a
-\emph{very-high-level language}, it has high-level data types built
-in, such as flexible arrays and dictionaries. Because of its more
-general data types Python is applicable to a much larger problem
-domain than Awk or even Perl, yet many things are at
-least as easy in Python as in those languages.
-
-Python allows you to split your program into modules that can be
-reused in other Python programs. It comes with a large collection of
-standard modules that you can use as the basis of your programs --- or
-as examples to start learning to program in Python. Some of these
-modules provide things like file I/O, system calls,
-sockets, and even interfaces to graphical user interface toolkits like Tk.
-
-Python is an interpreted language, which can save you considerable time
-during program development because no compilation and linking is
-necessary. The interpreter can be used interactively, which makes it
-easy to experiment with features of the language, to write throw-away
-programs, or to test functions during bottom-up program development.
-It is also a handy desk calculator.
-
-Python enables programs to be written compactly and readably. Programs
-written in Python are typically much shorter than equivalent C,
-\Cpp{}, or Java programs, for several reasons:
-\begin{itemize}
-\item
-the high-level data types allow you to express complex operations in a
-single statement;
-\item
-statement grouping is done by indentation instead of beginning and ending
-brackets;
-\item
-no variable or argument declarations are necessary.
-\end{itemize}
-
-Python is \emph{extensible}: if you know how to program in C it is easy
-to add a new built-in function or module to the interpreter, either to
-perform critical operations at maximum speed, or to link Python
-programs to libraries that may only be available in binary form (such
-as a vendor-specific graphics library). Once you are really hooked,
-you can link the Python interpreter into an application written in C
-and use it as an extension or command language for that application.
-
-By the way, the language is named after the BBC show ``Monty Python's
-Flying Circus'' and has nothing to do with nasty reptiles. Making
-references to Monty Python skits in documentation is not only allowed,
-it is encouraged!
-
-%\section{Where From Here \label{where}}
-
-Now that you are all excited about Python, you'll want to examine it
-in some more detail. Since the best way to learn a language is
-to use it, the tutorial invites you to play with the Python interpreter
-as you read.
-
-In the next chapter, the mechanics of using the interpreter are
-explained. This is rather mundane information, but essential for
-trying out the examples shown later.
-
-The rest of the tutorial introduces various features of the Python
-language and system through examples, beginning with simple
-expressions, statements and data types, through functions and modules,
-and finally touching upon advanced concepts like exceptions
-and user-defined classes.
-
-\chapter{Using the Python Interpreter \label{using}}
-
-\section{Invoking the Interpreter \label{invoking}}
-
-The Python interpreter is usually installed as
-\file{/usr/local/bin/python} on those machines where it is available;
-putting \file{/usr/local/bin} in your \UNIX{} shell's search path
-makes it possible to start it by typing the command
-
-\begin{verbatim}
-python
-\end{verbatim}
-
-to the shell. Since the choice of the directory where the interpreter
-lives is an installation option, other places are possible; check with
-your local Python guru or system administrator. (E.g.,
-\file{/usr/local/python} is a popular alternative location.)
-
-On Windows machines, the Python installation is usually placed in
-\file{C:\e Python30}, though you can change this when you're running
-the installer. To add this directory to your path,
-you can type the following command into the command prompt in a DOS box:
-
-\begin{verbatim}
-set path=%path%;C:\python30
-\end{verbatim}
-
-
-Typing an end-of-file character (\kbd{Control-D} on \UNIX,
-\kbd{Control-Z} on Windows) at the primary prompt causes the
-interpreter to exit with a zero exit status. If that doesn't work,
-you can exit the interpreter by typing the following commands:
-\samp{import sys; sys.exit()}.
-
-The interpreter's line-editing features usually aren't very
-sophisticated. On \UNIX, whoever installed the interpreter may have
-enabled support for the GNU readline library, which adds more
-elaborate interactive editing and history features. Perhaps the
-quickest check to see whether command line editing is supported is
-typing Control-P to the first Python prompt you get. If it beeps, you
-have command line editing; see Appendix \ref{interacting} for an
-introduction to the keys. If nothing appears to happen, or if
-\code{\^P} is echoed, command line editing isn't available; you'll
-only be able to use backspace to remove characters from the current
-line.
-
-The interpreter operates somewhat like the \UNIX{} shell: when called
-with standard input connected to a tty device, it reads and executes
-commands interactively; when called with a file name argument or with
-a file as standard input, it reads and executes a \emph{script} from
-that file.
-
-A second way of starting the interpreter is
-\samp{\program{python} \programopt{-c} \var{command} [arg] ...}, which
-executes the statement(s) in \var{command}, analogous to the shell's
-\programopt{-c} option. Since Python statements often contain spaces
-or other characters that are special to the shell, it is best to quote
-\var{command} in its entirety with double quotes.
-
-Some Python modules are also useful as scripts. These can be invoked using
-\samp{\program{python} \programopt{-m} \var{module} [arg] ...}, which
-executes the source file for \var{module} as if you had spelled out its
-full name on the command line.
-
-Note that there is a difference between \samp{python file} and
-\samp{python <file}. In the latter case, input requests from the
-program, such as calling \code{sys.stdin.read()}, are
-satisfied from \emph{file}. Since this file has already been read
-until the end by the parser before the program starts executing, the
-program will encounter end-of-file immediately. In the former case
-(which is usually what you want) they are satisfied from whatever file
-or device is connected to standard input of the Python interpreter.
-
-When a script file is used, it is sometimes useful to be able to run
-the script and enter interactive mode afterwards. This can be done by
-passing \programopt{-i} before the script. (This does not work if the
-script is read from standard input, for the same reason as explained
-in the previous paragraph.)
-
-\subsection{Argument Passing \label{argPassing}}
-
-When known to the interpreter, the script name and additional
-arguments thereafter are passed to the script in the variable
-\code{sys.argv}, which is a list of strings. Its length is at least
-one; when no script and no arguments are given, \code{sys.argv[0]} is
-an empty string. When the script name is given as \code{'-'} (meaning
-standard input), \code{sys.argv[0]} is set to \code{'-'}. When
-\programopt{-c} \var{command} is used, \code{sys.argv[0]} is set to
-\code{'-c'}. When \programopt{-m} \var{module} is used, \code{sys.argv[0]}
-is set to the full name of the located module. Options found after
-\programopt{-c} \var{command} or \programopt{-m} \var{module} are not consumed
-by the Python interpreter's option processing but left in \code{sys.argv} for
-the command or module to handle.
-
-\subsection{Interactive Mode \label{interactive}}
-
-When commands are read from a tty, the interpreter is said to be in
-\emph{interactive mode}. In this mode it prompts for the next command
-with the \emph{primary prompt}, usually three greater-than signs
-(\samp{>>>~}); for continuation lines it prompts with the
-\emph{secondary prompt}, by default three dots (\samp{...~}).
-The interpreter prints a welcome message stating its version number
-and a copyright notice before printing the first prompt:
-
-\begin{verbatim}
-python
-Python 1.5.2b2 (#1, Feb 28 1999, 00:02:06) [GCC 2.8.1] on sunos5
-Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
->>>
-\end{verbatim}
-
-Continuation lines are needed when entering a multi-line construct.
-As an example, take a look at this \keyword{if} statement:
-
-\begin{verbatim}
->>> the_world_is_flat = 1
->>> if the_world_is_flat:
-... print "Be careful not to fall off!"
-...
-Be careful not to fall off!
-\end{verbatim}
-
-
-\section{The Interpreter and Its Environment \label{interp}}
-
-\subsection{Error Handling \label{error}}
-
-When an error occurs, the interpreter prints an error
-message and a stack trace. In interactive mode, it then returns to
-the primary prompt; when input came from a file, it exits with a
-nonzero exit status after printing
-the stack trace. (Exceptions handled by an \keyword{except} clause in a
-\keyword{try} statement are not errors in this context.) Some errors are
-unconditionally fatal and cause an exit with a nonzero exit; this
-applies to internal inconsistencies and some cases of running out of
-memory. All error messages are written to the standard error stream;
-normal output from executed commands is written to standard
-output.
-
-Typing the interrupt character (usually Control-C or DEL) to the
-primary or secondary prompt cancels the input and returns to the
-primary prompt.\footnote{
- A problem with the GNU Readline package may prevent this.
-}
-Typing an interrupt while a command is executing raises the
-\exception{KeyboardInterrupt} exception, which may be handled by a
-\keyword{try} statement.
-
-\subsection{Executable Python Scripts \label{scripts}}
-
-On BSD'ish \UNIX{} systems, Python scripts can be made directly
-executable, like shell scripts, by putting the line
-
-\begin{verbatim}
-#! /usr/bin/env python
-\end{verbatim}
-
-(assuming that the interpreter is on the user's \envvar{PATH}) at the
-beginning of the script and giving the file an executable mode. The
-\samp{\#!} must be the first two characters of the file. On some
-platforms, this first line must end with a \UNIX-style line ending
-(\character{\e n}), not a Mac OS (\character{\e r}) or Windows
-(\character{\e r\e n}) line ending. Note that
-the hash, or pound, character, \character{\#}, is used to start a
-comment in Python.
-
-The script can be given an executable mode, or permission, using the
-\program{chmod} command:
-
-\begin{verbatim}
-$ chmod +x myscript.py
-\end{verbatim} % $ <-- bow to font-lock
-
-
-\subsection{Source Code Encoding}
-
-It is possible to use encodings different than \ASCII{} in Python source
-files. The best way to do it is to put one more special comment line
-right after the \code{\#!} line to define the source file encoding:
-
-\begin{alltt}
-# -*- coding: \var{encoding} -*-
-\end{alltt}
-
-With that declaration, all characters in the source file will be treated as
-having the encoding \var{encoding}, and it will be
-possible to directly write Unicode string literals in the selected
-encoding. The list of possible encodings can be found in the
-\citetitle[../lib/lib.html]{Python Library Reference}, in the section
-on \ulink{\module{codecs}}{../lib/module-codecs.html}.
-
-For example, to write Unicode literals including the Euro currency
-symbol, the ISO-8859-15 encoding can be used, with the Euro symbol
-having the ordinal value 164. This script will print the value 8364
-(the Unicode codepoint corresponding to the Euro symbol) and then
-exit:
-
-\begin{alltt}
-# -*- coding: iso-8859-15 -*-
-
-currency = u"\texteuro"
-print ord(currency)
-\end{alltt}
-
-If your editor supports saving files as \code{UTF-8} with a UTF-8
-\emph{byte order mark} (aka BOM), you can use that instead of an
-encoding declaration. IDLE supports this capability if
-\code{Options/General/Default Source Encoding/UTF-8} is set. Notice
-that this signature is not understood in older Python releases (2.2
-and earlier), and also not understood by the operating system for
-script files with \code{\#!} lines (only used on \UNIX{} systems).
-
-By using UTF-8 (either through the signature or an encoding
-declaration), characters of most languages in the world can be used
-simultaneously in string literals and comments. Using non-\ASCII{}
-characters in identifiers is not supported. To display all these
-characters properly, your editor must recognize that the file is
-UTF-8, and it must use a font that supports all the characters in the
-file.
-
-\subsection{The Interactive Startup File \label{startup}}
-
-% XXX This should probably be dumped in an appendix, since most people
-% don't use Python interactively in non-trivial ways.
-
-When you use Python interactively, it is frequently handy to have some
-standard commands executed every time the interpreter is started. You
-can do this by setting an environment variable named
-\envvar{PYTHONSTARTUP} to the name of a file containing your start-up
-commands. This is similar to the \file{.profile} feature of the
-\UNIX{} shells.
-
-This file is only read in interactive sessions, not when Python reads
-commands from a script, and not when \file{/dev/tty} is given as the
-explicit source of commands (which otherwise behaves like an
-interactive session). It is executed in the same namespace where
-interactive commands are executed, so that objects that it defines or
-imports can be used without qualification in the interactive session.
-You can also change the prompts \code{sys.ps1} and \code{sys.ps2} in
-this file.
-
-If you want to read an additional start-up file from the current
-directory, you can program this in the global start-up file using code
-like \samp{if os.path.isfile('.pythonrc.py'):
-exec(open('.pythonrc.py')).read()}. If you want to use the startup file in a
-script, you must do this explicitly in the script:
-
-\begin{verbatim}
-import os
-filename = os.environ.get('PYTHONSTARTUP')
-if filename and os.path.isfile(filename):
- exec(open(filename).read())
-\end{verbatim}
-
-
-\chapter{An Informal Introduction to Python \label{informal}}
-
-In the following examples, input and output are distinguished by the
-presence or absence of prompts (\samp{>>>~} and \samp{...~}): to repeat
-the example, you must type everything after the prompt, when the
-prompt appears; lines that do not begin with a prompt are output from
-the interpreter. %
-%\footnote{
-% I'd prefer to use different fonts to distinguish input
-% from output, but the amount of LaTeX hacking that would require
-% is currently beyond my ability.
-%}
-Note that a secondary prompt on a line by itself in an example means
-you must type a blank line; this is used to end a multi-line command.
-
-Many of the examples in this manual, even those entered at the
-interactive prompt, include comments. Comments in Python start with
-the hash character, \character{\#}, and extend to the end of the
-physical line. A comment may appear at the start of a line or
-following whitespace or code, but not within a string literal. A hash
-character within a string literal is just a hash character.
-
-Some examples:
-
-\begin{verbatim}
-# this is the first comment
-SPAM = 1 # and this is the second comment
- # ... and now a third!
-STRING = "# This is not a comment."
-\end{verbatim}
-
-
-\section{Using Python as a Calculator \label{calculator}}
-
-Let's try some simple Python commands. Start the interpreter and wait
-for the primary prompt, \samp{>>>~}. (It shouldn't take long.)
-
-\subsection{Numbers \label{numbers}}
-
-The interpreter acts as a simple calculator: you can type an
-expression at it and it will write the value. Expression syntax is
-straightforward: the operators \code{+}, \code{-}, \code{*} and
-\code{/} work just like in most other languages (for example, Pascal
-or C); parentheses can be used for grouping. For example:
-
-\begin{verbatim}
->>> 2+2
-4
->>> # This is a comment
-... 2+2
-4
->>> 2+2 # and a comment on the same line as code
-4
->>> (50-5*6)/4
-5
->>> # Integer division returns the floor:
-... 7/3
-2
->>> 7/-3
--3
-\end{verbatim}
-
-The equal sign (\character{=}) is used to assign a value to a variable.
-Afterwards, no result is displayed before the next interactive prompt:
-
-\begin{verbatim}
->>> width = 20
->>> height = 5*9
->>> width * height
-900
-\end{verbatim}
-
-A value can be assigned to several variables simultaneously:
-
-\begin{verbatim}
->>> x = y = z = 0 # Zero x, y and z
->>> x
-0
->>> y
-0
->>> z
-0
-\end{verbatim}
-
-There is full support for floating point; operators with mixed type
-operands convert the integer operand to floating point:
-
-\begin{verbatim}
->>> 3 * 3.75 / 1.5
-7.5
->>> 7.0 / 2
-3.5
-\end{verbatim}
-
-Complex numbers are also supported; imaginary numbers are written with
-a suffix of \samp{j} or \samp{J}. Complex numbers with a nonzero
-real component are written as \samp{(\var{real}+\var{imag}j)}, or can
-be created with the \samp{complex(\var{real}, \var{imag})} function.
-
-\begin{verbatim}
->>> 1j * 1J
-(-1+0j)
->>> 1j * complex(0,1)
-(-1+0j)
->>> 3+1j*3
-(3+3j)
->>> (3+1j)*3
-(9+3j)
->>> (1+2j)/(1+1j)
-(1.5+0.5j)
-\end{verbatim}
-
-Complex numbers are always represented as two floating point numbers,
-the real and imaginary part. To extract these parts from a complex
-number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}.
-
-\begin{verbatim}
->>> a=1.5+0.5j
->>> a.real
-1.5
->>> a.imag
-0.5
-\end{verbatim}
-
-The conversion functions to floating point and integer
-(\function{float()}, \function{int()} and \function{long()}) don't
-work for complex numbers --- there is no one correct way to convert a
-complex number to a real number. Use \code{abs(\var{z})} to get its
-magnitude (as a float) or \code{z.real} to get its real part.
-
-\begin{verbatim}
->>> a=3.0+4.0j
->>> float(a)
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-TypeError: can't convert complex to float; use abs(z)
->>> a.real
-3.0
->>> a.imag
-4.0
->>> abs(a) # sqrt(a.real**2 + a.imag**2)
-5.0
->>>
-\end{verbatim}
-
-In interactive mode, the last printed expression is assigned to the
-variable \code{_}. This means that when you are using Python as a
-desk calculator, it is somewhat easier to continue calculations, for
-example:
-
-\begin{verbatim}
->>> tax = 12.5 / 100
->>> price = 100.50
->>> price * tax
-12.5625
->>> price + _
-113.0625
->>> round(_, 2)
-113.06
->>>
-\end{verbatim}
-
-This variable should be treated as read-only by the user. Don't
-explicitly assign a value to it --- you would create an independent
-local variable with the same name masking the built-in variable with
-its magic behavior.
-
-\subsection{Strings \label{strings}}
-
-Besides numbers, Python can also manipulate strings, which can be
-expressed in several ways. They can be enclosed in single quotes or
-double quotes:
-
-\begin{verbatim}
->>> 'spam eggs'
-'spam eggs'
->>> 'doesn\'t'
-"doesn't"
->>> "doesn't"
-"doesn't"
->>> '"Yes," he said.'
-'"Yes," he said.'
->>> "\"Yes,\" he said."
-'"Yes," he said.'
->>> '"Isn\'t," she said.'
-'"Isn\'t," she said.'
-\end{verbatim}
-
-String literals can span multiple lines in several ways. Continuation
-lines can be used, with a backslash as the last character on the line
-indicating that the next line is a logical continuation of the line:
-
-\begin{verbatim}
-hello = "This is a rather long string containing\n\
-several lines of text just as you would do in C.\n\
- Note that whitespace at the beginning of the line is\
- significant."
-
-print hello
-\end{verbatim}
-
-Note that newlines still need to be embedded in the string using
-\code{\e n}; the newline following the trailing backslash is
-discarded. This example would print the following:
-
-\begin{verbatim}
-This is a rather long string containing
-several lines of text just as you would do in C.
- Note that whitespace at the beginning of the line is significant.
-\end{verbatim}
-
-If we make the string literal a ``raw'' string, however, the
-\code{\e n} sequences are not converted to newlines, but the backslash
-at the end of the line, and the newline character in the source, are
-both included in the string as data. Thus, the example:
-
-\begin{verbatim}
-hello = r"This is a rather long string containing\n\
-several lines of text much as you would do in C."
-
-print hello
-\end{verbatim}
-
-would print:
-
-\begin{verbatim}
-This is a rather long string containing\n\
-several lines of text much as you would do in C.
-\end{verbatim}
-
-Or, strings can be surrounded in a pair of matching triple-quotes:
-\code{"""} or \code{'\code{'}'}. End of lines do not need to be escaped
-when using triple-quotes, but they will be included in the string.
-
-\begin{verbatim}
-print """
-Usage: thingy [OPTIONS]
- -h Display this usage message
- -H hostname Hostname to connect to
-"""
-\end{verbatim}
-
-produces the following output:
-
-\begin{verbatim}
-Usage: thingy [OPTIONS]
- -h Display this usage message
- -H hostname Hostname to connect to
-\end{verbatim}
-
-The interpreter prints the result of string operations in the same way
-as they are typed for input: inside quotes, and with quotes and other
-funny characters escaped by backslashes, to show the precise
-value. The string is enclosed in double quotes if the string contains
-a single quote and no double quotes, else it's enclosed in single
-quotes. (The \keyword{print} statement, described later, can be used
-to write strings without quotes or escapes.)
-
-Strings can be concatenated (glued together) with the
-\code{+} operator, and repeated with \code{*}:
-
-\begin{verbatim}
->>> word = 'Help' + 'A'
->>> word
-'HelpA'
->>> '<' + word*5 + '>'
-'<HelpAHelpAHelpAHelpAHelpA>'
-\end{verbatim}
-
-Two string literals next to each other are automatically concatenated;
-the first line above could also have been written \samp{word = 'Help'
-'A'}; this only works with two literals, not with arbitrary string
-expressions:
-
-\begin{verbatim}
->>> 'str' 'ing' # <- This is ok
-'string'
->>> 'str'.strip() + 'ing' # <- This is ok
-'string'
->>> 'str'.strip() 'ing' # <- This is invalid
- File "<stdin>", line 1, in ?
- 'str'.strip() 'ing'
- ^
-SyntaxError: invalid syntax
-\end{verbatim}
-
-Strings can be subscripted (indexed); like in C, the first character
-of a string has subscript (index) 0. There is no separate character
-type; a character is simply a string of size one. Like in Icon,
-substrings can be specified with the \emph{slice notation}: two indices
-separated by a colon.
-
-\begin{verbatim}
->>> word[4]
-'A'
->>> word[0:2]
-'He'
->>> word[2:4]
-'lp'
-\end{verbatim}
-
-Slice indices have useful defaults; an omitted first index defaults to
-zero, an omitted second index defaults to the size of the string being
-sliced.
-
-\begin{verbatim}
->>> word[:2] # The first two characters
-'He'
->>> word[2:] # Everything except the first two characters
-'lpA'
-\end{verbatim}
-
-Unlike a C string, Python strings cannot be changed. Assigning to an
-indexed position in the string results in an error:
-
-\begin{verbatim}
->>> word[0] = 'x'
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-TypeError: object doesn't support item assignment
->>> word[:1] = 'Splat'
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-TypeError: object doesn't support slice assignment
-\end{verbatim}
-
-However, creating a new string with the combined content is easy and
-efficient:
-
-\begin{verbatim}
->>> 'x' + word[1:]
-'xelpA'
->>> 'Splat' + word[4]
-'SplatA'
-\end{verbatim}
-
-Here's a useful invariant of slice operations:
-\code{s[:i] + s[i:]} equals \code{s}.
-
-\begin{verbatim}
->>> word[:2] + word[2:]
-'HelpA'
->>> word[:3] + word[3:]
-'HelpA'
-\end{verbatim}
-
-Degenerate slice indices are handled gracefully: an index that is too
-large is replaced by the string size, an upper bound smaller than the
-lower bound returns an empty string.
-
-\begin{verbatim}
->>> word[1:100]
-'elpA'
->>> word[10:]
-''
->>> word[2:1]
-''
-\end{verbatim}
-
-Indices may be negative numbers, to start counting from the right.
-For example:
-
-\begin{verbatim}
->>> word[-1] # The last character
-'A'
->>> word[-2] # The last-but-one character
-'p'
->>> word[-2:] # The last two characters
-'pA'
->>> word[:-2] # Everything except the last two characters
-'Hel'
-\end{verbatim}
-
-But note that -0 is really the same as 0, so it does not count from
-the right!
-
-\begin{verbatim}
->>> word[-0] # (since -0 equals 0)
-'H'
-\end{verbatim}
-
-Out-of-range negative slice indices are truncated, but don't try this
-for single-element (non-slice) indices:
-
-\begin{verbatim}
->>> word[-100:]
-'HelpA'
->>> word[-10] # error
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-IndexError: string index out of range
-\end{verbatim}
-
-One way to remember how slices work is to think of the indices as
-pointing \emph{between} characters, with the left edge of the first
-character numbered 0. Then the right edge of the last character of a
-string of \var{n} characters has index \var{n}, for example:
-
-\begin{verbatim}
- +---+---+---+---+---+
- | H | e | l | p | A |
- +---+---+---+---+---+
- 0 1 2 3 4 5
--5 -4 -3 -2 -1
-\end{verbatim}
-
-The first row of numbers gives the position of the indices 0...5 in
-the string; the second row gives the corresponding negative indices.
-The slice from \var{i} to \var{j} consists of all characters between
-the edges labeled \var{i} and \var{j}, respectively.
-
-For non-negative indices, the length of a slice is the difference of
-the indices, if both are within bounds. For example, the length of
-\code{word[1:3]} is 2.
-
-The built-in function \function{len()} returns the length of a string:
-
-\begin{verbatim}
->>> s = 'supercalifragilisticexpialidocious'
->>> len(s)
-34
-\end{verbatim}
-
-
-\begin{seealso}
- \seetitle[../lib/typesseq.html]{Sequence Types}%
- {Strings, and the Unicode strings described in the next
- section, are examples of \emph{sequence types}, and
- support the common operations supported by such types.}
- \seetitle[../lib/string-methods.html]{String Methods}%
- {Both strings and Unicode strings support a large number of
- methods for basic transformations and searching.}
- \seetitle[../lib/typesseq-strings.html]{String Formatting Operations}%
- {The formatting operations invoked when strings and Unicode
- strings are the left operand of the \code{\%} operator are
- described in more detail here.}
-\end{seealso}
-
-
-\subsection{Unicode Strings \label{unicodeStrings}}
-\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
-
-Starting with Python 2.0 a new data type for storing text data is
-available to the programmer: the Unicode object. It can be used to
-store and manipulate Unicode data (see \url{http://www.unicode.org/})
-and integrates well with the existing string objects, providing
-auto-conversions where necessary.
-
-Unicode has the advantage of providing one ordinal for every character
-in every script used in modern and ancient texts. Previously, there
-were only 256 possible ordinals for script characters. Texts were
-typically bound to a code page which mapped the ordinals to script
-characters. This lead to very much confusion especially with respect
-to internationalization (usually written as \samp{i18n} ---
-\character{i} + 18 characters + \character{n}) of software. Unicode
-solves these problems by defining one code page for all scripts.
-
-Creating Unicode strings in Python is just as simple as creating
-normal strings:
-
-\begin{verbatim}
->>> u'Hello World !'
-u'Hello World !'
-\end{verbatim}
-
-The small \character{u} in front of the quote indicates that a
-Unicode string is supposed to be created. If you want to include
-special characters in the string, you can do so by using the Python
-\emph{Unicode-Escape} encoding. The following example shows how:
-
-\begin{verbatim}
->>> u'Hello\u0020World !'
-u'Hello World !'
-\end{verbatim}
-
-The escape sequence \code{\e u0020} indicates to insert the Unicode
-character with the ordinal value 0x0020 (the space character) at the
-given position.
-
-Other characters are interpreted by using their respective ordinal
-values directly as Unicode ordinals. If you have literal strings
-in the standard Latin-1 encoding that is used in many Western countries,
-you will find it convenient that the lower 256 characters
-of Unicode are the same as the 256 characters of Latin-1.
-
-For experts, there is also a raw mode just like the one for normal
-strings. You have to prefix the opening quote with 'ur' to have
-Python use the \emph{Raw-Unicode-Escape} encoding. It will only apply
-the above \code{\e uXXXX} conversion if there is an uneven number of
-backslashes in front of the small 'u'.
-
-\begin{verbatim}
->>> ur'Hello\u0020World !'
-u'Hello World !'
->>> ur'Hello\\u0020World !'
-u'Hello\\\\u0020World !'
-\end{verbatim}
-
-The raw mode is most useful when you have to enter lots of
-backslashes, as can be necessary in regular expressions.
-
-Apart from these standard encodings, Python provides a whole set of
-other ways of creating Unicode strings on the basis of a known
-encoding.
-
-The built-in function \function{unicode()}\bifuncindex{unicode} provides
-access to all registered Unicode codecs (COders and DECoders). Some of
-the more well known encodings which these codecs can convert are
-\emph{Latin-1}, \emph{ASCII}, \emph{UTF-8}, and \emph{UTF-16}.
-The latter two are variable-length encodings that store each Unicode
-character in one or more bytes. The default encoding is
-normally set to \ASCII, which passes through characters in the range
-0 to 127 and rejects any other characters with an error.
-When a Unicode string is printed, written to a file, or converted
-with \function{str()}, conversion takes place using this default encoding.
-
-\begin{verbatim}
->>> u"abc"
-u'abc'
->>> str(u"abc")
-'abc'
->>> u"äöü"
-u'\xe4\xf6\xfc'
->>> str(u"äöü")
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-UnicodeEncodeError: 'ascii' codec can't encode characters in position 0-2: ordinal not in range(128)
-\end{verbatim}
-
-To convert a Unicode string into an 8-bit string using a specific
-encoding, Unicode objects provide an \function{encode()} method
-that takes one argument, the name of the encoding. Lowercase names
-for encodings are preferred.
-
-\begin{verbatim}
->>> u"äöü".encode('utf-8')
-'\xc3\xa4\xc3\xb6\xc3\xbc'
-\end{verbatim}
-
-If you have data in a specific encoding and want to produce a
-corresponding Unicode string from it, you can use the
-\function{unicode()} function with the encoding name as the second
-argument.
-
-\begin{verbatim}
->>> unicode('\xc3\xa4\xc3\xb6\xc3\xbc', 'utf-8')
-u'\xe4\xf6\xfc'
-\end{verbatim}
-
-\subsection{Lists \label{lists}}
-
-Python knows a number of \emph{compound} data types, used to group
-together other values. The most versatile is the \emph{list}, which
-can be written as a list of comma-separated values (items) between
-square brackets. List items need not all have the same type.
-
-\begin{verbatim}
->>> a = ['spam', 'eggs', 100, 1234]
->>> a
-['spam', 'eggs', 100, 1234]
-\end{verbatim}
-
-Like string indices, list indices start at 0, and lists can be sliced,
-concatenated and so on:
-
-\begin{verbatim}
->>> a[0]
-'spam'
->>> a[3]
-1234
->>> a[-2]
-100
->>> a[1:-1]
-['eggs', 100]
->>> a[:2] + ['bacon', 2*2]
-['spam', 'eggs', 'bacon', 4]
->>> 3*a[:3] + ['Boo!']
-['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boo!']
-\end{verbatim}
-
-Unlike strings, which are \emph{immutable}, it is possible to change
-individual elements of a list:
-
-\begin{verbatim}
->>> a
-['spam', 'eggs', 100, 1234]
->>> a[2] = a[2] + 23
->>> a
-['spam', 'eggs', 123, 1234]
-\end{verbatim}
-
-Assignment to slices is also possible, and this can even change the size
-of the list or clear it entirely:
-
-\begin{verbatim}
->>> # Replace some items:
-... a[0:2] = [1, 12]
->>> a
-[1, 12, 123, 1234]
->>> # Remove some:
-... a[0:2] = []
->>> a
-[123, 1234]
->>> # Insert some:
-... a[1:1] = ['bletch', 'xyzzy']
->>> a
-[123, 'bletch', 'xyzzy', 1234]
->>> # Insert (a copy of) itself at the beginning
->>> a[:0] = a
->>> a
-[123, 'bletch', 'xyzzy', 1234, 123, 'bletch', 'xyzzy', 1234]
->>> # Clear the list: replace all items with an empty list
->>> a[:] = []
->>> a
-[]
-\end{verbatim}
-
-The built-in function \function{len()} also applies to lists:
-
-\begin{verbatim}
->>> len(a)
-8
-\end{verbatim}
-
-It is possible to nest lists (create lists containing other lists),
-for example:
-
-\begin{verbatim}
->>> q = [2, 3]
->>> p = [1, q, 4]
->>> len(p)
-3
->>> p[1]
-[2, 3]
->>> p[1][0]
-2
->>> p[1].append('xtra') # See section 5.1
->>> p
-[1, [2, 3, 'xtra'], 4]
->>> q
-[2, 3, 'xtra']
-\end{verbatim}
-
-Note that in the last example, \code{p[1]} and \code{q} really refer to
-the same object! We'll come back to \emph{object semantics} later.
-
-\section{First Steps Towards Programming \label{firstSteps}}
-
-Of course, we can use Python for more complicated tasks than adding
-two and two together. For instance, we can write an initial
-sub-sequence of the \emph{Fibonacci} series as follows:
-
-\begin{verbatim}
->>> # Fibonacci series:
-... # the sum of two elements defines the next
-... a, b = 0, 1
->>> while b < 10:
-... print b
-... a, b = b, a+b
-...
-1
-1
-2
-3
-5
-8
-\end{verbatim}
-
-This example introduces several new features.
-
-\begin{itemize}
-
-\item
-The first line contains a \emph{multiple assignment}: the variables
-\code{a} and \code{b} simultaneously get the new values 0 and 1. On the
-last line this is used again, demonstrating that the expressions on
-the right-hand side are all evaluated first before any of the
-assignments take place. The right-hand side expressions are evaluated
-from the left to the right.
-
-\item
-The \keyword{while} loop executes as long as the condition (here:
-\code{b < 10}) remains true. In Python, like in C, any non-zero
-integer value is true; zero is false. The condition may also be a
-string or list value, in fact any sequence; anything with a non-zero
-length is true, empty sequences are false. The test used in the
-example is a simple comparison. The standard comparison operators are
-written the same as in C: \code{<} (less than), \code{>} (greater than),
-\code{==} (equal to), \code{<=} (less than or equal to),
-\code{>=} (greater than or equal to) and \code{!=} (not equal to).
-
-\item
-The \emph{body} of the loop is \emph{indented}: indentation is Python's
-way of grouping statements. Python does not (yet!) provide an
-intelligent input line editing facility, so you have to type a tab or
-space(s) for each indented line. In practice you will prepare more
-complicated input for Python with a text editor; most text editors have
-an auto-indent facility. When a compound statement is entered
-interactively, it must be followed by a blank line to indicate
-completion (since the parser cannot guess when you have typed the last
-line). Note that each line within a basic block must be indented by
-the same amount.
-
-\item
-The \keyword{print} statement writes the value of the expression(s) it is
-given. It differs from just writing the expression you want to write
-(as we did earlier in the calculator examples) in the way it handles
-multiple expressions and strings. Strings are printed without quotes,
-and a space is inserted between items, so you can format things nicely,
-like this:
-
-\begin{verbatim}
->>> i = 256*256
->>> print 'The value of i is', i
-The value of i is 65536
-\end{verbatim}
-
-A trailing comma avoids the newline after the output:
-
-\begin{verbatim}
->>> a, b = 0, 1
->>> while b < 1000:
-... print b,
-... a, b = b, a+b
-...
-1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
-\end{verbatim}
-
-Note that the interpreter inserts a newline before it prints the next
-prompt if the last line was not completed.
-
-\end{itemize}
-
-
-\chapter{More Control Flow Tools \label{moreControl}}
-
-Besides the \keyword{while} statement just introduced, Python knows
-the usual control flow statements known from other languages, with
-some twists.
-
-\section{\keyword{if} Statements \label{if}}
-
-Perhaps the most well-known statement type is the
-\keyword{if} statement. For example:
-
-\begin{verbatim}
->>> def raw_input(prompt):
-... import sys
-... sys.stdout.write(prompt)
-... sys.stdout.flush()
-... return sys.stdin.readline()
-...
->>> x = int(raw_input("Please enter an integer: "))
->>> if x < 0:
-... x = 0
-... print 'Negative changed to zero'
-... elif x == 0:
-... print 'Zero'
-... elif x == 1:
-... print 'Single'
-... else:
-... print 'More'
-...
-\end{verbatim}
-
-There can be zero or more \keyword{elif} parts, and the
-\keyword{else} part is optional. The keyword `\keyword{elif}' is
-short for `else if', and is useful to avoid excessive indentation. An
-\keyword{if} \ldots\ \keyword{elif} \ldots\ \keyword{elif} \ldots\ sequence
-% Weird spacings happen here if the wrapping of the source text
-% gets changed in the wrong way.
-is a substitute for the \keyword{switch} or
-\keyword{case} statements found in other languages.
-
-
-\section{\keyword{for} Statements \label{for}}
-
-The \keyword{for}\stindex{for} statement in Python differs a bit from
-what you may be used to in C or Pascal. Rather than always
-iterating over an arithmetic progression of numbers (like in Pascal),
-or giving the user the ability to define both the iteration step and
-halting condition (as C), Python's
-\keyword{for}\stindex{for} statement iterates over the items of any
-sequence (a list or a string), in the order that they appear in
-the sequence. For example (no pun intended):
-% One suggestion was to give a real C example here, but that may only
-% serve to confuse non-C programmers.
-
-\begin{verbatim}
->>> # Measure some strings:
-... a = ['cat', 'window', 'defenestrate']
->>> for x in a:
-... print x, len(x)
-...
-cat 3
-window 6
-defenestrate 12
-\end{verbatim}
-
-It is not safe to modify the sequence being iterated over in the loop
-(this can only happen for mutable sequence types, such as lists). If
-you need to modify the list you are iterating over (for example, to
-duplicate selected items) you must iterate over a copy. The slice
-notation makes this particularly convenient:
-
-\begin{verbatim}
->>> for x in a[:]: # make a slice copy of the entire list
-... if len(x) > 6: a.insert(0, x)
-...
->>> a
-['defenestrate', 'cat', 'window', 'defenestrate']
-\end{verbatim}
-
-
-\section{The \function{range()} Function \label{range}}
-
-If you do need to iterate over a sequence of numbers, the built-in
-function \function{range()} comes in handy. It generates lists
-containing arithmetic progressions:
-
-\begin{verbatim}
->>> range(10)
-[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
-\end{verbatim}
-
-The given end point is never part of the generated list;
-\code{range(10)} generates a list of 10 values, the legal
-indices for items of a sequence of length 10. It is possible to let
-the range start at another number, or to specify a different increment
-(even negative; sometimes this is called the `step'):
-
-\begin{verbatim}
->>> range(5, 10)
-[5, 6, 7, 8, 9]
->>> range(0, 10, 3)
-[0, 3, 6, 9]
->>> range(-10, -100, -30)
-[-10, -40, -70]
-\end{verbatim}
-
-To iterate over the indices of a sequence, combine
-\function{range()} and \function{len()} as follows:
-
-\begin{verbatim}
->>> a = ['Mary', 'had', 'a', 'little', 'lamb']
->>> for i in range(len(a)):
-... print i, a[i]
-...
-0 Mary
-1 had
-2 a
-3 little
-4 lamb
-\end{verbatim}
-
-
-\section{\keyword{break} and \keyword{continue} Statements, and
- \keyword{else} Clauses on Loops
- \label{break}}
-
-The \keyword{break} statement, like in C, breaks out of the smallest
-enclosing \keyword{for} or \keyword{while} loop.
-
-The \keyword{continue} statement, also borrowed from C, continues
-with the next iteration of the loop.
-
-Loop statements may have an \code{else} clause; it is executed when
-the loop terminates through exhaustion of the list (with
-\keyword{for}) or when the condition becomes false (with
-\keyword{while}), but not when the loop is terminated by a
-\keyword{break} statement. This is exemplified by the following loop,
-which searches for prime numbers:
-
-\begin{verbatim}
->>> for n in range(2, 10):
-... for x in range(2, n):
-... if n % x == 0:
-... print n, 'equals', x, '*', n/x
-... break
-... else:
-... # loop fell through without finding a factor
-... print n, 'is a prime number'
-...
-2 is a prime number
-3 is a prime number
-4 equals 2 * 2
-5 is a prime number
-6 equals 2 * 3
-7 is a prime number
-8 equals 2 * 4
-9 equals 3 * 3
-\end{verbatim}
-
-
-\section{\keyword{pass} Statements \label{pass}}
-
-The \keyword{pass} statement does nothing.
-It can be used when a statement is required syntactically but the
-program requires no action.
-For example:
-
-\begin{verbatim}
->>> while True:
-... pass # Busy-wait for keyboard interrupt
-...
-\end{verbatim}
-
-
-\section{Defining Functions \label{functions}}
-
-We can create a function that writes the Fibonacci series to an
-arbitrary boundary:
-
-\begin{verbatim}
->>> def fib(n): # write Fibonacci series up to n
-... """Print a Fibonacci series up to n."""
-... a, b = 0, 1
-... while b < n:
-... print b,
-... a, b = b, a+b
-...
->>> # Now call the function we just defined:
-... fib(2000)
-1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
-\end{verbatim}
-
-The keyword \keyword{def} introduces a function \emph{definition}. It
-must be followed by the function name and the parenthesized list of
-formal parameters. The statements that form the body of the function
-start at the next line, and must be indented. The first statement of
-the function body can optionally be a string literal; this string
-literal is the function's \index{documentation strings}documentation
-string, or \dfn{docstring}.\index{docstrings}\index{strings, documentation}
-
-There are tools which use docstrings to automatically produce online
-or printed documentation, or to let the user interactively browse
-through code; it's good practice to include docstrings in code that
-you write, so try to make a habit of it.
-
-The \emph{execution} of a function introduces a new symbol table used
-for the local variables of the function. More precisely, all variable
-assignments in a function store the value in the local symbol table;
-whereas variable references first look in the local symbol table, then
-in the global symbol table, and then in the table of built-in names.
-Thus, global variables cannot be directly assigned a value within a
-function (unless named in a \keyword{global} statement), although
-they may be referenced.
-
-The actual parameters (arguments) to a function call are introduced in
-the local symbol table of the called function when it is called; thus,
-arguments are passed using \emph{call by value} (where the
-\emph{value} is always an object \emph{reference}, not the value of
-the object).\footnote{
- Actually, \emph{call by object reference} would be a better
- description, since if a mutable object is passed, the caller
- will see any changes the callee makes to it (items
- inserted into a list).
-} When a function calls another function, a new local symbol table is
-created for that call.
-
-A function definition introduces the function name in the current
-symbol table. The value of the function name
-has a type that is recognized by the interpreter as a user-defined
-function. This value can be assigned to another name which can then
-also be used as a function. This serves as a general renaming
-mechanism:
-
-\begin{verbatim}
->>> fib
-<function fib at 10042ed0>
->>> f = fib
->>> f(100)
-1 1 2 3 5 8 13 21 34 55 89
-\end{verbatim}
-
-You might object that \code{fib} is not a function but a procedure. In
-Python, like in C, procedures are just functions that don't return a
-value. In fact, technically speaking, procedures do return a value,
-albeit a rather boring one. This value is called \code{None} (it's a
-built-in name). Writing the value \code{None} is normally suppressed by
-the interpreter if it would be the only value written. You can see it
-if you really want to:
-
-\begin{verbatim}
->>> print fib(0)
-None
-\end{verbatim}
-
-It is simple to write a function that returns a list of the numbers of
-the Fibonacci series, instead of printing it:
-
-\begin{verbatim}
->>> def fib2(n): # return Fibonacci series up to n
-... """Return a list containing the Fibonacci series up to n."""
-... result = []
-... a, b = 0, 1
-... while b < n:
-... result.append(b) # see below
-... a, b = b, a+b
-... return result
-...
->>> f100 = fib2(100) # call it
->>> f100 # write the result
-[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
-\end{verbatim}
-
-This example, as usual, demonstrates some new Python features:
-
-\begin{itemize}
-
-\item
-The \keyword{return} statement returns with a value from a function.
-\keyword{return} without an expression argument returns \code{None}.
-Falling off the end of a procedure also returns \code{None}.
-
-\item
-The statement \code{result.append(b)} calls a \emph{method} of the list
-object \code{result}. A method is a function that `belongs' to an
-object and is named \code{obj.methodname}, where \code{obj} is some
-object (this may be an expression), and \code{methodname} is the name
-of a method that is defined by the object's type. Different types
-define different methods. Methods of different types may have the
-same name without causing ambiguity. (It is possible to define your
-own object types and methods, using \emph{classes}, as discussed later
-in this tutorial.)
-The method \method{append()} shown in the example is defined for
-list objects; it adds a new element at the end of the list. In this
-example it is equivalent to \samp{result = result + [b]}, but more
-efficient.
-
-\end{itemize}
-
-\section{More on Defining Functions \label{defining}}
-
-It is also possible to define functions with a variable number of
-arguments. There are three forms, which can be combined.
-
-\subsection{Default Argument Values \label{defaultArgs}}
-
-The most useful form is to specify a default value for one or more
-arguments. This creates a function that can be called with fewer
-arguments than it is defined to allow. For example:
-
-\begin{verbatim}
-def raw_input(prompt):
- import sys
- sys.stdout.write(prompt)
- sys.stdout.flush()
- return sys.stdin.readline()
-
-def ask_ok(prompt, retries=4, complaint='Yes or no, please!'):
- while True:
- ok = raw_input(prompt)
- if ok in ('y', 'ye', 'yes'): return True
- if ok in ('n', 'no', 'nop', 'nope'): return False
- retries = retries - 1
- if retries < 0: raise IOError, 'refusenik user'
- print complaint
-\end{verbatim}
-
-This function can be called either like this:
-\code{ask_ok('Do you really want to quit?')} or like this:
-\code{ask_ok('OK to overwrite the file?', 2)}.
-
-This example also introduces the \keyword{in} keyword. This tests
-whether or not a sequence contains a certain value.
-
-The default values are evaluated at the point of function definition
-in the \emph{defining} scope, so that
-
-\begin{verbatim}
-i = 5
-
-def f(arg=i):
- print arg
-
-i = 6
-f()
-\end{verbatim}
-
-will print \code{5}.
-
-\strong{Important warning:} The default value is evaluated only once.
-This makes a difference when the default is a mutable object such as a
-list, dictionary, or instances of most classes. For example, the
-following function accumulates the arguments passed to it on
-subsequent calls:
-
-\begin{verbatim}
-def f(a, L=[]):
- L.append(a)
- return L
-
-print f(1)
-print f(2)
-print f(3)
-\end{verbatim}
-
-This will print
-
-\begin{verbatim}
-[1]
-[1, 2]
-[1, 2, 3]
-\end{verbatim}
-
-If you don't want the default to be shared between subsequent calls,
-you can write the function like this instead:
-
-\begin{verbatim}
-def f(a, L=None):
- if L is None:
- L = []
- L.append(a)
- return L
-\end{verbatim}
-
-\subsection{Keyword Arguments \label{keywordArgs}}
-
-Functions can also be called using
-keyword arguments of the form \samp{\var{keyword} = \var{value}}. For
-instance, the following function:
-
-\begin{verbatim}
-def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
- print "-- This parrot wouldn't", action,
- print "if you put", voltage, "volts through it."
- print "-- Lovely plumage, the", type
- print "-- It's", state, "!"
-\end{verbatim}
-
-could be called in any of the following ways:
-
-\begin{verbatim}
-parrot(1000)
-parrot(action = 'VOOOOOM', voltage = 1000000)
-parrot('a thousand', state = 'pushing up the daisies')
-parrot('a million', 'bereft of life', 'jump')
-\end{verbatim}
-
-but the following calls would all be invalid:
-
-\begin{verbatim}
-parrot() # required argument missing
-parrot(voltage=5.0, 'dead') # non-keyword argument following keyword
-parrot(110, voltage=220) # duplicate value for argument
-parrot(actor='John Cleese') # unknown keyword
-\end{verbatim}
-
-In general, an argument list must have any positional arguments
-followed by any keyword arguments, where the keywords must be chosen
-from the formal parameter names. It's not important whether a formal
-parameter has a default value or not. No argument may receive a
-value more than once --- formal parameter names corresponding to
-positional arguments cannot be used as keywords in the same calls.
-Here's an example that fails due to this restriction:
-
-\begin{verbatim}
->>> def function(a):
-... pass
-...
->>> function(0, a=0)
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-TypeError: function() got multiple values for keyword argument 'a'
-\end{verbatim}
-
-When a final formal parameter of the form \code{**\var{name}} is
-present, it receives a \ulink{dictionary}{../lib/typesmapping.html}
-containing all keyword arguments except for those corresponding to
-a formal parameter. This may be
-combined with a formal parameter of the form
-\code{*\var{name}} (described in the next subsection) which receives a
-tuple containing the positional arguments beyond the formal parameter
-list. (\code{*\var{name}} must occur before \code{**\var{name}}.)
-For example, if we define a function like this:
-
-\begin{verbatim}
-def cheeseshop(kind, *arguments, **keywords):
- print "-- Do you have any", kind, '?'
- print "-- I'm sorry, we're all out of", kind
- for arg in arguments: print arg
- print '-'*40
- keys = keywords.keys()
- keys.sort()
- for kw in keys: print kw, ':', keywords[kw]
-\end{verbatim}
-
-It could be called like this:
-
-\begin{verbatim}
-cheeseshop('Limburger', "It's very runny, sir.",
- "It's really very, VERY runny, sir.",
- client='John Cleese',
- shopkeeper='Michael Palin',
- sketch='Cheese Shop Sketch')
-\end{verbatim}
-
-and of course it would print:
-
-\begin{verbatim}
--- Do you have any Limburger ?
--- I'm sorry, we're all out of Limburger
-It's very runny, sir.
-It's really very, VERY runny, sir.
-----------------------------------------
-client : John Cleese
-shopkeeper : Michael Palin
-sketch : Cheese Shop Sketch
-\end{verbatim}
-
-Note that the \method{sort()} method of the list of keyword argument
-names is called before printing the contents of the \code{keywords}
-dictionary; if this is not done, the order in which the arguments are
-printed is undefined.
-
-
-\subsection{Arbitrary Argument Lists \label{arbitraryArgs}}
-
-Finally, the least frequently used option is to specify that a
-function can be called with an arbitrary number of arguments. These
-arguments will be wrapped up in a tuple. Before the variable number
-of arguments, zero or more normal arguments may occur.
-
-\begin{verbatim}
-def fprintf(file, format, *args):
- file.write(format % args)
-\end{verbatim}
-
-
-\subsection{Unpacking Argument Lists \label{unpacking-arguments}}
-
-The reverse situation occurs when the arguments are already in a list
-or tuple but need to be unpacked for a function call requiring separate
-positional arguments. For instance, the built-in \function{range()}
-function expects separate \var{start} and \var{stop} arguments. If they
-are not available separately, write the function call with the
-\code{*}-operator to unpack the arguments out of a list or tuple:
-
-\begin{verbatim}
->>> range(3, 6) # normal call with separate arguments
-[3, 4, 5]
->>> args = [3, 6]
->>> range(*args) # call with arguments unpacked from a list
-[3, 4, 5]
-\end{verbatim}
-
-In the same fashion, dictionaries can deliver keyword arguments with the
-\code{**}-operator:
-
-\begin{verbatim}
->>> def parrot(voltage, state='a stiff', action='voom'):
-... print "-- This parrot wouldn't", action,
-... print "if you put", voltage, "volts through it.",
-... print "E's", state, "!"
-...
->>> d = {"voltage": "four million", "state": "bleedin' demised", "action": "VOOM"}
->>> parrot(**d)
--- This parrot wouldn't VOOM if you put four million volts through it. E's bleedin' demised !
-\end{verbatim}
-
-
-\subsection{Lambda Forms \label{lambda}}
-
-By popular demand, a few features commonly found in functional
-programming languages like Lisp have been added to Python. With the
-\keyword{lambda} keyword, small anonymous functions can be created.
-Here's a function that returns the sum of its two arguments:
-\samp{lambda a, b: a+b}. Lambda forms can be used wherever function
-objects are required. They are syntactically restricted to a single
-expression. Semantically, they are just syntactic sugar for a normal
-function definition. Like nested function definitions, lambda forms
-can reference variables from the containing scope:
-
-\begin{verbatim}
->>> def make_incrementor(n):
-... return lambda x: x + n
-...
->>> f = make_incrementor(42)
->>> f(0)
-42
->>> f(1)
-43
-\end{verbatim}
-
-
-\subsection{Documentation Strings \label{docstrings}}
-
-There are emerging conventions about the content and formatting of
-documentation strings.
-\index{docstrings}\index{documentation strings}
-\index{strings, documentation}
-
-The first line should always be a short, concise summary of the
-object's purpose. For brevity, it should not explicitly state the
-object's name or type, since these are available by other means
-(except if the name happens to be a verb describing a function's
-operation). This line should begin with a capital letter and end with
-a period.
-
-If there are more lines in the documentation string, the second line
-should be blank, visually separating the summary from the rest of the
-description. The following lines should be one or more paragraphs
-describing the object's calling conventions, its side effects, etc.
-
-The Python parser does not strip indentation from multi-line string
-literals in Python, so tools that process documentation have to strip
-indentation if desired. This is done using the following convention.
-The first non-blank line \emph{after} the first line of the string
-determines the amount of indentation for the entire documentation
-string. (We can't use the first line since it is generally adjacent
-to the string's opening quotes so its indentation is not apparent in
-the string literal.) Whitespace ``equivalent'' to this indentation is
-then stripped from the start of all lines of the string. Lines that
-are indented less should not occur, but if they occur all their
-leading whitespace should be stripped. Equivalence of whitespace
-should be tested after expansion of tabs (to 8 spaces, normally).
-
-Here is an example of a multi-line docstring:
-
-\begin{verbatim}
->>> def my_function():
-... """Do nothing, but document it.
-...
-... No, really, it doesn't do anything.
-... """
-... pass
-...
->>> print my_function.__doc__
-Do nothing, but document it.
-
- No, really, it doesn't do anything.
-
-\end{verbatim}
-
-
-
-\chapter{Data Structures \label{structures}}
-
-This chapter describes some things you've learned about already in
-more detail, and adds some new things as well.
-
-
-\section{More on Lists \label{moreLists}}
-
-The list data type has some more methods. Here are all of the methods
-of list objects:
-
-\begin{methoddesc}[list]{append}{x}
-Add an item to the end of the list;
-equivalent to \code{a[len(a):] = [\var{x}]}.
-\end{methoddesc}
-
-\begin{methoddesc}[list]{extend}{L}
-Extend the list by appending all the items in the given list;
-equivalent to \code{a[len(a):] = \var{L}}.
-\end{methoddesc}
-
-\begin{methoddesc}[list]{insert}{i, x}
-Insert an item at a given position. The first argument is the index
-of the element before which to insert, so \code{a.insert(0, \var{x})}
-inserts at the front of the list, and \code{a.insert(len(a), \var{x})}
-is equivalent to \code{a.append(\var{x})}.
-\end{methoddesc}
-
-\begin{methoddesc}[list]{remove}{x}
-Remove the first item from the list whose value is \var{x}.
-It is an error if there is no such item.
-\end{methoddesc}
-
-\begin{methoddesc}[list]{pop}{\optional{i}}
-Remove the item at the given position in the list, and return it. If
-no index is specified, \code{a.pop()} removes and returns the last item
-in the list. (The square brackets
-around the \var{i} in the method signature denote that the parameter
-is optional, not that you should type square brackets at that
-position. You will see this notation frequently in the
-\citetitle[../lib/lib.html]{Python Library Reference}.)
-\end{methoddesc}
-
-\begin{methoddesc}[list]{index}{x}
-Return the index in the list of the first item whose value is \var{x}.
-It is an error if there is no such item.
-\end{methoddesc}
-
-\begin{methoddesc}[list]{count}{x}
-Return the number of times \var{x} appears in the list.
-\end{methoddesc}
-
-\begin{methoddesc}[list]{sort}{}
-Sort the items of the list, in place.
-\end{methoddesc}
-
-\begin{methoddesc}[list]{reverse}{}
-Reverse the elements of the list, in place.
-\end{methoddesc}
-
-An example that uses most of the list methods:
-
-\begin{verbatim}
->>> a = [66.25, 333, 333, 1, 1234.5]
->>> print a.count(333), a.count(66.25), a.count('x')
-2 1 0
->>> a.insert(2, -1)
->>> a.append(333)
->>> a
-[66.25, 333, -1, 333, 1, 1234.5, 333]
->>> a.index(333)
-1
->>> a.remove(333)
->>> a
-[66.25, -1, 333, 1, 1234.5, 333]
->>> a.reverse()
->>> a
-[333, 1234.5, 1, 333, -1, 66.25]
->>> a.sort()
->>> a
-[-1, 1, 66.25, 333, 333, 1234.5]
-\end{verbatim}
-
-
-\subsection{Using Lists as Stacks \label{lists-as-stacks}}
-\sectionauthor{Ka-Ping Yee}{ping@lfw.org}
-
-The list methods make it very easy to use a list as a stack, where the
-last element added is the first element retrieved (``last-in,
-first-out''). To add an item to the top of the stack, use
-\method{append()}. To retrieve an item from the top of the stack, use
-\method{pop()} without an explicit index. For example:
-
-\begin{verbatim}
->>> stack = [3, 4, 5]
->>> stack.append(6)
->>> stack.append(7)
->>> stack
-[3, 4, 5, 6, 7]
->>> stack.pop()
-7
->>> stack
-[3, 4, 5, 6]
->>> stack.pop()
-6
->>> stack.pop()
-5
->>> stack
-[3, 4]
-\end{verbatim}
-
-
-\subsection{Using Lists as Queues \label{lists-as-queues}}
-\sectionauthor{Ka-Ping Yee}{ping@lfw.org}
-
-You can also use a list conveniently as a queue, where the first
-element added is the first element retrieved (``first-in,
-first-out''). To add an item to the back of the queue, use
-\method{append()}. To retrieve an item from the front of the queue,
-use \method{pop()} with \code{0} as the index. For example:
-
-\begin{verbatim}
->>> queue = ["Eric", "John", "Michael"]
->>> queue.append("Terry") # Terry arrives
->>> queue.append("Graham") # Graham arrives
->>> queue.pop(0)
-'Eric'
->>> queue.pop(0)
-'John'
->>> queue
-['Michael', 'Terry', 'Graham']
-\end{verbatim}
-
-
-\subsection{Functional Programming Tools \label{functional}}
-
-There are two built-in functions that are very useful when used with
-lists: \function{filter()} and \function{map()}.
-
-\samp{filter(\var{function}, \var{sequence})} returns a sequence
-consisting of those items from the
-sequence for which \code{\var{function}(\var{item})} is true.
-If \var{sequence} is a \class{string} or \class{tuple}, the result will
-be of the same type; otherwise, it is always a \class{list}.
-For example, to compute some primes:
-
-\begin{verbatim}
->>> def f(x): return x % 2 != 0 and x % 3 != 0
-...
->>> filter(f, range(2, 25))
-[5, 7, 11, 13, 17, 19, 23]
-\end{verbatim}
-
-\samp{map(\var{function}, \var{sequence})} calls
-\code{\var{function}(\var{item})} for each of the sequence's items and
-returns a list of the return values. For example, to compute some
-cubes:
-
-\begin{verbatim}
->>> def cube(x): return x*x*x
-...
->>> map(cube, range(1, 11))
-[1, 8, 27, 64, 125, 216, 343, 512, 729, 1000]
-\end{verbatim}
-
-More than one sequence may be passed; the function must then have as
-many arguments as there are sequences and is called with the
-corresponding item from each sequence (or \code{None} if some sequence
-is shorter than another). For example:
-
-\begin{verbatim}
->>> seq = range(8)
->>> def add(x, y): return x+y
-...
->>> map(add, seq, seq)
-[0, 2, 4, 6, 8, 10, 12, 14]
-\end{verbatim}
-\versionadded{2.3}
-
-\subsection{List Comprehensions}
-
-List comprehensions provide a concise way to create lists without resorting
-to use of \function{map()}, \function{filter()} and/or \keyword{lambda}.
-The resulting list definition tends often to be clearer than lists built
-using those constructs. Each list comprehension consists of an expression
-followed by a \keyword{for} clause, then zero or more \keyword{for} or
-\keyword{if} clauses. The result will be a list resulting from evaluating
-the expression in the context of the \keyword{for} and \keyword{if} clauses
-which follow it. If the expression would evaluate to a tuple, it must be
-parenthesized.
-
-\begin{verbatim}
->>> freshfruit = [' banana', ' loganberry ', 'passion fruit ']
->>> [weapon.strip() for weapon in freshfruit]
-['banana', 'loganberry', 'passion fruit']
->>> vec = [2, 4, 6]
->>> [3*x for x in vec]
-[6, 12, 18]
->>> [3*x for x in vec if x > 3]
-[12, 18]
->>> [3*x for x in vec if x < 2]
-[]
->>> [[x,x**2] for x in vec]
-[[2, 4], [4, 16], [6, 36]]
->>> [x, x**2 for x in vec] # error - parens required for tuples
- File "<stdin>", line 1, in ?
- [x, x**2 for x in vec]
- ^
-SyntaxError: invalid syntax
->>> [(x, x**2) for x in vec]
-[(2, 4), (4, 16), (6, 36)]
->>> vec1 = [2, 4, 6]
->>> vec2 = [4, 3, -9]
->>> [x*y for x in vec1 for y in vec2]
-[8, 6, -18, 16, 12, -36, 24, 18, -54]
->>> [x+y for x in vec1 for y in vec2]
-[6, 5, -7, 8, 7, -5, 10, 9, -3]
->>> [vec1[i]*vec2[i] for i in range(len(vec1))]
-[8, 12, -54]
-\end{verbatim}
-
-List comprehensions are much more flexible than \function{map()} and can be
-applied to complex expressions and nested functions:
-
-\begin{verbatim}
->>> [str(round(355/113.0, i)) for i in range(1,6)]
-['3.1', '3.14', '3.142', '3.1416', '3.14159']
-\end{verbatim}
-
-
-\section{The \keyword{del} statement \label{del}}
-
-There is a way to remove an item from a list given its index instead
-of its value: the \keyword{del} statement. This differs from the
-\method{pop()} method which returns a value. The \keyword{del}
-statement can also be used to remove slices from a list or clear the
-entire list (which we did earlier by assignment of an empty list to
-the slice). For example:
-
-\begin{verbatim}
->>> a = [-1, 1, 66.25, 333, 333, 1234.5]
->>> del a[0]
->>> a
-[1, 66.25, 333, 333, 1234.5]
->>> del a[2:4]
->>> a
-[1, 66.25, 1234.5]
->>> del a[:]
->>> a
-[]
-\end{verbatim}
-
-\keyword{del} can also be used to delete entire variables:
-
-\begin{verbatim}
->>> del a
-\end{verbatim}
-
-Referencing the name \code{a} hereafter is an error (at least until
-another value is assigned to it). We'll find other uses for
-\keyword{del} later.
-
-
-\section{Tuples and Sequences \label{tuples}}
-
-We saw that lists and strings have many common properties, such as
-indexing and slicing operations. They are two examples of
-\ulink{\emph{sequence} data types}{../lib/typesseq.html}. Since
-Python is an evolving language, other sequence data types may be
-added. There is also another standard sequence data type: the
-\emph{tuple}.
-
-A tuple consists of a number of values separated by commas, for
-instance:
-
-\begin{verbatim}
->>> t = 12345, 54321, 'hello!'
->>> t[0]
-12345
->>> t
-(12345, 54321, 'hello!')
->>> # Tuples may be nested:
-... u = t, (1, 2, 3, 4, 5)
->>> u
-((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
-\end{verbatim}
-
-As you see, on output tuples are always enclosed in parentheses, so
-that nested tuples are interpreted correctly; they may be input with
-or without surrounding parentheses, although often parentheses are
-necessary anyway (if the tuple is part of a larger expression).
-
-Tuples have many uses. For example: (x, y) coordinate pairs, employee
-records from a database, etc. Tuples, like strings, are immutable: it
-is not possible to assign to the individual items of a tuple (you can
-simulate much of the same effect with slicing and concatenation,
-though). It is also possible to create tuples which contain mutable
-objects, such as lists.
-
-A special problem is the construction of tuples containing 0 or 1
-items: the syntax has some extra quirks to accommodate these. Empty
-tuples are constructed by an empty pair of parentheses; a tuple with
-one item is constructed by following a value with a comma
-(it is not sufficient to enclose a single value in parentheses).
-Ugly, but effective. For example:
-
-\begin{verbatim}
->>> empty = ()
->>> singleton = 'hello', # <-- note trailing comma
->>> len(empty)
-0
->>> len(singleton)
-1
->>> singleton
-('hello',)
-\end{verbatim}
-
-The statement \code{t = 12345, 54321, 'hello!'} is an example of
-\emph{tuple packing}: the values \code{12345}, \code{54321} and
-\code{'hello!'} are packed together in a tuple. The reverse operation
-is also possible:
-
-\begin{verbatim}
->>> x, y, z = t
-\end{verbatim}
-
-This is called, appropriately enough, \emph{sequence unpacking}.
-Sequence unpacking requires the list of variables on the left to
-have the same number of elements as the length of the sequence. Note
-that multiple assignment is really just a combination of tuple packing
-and sequence unpacking!
-
-There is a small bit of asymmetry here: packing multiple values
-always creates a tuple, and unpacking works for any sequence.
-
-% XXX Add a bit on the difference between tuples and lists.
-
-
-\section{Sets \label{sets}}
-
-Python also includes a data type for \emph{sets}. A set is an unordered
-collection with no duplicate elements. Basic uses include membership
-testing and eliminating duplicate entries. Set objects also support
-mathematical operations like union, intersection, difference, and
-symmetric difference.
-
-Here is a brief demonstration:
-
-\begin{verbatim}
->>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
->>> fruit = set(basket) # create a set without duplicates
->>> fruit
-set(['orange', 'pear', 'apple', 'banana'])
->>> 'orange' in fruit # fast membership testing
-True
->>> 'crabgrass' in fruit
-False
-
->>> # Demonstrate set operations on unique letters from two words
-...
->>> a = set('abracadabra')
->>> b = set('alacazam')
->>> a # unique letters in a
-set(['a', 'r', 'b', 'c', 'd'])
->>> a - b # letters in a but not in b
-set(['r', 'd', 'b'])
->>> a | b # letters in either a or b
-set(['a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'])
->>> a & b # letters in both a and b
-set(['a', 'c'])
->>> a ^ b # letters in a or b but not both
-set(['r', 'd', 'b', 'm', 'z', 'l'])
-\end{verbatim}
-
-
-\section{Dictionaries \label{dictionaries}}
-
-Another useful data type built into Python is the
-\ulink{\emph{dictionary}}{../lib/typesmapping.html}.
-Dictionaries are sometimes found in other languages as ``associative
-memories'' or ``associative arrays''. Unlike sequences, which are
-indexed by a range of numbers, dictionaries are indexed by \emph{keys},
-which can be any immutable type; strings and numbers can always be
-keys. Tuples can be used as keys if they contain only strings,
-numbers, or tuples; if a tuple contains any mutable object either
-directly or indirectly, it cannot be used as a key. You can't use
-lists as keys, since lists can be modified in place using
-index assignments, slice assignments, or methods like
-\method{append()} and \method{extend()}.
-
-It is best to think of a dictionary as an unordered set of
-\emph{key: value} pairs, with the requirement that the keys are unique
-(within one dictionary).
-A pair of braces creates an empty dictionary: \code{\{\}}.
-Placing a comma-separated list of key:value pairs within the
-braces adds initial key:value pairs to the dictionary; this is also the
-way dictionaries are written on output.
-
-The main operations on a dictionary are storing a value with some key
-and extracting the value given the key. It is also possible to delete
-a key:value pair
-with \code{del}.
-If you store using a key that is already in use, the old value
-associated with that key is forgotten. It is an error to extract a
-value using a non-existent key.
-
-The \method{keys()} method of a dictionary object returns a list of all
-the keys used in the dictionary, in arbitrary order (if you want it
-sorted, just apply the \method{sort()} method to the list of keys). To
-check whether a single key is in the dictionary, either use the dictionary's
-\method{has_key()} method or the \keyword{in} keyword.
-
-Here is a small example using a dictionary:
-
-\begin{verbatim}
->>> tel = {'jack': 4098, 'sape': 4139}
->>> tel['guido'] = 4127
->>> tel
-{'sape': 4139, 'guido': 4127, 'jack': 4098}
->>> tel['jack']
-4098
->>> del tel['sape']
->>> tel['irv'] = 4127
->>> tel
-{'guido': 4127, 'irv': 4127, 'jack': 4098}
->>> tel.keys()
-['guido', 'irv', 'jack']
->>> tel.has_key('guido')
-True
->>> 'guido' in tel
-True
-\end{verbatim}
-
-The \function{dict()} constructor builds dictionaries directly from
-lists of key-value pairs stored as tuples. When the pairs form a
-pattern, list comprehensions can compactly specify the key-value list.
-
-\begin{verbatim}
->>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
-{'sape': 4139, 'jack': 4098, 'guido': 4127}
->>> dict([(x, x**2) for x in (2, 4, 6)]) # use a list comprehension
-{2: 4, 4: 16, 6: 36}
-\end{verbatim}
-
-Later in the tutorial, we will learn about Generator Expressions
-which are even better suited for the task of supplying key-values pairs to
-the \function{dict()} constructor.
-
-When the keys are simple strings, it is sometimes easier to specify
-pairs using keyword arguments:
-
-\begin{verbatim}
->>> dict(sape=4139, guido=4127, jack=4098)
-{'sape': 4139, 'jack': 4098, 'guido': 4127}
-\end{verbatim}
-
-
-\section{Looping Techniques \label{loopidioms}}
-
-When looping through dictionaries, the key and corresponding value can
-be retrieved at the same time using the \method{iteritems()} method.
-
-\begin{verbatim}
->>> knights = {'gallahad': 'the pure', 'robin': 'the brave'}
->>> for k, v in knights.iteritems():
-... print k, v
-...
-gallahad the pure
-robin the brave
-\end{verbatim}
-
-When looping through a sequence, the position index and corresponding
-value can be retrieved at the same time using the
-\function{enumerate()} function.
-
-\begin{verbatim}
->>> for i, v in enumerate(['tic', 'tac', 'toe']):
-... print i, v
-...
-0 tic
-1 tac
-2 toe
-\end{verbatim}
-
-To loop over two or more sequences at the same time, the entries
-can be paired with the \function{zip()} function.
-
-\begin{verbatim}
->>> questions = ['name', 'quest', 'favorite color']
->>> answers = ['lancelot', 'the holy grail', 'blue']
->>> for q, a in zip(questions, answers):
-... print 'What is your %s? It is %s.' % (q, a)
-...
-What is your name? It is lancelot.
-What is your quest? It is the holy grail.
-What is your favorite color? It is blue.
-\end{verbatim}
-
-To loop over a sequence in reverse, first specify the sequence
-in a forward direction and then call the \function{reversed()}
-function.
-
-\begin{verbatim}
->>> for i in reversed(range(1,10,2)):
-... print i
-...
-9
-7
-5
-3
-1
-\end{verbatim}
-
-To loop over a sequence in sorted order, use the \function{sorted()}
-function which returns a new sorted list while leaving the source
-unaltered.
-
-\begin{verbatim}
->>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
->>> for f in sorted(set(basket)):
-... print f
-...
-apple
-banana
-orange
-pear
-\end{verbatim}
-
-\section{More on Conditions \label{conditions}}
-
-The conditions used in \code{while} and \code{if} statements can
-contain any operators, not just comparisons.
-
-The comparison operators \code{in} and \code{not in} check whether a value
-occurs (does not occur) in a sequence. The operators \code{is} and
-\code{is not} compare whether two objects are really the same object; this
-only matters for mutable objects like lists. All comparison operators
-have the same priority, which is lower than that of all numerical
-operators.
-
-Comparisons can be chained. For example, \code{a < b == c} tests
-whether \code{a} is less than \code{b} and moreover \code{b} equals
-\code{c}.
-
-Comparisons may be combined using the Boolean operators \code{and} and
-\code{or}, and the outcome of a comparison (or of any other Boolean
-expression) may be negated with \code{not}. These have lower
-priorities than comparison operators; between them, \code{not} has
-the highest priority and \code{or} the lowest, so that
-\code{A and not B or C} is equivalent to \code{(A and (not B)) or C}.
-As always, parentheses can be used to express the desired composition.
-
-The Boolean operators \code{and} and \code{or} are so-called
-\emph{short-circuit} operators: their arguments are evaluated from
-left to right, and evaluation stops as soon as the outcome is
-determined. For example, if \code{A} and \code{C} are true but
-\code{B} is false, \code{A and B and C} does not evaluate the
-expression \code{C}. When used as a general value and not as a
-Boolean, the return value of a short-circuit operator is the last
-evaluated argument.
-
-It is possible to assign the result of a comparison or other Boolean
-expression to a variable. For example,
-
-\begin{verbatim}
->>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'
->>> non_null = string1 or string2 or string3
->>> non_null
-'Trondheim'
-\end{verbatim}
-
-Note that in Python, unlike C, assignment cannot occur inside expressions.
-C programmers may grumble about this, but it avoids a common class of
-problems encountered in C programs: typing \code{=} in an expression when
-\code{==} was intended.
-
-
-\section{Comparing Sequences and Other Types \label{comparing}}
-
-Sequence objects may be compared to other objects with the same
-sequence type. The comparison uses \emph{lexicographical} ordering:
-first the first two items are compared, and if they differ this
-determines the outcome of the comparison; if they are equal, the next
-two items are compared, and so on, until either sequence is exhausted.
-If two items to be compared are themselves sequences of the same type,
-the lexicographical comparison is carried out recursively. If all
-items of two sequences compare equal, the sequences are considered
-equal. If one sequence is an initial sub-sequence of the other, the
-shorter sequence is the smaller (lesser) one. Lexicographical
-ordering for strings uses the \ASCII{} ordering for individual
-characters. Some examples of comparisons between sequences of the
-same type:
-
-\begin{verbatim}
-(1, 2, 3) < (1, 2, 4)
-[1, 2, 3] < [1, 2, 4]
-'ABC' < 'C' < 'Pascal' < 'Python'
-(1, 2, 3, 4) < (1, 2, 4)
-(1, 2) < (1, 2, -1)
-(1, 2, 3) == (1.0, 2.0, 3.0)
-(1, 2, ('aa', 'ab')) < (1, 2, ('abc', 'a'), 4)
-\end{verbatim}
-
-Note that comparing objects of different types is legal. The outcome
-is deterministic but arbitrary: the types are ordered by their name.
-Thus, a list is always smaller than a string, a string is always
-smaller than a tuple, etc. \footnote{
- The rules for comparing objects of different types should
- not be relied upon; they may change in a future version of
- the language.
-} Mixed numeric types are compared according to their numeric value, so
-0 equals 0.0, etc.
-
-
-\chapter{Modules \label{modules}}
-
-If you quit from the Python interpreter and enter it again, the
-definitions you have made (functions and variables) are lost.
-Therefore, if you want to write a somewhat longer program, you are
-better off using a text editor to prepare the input for the interpreter
-and running it with that file as input instead. This is known as creating a
-\emph{script}. As your program gets longer, you may want to split it
-into several files for easier maintenance. You may also want to use a
-handy function that you've written in several programs without copying
-its definition into each program.
-
-To support this, Python has a way to put definitions in a file and use
-them in a script or in an interactive instance of the interpreter.
-Such a file is called a \emph{module}; definitions from a module can be
-\emph{imported} into other modules or into the \emph{main} module (the
-collection of variables that you have access to in a script
-executed at the top level
-and in calculator mode).
-
-A module is a file containing Python definitions and statements. The
-file name is the module name with the suffix \file{.py} appended. Within
-a module, the module's name (as a string) is available as the value of
-the global variable \code{__name__}. For instance, use your favorite text
-editor to create a file called \file{fibo.py} in the current directory
-with the following contents:
-
-\begin{verbatim}
-# Fibonacci numbers module
-
-def fib(n): # write Fibonacci series up to n
- a, b = 0, 1
- while b < n:
- print b,
- a, b = b, a+b
-
-def fib2(n): # return Fibonacci series up to n
- result = []
- a, b = 0, 1
- while b < n:
- result.append(b)
- a, b = b, a+b
- return result
-\end{verbatim}
-
-Now enter the Python interpreter and import this module with the
-following command:
-
-\begin{verbatim}
->>> import fibo
-\end{verbatim}
-
-This does not enter the names of the functions defined in \code{fibo}
-directly in the current symbol table; it only enters the module name
-\code{fibo} there.
-Using the module name you can access the functions:
-
-\begin{verbatim}
->>> fibo.fib(1000)
-1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
->>> fibo.fib2(100)
-[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
->>> fibo.__name__
-'fibo'
-\end{verbatim}
-
-If you intend to use a function often you can assign it to a local name:
-
-\begin{verbatim}
->>> fib = fibo.fib
->>> fib(500)
-1 1 2 3 5 8 13 21 34 55 89 144 233 377
-\end{verbatim}
-
-
-\section{More on Modules \label{moreModules}}
-
-A module can contain executable statements as well as function
-definitions.
-These statements are intended to initialize the module.
-They are executed only the
-\emph{first} time the module is imported somewhere.\footnote{
- In fact function definitions are also `statements' that are
- `executed'; the execution enters the function name in the
- module's global symbol table.
-}
-
-Each module has its own private symbol table, which is used as the
-global symbol table by all functions defined in the module.
-Thus, the author of a module can use global variables in the module
-without worrying about accidental clashes with a user's global
-variables.
-On the other hand, if you know what you are doing you can touch a
-module's global variables with the same notation used to refer to its
-functions,
-\code{modname.itemname}.
-
-Modules can import other modules. It is customary but not required to
-place all \keyword{import} statements at the beginning of a module (or
-script, for that matter). The imported module names are placed in the
-importing module's global symbol table.
-
-There is a variant of the \keyword{import} statement that imports
-names from a module directly into the importing module's symbol
-table. For example:
-
-\begin{verbatim}
->>> from fibo import fib, fib2
->>> fib(500)
-1 1 2 3 5 8 13 21 34 55 89 144 233 377
-\end{verbatim}
-
-This does not introduce the module name from which the imports are taken
-in the local symbol table (so in the example, \code{fibo} is not
-defined).
-
-There is even a variant to import all names that a module defines:
-
-\begin{verbatim}
->>> from fibo import *
->>> fib(500)
-1 1 2 3 5 8 13 21 34 55 89 144 233 377
-\end{verbatim}
-
-This imports all names except those beginning with an underscore
-(\code{_}).
-
-\subsection{Executing modules as scripts \label{modulesAsScripts}}
-
-When you run a Python module with
-
-\begin{verbatim}
-python fibo.py <arguments>
-\end{verbatim}
-
-the code in the module will be executed, just as if you imported it, but
-with the \code{__name__} set to \code{"__main__"}. That means that by
-adding this code at the end of your module:
-
-\begin{verbatim}
-if __name__ == "__main__":
- import sys
- fib(int(sys.argv[1]))
-\end{verbatim}
-
-you can make the file usable as a script as well as an importable module,
-because the code that parses the command line only runs if the module is
-executed as the ``main'' file:
-
-\begin{verbatim}
-$ python fibo.py 50
-1 1 2 3 5 8 13 21 34
-\end{verbatim}
-
-If the module is imported, the code is not run:
-
-\begin{verbatim}
->>> import fibo
->>>
-\end{verbatim}
-
-This is often used either to provide a convenient user interface to a
-module, or for testing purposes (running the module as a script executes
-a test suite).
-
-
-\subsection{The Module Search Path \label{searchPath}}
-
-\indexiii{module}{search}{path}
-When a module named \module{spam} is imported, the interpreter searches
-for a file named \file{spam.py} in the current directory,
-and then in the list of directories specified by
-the environment variable \envvar{PYTHONPATH}. This has the same syntax as
-the shell variable \envvar{PATH}, that is, a list of
-directory names. When \envvar{PYTHONPATH} is not set, or when the file
-is not found there, the search continues in an installation-dependent
-default path; on \UNIX, this is usually \file{.:/usr/local/lib/python}.
-
-Actually, modules are searched in the list of directories given by the
-variable \code{sys.path} which is initialized from the directory
-containing the input script (or the current directory),
-\envvar{PYTHONPATH} and the installation-dependent default. This allows
-Python programs that know what they're doing to modify or replace the
-module search path. Note that because the directory containing the
-script being run is on the search path, it is important that the
-script not have the same name as a standard module, or Python will
-attempt to load the script as a module when that module is imported.
-This will generally be an error. See section~\ref{standardModules},
-``Standard Modules,'' for more information.
-
-
-\subsection{``Compiled'' Python files}
-
-As an important speed-up of the start-up time for short programs that
-use a lot of standard modules, if a file called \file{spam.pyc} exists
-in the directory where \file{spam.py} is found, this is assumed to
-contain an already-``byte-compiled'' version of the module \module{spam}.
-The modification time of the version of \file{spam.py} used to create
-\file{spam.pyc} is recorded in \file{spam.pyc}, and the
-\file{.pyc} file is ignored if these don't match.
-
-Normally, you don't need to do anything to create the
-\file{spam.pyc} file. Whenever \file{spam.py} is successfully
-compiled, an attempt is made to write the compiled version to
-\file{spam.pyc}. It is not an error if this attempt fails; if for any
-reason the file is not written completely, the resulting
-\file{spam.pyc} file will be recognized as invalid and thus ignored
-later. The contents of the \file{spam.pyc} file are platform
-independent, so a Python module directory can be shared by machines of
-different architectures.
-
-Some tips for experts:
-
-\begin{itemize}
-
-\item
-When the Python interpreter is invoked with the \programopt{-O} flag,
-optimized code is generated and stored in \file{.pyo} files. The
-optimizer currently doesn't help much; it only removes
-\keyword{assert} statements. When \programopt{-O} is used, \emph{all}
-bytecode is optimized; \code{.pyc} files are ignored and \code{.py}
-files are compiled to optimized bytecode.
-
-\item
-Passing two \programopt{-O} flags to the Python interpreter
-(\programopt{-OO}) will cause the bytecode compiler to perform
-optimizations that could in some rare cases result in malfunctioning
-programs. Currently only \code{__doc__} strings are removed from the
-bytecode, resulting in more compact \file{.pyo} files. Since some
-programs may rely on having these available, you should only use this
-option if you know what you're doing.
-
-\item
-A program doesn't run any faster when it is read from a \file{.pyc} or
-\file{.pyo} file than when it is read from a \file{.py} file; the only
-thing that's faster about \file{.pyc} or \file{.pyo} files is the
-speed with which they are loaded.
-
-\item
-When a script is run by giving its name on the command line, the
-bytecode for the script is never written to a \file{.pyc} or
-\file{.pyo} file. Thus, the startup time of a script may be reduced
-by moving most of its code to a module and having a small bootstrap
-script that imports that module. It is also possible to name a
-\file{.pyc} or \file{.pyo} file directly on the command line.
-
-\item
-It is possible to have a file called \file{spam.pyc} (or
-\file{spam.pyo} when \programopt{-O} is used) without a file
-\file{spam.py} for the same module. This can be used to distribute a
-library of Python code in a form that is moderately hard to reverse
-engineer.
-
-\item
-The module \ulink{\module{compileall}}{../lib/module-compileall.html}%
-{} \refstmodindex{compileall} can create \file{.pyc} files (or
-\file{.pyo} files when \programopt{-O} is used) for all modules in a
-directory.
-
-\end{itemize}
-
-
-\section{Standard Modules \label{standardModules}}
-
-Python comes with a library of standard modules, described in a separate
-document, the \citetitle[../lib/lib.html]{Python Library Reference}
-(``Library Reference'' hereafter). Some modules are built into the
-interpreter; these provide access to operations that are not part of
-the core of the language but are nevertheless built in, either for
-efficiency or to provide access to operating system primitives such as
-system calls. The set of such modules is a configuration option which
-also depends on the underlying platform For example,
-the \module{winreg} module is only provided on Windows systems.
-One particular module deserves some
-attention: \ulink{\module{sys}}{../lib/module-sys.html}%
-\refstmodindex{sys}, which is built into every
-Python interpreter. The variables \code{sys.ps1} and
-\code{sys.ps2} define the strings used as primary and secondary
-prompts:
-
-\begin{verbatim}
->>> import sys
->>> sys.ps1
-'>>> '
->>> sys.ps2
-'... '
->>> sys.ps1 = 'C> '
-C> print 'Yuck!'
-Yuck!
-C>
-
-\end{verbatim}
-
-These two variables are only defined if the interpreter is in
-interactive mode.
-
-The variable \code{sys.path} is a list of strings that determines the
-interpreter's search path for modules. It is initialized to a default
-path taken from the environment variable \envvar{PYTHONPATH}, or from
-a built-in default if \envvar{PYTHONPATH} is not set. You can modify
-it using standard list operations:
-
-\begin{verbatim}
->>> import sys
->>> sys.path.append('/ufs/guido/lib/python')
-\end{verbatim}
-
-\section{The \function{dir()} Function \label{dir}}
-
-The built-in function \function{dir()} is used to find out which names
-a module defines. It returns a sorted list of strings:
-
-\begin{verbatim}
->>> import fibo, sys
->>> dir(fibo)
-['__name__', 'fib', 'fib2']
->>> dir(sys)
-['__displayhook__', '__doc__', '__excepthook__', '__name__', '__stderr__',
- '__stdin__', '__stdout__', '_getframe', 'api_version', 'argv',
- 'builtin_module_names', 'byteorder', 'callstats', 'copyright',
- 'displayhook', 'exc_info', 'excepthook',
- 'exec_prefix', 'executable', 'exit', 'getdefaultencoding', 'getdlopenflags',
- 'getrecursionlimit', 'getrefcount', 'hexversion', 'maxint', 'maxunicode',
- 'meta_path', 'modules', 'path', 'path_hooks', 'path_importer_cache',
- 'platform', 'prefix', 'ps1', 'ps2', 'setcheckinterval', 'setdlopenflags',
- 'setprofile', 'setrecursionlimit', 'settrace', 'stderr', 'stdin', 'stdout',
- 'version', 'version_info', 'warnoptions']
-\end{verbatim}
-
-Without arguments, \function{dir()} lists the names you have defined
-currently:
-
-\begin{verbatim}
->>> a = [1, 2, 3, 4, 5]
->>> import fibo
->>> fib = fibo.fib
->>> dir()
-['__builtins__', '__doc__', '__file__', '__name__', 'a', 'fib', 'fibo', 'sys']
-\end{verbatim}
-
-Note that it lists all types of names: variables, modules, functions, etc.
-
-\function{dir()} does not list the names of built-in functions and
-variables. If you want a list of those, they are defined in the
-standard module \module{__builtin__}\refbimodindex{__builtin__}:
-
-\begin{verbatim}
->>> import __builtin__
->>> dir(__builtin__)
-['ArithmeticError', 'AssertionError', 'AttributeError', 'DeprecationWarning',
- 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',
- 'FloatingPointError', 'FutureWarning', 'IOError', 'ImportError',
- 'IndentationError', 'IndexError', 'KeyError', 'KeyboardInterrupt',
- 'LookupError', 'MemoryError', 'NameError', 'None', 'NotImplemented',
- 'NotImplementedError', 'OSError', 'OverflowError',
- 'PendingDeprecationWarning', 'ReferenceError', 'RuntimeError',
- 'RuntimeWarning', 'StopIteration', 'SyntaxError',
- 'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError', 'True',
- 'TypeError', 'UnboundLocalError', 'UnicodeDecodeError',
- 'UnicodeEncodeError', 'UnicodeError', 'UnicodeTranslateError',
- 'UserWarning', 'ValueError', 'Warning', 'WindowsError',
- 'ZeroDivisionError', '_', '__debug__', '__doc__', '__import__',
- '__name__', 'abs', 'basestring', 'bool', 'buffer',
- 'chr', 'classmethod', 'cmp', 'compile',
- 'complex', 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod',
- 'enumerate', 'eval', 'exec', 'exit', 'filter', 'float',
- 'frozenset', 'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex',
- 'id', 'input', 'int', 'isinstance', 'issubclass', 'iter',
- 'len', 'license', 'list', 'locals', 'map', 'max', 'min',
- 'object', 'oct', 'open', 'ord', 'pow', 'property', 'quit', 'range',
- 'repr', 'reversed', 'round', 'set',
- 'setattr', 'slice', 'sorted', 'staticmethod', 'str', 'sum', 'super',
- 'tuple', 'type', 'vars', 'zip']
-\end{verbatim}
-
-
-\section{Packages \label{packages}}
-
-Packages are a way of structuring Python's module namespace
-by using ``dotted module names''. For example, the module name
-\module{A.B} designates a submodule named \samp{B} in a package named
-\samp{A}. Just like the use of modules saves the authors of different
-modules from having to worry about each other's global variable names,
-the use of dotted module names saves the authors of multi-module
-packages like NumPy or the Python Imaging Library from having to worry
-about each other's module names.
-
-Suppose you want to design a collection of modules (a ``package'') for
-the uniform handling of sound files and sound data. There are many
-different sound file formats (usually recognized by their extension,
-for example: \file{.wav}, \file{.aiff}, \file{.au}), so you may need
-to create and maintain a growing collection of modules for the
-conversion between the various file formats. There are also many
-different operations you might want to perform on sound data (such as
-mixing, adding echo, applying an equalizer function, creating an
-artificial stereo effect), so in addition you will be writing a
-never-ending stream of modules to perform these operations. Here's a
-possible structure for your package (expressed in terms of a
-hierarchical filesystem):
-
-\begin{verbatim}
-sound/ Top-level package
- __init__.py Initialize the sound package
- formats/ Subpackage for file format conversions
- __init__.py
- wavread.py
- wavwrite.py
- aiffread.py
- aiffwrite.py
- auread.py
- auwrite.py
- ...
- effects/ Subpackage for sound effects
- __init__.py
- echo.py
- surround.py
- reverse.py
- ...
- filters/ Subpackage for filters
- __init__.py
- equalizer.py
- vocoder.py
- karaoke.py
- ...
-\end{verbatim}
-
-When importing the package, Python searches through the directories
-on \code{sys.path} looking for the package subdirectory.
-
-The \file{__init__.py} files are required to make Python treat the
-directories as containing packages; this is done to prevent
-directories with a common name, such as \samp{string}, from
-unintentionally hiding valid modules that occur later on the module
-search path. In the simplest case, \file{__init__.py} can just be an
-empty file, but it can also execute initialization code for the
-package or set the \code{__all__} variable, described later.
-
-Users of the package can import individual modules from the
-package, for example:
-
-\begin{verbatim}
-import sound.effects.echo
-\end{verbatim}
-
-This loads the submodule \module{sound.effects.echo}. It must be referenced
-with its full name.
-
-\begin{verbatim}
-sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)
-\end{verbatim}
-
-An alternative way of importing the submodule is:
-
-\begin{verbatim}
-from sound.effects import echo
-\end{verbatim}
-
-This also loads the submodule \module{echo}, and makes it available without
-its package prefix, so it can be used as follows:
-
-\begin{verbatim}
-echo.echofilter(input, output, delay=0.7, atten=4)
-\end{verbatim}
-
-Yet another variation is to import the desired function or variable directly:
-
-\begin{verbatim}
-from sound.effects.echo import echofilter
-\end{verbatim}
-
-Again, this loads the submodule \module{echo}, but this makes its function
-\function{echofilter()} directly available:
-
-\begin{verbatim}
-echofilter(input, output, delay=0.7, atten=4)
-\end{verbatim}
-
-Note that when using \code{from \var{package} import \var{item}}, the
-item can be either a submodule (or subpackage) of the package, or some
-other name defined in the package, like a function, class or
-variable. The \code{import} statement first tests whether the item is
-defined in the package; if not, it assumes it is a module and attempts
-to load it. If it fails to find it, an
-\exception{ImportError} exception is raised.
-
-Contrarily, when using syntax like \code{import
-\var{item.subitem.subsubitem}}, each item except for the last must be
-a package; the last item can be a module or a package but can't be a
-class or function or variable defined in the previous item.
-
-\subsection{Importing * From a Package \label{pkg-import-star}}
-%The \code{__all__} Attribute
-
-\ttindex{__all__}
-Now what happens when the user writes \code{from sound.effects import
-*}? Ideally, one would hope that this somehow goes out to the
-filesystem, finds which submodules are present in the package, and
-imports them all. Unfortunately, this operation does not work very
-well on Windows platforms, where the filesystem does not
-always have accurate information about the case of a filename! On
-these platforms, there is no guaranteed way to know whether a file
-\file{ECHO.PY} should be imported as a module \module{echo},
-\module{Echo} or \module{ECHO}. (For example, Windows 95 has the
-annoying practice of showing all file names with a capitalized first
-letter.) The DOS 8+3 filename restriction adds another interesting
-problem for long module names.
-
-The only solution is for the package author to provide an explicit
-index of the package. The import statement uses the following
-convention: if a package's \file{__init__.py} code defines a list
-named \code{__all__}, it is taken to be the list of module names that
-should be imported when \code{from \var{package} import *} is
-encountered. It is up to the package author to keep this list
-up-to-date when a new version of the package is released. Package
-authors may also decide not to support it, if they don't see a use for
-importing * from their package. For example, the file
-\file{sounds/effects/__init__.py} could contain the following code:
-
-\begin{verbatim}
-__all__ = ["echo", "surround", "reverse"]
-\end{verbatim}
-
-This would mean that \code{from sound.effects import *} would
-import the three named submodules of the \module{sound} package.
-
-If \code{__all__} is not defined, the statement \code{from sound.effects
-import *} does \emph{not} import all submodules from the package
-\module{sound.effects} into the current namespace; it only ensures that the
-package \module{sound.effects} has been imported (possibly running any
-initialization code in \file{__init__.py}) and then imports whatever names are
-defined in the package. This includes any names defined (and
-submodules explicitly loaded) by \file{__init__.py}. It also includes any
-submodules of the package that were explicitly loaded by previous
-import statements. Consider this code:
-
-\begin{verbatim}
-import sound.effects.echo
-import sound.effects.surround
-from sound.effects import *
-\end{verbatim}
-
-In this example, the echo and surround modules are imported in the
-current namespace because they are defined in the
-\module{sound.effects} package when the \code{from...import} statement
-is executed. (This also works when \code{__all__} is defined.)
-
-Note that in general the practice of importing \code{*} from a module or
-package is frowned upon, since it often causes poorly readable code.
-However, it is okay to use it to save typing in interactive sessions,
-and certain modules are designed to export only names that follow
-certain patterns.
-
-Remember, there is nothing wrong with using \code{from Package
-import specific_submodule}! In fact, this is the
-recommended notation unless the importing module needs to use
-submodules with the same name from different packages.
-
-
-\subsection{Intra-package References}
-
-The submodules often need to refer to each other. For example, the
-\module{surround} module might use the \module{echo} module. In fact,
-such references are so common that the \keyword{import} statement
-first looks in the containing package before looking in the standard
-module search path. Thus, the \module{surround} module can simply use
-\code{import echo} or \code{from echo import echofilter}. If the
-imported module is not found in the current package (the package of
-which the current module is a submodule), the \keyword{import}
-statement looks for a top-level module with the given name.
-
-When packages are structured into subpackages (as with the
-\module{sound} package in the example), you can use absolute
-imports to refer to submodules of siblings packages.
-For example, if the module \module{sound.filters.vocoder} needs to
-use the \module{echo} module in the \module{sound.effects} package,
-it can use \code{from sound.effects import echo}.
-
-Starting with Python 2.5, in addition to the implicit relative imports
-described above, you can also write explicit relative imports with the
-\code{from module import name} form of import statement. These explicit
-relative imports use leading dots to indicate the current and parent
-packages involved in the relative import. From the \module{surround}
-module for example, you might use:
-
-\begin{verbatim}
-from . import echo
-from .. import formats
-from ..filters import equalizer
-\end{verbatim}
-
-Note that both explicit and implicit relative imports are based on the
-name of the current module. Since the name of the main module is always
-\code{"__main__"}, modules intended for use as the main module of a
-Python application should always use absolute imports.
-
-\subsection{Packages in Multiple Directories}
-
-Packages support one more special attribute, \member{__path__}. This
-is initialized to be a list containing the name of the directory
-holding the package's \file{__init__.py} before the code in that file
-is executed. This variable can be modified; doing so affects future
-searches for modules and subpackages contained in the package.
-
-While this feature is not often needed, it can be used to extend the
-set of modules found in a package.
-
-
-
-\chapter{Input and Output \label{io}}
-
-There are several ways to present the output of a program; data can be
-printed in a human-readable form, or written to a file for future use.
-This chapter will discuss some of the possibilities.
-
-
-\section{Fancier Output Formatting \label{formatting}}
-
-So far we've encountered two ways of writing values: \emph{expression
-statements} and the \keyword{print} statement. (A third way is using
-the \method{write()} method of file objects; the standard output file
-can be referenced as \code{sys.stdout}. See the Library Reference for
-more information on this.)
-
-Often you'll want more control over the formatting of your output than
-simply printing space-separated values. There are two ways to format
-your output; the first way is to do all the string handling yourself;
-using string slicing and concatenation operations you can create any
-layout you can imagine. The standard module
-\module{string}\refstmodindex{string} contains some useful operations
-for padding strings to a given column width; these will be discussed
-shortly. The second way is to use the \code{\%} operator with a
-string as the left argument. The \code{\%} operator interprets the
-left argument much like a \cfunction{sprintf()}-style format
-string to be applied to the right argument, and returns the string
-resulting from this formatting operation.
-
-One question remains, of course: how do you convert values to strings?
-Luckily, Python has ways to convert any value to a string: pass it to
-the \function{repr()} or \function{str()} functions. Reverse quotes
-(\code{``}) are equivalent to \function{repr()}, but they are no
-longer used in modern Python code and will likely not be in future
-versions of the language.
-
-The \function{str()} function is meant to return representations of
-values which are fairly human-readable, while \function{repr()} is
-meant to generate representations which can be read by the interpreter
-(or will force a \exception{SyntaxError} if there is not equivalent
-syntax). For objects which don't have a particular representation for
-human consumption, \function{str()} will return the same value as
-\function{repr()}. Many values, such as numbers or structures like
-lists and dictionaries, have the same representation using either
-function. Strings and floating point numbers, in particular, have two
-distinct representations.
-
-Some examples:
-
-\begin{verbatim}
->>> s = 'Hello, world.'
->>> str(s)
-'Hello, world.'
->>> repr(s)
-"'Hello, world.'"
->>> str(0.1)
-'0.1'
->>> repr(0.1)
-'0.10000000000000001'
->>> x = 10 * 3.25
->>> y = 200 * 200
->>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
->>> print s
-The value of x is 32.5, and y is 40000...
->>> # The repr() of a string adds string quotes and backslashes:
-... hello = 'hello, world\n'
->>> hellos = repr(hello)
->>> print hellos
-'hello, world\n'
->>> # The argument to repr() may be any Python object:
-... repr((x, y, ('spam', 'eggs')))
-"(32.5, 40000, ('spam', 'eggs'))"
->>> # reverse quotes are convenient in interactive sessions:
-... `x, y, ('spam', 'eggs')`
-"(32.5, 40000, ('spam', 'eggs'))"
-\end{verbatim}
-
-Here are two ways to write a table of squares and cubes:
-
-\begin{verbatim}
->>> for x in range(1, 11):
-... print repr(x).rjust(2), repr(x*x).rjust(3),
-... # Note trailing comma on previous line
-... print repr(x*x*x).rjust(4)
-...
- 1 1 1
- 2 4 8
- 3 9 27
- 4 16 64
- 5 25 125
- 6 36 216
- 7 49 343
- 8 64 512
- 9 81 729
-10 100 1000
-
->>> for x in range(1,11):
-... print '%2d %3d %4d' % (x, x*x, x*x*x)
-...
- 1 1 1
- 2 4 8
- 3 9 27
- 4 16 64
- 5 25 125
- 6 36 216
- 7 49 343
- 8 64 512
- 9 81 729
-10 100 1000
-\end{verbatim}
-
-(Note that in the first example, one space between each column was
-added by the way \keyword{print} works: it always adds spaces between
-its arguments.)
-
-This example demonstrates the \method{rjust()} method of string objects,
-which right-justifies a string in a field of a given width by padding
-it with spaces on the left. There are similar methods
-\method{ljust()} and \method{center()}. These
-methods do not write anything, they just return a new string. If
-the input string is too long, they don't truncate it, but return it
-unchanged; this will mess up your column lay-out but that's usually
-better than the alternative, which would be lying about a value. (If
-you really want truncation you can always add a slice operation, as in
-\samp{x.ljust(n)[:n]}.)
-
-There is another method, \method{zfill()}, which pads a
-numeric string on the left with zeros. It understands about plus and
-minus signs:
-
-\begin{verbatim}
->>> '12'.zfill(5)
-'00012'
->>> '-3.14'.zfill(7)
-'-003.14'
->>> '3.14159265359'.zfill(5)
-'3.14159265359'
-\end{verbatim}
-
-Using the \code{\%} operator looks like this:
-
-\begin{verbatim}
->>> import math
->>> print 'The value of PI is approximately %5.3f.' % math.pi
-The value of PI is approximately 3.142.
-\end{verbatim}
-
-If there is more than one format in the string, you need to pass a
-tuple as right operand, as in this example:
-
-\begin{verbatim}
->>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
->>> for name, phone in table.items():
-... print '%-10s ==> %10d' % (name, phone)
-...
-Jack ==> 4098
-Dcab ==> 7678
-Sjoerd ==> 4127
-\end{verbatim}
-
-Most formats work exactly as in C and require that you pass the proper
-type; however, if you don't you get an exception, not a core dump.
-The \code{\%s} format is more relaxed: if the corresponding argument is
-not a string object, it is converted to string using the
-\function{str()} built-in function. Using \code{*} to pass the width
-or precision in as a separate (integer) argument is supported. The
-C formats \code{\%n} and \code{\%p} are not supported.
-
-If you have a really long format string that you don't want to split
-up, it would be nice if you could reference the variables to be
-formatted by name instead of by position. This can be done by using
-form \code{\%(name)format}, as shown here:
-
-\begin{verbatim}
->>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
->>> print 'Jack: %(Jack)d; Sjoerd: %(Sjoerd)d; Dcab: %(Dcab)d' % table
-Jack: 4098; Sjoerd: 4127; Dcab: 8637678
-\end{verbatim}
-
-This is particularly useful in combination with the new built-in
-\function{vars()} function, which returns a dictionary containing all
-local variables.
-
-\section{Reading and Writing Files \label{files}}
-
-% Opening files
-\function{open()}\bifuncindex{open} returns a file
-object\obindex{file}, and is most commonly used with two arguments:
-\samp{open(\var{filename}, \var{mode})}.
-
-\begin{verbatim}
->>> f=open('/tmp/workfile', 'w')
->>> print f
-<open file '/tmp/workfile', mode 'w' at 80a0960>
-\end{verbatim}
-
-The first argument is a string containing the filename. The second
-argument is another string containing a few characters describing the
-way in which the file will be used. \var{mode} can be \code{'r'} when
-the file will only be read, \code{'w'} for only writing (an existing
-file with the same name will be erased), and \code{'a'} opens the file
-for appending; any data written to the file is automatically added to
-the end. \code{'r+'} opens the file for both reading and writing.
-The \var{mode} argument is optional; \code{'r'} will be assumed if
-it's omitted.
-
-On Windows and the Macintosh, \code{'b'} appended to the
-mode opens the file in binary mode, so there are also modes like
-\code{'rb'}, \code{'wb'}, and \code{'r+b'}. Windows makes a
-distinction between text and binary files; the end-of-line characters
-in text files are automatically altered slightly when data is read or
-written. This behind-the-scenes modification to file data is fine for
-\ASCII{} text files, but it'll corrupt binary data like that in \file{JPEG} or
-\file{EXE} files. Be very careful to use binary mode when reading and
-writing such files.
-
-\subsection{Methods of File Objects \label{fileMethods}}
-
-The rest of the examples in this section will assume that a file
-object called \code{f} has already been created.
-
-To read a file's contents, call \code{f.read(\var{size})}, which reads
-some quantity of data and returns it as a string. \var{size} is an
-optional numeric argument. When \var{size} is omitted or negative,
-the entire contents of the file will be read and returned; it's your
-problem if the file is twice as large as your machine's memory.
-Otherwise, at most \var{size} bytes are read and returned. If the end
-of the file has been reached, \code{f.read()} will return an empty
-string (\code {""}).
-\begin{verbatim}
->>> f.read()
-'This is the entire file.\n'
->>> f.read()
-''
-\end{verbatim}
-
-\code{f.readline()} reads a single line from the file; a newline
-character (\code{\e n}) is left at the end of the string, and is only
-omitted on the last line of the file if the file doesn't end in a
-newline. This makes the return value unambiguous; if
-\code{f.readline()} returns an empty string, the end of the file has
-been reached, while a blank line is represented by \code{'\e n'}, a
-string containing only a single newline.
-
-\begin{verbatim}
->>> f.readline()
-'This is the first line of the file.\n'
->>> f.readline()
-'Second line of the file\n'
->>> f.readline()
-''
-\end{verbatim}
-
-\code{f.readlines()} returns a list containing all the lines of data
-in the file. If given an optional parameter \var{sizehint}, it reads
-that many bytes from the file and enough more to complete a line, and
-returns the lines from that. This is often used to allow efficient
-reading of a large file by lines, but without having to load the
-entire file in memory. Only complete lines will be returned.
-
-\begin{verbatim}
->>> f.readlines()
-['This is the first line of the file.\n', 'Second line of the file\n']
-\end{verbatim}
-
-An alternate approach to reading lines is to loop over the file object.
-This is memory efficient, fast, and leads to simpler code:
-
-\begin{verbatim}
->>> for line in f:
- print line,
-
-This is the first line of the file.
-Second line of the file
-\end{verbatim}
-
-The alternative approach is simpler but does not provide as fine-grained
-control. Since the two approaches manage line buffering differently,
-they should not be mixed.
-
-\code{f.write(\var{string})} writes the contents of \var{string} to
-the file, returning \code{None}.
-
-\begin{verbatim}
->>> f.write('This is a test\n')
-\end{verbatim}
-
-To write something other than a string, it needs to be converted to a
-string first:
-
-\begin{verbatim}
->>> value = ('the answer', 42)
->>> s = str(value)
->>> f.write(s)
-\end{verbatim}
-
-\code{f.tell()} returns an integer giving the file object's current
-position in the file, measured in bytes from the beginning of the
-file. To change the file object's position, use
-\samp{f.seek(\var{offset}, \var{from_what})}. The position is
-computed from adding \var{offset} to a reference point; the reference
-point is selected by the \var{from_what} argument. A
-\var{from_what} value of 0 measures from the beginning of the file, 1
-uses the current file position, and 2 uses the end of the file as the
-reference point. \var{from_what} can be omitted and defaults to 0,
-using the beginning of the file as the reference point.
-
-\begin{verbatim}
->>> f = open('/tmp/workfile', 'r+')
->>> f.write('0123456789abcdef')
->>> f.seek(5) # Go to the 6th byte in the file
->>> f.read(1)
-'5'
->>> f.seek(-3, 2) # Go to the 3rd byte before the end
->>> f.read(1)
-'d'
-\end{verbatim}
-
-When you're done with a file, call \code{f.close()} to close it and
-free up any system resources taken up by the open file. After calling
-\code{f.close()}, attempts to use the file object will automatically fail.
-
-\begin{verbatim}
->>> f.close()
->>> f.read()
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ValueError: I/O operation on closed file
-\end{verbatim}
-
-File objects have some additional methods, such as
-\method{isatty()} and \method{truncate()} which are less frequently
-used; consult the Library Reference for a complete guide to file
-objects.
-
-\subsection{The \module{pickle} Module \label{pickle}}
-\refstmodindex{pickle}
-
-Strings can easily be written to and read from a file. Numbers take a
-bit more effort, since the \method{read()} method only returns
-strings, which will have to be passed to a function like
-\function{int()}, which takes a string like \code{'123'} and
-returns its numeric value 123. However, when you want to save more
-complex data types like lists, dictionaries, or class instances,
-things get a lot more complicated.
-
-Rather than have users be constantly writing and debugging code to
-save complicated data types, Python provides a standard module called
-\ulink{\module{pickle}}{../lib/module-pickle.html}. This is an
-amazing module that can take almost
-any Python object (even some forms of Python code!), and convert it to
-a string representation; this process is called \dfn{pickling}.
-Reconstructing the object from the string representation is called
-\dfn{unpickling}. Between pickling and unpickling, the string
-representing the object may have been stored in a file or data, or
-sent over a network connection to some distant machine.
-
-If you have an object \code{x}, and a file object \code{f} that's been
-opened for writing, the simplest way to pickle the object takes only
-one line of code:
-
-\begin{verbatim}
-pickle.dump(x, f)
-\end{verbatim}
-
-To unpickle the object again, if \code{f} is a file object which has
-been opened for reading:
-
-\begin{verbatim}
-x = pickle.load(f)
-\end{verbatim}
-
-(There are other variants of this, used when pickling many objects or
-when you don't want to write the pickled data to a file; consult the
-complete documentation for
-\ulink{\module{pickle}}{../lib/module-pickle.html} in the
-\citetitle[../lib/]{Python Library Reference}.)
-
-\ulink{\module{pickle}}{../lib/module-pickle.html} is the standard way
-to make Python objects which can be stored and reused by other
-programs or by a future invocation of the same program; the technical
-term for this is a \dfn{persistent} object. Because
-\ulink{\module{pickle}}{../lib/module-pickle.html} is so widely used,
-many authors who write Python extensions take care to ensure that new
-data types such as matrices can be properly pickled and unpickled.
-
-
-
-\chapter{Errors and Exceptions \label{errors}}
-
-Until now error messages haven't been more than mentioned, but if you
-have tried out the examples you have probably seen some. There are
-(at least) two distinguishable kinds of errors:
-\emph{syntax errors} and \emph{exceptions}.
-
-\section{Syntax Errors \label{syntaxErrors}}
-
-Syntax errors, also known as parsing errors, are perhaps the most common
-kind of complaint you get while you are still learning Python:
-
-\begin{verbatim}
->>> while True print 'Hello world'
- File "<stdin>", line 1, in ?
- while True print 'Hello world'
- ^
-SyntaxError: invalid syntax
-\end{verbatim}
-
-The parser repeats the offending line and displays a little `arrow'
-pointing at the earliest point in the line where the error was
-detected. The error is caused by (or at least detected at) the token
-\emph{preceding} the arrow: in the example, the error is detected at
-the keyword \keyword{print}, since a colon (\character{:}) is missing
-before it. File name and line number are printed so you know where to
-look in case the input came from a script.
-
-\section{Exceptions \label{exceptions}}
-
-Even if a statement or expression is syntactically correct, it may
-cause an error when an attempt is made to execute it.
-Errors detected during execution are called \emph{exceptions} and are
-not unconditionally fatal: you will soon learn how to handle them in
-Python programs. Most exceptions are not handled by programs,
-however, and result in error messages as shown here:
-
-\begin{verbatim}
->>> 10 * (1/0)
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ZeroDivisionError: integer division or modulo by zero
->>> 4 + spam*3
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-NameError: name 'spam' is not defined
->>> '2' + 2
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-TypeError: cannot concatenate 'str' and 'int' objects
-\end{verbatim}
-
-The last line of the error message indicates what happened.
-Exceptions come in different types, and the type is printed as part of
-the message: the types in the example are
-\exception{ZeroDivisionError}, \exception{NameError} and
-\exception{TypeError}.
-The string printed as the exception type is the name of the built-in
-exception that occurred. This is true for all built-in
-exceptions, but need not be true for user-defined exceptions (although
-it is a useful convention).
-Standard exception names are built-in identifiers (not reserved
-keywords).
-
-The rest of the line provides detail based on the type of exception
-and what caused it.
-
-The preceding part of the error message shows the context where the
-exception happened, in the form of a stack traceback.
-In general it contains a stack traceback listing source lines; however,
-it will not display lines read from standard input.
-
-The \citetitle[../lib/module-exceptions.html]{Python Library
-Reference} lists the built-in exceptions and their meanings.
-
-
-\section{Handling Exceptions \label{handling}}
-
-It is possible to write programs that handle selected exceptions.
-Look at the following example, which asks the user for input until a
-valid integer has been entered, but allows the user to interrupt the
-program (using \kbd{Control-C} or whatever the operating system
-supports); note that a user-generated interruption is signalled by
-raising the \exception{KeyboardInterrupt} exception.
-
-\begin{verbatim}
->>> def raw_input(prompt):
-... import sys
-... sys.stdout.write(prompt)
-... sys.stdout.flush()
-... return sys.stdin.readline()
-...
->>> while True:
-... try:
-... x = int(raw_input("Please enter a number: "))
-... break
-... except ValueError:
-... print "Oops! That was no valid number. Try again..."
-...
-\end{verbatim}
-
-The \keyword{try} statement works as follows.
-
-\begin{itemize}
-\item
-First, the \emph{try clause} (the statement(s) between the
-\keyword{try} and \keyword{except} keywords) is executed.
-
-\item
-If no exception occurs, the \emph{except\ clause} is skipped and
-execution of the \keyword{try} statement is finished.
-
-\item
-If an exception occurs during execution of the try clause, the rest of
-the clause is skipped. Then if its type matches the exception named
-after the \keyword{except} keyword, the except clause is executed, and
-then execution continues after the \keyword{try} statement.
-
-\item
-If an exception occurs which does not match the exception named in the
-except clause, it is passed on to outer \keyword{try} statements; if
-no handler is found, it is an \emph{unhandled exception} and execution
-stops with a message as shown above.
-
-\end{itemize}
-
-A \keyword{try} statement may have more than one except clause, to
-specify handlers for different exceptions. At most one handler will
-be executed. Handlers only handle exceptions that occur in the
-corresponding try clause, not in other handlers of the same
-\keyword{try} statement. An except clause may name multiple exceptions
-as a parenthesized tuple, for example:
-
-\begin{verbatim}
-... except (RuntimeError, TypeError, NameError):
-... pass
-\end{verbatim}
-
-The last except clause may omit the exception name(s), to serve as a
-wildcard. Use this with extreme caution, since it is easy to mask a
-real programming error in this way! It can also be used to print an
-error message and then re-raise the exception (allowing a caller to
-handle the exception as well):
-
-\begin{verbatim}
-import sys
-
-try:
- f = open('myfile.txt')
- s = f.readline()
- i = int(s.strip())
-except IOError as e:
- (errno, strerror) = e
- print "I/O error(%s): %s" % (e.errno, e.strerror)
-except ValueError:
- print "Could not convert data to an integer."
-except:
- print "Unexpected error:", sys.exc_info()[0]
- raise
-\end{verbatim}
-
-The \keyword{try} \ldots\ \keyword{except} statement has an optional
-\emph{else clause}, which, when present, must follow all except
-clauses. It is useful for code that must be executed if the try
-clause does not raise an exception. For example:
-
-\begin{verbatim}
-for arg in sys.argv[1:]:
- try:
- f = open(arg, 'r')
- except IOError:
- print 'cannot open', arg
- else:
- print arg, 'has', len(f.readlines()), 'lines'
- f.close()
-\end{verbatim}
-
-The use of the \keyword{else} clause is better than adding additional
-code to the \keyword{try} clause because it avoids accidentally
-catching an exception that wasn't raised by the code being protected
-by the \keyword{try} \ldots\ \keyword{except} statement.
-
-
-When an exception occurs, it may have an associated value, also known as
-the exception's \emph{argument}.
-The presence and type of the argument depend on the exception type.
-
-The except clause may specify a variable after the exception name (or tuple).
-The variable is bound to an exception instance with the arguments stored
-in \code{instance.args}. For convenience, the exception instance
-defines \method{__getitem__} and \method{__str__} so the arguments can
-be accessed or printed directly without having to reference \code{.args}.
-
-But use of \code{.args} is discouraged. Instead, the preferred use is to pass
-a single argument to an exception (which can be a tuple if multiple arguments
-are needed) and have it bound to the \code{message} attribute. One may also
-instantiate an exception first before raising it and add any attributes to it
-as desired.
-
-\begin{verbatim}
->>> try:
-... raise Exception('spam', 'eggs')
-... except Exception as inst:
-... print type(inst) # the exception instance
-... print inst.args # arguments stored in .args
-... print inst # __str__ allows args to printed directly
-... x, y = inst # __getitem__ allows args to be unpacked directly
-... print 'x =', x
-... print 'y =', y
-...
-<type 'Exception'>
-('spam', 'eggs')
-('spam', 'eggs')
-x = spam
-y = eggs
-\end{verbatim}
-
-If an exception has an argument, it is printed as the last part
-(`detail') of the message for unhandled exceptions.
-
-Exception handlers don't just handle exceptions if they occur
-immediately in the try clause, but also if they occur inside functions
-that are called (even indirectly) in the try clause.
-For example:
-
-\begin{verbatim}
->>> def this_fails():
-... x = 1/0
-...
->>> try:
-... this_fails()
-... except ZeroDivisionError as detail:
-... print 'Handling run-time error:', detail
-...
-Handling run-time error: integer division or modulo by zero
-\end{verbatim}
-
-
-\section{Raising Exceptions \label{raising}}
-
-The \keyword{raise} statement allows the programmer to force a
-specified exception to occur.
-For example:
-
-\begin{verbatim}
->>> raise NameError, 'HiThere'
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-NameError: HiThere
-\end{verbatim}
-
-The first argument to \keyword{raise} names the exception to be
-raised. The optional second argument specifies the exception's
-argument. Alternatively, the above could be written as
-\code{raise NameError('HiThere')}. Either form works fine, but there
-seems to be a growing stylistic preference for the latter.
-
-If you need to determine whether an exception was raised but don't
-intend to handle it, a simpler form of the \keyword{raise} statement
-allows you to re-raise the exception:
-
-\begin{verbatim}
->>> try:
-... raise NameError, 'HiThere'
-... except NameError:
-... print 'An exception flew by!'
-... raise
-...
-An exception flew by!
-Traceback (most recent call last):
- File "<stdin>", line 2, in ?
-NameError: HiThere
-\end{verbatim}
-
-
-\section{User-defined Exceptions \label{userExceptions}}
-
-Programs may name their own exceptions by creating a new exception
-class. Exceptions should typically be derived from the
-\exception{Exception} class, either directly or indirectly. For
-example:
-
-\begin{verbatim}
->>> class MyError(Exception):
-... def __init__(self, value):
-... self.value = value
-... def __str__(self):
-... return repr(self.value)
-...
->>> try:
-... raise MyError(2*2)
-... except MyError as e:
-... print 'My exception occurred, value:', e.value
-...
-My exception occurred, value: 4
->>> raise MyError, 'oops!'
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-__main__.MyError: 'oops!'
-\end{verbatim}
-
-In this example, the default \method{__init__} of \class{Exception}
-has been overridden. The new behavior simply creates the \var{value}
-attribute. This replaces the default behavior of creating the
-\var{args} attribute.
-
-Exception classes can be defined which do anything any other class can
-do, but are usually kept simple, often only offering a number of
-attributes that allow information about the error to be extracted by
-handlers for the exception. When creating a module that can raise
-several distinct errors, a common practice is to create a base class
-for exceptions defined by that module, and subclass that to create
-specific exception classes for different error conditions:
-
-\begin{verbatim}
-class Error(Exception):
- """Base class for exceptions in this module."""
- pass
-
-class InputError(Error):
- """Exception raised for errors in the input.
-
- Attributes:
- expression -- input expression in which the error occurred
- message -- explanation of the error
- """
-
- def __init__(self, expression, message):
- self.expression = expression
- self.message = message
-
-class TransitionError(Error):
- """Raised when an operation attempts a state transition that's not
- allowed.
-
- Attributes:
- previous -- state at beginning of transition
- next -- attempted new state
- message -- explanation of why the specific transition is not allowed
- """
-
- def __init__(self, previous, next, message):
- self.previous = previous
- self.next = next
- self.message = message
-\end{verbatim}
-
-Most exceptions are defined with names that end in ``Error,'' similar
-to the naming of the standard exceptions.
-
-Many standard modules define their own exceptions to report errors
-that may occur in functions they define. More information on classes
-is presented in chapter \ref{classes}, ``Classes.''
-
-
-\section{Defining Clean-up Actions \label{cleanup}}
-
-The \keyword{try} statement has another optional clause which is
-intended to define clean-up actions that must be executed under all
-circumstances. For example:
-
-\begin{verbatim}
->>> try:
-... raise KeyboardInterrupt
-... finally:
-... print 'Goodbye, world!'
-...
-Goodbye, world!
-Traceback (most recent call last):
- File "<stdin>", line 2, in ?
-KeyboardInterrupt
-\end{verbatim}
-
-A \emph{finally clause} is always executed before leaving the
-\keyword{try} statement, whether an exception has occurred or not.
-When an exception has occurred in the \keyword{try} clause and has not
-been handled by an \keyword{except} clause (or it has occurred in a
-\keyword{except} or \keyword{else} clause), it is re-raised after the
-\keyword{finally} clause has been executed. The \keyword{finally} clause
-is also executed ``on the way out'' when any other clause of the
-\keyword{try} statement is left via a \keyword{break}, \keyword{continue}
-or \keyword{return} statement. A more complicated example (having
-\keyword{except} and \keyword{finally} clauses in the same \keyword{try}
-statement works as of Python 2.5):
-
-\begin{verbatim}
->>> def divide(x, y):
-... try:
-... result = x / y
-... except ZeroDivisionError:
-... print "division by zero!"
-... else:
-... print "result is", result
-... finally:
-... print "executing finally clause"
-...
->>> divide(2, 1)
-result is 2
-executing finally clause
->>> divide(2, 0)
-division by zero!
-executing finally clause
->>> divide("2", "1")
-executing finally clause
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
- File "<stdin>", line 3, in divide
-TypeError: unsupported operand type(s) for /: 'str' and 'str'
-\end{verbatim}
-
-As you can see, the \keyword{finally} clause is executed in any
-event. The \exception{TypeError} raised by dividing two strings
-is not handled by the \keyword{except} clause and therefore
-re-raised after the \keyword{finally} clauses has been executed.
-
-In real world applications, the \keyword{finally} clause is useful
-for releasing external resources (such as files or network connections),
-regardless of whether the use of the resource was successful.
-
-
-\section{Predefined Clean-up Actions \label{cleanup-with}}
-
-Some objects define standard clean-up actions to be undertaken when
-the object is no longer needed, regardless of whether or not the
-operation using the object succeeded or failed.
-Look at the following example, which tries to open a file and print
-its contents to the screen.
-
-\begin{verbatim}
-for line in open("myfile.txt"):
- print line
-\end{verbatim}
-
-The problem with this code is that it leaves the file open for an
-indeterminate amount of time after the code has finished executing.
-This is not an issue in simple scripts, but can be a problem for
-larger applications. The \keyword{with} statement allows
-objects like files to be used in a way that ensures they are
-always cleaned up promptly and correctly.
-
-\begin{verbatim}
-with open("myfile.txt") as f:
- for line in f:
- print line
-\end{verbatim}
-
-After the statement is executed, the file \var{f} is always closed,
-even if a problem was encountered while processing the lines. Other
-objects which provide predefined clean-up actions will indicate
-this in their documentation.
-
-
-\chapter{Classes \label{classes}}
-
-Python's class mechanism adds classes to the language with a minimum
-of new syntax and semantics. It is a mixture of the class mechanisms
-found in \Cpp{} and Modula-3. As is true for modules, classes in Python
-do not put an absolute barrier between definition and user, but rather
-rely on the politeness of the user not to ``break into the
-definition.'' The most important features of classes are retained
-with full power, however: the class inheritance mechanism allows
-multiple base classes, a derived class can override any methods of its
-base class or classes, and a method can call the method of a base class with the
-same name. Objects can contain an arbitrary amount of private data.
-
-In \Cpp{} terminology, all class members (including the data members) are
-\emph{public}, and all member functions are \emph{virtual}. There are
-no special constructors or destructors. As in Modula-3, there are no
-shorthands for referencing the object's members from its methods: the
-method function is declared with an explicit first argument
-representing the object, which is provided implicitly by the call. As
-in Smalltalk, classes themselves are objects, albeit in the wider
-sense of the word: in Python, all data types are objects. This
-provides semantics for importing and renaming. Unlike
-\Cpp{} and Modula-3, built-in types can be used as base classes for
-extension by the user. Also, like in \Cpp{} but unlike in Modula-3, most
-built-in operators with special syntax (arithmetic operators,
-subscripting etc.) can be redefined for class instances.
-
-\section{A Word About Terminology \label{terminology}}
-
-Lacking universally accepted terminology to talk about classes, I will
-make occasional use of Smalltalk and \Cpp{} terms. (I would use Modula-3
-terms, since its object-oriented semantics are closer to those of
-Python than \Cpp, but I expect that few readers have heard of it.)
-
-Objects have individuality, and multiple names (in multiple scopes)
-can be bound to the same object. This is known as aliasing in other
-languages. This is usually not appreciated on a first glance at
-Python, and can be safely ignored when dealing with immutable basic
-types (numbers, strings, tuples). However, aliasing has an
-(intended!) effect on the semantics of Python code involving mutable
-objects such as lists, dictionaries, and most types representing
-entities outside the program (files, windows, etc.). This is usually
-used to the benefit of the program, since aliases behave like pointers
-in some respects. For example, passing an object is cheap since only
-a pointer is passed by the implementation; and if a function modifies
-an object passed as an argument, the caller will see the change --- this
-eliminates the need for two different argument passing mechanisms as in
-Pascal.
-
-
-\section{Python Scopes and Name Spaces \label{scopes}}
-
-Before introducing classes, I first have to tell you something about
-Python's scope rules. Class definitions play some neat tricks with
-namespaces, and you need to know how scopes and namespaces work to
-fully understand what's going on. Incidentally, knowledge about this
-subject is useful for any advanced Python programmer.
-
-Let's begin with some definitions.
-
-A \emph{namespace} is a mapping from names to objects. Most
-namespaces are currently implemented as Python dictionaries, but
-that's normally not noticeable in any way (except for performance),
-and it may change in the future. Examples of namespaces are: the set
-of built-in names (functions such as \function{abs()}, and built-in
-exception names); the global names in a module; and the local names in
-a function invocation. In a sense the set of attributes of an object
-also form a namespace. The important thing to know about namespaces
-is that there is absolutely no relation between names in different
-namespaces; for instance, two different modules may both define a
-function ``maximize'' without confusion --- users of the modules must
-prefix it with the module name.
-
-By the way, I use the word \emph{attribute} for any name following a
-dot --- for example, in the expression \code{z.real}, \code{real} is
-an attribute of the object \code{z}. Strictly speaking, references to
-names in modules are attribute references: in the expression
-\code{modname.funcname}, \code{modname} is a module object and
-\code{funcname} is an attribute of it. In this case there happens to
-be a straightforward mapping between the module's attributes and the
-global names defined in the module: they share the same namespace!
-\footnote{
- Except for one thing. Module objects have a secret read-only
- attribute called \member{__dict__} which returns the dictionary
- used to implement the module's namespace; the name
- \member{__dict__} is an attribute but not a global name.
- Obviously, using this violates the abstraction of namespace
- implementation, and should be restricted to things like
- post-mortem debuggers.
-}
-
-Attributes may be read-only or writable. In the latter case,
-assignment to attributes is possible. Module attributes are writable:
-you can write \samp{modname.the_answer = 42}. Writable attributes may
-also be deleted with the \keyword{del} statement. For example,
-\samp{del modname.the_answer} will remove the attribute
-\member{the_answer} from the object named by \code{modname}.
-
-Name spaces are created at different moments and have different
-lifetimes. The namespace containing the built-in names is created
-when the Python interpreter starts up, and is never deleted. The
-global namespace for a module is created when the module definition
-is read in; normally, module namespaces also last until the
-interpreter quits. The statements executed by the top-level
-invocation of the interpreter, either read from a script file or
-interactively, are considered part of a module called
-\module{__main__}, so they have their own global namespace. (The
-built-in names actually also live in a module; this is called
-\module{__builtin__}.)
-
-The local namespace for a function is created when the function is
-called, and deleted when the function returns or raises an exception
-that is not handled within the function. (Actually, forgetting would
-be a better way to describe what actually happens.) Of course,
-recursive invocations each have their own local namespace.
-
-A \emph{scope} is a textual region of a Python program where a
-namespace is directly accessible. ``Directly accessible'' here means
-that an unqualified reference to a name attempts to find the name in
-the namespace.
-
-Although scopes are determined statically, they are used dynamically.
-At any time during execution, there are at least three nested scopes whose
-namespaces are directly accessible: the innermost scope, which is searched
-first, contains the local names; the namespaces of any enclosing
-functions, which are searched starting with the nearest enclosing scope;
-the middle scope, searched next, contains the current module's global names;
-and the outermost scope (searched last) is the namespace containing built-in
-names.
-
-If a name is declared global, then all references and assignments go
-directly to the middle scope containing the module's global names.
-Otherwise, all variables found outside of the innermost scope are read-only
-(an attempt to write to such a variable will simply create a \emph{new}
-local variable in the innermost scope, leaving the identically named
-outer variable unchanged).
-
-Usually, the local scope references the local names of the (textually)
-current function. Outside functions, the local scope references
-the same namespace as the global scope: the module's namespace.
-Class definitions place yet another namespace in the local scope.
-
-It is important to realize that scopes are determined textually: the
-global scope of a function defined in a module is that module's
-namespace, no matter from where or by what alias the function is
-called. On the other hand, the actual search for names is done
-dynamically, at run time --- however, the language definition is
-evolving towards static name resolution, at ``compile'' time, so don't
-rely on dynamic name resolution! (In fact, local variables are
-already determined statically.)
-
-A special quirk of Python is that assignments always go into the
-innermost scope. Assignments do not copy data --- they just
-bind names to objects. The same is true for deletions: the statement
-\samp{del x} removes the binding of \code{x} from the namespace
-referenced by the local scope. In fact, all operations that introduce
-new names use the local scope: in particular, import statements and
-function definitions bind the module or function name in the local
-scope. (The \keyword{global} statement can be used to indicate that
-particular variables live in the global scope.)
-
-
-\section{A First Look at Classes \label{firstClasses}}
-
-Classes introduce a little bit of new syntax, three new object types,
-and some new semantics.
-
-
-\subsection{Class Definition Syntax \label{classDefinition}}
-
-The simplest form of class definition looks like this:
-
-\begin{verbatim}
-class ClassName:
- <statement-1>
- .
- .
- .
- <statement-N>
-\end{verbatim}
-
-Class definitions, like function definitions
-(\keyword{def} statements) must be executed before they have any
-effect. (You could conceivably place a class definition in a branch
-of an \keyword{if} statement, or inside a function.)
-
-In practice, the statements inside a class definition will usually be
-function definitions, but other statements are allowed, and sometimes
-useful --- we'll come back to this later. The function definitions
-inside a class normally have a peculiar form of argument list,
-dictated by the calling conventions for methods --- again, this is
-explained later.
-
-When a class definition is entered, a new namespace is created, and
-used as the local scope --- thus, all assignments to local variables
-go into this new namespace. In particular, function definitions bind
-the name of the new function here.
-
-When a class definition is left normally (via the end), a \emph{class
-object} is created. This is basically a wrapper around the contents
-of the namespace created by the class definition; we'll learn more
-about class objects in the next section. The original local scope
-(the one in effect just before the class definition was entered) is
-reinstated, and the class object is bound here to the class name given
-in the class definition header (\class{ClassName} in the example).
-
-
-\subsection{Class Objects \label{classObjects}}
-
-Class objects support two kinds of operations: attribute references
-and instantiation.
-
-\emph{Attribute references} use the standard syntax used for all
-attribute references in Python: \code{obj.name}. Valid attribute
-names are all the names that were in the class's namespace when the
-class object was created. So, if the class definition looked like
-this:
-
-\begin{verbatim}
-class MyClass:
- "A simple example class"
- i = 12345
- def f(self):
- return 'hello world'
-\end{verbatim}
-
-then \code{MyClass.i} and \code{MyClass.f} are valid attribute
-references, returning an integer and a function object, respectively.
-Class attributes can also be assigned to, so you can change the value
-of \code{MyClass.i} by assignment. \member{__doc__} is also a valid
-attribute, returning the docstring belonging to the class: \code{"A
-simple example class"}.
-
-Class \emph{instantiation} uses function notation. Just pretend that
-the class object is a parameterless function that returns a new
-instance of the class. For example (assuming the above class):
-
-\begin{verbatim}
-x = MyClass()
-\end{verbatim}
-
-creates a new \emph{instance} of the class and assigns this object to
-the local variable \code{x}.
-
-The instantiation operation (``calling'' a class object) creates an
-empty object. Many classes like to create objects with instances
-customized to a specific initial state.
-Therefore a class may define a special method named
-\method{__init__()}, like this:
-
-\begin{verbatim}
- def __init__(self):
- self.data = []
-\end{verbatim}
-
-When a class defines an \method{__init__()} method, class
-instantiation automatically invokes \method{__init__()} for the
-newly-created class instance. So in this example, a new, initialized
-instance can be obtained by:
-
-\begin{verbatim}
-x = MyClass()
-\end{verbatim}
-
-Of course, the \method{__init__()} method may have arguments for
-greater flexibility. In that case, arguments given to the class
-instantiation operator are passed on to \method{__init__()}. For
-example,
-
-\begin{verbatim}
->>> class Complex:
-... def __init__(self, realpart, imagpart):
-... self.r = realpart
-... self.i = imagpart
-...
->>> x = Complex(3.0, -4.5)
->>> x.r, x.i
-(3.0, -4.5)
-\end{verbatim}
-
-
-\subsection{Instance Objects \label{instanceObjects}}
-
-Now what can we do with instance objects? The only operations
-understood by instance objects are attribute references. There are
-two kinds of valid attribute names, data attributes and methods.
-
-\emph{data attributes} correspond to
-``instance variables'' in Smalltalk, and to ``data members'' in
-\Cpp. Data attributes need not be declared; like local variables,
-they spring into existence when they are first assigned to. For
-example, if \code{x} is the instance of \class{MyClass} created above,
-the following piece of code will print the value \code{16}, without
-leaving a trace:
-
-\begin{verbatim}
-x.counter = 1
-while x.counter < 10:
- x.counter = x.counter * 2
-print x.counter
-del x.counter
-\end{verbatim}
-
-The other kind of instance attribute reference is a \emph{method}.
-A method is a function that ``belongs to'' an
-object. (In Python, the term method is not unique to class instances:
-other object types can have methods as well. For example, list objects have
-methods called append, insert, remove, sort, and so on. However,
-in the following discussion, we'll use the term method exclusively to mean
-methods of class instance objects, unless explicitly stated otherwise.)
-
-Valid method names of an instance object depend on its class. By
-definition, all attributes of a class that are function
-objects define corresponding methods of its instances. So in our
-example, \code{x.f} is a valid method reference, since
-\code{MyClass.f} is a function, but \code{x.i} is not, since
-\code{MyClass.i} is not. But \code{x.f} is not the same thing as
-\code{MyClass.f} --- it is a \obindex{method}\emph{method object}, not
-a function object.
-
-
-\subsection{Method Objects \label{methodObjects}}
-
-Usually, a method is called right after it is bound:
-
-\begin{verbatim}
-x.f()
-\end{verbatim}
-
-In the \class{MyClass} example, this will return the string \code{'hello world'}.
-However, it is not necessary to call a method right away:
-\code{x.f} is a method object, and can be stored away and called at a
-later time. For example:
-
-\begin{verbatim}
-xf = x.f
-while True:
- print xf()
-\end{verbatim}
-
-will continue to print \samp{hello world} until the end of time.
-
-What exactly happens when a method is called? You may have noticed
-that \code{x.f()} was called without an argument above, even though
-the function definition for \method{f} specified an argument. What
-happened to the argument? Surely Python raises an exception when a
-function that requires an argument is called without any --- even if
-the argument isn't actually used...
-
-Actually, you may have guessed the answer: the special thing about
-methods is that the object is passed as the first argument of the
-function. In our example, the call \code{x.f()} is exactly equivalent
-to \code{MyClass.f(x)}. In general, calling a method with a list of
-\var{n} arguments is equivalent to calling the corresponding function
-with an argument list that is created by inserting the method's object
-before the first argument.
-
-If you still don't understand how methods work, a look at the
-implementation can perhaps clarify matters. When an instance
-attribute is referenced that isn't a data attribute, its class is
-searched. If the name denotes a valid class attribute that is a
-function object, a method object is created by packing (pointers to)
-the instance object and the function object just found together in an
-abstract object: this is the method object. When the method object is
-called with an argument list, it is unpacked again, a new argument
-list is constructed from the instance object and the original argument
-list, and the function object is called with this new argument list.
-
-
-\section{Random Remarks \label{remarks}}
-
-% [These should perhaps be placed more carefully...]
-
-
-Data attributes override method attributes with the same name; to
-avoid accidental name conflicts, which may cause hard-to-find bugs in
-large programs, it is wise to use some kind of convention that
-minimizes the chance of conflicts. Possible conventions include
-capitalizing method names, prefixing data attribute names with a small
-unique string (perhaps just an underscore), or using verbs for methods
-and nouns for data attributes.
-
-
-Data attributes may be referenced by methods as well as by ordinary
-users (``clients'') of an object. In other words, classes are not
-usable to implement pure abstract data types. In fact, nothing in
-Python makes it possible to enforce data hiding --- it is all based
-upon convention. (On the other hand, the Python implementation,
-written in C, can completely hide implementation details and control
-access to an object if necessary; this can be used by extensions to
-Python written in C.)
-
-
-Clients should use data attributes with care --- clients may mess up
-invariants maintained by the methods by stamping on their data
-attributes. Note that clients may add data attributes of their own to
-an instance object without affecting the validity of the methods, as
-long as name conflicts are avoided --- again, a naming convention can
-save a lot of headaches here.
-
-
-There is no shorthand for referencing data attributes (or other
-methods!) from within methods. I find that this actually increases
-the readability of methods: there is no chance of confusing local
-variables and instance variables when glancing through a method.
-
-
-Often, the first argument of a method is called
-\code{self}. This is nothing more than a convention: the name
-\code{self} has absolutely no special meaning to Python. (Note,
-however, that by not following the convention your code may be less
-readable to other Python programmers, and it is also conceivable that
-a \emph{class browser} program might be written that relies upon such a
-convention.)
-
-
-Any function object that is a class attribute defines a method for
-instances of that class. It is not necessary that the function
-definition is textually enclosed in the class definition: assigning a
-function object to a local variable in the class is also ok. For
-example:
-
-\begin{verbatim}
-# Function defined outside the class
-def f1(self, x, y):
- return min(x, x+y)
-
-class C:
- f = f1
- def g(self):
- return 'hello world'
- h = g
-\end{verbatim}
-
-Now \code{f}, \code{g} and \code{h} are all attributes of class
-\class{C} that refer to function objects, and consequently they are all
-methods of instances of \class{C} --- \code{h} being exactly equivalent
-to \code{g}. Note that this practice usually only serves to confuse
-the reader of a program.
-
-
-Methods may call other methods by using method attributes of the
-\code{self} argument:
-
-\begin{verbatim}
-class Bag:
- def __init__(self):
- self.data = []
- def add(self, x):
- self.data.append(x)
- def addtwice(self, x):
- self.add(x)
- self.add(x)
-\end{verbatim}
-
-Methods may reference global names in the same way as ordinary
-functions. The global scope associated with a method is the module
-containing the class definition. (The class itself is never used as a
-global scope!) While one rarely encounters a good reason for using
-global data in a method, there are many legitimate uses of the global
-scope: for one thing, functions and modules imported into the global
-scope can be used by methods, as well as functions and classes defined
-in it. Usually, the class containing the method is itself defined in
-this global scope, and in the next section we'll find some good
-reasons why a method would want to reference its own class!
-
-
-\section{Inheritance \label{inheritance}}
-
-Of course, a language feature would not be worthy of the name ``class''
-without supporting inheritance. The syntax for a derived class
-definition looks like this:
-
-\begin{verbatim}
-class DerivedClassName(BaseClassName):
- <statement-1>
- .
- .
- .
- <statement-N>
-\end{verbatim}
-
-The name \class{BaseClassName} must be defined in a scope containing
-the derived class definition. In place of a base class name, other
-arbitrary expressions are also allowed. This can be useful, for
-example, when the base class is defined in another module:
-
-\begin{verbatim}
-class DerivedClassName(modname.BaseClassName):
-\end{verbatim}
-
-Execution of a derived class definition proceeds the same as for a
-base class. When the class object is constructed, the base class is
-remembered. This is used for resolving attribute references: if a
-requested attribute is not found in the class, the search proceeds to look in the
-base class. This rule is applied recursively if the base class itself
-is derived from some other class.
-
-There's nothing special about instantiation of derived classes:
-\code{DerivedClassName()} creates a new instance of the class. Method
-references are resolved as follows: the corresponding class attribute
-is searched, descending down the chain of base classes if necessary,
-and the method reference is valid if this yields a function object.
-
-Derived classes may override methods of their base classes. Because
-methods have no special privileges when calling other methods of the
-same object, a method of a base class that calls another method
-defined in the same base class may end up calling a method of
-a derived class that overrides it. (For \Cpp{} programmers: all methods
-in Python are effectively \keyword{virtual}.)
-
-An overriding method in a derived class may in fact want to extend
-rather than simply replace the base class method of the same name.
-There is a simple way to call the base class method directly: just
-call \samp{BaseClassName.methodname(self, arguments)}. This is
-occasionally useful to clients as well. (Note that this only works if
-the base class is defined or imported directly in the global scope.)
-
-
-\subsection{Multiple Inheritance \label{multiple}}
-
-Python supports a limited form of multiple inheritance as well. A
-class definition with multiple base classes looks like this:
-
-\begin{verbatim}
-class DerivedClassName(Base1, Base2, Base3):
- <statement-1>
- .
- .
- .
- <statement-N>
-\end{verbatim}
-
-For old-style classes, the only rule is depth-first,
-left-to-right. Thus, if an attribute is not found in
-\class{DerivedClassName}, it is searched in \class{Base1}, then
-(recursively) in the base classes of \class{Base1}, and only if it is
-not found there, it is searched in \class{Base2}, and so on.
-
-(To some people breadth first --- searching \class{Base2} and
-\class{Base3} before the base classes of \class{Base1} --- looks more
-natural. However, this would require you to know whether a particular
-attribute of \class{Base1} is actually defined in \class{Base1} or in
-one of its base classes before you can figure out the consequences of
-a name conflict with an attribute of \class{Base2}. The depth-first
-rule makes no differences between direct and inherited attributes of
-\class{Base1}.)
-
-For new-style classes, the method resolution order changes dynamically
-to support cooperative calls to \function{super()}. This approach
-is known in some other multiple-inheritance languages as call-next-method
-and is more powerful than the super call found in single-inheritance languages.
-
-With new-style classes, dynamic ordering is necessary because all
-cases of multiple inheritance exhibit one or more diamond relationships
-(where one at least one of the parent classes can be accessed through
-multiple paths from the bottommost class). For example, all new-style
-classes inherit from \class{object}, so any case of multiple inheritance
-provides more than one path to reach \class{object}. To keep the
-base classes from being accessed more than once, the dynamic algorithm
-linearizes the search order in a way that preserves the left-to-right
-ordering specified in each class, that calls each parent only once, and
-that is monotonic (meaning that a class can be subclassed without affecting
-the precedence order of its parents). Taken together, these properties
-make it possible to design reliable and extensible classes with
-multiple inheritance. For more detail, see
-\url{http://www.python.org/download/releases/2.3/mro/}.
-
-
-\section{Private Variables \label{private}}
-
-There is limited support for class-private
-identifiers. Any identifier of the form \code{__spam} (at least two
-leading underscores, at most one trailing underscore) is textually
-replaced with \code{_classname__spam}, where \code{classname} is the
-current class name with leading underscore(s) stripped. This mangling
-is done without regard to the syntactic position of the identifier, so
-it can be used to define class-private instance and class variables,
-methods, variables stored in globals, and even variables stored in instances.
-private to this class on instances of \emph{other} classes. Truncation
-may occur when the mangled name would be longer than 255 characters.
-Outside classes, or when the class name consists of only underscores,
-no mangling occurs.
-
-Name mangling is intended to give classes an easy way to define
-``private'' instance variables and methods, without having to worry
-about instance variables defined by derived classes, or mucking with
-instance variables by code outside the class. Note that the mangling
-rules are designed mostly to avoid accidents; it still is possible for
-a determined soul to access or modify a variable that is considered
-private. This can even be useful in special circumstances, such as in
-the debugger, and that's one reason why this loophole is not closed.
-(Buglet: derivation of a class with the same name as the base class
-makes use of private variables of the base class possible.)
-
-Notice that code passed to \code{exec()} or \code{eval()}
-does not consider the classname of the invoking
-class to be the current class; this is similar to the effect of the
-\code{global} statement, the effect of which is likewise restricted to
-code that is byte-compiled together. The same restriction applies to
-\code{getattr()}, \code{setattr()} and \code{delattr()}, as well as
-when referencing \code{__dict__} directly.
-
-
-\section{Odds and Ends \label{odds}}
-
-Sometimes it is useful to have a data type similar to the Pascal
-``record'' or C ``struct'', bundling together a few named data
-items. An empty class definition will do nicely:
-
-\begin{verbatim}
-class Employee:
- pass
-
-john = Employee() # Create an empty employee record
-
-# Fill the fields of the record
-john.name = 'John Doe'
-john.dept = 'computer lab'
-john.salary = 1000
-\end{verbatim}
-
-A piece of Python code that expects a particular abstract data type
-can often be passed a class that emulates the methods of that data
-type instead. For instance, if you have a function that formats some
-data from a file object, you can define a class with methods
-\method{read()} and \method{readline()} that get the data from a string
-buffer instead, and pass it as an argument.% (Unfortunately, this
-%technique has its limitations: a class can't define operations that
-%are accessed by special syntax such as sequence subscripting or
-%arithmetic operators, and assigning such a ``pseudo-file'' to
-%\code{sys.stdin} will not cause the interpreter to read further input
-%from it.)
-
-
-Instance method objects have attributes, too: \code{m.im_self} is the
-instance object with the method \method{m}, and \code{m.im_func} is the
-function object corresponding to the method.
-
-
-\section{Exceptions Are Classes Too\label{exceptionClasses}}
-
-User-defined exceptions are identified by classes as well. Using this
-mechanism it is possible to create extensible hierarchies of exceptions.
-
-There are two new valid (semantic) forms for the raise statement:
-
-\begin{verbatim}
-raise Class, instance
-
-raise instance
-\end{verbatim}
-
-In the first form, \code{instance} must be an instance of
-\class{Class} or of a class derived from it. The second form is a
-shorthand for:
-
-\begin{verbatim}
-raise instance.__class__, instance
-\end{verbatim}
-
-A class in an except clause is compatible with an exception if it is the same
-class or a base class thereof (but not the other way around --- an
-except clause listing a derived class is not compatible with a base
-class). For example, the following code will print B, C, D in that
-order:
-
-\begin{verbatim}
-class B:
- pass
-class C(B):
- pass
-class D(C):
- pass
-
-for c in [B, C, D]:
- try:
- raise c()
- except D:
- print "D"
- except C:
- print "C"
- except B:
- print "B"
-\end{verbatim}
-
-Note that if the except clauses were reversed (with
-\samp{except B} first), it would have printed B, B, B --- the first
-matching except clause is triggered.
-
-When an error message is printed for an unhandled exception, the
-exception's class name is printed, then a colon and a space, and
-finally the instance converted to a string using the built-in function
-\function{str()}.
-
-
-\section{Iterators\label{iterators}}
-
-By now you have probably noticed that most container objects can be looped
-over using a \keyword{for} statement:
-
-\begin{verbatim}
-for element in [1, 2, 3]:
- print element
-for element in (1, 2, 3):
- print element
-for key in {'one':1, 'two':2}:
- print key
-for char in "123":
- print char
-for line in open("myfile.txt"):
- print line
-\end{verbatim}
-
-This style of access is clear, concise, and convenient. The use of iterators
-pervades and unifies Python. Behind the scenes, the \keyword{for}
-statement calls \function{iter()} on the container object. The
-function returns an iterator object that defines the method
-\method{__next__()} which accesses elements in the container one at a
-time. When there are no more elements, \method{__next__()} raises a
-\exception{StopIteration} exception which tells the \keyword{for} loop
-to terminate. You can call the \method{__next__()} method using the
-\function{next()} builtin; this example shows how it all works:
-
-\begin{verbatim}
->>> s = 'abc'
->>> it = iter(s)
->>> it
-<iterator object at 0x00A1DB50>
->>> next(it)
-'a'
->>> next(it)
-'b'
->>> next(it)
-'c'
->>> next(it)
-
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
- next(it)
-StopIteration
-\end{verbatim}
-
-Having seen the mechanics behind the iterator protocol, it is easy to add
-iterator behavior to your classes. Define a \method{__iter__()} method
-which returns an object with a \method{__next__()} method. If the class defines
-\method{__next__()}, then \method{__iter__()} can just return \code{self}:
-
-\begin{verbatim}
-class Reverse:
- "Iterator for looping over a sequence backwards"
- def __init__(self, data):
- self.data = data
- self.index = len(data)
- def __iter__(self):
- return self
- def __next__(self):
- if self.index == 0:
- raise StopIteration
- self.index = self.index - 1
- return self.data[self.index]
-
->>> for char in Reverse('spam'):
-... print char
-...
-m
-a
-p
-s
-\end{verbatim}
-
-
-\section{Generators\label{generators}}
-
-Generators are a simple and powerful tool for creating iterators. They are
-written like regular functions but use the \keyword{yield} statement whenever
-they want to return data. Each time \function{next()} is called on it, the
-generator resumes where it left-off (it remembers all the data values and
-which statement was last executed). An example shows that generators can
-be trivially easy to create:
-
-\begin{verbatim}
-def reverse(data):
- for index in range(len(data)-1, -1, -1):
- yield data[index]
-
->>> for char in reverse('golf'):
-... print char
-...
-f
-l
-o
-g
-\end{verbatim}
-
-Anything that can be done with generators can also be done with class based
-iterators as described in the previous section. What makes generators so
-compact is that the \method{__iter__()} and \method{__next__()} methods are
-created automatically.
-
-Another key feature is that the local variables and execution state
-are automatically saved between calls. This made the function easier to write
-and much more clear than an approach using instance variables like
-\code{self.index} and \code{self.data}.
-
-In addition to automatic method creation and saving program state, when
-generators terminate, they automatically raise \exception{StopIteration}.
-In combination, these features make it easy to create iterators with no
-more effort than writing a regular function.
-
-\section{Generator Expressions\label{genexps}}
-
-Some simple generators can be coded succinctly as expressions using a syntax
-similar to list comprehensions but with parentheses instead of brackets. These
-expressions are designed for situations where the generator is used right
-away by an enclosing function. Generator expressions are more compact but
-less versatile than full generator definitions and tend to be more memory
-friendly than equivalent list comprehensions.
-
-Examples:
-
-\begin{verbatim}
->>> sum(i*i for i in range(10)) # sum of squares
-285
-
->>> xvec = [10, 20, 30]
->>> yvec = [7, 5, 3]
->>> sum(x*y for x,y in zip(xvec, yvec)) # dot product
-260
-
->>> from math import pi, sin
->>> sine_table = dict((x, sin(x*pi/180)) for x in range(0, 91))
-
->>> unique_words = set(word for line in page for word in line.split())
-
->>> valedictorian = max((student.gpa, student.name) for student in graduates)
-
->>> data = 'golf'
->>> list(data[i] for i in range(len(data)-1,-1,-1))
-['f', 'l', 'o', 'g']
-
-\end{verbatim}
-
-
-
-\chapter{Brief Tour of the Standard Library \label{briefTour}}
-
-
-\section{Operating System Interface\label{os-interface}}
-
-The \ulink{\module{os}}{../lib/module-os.html}
-module provides dozens of functions for interacting with the
-operating system:
-
-\begin{verbatim}
->>> import os
->>> os.system('time 0:02')
-0
->>> os.getcwd() # Return the current working directory
-'C:\\Python30'
->>> os.chdir('/server/accesslogs')
-\end{verbatim}
-
-Be sure to use the \samp{import os} style instead of
-\samp{from os import *}. This will keep \function{os.open()} from
-shadowing the builtin \function{open()} function which operates much
-differently.
-
-\bifuncindex{help}
-The builtin \function{dir()} and \function{help()} functions are useful
-as interactive aids for working with large modules like \module{os}:
-
-\begin{verbatim}
->>> import os
->>> dir(os)
-<returns a list of all module functions>
->>> help(os)
-<returns an extensive manual page created from the module's docstrings>
-\end{verbatim}
-
-For daily file and directory management tasks, the
-\ulink{\module{shutil}}{../lib/module-shutil.html}
-module provides a higher level interface that is easier to use:
-
-\begin{verbatim}
->>> import shutil
->>> shutil.copyfile('data.db', 'archive.db')
->>> shutil.move('/build/executables', 'installdir')
-\end{verbatim}
-
-
-\section{File Wildcards\label{file-wildcards}}
-
-The \ulink{\module{glob}}{../lib/module-glob.html}
-module provides a function for making file lists from directory
-wildcard searches:
-
-\begin{verbatim}
->>> import glob
->>> glob.glob('*.py')
-['primes.py', 'random.py', 'quote.py']
-\end{verbatim}
-
-
-\section{Command Line Arguments\label{command-line-arguments}}
-
-Common utility scripts often need to process command line arguments.
-These arguments are stored in the
-\ulink{\module{sys}}{../lib/module-sys.html}\ module's \var{argv}
-attribute as a list. For instance the following output results from
-running \samp{python demo.py one two three} at the command line:
-
-\begin{verbatim}
->>> import sys
->>> print sys.argv
-['demo.py', 'one', 'two', 'three']
-\end{verbatim}
-
-The \ulink{\module{getopt}}{../lib/module-getopt.html}
-module processes \var{sys.argv} using the conventions of the \UNIX{}
-\function{getopt()} function. More powerful and flexible command line
-processing is provided by the
-\ulink{\module{optparse}}{../lib/module-optparse.html} module.
-
-
-\section{Error Output Redirection and Program Termination\label{stderr}}
-
-The \ulink{\module{sys}}{../lib/module-sys.html}
-module also has attributes for \var{stdin}, \var{stdout}, and
-\var{stderr}. The latter is useful for emitting warnings and error
-messages to make them visible even when \var{stdout} has been redirected:
-
-\begin{verbatim}
->>> sys.stderr.write('Warning, log file not found starting a new one\n')
-Warning, log file not found starting a new one
-\end{verbatim}
-
-The most direct way to terminate a script is to use \samp{sys.exit()}.
-
-
-\section{String Pattern Matching\label{string-pattern-matching}}
-
-The \ulink{\module{re}}{../lib/module-re.html}
-module provides regular expression tools for advanced string processing.
-For complex matching and manipulation, regular expressions offer succinct,
-optimized solutions:
-
-\begin{verbatim}
->>> import re
->>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')
-['foot', 'fell', 'fastest']
->>> re.sub(r'(\b[a-z]+) \1', r'\1', 'cat in the the hat')
-'cat in the hat'
-\end{verbatim}
-
-When only simple capabilities are needed, string methods are preferred
-because they are easier to read and debug:
-
-\begin{verbatim}
->>> 'tea for too'.replace('too', 'two')
-'tea for two'
-\end{verbatim}
-
-\section{Mathematics\label{mathematics}}
-
-The \ulink{\module{math}}{../lib/module-math.html} module gives
-access to the underlying C library functions for floating point math:
-
-\begin{verbatim}
->>> import math
->>> math.cos(math.pi / 4.0)
-0.70710678118654757
->>> math.log(1024, 2)
-10.0
-\end{verbatim}
-
-The \ulink{\module{random}}{../lib/module-random.html}
-module provides tools for making random selections:
-
-\begin{verbatim}
->>> import random
->>> random.choice(['apple', 'pear', 'banana'])
-'apple'
->>> random.sample(range(100), 10) # sampling without replacement
-[30, 83, 16, 4, 8, 81, 41, 50, 18, 33]
->>> random.random() # random float
-0.17970987693706186
->>> random.randrange(6) # random integer chosen from range(6)
-4
-\end{verbatim}
-
-
-\section{Internet Access\label{internet-access}}
-
-There are a number of modules for accessing the internet and processing
-internet protocols. Two of the simplest are
-\ulink{\module{urllib2}}{../lib/module-urllib2.html}
-for retrieving data from urls and
-\ulink{\module{smtplib}}{../lib/module-smtplib.html}
-for sending mail:
-
-\begin{verbatim}
->>> import urllib2
->>> for line in urllib2.urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl'):
-... if 'EST' in line or 'EDT' in line: # look for Eastern Time
-... print line
-
-<BR>Nov. 25, 09:43:32 PM EST
-
->>> import smtplib
->>> server = smtplib.SMTP('localhost')
->>> server.sendmail('soothsayer@example.org', 'jcaesar@example.org',
-"""To: jcaesar@example.org
-From: soothsayer@example.org
-
-Beware the Ides of March.
-""")
->>> server.quit()
-\end{verbatim}
-
-
-\section{Dates and Times\label{dates-and-times}}
-
-The \ulink{\module{datetime}}{../lib/module-datetime.html} 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. The module also supports objects
-that are timezone aware.
-
-\begin{verbatim}
-# dates are easily constructed and formatted
->>> from datetime import date
->>> now = date.today()
->>> now
-datetime.date(2003, 12, 2)
->>> now.strftime("%m-%d-%y. %d %b %Y is a %A on the %d day of %B.")
-'12-02-03. 02 Dec 2003 is a Tuesday on the 02 day of December.'
-
-# dates support calendar arithmetic
->>> birthday = date(1964, 7, 31)
->>> age = now - birthday
->>> age.days
-14368
-\end{verbatim}
-
-
-\section{Data Compression\label{data-compression}}
-
-Common data archiving and compression formats are directly supported
-by modules including:
-\ulink{\module{zlib}}{../lib/module-zlib.html},
-\ulink{\module{gzip}}{../lib/module-gzip.html},
-\ulink{\module{bz2}}{../lib/module-bz2.html},
-\ulink{\module{zipfile}}{../lib/module-zipfile.html}, and
-\ulink{\module{tarfile}}{../lib/module-tarfile.html}.
-
-\begin{verbatim}
->>> import zlib
->>> s = 'witch which has which witches wrist watch'
->>> len(s)
-41
->>> t = zlib.compress(s)
->>> len(t)
-37
->>> zlib.decompress(t)
-'witch which has which witches wrist watch'
->>> zlib.crc32(s)
-226805979
-\end{verbatim}
-
-
-\section{Performance Measurement\label{performance-measurement}}
-
-Some Python users develop a deep interest in knowing the relative
-performance of different approaches to the same problem.
-Python provides a measurement tool that answers those questions
-immediately.
-
-For example, it may be tempting to use the tuple packing and unpacking
-feature instead of the traditional approach to swapping arguments.
-The \ulink{\module{timeit}}{../lib/module-timeit.html} module
-quickly demonstrates a modest performance advantage:
-
-\begin{verbatim}
->>> from timeit import Timer
->>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit()
-0.57535828626024577
->>> Timer('a,b = b,a', 'a=1; b=2').timeit()
-0.54962537085770791
-\end{verbatim}
-
-In contrast to \module{timeit}'s fine level of granularity, the
-\ulink{\module{profile}}{../lib/module-profile.html} and \module{pstats}
-modules provide tools for identifying time critical sections in larger blocks
-of code.
-
-
-\section{Quality Control\label{quality-control}}
-
-One approach for developing high quality software is to write tests for
-each function as it is developed and to run those tests frequently during
-the development process.
-
-The \ulink{\module{doctest}}{../lib/module-doctest.html} module provides
-a tool for scanning a module and validating tests embedded in a program's
-docstrings. Test construction is as simple as cutting-and-pasting a
-typical call along with its results into the docstring. This improves
-the documentation by providing the user with an example and it allows the
-doctest module to make sure the code remains true to the documentation:
-
-\begin{verbatim}
-def average(values):
- """Computes the arithmetic mean of a list of numbers.
-
- >>> print average([20, 30, 70])
- 40.0
- """
- return sum(values, 0.0) / len(values)
-
-import doctest
-doctest.testmod() # automatically validate the embedded tests
-\end{verbatim}
-
-The \ulink{\module{unittest}}{../lib/module-unittest.html} module is not
-as effortless as the \module{doctest} module, but it allows a more
-comprehensive set of tests to be maintained in a separate file:
-
-\begin{verbatim}
-import unittest
-
-class TestStatisticalFunctions(unittest.TestCase):
-
- def test_average(self):
- self.assertEqual(average([20, 30, 70]), 40.0)
- self.assertEqual(round(average([1, 5, 7]), 1), 4.3)
- self.assertRaises(ZeroDivisionError, average, [])
- self.assertRaises(TypeError, average, 20, 30, 70)
-
-unittest.main() # Calling from the command line invokes all tests
-\end{verbatim}
-
-\section{Batteries Included\label{batteries-included}}
-
-Python has a ``batteries included'' philosophy. This is best seen
-through the sophisticated and robust capabilities of its larger
-packages. For example:
-
-\begin{itemize}
-\item The \ulink{\module{xmlrpclib}}{../lib/module-xmlrpclib.html} and
- \ulink{\module{SimpleXMLRPCServer}}{../lib/module-SimpleXMLRPCServer.html}
- modules make implementing remote procedure calls into an almost trivial task.
- Despite the modules names, no direct knowledge or handling of XML is needed.
-\item The \ulink{\module{email}}{../lib/module-email.html} package is a library
- for managing email messages, including MIME and other RFC 2822-based message
- documents. Unlike \module{smtplib} and \module{poplib} which actually send
- and receive messages, the email package has a complete toolset for building
- or decoding complex message structures (including attachments) and for
- implementing internet encoding and header protocols.
-\item The \ulink{\module{xml.dom}}{../lib/module-xml.dom.html} and
- \ulink{\module{xml.sax}}{../lib/module-xml.sax.html} packages provide robust
- support for parsing this popular data interchange format. Likewise, the
- \ulink{\module{csv}}{../lib/module-csv.html} module supports direct reads and
- writes in a common database format. Together, these modules and packages
- greatly simplify data interchange between python applications and other
- tools.
-\item Internationalization is supported by a number of modules including
- \ulink{\module{gettext}}{../lib/module-gettext.html},
- \ulink{\module{locale}}{../lib/module-locale.html}, and the
- \ulink{\module{codecs}}{../lib/module-codecs.html} package.
-\end{itemize}
-
-\chapter{Brief Tour of the Standard Library -- Part II\label{briefTourTwo}}
-
-This second tour covers more advanced modules that support professional
-programming needs. These modules rarely occur in small scripts.
-
-
-\section{Output Formatting\label{output-formatting}}
-
-The \ulink{\module{repr}}{../lib/module-repr.html} module provides a
-version of \function{repr()} customized for abbreviated displays of large
-or deeply nested containers:
-
-\begin{verbatim}
- >>> import repr
- >>> repr.repr(set('supercalifragilisticexpialidocious'))
- "set(['a', 'c', 'd', 'e', 'f', 'g', ...])"
-\end{verbatim}
-
-The \ulink{\module{pprint}}{../lib/module-pprint.html} module offers
-more sophisticated control over printing both built-in and user defined
-objects in a way that is readable by the interpreter. When the result
-is longer than one line, the ``pretty printer'' adds line breaks and
-indentation to more clearly reveal data structure:
-
-\begin{verbatim}
- >>> import pprint
- >>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta',
- ... 'yellow'], 'blue']]]
- ...
- >>> pprint.pprint(t, width=30)
- [[[['black', 'cyan'],
- 'white',
- ['green', 'red']],
- [['magenta', 'yellow'],
- 'blue']]]
-\end{verbatim}
-
-The \ulink{\module{textwrap}}{../lib/module-textwrap.html} module
-formats paragraphs of text to fit a given screen width:
-
-\begin{verbatim}
- >>> import textwrap
- >>> doc = """The wrap() method is just like fill() except that it returns
- ... a list of strings instead of one big string with newlines to separate
- ... the wrapped lines."""
- ...
- >>> print textwrap.fill(doc, width=40)
- The wrap() method is just like fill()
- except that it returns a list of strings
- instead of one big string with newlines
- to separate the wrapped lines.
-\end{verbatim}
-
-The \ulink{\module{locale}}{../lib/module-locale.html} module accesses
-a database of culture specific data formats. The grouping attribute
-of locale's format function provides a direct way of formatting numbers
-with group separators:
-
-\begin{verbatim}
- >>> import locale
- >>> locale.setlocale(locale.LC_ALL, 'English_United States.1252')
- 'English_United States.1252'
- >>> conv = locale.localeconv() # get a mapping of conventions
- >>> x = 1234567.8
- >>> locale.format("%d", x, grouping=True)
- '1,234,567'
- >>> locale.format("%s%.*f", (conv['currency_symbol'],
- ... conv['frac_digits'], x), grouping=True)
- '$1,234,567.80'
-\end{verbatim}
-
-
-\section{Templating\label{templating}}
-
-The \ulink{\module{string}}{../lib/module-string.html} module includes a
-versatile \class{Template} class with a simplified syntax suitable for
-editing by end-users. This allows users to customize their applications
-without having to alter the application.
-
-The format uses placeholder names formed by \samp{\$} with valid Python
-identifiers (alphanumeric characters and underscores). Surrounding the
-placeholder with braces allows it to be followed by more alphanumeric letters
-with no intervening spaces. Writing \samp{\$\$} creates a single escaped
-\samp{\$}:
-
-\begin{verbatim}
->>> from string import Template
->>> t = Template('${village}folk send $$10 to $cause.')
->>> t.substitute(village='Nottingham', cause='the ditch fund')
-'Nottinghamfolk send $10 to the ditch fund.'
-\end{verbatim}
-
-The \method{substitute} method raises a \exception{KeyError} when a
-placeholder is not supplied in a dictionary or a keyword argument. For
-mail-merge style applications, user supplied data may be incomplete and the
-\method{safe_substitute} method may be more appropriate --- it will leave
-placeholders unchanged if data is missing:
-
-\begin{verbatim}
->>> t = Template('Return the $item to $owner.')
->>> d = dict(item='unladen swallow')
->>> t.substitute(d)
-Traceback (most recent call last):
- . . .
-KeyError: 'owner'
->>> t.safe_substitute(d)
-'Return the unladen swallow to $owner.'
-\end{verbatim}
-
-Template subclasses can specify a custom delimiter. For example, a batch
-renaming utility for a photo browser may elect to use percent signs for
-placeholders such as the current date, image sequence number, or file format:
-
-\begin{verbatim}
->>> import time, os.path, sys
->>> def raw_input(prompt):
-... sys.stdout.write(prompt)
-... sys.stdout.flush()
-... return sys.stdin.readline()
-...
->>> photofiles = ['img_1074.jpg', 'img_1076.jpg', 'img_1077.jpg']
->>> class BatchRename(Template):
-... delimiter = '%'
->>> fmt = raw_input('Enter rename style (%d-date %n-seqnum %f-format): ')
-Enter rename style (%d-date %n-seqnum %f-format): Ashley_%n%f
-
->>> t = BatchRename(fmt)
->>> date = time.strftime('%d%b%y')
->>> for i, filename in enumerate(photofiles):
-... base, ext = os.path.splitext(filename)
-... newname = t.substitute(d=date, n=i, f=ext)
-... print '%s --> %s' % (filename, newname)
-
-img_1074.jpg --> Ashley_0.jpg
-img_1076.jpg --> Ashley_1.jpg
-img_1077.jpg --> Ashley_2.jpg
-\end{verbatim}
-
-Another application for templating is separating program logic from the
-details of multiple output formats. This makes it possible to substitute
-custom templates for XML files, plain text reports, and HTML web reports.
-
-
-\section{Working with Binary Data Record Layouts\label{binary-formats}}
-
-The \ulink{\module{struct}}{../lib/module-struct.html} module provides
-\function{pack()} and \function{unpack()} functions for working with
-variable length binary record formats. The following example shows how
-to loop through header information in a ZIP file (with pack codes
-\code{"H"} and \code{"L"} representing two and four byte unsigned
-numbers respectively):
-
-\begin{verbatim}
- import struct
-
- data = open('myfile.zip', 'rb').read()
- start = 0
- for i in range(3): # show the first 3 file headers
- start += 14
- fields = struct.unpack('LLLHH', data[start:start+16])
- crc32, comp_size, uncomp_size, filenamesize, extra_size = fields
-
- start += 16
- filename = data[start:start+filenamesize]
- start += filenamesize
- extra = data[start:start+extra_size]
- print filename, hex(crc32), comp_size, uncomp_size
-
- start += extra_size + comp_size # skip to the next header
-\end{verbatim}
-
-
-\section{Multi-threading\label{multi-threading}}
-
-Threading is a technique for decoupling tasks which are not sequentially
-dependent. Threads can be used to improve the responsiveness of
-applications that accept user input while other tasks run in the
-background. A related use case is running I/O in parallel with
-computations in another thread.
-
-The following code shows how the high level
-\ulink{\module{threading}}{../lib/module-threading.html} module can run
-tasks in background while the main program continues to run:
-
-\begin{verbatim}
- import threading, zipfile
-
- class AsyncZip(threading.Thread):
- def __init__(self, infile, outfile):
- threading.Thread.__init__(self)
- self.infile = infile
- self.outfile = outfile
- def run(self):
- f = zipfile.ZipFile(self.outfile, 'w', zipfile.ZIP_DEFLATED)
- f.write(self.infile)
- f.close()
- print 'Finished background zip of: ', self.infile
-
- background = AsyncZip('mydata.txt', 'myarchive.zip')
- background.start()
- print 'The main program continues to run in foreground.'
-
- background.join() # Wait for the background task to finish
- print 'Main program waited until background was done.'
-\end{verbatim}
-
-The principal challenge of multi-threaded applications is coordinating
-threads that share data or other resources. To that end, the threading
-module provides a number of synchronization primitives including locks,
-events, condition variables, and semaphores.
-
-While those tools are powerful, minor design errors can result in
-problems that are difficult to reproduce. So, the preferred approach
-to task coordination is to concentrate all access to a resource
-in a single thread and then use the
-\ulink{\module{Queue}}{../lib/module-Queue.html} module to feed that
-thread with requests from other threads. Applications using
-\class{Queue} objects for inter-thread communication and coordination
-are easier to design, more readable, and more reliable.
-
-
-\section{Logging\label{logging}}
-
-The \ulink{\module{logging}}{../lib/module-logging.html} module offers
-a full featured and flexible logging system. At its simplest, log
-messages are sent to a file or to \code{sys.stderr}:
-
-\begin{verbatim}
- import logging
- logging.debug('Debugging information')
- logging.info('Informational message')
- logging.warning('Warning:config file %s not found', 'server.conf')
- logging.error('Error occurred')
- logging.critical('Critical error -- shutting down')
-\end{verbatim}
-
-This produces the following output:
-
-\begin{verbatim}
- WARNING:root:Warning:config file server.conf not found
- ERROR:root:Error occurred
- CRITICAL:root:Critical error -- shutting down
-\end{verbatim}
-
-By default, informational and debugging messages are suppressed and the
-output is sent to standard error. Other output options include routing
-messages through email, datagrams, sockets, or to an HTTP Server. New
-filters can select different routing based on message priority:
-\constant{DEBUG}, \constant{INFO}, \constant{WARNING}, \constant{ERROR},
-and \constant{CRITICAL}.
-
-The logging system can be configured directly from Python or can be
-loaded from a user editable configuration file for customized logging
-without altering the application.
-
-
-\section{Weak References\label{weak-references}}
-
-Python does automatic memory management (reference counting for most
-objects and garbage collection to eliminate cycles). The memory is
-freed shortly after the last reference to it has been eliminated.
-
-This approach works fine for most applications but occasionally there
-is a need to track objects only as long as they are being used by
-something else. Unfortunately, just tracking them creates a reference
-that makes them permanent. The
-\ulink{\module{weakref}}{../lib/module-weakref.html} module provides
-tools for tracking objects without creating a reference. When the
-object is no longer needed, it is automatically removed from a weakref
-table and a callback is triggered for weakref objects. Typical
-applications include caching objects that are expensive to create:
-
-\begin{verbatim}
- >>> import weakref, gc
- >>> class A:
- ... def __init__(self, value):
- ... self.value = value
- ... def __repr__(self):
- ... return str(self.value)
- ...
- >>> a = A(10) # create a reference
- >>> d = weakref.WeakValueDictionary()
- >>> d['primary'] = a # does not create a reference
- >>> d['primary'] # fetch the object if it is still alive
- 10
- >>> del a # remove the one reference
- >>> gc.collect() # run garbage collection right away
- 0
- >>> d['primary'] # entry was automatically removed
- Traceback (most recent call last):
- File "<pyshell#108>", line 1, in -toplevel-
- d['primary'] # entry was automatically removed
- File "C:/python30/lib/weakref.py", line 46, in __getitem__
- o = self.data[key]()
- KeyError: 'primary'
-\end{verbatim}
-
-\section{Tools for Working with Lists\label{list-tools}}
-
-Many data structure needs can be met with the built-in list type.
-However, sometimes there is a need for alternative implementations
-with different performance trade-offs.
-
-The \ulink{\module{array}}{../lib/module-array.html} module provides an
-\class{array()} object that is like a list that stores only homogenous
-data and stores it more compactly. The following example shows an array
-of numbers stored as two byte unsigned binary numbers (typecode
-\code{"H"}) rather than the usual 16 bytes per entry for regular lists
-of python int objects:
-
-\begin{verbatim}
- >>> from array import array
- >>> a = array('H', [4000, 10, 700, 22222])
- >>> sum(a)
- 26932
- >>> a[1:3]
- array('H', [10, 700])
-\end{verbatim}
-
-The \ulink{\module{collections}}{../lib/module-collections.html} module
-provides a \class{deque()} object that is like a list with faster
-appends and pops from the left side but slower lookups in the middle.
-These objects are well suited for implementing queues and breadth first
-tree searches:
-
-\begin{verbatim}
- >>> from collections import deque
- >>> d = deque(["task1", "task2", "task3"])
- >>> d.append("task4")
- >>> print "Handling", d.popleft()
- Handling task1
-
- unsearched = deque([starting_node])
- def breadth_first_search(unsearched):
- node = unsearched.popleft()
- for m in gen_moves(node):
- if is_goal(m):
- return m
- unsearched.append(m)
-\end{verbatim}
-
-In addition to alternative list implementations, the library also offers
-other tools such as the \ulink{\module{bisect}}{../lib/module-bisect.html}
-module with functions for manipulating sorted lists:
-
-\begin{verbatim}
- >>> import bisect
- >>> scores = [(100, 'perl'), (200, 'tcl'), (400, 'lua'), (500, 'python')]
- >>> bisect.insort(scores, (300, 'ruby'))
- >>> scores
- [(100, 'perl'), (200, 'tcl'), (300, 'ruby'), (400, 'lua'), (500, 'python')]
-\end{verbatim}
-
-The \ulink{\module{heapq}}{../lib/module-heapq.html} module provides
-functions for implementing heaps based on regular lists. The lowest
-valued entry is always kept at position zero. This is useful for
-applications which repeatedly access the smallest element but do not
-want to run a full list sort:
-
-\begin{verbatim}
- >>> from heapq import heapify, heappop, heappush
- >>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
- >>> heapify(data) # rearrange the list into heap order
- >>> heappush(data, -5) # add a new entry
- >>> [heappop(data) for i in range(3)] # fetch the three smallest entries
- [-5, 0, 1]
-\end{verbatim}
-
-
-\section{Decimal Floating Point Arithmetic\label{decimal-fp}}
-
-The \ulink{\module{decimal}}{../lib/module-decimal.html} module offers a
-\class{Decimal} datatype for decimal floating point arithmetic. Compared to
-the built-in \class{float} implementation of binary floating point, the new
-class is especially helpful for financial applications and other uses which
-require exact decimal representation, control over precision, control over
-rounding to meet legal or regulatory requirements, tracking of significant
-decimal places, or for applications where the user expects the results to
-match calculations done by hand.
-
-For example, calculating a 5\%{} tax on a 70 cent phone charge gives
-different results in decimal floating point and binary floating point.
-The difference becomes significant if the results are rounded to the
-nearest cent:
-
-\begin{verbatim}
->>> from decimal import *
->>> Decimal('0.70') * Decimal('1.05')
-Decimal("0.7350")
->>> .70 * 1.05
-0.73499999999999999
-\end{verbatim}
-
-The \class{Decimal} result keeps a trailing zero, automatically inferring four
-place significance from multiplicands with two place significance. Decimal reproduces
-mathematics as done by hand and avoids issues that can arise when binary
-floating point cannot exactly represent decimal quantities.
-
-Exact representation enables the \class{Decimal} class to perform
-modulo calculations and equality tests that are unsuitable for binary
-floating point:
-
-\begin{verbatim}
->>> Decimal('1.00') % Decimal('.10')
-Decimal("0.00")
->>> 1.00 % 0.10
-0.09999999999999995
-
->>> sum([Decimal('0.1')]*10) == Decimal('1.0')
-True
->>> sum([0.1]*10) == 1.0
-False
-\end{verbatim}
-
-The \module{decimal} module provides arithmetic with as much precision as
-needed:
-
-\begin{verbatim}
->>> getcontext().prec = 36
->>> Decimal(1) / Decimal(7)
-Decimal("0.142857142857142857142857142857142857")
-\end{verbatim}
-
-
-
-\chapter{What Now? \label{whatNow}}
-
-Reading this tutorial has probably reinforced your interest in using
-Python --- you should be eager to apply Python to solving your
-real-world problems. Where should you go to learn more?
-
-This tutorial is part of Python's documentation set.
-Some other documents in the set are:
-
-\begin{itemize}
-
-\item \citetitle[../lib/lib.html]{Python Library Reference}:
-
-You should browse through this manual, which gives complete (though
-terse) reference material about types, functions, and the modules in
-the standard library. The standard Python distribution includes a
-\emph{lot} of additional code. There are modules to read \UNIX{}
-mailboxes, retrieve documents via HTTP, generate random numbers, parse
-command-line options, write CGI programs, compress data, and many other tasks.
-Skimming through the Library Reference will give you an idea of
-what's available.
-
-\item \citetitle[../inst/inst.html]{Installing Python Modules}
-explains how to install external modules written by other Python
-users.
-
-\item \citetitle[../ref/ref.html]{Language Reference}: A detailed
-explanation of Python's syntax and semantics. It's heavy reading,
-but is useful as a complete guide to the language itself.
-
-\end{itemize}
-
-More Python resources:
-
-\begin{itemize}
-
-\item \url{http://www.python.org}: The major Python Web site. It contains
-code, documentation, and pointers to Python-related pages around the
-Web. This Web site is mirrored in various places around the
-world, such as Europe, Japan, and Australia; a mirror may be faster
-than the main site, depending on your geographical location.
-
-\item \url{http://docs.python.org}: Fast access to Python's
-documentation.
-
-\item \url{http://cheeseshop.python.org}:
-The Python Package Index, nicknamed the Cheese Shop,
-is an index of user-created Python modules that are available for
-download. Once you begin releasing code, you can register it
-here so that others can find it.
-
-\item \url{http://aspn.activestate.com/ASPN/Python/Cookbook/}: The
-Python Cookbook is a sizable collection of code examples, larger
-modules, and useful scripts. Particularly notable contributions are
-collected in a book also titled \citetitle{Python Cookbook} (O'Reilly
-\& Associates, ISBN 0-596-00797-3.)
-
-\end{itemize}
-
-
-For Python-related questions and problem reports, you can post to the
-newsgroup \newsgroup{comp.lang.python}, or send them to the mailing
-list at \email{python-list@python.org}. The newsgroup and mailing list
-are gatewayed, so messages posted to one will automatically be
-forwarded to the other. There are around 120 postings a day (with peaks
-up to several hundred),
-% Postings figure based on average of last six months activity as
-% reported by www.egroups.com; Jan. 2000 - June 2000: 21272 msgs / 182
-% days = 116.9 msgs / day and steadily increasing.
-asking (and answering) questions, suggesting new features, and
-announcing new modules. Before posting, be sure to check the list of
-\ulink{Frequently Asked Questions}{http://www.python.org/doc/faq/} (also called the FAQ), or look for it in the
-\file{Misc/} directory of the Python source distribution. Mailing
-list archives are available at \url{http://mail.python.org/pipermail/}.
-The FAQ answers many of the questions that come up again and again,
-and may already contain the solution for your problem.
-
-
-\appendix
-
-\chapter{Interactive Input Editing and History Substitution\label{interacting}}
-
-Some versions of the Python interpreter support editing of the current
-input line and history substitution, similar to facilities found in
-the Korn shell and the GNU Bash shell. This is implemented using the
-\emph{GNU Readline} library, which supports Emacs-style and vi-style
-editing. This library has its own documentation which I won't
-duplicate here; however, the basics are easily explained. The
-interactive editing and history described here are optionally
-available in the \UNIX{} and Cygwin versions of the interpreter.
-
-This chapter does \emph{not} document the editing facilities of Mark
-Hammond's PythonWin package or the Tk-based environment, IDLE,
-distributed with Python. The command line history recall which
-operates within DOS boxes on NT and some other DOS and Windows flavors
-is yet another beast.
-
-\section{Line Editing \label{lineEditing}}
-
-If supported, input line editing is active whenever the interpreter
-prints a primary or secondary prompt. The current line can be edited
-using the conventional Emacs control characters. The most important
-of these are: \kbd{C-A} (Control-A) moves the cursor to the beginning
-of the line, \kbd{C-E} to the end, \kbd{C-B} moves it one position to
-the left, \kbd{C-F} to the right. Backspace erases the character to
-the left of the cursor, \kbd{C-D} the character to its right.
-\kbd{C-K} kills (erases) the rest of the line to the right of the
-cursor, \kbd{C-Y} yanks back the last killed string.
-\kbd{C-underscore} undoes the last change you made; it can be repeated
-for cumulative effect.
-
-\section{History Substitution \label{history}}
-
-History substitution works as follows. All non-empty input lines
-issued are saved in a history buffer, and when a new prompt is given
-you are positioned on a new line at the bottom of this buffer.
-\kbd{C-P} moves one line up (back) in the history buffer,
-\kbd{C-N} moves one down. Any line in the history buffer can be
-edited; an asterisk appears in front of the prompt to mark a line as
-modified. Pressing the \kbd{Return} key passes the current line to
-the interpreter. \kbd{C-R} starts an incremental reverse search;
-\kbd{C-S} starts a forward search.
-
-\section{Key Bindings \label{keyBindings}}
-
-The key bindings and some other parameters of the Readline library can
-be customized by placing commands in an initialization file called
-\file{\~{}/.inputrc}. Key bindings have the form
-
-\begin{verbatim}
-key-name: function-name
-\end{verbatim}
-
-or
-
-\begin{verbatim}
-"string": function-name
-\end{verbatim}
-
-and options can be set with
-
-\begin{verbatim}
-set option-name value
-\end{verbatim}
-
-For example:
-
-\begin{verbatim}
-# I prefer vi-style editing:
-set editing-mode vi
-
-# Edit using a single line:
-set horizontal-scroll-mode On
-
-# Rebind some keys:
-Meta-h: backward-kill-word
-"\C-u": universal-argument
-"\C-x\C-r": re-read-init-file
-\end{verbatim}
-
-Note that the default binding for \kbd{Tab} in Python is to insert a
-\kbd{Tab} character instead of Readline's default filename completion
-function. If you insist, you can override this by putting
-
-\begin{verbatim}
-Tab: complete
-\end{verbatim}
-
-in your \file{\~{}/.inputrc}. (Of course, this makes it harder to
-type indented continuation lines if you're accustomed to using
-\kbd{Tab} for that purpose.)
-
-Automatic completion of variable and module names is optionally
-available. To enable it in the interpreter's interactive mode, add
-the following to your startup file:\footnote{
- Python will execute the contents of a file identified by the
- \envvar{PYTHONSTARTUP} environment variable when you start an
- interactive interpreter.}
-\refstmodindex{rlcompleter}\refbimodindex{readline}
-
-\begin{verbatim}
-import rlcompleter, readline
-readline.parse_and_bind('tab: complete')
-\end{verbatim}
-
-This binds the \kbd{Tab} key to the completion function, so hitting
-the \kbd{Tab} key twice suggests completions; it looks at Python
-statement names, the current local variables, and the available module
-names. For dotted expressions such as \code{string.a}, it will
-evaluate the expression up to the final \character{.} and then
-suggest completions from the attributes of the resulting object. Note
-that this may execute application-defined code if an object with a
-\method{__getattr__()} method is part of the expression.
-
-A more capable startup file might look like this example. Note that
-this deletes the names it creates once they are no longer needed; this
-is done since the startup file is executed in the same namespace as
-the interactive commands, and removing the names avoids creating side
-effects in the interactive environment. You may find it convenient
-to keep some of the imported modules, such as
-\ulink{\module{os}}{../lib/module-os.html}, which turn
-out to be needed in most sessions with the interpreter.
-
-\begin{verbatim}
-# Add auto-completion and a stored history file of commands to your Python
-# interactive interpreter. Requires Python 2.0+, readline. Autocomplete is
-# bound to the Esc key by default (you can change it - see readline docs).
-#
-# Store the file in ~/.pystartup, and set an environment variable to point
-# to it: "export PYTHONSTARTUP=/max/home/itamar/.pystartup" in bash.
-#
-# Note that PYTHONSTARTUP does *not* expand "~", so you have to put in the
-# full path to your home directory.
-
-import atexit
-import os
-import readline
-import rlcompleter
-
-historyPath = os.path.expanduser("~/.pyhistory")
-
-def save_history(historyPath=historyPath):
- import readline
- readline.write_history_file(historyPath)
-
-if os.path.exists(historyPath):
- readline.read_history_file(historyPath)
-
-atexit.register(save_history)
-del os, atexit, readline, rlcompleter, save_history, historyPath
-\end{verbatim}
-
-
-\section{Commentary \label{commentary}}
-
-This facility is an enormous step forward compared to earlier versions
-of the interpreter; however, some wishes are left: It would be nice if
-the proper indentation were suggested on continuation lines (the
-parser knows if an indent token is required next). The completion
-mechanism might use the interpreter's symbol table. A command to
-check (or even suggest) matching parentheses, quotes, etc., would also
-be useful.
-
-
-\chapter{Floating Point Arithmetic: Issues and Limitations\label{fp-issues}}
-\sectionauthor{Tim Peters}{tim_one@users.sourceforge.net}
-
-Floating-point numbers are represented in computer hardware as
-base 2 (binary) fractions. For example, the decimal fraction
-
-\begin{verbatim}
-0.125
-\end{verbatim}
-
-has value 1/10 + 2/100 + 5/1000, and in the same way the binary fraction
-
-\begin{verbatim}
-0.001
-\end{verbatim}
-
-has value 0/2 + 0/4 + 1/8. These two fractions have identical values,
-the only real difference being that the first is written in base 10
-fractional notation, and the second in base 2.
-
-Unfortunately, most decimal fractions cannot be represented exactly as
-binary fractions. A consequence is that, in general, the decimal
-floating-point numbers you enter are only approximated by the binary
-floating-point numbers actually stored in the machine.
-
-The problem is easier to understand at first in base 10. Consider the
-fraction 1/3. You can approximate that as a base 10 fraction:
-
-\begin{verbatim}
-0.3
-\end{verbatim}
-
-or, better,
-
-\begin{verbatim}
-0.33
-\end{verbatim}
-
-or, better,
-
-\begin{verbatim}
-0.333
-\end{verbatim}
-
-and so on. No matter how many digits you're willing to write down, the
-result will never be exactly 1/3, but will be an increasingly better
-approximation of 1/3.
-
-In the same way, no matter how many base 2 digits you're willing to
-use, the decimal value 0.1 cannot be represented exactly as a base 2
-fraction. In base 2, 1/10 is the infinitely repeating fraction
-
-\begin{verbatim}
-0.0001100110011001100110011001100110011001100110011...
-\end{verbatim}
-
-Stop at any finite number of bits, and you get an approximation. This
-is why you see things like:
-
-\begin{verbatim}
->>> 0.1
-0.10000000000000001
-\end{verbatim}
-
-On most machines today, that is what you'll see if you enter 0.1 at
-a Python prompt. You may not, though, because the number of bits
-used by the hardware to store floating-point values can vary across
-machines, and Python only prints a decimal approximation to the true
-decimal value of the binary approximation stored by the machine. On
-most machines, if Python were to print the true decimal value of
-the binary approximation stored for 0.1, it would have to display
-
-\begin{verbatim}
->>> 0.1
-0.1000000000000000055511151231257827021181583404541015625
-\end{verbatim}
-
-instead! The Python prompt uses the builtin
-\function{repr()} function to obtain a string version of everything it
-displays. For floats, \code{repr(\var{float})} rounds the true
-decimal value to 17 significant digits, giving
-
-\begin{verbatim}
-0.10000000000000001
-\end{verbatim}
-
-\code{repr(\var{float})} produces 17 significant digits because it
-turns out that's enough (on most machines) so that
-\code{eval(repr(\var{x})) == \var{x}} exactly for all finite floats
-\var{x}, but rounding to 16 digits is not enough to make that true.
-
-Note that this is in the very nature of binary floating-point: this is
-not a bug in Python, and it is not a bug in your code either. You'll
-see the same kind of thing in all languages that support your
-hardware's floating-point arithmetic (although some languages may
-not \emph{display} the difference by default, or in all output modes).
-
-Python's builtin \function{str()} function produces only 12
-significant digits, and you may wish to use that instead. It's
-unusual for \code{eval(str(\var{x}))} to reproduce \var{x}, but the
-output may be more pleasant to look at:
-
-\begin{verbatim}
->>> print str(0.1)
-0.1
-\end{verbatim}
-
-It's important to realize that this is, in a real sense, an illusion:
-the value in the machine is not exactly 1/10, you're simply rounding
-the \emph{display} of the true machine value.
-
-Other surprises follow from this one. For example, after seeing
-
-\begin{verbatim}
->>> 0.1
-0.10000000000000001
-\end{verbatim}
-
-you may be tempted to use the \function{round()} function to chop it
-back to the single digit you expect. But that makes no difference:
-
-\begin{verbatim}
->>> round(0.1, 1)
-0.10000000000000001
-\end{verbatim}
-
-The problem is that the binary floating-point value stored for "0.1"
-was already the best possible binary approximation to 1/10, so trying
-to round it again can't make it better: it was already as good as it
-gets.
-
-Another consequence is that since 0.1 is not exactly 1/10,
-summing ten values of 0.1 may not yield exactly 1.0, either:
-
-\begin{verbatim}
->>> sum = 0.0
->>> for i in range(10):
-... sum += 0.1
-...
->>> sum
-0.99999999999999989
-\end{verbatim}
-
-Binary floating-point arithmetic holds many surprises like this. The
-problem with "0.1" is explained in precise detail below, in the
-"Representation Error" section. See
-\citetitle[http://www.lahey.com/float.htm]{The Perils of Floating
-Point} for a more complete account of other common surprises.
-
-As that says near the end, ``there are no easy answers.'' Still,
-don't be unduly wary of floating-point! The errors in Python float
-operations are inherited from the floating-point hardware, and on most
-machines are on the order of no more than 1 part in 2**53 per
-operation. That's more than adequate for most tasks, but you do need
-to keep in mind that it's not decimal arithmetic, and that every float
-operation can suffer a new rounding error.
-
-While pathological cases do exist, for most casual use of
-floating-point arithmetic you'll see the result you expect in the end
-if you simply round the display of your final results to the number of
-decimal digits you expect. \function{str()} usually suffices, and for
-finer control see the discussion of Python's \code{\%} format
-operator: the \code{\%g}, \code{\%f} and \code{\%e} format codes
-supply flexible and easy ways to round float results for display.
-
-
-\section{Representation Error
- \label{fp-error}}
-
-This section explains the ``0.1'' example in detail, and shows how
-you can perform an exact analysis of cases like this yourself. Basic
-familiarity with binary floating-point representation is assumed.
-
-\dfn{Representation error} refers to the fact that some (most, actually)
-decimal fractions cannot be represented exactly as binary (base 2)
-fractions. This is the chief reason why Python (or Perl, C, \Cpp,
-Java, Fortran, and many others) often won't display the exact decimal
-number you expect:
-
-\begin{verbatim}
->>> 0.1
-0.10000000000000001
-\end{verbatim}
-
-Why is that? 1/10 is not exactly representable as a binary fraction.
-Almost all machines today (November 2000) use IEEE-754 floating point
-arithmetic, and almost all platforms map Python floats to IEEE-754
-"double precision". 754 doubles contain 53 bits of precision, so on
-input the computer strives to convert 0.1 to the closest fraction it can
-of the form \var{J}/2**\var{N} where \var{J} is an integer containing
-exactly 53 bits. Rewriting
-
-\begin{verbatim}
- 1 / 10 ~= J / (2**N)
-\end{verbatim}
-
-as
-
-\begin{verbatim}
-J ~= 2**N / 10
-\end{verbatim}
-
-and recalling that \var{J} has exactly 53 bits (is \code{>= 2**52} but
-\code{< 2**53}), the best value for \var{N} is 56:
-
-\begin{verbatim}
->>> 2**52
-4503599627370496L
->>> 2**53
-9007199254740992L
->>> 2**56/10
-7205759403792793L
-\end{verbatim}
-
-That is, 56 is the only value for \var{N} that leaves \var{J} with
-exactly 53 bits. The best possible value for \var{J} is then that
-quotient rounded:
-
-\begin{verbatim}
->>> q, r = divmod(2**56, 10)
->>> r
-6L
-\end{verbatim}
-
-Since the remainder is more than half of 10, the best approximation is
-obtained by rounding up:
-
-\begin{verbatim}
->>> q+1
-7205759403792794L
-\end{verbatim}
-
-Therefore the best possible approximation to 1/10 in 754 double
-precision is that over 2**56, or
-
-\begin{verbatim}
-7205759403792794 / 72057594037927936
-\end{verbatim}
-
-Note that since we rounded up, this is actually a little bit larger than
-1/10; if we had not rounded up, the quotient would have been a little
-bit smaller than 1/10. But in no case can it be \emph{exactly} 1/10!
-
-So the computer never ``sees'' 1/10: what it sees is the exact
-fraction given above, the best 754 double approximation it can get:
-
-\begin{verbatim}
->>> .1 * 2**56
-7205759403792794.0
-\end{verbatim}
-
-If we multiply that fraction by 10**30, we can see the (truncated)
-value of its 30 most significant decimal digits:
-
-\begin{verbatim}
->>> 7205759403792794 * 10**30 / 2**56
-100000000000000005551115123125L
-\end{verbatim}
-
-meaning that the exact number stored in the computer is approximately
-equal to the decimal value 0.100000000000000005551115123125. Rounding
-that to 17 significant digits gives the 0.10000000000000001 that Python
-displays (well, will display on any 754-conforming platform that does
-best-possible input and output conversions in its C library --- yours may
-not!).
-
-\chapter{History and License}
-\input{license}
-
-\input{glossary}
-
-\input{tut.ind}
-
-\end{document}
diff --git a/Doc/whatsnew/whatsnew20.tex b/Doc/whatsnew/whatsnew20.tex
deleted file mode 100644
index 360d7dc..0000000
--- a/Doc/whatsnew/whatsnew20.tex
+++ /dev/null
@@ -1,1337 +0,0 @@
-\documentclass{howto}
-
-% $Id$
-
-\title{What's New in Python 2.0}
-\release{1.02}
-\author{A.M. Kuchling and Moshe Zadka}
-\authoraddress{
- \strong{Python Software Foundation}\\
- Email: \email{amk@amk.ca}, \email{moshez@twistedmatrix.com}
-}
-\begin{document}
-\maketitle\tableofcontents
-
-\section{Introduction}
-
-A new release of Python, version 2.0, was released on October 16, 2000. This
-article covers the exciting new features in 2.0, highlights some other
-useful changes, and points out a few incompatible changes that may require
-rewriting code.
-
-Python's development never completely stops between releases, and a
-steady flow of bug fixes and improvements are always being submitted.
-A host of minor fixes, a few optimizations, additional docstrings, and
-better error messages went into 2.0; to list them all would be
-impossible, but they're certainly significant. Consult the
-publicly-available CVS logs if you want to see the full list. This
-progress is due to the five developers working for
-PythonLabs are now getting paid to spend their days fixing bugs,
-and also due to the improved communication resulting
-from moving to SourceForge.
-
-% ======================================================================
-\section{What About Python 1.6?}
-
-Python 1.6 can be thought of as the Contractual Obligations Python
-release. After the core development team left CNRI in May 2000, CNRI
-requested that a 1.6 release be created, containing all the work on
-Python that had been performed at CNRI. Python 1.6 therefore
-represents the state of the CVS tree as of May 2000, with the most
-significant new feature being Unicode support. Development continued
-after May, of course, so the 1.6 tree received a few fixes to ensure
-that it's forward-compatible with Python 2.0. 1.6 is therefore part
-of Python's evolution, and not a side branch.
-
-So, should you take much interest in Python 1.6? Probably not. The
-1.6final and 2.0beta1 releases were made on the same day (September 5,
-2000), the plan being to finalize Python 2.0 within a month or so. If
-you have applications to maintain, there seems little point in
-breaking things by moving to 1.6, fixing them, and then having another
-round of breakage within a month by moving to 2.0; you're better off
-just going straight to 2.0. Most of the really interesting features
-described in this document are only in 2.0, because a lot of work was
-done between May and September.
-
-% ======================================================================
-\section{New Development Process}
-
-The most important change in Python 2.0 may not be to the code at all,
-but to how Python is developed: in May 2000 the Python developers
-began using the tools made available by SourceForge for storing
-source code, tracking bug reports, and managing the queue of patch
-submissions. To report bugs or submit patches for Python 2.0, use the
-bug tracking and patch manager tools available from Python's project
-page, located at \url{http://sourceforge.net/projects/python/}.
-
-The most important of the services now hosted at SourceForge is the
-Python CVS tree, the version-controlled repository containing the
-source code for Python. Previously, there were roughly 7 or so people
-who had write access to the CVS tree, and all patches had to be
-inspected and checked in by one of the people on this short list.
-Obviously, this wasn't very scalable. By moving the CVS tree to
-SourceForge, it became possible to grant write access to more people;
-as of September 2000 there were 27 people able to check in changes, a
-fourfold increase. This makes possible large-scale changes that
-wouldn't be attempted if they'd have to be filtered through the small
-group of core developers. For example, one day Peter Schneider-Kamp
-took it into his head to drop K\&R C compatibility and convert the C
-source for Python to ANSI C. After getting approval on the python-dev
-mailing list, he launched into a flurry of checkins that lasted about
-a week, other developers joined in to help, and the job was done. If
-there were only 5 people with write access, probably that task would
-have been viewed as ``nice, but not worth the time and effort needed''
-and it would never have gotten done.
-
-The shift to using SourceForge's services has resulted in a remarkable
-increase in the speed of development. Patches now get submitted,
-commented on, revised by people other than the original submitter, and
-bounced back and forth between people until the patch is deemed worth
-checking in. Bugs are tracked in one central location and can be
-assigned to a specific person for fixing, and we can count the number
-of open bugs to measure progress. This didn't come without a cost:
-developers now have more e-mail to deal with, more mailing lists to
-follow, and special tools had to be written for the new environment.
-For example, SourceForge sends default patch and bug notification
-e-mail messages that are completely unhelpful, so Ka-Ping Yee wrote an
-HTML screen-scraper that sends more useful messages.
-
-The ease of adding code caused a few initial growing pains, such as
-code was checked in before it was ready or without getting clear
-agreement from the developer group. The approval process that has
-emerged is somewhat similar to that used by the Apache group.
-Developers can vote +1, +0, -0, or -1 on a patch; +1 and -1 denote
-acceptance or rejection, while +0 and -0 mean the developer is mostly
-indifferent to the change, though with a slight positive or negative
-slant. The most significant change from the Apache model is that the
-voting is essentially advisory, letting Guido van Rossum, who has
-Benevolent Dictator For Life status, know what the general opinion is.
-He can still ignore the result of a vote, and approve or
-reject a change even if the community disagrees with him.
-
-Producing an actual patch is the last step in adding a new feature,
-and is usually easy compared to the earlier task of coming up with a
-good design. Discussions of new features can often explode into
-lengthy mailing list threads, making the discussion hard to follow,
-and no one can read every posting to python-dev. Therefore, a
-relatively formal process has been set up to write Python Enhancement
-Proposals (PEPs), modelled on the Internet RFC process. PEPs are
-draft documents that describe a proposed new feature, and are
-continually revised until the community reaches a consensus, either
-accepting or rejecting the proposal. Quoting from the introduction to
-PEP 1, ``PEP Purpose and Guidelines'':
-
-\begin{quotation}
- PEP stands for Python Enhancement Proposal. A PEP is a design
- document providing information to the Python community, or
- describing a new feature for Python. The PEP should provide a
- concise technical specification of the feature and a rationale for
- the feature.
-
- We intend PEPs to be the primary mechanisms for proposing new
- features, for collecting community input on an issue, and for
- documenting the design decisions that have gone into Python. The
- PEP author is responsible for building consensus within the
- community and documenting dissenting opinions.
-\end{quotation}
-
-Read the rest of PEP 1 for the details of the PEP editorial process,
-style, and format. PEPs are kept in the Python CVS tree on
-SourceForge, though they're not part of the Python 2.0 distribution,
-and are also available in HTML form from
-\url{http://www.python.org/peps/}. As of September 2000,
-there are 25 PEPS, ranging from PEP 201, ``Lockstep Iteration'', to
-PEP 225, ``Elementwise/Objectwise Operators''.
-
-% ======================================================================
-\section{Unicode}
-
-The largest new feature in Python 2.0 is a new fundamental data type:
-Unicode strings. Unicode uses 16-bit numbers to represent characters
-instead of the 8-bit number used by ASCII, meaning that 65,536
-distinct characters can be supported.
-
-The final interface for Unicode support was arrived at through
-countless often-stormy discussions on the python-dev mailing list, and
-mostly implemented by Marc-Andr\'e Lemburg, based on a Unicode string
-type implementation by Fredrik Lundh. A detailed explanation of the
-interface was written up as \pep{100}, ``Python Unicode Integration''.
-This article will simply cover the most significant points about the
-Unicode interfaces.
-
-In Python source code, Unicode strings are written as
-\code{u"string"}. Arbitrary Unicode characters can be written using a
-new escape sequence, \code{\e u\var{HHHH}}, where \var{HHHH} is a
-4-digit hexadecimal number from 0000 to FFFF. The existing
-\code{\e x\var{HHHH}} escape sequence can also be used, and octal
-escapes can be used for characters up to U+01FF, which is represented
-by \code{\e 777}.
-
-Unicode strings, just like regular strings, are an immutable sequence
-type. They can be indexed and sliced, but not modified in place.
-Unicode strings have an \method{encode( \optional{encoding} )} method
-that returns an 8-bit string in the desired encoding. Encodings are
-named by strings, such as \code{'ascii'}, \code{'utf-8'},
-\code{'iso-8859-1'}, or whatever. A codec API is defined for
-implementing and registering new encodings that are then available
-throughout a Python program. If an encoding isn't specified, the
-default encoding is usually 7-bit ASCII, though it can be changed for
-your Python installation by calling the
-\function{sys.setdefaultencoding(\var{encoding})} function in a
-customised version of \file{site.py}.
-
-Combining 8-bit and Unicode strings always coerces to Unicode, using
-the default ASCII encoding; the result of \code{'a' + u'bc'} is
-\code{u'abc'}.
-
-New built-in functions have been added, and existing built-ins
-modified to support Unicode:
-
-\begin{itemize}
-\item \code{unichr(\var{ch})} returns a Unicode string 1 character
-long, containing the character \var{ch}.
-
-\item \code{ord(\var{u})}, where \var{u} is a 1-character regular or Unicode string, returns the number of the character as an integer.
-
-\item \code{unicode(\var{string} \optional{, \var{encoding}}
-\optional{, \var{errors}} ) } creates a Unicode string from an 8-bit
-string. \code{encoding} is a string naming the encoding to use.
-The \code{errors} parameter specifies the treatment of characters that
-are invalid for the current encoding; passing \code{'strict'} as the
-value causes an exception to be raised on any encoding error, while
-\code{'ignore'} causes errors to be silently ignored and
-\code{'replace'} uses U+FFFD, the official replacement character, in
-case of any problems.
-
-\item The \keyword{exec} statement, and various built-ins such as
-\code{eval()}, \code{getattr()}, and \code{setattr()} will also
-accept Unicode strings as well as regular strings. (It's possible
-that the process of fixing this missed some built-ins; if you find a
-built-in function that accepts strings but doesn't accept Unicode
-strings at all, please report it as a bug.)
-
-\end{itemize}
-
-A new module, \module{unicodedata}, provides an interface to Unicode
-character properties. For example, \code{unicodedata.category(u'A')}
-returns the 2-character string 'Lu', the 'L' denoting it's a letter,
-and 'u' meaning that it's uppercase.
-\code{unicodedata.bidirectional(u'\e u0660')} returns 'AN', meaning that U+0660 is
-an Arabic number.
-
-The \module{codecs} module contains functions to look up existing encodings
-and register new ones. Unless you want to implement a
-new encoding, you'll most often use the
-\function{codecs.lookup(\var{encoding})} function, which returns a
-4-element tuple: \code{(\var{encode_func},
-\var{decode_func}, \var{stream_reader}, \var{stream_writer})}.
-
-\begin{itemize}
-\item \var{encode_func} is a function that takes a Unicode string, and
-returns a 2-tuple \code{(\var{string}, \var{length})}. \var{string}
-is an 8-bit string containing a portion (perhaps all) of the Unicode
-string converted into the given encoding, and \var{length} tells you
-how much of the Unicode string was converted.
-
-\item \var{decode_func} is the opposite of \var{encode_func}, taking
-an 8-bit string and returning a 2-tuple \code{(\var{ustring},
-\var{length})}, consisting of the resulting Unicode string
-\var{ustring} and the integer \var{length} telling how much of the
-8-bit string was consumed.
-
-\item \var{stream_reader} is a class that supports decoding input from
-a stream. \var{stream_reader(\var{file_obj})} returns an object that
-supports the \method{read()}, \method{readline()}, and
-\method{readlines()} methods. These methods will all translate from
-the given encoding and return Unicode strings.
-
-\item \var{stream_writer}, similarly, is a class that supports
-encoding output to a stream. \var{stream_writer(\var{file_obj})}
-returns an object that supports the \method{write()} and
-\method{writelines()} methods. These methods expect Unicode strings,
-translating them to the given encoding on output.
-\end{itemize}
-
-For example, the following code writes a Unicode string into a file,
-encoding it as UTF-8:
-
-\begin{verbatim}
-import codecs
-
-unistr = u'\u0660\u2000ab ...'
-
-(UTF8_encode, UTF8_decode,
- UTF8_streamreader, UTF8_streamwriter) = codecs.lookup('UTF-8')
-
-output = UTF8_streamwriter( open( '/tmp/output', 'wb') )
-output.write( unistr )
-output.close()
-\end{verbatim}
-
-The following code would then read UTF-8 input from the file:
-
-\begin{verbatim}
-input = UTF8_streamreader( open( '/tmp/output', 'rb') )
-print repr(input.read())
-input.close()
-\end{verbatim}
-
-Unicode-aware regular expressions are available through the
-\module{re} module, which has a new underlying implementation called
-SRE written by Fredrik Lundh of Secret Labs AB.
-
-A \code{-U} command line option was added which causes the Python
-compiler to interpret all string literals as Unicode string literals.
-This is intended to be used in testing and future-proofing your Python
-code, since some future version of Python may drop support for 8-bit
-strings and provide only Unicode strings.
-
-% ======================================================================
-\section{List Comprehensions}
-
-Lists are a workhorse data type in Python, and many programs
-manipulate a list at some point. Two common operations on lists are
-to loop over them, and either pick out the elements that meet a
-certain criterion, or apply some function to each element. For
-example, given a list of strings, you might want to pull out all the
-strings containing a given substring, or strip off trailing whitespace
-from each line.
-
-The existing \function{map()} and \function{filter()} functions can be
-used for this purpose, but they require a function as one of their
-arguments. This is fine if there's an existing built-in function that
-can be passed directly, but if there isn't, you have to create a
-little function to do the required work, and Python's scoping rules
-make the result ugly if the little function needs additional
-information. Take the first example in the previous paragraph,
-finding all the strings in the list containing a given substring. You
-could write the following to do it:
-
-\begin{verbatim}
-# Given the list L, make a list of all strings
-# containing the substring S.
-sublist = filter( lambda s, substring=S:
- string.find(s, substring) != -1,
- L)
-\end{verbatim}
-
-Because of Python's scoping rules, a default argument is used so that
-the anonymous function created by the \keyword{lambda} statement knows
-what substring is being searched for. List comprehensions make this
-cleaner:
-
-\begin{verbatim}
-sublist = [ s for s in L if string.find(s, S) != -1 ]
-\end{verbatim}
-
-List comprehensions have the form:
-
-\begin{verbatim}
-[ expression for expr in sequence1
- for expr2 in sequence2 ...
- for exprN in sequenceN
- if condition ]
-\end{verbatim}
-
-The \keyword{for}...\keyword{in} clauses contain the sequences to be
-iterated over. The sequences do not have to be the same length,
-because they are \emph{not} iterated over in parallel, but
-from left to right; this is explained more clearly in the following
-paragraphs. The elements of the generated list will be the successive
-values of \var{expression}. The final \keyword{if} clause is
-optional; if present, \var{expression} is only evaluated and added to
-the result if \var{condition} is true.
-
-To make the semantics very clear, a list comprehension is equivalent
-to the following Python code:
-
-\begin{verbatim}
-for expr1 in sequence1:
- for expr2 in sequence2:
- ...
- for exprN in sequenceN:
- if (condition):
- # Append the value of
- # the expression to the
- # resulting list.
-\end{verbatim}
-
-This means that when there are multiple \keyword{for}...\keyword{in} clauses,
-the resulting list 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:
-
-\begin{verbatim}
-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)]
-\end{verbatim}
-
-To avoid introducing an ambiguity into Python's grammar, if
-\var{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:
-
-\begin{verbatim}
-# Syntax error
-[ x,y for x in seq1 for y in seq2]
-# Correct
-[ (x,y) for x in seq1 for y in seq2]
-\end{verbatim}
-
-The idea of list comprehensions originally comes from the functional
-programming language Haskell (\url{http://www.haskell.org}). Greg
-Ewing argued most effectively for adding them to Python and wrote the
-initial list comprehension patch, which was then discussed for a
-seemingly endless time on the python-dev mailing list and kept
-up-to-date by Skip Montanaro.
-
-% ======================================================================
-\section{Augmented Assignment}
-
-Augmented assignment operators, another long-requested feature, have
-been added to Python 2.0. Augmented assignment operators include
-\code{+=}, \code{-=}, \code{*=}, and so forth. For example, the
-statement \code{a += 2} increments the value of the variable
-\code{a} by 2, equivalent to the slightly lengthier \code{a = a + 2}.
-
-% The empty groups below prevent conversion to guillemets.
-The full list of supported assignment operators is \code{+=},
-\code{-=}, \code{*=}, \code{/=}, \code{\%=}, \code{**=}, \code{\&=},
-\code{|=}, \verb|^=|, \code{>>=}, and \code{<<=}. Python classes can
-override the augmented assignment operators by defining methods named
-\method{__iadd__}, \method{__isub__}, etc. For example, the following
-\class{Number} class stores a number and supports using += to create a
-new instance with an incremented value.
-
-\begin{verbatim}
-class Number:
- def __init__(self, value):
- self.value = value
- def __iadd__(self, increment):
- return Number( self.value + increment)
-
-n = Number(5)
-n += 3
-print n.value
-\end{verbatim}
-
-The \method{__iadd__} special method is called with the value of the
-increment, and should return a new instance with an appropriately
-modified value; this return value is bound as the new value of the
-variable on the left-hand side.
-
-Augmented assignment operators were first introduced in the C
-programming language, and most C-derived languages, such as
-\program{awk}, \Cpp, Java, Perl, and PHP also support them. The augmented
-assignment patch was implemented by Thomas Wouters.
-
-% ======================================================================
-\section{String Methods}
-
-Until now string-manipulation functionality was in the \module{string}
-module, which was usually a front-end for the \module{strop}
-module written in C. The addition of Unicode posed a difficulty for
-the \module{strop} module, because the functions would all need to be
-rewritten in order to accept either 8-bit or Unicode strings. For
-functions such as \function{string.replace()}, which takes 3 string
-arguments, that means eight possible permutations, and correspondingly
-complicated code.
-
-Instead, Python 2.0 pushes the problem onto the string type, making
-string manipulation functionality available through methods on both
-8-bit strings and Unicode strings.
-
-\begin{verbatim}
->>> 'andrew'.capitalize()
-'Andrew'
->>> 'hostname'.replace('os', 'linux')
-'hlinuxtname'
->>> 'moshe'.find('sh')
-2
-\end{verbatim}
-
-One thing that hasn't changed, a noteworthy April Fools' joke
-notwithstanding, is that Python strings are immutable. Thus, the
-string methods return new strings, and do not modify the string on
-which they operate.
-
-The old \module{string} module is still around for backwards
-compatibility, but it mostly acts as a front-end to the new string
-methods.
-
-Two methods which have no parallel in pre-2.0 versions, although they
-did exist in JPython for quite some time, are \method{startswith()}
-and \method{endswith}. \code{s.startswith(t)} is equivalent to \code{s[:len(t)]
-== t}, while \code{s.endswith(t)} is equivalent to \code{s[-len(t):] == t}.
-
-One other method which deserves special mention is \method{join}. The
-\method{join} method of a string receives one parameter, a sequence of
-strings, and is equivalent to the \function{string.join} function from
-the old \module{string} module, with the arguments reversed. In other
-words, \code{s.join(seq)} is equivalent to the old
-\code{string.join(seq, s)}.
-
-% ======================================================================
-\section{Garbage Collection of Cycles}
-
-The C implementation of Python uses reference counting to implement
-garbage collection. Every Python object maintains a count of the
-number of references pointing to itself, and adjusts the count as
-references are created or destroyed. Once the reference count reaches
-zero, the object is no longer accessible, since you need to have a
-reference to an object to access it, and if the count is zero, no
-references exist any longer.
-
-Reference counting has some pleasant properties: it's easy to
-understand and implement, and the resulting implementation is
-portable, fairly fast, and reacts well with other libraries that
-implement their own memory handling schemes. The major problem with
-reference counting is that it sometimes doesn't realise that objects
-are no longer accessible, resulting in a memory leak. This happens
-when there are cycles of references.
-
-Consider the simplest possible cycle,
-a class instance which has a reference to itself:
-
-\begin{verbatim}
-instance = SomeClass()
-instance.myself = instance
-\end{verbatim}
-
-After the above two lines of code have been executed, the reference
-count of \code{instance} is 2; one reference is from the variable
-named \samp{'instance'}, and the other is from the \samp{myself}
-attribute of the instance.
-
-If the next line of code is \code{del instance}, what happens? The
-reference count of \code{instance} is decreased by 1, so it has a
-reference count of 1; the reference in the \samp{myself} attribute
-still exists. Yet the instance is no longer accessible through Python
-code, and it could be deleted. Several objects can participate in a
-cycle if they have references to each other, causing all of the
-objects to be leaked.
-
-Python 2.0 fixes this problem by periodically executing a cycle
-detection algorithm which looks for inaccessible cycles and deletes
-the objects involved. A new \module{gc} module provides functions to
-perform a garbage collection, obtain debugging statistics, and tuning
-the collector's parameters.
-
-Running the cycle detection algorithm takes some time, and therefore
-will result in some additional overhead. It is hoped that after we've
-gotten experience with the cycle collection from using 2.0, Python 2.1
-will be able to minimize the overhead with careful tuning. It's not
-yet obvious how much performance is lost, because benchmarking this is
-tricky and depends crucially on how often the program creates and
-destroys objects. The detection of cycles can be disabled when Python
-is compiled, if you can't afford even a tiny speed penalty or suspect
-that the cycle collection is buggy, by specifying the
-\longprogramopt{without-cycle-gc} switch when running the
-\program{configure} script.
-
-Several people tackled this problem and contributed to a solution. An
-early implementation of the cycle detection approach was written by
-Toby Kelsey. The current algorithm was suggested by Eric Tiedemann
-during a visit to CNRI, and Guido van Rossum and Neil Schemenauer
-wrote two different implementations, which were later integrated by
-Neil. Lots of other people offered suggestions along the way; the
-March 2000 archives of the python-dev mailing list contain most of the
-relevant discussion, especially in the threads titled ``Reference
-cycle collection for Python'' and ``Finalization again''.
-
-% ======================================================================
-\section{Other Core Changes}
-
-Various minor changes have been made to Python's syntax and built-in
-functions. None of the changes are very far-reaching, but they're
-handy conveniences.
-
-\subsection{Minor Language Changes}
-
-A new syntax makes it more convenient to call a given function
-with a tuple of arguments and/or a dictionary of keyword arguments.
-In Python 1.5 and earlier, you'd use the \function{apply()}
-built-in function: \code{apply(f, \var{args}, \var{kw})} calls the
-function \function{f()} with the argument tuple \var{args} and the
-keyword arguments in the dictionary \var{kw}. \function{apply()}
-is the same in 2.0, but thanks to a patch from
-Greg Ewing, \code{f(*\var{args}, **\var{kw})} as a shorter
-and clearer way to achieve the same effect. This syntax is
-symmetrical with the syntax for defining functions:
-
-\begin{verbatim}
-def f(*args, **kw):
- # args is a tuple of positional args,
- # kw is a dictionary of keyword args
- ...
-\end{verbatim}
-
-The \keyword{print} statement can now have its output directed to a
-file-like object by following the \keyword{print} with
-\verb|>> file|, similar to the redirection operator in \UNIX{} shells.
-Previously you'd either have to use the \method{write()} method of the
-file-like object, which lacks the convenience and simplicity of
-\keyword{print}, or you could assign a new value to
-\code{sys.stdout} and then restore the old value. For sending output to standard error,
-it's much easier to write this:
-
-\begin{verbatim}
-print >> sys.stderr, "Warning: action field not supplied"
-\end{verbatim}
-
-Modules can now be renamed on importing them, using the syntax
-\code{import \var{module} as \var{name}} or \code{from \var{module}
-import \var{name} as \var{othername}}. The patch was submitted by
-Thomas Wouters.
-
-A new format style is available when using the \code{\%} operator;
-'\%r' will insert the \function{repr()} of its argument. This was
-also added from symmetry considerations, this time for symmetry with
-the existing '\%s' format style, which inserts the \function{str()} of
-its argument. For example, \code{'\%r \%s' \% ('abc', 'abc')} returns a
-string containing \verb|'abc' abc|.
-
-Previously there was no way to implement a class that overrode
-Python's built-in \keyword{in} operator and implemented a custom
-version. \code{\var{obj} in \var{seq}} returns true if \var{obj} is
-present in the sequence \var{seq}; Python computes this by simply
-trying every index of the sequence until either \var{obj} is found or
-an \exception{IndexError} is encountered. Moshe Zadka contributed a
-patch which adds a \method{__contains__} magic method for providing a
-custom implementation for \keyword{in}. Additionally, new built-in
-objects written in C can define what \keyword{in} means for them via a
-new slot in the sequence protocol.
-
-Earlier versions of Python used a recursive algorithm for deleting
-objects. Deeply nested data structures could cause the interpreter to
-fill up the C stack and crash; Christian Tismer rewrote the deletion
-logic to fix this problem. On a related note, comparing recursive
-objects recursed infinitely and crashed; Jeremy Hylton rewrote the
-code to no longer crash, producing a useful result instead. For
-example, after this code:
-
-\begin{verbatim}
-a = []
-b = []
-a.append(a)
-b.append(b)
-\end{verbatim}
-
-The comparison \code{a==b} returns true, because the two recursive
-data structures are isomorphic. See the thread ``trashcan
-and PR\#7'' in the April 2000 archives of the python-dev mailing list
-for the discussion leading up to this implementation, and some useful
-relevant links.
-% Starting URL:
-% http://www.python.org/pipermail/python-dev/2000-April/004834.html
-
-Note that comparisons can now also raise exceptions. In earlier
-versions of Python, a comparison operation such as \code{cmp(a,b)}
-would always produce an answer, even if a user-defined
-\method{__cmp__} method encountered an error, since the resulting
-exception would simply be silently swallowed.
-
-Work has been done on porting Python to 64-bit Windows on the Itanium
-processor, mostly by Trent Mick of ActiveState. (Confusingly,
-\code{sys.platform} is still \code{'win32'} on Win64 because it seems
-that for ease of porting, MS Visual \Cpp{} treats code as 32 bit on Itanium.)
-PythonWin also supports Windows CE; see the Python CE page at
-\url{http://starship.python.net/crew/mhammond/ce/} for more
-information.
-
-Another new platform is Darwin/MacOS X; initial support for it is in
-Python 2.0. Dynamic loading works, if you specify ``configure
---with-dyld --with-suffix=.x''. Consult the README in the Python
-source distribution for more instructions.
-
-An attempt has been made to alleviate one of Python's warts, the
-often-confusing \exception{NameError} exception when code refers to a
-local variable before the variable has been assigned a value. For
-example, the following code raises an exception on the \keyword{print}
-statement in both 1.5.2 and 2.0; in 1.5.2 a \exception{NameError}
-exception is raised, while 2.0 raises a new
-\exception{UnboundLocalError} exception.
-\exception{UnboundLocalError} is a subclass of \exception{NameError},
-so any existing code that expects \exception{NameError} to be raised
-should still work.
-
-\begin{verbatim}
-def f():
- print "i=",i
- i = i + 1
-f()
-\end{verbatim}
-
-Two new exceptions, \exception{TabError} and
-\exception{IndentationError}, have been introduced. They're both
-subclasses of \exception{SyntaxError}, and are raised when Python code
-is found to be improperly indented.
-
-\subsection{Changes to Built-in Functions}
-
-A new built-in, \function{zip(\var{seq1}, \var{seq2}, ...)}, has been
-added. \function{zip()} returns a list of tuples where each tuple
-contains the i-th element from each of the argument sequences. The
-difference between \function{zip()} and \code{map(None, \var{seq1},
-\var{seq2})} is that \function{map()} pads the sequences with
-\code{None} if the sequences aren't all of the same length, while
-\function{zip()} truncates the returned list to the length of the
-shortest argument sequence.
-
-The \function{int()} and \function{long()} functions now accept an
-optional ``base'' parameter when the first argument is a string.
-\code{int('123', 10)} returns 123, while \code{int('123', 16)} returns
-291. \code{int(123, 16)} raises a \exception{TypeError} exception
-with the message ``can't convert non-string with explicit base''.
-
-A new variable holding more detailed version information has been
-added to the \module{sys} module. \code{sys.version_info} is a tuple
-\code{(\var{major}, \var{minor}, \var{micro}, \var{level},
-\var{serial})} For example, in a hypothetical 2.0.1beta1,
-\code{sys.version_info} would be \code{(2, 0, 1, 'beta', 1)}.
-\var{level} is a string such as \code{"alpha"}, \code{"beta"}, or
-\code{"final"} for a final release.
-
-Dictionaries have an odd new method, \method{setdefault(\var{key},
-\var{default})}, which behaves similarly to the existing
-\method{get()} method. However, if the key is missing,
-\method{setdefault()} both returns the value of \var{default} as
-\method{get()} would do, and also inserts it into the dictionary as
-the value for \var{key}. Thus, the following lines of code:
-
-\begin{verbatim}
-if dict.has_key( key ): return dict[key]
-else:
- dict[key] = []
- return dict[key]
-\end{verbatim}
-
-can be reduced to a single \code{return dict.setdefault(key, [])} statement.
-
-The interpreter sets a maximum recursion depth in order to catch
-runaway recursion before filling the C stack and causing a core dump
-or GPF.. Previously this limit was fixed when you compiled Python,
-but in 2.0 the maximum recursion depth can be read and modified using
-\function{sys.getrecursionlimit} and \function{sys.setrecursionlimit}.
-The default value is 1000, and a rough maximum value for a given
-platform can be found by running a new script,
-\file{Misc/find_recursionlimit.py}.
-
-% ======================================================================
-\section{Porting to 2.0}
-
-New Python releases try hard to be compatible with previous releases,
-and the record has been pretty good. However, some changes are
-considered useful enough, usually because they fix initial design decisions that
-turned out to be actively mistaken, that breaking backward compatibility
-can't always be avoided. This section lists the changes in Python 2.0
-that may cause old Python code to break.
-
-The change which will probably break the most code is tightening up
-the arguments accepted by some methods. Some methods would take
-multiple arguments and treat them as a tuple, particularly various
-list methods such as \method{.append()} and \method{.insert()}.
-In earlier versions of Python, if \code{L} is a list, \code{L.append(
-1,2 )} appends the tuple \code{(1,2)} to the list. In Python 2.0 this
-causes a \exception{TypeError} exception to be raised, with the
-message: 'append requires exactly 1 argument; 2 given'. The fix is to
-simply add an extra set of parentheses to pass both values as a tuple:
-\code{L.append( (1,2) )}.
-
-The earlier versions of these methods were more forgiving because they
-used an old function in Python's C interface to parse their arguments;
-2.0 modernizes them to use \function{PyArg_ParseTuple}, the current
-argument parsing function, which provides more helpful error messages
-and treats multi-argument calls as errors. If you absolutely must use
-2.0 but can't fix your code, you can edit \file{Objects/listobject.c}
-and define the preprocessor symbol \code{NO_STRICT_LIST_APPEND} to
-preserve the old behaviour; this isn't recommended.
-
-Some of the functions in the \module{socket} module are still
-forgiving in this way. For example, \function{socket.connect(
-('hostname', 25) )} is the correct form, passing a tuple representing
-an IP address, but \function{socket.connect( 'hostname', 25 )} also
-works. \function{socket.connect_ex()} and \function{socket.bind()} are
-similarly easy-going. 2.0alpha1 tightened these functions up, but
-because the documentation actually used the erroneous multiple
-argument form, many people wrote code which would break with the
-stricter checking. GvR backed out the changes in the face of public
-reaction, so for the \module{socket} module, the documentation was
-fixed and the multiple argument form is simply marked as deprecated;
-it \emph{will} be tightened up again in a future Python version.
-
-The \code{\e x} escape in string literals now takes exactly 2 hex
-digits. Previously it would consume all the hex digits following the
-'x' and take the lowest 8 bits of the result, so \code{\e x123456} was
-equivalent to \code{\e x56}.
-
-The \exception{AttributeError} and \exception{NameError} exceptions
-have a more friendly error message, whose text will be something like
-\code{'Spam' instance has no attribute 'eggs'} or \code{name 'eggs' is
-not defined}. Previously the error message was just the missing
-attribute name \code{eggs}, and code written to take advantage of this
-fact will break in 2.0.
-
-Some work has been done to make integers and long integers a bit more
-interchangeable. In 1.5.2, large-file support was added for Solaris,
-to allow reading files larger than 2~GiB; this made the \method{tell()}
-method of file objects return a long integer instead of a regular
-integer. Some code would subtract two file offsets and attempt to use
-the result to multiply a sequence or slice a string, but this raised a
-\exception{TypeError}. In 2.0, long integers can be used to multiply
-or slice a sequence, and it'll behave as you'd intuitively expect it
-to; \code{3L * 'abc'} produces 'abcabcabc', and \code{
-(0,1,2,3)[2L:4L]} produces (2,3). Long integers can also be used in
-various contexts where previously only integers were accepted, such
-as in the \method{seek()} method of file objects, and in the formats
-supported by the \verb|%| operator (\verb|%d|, \verb|%i|, \verb|%x|,
-etc.). For example, \code{"\%d" \% 2L**64} will produce the string
-\samp{18446744073709551616}.
-
-The subtlest long integer change of all is that the \function{str()}
-of a long integer no longer has a trailing 'L' character, though
-\function{repr()} still includes it. The 'L' annoyed many people who
-wanted to print long integers that looked just like regular integers,
-since they had to go out of their way to chop off the character. This
-is no longer a problem in 2.0, but code which does \code{str(longval)[:-1]} and assumes the 'L' is there, will now lose
-the final digit.
-
-Taking the \function{repr()} of a float now uses a different
-formatting precision than \function{str()}. \function{repr()} uses
-\code{\%.17g} format string for C's \function{sprintf()}, while
-\function{str()} uses \code{\%.12g} as before. The effect is that
-\function{repr()} may occasionally show more decimal places than
-\function{str()}, for certain numbers.
-For example, the number 8.1 can't be represented exactly in binary, so
-\code{repr(8.1)} is \code{'8.0999999999999996'}, while str(8.1) is
-\code{'8.1'}.
-
-The \code{-X} command-line option, which turned all standard
-exceptions into strings instead of classes, has been removed; the
-standard exceptions will now always be classes. The
-\module{exceptions} module containing the standard exceptions was
-translated from Python to a built-in C module, written by Barry Warsaw
-and Fredrik Lundh.
-
-% Commented out for now -- I don't think anyone will care.
-%The pattern and match objects provided by SRE are C types, not Python
-%class instances as in 1.5. This means you can no longer inherit from
-%\class{RegexObject} or \class{MatchObject}, but that shouldn't be much
-%of a problem since no one should have been doing that in the first
-%place.
-
-% ======================================================================
-\section{Extending/Embedding Changes}
-
-Some of the changes are under the covers, and will only be apparent to
-people writing C extension modules or embedding a Python interpreter
-in a larger application. If you aren't dealing with Python's C API,
-you can safely skip this section.
-
-The version number of the Python C API was incremented, so C
-extensions compiled for 1.5.2 must be recompiled in order to work with
-2.0. On Windows, it's not possible for Python 2.0 to import a third
-party extension built for Python 1.5.x due to how Windows DLLs work,
-so Python will raise an exception and the import will fail.
-
-Users of Jim Fulton's ExtensionClass module will be pleased to find
-out that hooks have been added so that ExtensionClasses are now
-supported by \function{isinstance()} and \function{issubclass()}.
-This means you no longer have to remember to write code such as
-\code{if type(obj) == myExtensionClass}, but can use the more natural
-\code{if isinstance(obj, myExtensionClass)}.
-
-The \file{Python/importdl.c} file, which was a mass of \#ifdefs to
-support dynamic loading on many different platforms, was cleaned up
-and reorganised by Greg Stein. \file{importdl.c} is now quite small,
-and platform-specific code has been moved into a bunch of
-\file{Python/dynload_*.c} files. Another cleanup: there were also a
-number of \file{my*.h} files in the Include/ directory that held
-various portability hacks; they've been merged into a single file,
-\file{Include/pyport.h}.
-
-Vladimir Marangozov's long-awaited malloc restructuring was completed,
-to make it easy to have the Python interpreter use a custom allocator
-instead of C's standard \function{malloc()}. For documentation, read
-the comments in \file{Include/pymem.h} and
-\file{Include/objimpl.h}. For the lengthy discussions during which
-the interface was hammered out, see the Web archives of the 'patches'
-and 'python-dev' lists at python.org.
-
-Recent versions of the GUSI development environment for MacOS support
-POSIX threads. Therefore, Python's POSIX threading support now works
-on the Macintosh. Threading support using the user-space GNU \texttt{pth}
-library was also contributed.
-
-Threading support on Windows was enhanced, too. Windows supports
-thread locks that use kernel objects only in case of contention; in
-the common case when there's no contention, they use simpler functions
-which are an order of magnitude faster. A threaded version of Python
-1.5.2 on NT is twice as slow as an unthreaded version; with the 2.0
-changes, the difference is only 10\%. These improvements were
-contributed by Yakov Markovitch.
-
-Python 2.0's source now uses only ANSI C prototypes, so compiling Python now
-requires an ANSI C compiler, and can no longer be done using a compiler that
-only supports K\&R C.
-
-Previously the Python virtual machine used 16-bit numbers in its
-bytecode, limiting the size of source files. In particular, this
-affected the maximum size of literal lists and dictionaries in Python
-source; occasionally people who are generating Python code would run
-into this limit. A patch by Charles G. Waldman raises the limit from
-\verb|2^16| to \verb|2^{32}|.
-
-Three new convenience functions intended for adding constants to a
-module's dictionary at module initialization time were added:
-\function{PyModule_AddObject()}, \function{PyModule_AddIntConstant()},
-and \function{PyModule_AddStringConstant()}. Each of these functions
-takes a module object, a null-terminated C string containing the name
-to be added, and a third argument for the value to be assigned to the
-name. This third argument is, respectively, a Python object, a C
-long, or a C string.
-
-A wrapper API was added for \UNIX-style signal handlers.
-\function{PyOS_getsig()} gets a signal handler and
-\function{PyOS_setsig()} will set a new handler.
-
-% ======================================================================
-\section{Distutils: Making Modules Easy to Install}
-
-Before Python 2.0, installing modules was a tedious affair -- there
-was no way to figure out automatically where Python is installed, or
-what compiler options to use for extension modules. Software authors
-had to go through an arduous ritual of editing Makefiles and
-configuration files, which only really work on \UNIX{} and leave Windows
-and MacOS unsupported. Python users faced wildly differing
-installation instructions which varied between different extension
-packages, which made administering a Python installation something of
-a chore.
-
-The SIG for distribution utilities, shepherded by Greg Ward, has
-created the Distutils, a system to make package installation much
-easier. They form the \module{distutils} package, a new part of
-Python's standard library. In the best case, installing a Python
-module from source will require the same steps: first you simply mean
-unpack the tarball or zip archive, and the run ``\code{python setup.py
-install}''. The platform will be automatically detected, the compiler
-will be recognized, C extension modules will be compiled, and the
-distribution installed into the proper directory. Optional
-command-line arguments provide more control over the installation
-process, the distutils package offers many places to override defaults
--- separating the build from the install, building or installing in
-non-default directories, and more.
-
-In order to use the Distutils, you need to write a \file{setup.py}
-script. For the simple case, when the software contains only .py
-files, a minimal \file{setup.py} can be just a few lines long:
-
-\begin{verbatim}
-from distutils.core import setup
-setup (name = "foo", version = "1.0",
- py_modules = ["module1", "module2"])
-\end{verbatim}
-
-The \file{setup.py} file isn't much more complicated if the software
-consists of a few packages:
-
-\begin{verbatim}
-from distutils.core import setup
-setup (name = "foo", version = "1.0",
- packages = ["package", "package.subpackage"])
-\end{verbatim}
-
-A C extension can be the most complicated case; here's an example taken from
-the PyXML package:
-
-
-\begin{verbatim}
-from distutils.core import setup, Extension
-
-expat_extension = Extension('xml.parsers.pyexpat',
- define_macros = [('XML_NS', None)],
- include_dirs = [ 'extensions/expat/xmltok',
- 'extensions/expat/xmlparse' ],
- sources = [ 'extensions/pyexpat.c',
- 'extensions/expat/xmltok/xmltok.c',
- 'extensions/expat/xmltok/xmlrole.c',
- ]
- )
-setup (name = "PyXML", version = "0.5.4",
- ext_modules =[ expat_extension ] )
-\end{verbatim}
-
-The Distutils can also take care of creating source and binary
-distributions. The ``sdist'' command, run by ``\code{python setup.py
-sdist}', builds a source distribution such as \file{foo-1.0.tar.gz}.
-Adding new commands isn't difficult, ``bdist_rpm'' and
-``bdist_wininst'' commands have already been contributed to create an
-RPM distribution and a Windows installer for the software,
-respectively. Commands to create other distribution formats such as
-Debian packages and Solaris \file{.pkg} files are in various stages of
-development.
-
-All this is documented in a new manual, \textit{Distributing Python
-Modules}, that joins the basic set of Python documentation.
-
-% ======================================================================
-\section{XML Modules}
-
-Python 1.5.2 included a simple XML parser in the form of the
-\module{xmllib} module, contributed by Sjoerd Mullender. Since
-1.5.2's release, two different interfaces for processing XML have
-become common: SAX2 (version 2 of the Simple API for XML) provides an
-event-driven interface with some similarities to \module{xmllib}, and
-the DOM (Document Object Model) provides a tree-based interface,
-transforming an XML document into a tree of nodes that can be
-traversed and modified. Python 2.0 includes a SAX2 interface and a
-stripped-down DOM interface as part of the \module{xml} package.
-Here we will give a brief overview of these new interfaces; consult
-the Python documentation or the source code for complete details.
-The Python XML SIG is also working on improved documentation.
-
-\subsection{SAX2 Support}
-
-SAX defines an event-driven interface for parsing XML. To use SAX,
-you must write a SAX handler class. Handler classes inherit from
-various classes provided by SAX, and override various methods that
-will then be called by the XML parser. For example, the
-\method{startElement} and \method{endElement} methods are called for
-every starting and end tag encountered by the parser, the
-\method{characters()} method is called for every chunk of character
-data, and so forth.
-
-The advantage of the event-driven approach is that the whole
-document doesn't have to be resident in memory at any one time, which
-matters if you are processing really huge documents. However, writing
-the SAX handler class can get very complicated if you're trying to
-modify the document structure in some elaborate way.
-
-For example, this little example program defines a handler that prints
-a message for every starting and ending tag, and then parses the file
-\file{hamlet.xml} using it:
-
-\begin{verbatim}
-from xml import sax
-
-class SimpleHandler(sax.ContentHandler):
- def startElement(self, name, attrs):
- print 'Start of element:', name, attrs.keys()
-
- def endElement(self, name):
- print 'End of element:', name
-
-# Create a parser object
-parser = sax.make_parser()
-
-# Tell it what handler to use
-handler = SimpleHandler()
-parser.setContentHandler( handler )
-
-# Parse a file!
-parser.parse( 'hamlet.xml' )
-\end{verbatim}
-
-For more information, consult the Python documentation, or the XML
-HOWTO at \url{http://pyxml.sourceforge.net/topics/howto/xml-howto.html}.
-
-\subsection{DOM Support}
-
-The Document Object Model is a tree-based representation for an XML
-document. A top-level \class{Document} instance is the root of the
-tree, and has a single child which is the top-level \class{Element}
-instance. This \class{Element} has children nodes representing
-character data and any sub-elements, which may have further children
-of their own, and so forth. Using the DOM you can traverse the
-resulting tree any way you like, access element and attribute values,
-insert and delete nodes, and convert the tree back into XML.
-
-The DOM is useful for modifying XML documents, because you can create
-a DOM tree, modify it by adding new nodes or rearranging subtrees, and
-then produce a new XML document as output. You can also construct a
-DOM tree manually and convert it to XML, which can be a more flexible
-way of producing XML output than simply writing
-\code{<tag1>}...\code{</tag1>} to a file.
-
-The DOM implementation included with Python lives in the
-\module{xml.dom.minidom} module. It's a lightweight implementation of
-the Level 1 DOM with support for XML namespaces. The
-\function{parse()} and \function{parseString()} convenience
-functions are provided for generating a DOM tree:
-
-\begin{verbatim}
-from xml.dom import minidom
-doc = minidom.parse('hamlet.xml')
-\end{verbatim}
-
-\code{doc} is a \class{Document} instance. \class{Document}, like all
-the other DOM classes such as \class{Element} and \class{Text}, is a
-subclass of the \class{Node} base class. All the nodes in a DOM tree
-therefore support certain common methods, such as \method{toxml()}
-which returns a string containing the XML representation of the node
-and its children. Each class also has special methods of its own; for
-example, \class{Element} and \class{Document} instances have a method
-to find all child elements with a given tag name. Continuing from the
-previous 2-line example:
-
-\begin{verbatim}
-perslist = doc.getElementsByTagName( 'PERSONA' )
-print perslist[0].toxml()
-print perslist[1].toxml()
-\end{verbatim}
-
-For the \textit{Hamlet} XML file, the above few lines output:
-
-\begin{verbatim}
-<PERSONA>CLAUDIUS, king of Denmark. </PERSONA>
-<PERSONA>HAMLET, son to the late, and nephew to the present king.</PERSONA>
-\end{verbatim}
-
-The root element of the document is available as
-\code{doc.documentElement}, and its children can be easily modified
-by deleting, adding, or removing nodes:
-
-\begin{verbatim}
-root = doc.documentElement
-
-# Remove the first child
-root.removeChild( root.childNodes[0] )
-
-# Move the new first child to the end
-root.appendChild( root.childNodes[0] )
-
-# Insert the new first child (originally,
-# the third child) before the 20th child.
-root.insertBefore( root.childNodes[0], root.childNodes[20] )
-\end{verbatim}
-
-Again, I will refer you to the Python documentation for a complete
-listing of the different \class{Node} classes and their various methods.
-
-\subsection{Relationship to PyXML}
-
-The XML Special Interest Group has been working on XML-related Python
-code for a while. Its code distribution, called PyXML, is available
-from the SIG's Web pages at \url{http://www.python.org/sigs/xml-sig/}.
-The PyXML distribution also used the package name \samp{xml}. If
-you've written programs that used PyXML, you're probably wondering
-about its compatibility with the 2.0 \module{xml} package.
-
-The answer is that Python 2.0's \module{xml} package isn't compatible
-with PyXML, but can be made compatible by installing a recent version
-PyXML. Many applications can get by with the XML support that is
-included with Python 2.0, but more complicated applications will
-require that the full PyXML package will be installed. When
-installed, PyXML versions 0.6.0 or greater will replace the
-\module{xml} package shipped with Python, and will be a strict
-superset of the standard package, adding a bunch of additional
-features. Some of the additional features in PyXML include:
-
-\begin{itemize}
-\item 4DOM, a full DOM implementation
-from FourThought, Inc.
-\item The xmlproc validating parser, written by Lars Marius Garshol.
-\item The \module{sgmlop} parser accelerator module, written by Fredrik Lundh.
-\end{itemize}
-
-% ======================================================================
-\section{Module changes}
-
-Lots of improvements and bugfixes were made to Python's extensive
-standard library; some of the affected modules include
-\module{readline}, \module{ConfigParser}, \module{cgi},
-\module{calendar}, \module{posix}, \module{readline}, \module{xmllib},
-\module{aifc}, \module{chunk, wave}, \module{random}, \module{shelve},
-and \module{nntplib}. Consult the CVS logs for the exact
-patch-by-patch details.
-
-Brian Gallew contributed OpenSSL support for the \module{socket}
-module. OpenSSL is an implementation of the Secure Socket Layer,
-which encrypts the data being sent over a socket. When compiling
-Python, you can edit \file{Modules/Setup} to include SSL support,
-which adds an additional function to the \module{socket} module:
-\function{socket.ssl(\var{socket}, \var{keyfile}, \var{certfile})},
-which takes a socket object and returns an SSL socket. The
-\module{httplib} and \module{urllib} modules were also changed to
-support ``https://'' URLs, though no one has implemented FTP or SMTP
-over SSL.
-
-The \module{httplib} module has been rewritten by Greg Stein to
-support HTTP/1.1. Backward compatibility with the 1.5 version of
-\module{httplib} is provided, though using HTTP/1.1 features such as
-pipelining will require rewriting code to use a different set of
-interfaces.
-
-The \module{Tkinter} module now supports Tcl/Tk version 8.1, 8.2, or
-8.3, and support for the older 7.x versions has been dropped. The
-Tkinter module now supports displaying Unicode strings in Tk widgets.
-Also, Fredrik Lundh contributed an optimization which makes operations
-like \code{create_line} and \code{create_polygon} much faster,
-especially when using lots of coordinates.
-
-The \module{curses} module has been greatly extended, starting from
-Oliver Andrich's enhanced version, to provide many additional
-functions from ncurses and SYSV curses, such as colour, alternative
-character set support, pads, and mouse support. This means the module
-is no longer compatible with operating systems that only have BSD
-curses, but there don't seem to be any currently maintained OSes that
-fall into this category.
-
-As mentioned in the earlier discussion of 2.0's Unicode support, the
-underlying implementation of the regular expressions provided by the
-\module{re} module has been changed. SRE, a new regular expression
-engine written by Fredrik Lundh and partially funded by Hewlett
-Packard, supports matching against both 8-bit strings and Unicode
-strings.
-
-% ======================================================================
-\section{New modules}
-
-A number of new modules were added. We'll simply list them with brief
-descriptions; consult the 2.0 documentation for the details of a
-particular module.
-
-\begin{itemize}
-
-\item{\module{atexit}}:
-For registering functions to be called before the Python interpreter exits.
-Code that currently sets
-\code{sys.exitfunc} directly should be changed to
-use the \module{atexit} module instead, importing \module{atexit}
-and calling \function{atexit.register()} with
-the function to be called on exit.
-(Contributed by Skip Montanaro.)
-
-\item{\module{codecs}, \module{encodings}, \module{unicodedata}:} Added as part of the new Unicode support.
-
-\item{\module{filecmp}:} Supersedes the old \module{cmp}, \module{cmpcache} and
-\module{dircmp} modules, which have now become deprecated.
-(Contributed by Gordon MacMillan and Moshe Zadka.)
-
-\item{\module{gettext}:} This module provides internationalization
-(I18N) and localization (L10N) support for Python programs by
-providing an interface to the GNU gettext message catalog library.
-(Integrated by Barry Warsaw, from separate contributions by Martin
-von~L\"owis, Peter Funk, and James Henstridge.)
-
-\item{\module{linuxaudiodev}:} Support for the \file{/dev/audio}
-device on Linux, a twin to the existing \module{sunaudiodev} module.
-(Contributed by Peter Bosch, with fixes by Jeremy Hylton.)
-
-\item{\module{mmap}:} An interface to memory-mapped files on both
-Windows and \UNIX. A file's contents can be mapped directly into
-memory, at which point it behaves like a mutable string, so its
-contents can be read and modified. They can even be passed to
-functions that expect ordinary strings, such as the \module{re}
-module. (Contributed by Sam Rushing, with some extensions by
-A.M. Kuchling.)
-
-\item{\module{pyexpat}:} An interface to the Expat XML parser.
-(Contributed by Paul Prescod.)
-
-\item{\module{robotparser}:} Parse a \file{robots.txt} file, which is
-used for writing Web spiders that politely avoid certain areas of a
-Web site. The parser accepts the contents of a \file{robots.txt} file,
-builds a set of rules from it, and can then answer questions about
-the fetchability of a given URL. (Contributed by Skip Montanaro.)
-
-\item{\module{tabnanny}:} A module/script to
-check Python source code for ambiguous indentation.
-(Contributed by Tim Peters.)
-
-\item{\module{UserString}:} A base class useful for deriving objects that behave like strings.
-
-\item{\module{webbrowser}:} A module that provides a platform independent
-way to launch a web browser on a specific URL. For each platform, various
-browsers are tried in a specific order. The user can alter which browser
-is launched by setting the \var{BROWSER} environment variable.
-(Originally inspired by Eric S. Raymond's patch to \module{urllib}
-which added similar functionality, but
-the final module comes from code originally
-implemented by Fred Drake as \file{Tools/idle/BrowserControl.py},
-and adapted for the standard library by Fred.)
-
-\item{\module{_winreg}:} An interface to the
-Windows registry. \module{_winreg} is an adaptation of functions that
-have been part of PythonWin since 1995, but has now been added to the core
-distribution, and enhanced to support Unicode.
-\module{_winreg} was written by Bill Tutt and Mark Hammond.
-
-\item{\module{zipfile}:} A module for reading and writing ZIP-format
-archives. These are archives produced by \program{PKZIP} on
-DOS/Windows or \program{zip} on \UNIX, not to be confused with
-\program{gzip}-format files (which are supported by the \module{gzip}
-module)
-(Contributed by James C. Ahlstrom.)
-
-\item{\module{imputil}:} A module that provides a simpler way for
-writing customised import hooks, in comparison to the existing
-\module{ihooks} module. (Implemented by Greg Stein, with much
-discussion on python-dev along the way.)
-
-\end{itemize}
-
-% ======================================================================
-\section{IDLE Improvements}
-
-IDLE is the official Python cross-platform IDE, written using Tkinter.
-Python 2.0 includes IDLE 0.6, which adds a number of new features and
-improvements. A partial list:
-
-\begin{itemize}
-\item UI improvements and optimizations,
-especially in the area of syntax highlighting and auto-indentation.
-
-\item The class browser now shows more information, such as the top
-level functions in a module.
-
-\item Tab width is now a user settable option. When opening an existing Python
-file, IDLE automatically detects the indentation conventions, and adapts.
-
-\item There is now support for calling browsers on various platforms,
-used to open the Python documentation in a browser.
-
-\item IDLE now has a command line, which is largely similar to
-the vanilla Python interpreter.
-
-\item Call tips were added in many places.
-
-\item IDLE can now be installed as a package.
-
-\item In the editor window, there is now a line/column bar at the bottom.
-
-\item Three new keystroke commands: Check module (Alt-F5), Import
-module (F5) and Run script (Ctrl-F5).
-
-\end{itemize}
-
-% ======================================================================
-\section{Deleted and Deprecated Modules}
-
-A few modules have been dropped because they're obsolete, or because
-there are now better ways to do the same thing. The \module{stdwin}
-module is gone; it was for a platform-independent windowing toolkit
-that's no longer developed.
-
-A number of modules have been moved to the
-\file{lib-old} subdirectory:
-\module{cmp}, \module{cmpcache}, \module{dircmp}, \module{dump},
-\module{find}, \module{grep}, \module{packmail},
-\module{poly}, \module{util}, \module{whatsound}, \module{zmod}.
-If you have code which relies on a module that's been moved to
-\file{lib-old}, you can simply add that directory to \code{sys.path}
-to get them back, but you're encouraged to update any code that uses
-these modules.
-
-\section{Acknowledgements}
-
-The authors would like to thank the following people for offering
-suggestions on various drafts of this article: David Bolen, Mark
-Hammond, Gregg Hauser, Jeremy Hylton, Fredrik Lundh, Detlef Lannert,
-Aahz Maruch, Skip Montanaro, Vladimir Marangozov, Tobias Polzin, Guido
-van Rossum, Neil Schemenauer, and Russ Schmidt.
-
-\end{document}
diff --git a/Doc/whatsnew/whatsnew21.tex b/Doc/whatsnew/whatsnew21.tex
deleted file mode 100644
index 67cbbe4..0000000
--- a/Doc/whatsnew/whatsnew21.tex
+++ /dev/null
@@ -1,868 +0,0 @@
-\documentclass{howto}
-
-\usepackage{distutils}
-
-% $Id$
-
-\title{What's New in Python 2.1}
-\release{1.01}
-\author{A.M. Kuchling}
-\authoraddress{
- \strong{Python Software Foundation}\\
- Email: \email{amk@amk.ca}
-}
-\begin{document}
-\maketitle\tableofcontents
-
-\section{Introduction}
-
-This article explains the new features in Python 2.1. While there aren't as
-many changes in 2.1 as there were in Python 2.0, there are still some
-pleasant surprises in store. 2.1 is the first release to be steered
-through the use of Python Enhancement Proposals, or PEPs, so most of
-the sizable changes have accompanying PEPs that provide more complete
-documentation and a design rationale for the change. This article
-doesn't attempt to document the new features completely, but simply
-provides an overview of the new features for Python programmers.
-Refer to the Python 2.1 documentation, or to the specific PEP, for
-more details about any new feature that particularly interests you.
-
-One recent goal of the Python development team has been to accelerate
-the pace of new releases, with a new release coming every 6 to 9
-months. 2.1 is the first release to come out at this faster pace, with
-the first alpha appearing in January, 3 months after the final version
-of 2.0 was released.
-
-The final release of Python 2.1 was made on April 17, 2001.
-
-%======================================================================
-\section{PEP 227: Nested Scopes}
-
-The largest change in Python 2.1 is to Python's scoping rules. In
-Python 2.0, at any given time there are at most three namespaces used
-to look up variable names: local, module-level, and the built-in
-namespace. This often surprised people because it didn't match their
-intuitive expectations. For example, a nested recursive function
-definition doesn't work:
-
-\begin{verbatim}
-def f():
- ...
- def g(value):
- ...
- return g(value-1) + 1
- ...
-\end{verbatim}
-
-The function \function{g()} will always raise a \exception{NameError}
-exception, because the binding of the name \samp{g} isn't in either
-its local namespace or in the module-level namespace. This isn't much
-of a problem in practice (how often do you recursively define interior
-functions like this?), but this also made using the \keyword{lambda}
-statement clumsier, and this was a problem in practice. In code which
-uses \keyword{lambda} you can often find local variables being copied
-by passing them as the default values of arguments.
-
-\begin{verbatim}
-def find(self, name):
- "Return list of any entries equal to 'name'"
- L = filter(lambda x, name=name: x == name,
- self.list_attribute)
- return L
-\end{verbatim}
-
-The readability of Python code written in a strongly functional style
-suffers greatly as a result.
-
-The most significant change to Python 2.1 is that static scoping has
-been added to the language to fix this problem. As a first effect,
-the \code{name=name} default argument is now unnecessary in the above
-example. Put simply, when a given variable name is not assigned a
-value within a function (by an assignment, or the \keyword{def},
-\keyword{class}, or \keyword{import} statements), references to the
-variable will be looked up in the local namespace of the enclosing
-scope. A more detailed explanation of the rules, and a dissection of
-the implementation, can be found in the PEP.
-
-This change may cause some compatibility problems for code where the
-same variable name is used both at the module level and as a local
-variable within a function that contains further function definitions.
-This seems rather unlikely though, since such code would have been
-pretty confusing to read in the first place.
-
-One side effect of the change is that the \code{from \var{module}
-import *} and \keyword{exec} statements have been made illegal inside
-a function scope under certain conditions. The Python reference
-manual has said all along that \code{from \var{module} import *} is
-only legal at the top level of a module, but the CPython interpreter
-has never enforced this before. As part of the implementation of
-nested scopes, the compiler which turns Python source into bytecodes
-has to generate different code to access variables in a containing
-scope. \code{from \var{module} import *} and \keyword{exec} make it
-impossible for the compiler to figure this out, because they add names
-to the local namespace that are unknowable at compile time.
-Therefore, if a function contains function definitions or
-\keyword{lambda} expressions with free variables, the compiler will
-flag this by raising a \exception{SyntaxError} exception.
-
-To make the preceding explanation a bit clearer, here's an example:
-
-\begin{verbatim}
-x = 1
-def f():
- # The next line is a syntax error
- exec 'x=2'
- def g():
- return x
-\end{verbatim}
-
-Line 4 containing the \keyword{exec} statement is a syntax error,
-since \keyword{exec} would define a new local variable named \samp{x}
-whose value should be accessed by \function{g()}.
-
-This shouldn't be much of a limitation, since \keyword{exec} is rarely
-used in most Python code (and when it is used, it's often a sign of a
-poor design anyway).
-
-Compatibility concerns have led to nested scopes being introduced
-gradually; in Python 2.1, they aren't enabled by default, but can be
-turned on within a module by using a future statement as described in
-PEP 236. (See the following section for further discussion of PEP
-236.) In Python 2.2, nested scopes will become the default and there
-will be no way to turn them off, but users will have had all of 2.1's
-lifetime to fix any breakage resulting from their introduction.
-
-\begin{seealso}
-
-\seepep{227}{Statically Nested Scopes}{Written and implemented by
-Jeremy Hylton.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 236: __future__ Directives}
-
-The reaction to nested scopes was widespread concern about the dangers
-of breaking code with the 2.1 release, and it was strong enough to
-make the Pythoneers take a more conservative approach. This approach
-consists of introducing a convention for enabling optional
-functionality in release N that will become compulsory in release N+1.
-
-The syntax uses a \code{from...import} statement using the reserved
-module name \module{__future__}. Nested scopes can be enabled by the
-following statement:
-
-\begin{verbatim}
-from __future__ import nested_scopes
-\end{verbatim}
-
-While it looks like a normal \keyword{import} statement, it's not;
-there are strict rules on where such a future statement can be put.
-They can only be at the top of a module, and must precede any Python
-code or regular \keyword{import} statements. This is because such
-statements can affect how the Python bytecode compiler parses code and
-generates bytecode, so they must precede any statement that will
-result in bytecodes being produced.
-
-\begin{seealso}
-
-\seepep{236}{Back to the \module{__future__}}{Written by Tim Peters,
-and primarily implemented by Jeremy Hylton.}
-
-\end{seealso}
-
-%======================================================================
-\section{PEP 207: Rich Comparisons}
-
-In earlier versions, Python's support for implementing comparisons on
-user-defined classes and extension types was quite simple. Classes
-could implement a \method{__cmp__} method that was given two instances
-of a class, and could only return 0 if they were equal or +1 or -1 if
-they weren't; the method couldn't raise an exception or return
-anything other than a Boolean value. Users of Numeric Python often
-found this model too weak and restrictive, because in the
-number-crunching programs that numeric Python is used for, it would be
-more useful to be able to perform elementwise comparisons of two
-matrices, returning a matrix containing the results of a given
-comparison for each element. If the two matrices are of different
-sizes, then the compare has to be able to raise an exception to signal
-the error.
-
-In Python 2.1, rich comparisons were added in order to support this
-need. Python classes can now individually overload each of the
-\code{<}, \code{<=}, \code{>}, \code{>=}, \code{==}, and \code{!=}
-operations. The new magic method names are:
-
-\begin{tableii}{c|l}{code}{Operation}{Method name}
- \lineii{<}{\method{__lt__}} \lineii{<=}{\method{__le__}}
- \lineii{>}{\method{__gt__}} \lineii{>=}{\method{__ge__}}
- \lineii{==}{\method{__eq__}} \lineii{!=}{\method{__ne__}}
- \end{tableii}
-
-(The magic methods are named after the corresponding Fortran operators
-\code{.LT.}. \code{.LE.}, \&c. Numeric programmers are almost
-certainly quite familiar with these names and will find them easy to
-remember.)
-
-Each of these magic methods is of the form \code{\var{method}(self,
-other)}, where \code{self} will be the object on the left-hand side of
-the operator, while \code{other} will be the object on the right-hand
-side. For example, the expression \code{A < B} will cause
-\code{A.__lt__(B)} to be called.
-
-Each of these magic methods can return anything at all: a Boolean, a
-matrix, a list, or any other Python object. Alternatively they can
-raise an exception if the comparison is impossible, inconsistent, or
-otherwise meaningless.
-
-The built-in \function{cmp(A,B)} function can use the rich comparison
-machinery, and now accepts an optional argument specifying which
-comparison operation to use; this is given as one of the strings
-\code{"<"}, \code{"<="}, \code{">"}, \code{">="}, \code{"=="}, or
-\code{"!="}. If called without the optional third argument,
-\function{cmp()} will only return -1, 0, or +1 as in previous versions
-of Python; otherwise it will call the appropriate method and can
-return any Python object.
-
-There are also corresponding changes of interest to C programmers;
-there's a new slot \code{tp_richcmp} in type objects and an API for
-performing a given rich comparison. I won't cover the C API here, but
-will refer you to PEP 207, or to 2.1's C API documentation, for the
-full list of related functions.
-
-\begin{seealso}
-
-\seepep{207}{Rich Comparisions}{Written by Guido van Rossum, heavily
-based on earlier work by David Ascher, and implemented by Guido van
-Rossum.}
-
-\end{seealso}
-
-%======================================================================
-\section{PEP 230: Warning Framework}
-
-Over its 10 years of existence, Python has accumulated a certain
-number of obsolete modules and features along the way. It's difficult
-to know when a feature is safe to remove, since there's no way of
-knowing how much code uses it --- perhaps no programs depend on the
-feature, or perhaps many do. To enable removing old features in a
-more structured way, a warning framework was added. When the Python
-developers want to get rid of a feature, it will first trigger a
-warning in the next version of Python. The following Python version
-can then drop the feature, and users will have had a full release
-cycle to remove uses of the old feature.
-
-Python 2.1 adds the warning framework to be used in this scheme. It
-adds a \module{warnings} module that provide functions to issue
-warnings, and to filter out warnings that you don't want to be
-displayed. Third-party modules can also use this framework to
-deprecate old features that they no longer wish to support.
-
-For example, in Python 2.1 the \module{regex} module is deprecated, so
-importing it causes a warning to be printed:
-
-\begin{verbatim}
->>> import regex
-__main__:1: DeprecationWarning: the regex module
- is deprecated; please use the re module
->>>
-\end{verbatim}
-
-Warnings can be issued by calling the \function{warnings.warn}
-function:
-
-\begin{verbatim}
-warnings.warn("feature X no longer supported")
-\end{verbatim}
-
-The first parameter is the warning message; an additional optional
-parameters can be used to specify a particular warning category.
-
-Filters can be added to disable certain warnings; a regular expression
-pattern can be applied to the message or to the module name in order
-to suppress a warning. For example, you may have a program that uses
-the \module{regex} module and not want to spare the time to convert it
-to use the \module{re} module right now. The warning can be
-suppressed by calling
-
-\begin{verbatim}
-import warnings
-warnings.filterwarnings(action = 'ignore',
- message='.*regex module is deprecated',
- category=DeprecationWarning,
- module = '__main__')
-\end{verbatim}
-
-This adds a filter that will apply only to warnings of the class
-\class{DeprecationWarning} triggered in the \module{__main__} module,
-and applies a regular expression to only match the message about the
-\module{regex} module being deprecated, and will cause such warnings
-to be ignored. Warnings can also be printed only once, printed every
-time the offending code is executed, or turned into exceptions that
-will cause the program to stop (unless the exceptions are caught in
-the usual way, of course).
-
-Functions were also added to Python's C API for issuing warnings;
-refer to PEP 230 or to Python's API documentation for the details.
-
-\begin{seealso}
-
-\seepep{5}{Guidelines for Language Evolution}{Written
-by Paul Prescod, to specify procedures to be followed when removing
-old features from Python. The policy described in this PEP hasn't
-been officially adopted, but the eventual policy probably won't be too
-different from Prescod's proposal.}
-
-\seepep{230}{Warning Framework}{Written and implemented by Guido van
-Rossum.}
-
-\end{seealso}
-
-%======================================================================
-\section{PEP 229: New Build System}
-
-When compiling Python, the user had to go in and edit the
-\file{Modules/Setup} file in order to enable various additional
-modules; the default set is relatively small and limited to modules
-that compile on most \UNIX{} platforms. This means that on \Unix{}
-platforms with many more features, most notably Linux, Python
-installations often don't contain all useful modules they could.
-
-Python 2.0 added the Distutils, a set of modules for distributing and
-installing extensions. In Python 2.1, the Distutils are used to
-compile much of the standard library of extension modules,
-autodetecting which ones are supported on the current machine. It's
-hoped that this will make Python installations easier and more
-featureful.
-
-Instead of having to edit the \file{Modules/Setup} file in order to
-enable modules, a \file{setup.py} script in the top directory of the
-Python source distribution is run at build time, and attempts to
-discover which modules can be enabled by examining the modules and
-header files on the system. If a module is configured in
-\file{Modules/Setup}, the \file{setup.py} script won't attempt to
-compile that module and will defer to the \file{Modules/Setup} file's
-contents. This provides a way to specific any strange command-line
-flags or libraries that are required for a specific platform.
-
-In another far-reaching change to the build mechanism, Neil
-Schemenauer restructured things so Python now uses a single makefile
-that isn't recursive, instead of makefiles in the top directory and in
-each of the \file{Python/}, \file{Parser/}, \file{Objects/}, and
-\file{Modules/} subdirectories. This makes building Python faster
-and also makes hacking the Makefiles clearer and simpler.
-
-\begin{seealso}
-
-\seepep{229}{Using Distutils to Build Python}{Written
-and implemented by A.M. Kuchling.}
-
-\end{seealso}
-
-%======================================================================
-\section{PEP 205: Weak References}
-
-Weak references, available through the \module{weakref} module, are a
-minor but useful new data type in the Python programmer's toolbox.
-
-Storing a reference to an object (say, in a dictionary or a list) has
-the side effect of keeping that object alive forever. There are a few
-specific cases where this behaviour is undesirable, object caches
-being the most common one, and another being circular references in
-data structures such as trees.
-
-For example, consider a memoizing function that caches the results of
-another function \function{f(\var{x})} by storing the function's
-argument and its result in a dictionary:
-
-\begin{verbatim}
-_cache = {}
-def memoize(x):
- if _cache.has_key(x):
- return _cache[x]
-
- retval = f(x)
-
- # Cache the returned object
- _cache[x] = retval
-
- return retval
-\end{verbatim}
-
-This version works for simple things such as integers, but it has a
-side effect; the \code{_cache} dictionary holds a reference to the
-return values, so they'll never be deallocated until the Python
-process exits and cleans up This isn't very noticeable for integers,
-but if \function{f()} returns an object, or a data structure that
-takes up a lot of memory, this can be a problem.
-
-Weak references provide a way to implement a cache that won't keep
-objects alive beyond their time. If an object is only accessible
-through weak references, the object will be deallocated and the weak
-references will now indicate that the object it referred to no longer
-exists. A weak reference to an object \var{obj} is created by calling
-\code{wr = weakref.ref(\var{obj})}. The object being referred to is
-returned by calling the weak reference as if it were a function:
-\code{wr()}. It will return the referenced object, or \code{None} if
-the object no longer exists.
-
-This makes it possible to write a \function{memoize()} function whose
-cache doesn't keep objects alive, by storing weak references in the
-cache.
-
-\begin{verbatim}
-_cache = {}
-def memoize(x):
- if _cache.has_key(x):
- obj = _cache[x]()
- # If weak reference object still exists,
- # return it
- if obj is not None: return obj
-
- retval = f(x)
-
- # Cache a weak reference
- _cache[x] = weakref.ref(retval)
-
- return retval
-\end{verbatim}
-
-The \module{weakref} module also allows creating proxy objects which
-behave like weak references --- an object referenced only by proxy
-objects is deallocated -- but instead of requiring an explicit call to
-retrieve the object, the proxy transparently forwards all operations
-to the object as long as the object still exists. If the object is
-deallocated, attempting to use a proxy will cause a
-\exception{weakref.ReferenceError} exception to be raised.
-
-\begin{verbatim}
-proxy = weakref.proxy(obj)
-proxy.attr # Equivalent to obj.attr
-proxy.meth() # Equivalent to obj.meth()
-del obj
-proxy.attr # raises weakref.ReferenceError
-\end{verbatim}
-
-\begin{seealso}
-
-\seepep{205}{Weak References}{Written and implemented by
-Fred~L. Drake,~Jr.}
-
-\end{seealso}
-
-%======================================================================
-\section{PEP 232: Function Attributes}
-
-In Python 2.1, functions can now have arbitrary information attached
-to them. People were often using docstrings to hold information about
-functions and methods, because the \code{__doc__} attribute was the
-only way of attaching any information to a function. For example, in
-the Zope Web application server, functions are marked as safe for
-public access by having a docstring, and in John Aycock's SPARK
-parsing framework, docstrings hold parts of the BNF grammar to be
-parsed. This overloading is unfortunate, since docstrings are really
-intended to hold a function's documentation; for example, it means you
-can't properly document functions intended for private use in Zope.
-
-Arbitrary attributes can now be set and retrieved on functions using the
-regular Python syntax:
-
-\begin{verbatim}
-def f(): pass
-
-f.publish = 1
-f.secure = 1
-f.grammar = "A ::= B (C D)*"
-\end{verbatim}
-
-The dictionary containing attributes can be accessed as the function's
-\member{__dict__}. Unlike the \member{__dict__} attribute of class
-instances, in functions you can actually assign a new dictionary to
-\member{__dict__}, though the new value is restricted to a regular
-Python dictionary; you \emph{can't} be tricky and set it to a
-\class{UserDict} instance, or any other random object that behaves
-like a mapping.
-
-\begin{seealso}
-
-\seepep{232}{Function Attributes}{Written and implemented by Barry
-Warsaw.}
-
-\end{seealso}
-
-
-%======================================================================
-
-\section{PEP 235: Importing Modules on Case-Insensitive Platforms}
-
-Some operating systems have filesystems that are case-insensitive,
-MacOS and Windows being the primary examples; on these systems, it's
-impossible to distinguish the filenames \samp{FILE.PY} and
-\samp{file.py}, even though they do store the file's name
-in its original case (they're case-preserving, too).
-
-In Python 2.1, the \keyword{import} statement will work to simulate
-case-sensitivity on case-insensitive platforms. Python will now
-search for the first case-sensitive match by default, raising an
-\exception{ImportError} if no such file is found, so \code{import file}
-will not import a module named \samp{FILE.PY}. Case-insensitive
-matching can be requested by setting the \envvar{PYTHONCASEOK} environment
-variable before starting the Python interpreter.
-
-%======================================================================
-\section{PEP 217: Interactive Display Hook}
-
-When using the Python interpreter interactively, the output of
-commands is displayed using the built-in \function{repr()} function.
-In Python 2.1, the variable \function{sys.displayhook} can be set to a
-callable object which will be called instead of \function{repr()}.
-For example, you can set it to a special pretty-printing function:
-
-\begin{verbatim}
->>> # Create a recursive data structure
-... L = [1,2,3]
->>> L.append(L)
->>> L # Show Python's default output
-[1, 2, 3, [...]]
->>> # Use pprint.pprint() as the display function
-... import sys, pprint
->>> sys.displayhook = pprint.pprint
->>> L
-[1, 2, 3, <Recursion on list with id=135143996>]
->>>
-\end{verbatim}
-
-\begin{seealso}
-
-\seepep{217}{Display Hook for Interactive Use}{Written and implemented
-by Moshe Zadka.}
-
-\end{seealso}
-
-%======================================================================
-\section{PEP 208: New Coercion Model}
-
-How numeric coercion is done at the C level was significantly
-modified. This will only affect the authors of C extensions to
-Python, allowing them more flexibility in writing extension types that
-support numeric operations.
-
-Extension types can now set the type flag \code{Py_TPFLAGS_CHECKTYPES}
-in their \code{PyTypeObject} structure to indicate that they support
-the new coercion model. In such extension types, the numeric slot
-functions can no longer assume that they'll be passed two arguments of
-the same type; instead they may be passed two arguments of differing
-types, and can then perform their own internal coercion. If the slot
-function is passed a type it can't handle, it can indicate the failure
-by returning a reference to the \code{Py_NotImplemented} singleton
-value. The numeric functions of the other type will then be tried,
-and perhaps they can handle the operation; if the other type also
-returns \code{Py_NotImplemented}, then a \exception{TypeError} will be
-raised. Numeric methods written in Python can also return
-\code{Py_NotImplemented}, causing the interpreter to act as if the
-method did not exist (perhaps raising a \exception{TypeError}, perhaps
-trying another object's numeric methods).
-
-\begin{seealso}
-
-\seepep{208}{Reworking the Coercion Model}{Written and implemented by
-Neil Schemenauer, heavily based upon earlier work by Marc-Andr\'e
-Lemburg. Read this to understand the fine points of how numeric
-operations will now be processed at the C level.}
-
-\end{seealso}
-
-%======================================================================
-\section{PEP 241: Metadata in Python Packages}
-
-A common complaint from Python users is that there's no single catalog
-of all the Python modules in existence. T.~Middleton's Vaults of
-Parnassus at \url{http://www.vex.net/parnassus/} are the largest
-catalog of Python modules, but registering software at the Vaults is
-optional, and many people don't bother.
-
-As a first small step toward fixing the problem, Python software
-packaged using the Distutils \command{sdist} command will include a
-file named \file{PKG-INFO} containing information about the package
-such as its name, version, and author (metadata, in cataloguing
-terminology). PEP 241 contains the full list of fields that can be
-present in the \file{PKG-INFO} file. As people began to package their
-software using Python 2.1, more and more packages will include
-metadata, making it possible to build automated cataloguing systems
-and experiment with them. With the result experience, perhaps it'll
-be possible to design a really good catalog and then build support for
-it into Python 2.2. For example, the Distutils \command{sdist}
-and \command{bdist_*} commands could support a \option{upload} option
-that would automatically upload your package to a catalog server.
-
-You can start creating packages containing \file{PKG-INFO} even if
-you're not using Python 2.1, since a new release of the Distutils will
-be made for users of earlier Python versions. Version 1.0.2 of the
-Distutils includes the changes described in PEP 241, as well as
-various bugfixes and enhancements. It will be available from
-the Distutils SIG at \url{http://www.python.org/sigs/distutils-sig/}.
-
-\begin{seealso}
-
-\seepep{241}{Metadata for Python Software Packages}{Written and
-implemented by A.M. Kuchling.}
-
-\seepep{243}{Module Repository Upload Mechanism}{Written by Sean
-Reifschneider, this draft PEP describes a proposed mechanism for uploading
-Python packages to a central server.
-}
-
-\end{seealso}
-
-%======================================================================
-\section{New and Improved Modules}
-
-\begin{itemize}
-
-\item Ka-Ping Yee contributed two new modules: \module{inspect.py}, a
-module for getting information about live Python code, and
-\module{pydoc.py}, a module for interactively converting docstrings to
-HTML or text. As a bonus, \file{Tools/scripts/pydoc}, which is now
-automatically installed, uses \module{pydoc.py} to display
-documentation given a Python module, package, or class name. For
-example, \samp{pydoc xml.dom} displays the following:
-
-\begin{verbatim}
-Python Library Documentation: package xml.dom in xml
-
-NAME
- xml.dom - W3C Document Object Model implementation for Python.
-
-FILE
- /usr/local/lib/python2.1/xml/dom/__init__.pyc
-
-DESCRIPTION
- The Python mapping of the Document Object Model is documented in the
- Python Library Reference in the section on the xml.dom package.
-
- This package contains the following modules:
- ...
-\end{verbatim}
-
-\file{pydoc} also includes a Tk-based interactive help browser.
-\file{pydoc} quickly becomes addictive; try it out!
-
-\item Two different modules for unit testing were added to the
-standard library. The \module{doctest} module, contributed by Tim
-Peters, provides a testing framework based on running embedded
-examples in docstrings and comparing the results against the expected
-output. PyUnit, contributed by Steve Purcell, is a unit testing
-framework inspired by JUnit, which was in turn an adaptation of Kent
-Beck's Smalltalk testing framework. See
-\url{http://pyunit.sourceforge.net/} for more information about
-PyUnit.
-
-\item The \module{difflib} module contains a class,
-\class{SequenceMatcher}, which compares two sequences and computes the
-changes required to transform one sequence into the other. For
-example, this module can be used to write a tool similar to the \UNIX{}
-\program{diff} program, and in fact the sample program
-\file{Tools/scripts/ndiff.py} demonstrates how to write such a script.
-
-\item \module{curses.panel}, a wrapper for the panel library, part of
-ncurses and of SYSV curses, was contributed by Thomas Gellekum. The
-panel library provides windows with the additional feature of depth.
-Windows can be moved higher or lower in the depth ordering, and the
-panel library figures out where panels overlap and which sections are
-visible.
-
-\item The PyXML package has gone through a few releases since Python
-2.0, and Python 2.1 includes an updated version of the \module{xml}
-package. Some of the noteworthy changes include support for Expat 1.2
-and later versions, the ability for Expat parsers to handle files in
-any encoding supported by Python, and various bugfixes for SAX, DOM,
-and the \module{minidom} module.
-
-\item Ping also contributed another hook for handling uncaught
-exceptions. \function{sys.excepthook} can be set to a callable
-object. When an exception isn't caught by any
-\keyword{try}...\keyword{except} blocks, the exception will be passed
-to \function{sys.excepthook}, which can then do whatever it likes. At
-the Ninth Python Conference, Ping demonstrated an application for this
-hook: printing an extended traceback that not only lists the stack
-frames, but also lists the function arguments and the local variables
-for each frame.
-
-\item Various functions in the \module{time} module, such as
-\function{asctime()} and \function{localtime()}, require a floating
-point argument containing the time in seconds since the epoch. The
-most common use of these functions is to work with the current time,
-so the floating point argument has been made optional; when a value
-isn't provided, the current time will be used. For example, log file
-entries usually need a string containing the current time; in Python
-2.1, \code{time.asctime()} can be used, instead of the lengthier
-\code{time.asctime(time.localtime(time.time()))} that was previously
-required.
-
-This change was proposed and implemented by Thomas Wouters.
-
-\item The \module{ftplib} module now defaults to retrieving files in
-passive mode, because passive mode is more likely to work from behind
-a firewall. This request came from the Debian bug tracking system,
-since other Debian packages use \module{ftplib} to retrieve files and
-then don't work from behind a firewall. It's deemed unlikely that
-this will cause problems for anyone, because Netscape defaults to
-passive mode and few people complain, but if passive mode is
-unsuitable for your application or network setup, call
-\method{set_pasv(0)} on FTP objects to disable passive mode.
-
-\item Support for raw socket access has been added to the
-\module{socket} module, contributed by Grant Edwards.
-
-\item The \module{pstats} module now contains a simple interactive
-statistics browser for displaying timing profiles for Python programs,
-invoked when the module is run as a script. Contributed by
-Eric S.\ Raymond.
-
-\item A new implementation-dependent function, \function{sys._getframe(\optional{depth})},
-has been added to return a given frame object from the current call stack.
-\function{sys._getframe()} returns the frame at the top of the call stack;
-if the optional integer argument \var{depth} is supplied, the function returns the frame
-that is \var{depth} calls below the top of the stack. For example, \code{sys._getframe(1)}
-returns the caller's frame object.
-
-This function is only present in CPython, not in Jython or the .NET
-implementation. Use it for debugging, and resist the temptation to
-put it into production code.
-
-
-
-\end{itemize}
-
-%======================================================================
-\section{Other Changes and Fixes}
-
-There were relatively few smaller changes made in Python 2.1 due to
-the shorter release cycle. A search through the CVS change logs turns
-up 117 patches applied, and 136 bugs fixed; both figures are likely to
-be underestimates. Some of the more notable changes are:
-
-\begin{itemize}
-
-
-\item A specialized object allocator is now optionally available, that
-should be faster than the system \function{malloc()} and have less
-memory overhead. The allocator uses C's \function{malloc()} function
-to get large pools of memory, and then fulfills smaller memory
-requests from these pools. It can be enabled by providing the
-\longprogramopt{with-pymalloc} option to the \program{configure} script; see
-\file{Objects/obmalloc.c} for the implementation details.
-
-Authors of C extension modules should test their code with the object
-allocator enabled, because some incorrect code may break, causing core
-dumps at runtime. There are a bunch of memory allocation functions in
-Python's C API that have previously been just aliases for the C
-library's \function{malloc()} and \function{free()}, meaning that if
-you accidentally called mismatched functions, the error wouldn't be
-noticeable. When the object allocator is enabled, these functions
-aren't aliases of \function{malloc()} and \function{free()} any more,
-and calling the wrong function to free memory will get you a core
-dump. For example, if memory was allocated using
-\function{PyMem_New()}, it has to be freed using
-\function{PyMem_Del()}, not \function{free()}. A few modules included
-with Python fell afoul of this and had to be fixed; doubtless there
-are more third-party modules that will have the same problem.
-
-The object allocator was contributed by Vladimir Marangozov.
-
-\item The speed of line-oriented file I/O has been improved because
-people often complain about its lack of speed, and because it's often
-been used as a na\"ive benchmark. The \method{readline()} method of
-file objects has therefore been rewritten to be much faster. The
-exact amount of the speedup will vary from platform to platform
-depending on how slow the C library's \function{getc()} was, but is
-around 66\%, and potentially much faster on some particular operating
-systems. Tim Peters did much of the benchmarking and coding for this
-change, motivated by a discussion in comp.lang.python.
-
-A new module and method for file objects was also added, contributed
-by Jeff Epler. The new method, \method{xreadlines()}, is similar to
-the existing \function{xrange()} built-in. \function{xreadlines()}
-returns an opaque sequence object that only supports being iterated
-over, reading a line on every iteration but not reading the entire
-file into memory as the existing \method{readlines()} method does.
-You'd use it like this:
-
-\begin{verbatim}
-for line in sys.stdin.xreadlines():
- # ... do something for each line ...
- ...
-\end{verbatim}
-
-For a fuller discussion of the line I/O changes, see the python-dev
-summary for January 1-15, 2001 at
-\url{http://www.python.org/dev/summary/2001-01-1.html}.
-
-\item A new method, \method{popitem()}, was added to dictionaries to
-enable destructively iterating through the contents of a dictionary;
-this can be faster for large dictionaries because there's no need to
-construct a list containing all the keys or values.
-\code{D.popitem()} removes a random \code{(\var{key}, \var{value})}
-pair from the dictionary~\code{D} and returns it as a 2-tuple. This
-was implemented mostly by Tim Peters and Guido van Rossum, after a
-suggestion and preliminary patch by Moshe Zadka.
-
-\item Modules can now control which names are imported when \code{from
-\var{module} import *} is used, by defining an \code{__all__}
-attribute containing a list of names that will be imported. One
-common complaint is that if the module imports other modules such as
-\module{sys} or \module{string}, \code{from \var{module} import *}
-will add them to the importing module's namespace. To fix this,
-simply list the public names in \code{__all__}:
-
-\begin{verbatim}
-# List public names
-__all__ = ['Database', 'open']
-\end{verbatim}
-
-A stricter version of this patch was first suggested and implemented
-by Ben Wolfson, but after some python-dev discussion, a weaker final
-version was checked in.
-
-\item Applying \function{repr()} to strings previously used octal
-escapes for non-printable characters; for example, a newline was
-\code{'\e 012'}. This was a vestigial trace of Python's C ancestry, but
-today octal is of very little practical use. Ka-Ping Yee suggested
-using hex escapes instead of octal ones, and using the \code{\e n},
-\code{\e t}, \code{\e r} escapes for the appropriate characters, and
-implemented this new formatting.
-
-\item Syntax errors detected at compile-time can now raise exceptions
-containing the filename and line number of the error, a pleasant side
-effect of the compiler reorganization done by Jeremy Hylton.
-
-\item C extensions which import other modules have been changed to use
-\function{PyImport_ImportModule()}, which means that they will use any
-import hooks that have been installed. This is also encouraged for
-third-party extensions that need to import some other module from C
-code.
-
-\item The size of the Unicode character database was shrunk by another
-340K thanks to Fredrik Lundh.
-
-\item Some new ports were contributed: MacOS X (by Steven Majewski),
-Cygwin (by Jason Tishler); RISCOS (by Dietmar Schwertberger); Unixware~7
-(by Billy G. Allie).
-
-\end{itemize}
-
-And there's the usual list of minor bugfixes, minor memory leaks,
-docstring edits, and other tweaks, too lengthy to be worth itemizing;
-see the CVS logs for the full details if you want them.
-
-
-%======================================================================
-\section{Acknowledgements}
-
-The author would like to thank the following people for offering
-suggestions on various drafts of this article: Graeme Cross, David
-Goodger, Jay Graves, Michael Hudson, Marc-Andr\'e Lemburg, Fredrik
-Lundh, Neil Schemenauer, Thomas Wouters.
-
-\end{document}
diff --git a/Doc/whatsnew/whatsnew22.tex b/Doc/whatsnew/whatsnew22.tex
deleted file mode 100644
index 82ff061..0000000
--- a/Doc/whatsnew/whatsnew22.tex
+++ /dev/null
@@ -1,1466 +0,0 @@
-\documentclass{howto}
-
-% $Id$
-
-\title{What's New in Python 2.2}
-\release{1.02}
-\author{A.M. Kuchling}
-\authoraddress{
- \strong{Python Software Foundation}\\
- Email: \email{amk@amk.ca}
-}
-\begin{document}
-\maketitle\tableofcontents
-
-\section{Introduction}
-
-This article explains the new features in Python 2.2.2, released on
-October 14, 2002. Python 2.2.2 is a bugfix release of Python 2.2,
-originally released on December 21, 2001.
-
-Python 2.2 can be thought of as the "cleanup release". There are some
-features such as generators and iterators that are completely new, but
-most of the changes, significant and far-reaching though they may be,
-are aimed at cleaning up irregularities and dark corners of the
-language design.
-
-This article doesn't attempt to provide a complete specification of
-the new features, but instead provides a convenient overview. For
-full details, you should refer to the documentation for Python 2.2,
-such as the
-\citetitle[http://www.python.org/doc/2.2/lib/lib.html]{Python
-Library Reference} and the
-\citetitle[http://www.python.org/doc/2.2/ref/ref.html]{Python
-Reference Manual}. If you want to understand the complete
-implementation and design rationale for a change, refer to the PEP for
-a particular new feature.
-
-\begin{seealso}
-
-\seeurl{http://www.unixreview.com/documents/s=1356/urm0109h/0109h.htm}
-{``What's So Special About Python 2.2?'' is also about the new 2.2
-features, and was written by Cameron Laird and Kathryn Soraiz.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEPs 252 and 253: Type and Class Changes}
-
-The largest and most far-reaching changes in Python 2.2 are to
-Python's model of objects and classes. The changes should be backward
-compatible, so it's likely that your code will continue to run
-unchanged, but the changes provide some amazing new capabilities.
-Before beginning this, the longest and most complicated section of
-this article, I'll provide an overview of the changes and offer some
-comments.
-
-A long time ago I wrote a Web page
-(\url{http://www.amk.ca/python/writing/warts.html}) listing flaws in
-Python's design. One of the most significant flaws was that it's
-impossible to subclass Python types implemented in C. In particular,
-it's not possible to subclass built-in types, so you can't just
-subclass, say, lists in order to add a single useful method to them.
-The \module{UserList} module provides a class that supports all of the
-methods of lists and that can be subclassed further, but there's lots
-of C code that expects a regular Python list and won't accept a
-\class{UserList} instance.
-
-Python 2.2 fixes this, and in the process adds some exciting new
-capabilities. A brief summary:
-
-\begin{itemize}
-
-\item You can subclass built-in types such as lists and even integers,
-and your subclasses should work in every place that requires the
-original type.
-
-\item It's now possible to define static and class methods, in addition
-to the instance methods available in previous versions of Python.
-
-\item It's also possible to automatically call methods on accessing or
-setting an instance attribute by using a new mechanism called
-\dfn{properties}. Many uses of \method{__getattr__} can be rewritten
-to use properties instead, making the resulting code simpler and
-faster. As a small side benefit, attributes can now have docstrings,
-too.
-
-\item The list of legal attributes for an instance can be limited to a
-particular set using \dfn{slots}, making it possible to safeguard
-against typos and perhaps make more optimizations possible in future
-versions of Python.
-
-\end{itemize}
-
-Some users have voiced concern about all these changes. Sure, they
-say, the new features are neat and lend themselves to all sorts of
-tricks that weren't possible in previous versions of Python, but
-they also make the language more complicated. Some people have said
-that they've always recommended Python for its simplicity, and feel
-that its simplicity is being lost.
-
-Personally, I think there's no need to worry. Many of the new
-features are quite esoteric, and you can write a lot of Python code
-without ever needed to be aware of them. Writing a simple class is no
-more difficult than it ever was, so you don't need to bother learning
-or teaching them unless they're actually needed. Some very
-complicated tasks that were previously only possible from C will now
-be possible in pure Python, and to my mind that's all for the better.
-
-I'm not going to attempt to cover every single corner case and small
-change that were required to make the new features work. Instead this
-section will paint only the broad strokes. See section~\ref{sect-rellinks},
-``Related Links'', for further sources of information about Python 2.2's new
-object model.
-
-
-\subsection{Old and New Classes}
-
-First, you should know that Python 2.2 really has two kinds of
-classes: classic or old-style classes, and new-style classes. The
-old-style class model is exactly the same as the class model in
-earlier versions of Python. All the new features described in this
-section apply only to new-style classes. This divergence isn't
-intended to last forever; eventually old-style classes will be
-dropped, possibly in Python 3.0.
-
-So how do you define a new-style class? You do it by subclassing an
-existing new-style class. Most of Python's built-in types, such as
-integers, lists, dictionaries, and even files, are new-style classes
-now. A new-style class named \class{object}, the base class for all
-built-in types, has also been added so if no built-in type is
-suitable, you can just subclass \class{object}:
-
-\begin{verbatim}
-class C(object):
- def __init__ (self):
- ...
- ...
-\end{verbatim}
-
-This means that \keyword{class} statements that don't have any base
-classes are always classic classes in Python 2.2. (Actually you can
-also change this by setting a module-level variable named
-\member{__metaclass__} --- see \pep{253} for the details --- but it's
-easier to just subclass \keyword{object}.)
-
-The type objects for the built-in types are available as built-ins,
-named using a clever trick. Python has always had built-in functions
-named \function{int()}, \function{float()}, and \function{str()}. In
-2.2, they aren't functions any more, but type objects that behave as
-factories when called.
-
-\begin{verbatim}
->>> int
-<type 'int'>
->>> int('123')
-123
-\end{verbatim}
-
-To make the set of types complete, new type objects such as
-\function{dict} and \function{file} have been added. Here's a
-more interesting example, adding a \method{lock()} method to file
-objects:
-
-\begin{verbatim}
-class LockableFile(file):
- def lock (self, operation, length=0, start=0, whence=0):
- import fcntl
- return fcntl.lockf(self.fileno(), operation,
- length, start, whence)
-\end{verbatim}
-
-The now-obsolete \module{posixfile} module contained a class that
-emulated all of a file object's methods and also added a
-\method{lock()} method, but this class couldn't be passed to internal
-functions that expected a built-in file, something which is possible
-with our new \class{LockableFile}.
-
-
-\subsection{Descriptors}
-
-In previous versions of Python, there was no consistent way to
-discover what attributes and methods were supported by an object.
-There were some informal conventions, such as defining
-\member{__members__} and \member{__methods__} attributes that were
-lists of names, but often the author of an extension type or a class
-wouldn't bother to define them. You could fall back on inspecting the
-\member{__dict__} of an object, but when class inheritance or an
-arbitrary \method{__getattr__} hook were in use this could still be
-inaccurate.
-
-The one big idea underlying the new class model is that an API for
-describing the attributes of an object using \dfn{descriptors} has
-been formalized. Descriptors specify the value of an attribute,
-stating whether it's a method or a field. With the descriptor API,
-static methods and class methods become possible, as well as more
-exotic constructs.
-
-Attribute descriptors are objects that live inside class objects, and
-have a few attributes of their own:
-
-\begin{itemize}
-
-\item \member{__name__} is the attribute's name.
-
-\item \member{__doc__} is the attribute's docstring.
-
-\item \method{__get__(\var{object})} is a method that retrieves the
-attribute value from \var{object}.
-
-\item \method{__set__(\var{object}, \var{value})} sets the attribute
-on \var{object} to \var{value}.
-
-\item \method{__delete__(\var{object}, \var{value})} deletes the \var{value}
-attribute of \var{object}.
-\end{itemize}
-
-For example, when you write \code{obj.x}, the steps that Python
-actually performs are:
-
-\begin{verbatim}
-descriptor = obj.__class__.x
-descriptor.__get__(obj)
-\end{verbatim}
-
-For methods, \method{descriptor.__get__} returns a temporary object that's
-callable, and wraps up the instance and the method to be called on it.
-This is also why static methods and class methods are now possible;
-they have descriptors that wrap up just the method, or the method and
-the class. As a brief explanation of these new kinds of methods,
-static methods aren't passed the instance, and therefore resemble
-regular functions. Class methods are passed the class of the object,
-but not the object itself. Static and class methods are defined like
-this:
-
-\begin{verbatim}
-class C(object):
- def f(arg1, arg2):
- ...
- f = staticmethod(f)
-
- def g(cls, arg1, arg2):
- ...
- g = classmethod(g)
-\end{verbatim}
-
-The \function{staticmethod()} function takes the function
-\function{f}, and returns it wrapped up in a descriptor so it can be
-stored in the class object. You might expect there to be special
-syntax for creating such methods (\code{def static f()},
-\code{defstatic f()}, or something like that) but no such syntax has
-been defined yet; that's been left for future versions of Python.
-
-More new features, such as slots and properties, are also implemented
-as new kinds of descriptors, and it's not difficult to write a
-descriptor class that does something novel. For example, it would be
-possible to write a descriptor class that made it possible to write
-Eiffel-style preconditions and postconditions for a method. A class
-that used this feature might be defined like this:
-
-\begin{verbatim}
-from eiffel import eiffelmethod
-
-class C(object):
- def f(self, arg1, arg2):
- # The actual function
- ...
- def pre_f(self):
- # Check preconditions
- ...
- def post_f(self):
- # Check postconditions
- ...
-
- f = eiffelmethod(f, pre_f, post_f)
-\end{verbatim}
-
-Note that a person using the new \function{eiffelmethod()} doesn't
-have to understand anything about descriptors. This is why I think
-the new features don't increase the basic complexity of the language.
-There will be a few wizards who need to know about it in order to
-write \function{eiffelmethod()} or the ZODB or whatever, but most
-users will just write code on top of the resulting libraries and
-ignore the implementation details.
-
-
-\subsection{Multiple Inheritance: The Diamond Rule}
-
-Multiple inheritance has also been made more useful through changing
-the rules under which names are resolved. Consider this set of classes
-(diagram taken from \pep{253} by Guido van Rossum):
-
-\begin{verbatim}
- class A:
- ^ ^ def save(self): ...
- / \
- / \
- / \
- / \
- class B class C:
- ^ ^ def save(self): ...
- \ /
- \ /
- \ /
- \ /
- class D
-\end{verbatim}
-
-The lookup rule for classic classes is simple but not very smart; the
-base classes are searched depth-first, going from left to right. A
-reference to \method{D.save} will search the classes \class{D},
-\class{B}, and then \class{A}, where \method{save()} would be found
-and returned. \method{C.save()} would never be found at all. This is
-bad, because if \class{C}'s \method{save()} method is saving some
-internal state specific to \class{C}, not calling it will result in
-that state never getting saved.
-
-New-style classes follow a different algorithm that's a bit more
-complicated to explain, but does the right thing in this situation.
-(Note that Python 2.3 changes this algorithm to one that produces the
-same results in most cases, but produces more useful results for
-really complicated inheritance graphs.)
-
-\begin{enumerate}
-
-\item List all the base classes, following the classic lookup rule and
-include a class multiple times if it's visited repeatedly. In the
-above example, the list of visited classes is [\class{D}, \class{B},
-\class{A}, \class{C}, \class{A}].
-
-\item Scan the list for duplicated classes. If any are found, remove
-all but one occurrence, leaving the \emph{last} one in the list. In
-the above example, the list becomes [\class{D}, \class{B}, \class{C},
-\class{A}] after dropping duplicates.
-
-\end{enumerate}
-
-Following this rule, referring to \method{D.save()} will return
-\method{C.save()}, which is the behaviour we're after. This lookup
-rule is the same as the one followed by Common Lisp. A new built-in
-function, \function{super()}, provides a way to get at a class's
-superclasses without having to reimplement Python's algorithm.
-The most commonly used form will be
-\function{super(\var{class}, \var{obj})}, which returns
-a bound superclass object (not the actual class object). This form
-will be used in methods to call a method in the superclass; for
-example, \class{D}'s \method{save()} method would look like this:
-
-\begin{verbatim}
-class D (B,C):
- def save (self):
- # Call superclass .save()
- super(D, self).save()
- # Save D's private information here
- ...
-\end{verbatim}
-
-\function{super()} can also return unbound superclass objects
-when called as \function{super(\var{class})} or
-\function{super(\var{class1}, \var{class2})}, but this probably won't
-often be useful.
-
-
-\subsection{Attribute Access}
-
-A fair number of sophisticated Python classes define hooks for
-attribute access using \method{__getattr__}; most commonly this is
-done for convenience, to make code more readable by automatically
-mapping an attribute access such as \code{obj.parent} into a method
-call such as \code{obj.get_parent()}. Python 2.2 adds some new ways
-of controlling attribute access.
-
-First, \method{__getattr__(\var{attr_name})} is still supported by
-new-style classes, and nothing about it has changed. As before, it
-will be called when an attempt is made to access \code{obj.foo} and no
-attribute named \samp{foo} is found in the instance's dictionary.
-
-New-style classes also support a new method,
-\method{__getattribute__(\var{attr_name})}. The difference between
-the two methods is that \method{__getattribute__} is \emph{always}
-called whenever any attribute is accessed, while the old
-\method{__getattr__} is only called if \samp{foo} isn't found in the
-instance's dictionary.
-
-However, Python 2.2's support for \dfn{properties} will often be a
-simpler way to trap attribute references. Writing a
-\method{__getattr__} method is complicated because to avoid recursion
-you can't use regular attribute accesses inside them, and instead have
-to mess around with the contents of \member{__dict__}.
-\method{__getattr__} methods also end up being called by Python when
-it checks for other methods such as \method{__repr__} or
-\method{__coerce__}, and so have to be written with this in mind.
-Finally, calling a function on every attribute access results in a
-sizable performance loss.
-
-\class{property} is a new built-in type that packages up three
-functions that get, set, or delete an attribute, and a docstring. For
-example, if you want to define a \member{size} attribute that's
-computed, but also settable, you could write:
-
-\begin{verbatim}
-class C(object):
- def get_size (self):
- result = ... computation ...
- return result
- def set_size (self, size):
- ... compute something based on the size
- and set internal state appropriately ...
-
- # Define a property. The 'delete this attribute'
- # method is defined as None, so the attribute
- # can't be deleted.
- size = property(get_size, set_size,
- None,
- "Storage size of this instance")
-\end{verbatim}
-
-That is certainly clearer and easier to write than a pair of
-\method{__getattr__}/\method{__setattr__} methods that check for the
-\member{size} attribute and handle it specially while retrieving all
-other attributes from the instance's \member{__dict__}. Accesses to
-\member{size} are also the only ones which have to perform the work of
-calling a function, so references to other attributes run at
-their usual speed.
-
-Finally, it's possible to constrain the list of attributes that can be
-referenced on an object using the new \member{__slots__} class attribute.
-Python objects are usually very dynamic; at any time it's possible to
-define a new attribute on an instance by just doing
-\code{obj.new_attr=1}. A new-style class can define a class attribute named
-\member{__slots__} to limit the legal attributes
-to a particular set of names. An example will make this clear:
-
-\begin{verbatim}
->>> class C(object):
-... __slots__ = ('template', 'name')
-...
->>> obj = C()
->>> print obj.template
-None
->>> obj.template = 'Test'
->>> print obj.template
-Test
->>> obj.newattr = None
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-AttributeError: 'C' object has no attribute 'newattr'
-\end{verbatim}
-
-Note how you get an \exception{AttributeError} on the attempt to
-assign to an attribute not listed in \member{__slots__}.
-
-
-
-\subsection{Related Links}
-\label{sect-rellinks}
-
-This section has just been a quick overview of the new features,
-giving enough of an explanation to start you programming, but many
-details have been simplified or ignored. Where should you go to get a
-more complete picture?
-
-\url{http://www.python.org/2.2/descrintro.html} is a lengthy tutorial
-introduction to the descriptor features, written by Guido van Rossum.
-If my description has whetted your appetite, go read this tutorial
-next, because it goes into much more detail about the new features
-while still remaining quite easy to read.
-
-Next, there are two relevant PEPs, \pep{252} and \pep{253}. \pep{252}
-is titled "Making Types Look More Like Classes", and covers the
-descriptor API. \pep{253} is titled "Subtyping Built-in Types", and
-describes the changes to type objects that make it possible to subtype
-built-in objects. \pep{253} is the more complicated PEP of the two,
-and at a few points the necessary explanations of types and meta-types
-may cause your head to explode. Both PEPs were written and
-implemented by Guido van Rossum, with substantial assistance from the
-rest of the Zope Corp. team.
-
-Finally, there's the ultimate authority: the source code. Most of the
-machinery for the type handling is in \file{Objects/typeobject.c}, but
-you should only resort to it after all other avenues have been
-exhausted, including posting a question to python-list or python-dev.
-
-
-%======================================================================
-\section{PEP 234: Iterators}
-
-Another significant addition to 2.2 is an iteration interface at both
-the C and Python levels. Objects can define how they can be looped
-over by callers.
-
-In Python versions up to 2.1, the usual way to make \code{for item in
-obj} work is to define a \method{__getitem__()} method that looks
-something like this:
-
-\begin{verbatim}
- def __getitem__(self, index):
- return <next item>
-\end{verbatim}
-
-\method{__getitem__()} is more properly used to define an indexing
-operation on an object so that you can write \code{obj[5]} to retrieve
-the sixth element. It's a bit misleading when you're using this only
-to support \keyword{for} loops. Consider some file-like object that
-wants to be looped over; the \var{index} parameter is essentially
-meaningless, as the class probably assumes that a series of
-\method{__getitem__()} calls will be made with \var{index}
-incrementing by one each time. In other words, the presence of the
-\method{__getitem__()} method doesn't mean that using \code{file[5]}
-to randomly access the sixth element will work, though it really should.
-
-In Python 2.2, iteration can be implemented separately, and
-\method{__getitem__()} methods can be limited to classes that really
-do support random access. The basic idea of iterators is
-simple. A new built-in function, \function{iter(obj)} or
-\code{iter(\var{C}, \var{sentinel})}, is used to get an iterator.
-\function{iter(obj)} returns an iterator for the object \var{obj},
-while \code{iter(\var{C}, \var{sentinel})} returns an iterator that
-will invoke the callable object \var{C} until it returns
-\var{sentinel} to signal that the iterator is done.
-
-Python classes can define an \method{__iter__()} method, which should
-create and return a new iterator for the object; if the object is its
-own iterator, this method can just return \code{self}. In particular,
-iterators will usually be their own iterators. Extension types
-implemented in C can implement a \member{tp_iter} function in order to
-return an iterator, and extension types that want to behave as
-iterators can define a \member{tp_iternext} function.
-
-So, after all this, what do iterators actually do? They have one
-required method, \method{next()}, which takes no arguments and returns
-the next value. When there are no more values to be returned, calling
-\method{next()} should raise the \exception{StopIteration} exception.
-
-\begin{verbatim}
->>> L = [1,2,3]
->>> i = iter(L)
->>> print i
-<iterator object at 0x8116870>
->>> i.next()
-1
->>> i.next()
-2
->>> i.next()
-3
->>> i.next()
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-StopIteration
->>>
-\end{verbatim}
-
-In 2.2, Python's \keyword{for} statement no longer expects a sequence;
-it expects something for which \function{iter()} will return an iterator.
-For backward compatibility and convenience, an iterator is
-automatically constructed for sequences that don't implement
-\method{__iter__()} or a \member{tp_iter} slot, so \code{for i in
-[1,2,3]} will still work. Wherever the Python interpreter loops over
-a sequence, it's been changed to use the iterator protocol. This
-means you can do things like this:
-
-\begin{verbatim}
->>> L = [1,2,3]
->>> i = iter(L)
->>> a,b,c = i
->>> a,b,c
-(1, 2, 3)
-\end{verbatim}
-
-Iterator support has been added to some of Python's basic types.
-Calling \function{iter()} on a dictionary will return an iterator
-which loops over its keys:
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
-
-That's just the default behaviour. If you want to iterate over keys,
-values, or key/value pairs, you can explicitly call the
-\method{iterkeys()}, \method{itervalues()}, or \method{iteritems()}
-methods to get an appropriate iterator. In a minor related change,
-the \keyword{in} operator now works on dictionaries, so
-\code{\var{key} in dict} is now equivalent to
-\code{dict.has_key(\var{key})}.
-
-Files also provide an iterator, which calls the \method{readline()}
-method until there are no more lines in the file. This means you can
-now read each line of a file using code like this:
-
-\begin{verbatim}
-for line in file:
- # do something for each line
- ...
-\end{verbatim}
-
-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.
-An iterator object could provide such additional capabilities, but the
-iterator protocol only requires a \method{next()} method.
-
-\begin{seealso}
-
-\seepep{234}{Iterators}{Written by Ka-Ping Yee and GvR; implemented
-by the Python Labs crew, mostly by GvR and Tim Peters.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 255: Simple Generators}
-
-Generators are another new feature, one that interacts with the
-introduction of iterators.
-
-You're doubtless familiar with how 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 \keyword{return}
-statement, the local variables are destroyed and the resulting value
-is returned to the caller. A later call to the same function will get
-a fresh new 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:
-
-\begin{verbatim}
-def generate_ints(N):
- for i in range(N):
- yield i
-\end{verbatim}
-
-A new keyword, \keyword{yield}, was introduced for generators. Any
-function containing a \keyword{yield} statement is a generator
-function; this is detected by Python's bytecode compiler which
-compiles the function specially as a result. Because a new keyword was
-introduced, generators must be explicitly enabled in a module by
-including a \code{from __future__ import generators} statement near
-the top of the module's source code. In Python 2.3 this statement
-will become unnecessary.
-
-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 \keyword{yield} statement, the generator
-outputs the value of \code{i}, similar to a \keyword{return}
-statement. The big difference between \keyword{yield} and a
-\keyword{return} statement is that on reaching a \keyword{yield} the
-generator's state of execution is suspended and local variables are
-preserved. On the next call to the generator's \code{next()} method,
-the function will resume executing immediately after the
-\keyword{yield} statement. (For complicated reasons, the
-\keyword{yield} statement isn't allowed inside the \keyword{try} block
-of a \keyword{try}...\keyword{finally} statement; read \pep{255} for a full
-explanation of the interaction between \keyword{yield} and
-exceptions.)
-
-Here's a sample usage of the \function{generate_ints} generator:
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
-
-You could equally write \code{for i in generate_ints(5)}, or
-\code{a,b,c = generate_ints(3)}.
-
-Inside a generator function, the \keyword{return} statement can only
-be used without a value, and signals the end of the procession of
-values; afterwards the generator cannot return any further values.
-\keyword{return} with a value, such as \code{return 5}, is a syntax
-error inside a generator function. The end of the generator's results
-can also be indicated by raising \exception{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 \code{self.count} to 0, and having the
-\method{next()} method increment \code{self.count} and return it.
-However, for a moderately complicated generator, writing a
-corresponding class would be much messier.
-\file{Lib/test/test_generators.py} contains a number of more
-interesting examples. The simplest one implements an in-order
-traversal of a tree using generators recursively.
-
-\begin{verbatim}
-# 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
-\end{verbatim}
-
-Two other examples in \file{Lib/test/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
-(a route that takes a knight to every square of an $NxN$ chessboard
-without visiting any square twice).
-
-The idea of generators comes from other programming languages,
-especially Icon (\url{http://www.cs.arizona.edu/icon/}), where the
-idea of generators is central. In Icon, every
-expression and function call behaves like a generator. One example
-from ``An Overview of the Icon Programming Language'' at
-\url{http://www.cs.arizona.edu/icon/docs/ipd266.htm} gives an idea of
-what this looks like:
-
-\begin{verbatim}
-sentence := "Store it in the neighboring harbor"
-if (i := find("or", sentence)) > 5 then write(i)
-\end{verbatim}
-
-In Icon the \function{find()} function returns the indexes at which the
-substring ``or'' is found: 3, 23, 33. In the \keyword{if} statement,
-\code{i} is first assigned a value of 3, but 3 is less than 5, so the
-comparison fails, and Icon retries it with the second value of 23. 23
-is greater than 5, so the comparison now succeeds, and the code prints
-the value 23 to the screen.
-
-Python doesn't go nearly as far as Icon in adopting generators as a
-central concept. Generators are considered a new part of the core
-Python language, but learning or using them isn't compulsory; if they
-don't solve any problems that you have, feel free to ignore them.
-One novel feature of Python's interface as compared to
-Icon's is that a generator's state is represented as a concrete object
-(the iterator) that can be passed around to other functions or stored
-in a data structure.
-
-\begin{seealso}
-
-\seepep{255}{Simple Generators}{Written by Neil Schemenauer, Tim
-Peters, Magnus Lie Hetland. Implemented mostly by Neil Schemenauer
-and Tim Peters, with other fixes from the Python Labs crew.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 237: Unifying Long Integers and Integers}
-
-In recent versions, the distinction between regular integers, which
-are 32-bit values on most machines, and long integers, which can be of
-arbitrary size, was becoming an annoyance. For example, on platforms
-that support files larger than \code{2**32} bytes, the
-\method{tell()} method of file objects has to return a long integer.
-However, there were various bits of Python that expected plain
-integers and would raise an error if a long integer was provided
-instead. For example, in Python 1.5, only regular integers
-could be used as a slice index, and \code{'abc'[1L:]} would raise a
-\exception{TypeError} exception with the message 'slice index must be
-int'.
-
-Python 2.2 will shift values from short to long integers as required.
-The 'L' suffix is no longer needed to indicate a long integer literal,
-as now the compiler will choose the appropriate type. (Using the 'L'
-suffix will be discouraged in future 2.x versions of Python,
-triggering a warning in Python 2.4, and probably dropped in Python
-3.0.) Many operations that used to raise an \exception{OverflowError}
-will now return a long integer as their result. For example:
-
-\begin{verbatim}
->>> 1234567890123
-1234567890123L
->>> 2 ** 64
-18446744073709551616L
-\end{verbatim}
-
-In most cases, integers and long integers will now be treated
-identically. You can still distinguish them with the
-\function{type()} built-in function, but that's rarely needed.
-
-\begin{seealso}
-
-\seepep{237}{Unifying Long Integers and Integers}{Written by
-Moshe Zadka and Guido van Rossum. Implemented mostly by Guido van
-Rossum.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 238: Changing the Division Operator}
-
-The most controversial change in Python 2.2 heralds the start of an effort
-to fix an old design flaw that's been in Python from the beginning.
-Currently Python's division operator, \code{/}, behaves like C's
-division operator when presented with two integer arguments: it
-returns an integer result that's truncated down when there would be
-a fractional part. For example, \code{3/2} is 1, not 1.5, and
-\code{(-1)/2} is -1, not -0.5. This means that the results of divison
-can vary unexpectedly depending on the type of the two operands and
-because Python is dynamically typed, it can be difficult to determine
-the possible types of the operands.
-
-(The controversy is over whether this is \emph{really} a design flaw,
-and whether it's worth breaking existing code to fix this. It's
-caused endless discussions on python-dev, and in July 2001 erupted into an
-storm of acidly sarcastic postings on \newsgroup{comp.lang.python}. I
-won't argue for either side here and will stick to describing what's
-implemented in 2.2. Read \pep{238} for a summary of arguments and
-counter-arguments.)
-
-Because this change might break code, it's being introduced very
-gradually. Python 2.2 begins the transition, but the switch won't be
-complete until Python 3.0.
-
-First, I'll borrow some terminology from \pep{238}. ``True division'' is the
-division that most non-programmers are familiar with: 3/2 is 1.5, 1/4
-is 0.25, and so forth. ``Floor division'' is what Python's \code{/}
-operator currently does when given integer operands; the result is the
-floor of the value returned by true division. ``Classic division'' is
-the current mixed behaviour of \code{/}; it returns the result of
-floor division when the operands are integers, and returns the result
-of true division when one of the operands is a floating-point number.
-
-Here are the changes 2.2 introduces:
-
-\begin{itemize}
-
-\item A new operator, \code{//}, is the floor division operator.
-(Yes, we know it looks like \Cpp's comment symbol.) \code{//}
-\emph{always} performs floor division no matter what the types of
-its operands are, so \code{1 // 2} is 0 and \code{1.0 // 2.0} is also
-0.0.
-
-\code{//} is always available in Python 2.2; you don't need to enable
-it using a \code{__future__} statement.
-
-\item By including a \code{from __future__ import division} in a
-module, the \code{/} operator will be changed to return the result of
-true division, so \code{1/2} is 0.5. Without the \code{__future__}
-statement, \code{/} still means classic division. The default meaning
-of \code{/} will not change until Python 3.0.
-
-\item Classes can define methods called \method{__truediv__} and
-\method{__floordiv__} to overload the two division operators. At the
-C level, there are also slots in the \ctype{PyNumberMethods} structure
-so extension types can define the two operators.
-
-\item Python 2.2 supports some command-line arguments for testing
-whether code will works with the changed division semantics. Running
-python with \programopt{-Q warn} will cause a warning to be issued
-whenever division is applied to two integers. You can use this to
-find code that's affected by the change and fix it. By default,
-Python 2.2 will simply perform classic division without a warning; the
-warning will be turned on by default in Python 2.3.
-
-\end{itemize}
-
-\begin{seealso}
-
-\seepep{238}{Changing the Division Operator}{Written by Moshe Zadka and
-Guido van Rossum. Implemented by Guido van Rossum..}
-
-\end{seealso}
-
-
-%======================================================================
-\section{Unicode Changes}
-
-Python's Unicode support has been enhanced a bit in 2.2. Unicode
-strings are usually stored as UCS-2, as 16-bit unsigned integers.
-Python 2.2 can also be compiled to use UCS-4, 32-bit unsigned
-integers, as its internal encoding by supplying
-\longprogramopt{enable-unicode=ucs4} to the configure script.
-(It's also possible to specify
-\longprogramopt{disable-unicode} to completely disable Unicode
-support.)
-
-When built to use UCS-4 (a ``wide Python''), the interpreter can
-natively handle Unicode characters from U+000000 to U+110000, so the
-range of legal values for the \function{unichr()} function is expanded
-accordingly. Using an interpreter compiled to use UCS-2 (a ``narrow
-Python''), values greater than 65535 will still cause
-\function{unichr()} to raise a \exception{ValueError} exception.
-This is all described in \pep{261}, ``Support for `wide' Unicode
-characters''; consult it for further details.
-
-Another change is simpler to explain. Since their introduction,
-Unicode strings have supported an \method{encode()} method to convert
-the string to a selected encoding such as UTF-8 or Latin-1. A
-symmetric \method{decode(\optional{\var{encoding}})} method has been
-added to 8-bit strings (though not to Unicode strings) in 2.2.
-\method{decode()} assumes that the string is in the specified encoding
-and decodes it, returning whatever is returned by the codec.
-
-Using this new feature, codecs have been added for tasks not directly
-related to Unicode. For example, codecs have been added for
-uu-encoding, MIME's base64 encoding, and compression with the
-\module{zlib} module:
-
-\begin{verbatim}
->>> s = """Here is a lengthy piece of redundant, overly verbose,
-... and repetitive text.
-... """
->>> data = s.encode('zlib')
->>> data
-'x\x9c\r\xc9\xc1\r\x80 \x10\x04\xc0?Ul...'
->>> data.decode('zlib')
-'Here is a lengthy piece of redundant, overly verbose,\nand repetitive text.\n'
->>> print s.encode('uu')
-begin 666 <data>
-M2&5R92!I<R!A(&QE;F=T:'D@<&EE8V4@;V8@<F5D=6YD86YT+"!O=F5R;'D@
->=F5R8F]S92P*86YD(')E<&5T:71I=F4@=&5X="X*
-
-end
->>> "sheesh".encode('rot-13')
-'furrfu'
-\end{verbatim}
-
-To convert a class instance to Unicode, a \method{__unicode__} method
-can be defined by a class, analogous to \method{__str__}.
-
-\method{encode()}, \method{decode()}, and \method{__unicode__} were
-implemented by Marc-Andr\'e Lemburg. The changes to support using
-UCS-4 internally were implemented by Fredrik Lundh and Martin von
-L\"owis.
-
-\begin{seealso}
-
-\seepep{261}{Support for `wide' Unicode characters}{Written by
-Paul Prescod.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 227: Nested Scopes}
-
-In Python 2.1, statically nested scopes were added as an optional
-feature, to be enabled by a \code{from __future__ import
-nested_scopes} directive. In 2.2 nested scopes no longer need to be
-specially enabled, and are now always present. The rest of this section
-is a copy of the description of nested scopes from my ``What's New in
-Python 2.1'' document; if you read it when 2.1 came out, you can skip
-the rest of this section.
-
-The largest change introduced in Python 2.1, and made complete in 2.2,
-is to Python's scoping rules. In Python 2.0, at any given time there
-are at most three namespaces used to look up variable names: local,
-module-level, and the built-in namespace. This often surprised people
-because it didn't match their intuitive expectations. For example, a
-nested recursive function definition doesn't work:
-
-\begin{verbatim}
-def f():
- ...
- def g(value):
- ...
- return g(value-1) + 1
- ...
-\end{verbatim}
-
-The function \function{g()} will always raise a \exception{NameError}
-exception, because the binding of the name \samp{g} isn't in either
-its local namespace or in the module-level namespace. This isn't much
-of a problem in practice (how often do you recursively define interior
-functions like this?), but this also made using the \keyword{lambda}
-statement clumsier, and this was a problem in practice. In code which
-uses \keyword{lambda} you can often find local variables being copied
-by passing them as the default values of arguments.
-
-\begin{verbatim}
-def find(self, name):
- "Return list of any entries equal to 'name'"
- L = filter(lambda x, name=name: x == name,
- self.list_attribute)
- return L
-\end{verbatim}
-
-The readability of Python code written in a strongly functional style
-suffers greatly as a result.
-
-The most significant change to Python 2.2 is that static scoping has
-been added to the language to fix this problem. As a first effect,
-the \code{name=name} default argument is now unnecessary in the above
-example. Put simply, when a given variable name is not assigned a
-value within a function (by an assignment, or the \keyword{def},
-\keyword{class}, or \keyword{import} statements), references to the
-variable will be looked up in the local namespace of the enclosing
-scope. A more detailed explanation of the rules, and a dissection of
-the implementation, can be found in the PEP.
-
-This change may cause some compatibility problems for code where the
-same variable name is used both at the module level and as a local
-variable within a function that contains further function definitions.
-This seems rather unlikely though, since such code would have been
-pretty confusing to read in the first place.
-
-One side effect of the change is that the \code{from \var{module}
-import *} and \keyword{exec} statements have been made illegal inside
-a function scope under certain conditions. The Python reference
-manual has said all along that \code{from \var{module} import *} is
-only legal at the top level of a module, but the CPython interpreter
-has never enforced this before. As part of the implementation of
-nested scopes, the compiler which turns Python source into bytecodes
-has to generate different code to access variables in a containing
-scope. \code{from \var{module} import *} and \keyword{exec} make it
-impossible for the compiler to figure this out, because they add names
-to the local namespace that are unknowable at compile time.
-Therefore, if a function contains function definitions or
-\keyword{lambda} expressions with free variables, the compiler will
-flag this by raising a \exception{SyntaxError} exception.
-
-To make the preceding explanation a bit clearer, here's an example:
-
-\begin{verbatim}
-x = 1
-def f():
- # The next line is a syntax error
- exec 'x=2'
- def g():
- return x
-\end{verbatim}
-
-Line 4 containing the \keyword{exec} statement is a syntax error,
-since \keyword{exec} would define a new local variable named \samp{x}
-whose value should be accessed by \function{g()}.
-
-This shouldn't be much of a limitation, since \keyword{exec} is rarely
-used in most Python code (and when it is used, it's often a sign of a
-poor design anyway).
-
-\begin{seealso}
-
-\seepep{227}{Statically Nested Scopes}{Written and implemented by
-Jeremy Hylton.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{New and Improved Modules}
-
-\begin{itemize}
-
- \item The \module{xmlrpclib} module was contributed to the standard
- library by Fredrik Lundh, providing support for writing XML-RPC
- clients. XML-RPC is a simple remote procedure call protocol built on
- top of HTTP and XML. For example, the following snippet retrieves a
- list of RSS channels from the O'Reilly Network, and then
- lists the recent headlines for one channel:
-
-\begin{verbatim}
-import xmlrpclib
-s = xmlrpclib.Server(
- 'http://www.oreillynet.com/meerkat/xml-rpc/server.php')
-channels = s.meerkat.getChannels()
-# channels is a list of dictionaries, like this:
-# [{'id': 4, 'title': 'Freshmeat Daily News'}
-# {'id': 190, 'title': '32Bits Online'},
-# {'id': 4549, 'title': '3DGamers'}, ... ]
-
-# Get the items for one channel
-items = s.meerkat.getItems( {'channel': 4} )
-
-# 'items' is another list of dictionaries, like this:
-# [{'link': 'http://freshmeat.net/releases/52719/',
-# 'description': 'A utility which converts HTML to XSL FO.',
-# 'title': 'html2fo 0.3 (Default)'}, ... ]
-\end{verbatim}
-
-The \module{SimpleXMLRPCServer} module makes it easy to create
-straightforward XML-RPC servers. See \url{http://www.xmlrpc.com/} for
-more information about XML-RPC.
-
- \item The new \module{hmac} module implements the HMAC
- algorithm described by \rfc{2104}.
- (Contributed by Gerhard H\"aring.)
-
- \item Several functions that originally returned lengthy tuples now
- return pseudo-sequences that still behave like tuples but also have
- mnemonic attributes such as member{st_mtime} or \member{tm_year}.
- The enhanced functions include \function{stat()},
- \function{fstat()}, \function{statvfs()}, and \function{fstatvfs()}
- in the \module{os} module, and \function{localtime()},
- \function{gmtime()}, and \function{strptime()} in the \module{time}
- module.
-
- For example, to obtain a file's size using the old tuples, you'd end
- up writing something like \code{file_size =
- os.stat(filename)[stat.ST_SIZE]}, but now this can be written more
- clearly as \code{file_size = os.stat(filename).st_size}.
-
- The original patch for this feature was contributed by Nick Mathewson.
-
- \item The Python profiler has been extensively reworked and various
- errors in its output have been corrected. (Contributed by
- Fred~L. Drake, Jr. and Tim Peters.)
-
- \item The \module{socket} module can be compiled to support IPv6;
- specify the \longprogramopt{enable-ipv6} option to Python's configure
- script. (Contributed by Jun-ichiro ``itojun'' Hagino.)
-
- \item Two new format characters were added to the \module{struct}
- module for 64-bit integers on platforms that support the C
- \ctype{long long} type. \samp{q} is for a signed 64-bit integer,
- and \samp{Q} is for an unsigned one. The value is returned in
- Python's long integer type. (Contributed by Tim Peters.)
-
- \item In the interpreter's interactive mode, there's a new built-in
- function \function{help()} that uses the \module{pydoc} module
- introduced in Python 2.1 to provide interactive help.
- \code{help(\var{object})} displays any available help text about
- \var{object}. \function{help()} with no argument puts you in an online
- help utility, where you can enter the names of functions, classes,
- or modules to read their help text.
- (Contributed by Guido van Rossum, using Ka-Ping Yee's \module{pydoc} module.)
-
- \item Various bugfixes and performance improvements have been made
- to the SRE engine underlying the \module{re} module. For example,
- the \function{re.sub()} and \function{re.split()} functions have
- been rewritten in C. Another contributed patch speeds up certain
- Unicode character ranges by a factor of two, and a new \method{finditer()}
- method that returns an iterator over all the non-overlapping matches in
- a given string.
- (SRE is maintained by
- Fredrik Lundh. The BIGCHARSET patch was contributed by Martin von
- L\"owis.)
-
- \item The \module{smtplib} module now supports \rfc{2487}, ``Secure
- SMTP over TLS'', so it's now possible to encrypt the SMTP traffic
- between a Python program and the mail transport agent being handed a
- message. \module{smtplib} also supports SMTP authentication.
- (Contributed by Gerhard H\"aring.)
-
- \item The \module{imaplib} module, maintained by Piers Lauder, has
- support for several new extensions: the NAMESPACE extension defined
- in \rfc{2342}, SORT, GETACL and SETACL. (Contributed by Anthony
- Baxter and Michel Pelletier.)
-
- \item The \module{rfc822} module's parsing of email addresses is now
- compliant with \rfc{2822}, an update to \rfc{822}. (The module's
- name is \emph{not} going to be changed to \samp{rfc2822}.) A new
- package, \module{email}, has also been added for parsing and
- generating e-mail messages. (Contributed by Barry Warsaw, and
- arising out of his work on Mailman.)
-
- \item The \module{difflib} module now contains a new \class{Differ}
- class for producing human-readable lists of changes (a ``delta'')
- between two sequences of lines of text. There are also two
- generator functions, \function{ndiff()} and \function{restore()},
- which respectively return a delta from two sequences, or one of the
- original sequences from a delta. (Grunt work contributed by David
- Goodger, from ndiff.py code by Tim Peters who then did the
- generatorization.)
-
- \item New constants \constant{ascii_letters},
- \constant{ascii_lowercase}, and \constant{ascii_uppercase} were
- added to the \module{string} module. There were several modules in
- the standard library that used \constant{string.letters} to mean the
- ranges A-Za-z, but that assumption is incorrect when locales are in
- use, because \constant{string.letters} varies depending on the set
- of legal characters defined by the current locale. The buggy
- modules have all been fixed to use \constant{ascii_letters} instead.
- (Reported by an unknown person; fixed by Fred~L. Drake, Jr.)
-
- \item The \module{mimetypes} module now makes it easier to use
- alternative MIME-type databases by the addition of a
- \class{MimeTypes} class, which takes a list of filenames to be
- parsed. (Contributed by Fred~L. Drake, Jr.)
-
- \item A \class{Timer} class was added to the \module{threading}
- module that allows scheduling an activity to happen at some future
- time. (Contributed by Itamar Shtull-Trauring.)
-
-\end{itemize}
-
-
-%======================================================================
-\section{Interpreter Changes and Fixes}
-
-Some of the changes only affect people who deal with the Python
-interpreter at the C level because they're writing Python extension modules,
-embedding the interpreter, or just hacking on the interpreter itself.
-If you only write Python code, none of the changes described here will
-affect you very much.
-
-\begin{itemize}
-
- \item Profiling and tracing functions can now be implemented in C,
- which can operate at much higher speeds than Python-based functions
- and should reduce the overhead of profiling and tracing. This
- will be of interest to authors of development environments for
- Python. Two new C functions were added to Python's API,
- \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}.
- The existing \function{sys.setprofile()} and
- \function{sys.settrace()} functions still exist, and have simply
- been changed to use the new C-level interface. (Contributed by Fred
- L. Drake, Jr.)
-
- \item Another low-level API, primarily of interest to implementors
- of Python debuggers and development tools, was added.
- \cfunction{PyInterpreterState_Head()} and
- \cfunction{PyInterpreterState_Next()} let a caller walk through all
- the existing interpreter objects;
- \cfunction{PyInterpreterState_ThreadHead()} and
- \cfunction{PyThreadState_Next()} allow looping over all the thread
- states for a given interpreter. (Contributed by David Beazley.)
-
-\item The C-level interface to the garbage collector has been changed
-to make it easier to write extension types that support garbage
-collection and to debug misuses of the functions.
-Various functions have slightly different semantics, so a bunch of
-functions had to be renamed. Extensions that use the old API will
-still compile but will \emph{not} participate in garbage collection,
-so updating them for 2.2 should be considered fairly high priority.
-
-To upgrade an extension module to the new API, perform the following
-steps:
-
-\begin{itemize}
-
-\item Rename \cfunction{Py_TPFLAGS_GC} to \cfunction{PyTPFLAGS_HAVE_GC}.
-
-\item Use \cfunction{PyObject_GC_New} or \cfunction{PyObject_GC_NewVar} to
-allocate objects, and \cfunction{PyObject_GC_Del} to deallocate them.
-
-\item Rename \cfunction{PyObject_GC_Init} to \cfunction{PyObject_GC_Track} and
-\cfunction{PyObject_GC_Fini} to \cfunction{PyObject_GC_UnTrack}.
-
-\item Remove \cfunction{PyGC_HEAD_SIZE} from object size calculations.
-
-\item Remove calls to \cfunction{PyObject_AS_GC} and \cfunction{PyObject_FROM_GC}.
-
-\end{itemize}
-
- \item A new \samp{et} format sequence was added to
- \cfunction{PyArg_ParseTuple}; \samp{et} takes both a parameter and
- an encoding name, and converts the parameter to the given encoding
- if the parameter turns out to be a Unicode string, or leaves it
- alone if it's an 8-bit string, assuming it to already be in the
- desired encoding. This differs from the \samp{es} format character,
- which assumes that 8-bit strings are in Python's default ASCII
- encoding and converts them to the specified new encoding.
- (Contributed by M.-A. Lemburg, and used for the MBCS support on
- Windows described in the following section.)
-
- \item A different argument parsing function,
- \cfunction{PyArg_UnpackTuple()}, has been added that's simpler and
- presumably faster. Instead of specifying a format string, the
- caller simply gives the minimum and maximum number of arguments
- expected, and a set of pointers to \ctype{PyObject*} variables that
- will be filled in with argument values.
-
- \item Two new flags \constant{METH_NOARGS} and \constant{METH_O} are
- available in method definition tables to simplify implementation of
- methods with no arguments or a single untyped argument. Calling
- such methods is more efficient than calling a corresponding method
- that uses \constant{METH_VARARGS}.
- Also, the old \constant{METH_OLDARGS} style of writing C methods is
- now officially deprecated.
-
-\item
- Two new wrapper functions, \cfunction{PyOS_snprintf()} and
- \cfunction{PyOS_vsnprintf()} were added to provide
- cross-platform implementations for the relatively new
- \cfunction{snprintf()} and \cfunction{vsnprintf()} C lib APIs. In
- contrast to the standard \cfunction{sprintf()} and
- \cfunction{vsprintf()} functions, the Python versions check the
- bounds of the buffer used to protect against buffer overruns.
- (Contributed by M.-A. Lemburg.)
-
- \item The \cfunction{_PyTuple_Resize()} function has lost an unused
- parameter, so now it takes 2 parameters instead of 3. The third
- argument was never used, and can simply be discarded when porting
- code from earlier versions to Python 2.2.
-
-\end{itemize}
-
-
-%======================================================================
-\section{Other Changes and Fixes}
-
-As usual there were a bunch of other improvements and bugfixes
-scattered throughout the source tree. A search through the CVS change
-logs finds there were 527 patches applied and 683 bugs fixed between
-Python 2.1 and 2.2; 2.2.1 applied 139 patches and fixed 143 bugs;
-2.2.2 applied 106 patches and fixed 82 bugs. These figures are likely
-to be underestimates.
-
-Some of the more notable changes are:
-
-\begin{itemize}
-
- \item The code for the MacOS port for Python, maintained by Jack
- Jansen, is now kept in the main Python CVS tree, and many changes
- have been made to support MacOS~X.
-
-The most significant change is the ability to build Python as a
-framework, enabled by supplying the \longprogramopt{enable-framework}
-option to the configure script when compiling Python. According to
-Jack Jansen, ``This installs a self-contained Python installation plus
-the OS~X framework "glue" into
-\file{/Library/Frameworks/Python.framework} (or another location of
-choice). For now there is little immediate added benefit to this
-(actually, there is the disadvantage that you have to change your PATH
-to be able to find Python), but it is the basis for creating a
-full-blown Python application, porting the MacPython IDE, possibly
-using Python as a standard OSA scripting language and much more.''
-
-Most of the MacPython toolbox modules, which interface to MacOS APIs
-such as windowing, QuickTime, scripting, etc. have been ported to OS~X,
-but they've been left commented out in \file{setup.py}. People who want
-to experiment with these modules can uncomment them manually.
-
-% Jack's original comments:
-%The main change is the possibility to build Python as a
-%framework. This installs a self-contained Python installation plus the
-%OSX framework "glue" into /Library/Frameworks/Python.framework (or
-%another location of choice). For now there is little immedeate added
-%benefit to this (actually, there is the disadvantage that you have to
-%change your PATH to be able to find Python), but it is the basis for
-%creating a fullblown Python application, porting the MacPython IDE,
-%possibly using Python as a standard OSA scripting language and much
-%more. You enable this with "configure --enable-framework".
-
-%The other change is that most MacPython toolbox modules, which
-%interface to all the MacOS APIs such as windowing, quicktime,
-%scripting, etc. have been ported. Again, most of these are not of
-%immedeate use, as they need a full application to be really useful, so
-%they have been commented out in setup.py. People wanting to experiment
-%can uncomment them. Gestalt and Internet Config modules are enabled by
-%default.
-
- \item Keyword arguments passed to builtin functions that don't take them
- now cause a \exception{TypeError} exception to be raised, with the
- message "\var{function} takes no keyword arguments".
-
- \item Weak references, added in Python 2.1 as an extension module,
- are now part of the core because they're used in the implementation
- of new-style classes. The \exception{ReferenceError} exception has
- therefore moved from the \module{weakref} module to become a
- built-in exception.
-
- \item A new script, \file{Tools/scripts/cleanfuture.py} by Tim
- Peters, automatically removes obsolete \code{__future__} statements
- from Python source code.
-
- \item An additional \var{flags} argument has been added to the
- built-in function \function{compile()}, so the behaviour of
- \code{__future__} statements can now be correctly observed in
- simulated shells, such as those presented by IDLE and other
- development environments. This is described in \pep{264}.
- (Contributed by Michael Hudson.)
-
- \item The new license introduced with Python 1.6 wasn't
- GPL-compatible. This is fixed by some minor textual changes to the
- 2.2 license, so it's now legal to embed Python inside a GPLed
- program again. Note that Python itself is not GPLed, but instead is
- under a license that's essentially equivalent to the BSD license,
- same as it always was. The license changes were also applied to the
- Python 2.0.1 and 2.1.1 releases.
-
- \item When presented with a Unicode filename on Windows, Python will
- now convert it to an MBCS encoded string, as used by the Microsoft
- file APIs. As MBCS is explicitly used by the file APIs, Python's
- choice of ASCII as the default encoding turns out to be an
- annoyance. On \UNIX, the locale's character set is used if
- \function{locale.nl_langinfo(CODESET)} is available. (Windows
- support was contributed by Mark Hammond with assistance from
- Marc-Andr\'e Lemburg. \UNIX{} support was added by Martin von L\"owis.)
-
- \item Large file support is now enabled on Windows. (Contributed by
- Tim Peters.)
-
- \item The \file{Tools/scripts/ftpmirror.py} script
- now parses a \file{.netrc} file, if you have one.
- (Contributed by Mike Romberg.)
-
- \item Some features of the object returned by the
- \function{xrange()} function are now deprecated, and trigger
- warnings when they're accessed; they'll disappear in Python 2.3.
- \class{xrange} objects tried to pretend they were full sequence
- types by supporting slicing, sequence multiplication, and the
- \keyword{in} operator, but these features were rarely used and
- therefore buggy. The \method{tolist()} method and the
- \member{start}, \member{stop}, and \member{step} attributes are also
- being deprecated. At the C level, the fourth argument to the
- \cfunction{PyRange_New()} function, \samp{repeat}, has also been
- deprecated.
-
- \item There were a bunch of patches to the dictionary
- implementation, mostly to fix potential core dumps if a dictionary
- contains objects that sneakily changed their hash value, or mutated
- the dictionary they were contained in. For a while python-dev fell
- into a gentle rhythm of Michael Hudson finding a case that dumped
- core, Tim Peters fixing the bug, Michael finding another case, and round
- and round it went.
-
- \item On Windows, Python can now be compiled with Borland C thanks
- to a number of patches contributed by Stephen Hansen, though the
- result isn't fully functional yet. (But this \emph{is} progress...)
-
- \item Another Windows enhancement: Wise Solutions generously offered
- PythonLabs use of their InstallerMaster 8.1 system. Earlier
- PythonLabs Windows installers used Wise 5.0a, which was beginning to
- show its age. (Packaged up by Tim Peters.)
-
- \item Files ending in \samp{.pyw} can now be imported on Windows.
- \samp{.pyw} is a Windows-only thing, used to indicate that a script
- needs to be run using PYTHONW.EXE instead of PYTHON.EXE in order to
- prevent a DOS console from popping up to display the output. This
- patch makes it possible to import such scripts, in case they're also
- usable as modules. (Implemented by David Bolen.)
-
- \item On platforms where Python uses the C \cfunction{dlopen()} function
- to load extension modules, it's now possible to set the flags used
- by \cfunction{dlopen()} using the \function{sys.getdlopenflags()} and
- \function{sys.setdlopenflags()} functions. (Contributed by Bram Stolk.)
-
- \item The \function{pow()} built-in function no longer supports 3
- arguments when floating-point numbers are supplied.
- \code{pow(\var{x}, \var{y}, \var{z})} returns \code{(x**y) \% z}, but
- this is never useful for floating point numbers, and the final
- result varies unpredictably depending on the platform. A call such
- as \code{pow(2.0, 8.0, 7.0)} will now raise a \exception{TypeError}
- exception.
-
-\end{itemize}
-
-
-%======================================================================
-\section{Acknowledgements}
-
-The author would like to thank the following people for offering
-suggestions, corrections and assistance with various drafts of this
-article: Fred Bremmer, Keith Briggs, Andrew Dalke, Fred~L. Drake, Jr.,
-Carel Fellinger, David Goodger, Mark Hammond, Stephen Hansen, Michael
-Hudson, Jack Jansen, Marc-Andr\'e Lemburg, Martin von L\"owis, Fredrik
-Lundh, Michael McLay, Nick Mathewson, Paul Moore, Gustavo Niemeyer,
-Don O'Donnell, Joonas Paalasma, Tim Peters, Jens Quade, Tom Reinhardt, Neil
-Schemenauer, Guido van Rossum, Greg Ward, Edward Welbourne.
-
-\end{document}
diff --git a/Doc/whatsnew/whatsnew23.tex b/Doc/whatsnew/whatsnew23.tex
deleted file mode 100644
index 7c92be2..0000000
--- a/Doc/whatsnew/whatsnew23.tex
+++ /dev/null
@@ -1,2380 +0,0 @@
-\documentclass{howto}
-\usepackage{distutils}
-% $Id$
-
-\title{What's New in Python 2.3}
-\release{1.01}
-\author{A.M.\ Kuchling}
-\authoraddress{
- \strong{Python Software Foundation}\\
- Email: \email{amk@amk.ca}
-}
-
-\begin{document}
-\maketitle
-\tableofcontents
-
-This article explains the new features in Python 2.3. Python 2.3 was
-released on July 29, 2003.
-
-The main themes for Python 2.3 are polishing some of the features
-added in 2.2, adding various small but useful enhancements to the core
-language, and expanding the standard library. The new object model
-introduced in the previous version has benefited from 18 months of
-bugfixes and from optimization efforts that have improved the
-performance of new-style classes. A few new built-in functions have
-been added such as \function{sum()} and \function{enumerate()}. The
-\keyword{in} operator can now be used for substring searches (e.g.
-\code{"ab" in "abc"} returns \constant{True}).
-
-Some of the many new library features include Boolean, set, heap, and
-date/time data types, the ability to import modules from ZIP-format
-archives, metadata support for the long-awaited Python catalog, an
-updated version of IDLE, and modules for logging messages, wrapping
-text, parsing CSV files, processing command-line options, using BerkeleyDB
-databases... the list of new and enhanced modules is lengthy.
-
-This article doesn't attempt to provide a complete specification of
-the new features, but instead provides a convenient overview. For
-full details, you should refer to the documentation for Python 2.3,
-such as the \citetitle[../lib/lib.html]{Python Library Reference} and
-the \citetitle[../ref/ref.html]{Python Reference Manual}. If you want
-to understand the complete implementation and design rationale,
-refer to the PEP for a particular new feature.
-
-
-%======================================================================
-\section{PEP 218: A Standard Set Datatype}
-
-The new \module{sets} module contains an implementation of a set
-datatype. The \class{Set} class is for mutable sets, sets that can
-have members added and removed. The \class{ImmutableSet} class is for
-sets that can't be modified, and instances of \class{ImmutableSet} can
-therefore be used as dictionary keys. Sets are built on top of
-dictionaries, so the elements within a set must be hashable.
-
-Here's a simple example:
-
-\begin{verbatim}
->>> import sets
->>> S = sets.Set([1,2,3])
->>> S
-Set([1, 2, 3])
->>> 1 in S
-True
->>> 0 in S
-False
->>> S.add(5)
->>> S.remove(3)
->>> S
-Set([1, 2, 5])
->>>
-\end{verbatim}
-
-The union and intersection of sets can be computed with the
-\method{union()} and \method{intersection()} methods; an alternative
-notation uses the bitwise operators \code{\&} and \code{|}.
-Mutable sets also have in-place versions of these methods,
-\method{union_update()} and \method{intersection_update()}.
-
-\begin{verbatim}
->>> S1 = sets.Set([1,2,3])
->>> S2 = sets.Set([4,5,6])
->>> S1.union(S2)
-Set([1, 2, 3, 4, 5, 6])
->>> S1 | S2 # Alternative notation
-Set([1, 2, 3, 4, 5, 6])
->>> S1.intersection(S2)
-Set([])
->>> S1 & S2 # Alternative notation
-Set([])
->>> S1.union_update(S2)
->>> S1
-Set([1, 2, 3, 4, 5, 6])
->>>
-\end{verbatim}
-
-It's also possible to take the symmetric difference of two sets. This
-is the set of all elements in the union that aren't in the
-intersection. Another way of putting it is that the symmetric
-difference contains all elements that are in exactly one
-set. Again, there's an alternative notation (\code{\^}), and an
-in-place version with the ungainly name
-\method{symmetric_difference_update()}.
-
-\begin{verbatim}
->>> S1 = sets.Set([1,2,3,4])
->>> S2 = sets.Set([3,4,5,6])
->>> S1.symmetric_difference(S2)
-Set([1, 2, 5, 6])
->>> S1 ^ S2
-Set([1, 2, 5, 6])
->>>
-\end{verbatim}
-
-There are also \method{issubset()} and \method{issuperset()} methods
-for checking whether one set is a subset or superset of another:
-
-\begin{verbatim}
->>> S1 = sets.Set([1,2,3])
->>> S2 = sets.Set([2,3])
->>> S2.issubset(S1)
-True
->>> S1.issubset(S2)
-False
->>> S1.issuperset(S2)
-True
->>>
-\end{verbatim}
-
-
-\begin{seealso}
-
-\seepep{218}{Adding a Built-In Set Object Type}{PEP written by Greg V. Wilson.
-Implemented by Greg V. Wilson, Alex Martelli, and GvR.}
-
-\end{seealso}
-
-
-
-%======================================================================
-\section{PEP 255: Simple Generators\label{section-generators}}
-
-In Python 2.2, generators were added as an optional feature, to be
-enabled by a \code{from __future__ import generators} directive. In
-2.3 generators no longer need to be specially enabled, and are now
-always present; this means that \keyword{yield} is now always a
-keyword. The rest of this section is a copy of the description of
-generators from the ``What's New in Python 2.2'' document; if you read
-it back when Python 2.2 came out, you can skip the rest of this section.
-
-You're doubtless familiar with how 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 \keyword{return}
-statement, the local variables are destroyed and the resulting value
-is returned to the caller. A later call to the same function will get
-a fresh new 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:
-
-\begin{verbatim}
-def generate_ints(N):
- for i in range(N):
- yield i
-\end{verbatim}
-
-A new keyword, \keyword{yield}, was introduced for generators. Any
-function containing a \keyword{yield} statement 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 \keyword{yield} statement, the generator
-outputs the value of \code{i}, similar to a \keyword{return}
-statement. The big difference between \keyword{yield} and a
-\keyword{return} statement is that on reaching a \keyword{yield} the
-generator's state of execution is suspended and local variables are
-preserved. On the next call to the generator's \code{.next()} method,
-the function will resume executing immediately after the
-\keyword{yield} statement. (For complicated reasons, the
-\keyword{yield} statement isn't allowed inside the \keyword{try} block
-of a \keyword{try}...\keyword{finally} statement; read \pep{255} for a full
-explanation of the interaction between \keyword{yield} and
-exceptions.)
-
-Here's a sample usage of the \function{generate_ints()} generator:
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
-
-You could equally write \code{for i in generate_ints(5)}, or
-\code{a,b,c = generate_ints(3)}.
-
-Inside a generator function, the \keyword{return} statement can only
-be used without a value, and signals the end of the procession of
-values; afterwards the generator cannot return any further values.
-\keyword{return} with a value, such as \code{return 5}, is a syntax
-error inside a generator function. The end of the generator's results
-can also be indicated by raising \exception{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 \code{self.count} to 0, and having the
-\method{next()} method increment \code{self.count} and return it.
-However, for a moderately complicated generator, writing a
-corresponding class would be much messier.
-\file{Lib/test/test_generators.py} contains a number of more
-interesting examples. The simplest one implements an in-order
-traversal of a tree using generators recursively.
-
-\begin{verbatim}
-# 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
-\end{verbatim}
-
-Two other examples in \file{Lib/test/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
-(a route that takes a knight to every square of an $NxN$ chessboard
-without visiting any square twice).
-
-The idea of generators comes from other programming languages,
-especially Icon (\url{http://www.cs.arizona.edu/icon/}), where the
-idea of generators is central. In Icon, every
-expression and function call behaves like a generator. One example
-from ``An Overview of the Icon Programming Language'' at
-\url{http://www.cs.arizona.edu/icon/docs/ipd266.htm} gives an idea of
-what this looks like:
-
-\begin{verbatim}
-sentence := "Store it in the neighboring harbor"
-if (i := find("or", sentence)) > 5 then write(i)
-\end{verbatim}
-
-In Icon the \function{find()} function returns the indexes at which the
-substring ``or'' is found: 3, 23, 33. In the \keyword{if} statement,
-\code{i} is first assigned a value of 3, but 3 is less than 5, so the
-comparison fails, and Icon retries it with the second value of 23. 23
-is greater than 5, so the comparison now succeeds, and the code prints
-the value 23 to the screen.
-
-Python doesn't go nearly as far as Icon in adopting generators as a
-central concept. Generators are considered part of the core
-Python language, but learning or using them isn't compulsory; if they
-don't solve any problems that you have, feel free to ignore them.
-One novel feature of Python's interface as compared to
-Icon's is that a generator's state is represented as a concrete object
-(the iterator) that can be passed around to other functions or stored
-in a data structure.
-
-\begin{seealso}
-
-\seepep{255}{Simple Generators}{Written by Neil Schemenauer, Tim
-Peters, Magnus Lie Hetland. Implemented mostly by Neil Schemenauer
-and Tim Peters, with other fixes from the Python Labs crew.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 263: Source Code Encodings \label{section-encodings}}
-
-Python source files can now be declared as being in different
-character set encodings. Encodings are declared by including a
-specially formatted comment in the first or second line of the source
-file. For example, a UTF-8 file can be declared with:
-
-\begin{verbatim}
-#!/usr/bin/env python
-# -*- coding: UTF-8 -*-
-\end{verbatim}
-
-Without such an encoding declaration, the default encoding used is
-7-bit ASCII. Executing or importing modules that contain string
-literals with 8-bit characters and have no encoding declaration will result
-in a \exception{DeprecationWarning} being signalled by Python 2.3; in
-2.4 this will be a syntax error.
-
-The encoding declaration only affects Unicode string literals, which
-will be converted to Unicode using the specified encoding. Note that
-Python identifiers are still restricted to ASCII characters, so you
-can't have variable names that use characters outside of the usual
-alphanumerics.
-
-\begin{seealso}
-
-\seepep{263}{Defining Python Source Code Encodings}{Written by
-Marc-Andr\'e Lemburg and Martin von~L\"owis; implemented by Suzuki
-Hisao and Martin von~L\"owis.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 273: Importing Modules from ZIP Archives}
-
-The new \module{zipimport} module adds support for importing
-modules from a ZIP-format archive. You don't need to import the
-module explicitly; it will be automatically imported if a ZIP
-archive's filename is added to \code{sys.path}. For example:
-
-\begin{verbatim}
-amk@nyman:~/src/python$ unzip -l /tmp/example.zip
-Archive: /tmp/example.zip
- Length Date Time Name
- -------- ---- ---- ----
- 8467 11-26-02 22:30 jwzthreading.py
- -------- -------
- 8467 1 file
-amk@nyman:~/src/python$ ./python
-Python 2.3 (#1, Aug 1 2003, 19:54:32)
->>> import sys
->>> sys.path.insert(0, '/tmp/example.zip') # Add .zip file to front of path
->>> import jwzthreading
->>> jwzthreading.__file__
-'/tmp/example.zip/jwzthreading.py'
->>>
-\end{verbatim}
-
-An entry in \code{sys.path} can now be the filename of a ZIP archive.
-The ZIP archive can contain any kind of files, but only files named
-\file{*.py}, \file{*.pyc}, or \file{*.pyo} can be imported. If an
-archive only contains \file{*.py} files, Python will not attempt to
-modify the archive by adding the corresponding \file{*.pyc} file, meaning
-that if a ZIP archive doesn't contain \file{*.pyc} files, importing may be
-rather slow.
-
-A path within the archive can also be specified to only import from a
-subdirectory; for example, the path \file{/tmp/example.zip/lib/}
-would only import from the \file{lib/} subdirectory within the
-archive.
-
-\begin{seealso}
-
-\seepep{273}{Import Modules from Zip Archives}{Written by James C. Ahlstrom,
-who also provided an implementation.
-Python 2.3 follows the specification in \pep{273},
-but uses an implementation written by Just van~Rossum
-that uses the import hooks described in \pep{302}.
-See section~\ref{section-pep302} for a description of the new import hooks.
-}
-
-\end{seealso}
-
-%======================================================================
-\section{PEP 277: Unicode file name support for Windows NT}
-
-On Windows NT, 2000, and XP, the system stores file names as Unicode
-strings. Traditionally, Python has represented file names as byte
-strings, which is inadequate because it renders some file names
-inaccessible.
-
-Python now allows using arbitrary Unicode strings (within the
-limitations of the file system) for all functions that expect file
-names, most notably the \function{open()} built-in function. If a Unicode
-string is passed to \function{os.listdir()}, Python now returns a list
-of Unicode strings. A new function, \function{os.getcwdu()}, returns
-the current directory as a Unicode string.
-
-Byte strings still work as file names, and on Windows Python will
-transparently convert them to Unicode using the \code{mbcs} encoding.
-
-Other systems also allow Unicode strings as file names but convert
-them to byte strings before passing them to the system, which can
-cause a \exception{UnicodeError} to be raised. Applications can test
-whether arbitrary Unicode strings are supported as file names by
-checking \member{os.path.supports_unicode_filenames}, a Boolean value.
-
-Under MacOS, \function{os.listdir()} may now return Unicode filenames.
-
-\begin{seealso}
-
-\seepep{277}{Unicode file name support for Windows NT}{Written by Neil
-Hodgson; implemented by Neil Hodgson, Martin von~L\"owis, and Mark
-Hammond.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 278: Universal Newline Support}
-
-The three major operating systems used today are Microsoft Windows,
-Apple's Macintosh OS, and the various \UNIX\ derivatives. A minor
-irritation of cross-platform work
-is that these three platforms all use different characters
-to mark the ends of lines in text files. \UNIX\ uses the linefeed
-(ASCII character 10), MacOS uses the carriage return (ASCII
-character 13), and Windows uses a two-character sequence of a
-carriage return plus a newline.
-
-Python's file objects can now support end of line conventions other
-than the one followed by the platform on which Python is running.
-Opening a file with the mode \code{'U'} or \code{'rU'} will open a file
-for reading in universal newline mode. All three line ending
-conventions will be translated to a \character{\e n} in the strings
-returned by the various file methods such as \method{read()} and
-\method{readline()}.
-
-Universal newline support is also used when importing modules and when
-executing a file with the \function{execfile()} function. This means
-that Python modules can be shared between all three operating systems
-without needing to convert the line-endings.
-
-This feature can be disabled when compiling Python by specifying
-the \longprogramopt{without-universal-newlines} switch when running Python's
-\program{configure} script.
-
-\begin{seealso}
-
-\seepep{278}{Universal Newline Support}{Written
-and implemented by Jack Jansen.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 279: enumerate()\label{section-enumerate}}
-
-A new built-in function, \function{enumerate()}, will make
-certain loops a bit clearer. \code{enumerate(thing)}, where
-\var{thing} is either an iterator or a sequence, returns a iterator
-that will return \code{(0, \var{thing}[0])}, \code{(1,
-\var{thing}[1])}, \code{(2, \var{thing}[2])}, and so forth.
-
-A common idiom to change every element of a list looks like this:
-
-\begin{verbatim}
-for i in range(len(L)):
- item = L[i]
- # ... compute some result based on item ...
- L[i] = result
-\end{verbatim}
-
-This can be rewritten using \function{enumerate()} as:
-
-\begin{verbatim}
-for i, item in enumerate(L):
- # ... compute some result based on item ...
- L[i] = result
-\end{verbatim}
-
-
-\begin{seealso}
-
-\seepep{279}{The enumerate() built-in function}{Written
-and implemented by Raymond D. Hettinger.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 282: The logging Package}
-
-A standard package for writing logs, \module{logging}, has been added
-to Python 2.3. It provides a powerful and flexible mechanism for
-generating logging output which can then be filtered and processed in
-various ways. A configuration file written in a standard format can
-be used to control the logging behavior of a program. Python
-includes handlers that will write log records to
-standard error or to a file or socket, send them to the system log, or
-even e-mail them to a particular address; of course, it's also
-possible to write your own handler classes.
-
-The \class{Logger} class is the primary class.
-Most application code will deal with one or more \class{Logger}
-objects, each one used by a particular subsystem of the application.
-Each \class{Logger} is identified by a name, and names are organized
-into a hierarchy using \samp{.} as the component separator. For
-example, you might have \class{Logger} instances named \samp{server},
-\samp{server.auth} and \samp{server.network}. The latter two
-instances are below \samp{server} in the hierarchy. This means that
-if you turn up the verbosity for \samp{server} or direct \samp{server}
-messages to a different handler, the changes will also apply to
-records logged to \samp{server.auth} and \samp{server.network}.
-There's also a root \class{Logger} that's the parent of all other
-loggers.
-
-For simple uses, the \module{logging} package contains some
-convenience functions that always use the root log:
-
-\begin{verbatim}
-import logging
-
-logging.debug('Debugging information')
-logging.info('Informational message')
-logging.warning('Warning:config file %s not found', 'server.conf')
-logging.error('Error occurred')
-logging.critical('Critical error -- shutting down')
-\end{verbatim}
-
-This produces the following output:
-
-\begin{verbatim}
-WARNING:root:Warning:config file server.conf not found
-ERROR:root:Error occurred
-CRITICAL:root:Critical error -- shutting down
-\end{verbatim}
-
-In the default configuration, informational and debugging messages are
-suppressed and the output is sent to standard error. You can enable
-the display of informational and debugging messages by calling the
-\method{setLevel()} method on the root logger.
-
-Notice the \function{warning()} call's use of string formatting
-operators; all of the functions for logging messages take the
-arguments \code{(\var{msg}, \var{arg1}, \var{arg2}, ...)} and log the
-string resulting from \code{\var{msg} \% (\var{arg1}, \var{arg2},
-...)}.
-
-There's also an \function{exception()} function that records the most
-recent traceback. Any of the other functions will also record the
-traceback if you specify a true value for the keyword argument
-\var{exc_info}.
-
-\begin{verbatim}
-def f():
- try: 1/0
- except: logging.exception('Problem recorded')
-
-f()
-\end{verbatim}
-
-This produces the following output:
-
-\begin{verbatim}
-ERROR:root:Problem recorded
-Traceback (most recent call last):
- File "t.py", line 6, in f
- 1/0
-ZeroDivisionError: integer division or modulo by zero
-\end{verbatim}
-
-Slightly more advanced programs will use a logger other than the root
-logger. The \function{getLogger(\var{name})} function is used to get
-a particular log, creating it if it doesn't exist yet.
-\function{getLogger(None)} returns the root logger.
-
-
-\begin{verbatim}
-log = logging.getLogger('server')
- ...
-log.info('Listening on port %i', port)
- ...
-log.critical('Disk full')
- ...
-\end{verbatim}
-
-Log records are usually propagated up the hierarchy, so a message
-logged to \samp{server.auth} is also seen by \samp{server} and
-\samp{root}, but a \class{Logger} can prevent this by setting its
-\member{propagate} attribute to \constant{False}.
-
-There are more classes provided by the \module{logging} package that
-can be customized. When a \class{Logger} instance is told to log a
-message, it creates a \class{LogRecord} instance that is sent to any
-number of different \class{Handler} instances. Loggers and handlers
-can also have an attached list of filters, and each filter can cause
-the \class{LogRecord} to be ignored or can modify the record before
-passing it along. When they're finally output, \class{LogRecord}
-instances are converted to text by a \class{Formatter} class. All of
-these classes can be replaced by your own specially-written classes.
-
-With all of these features the \module{logging} package should provide
-enough flexibility for even the most complicated applications. This
-is only an incomplete overview of its features, so please see the
-\ulink{package's reference documentation}{../lib/module-logging.html}
-for all of the details. Reading \pep{282} will also be helpful.
-
-
-\begin{seealso}
-
-\seepep{282}{A Logging System}{Written by Vinay Sajip and Trent Mick;
-implemented by Vinay Sajip.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 285: A Boolean Type\label{section-bool}}
-
-A Boolean type was added to Python 2.3. Two new constants were added
-to the \module{__builtin__} module, \constant{True} and
-\constant{False}. (\constant{True} and
-\constant{False} constants were added to the built-ins
-in Python 2.2.1, but the 2.2.1 versions are simply set to integer values of
-1 and 0 and aren't a different type.)
-
-The type object for this new type is named
-\class{bool}; the constructor for it takes any Python value and
-converts it to \constant{True} or \constant{False}.
-
-\begin{verbatim}
->>> bool(1)
-True
->>> bool(0)
-False
->>> bool([])
-False
->>> bool( (1,) )
-True
-\end{verbatim}
-
-Most of the standard library modules and built-in functions have been
-changed to return Booleans.
-
-\begin{verbatim}
->>> obj = []
->>> hasattr(obj, 'append')
-True
->>> isinstance(obj, list)
-True
->>> isinstance(obj, tuple)
-False
-\end{verbatim}
-
-Python's Booleans were added with the primary goal of making code
-clearer. For example, if you're reading a function and encounter the
-statement \code{return 1}, you might wonder whether the \code{1}
-represents a Boolean truth value, an index, or a
-coefficient that multiplies some other quantity. If the statement is
-\code{return True}, however, the meaning of the return value is quite
-clear.
-
-Python's Booleans were \emph{not} added for the sake of strict
-type-checking. A very strict language such as Pascal would also
-prevent you performing arithmetic with Booleans, and would require
-that the expression in an \keyword{if} statement always evaluate to a
-Boolean result. Python is not this strict and never will be, as
-\pep{285} explicitly says. This means you can still use any
-expression in an \keyword{if} statement, even ones that evaluate to a
-list or tuple or some random object. The Boolean type is a
-subclass of the \class{int} class so that arithmetic using a Boolean
-still works.
-
-\begin{verbatim}
->>> True + 1
-2
->>> False + 1
-1
->>> False * 75
-0
->>> True * 75
-75
-\end{verbatim}
-
-To sum up \constant{True} and \constant{False} in a sentence: they're
-alternative ways to spell the integer values 1 and 0, with the single
-difference that \function{str()} and \function{repr()} return the
-strings \code{'True'} and \code{'False'} instead of \code{'1'} and
-\code{'0'}.
-
-\begin{seealso}
-
-\seepep{285}{Adding a bool type}{Written and implemented by GvR.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 293: Codec Error Handling Callbacks}
-
-When encoding a Unicode string into a byte string, unencodable
-characters may be encountered. So far, Python has allowed specifying
-the error processing as either ``strict'' (raising
-\exception{UnicodeError}), ``ignore'' (skipping the character), or
-``replace'' (using a question mark in the output string), with
-``strict'' being the default behavior. It may be desirable to specify
-alternative processing of such errors, such as inserting an XML
-character reference or HTML entity reference into the converted
-string.
-
-Python now has a flexible framework to add different processing
-strategies. New error handlers can be added with
-\function{codecs.register_error}, and codecs then can access the error
-handler with \function{codecs.lookup_error}. An equivalent C API has
-been added for codecs written in C. The error handler gets the
-necessary state information such as the string being converted, the
-position in the string where the error was detected, and the target
-encoding. The handler can then either raise an exception or return a
-replacement string.
-
-Two additional error handlers have been implemented using this
-framework: ``backslashreplace'' uses Python backslash quoting to
-represent unencodable characters and ``xmlcharrefreplace'' emits
-XML character references.
-
-\begin{seealso}
-
-\seepep{293}{Codec Error Handling Callbacks}{Written and implemented by
-Walter D\"orwald.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 301: Package Index and Metadata for
-Distutils\label{section-pep301}}
-
-Support for the long-requested Python catalog makes its first
-appearance in 2.3.
-
-The heart of the catalog is the new Distutils \command{register} command.
-Running \code{python setup.py register} will collect the metadata
-describing a package, such as its name, version, maintainer,
-description, \&c., and send it to a central catalog server. The
-resulting catalog is available from \url{http://www.python.org/pypi}.
-
-To make the catalog a bit more useful, a new optional
-\var{classifiers} keyword argument has been added to the Distutils
-\function{setup()} function. A list of
-\ulink{Trove}{http://catb.org/\textasciitilde esr/trove/}-style
-strings can be supplied to help classify the software.
-
-Here's an example \file{setup.py} with classifiers, written to be compatible
-with older versions of the Distutils:
-
-\begin{verbatim}
-from distutils import core
-kw = {'name': "Quixote",
- 'version': "0.5.1",
- 'description': "A highly Pythonic Web application framework",
- # ...
- }
-
-if (hasattr(core, 'setup_keywords') and
- 'classifiers' in core.setup_keywords):
- kw['classifiers'] = \
- ['Topic :: Internet :: WWW/HTTP :: Dynamic Content',
- 'Environment :: No Input/Output (Daemon)',
- 'Intended Audience :: Developers'],
-
-core.setup(**kw)
-\end{verbatim}
-
-The full list of classifiers can be obtained by running
-\verb|python setup.py register --list-classifiers|.
-
-\begin{seealso}
-
-\seepep{301}{Package Index and Metadata for Distutils}{Written and
-implemented by Richard Jones.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 302: New Import Hooks \label{section-pep302}}
-
-While it's been possible to write custom import hooks ever since the
-\module{ihooks} module was introduced in Python 1.3, no one has ever
-been really happy with it because writing new import hooks is
-difficult and messy. There have been various proposed alternatives
-such as the \module{imputil} and \module{iu} modules, but none of them
-has ever gained much acceptance, and none of them were easily usable
-from \C{} code.
-
-\pep{302} borrows ideas from its predecessors, especially from
-Gordon McMillan's \module{iu} module. Three new items
-are added to the \module{sys} module:
-
-\begin{itemize}
- \item \code{sys.path_hooks} is a list of callable objects; most
- often they'll be classes. Each callable takes a string containing a
- path and either returns an importer object that will handle imports
- from this path or raises an \exception{ImportError} exception if it
- can't handle this path.
-
- \item \code{sys.path_importer_cache} caches importer objects for
- each path, so \code{sys.path_hooks} will only need to be traversed
- once for each path.
-
- \item \code{sys.meta_path} is a list of importer objects that will
- be traversed before \code{sys.path} is checked. This list is
- initially empty, but user code can add objects to it. Additional
- built-in and frozen modules can be imported by an object added to
- this list.
-
-\end{itemize}
-
-Importer objects must have a single method,
-\method{find_module(\var{fullname}, \var{path}=None)}. \var{fullname}
-will be a module or package name, e.g. \samp{string} or
-\samp{distutils.core}. \method{find_module()} must return a loader object
-that has a single method, \method{load_module(\var{fullname})}, that
-creates and returns the corresponding module object.
-
-Pseudo-code for Python's new import logic, therefore, looks something
-like this (simplified a bit; see \pep{302} for the full details):
-
-\begin{verbatim}
-for mp in sys.meta_path:
- loader = mp(fullname)
- if loader is not None:
- <module> = loader.load_module(fullname)
-
-for path in sys.path:
- for hook in sys.path_hooks:
- try:
- importer = hook(path)
- except ImportError:
- # ImportError, so try the other path hooks
- pass
- else:
- loader = importer.find_module(fullname)
- <module> = loader.load_module(fullname)
-
-# Not found!
-raise ImportError
-\end{verbatim}
-
-\begin{seealso}
-
-\seepep{302}{New Import Hooks}{Written by Just van~Rossum and Paul Moore.
-Implemented by Just van~Rossum.
-}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 305: Comma-separated Files \label{section-pep305}}
-
-Comma-separated files are a format frequently used for exporting data
-from databases and spreadsheets. Python 2.3 adds a parser for
-comma-separated files.
-
-Comma-separated format is deceptively simple at first glance:
-
-\begin{verbatim}
-Costs,150,200,3.95
-\end{verbatim}
-
-Read a line and call \code{line.split(',')}: what could be simpler?
-But toss in string data that can contain commas, and things get more
-complicated:
-
-\begin{verbatim}
-"Costs",150,200,3.95,"Includes taxes, shipping, and sundry items"
-\end{verbatim}
-
-A big ugly regular expression can parse this, but using the new
-\module{csv} package is much simpler:
-
-\begin{verbatim}
-import csv
-
-input = open('datafile', 'rb')
-reader = csv.reader(input)
-for line in reader:
- print line
-\end{verbatim}
-
-The \function{reader} function takes a number of different options.
-The field separator isn't limited to the comma and can be changed to
-any character, and so can the quoting and line-ending characters.
-
-Different dialects of comma-separated files can be defined and
-registered; currently there are two dialects, both used by Microsoft Excel.
-A separate \class{csv.writer} class will generate comma-separated files
-from a succession of tuples or lists, quoting strings that contain the
-delimiter.
-
-\begin{seealso}
-
-\seepep{305}{CSV File API}{Written and implemented
-by Kevin Altis, Dave Cole, Andrew McNamara, Skip Montanaro, Cliff Wells.
-}
-
-\end{seealso}
-
-%======================================================================
-\section{PEP 307: Pickle Enhancements \label{section-pep307}}
-
-The \module{pickle} and \module{cPickle} modules received some
-attention during the 2.3 development cycle. In 2.2, new-style classes
-could be pickled without difficulty, but they weren't pickled very
-compactly; \pep{307} quotes a trivial example where a new-style class
-results in a pickled string three times longer than that for a classic
-class.
-
-The solution was to invent a new pickle protocol. The
-\function{pickle.dumps()} function has supported a text-or-binary flag
-for a long time. In 2.3, this flag is redefined from a Boolean to an
-integer: 0 is the old text-mode pickle format, 1 is the old binary
-format, and now 2 is a new 2.3-specific format. A new constant,
-\constant{pickle.HIGHEST_PROTOCOL}, can be used to select the fanciest
-protocol available.
-
-Unpickling is no longer considered a safe operation. 2.2's
-\module{pickle} provided hooks for trying to prevent unsafe classes
-from being unpickled (specifically, a
-\member{__safe_for_unpickling__} attribute), but none of this code
-was ever audited and therefore it's all been ripped out in 2.3. You
-should not unpickle untrusted data in any version of Python.
-
-To reduce the pickling overhead for new-style classes, a new interface
-for customizing pickling was added using three special methods:
-\method{__getstate__}, \method{__setstate__}, and
-\method{__getnewargs__}. Consult \pep{307} for the full semantics
-of these methods.
-
-As a way to compress pickles yet further, it's now possible to use
-integer codes instead of long strings to identify pickled classes.
-The Python Software Foundation will maintain a list of standardized
-codes; there's also a range of codes for private use. Currently no
-codes have been specified.
-
-\begin{seealso}
-
-\seepep{307}{Extensions to the pickle protocol}{Written and implemented
-by Guido van Rossum and Tim Peters.}
-
-\end{seealso}
-
-%======================================================================
-\section{Extended Slices\label{section-slices}}
-
-Ever since Python 1.4, the slicing syntax has supported an optional
-third ``step'' or ``stride'' argument. For example, these are all
-legal Python syntax: \code{L[1:10:2]}, \code{L[:-1:1]},
-\code{L[::-1]}. This was added to Python at the request of
-the developers of Numerical Python, which uses the third argument
-extensively. However, Python's built-in list, tuple, and string
-sequence types have never supported this feature, raising a
-\exception{TypeError} if you tried it. Michael Hudson contributed a
-patch to fix this shortcoming.
-
-For example, you can now easily extract the elements of a list that
-have even indexes:
-
-\begin{verbatim}
->>> L = range(10)
->>> L[::2]
-[0, 2, 4, 6, 8]
-\end{verbatim}
-
-Negative values also work to make a copy of the same list in reverse
-order:
-
-\begin{verbatim}
->>> L[::-1]
-[9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
-\end{verbatim}
-
-This also works for tuples, arrays, and strings:
-
-\begin{verbatim}
->>> s='abcd'
->>> s[::2]
-'ac'
->>> s[::-1]
-'dcba'
-\end{verbatim}
-
-If you have a mutable sequence such as a list or an array you can
-assign to or delete an extended slice, but there are some differences
-between assignment to extended and regular slices. Assignment to a
-regular slice can be used to change the length of the sequence:
-
-\begin{verbatim}
->>> a = range(3)
->>> a
-[0, 1, 2]
->>> a[1:3] = [4, 5, 6]
->>> a
-[0, 4, 5, 6]
-\end{verbatim}
-
-Extended slices aren't this flexible. When assigning to an extended
-slice, the list on the right hand side of the statement must contain
-the same number of items as the slice it is replacing:
-
-\begin{verbatim}
->>> a = range(4)
->>> a
-[0, 1, 2, 3]
->>> a[::2]
-[0, 2]
->>> a[::2] = [0, -1]
->>> a
-[0, 1, -1, 3]
->>> a[::2] = [0,1,2]
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ValueError: attempt to assign sequence of size 3 to extended slice of size 2
-\end{verbatim}
-
-Deletion is more straightforward:
-
-\begin{verbatim}
->>> a = range(4)
->>> a
-[0, 1, 2, 3]
->>> a[::2]
-[0, 2]
->>> del a[::2]
->>> a
-[1, 3]
-\end{verbatim}
-
-One can also now pass slice objects to the
-\method{__getitem__} methods of the built-in sequences:
-
-\begin{verbatim}
->>> range(10).__getitem__(slice(0, 5, 2))
-[0, 2, 4]
-\end{verbatim}
-
-Or use slice objects directly in subscripts:
-
-\begin{verbatim}
->>> range(10)[slice(0, 5, 2)]
-[0, 2, 4]
-\end{verbatim}
-
-To simplify implementing sequences that support extended slicing,
-slice objects now have a method \method{indices(\var{length})} which,
-given the length of a sequence, returns a \code{(\var{start},
-\var{stop}, \var{step})} tuple that can be passed directly to
-\function{range()}.
-\method{indices()} handles omitted and out-of-bounds indices in a
-manner consistent with regular slices (and this innocuous phrase hides
-a welter of confusing details!). The method is intended to be used
-like this:
-
-\begin{verbatim}
-class FakeSeq:
- ...
- def calc_item(self, i):
- ...
- def __getitem__(self, item):
- if isinstance(item, slice):
- indices = item.indices(len(self))
- return FakeSeq([self.calc_item(i) for i in range(*indices)])
- else:
- return self.calc_item(i)
-\end{verbatim}
-
-From this example you can also see that the built-in \class{slice}
-object is now the type object for the slice type, and is no longer a
-function. This is consistent with Python 2.2, where \class{int},
-\class{str}, etc., underwent the same change.
-
-
-%======================================================================
-\section{Other Language Changes}
-
-Here are all of the changes that Python 2.3 makes to the core Python
-language.
-
-\begin{itemize}
-\item The \keyword{yield} statement is now always a keyword, as
-described in section~\ref{section-generators} of this document.
-
-\item A new built-in function \function{enumerate()}
-was added, as described in section~\ref{section-enumerate} of this
-document.
-
-\item Two new constants, \constant{True} and \constant{False} were
-added along with the built-in \class{bool} type, as described in
-section~\ref{section-bool} of this document.
-
-\item The \function{int()} type constructor will now return a long
-integer instead of raising an \exception{OverflowError} when a string
-or floating-point number is too large to fit into an integer. This
-can lead to the paradoxical result that
-\code{isinstance(int(\var{expression}), int)} is false, but that seems
-unlikely to cause problems in practice.
-
-\item Built-in types now support the extended slicing syntax,
-as described in section~\ref{section-slices} of this document.
-
-\item A new built-in function, \function{sum(\var{iterable}, \var{start}=0)},
-adds up the numeric items in the iterable object and returns their sum.
-\function{sum()} only accepts numbers, meaning that you can't use it
-to concatenate a bunch of strings. (Contributed by Alex
-Martelli.)
-
-\item \code{list.insert(\var{pos}, \var{value})} used to
-insert \var{value} at the front of the list when \var{pos} was
-negative. The behaviour has now been changed to be consistent with
-slice indexing, so when \var{pos} is -1 the value will be inserted
-before the last element, and so forth.
-
-\item \code{list.index(\var{value})}, which searches for \var{value}
-within the list and returns its index, now takes optional
-\var{start} and \var{stop} arguments to limit the search to
-only part of the list.
-
-\item Dictionaries have a new method, \method{pop(\var{key}\optional{,
-\var{default}})}, that returns the value corresponding to \var{key}
-and removes that key/value pair from the dictionary. If the requested
-key isn't present in the dictionary, \var{default} is returned if it's
-specified and \exception{KeyError} raised if it isn't.
-
-\begin{verbatim}
->>> d = {1:2}
->>> d
-{1: 2}
->>> d.pop(4)
-Traceback (most recent call last):
- File "stdin", line 1, in ?
-KeyError: 4
->>> d.pop(1)
-2
->>> d.pop(1)
-Traceback (most recent call last):
- File "stdin", line 1, in ?
-KeyError: 'pop(): dictionary is empty'
->>> d
-{}
->>>
-\end{verbatim}
-
-There's also a new class method,
-\method{dict.fromkeys(\var{iterable}, \var{value})}, that
-creates a dictionary with keys taken from the supplied iterator
-\var{iterable} and all values set to \var{value}, defaulting to
-\code{None}.
-
-(Patches contributed by Raymond Hettinger.)
-
-Also, the \function{dict()} constructor now accepts keyword arguments to
-simplify creating small dictionaries:
-
-\begin{verbatim}
->>> dict(red=1, blue=2, green=3, black=4)
-{'blue': 2, 'black': 4, 'green': 3, 'red': 1}
-\end{verbatim}
-
-(Contributed by Just van~Rossum.)
-
-\item The \keyword{assert} statement no longer checks the \code{__debug__}
-flag, so you can no longer disable assertions by assigning to \code{__debug__}.
-Running Python with the \programopt{-O} switch will still generate
-code that doesn't execute any assertions.
-
-\item Most type objects are now callable, so you can use them
-to create new objects such as functions, classes, and modules. (This
-means that the \module{new} module can be deprecated in a future
-Python version, because you can now use the type objects available in
-the \module{types} module.)
-% XXX should new.py use PendingDeprecationWarning?
-For example, you can create a new module object with the following code:
-
-\begin{verbatim}
->>> import types
->>> m = types.ModuleType('abc','docstring')
->>> m
-<module 'abc' (built-in)>
->>> m.__doc__
-'docstring'
-\end{verbatim}
-
-\item
-A new warning, \exception{PendingDeprecationWarning} was added to
-indicate features which are in the process of being
-deprecated. The warning will \emph{not} be printed by default. To
-check for use of features that will be deprecated in the future,
-supply \programopt{-Walways::PendingDeprecationWarning::} on the
-command line or use \function{warnings.filterwarnings()}.
-
-\item The process of deprecating string-based exceptions, as
-in \code{raise "Error occurred"}, has begun. Raising a string will
-now trigger \exception{PendingDeprecationWarning}.
-
-\item Using \code{None} as a variable name will now result in a
-\exception{SyntaxWarning} warning. In a future version of Python,
-\code{None} may finally become a keyword.
-
-\item The \method{xreadlines()} method of file objects, introduced in
-Python 2.1, is no longer necessary because files now behave as their
-own iterator. \method{xreadlines()} was originally introduced as a
-faster way to loop over all the lines in a file, but now you can
-simply write \code{for line in file_obj}. File objects also have a
-new read-only \member{encoding} attribute that gives the encoding used
-by the file; Unicode strings written to the file will be automatically
-converted to bytes using the given encoding.
-
-\item The method resolution order used by new-style classes has
-changed, though you'll only notice the difference if you have a really
-complicated inheritance hierarchy. Classic classes are unaffected by
-this change. Python 2.2 originally used a topological sort of a
-class's ancestors, but 2.3 now uses the C3 algorithm as described in
-the paper \ulink{``A Monotonic Superclass Linearization for
-Dylan''}{http://www.webcom.com/haahr/dylan/linearization-oopsla96.html}.
-To understand the motivation for this change,
-read Michele Simionato's article
-\ulink{``Python 2.3 Method Resolution Order''}
- {http://www.python.org/2.3/mro.html}, or
-read the thread on python-dev starting with the message at
-\url{http://mail.python.org/pipermail/python-dev/2002-October/029035.html}.
-Samuele Pedroni first pointed out the problem and also implemented the
-fix by coding the C3 algorithm.
-
-\item Python runs multithreaded programs by switching between threads
-after executing N bytecodes. The default value for N has been
-increased from 10 to 100 bytecodes, speeding up single-threaded
-applications by reducing the switching overhead. Some multithreaded
-applications may suffer slower response time, but that's easily fixed
-by setting the limit back to a lower number using
-\function{sys.setcheckinterval(\var{N})}.
-The limit can be retrieved with the new
-\function{sys.getcheckinterval()} function.
-
-\item One minor but far-reaching change is that the names of extension
-types defined by the modules included with Python now contain the
-module and a \character{.} in front of the type name. For example, in
-Python 2.2, if you created a socket and printed its
-\member{__class__}, you'd get this output:
-
-\begin{verbatim}
->>> s = socket.socket()
->>> s.__class__
-<type 'socket'>
-\end{verbatim}
-
-In 2.3, you get this:
-\begin{verbatim}
->>> s.__class__
-<type '_socket.socket'>
-\end{verbatim}
-
-\item One of the noted incompatibilities between old- and new-style
- classes has been removed: you can now assign to the
- \member{__name__} and \member{__bases__} attributes of new-style
- classes. There are some restrictions on what can be assigned to
- \member{__bases__} along the lines of those relating to assigning to
- an instance's \member{__class__} attribute.
-
-\end{itemize}
-
-
-%======================================================================
-\subsection{String Changes}
-
-\begin{itemize}
-
-\item The \keyword{in} operator now works differently for strings.
-Previously, when evaluating \code{\var{X} in \var{Y}} where \var{X}
-and \var{Y} are strings, \var{X} could only be a single character.
-That's now changed; \var{X} can be a string of any length, and
-\code{\var{X} in \var{Y}} will return \constant{True} if \var{X} is a
-substring of \var{Y}. If \var{X} is the empty string, the result is
-always \constant{True}.
-
-\begin{verbatim}
->>> 'ab' in 'abcd'
-True
->>> 'ad' in 'abcd'
-False
->>> '' in 'abcd'
-True
-\end{verbatim}
-
-Note that this doesn't tell you where the substring starts; if you
-need that information, use the \method{find()} string method.
-
-\item The \method{strip()}, \method{lstrip()}, and \method{rstrip()}
-string methods now have an optional argument for specifying the
-characters to strip. The default is still to remove all whitespace
-characters:
-
-\begin{verbatim}
->>> ' abc '.strip()
-'abc'
->>> '><><abc<><><>'.strip('<>')
-'abc'
->>> '><><abc<><><>\n'.strip('<>')
-'abc<><><>\n'
->>> u'\u4000\u4001abc\u4000'.strip(u'\u4000')
-u'\u4001abc'
->>>
-\end{verbatim}
-
-(Suggested by Simon Brunning and implemented by Walter D\"orwald.)
-
-\item The \method{startswith()} and \method{endswith()}
-string methods now accept negative numbers for the \var{start} and \var{end}
-parameters.
-
-\item Another new string method is \method{zfill()}, originally a
-function in the \module{string} module. \method{zfill()} pads a
-numeric string with zeros on the left until it's the specified width.
-Note that the \code{\%} operator is still more flexible and powerful
-than \method{zfill()}.
-
-\begin{verbatim}
->>> '45'.zfill(4)
-'0045'
->>> '12345'.zfill(4)
-'12345'
->>> 'goofy'.zfill(6)
-'0goofy'
-\end{verbatim}
-
-(Contributed by Walter D\"orwald.)
-
-\item A new type object, \class{basestring}, has been added.
- Both 8-bit strings and Unicode strings inherit from this type, so
- \code{isinstance(obj, basestring)} will return \constant{True} for
- either kind of string. It's a completely abstract type, so you
- can't create \class{basestring} instances.
-
-\item Interned strings are no longer immortal and will now be
-garbage-collected in the usual way when the only reference to them is
-from the internal dictionary of interned strings. (Implemented by
-Oren Tirosh.)
-
-\end{itemize}
-
-
-%======================================================================
-\subsection{Optimizations}
-
-\begin{itemize}
-
-\item The creation of new-style class instances has been made much
-faster; they're now faster than classic classes!
-
-\item The \method{sort()} method of list objects has been extensively
-rewritten by Tim Peters, and the implementation is significantly
-faster.
-
-\item Multiplication of large long integers is now much faster thanks
-to an implementation of Karatsuba multiplication, an algorithm that
-scales better than the O(n*n) required for the grade-school
-multiplication algorithm. (Original patch by Christopher A. Craig,
-and significantly reworked by Tim Peters.)
-
-\item The \code{SET_LINENO} opcode is now gone. This may provide a
-small speed increase, depending on your compiler's idiosyncrasies.
-See section~\ref{section-other} for a longer explanation.
-(Removed by Michael Hudson.)
-
-\item \function{xrange()} objects now have their own iterator, making
-\code{for i in xrange(n)} slightly faster than
-\code{for i in range(n)}. (Patch by Raymond Hettinger.)
-
-\item A number of small rearrangements have been made in various
-hotspots to improve performance, such as inlining a function or removing
-some code. (Implemented mostly by GvR, but lots of people have
-contributed single changes.)
-
-\end{itemize}
-
-The net result of the 2.3 optimizations is that Python 2.3 runs the
-pystone benchmark around 25\% faster than Python 2.2.
-
-
-%======================================================================
-\section{New, Improved, and Deprecated Modules}
-
-As usual, Python's standard library received a number of enhancements and
-bug fixes. Here's a partial list of the most notable changes, sorted
-alphabetically by module name. Consult the
-\file{Misc/NEWS} file in the source tree for a more
-complete list of changes, or look through the CVS logs for all the
-details.
-
-\begin{itemize}
-
-\item The \module{array} module now supports arrays of Unicode
-characters using the \character{u} format character. Arrays also now
-support using the \code{+=} assignment operator to add another array's
-contents, and the \code{*=} assignment operator to repeat an array.
-(Contributed by Jason Orendorff.)
-
-\item The \module{bsddb} module has been replaced by version 4.1.6
-of the \ulink{PyBSDDB}{http://pybsddb.sourceforge.net} package,
-providing a more complete interface to the transactional features of
-the BerkeleyDB library.
-
-The old version of the module has been renamed to
-\module{bsddb185} and is no longer built automatically; you'll
-have to edit \file{Modules/Setup} to enable it. Note that the new
-\module{bsddb} package is intended to be compatible with the
-old module, so be sure to file bugs if you discover any
-incompatibilities. When upgrading to Python 2.3, if the new interpreter is compiled
-with a new version of
-the underlying BerkeleyDB library, you will almost certainly have to
-convert your database files to the new version. You can do this
-fairly easily with the new scripts \file{db2pickle.py} and
-\file{pickle2db.py} which you will find in the distribution's
-\file{Tools/scripts} directory. If you've already been using the PyBSDDB
-package and importing it as \module{bsddb3}, you will have to change your
-\code{import} statements to import it as \module{bsddb}.
-
-\item The new \module{bz2} module is an interface to the bz2 data
-compression library. bz2-compressed data is usually smaller than
-corresponding \module{zlib}-compressed data. (Contributed by Gustavo Niemeyer.)
-
-\item A set of standard date/time types has been added in the new \module{datetime}
-module. See the following section for more details.
-
-\item The Distutils \class{Extension} class now supports
-an extra constructor argument named \var{depends} for listing
-additional source files that an extension depends on. This lets
-Distutils recompile the module if any of the dependency files are
-modified. For example, if \file{sampmodule.c} includes the header
-file \file{sample.h}, you would create the \class{Extension} object like
-this:
-
-\begin{verbatim}
-ext = Extension("samp",
- sources=["sampmodule.c"],
- depends=["sample.h"])
-\end{verbatim}
-
-Modifying \file{sample.h} would then cause the module to be recompiled.
-(Contributed by Jeremy Hylton.)
-
-\item Other minor changes to Distutils:
-it now checks for the \envvar{CC}, \envvar{CFLAGS}, \envvar{CPP},
-\envvar{LDFLAGS}, and \envvar{CPPFLAGS} environment variables, using
-them to override the settings in Python's configuration (contributed
-by Robert Weber).
-
-\item Previously the \module{doctest} module would only search the
-docstrings of public methods and functions for test cases, but it now
-also examines private ones as well. The \function{DocTestSuite(}
-function creates a \class{unittest.TestSuite} object from a set of
-\module{doctest} tests.
-
-\item The new \function{gc.get_referents(\var{object})} function returns a
-list of all the objects referenced by \var{object}.
-
-\item The \module{getopt} module gained a new function,
-\function{gnu_getopt()}, that supports the same arguments as the existing
-\function{getopt()} function but uses GNU-style scanning mode.
-The existing \function{getopt()} stops processing options as soon as a
-non-option argument is encountered, but in GNU-style mode processing
-continues, meaning that options and arguments can be mixed. For
-example:
-
-\begin{verbatim}
->>> getopt.getopt(['-f', 'filename', 'output', '-v'], 'f:v')
-([('-f', 'filename')], ['output', '-v'])
->>> getopt.gnu_getopt(['-f', 'filename', 'output', '-v'], 'f:v')
-([('-f', 'filename'), ('-v', '')], ['output'])
-\end{verbatim}
-
-(Contributed by Peter \AA{strand}.)
-
-\item The \module{grp}, \module{pwd}, and \module{resource} modules
-now return enhanced tuples:
-
-\begin{verbatim}
->>> import grp
->>> g = grp.getgrnam('amk')
->>> g.gr_name, g.gr_gid
-('amk', 500)
-\end{verbatim}
-
-\item The \module{gzip} module can now handle files exceeding 2~GiB.
-
-\item The new \module{heapq} module contains an implementation of a
-heap queue algorithm. A heap is an array-like data structure that
-keeps items in a partially sorted order such that, for every index
-\var{k}, \code{heap[\var{k}] <= heap[2*\var{k}+1]} and
-\code{heap[\var{k}] <= heap[2*\var{k}+2]}. This makes it quick to
-remove the smallest item, and inserting a new item while maintaining
-the heap property is O(lg~n). (See
-\url{http://www.nist.gov/dads/HTML/priorityque.html} for more
-information about the priority queue data structure.)
-
-The \module{heapq} module provides \function{heappush()} and
-\function{heappop()} functions for adding and removing items while
-maintaining the heap property on top of some other mutable Python
-sequence type. Here's an example that uses a Python list:
-
-\begin{verbatim}
->>> import heapq
->>> heap = []
->>> for item in [3, 7, 5, 11, 1]:
-... heapq.heappush(heap, item)
-...
->>> heap
-[1, 3, 5, 11, 7]
->>> heapq.heappop(heap)
-1
->>> heapq.heappop(heap)
-3
->>> heap
-[5, 7, 11]
-\end{verbatim}
-
-(Contributed by Kevin O'Connor.)
-
-\item The IDLE integrated development environment has been updated
-using the code from the IDLEfork project
-(\url{http://idlefork.sf.net}). The most notable feature is that the
-code being developed is now executed in a subprocess, meaning that
-there's no longer any need for manual \code{reload()} operations.
-IDLE's core code has been incorporated into the standard library as the
-\module{idlelib} package.
-
-\item The \module{imaplib} module now supports IMAP over SSL.
-(Contributed by Piers Lauder and Tino Lange.)
-
-\item The \module{itertools} contains a number of useful functions for
-use with iterators, inspired by various functions provided by the ML
-and Haskell languages. For example,
-\code{itertools.ifilter(predicate, iterator)} returns all elements in
-the iterator for which the function \function{predicate()} returns
-\constant{True}, and \code{itertools.repeat(obj, \var{N})} returns
-\code{obj} \var{N} times. There are a number of other functions in
-the module; see the \ulink{package's reference
-documentation}{../lib/module-itertools.html} for details.
-(Contributed by Raymond Hettinger.)
-
-\item Two new functions in the \module{math} module,
-\function{degrees(\var{rads})} and \function{radians(\var{degs})},
-convert between radians and degrees. Other functions in the
-\module{math} module such as \function{math.sin()} and
-\function{math.cos()} have always required input values measured in
-radians. Also, an optional \var{base} argument was added to
-\function{math.log()} to make it easier to compute logarithms for
-bases other than \code{e} and \code{10}. (Contributed by Raymond
-Hettinger.)
-
-\item Several new POSIX functions (\function{getpgid()}, \function{killpg()},
-\function{lchown()}, \function{loadavg()}, \function{major()}, \function{makedev()},
-\function{minor()}, and \function{mknod()}) were added to the
-\module{posix} module that underlies the \module{os} module.
-(Contributed by Gustavo Niemeyer, Geert Jansen, and Denis S. Otkidach.)
-
-\item In the \module{os} module, the \function{*stat()} family of
-functions can now report fractions of a second in a timestamp. Such
-time stamps are represented as floats, similar to
-the value returned by \function{time.time()}.
-
-During testing, it was found that some applications will break if time
-stamps are floats. For compatibility, when using the tuple interface
-of the \class{stat_result} time stamps will be represented as integers.
-When using named fields (a feature first introduced in Python 2.2),
-time stamps are still represented as integers, unless
-\function{os.stat_float_times()} is invoked to enable float return
-values:
-
-\begin{verbatim}
->>> os.stat("/tmp").st_mtime
-1034791200
->>> os.stat_float_times(True)
->>> os.stat("/tmp").st_mtime
-1034791200.6335014
-\end{verbatim}
-
-In Python 2.4, the default will change to always returning floats.
-
-Application developers should enable this feature only if all their
-libraries work properly when confronted with floating point time
-stamps, or if they use the tuple API. If used, the feature should be
-activated on an application level instead of trying to enable it on a
-per-use basis.
-
-\item The \module{optparse} module contains a new parser for command-line arguments
-that can convert option values to a particular Python type
-and will automatically generate a usage message. See the following section for
-more details.
-
-\item The old and never-documented \module{linuxaudiodev} module has
-been deprecated, and a new version named \module{ossaudiodev} has been
-added. The module was renamed because the OSS sound drivers can be
-used on platforms other than Linux, and the interface has also been
-tidied and brought up to date in various ways. (Contributed by Greg
-Ward and Nicholas FitzRoy-Dale.)
-
-\item The new \module{platform} module contains a number of functions
-that try to determine various properties of the platform you're
-running on. There are functions for getting the architecture, CPU
-type, the Windows OS version, and even the Linux distribution version.
-(Contributed by Marc-Andr\'e Lemburg.)
-
-\item The parser objects provided by the \module{pyexpat} module
-can now optionally buffer character data, resulting in fewer calls to
-your character data handler and therefore faster performance. Setting
-the parser object's \member{buffer_text} attribute to \constant{True}
-will enable buffering.
-
-\item The \function{sample(\var{population}, \var{k})} function was
-added to the \module{random} module. \var{population} is a sequence or
-\class{xrange} object containing the elements of a population, and
-\function{sample()} chooses \var{k} elements from the population without
-replacing chosen elements. \var{k} can be any value up to
-\code{len(\var{population})}. For example:
-
-\begin{verbatim}
->>> days = ['Mo', 'Tu', 'We', 'Th', 'Fr', 'St', 'Sn']
->>> random.sample(days, 3) # Choose 3 elements
-['St', 'Sn', 'Th']
->>> random.sample(days, 7) # Choose 7 elements
-['Tu', 'Th', 'Mo', 'We', 'St', 'Fr', 'Sn']
->>> random.sample(days, 7) # Choose 7 again
-['We', 'Mo', 'Sn', 'Fr', 'Tu', 'St', 'Th']
->>> random.sample(days, 8) # Can't choose eight
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
- File "random.py", line 414, in sample
- raise ValueError, "sample larger than population"
-ValueError: sample larger than population
->>> random.sample(xrange(1,10000,2), 10) # Choose ten odd nos. under 10000
-[3407, 3805, 1505, 7023, 2401, 2267, 9733, 3151, 8083, 9195]
-\end{verbatim}
-
-The \module{random} module now uses a new algorithm, the Mersenne
-Twister, implemented in C. It's faster and more extensively studied
-than the previous algorithm.
-
-(All changes contributed by Raymond Hettinger.)
-
-\item The \module{readline} module also gained a number of new
-functions: \function{get_history_item()},
-\function{get_current_history_length()}, and \function{redisplay()}.
-
-\item The \module{rexec} and \module{Bastion} modules have been
-declared dead, and attempts to import them will fail with a
-\exception{RuntimeError}. New-style classes provide new ways to break
-out of the restricted execution environment provided by
-\module{rexec}, and no one has interest in fixing them or time to do
-so. If you have applications using \module{rexec}, rewrite them to
-use something else.
-
-(Sticking with Python 2.2 or 2.1 will not make your applications any
-safer because there are known bugs in the \module{rexec} module in
-those versions. To repeat: if you're using \module{rexec}, stop using
-it immediately.)
-
-\item The \module{rotor} module has been deprecated because the
- algorithm it uses for encryption is not believed to be secure. If
- you need encryption, use one of the several AES Python modules
- that are available separately.
-
-\item The \module{shutil} module gained a \function{move(\var{src},
-\var{dest})} function that recursively moves a file or directory to a new
-location.
-
-\item Support for more advanced POSIX signal handling was added
-to the \module{signal} but then removed again as it proved impossible
-to make it work reliably across platforms.
-
-\item The \module{socket} module now supports timeouts. You
-can call the \method{settimeout(\var{t})} method on a socket object to
-set a timeout of \var{t} seconds. Subsequent socket operations that
-take longer than \var{t} seconds to complete will abort and raise a
-\exception{socket.timeout} exception.
-
-The original timeout implementation was by Tim O'Malley. Michael
-Gilfix integrated it into the Python \module{socket} module and
-shepherded it through a lengthy review. After the code was checked
-in, Guido van~Rossum rewrote parts of it. (This is a good example of
-a collaborative development process in action.)
-
-\item On Windows, the \module{socket} module now ships with Secure
-Sockets Layer (SSL) support.
-
-\item The value of the C \constant{PYTHON_API_VERSION} macro is now
-exposed at the Python level as \code{sys.api_version}. The current
-exception can be cleared by calling the new \function{sys.exc_clear()}
-function.
-
-\item The new \module{tarfile} module
-allows reading from and writing to \program{tar}-format archive files.
-(Contributed by Lars Gust\"abel.)
-
-\item The new \module{textwrap} module contains functions for wrapping
-strings containing paragraphs of text. The \function{wrap(\var{text},
-\var{width})} function takes a string and returns a list containing
-the text split into lines of no more than the chosen width. The
-\function{fill(\var{text}, \var{width})} function returns a single
-string, reformatted to fit into lines no longer than the chosen width.
-(As you can guess, \function{fill()} is built on top of
-\function{wrap()}. For example:
-
-\begin{verbatim}
->>> import textwrap
->>> paragraph = "Not a whit, we defy augury: ... more text ..."
->>> textwrap.wrap(paragraph, 60)
-["Not a whit, we defy augury: there's a special providence in",
- "the fall of a sparrow. If it be now, 'tis not to come; if it",
- ...]
->>> print textwrap.fill(paragraph, 35)
-Not a whit, we defy augury: there's
-a special providence in the fall of
-a sparrow. If it be now, 'tis not
-to come; if it be not to come, it
-will be now; if it be not now, yet
-it will come: the readiness is all.
->>>
-\end{verbatim}
-
-The module also contains a \class{TextWrapper} class that actually
-implements the text wrapping strategy. Both the
-\class{TextWrapper} class and the \function{wrap()} and
-\function{fill()} functions support a number of additional keyword
-arguments for fine-tuning the formatting; consult the \ulink{module's
-documentation}{../lib/module-textwrap.html} for details.
-(Contributed by Greg Ward.)
-
-\item The \module{thread} and \module{threading} modules now have
-companion modules, \module{dummy_thread} and \module{dummy_threading},
-that provide a do-nothing implementation of the \module{thread}
-module's interface for platforms where threads are not supported. The
-intention is to simplify thread-aware modules (ones that \emph{don't}
-rely on threads to run) by putting the following code at the top:
-
-\begin{verbatim}
-try:
- import threading as _threading
-except ImportError:
- import dummy_threading as _threading
-\end{verbatim}
-
-In this example, \module{_threading} is used as the module name to make
-it clear that the module being used is not necessarily the actual
-\module{threading} module. Code can call functions and use classes in
-\module{_threading} whether or not threads are supported, avoiding an
-\keyword{if} statement and making the code slightly clearer. This
-module will not magically make multithreaded code run without threads;
-code that waits for another thread to return or to do something will
-simply hang forever.
-
-\item The \module{time} module's \function{strptime()} function has
-long been an annoyance because it uses the platform C library's
-\function{strptime()} implementation, and different platforms
-sometimes have odd bugs. Brett Cannon contributed a portable
-implementation that's written in pure Python and should behave
-identically on all platforms.
-
-\item The new \module{timeit} module helps measure how long snippets
-of Python code take to execute. The \file{timeit.py} file can be run
-directly from the command line, or the module's \class{Timer} class
-can be imported and used directly. Here's a short example that
-figures out whether it's faster to convert an 8-bit string to Unicode
-by appending an empty Unicode string to it or by using the
-\function{unicode()} function:
-
-\begin{verbatim}
-import timeit
-
-timer1 = timeit.Timer('unicode("abc")')
-timer2 = timeit.Timer('"abc" + u""')
-
-# Run three trials
-print timer1.repeat(repeat=3, number=100000)
-print timer2.repeat(repeat=3, number=100000)
-
-# On my laptop this outputs:
-# [0.36831796169281006, 0.37441694736480713, 0.35304892063140869]
-# [0.17574405670166016, 0.18193507194519043, 0.17565798759460449]
-\end{verbatim}
-
-\item The \module{Tix} module has received various bug fixes and
-updates for the current version of the Tix package.
-
-\item The \module{Tkinter} module now works with a thread-enabled
-version of Tcl. Tcl's threading model requires that widgets only be
-accessed from the thread in which they're created; accesses from
-another thread can cause Tcl to panic. For certain Tcl interfaces,
-\module{Tkinter} will now automatically avoid this
-when a widget is accessed from a different thread by marshalling a
-command, passing it to the correct thread, and waiting for the
-results. Other interfaces can't be handled automatically but
-\module{Tkinter} will now raise an exception on such an access so that
-you can at least find out about the problem. See
-\url{http://mail.python.org/pipermail/python-dev/2002-December/031107.html} %
-for a more detailed explanation of this change. (Implemented by
-Martin von~L\"owis.)
-
-\item Calling Tcl methods through \module{_tkinter} no longer
-returns only strings. Instead, if Tcl returns other objects those
-objects are converted to their Python equivalent, if one exists, or
-wrapped with a \class{_tkinter.Tcl_Obj} object if no Python equivalent
-exists. This behavior can be controlled through the
-\method{wantobjects()} method of \class{tkapp} objects.
-
-When using \module{_tkinter} through the \module{Tkinter} module (as
-most Tkinter applications will), this feature is always activated. It
-should not cause compatibility problems, since Tkinter would always
-convert string results to Python types where possible.
-
-If any incompatibilities are found, the old behavior can be restored
-by setting the \member{wantobjects} variable in the \module{Tkinter}
-module to false before creating the first \class{tkapp} object.
-
-\begin{verbatim}
-import Tkinter
-Tkinter.wantobjects = 0
-\end{verbatim}
-
-Any breakage caused by this change should be reported as a bug.
-
-\item The \module{UserDict} module has a new \class{DictMixin} class which
-defines all dictionary methods for classes that already have a minimum
-mapping interface. This greatly simplifies writing classes that need
-to be substitutable for dictionaries, such as the classes in
-the \module{shelve} module.
-
-Adding the mix-in as a superclass provides the full dictionary
-interface whenever the class defines \method{__getitem__},
-\method{__setitem__}, \method{__delitem__}, and \method{keys}.
-For example:
-
-\begin{verbatim}
->>> import UserDict
->>> class SeqDict(UserDict.DictMixin):
-... """Dictionary lookalike implemented with lists."""
-... def __init__(self):
-... self.keylist = []
-... self.valuelist = []
-... def __getitem__(self, key):
-... try:
-... i = self.keylist.index(key)
-... except ValueError:
-... raise KeyError
-... return self.valuelist[i]
-... def __setitem__(self, key, value):
-... try:
-... i = self.keylist.index(key)
-... self.valuelist[i] = value
-... except ValueError:
-... self.keylist.append(key)
-... self.valuelist.append(value)
-... def __delitem__(self, key):
-... try:
-... i = self.keylist.index(key)
-... except ValueError:
-... raise KeyError
-... self.keylist.pop(i)
-... self.valuelist.pop(i)
-... def keys(self):
-... return list(self.keylist)
-...
->>> s = SeqDict()
->>> dir(s) # See that other dictionary methods are implemented
-['__cmp__', '__contains__', '__delitem__', '__doc__', '__getitem__',
- '__init__', '__iter__', '__len__', '__module__', '__repr__',
- '__setitem__', 'clear', 'get', 'has_key', 'items', 'iteritems',
- 'iterkeys', 'itervalues', 'keylist', 'keys', 'pop', 'popitem',
- 'setdefault', 'update', 'valuelist', 'values']
-\end{verbatim}
-
-(Contributed by Raymond Hettinger.)
-
-\item The DOM implementation
-in \module{xml.dom.minidom} can now generate XML output in a
-particular encoding by providing an optional encoding argument to
-the \method{toxml()} and \method{toprettyxml()} methods of DOM nodes.
-
-\item The \module{xmlrpclib} module now supports an XML-RPC extension
-for handling nil data values such as Python's \code{None}. Nil values
-are always supported on unmarshalling an XML-RPC response. To
-generate requests containing \code{None}, you must supply a true value
-for the \var{allow_none} parameter when creating a \class{Marshaller}
-instance.
-
-\item The new \module{DocXMLRPCServer} module allows writing
-self-documenting XML-RPC servers. Run it in demo mode (as a program)
-to see it in action. Pointing the Web browser to the RPC server
-produces pydoc-style documentation; pointing xmlrpclib to the
-server allows invoking the actual methods.
-(Contributed by Brian Quinlan.)
-
-\item Support for internationalized domain names (RFCs 3454, 3490,
-3491, and 3492) has been added. The ``idna'' encoding can be used
-to convert between a Unicode domain name and the ASCII-compatible
-encoding (ACE) of that name.
-
-\begin{alltt}
->{}>{}> u"www.Alliancefran\c caise.nu".encode("idna")
-'www.xn--alliancefranaise-npb.nu'
-\end{alltt}
-
-The \module{socket} module has also been extended to transparently
-convert Unicode hostnames to the ACE version before passing them to
-the C library. Modules that deal with hostnames such as
-\module{httplib} and \module{ftplib}) also support Unicode host names;
-\module{httplib} also sends HTTP \samp{Host} headers using the ACE
-version of the domain name. \module{urllib} supports Unicode URLs
-with non-ASCII host names as long as the \code{path} part of the URL
-is ASCII only.
-
-To implement this change, the \module{stringprep} module, the
-\code{mkstringprep} tool and the \code{punycode} encoding have been added.
-
-\end{itemize}
-
-
-%======================================================================
-\subsection{Date/Time Type}
-
-Date and time types suitable for expressing timestamps were added as
-the \module{datetime} module. The types don't support different
-calendars or many fancy features, and just stick to the basics of
-representing time.
-
-The three primary types are: \class{date}, representing a day, month,
-and year; \class{time}, consisting of hour, minute, and second; and
-\class{datetime}, which contains all the attributes of both
-\class{date} and \class{time}. There's also a
-\class{timedelta} class representing differences between two points
-in time, and time zone logic is implemented by classes inheriting from
-the abstract \class{tzinfo} class.
-
-You can create instances of \class{date} and \class{time} by either
-supplying keyword arguments to the appropriate constructor,
-e.g. \code{datetime.date(year=1972, month=10, day=15)}, or by using
-one of a number of class methods. For example, the \method{date.today()}
-class method returns the current local date.
-
-Once created, instances of the date/time classes are all immutable.
-There are a number of methods for producing formatted strings from
-objects:
-
-\begin{verbatim}
->>> import datetime
->>> now = datetime.datetime.now()
->>> now.isoformat()
-'2002-12-30T21:27:03.994956'
->>> now.ctime() # Only available on date, datetime
-'Mon Dec 30 21:27:03 2002'
->>> now.strftime('%Y %d %b')
-'2002 30 Dec'
-\end{verbatim}
-
-The \method{replace()} method allows modifying one or more fields
-of a \class{date} or \class{datetime} instance, returning a new instance:
-
-\begin{verbatim}
->>> d = datetime.datetime.now()
->>> d
-datetime.datetime(2002, 12, 30, 22, 15, 38, 827738)
->>> d.replace(year=2001, hour = 12)
-datetime.datetime(2001, 12, 30, 12, 15, 38, 827738)
->>>
-\end{verbatim}
-
-Instances can be compared, hashed, and converted to strings (the
-result is the same as that of \method{isoformat()}). \class{date} and
-\class{datetime} instances can be subtracted from each other, and
-added to \class{timedelta} instances. The largest missing feature is
-that there's no standard library support for parsing strings and getting back a
-\class{date} or \class{datetime}.
-
-For more information, refer to the \ulink{module's reference
-documentation}{../lib/module-datetime.html}.
-(Contributed by Tim Peters.)
-
-
-%======================================================================
-\subsection{The optparse Module}
-
-The \module{getopt} module provides simple parsing of command-line
-arguments. The new \module{optparse} module (originally named Optik)
-provides more elaborate command-line parsing that follows the \UNIX{}
-conventions, automatically creates the output for \longprogramopt{help},
-and can perform different actions for different options.
-
-You start by creating an instance of \class{OptionParser} and telling
-it what your program's options are.
-
-\begin{verbatim}
-import sys
-from optparse import OptionParser
-
-op = OptionParser()
-op.add_option('-i', '--input',
- action='store', type='string', dest='input',
- help='set input filename')
-op.add_option('-l', '--length',
- action='store', type='int', dest='length',
- help='set maximum length of output')
-\end{verbatim}
-
-Parsing a command line is then done by calling the \method{parse_args()}
-method.
-
-\begin{verbatim}
-options, args = op.parse_args(sys.argv[1:])
-print options
-print args
-\end{verbatim}
-
-This returns an object containing all of the option values,
-and a list of strings containing the remaining arguments.
-
-Invoking the script with the various arguments now works as you'd
-expect it to. Note that the length argument is automatically
-converted to an integer.
-
-\begin{verbatim}
-$ ./python opt.py -i data arg1
-<Values at 0x400cad4c: {'input': 'data', 'length': None}>
-['arg1']
-$ ./python opt.py --input=data --length=4
-<Values at 0x400cad2c: {'input': 'data', 'length': 4}>
-[]
-$
-\end{verbatim}
-
-The help message is automatically generated for you:
-
-\begin{verbatim}
-$ ./python opt.py --help
-usage: opt.py [options]
-
-options:
- -h, --help show this help message and exit
- -iINPUT, --input=INPUT
- set input filename
- -lLENGTH, --length=LENGTH
- set maximum length of output
-$
-\end{verbatim}
-% $ prevent Emacs tex-mode from getting confused
-
-See the \ulink{module's documentation}{../lib/module-optparse.html}
-for more details.
-
-Optik was written by Greg Ward, with suggestions from the readers of
-the Getopt SIG.
-
-
-%======================================================================
-\section{Pymalloc: A Specialized Object Allocator\label{section-pymalloc}}
-
-Pymalloc, a specialized object allocator written by Vladimir
-Marangozov, was a feature added to Python 2.1. Pymalloc is intended
-to be faster than the system \cfunction{malloc()} and to have less
-memory overhead for allocation patterns typical of Python programs.
-The allocator uses C's \cfunction{malloc()} function to get large
-pools of memory and then fulfills smaller memory requests from these
-pools.
-
-In 2.1 and 2.2, pymalloc was an experimental feature and wasn't
-enabled by default; you had to explicitly enable it when compiling
-Python by providing the
-\longprogramopt{with-pymalloc} option to the \program{configure}
-script. In 2.3, pymalloc has had further enhancements and is now
-enabled by default; you'll have to supply
-\longprogramopt{without-pymalloc} to disable it.
-
-This change is transparent to code written in Python; however,
-pymalloc may expose bugs in C extensions. Authors of C extension
-modules should test their code with pymalloc enabled,
-because some incorrect code may cause core dumps at runtime.
-
-There's one particularly common error that causes problems. There are
-a number of memory allocation functions in Python's C API that have
-previously just been aliases for the C library's \cfunction{malloc()}
-and \cfunction{free()}, meaning that if you accidentally called
-mismatched functions the error wouldn't be noticeable. When the
-object allocator is enabled, these functions aren't aliases of
-\cfunction{malloc()} and \cfunction{free()} any more, and calling the
-wrong function to free memory may get you a core dump. For example,
-if memory was allocated using \cfunction{PyObject_Malloc()}, it has to
-be freed using \cfunction{PyObject_Free()}, not \cfunction{free()}. A
-few modules included with Python fell afoul of this and had to be
-fixed; doubtless there are more third-party modules that will have the
-same problem.
-
-As part of this change, the confusing multiple interfaces for
-allocating memory have been consolidated down into two API families.
-Memory allocated with one family must not be manipulated with
-functions from the other family. There is one family for allocating
-chunks of memory and another family of functions specifically for
-allocating Python objects.
-
-\begin{itemize}
- \item To allocate and free an undistinguished chunk of memory use
- the ``raw memory'' family: \cfunction{PyMem_Malloc()},
- \cfunction{PyMem_Realloc()}, and \cfunction{PyMem_Free()}.
-
- \item The ``object memory'' family is the interface to the pymalloc
- facility described above and is biased towards a large number of
- ``small'' allocations: \cfunction{PyObject_Malloc},
- \cfunction{PyObject_Realloc}, and \cfunction{PyObject_Free}.
-
- \item To allocate and free Python objects, use the ``object'' family
- \cfunction{PyObject_New()}, \cfunction{PyObject_NewVar()}, and
- \cfunction{PyObject_Del()}.
-\end{itemize}
-
-Thanks to lots of work by Tim Peters, pymalloc in 2.3 also provides
-debugging features to catch memory overwrites and doubled frees in
-both extension modules and in the interpreter itself. To enable this
-support, compile a debugging version of the Python interpreter by
-running \program{configure} with \longprogramopt{with-pydebug}.
-
-To aid extension writers, a header file \file{Misc/pymemcompat.h} is
-distributed with the source to Python 2.3 that allows Python
-extensions to use the 2.3 interfaces to memory allocation while
-compiling against any version of Python since 1.5.2. You would copy
-the file from Python's source distribution and bundle it with the
-source of your extension.
-
-\begin{seealso}
-
-\seeurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/python/python/dist/src/Objects/obmalloc.c}
-{For the full details of the pymalloc implementation, see
-the comments at the top of the file \file{Objects/obmalloc.c} in the
-Python source code. The above link points to the file within the
-SourceForge CVS browser.}
-
-\end{seealso}
-
-
-% ======================================================================
-\section{Build and C API Changes}
-
-Changes to Python's build process and to the C API include:
-
-\begin{itemize}
-
-\item The cycle detection implementation used by the garbage collection
-has proven to be stable, so it's now been made mandatory. You can no
-longer compile Python without it, and the
-\longprogramopt{with-cycle-gc} switch to \program{configure} has been removed.
-
-\item Python can now optionally be built as a shared library
-(\file{libpython2.3.so}) by supplying \longprogramopt{enable-shared}
-when running Python's \program{configure} script. (Contributed by Ondrej
-Palkovsky.)
-
-\item The \csimplemacro{DL_EXPORT} and \csimplemacro{DL_IMPORT} macros
-are now deprecated. Initialization functions for Python extension
-modules should now be declared using the new macro
-\csimplemacro{PyMODINIT_FUNC}, while the Python core will generally
-use the \csimplemacro{PyAPI_FUNC} and \csimplemacro{PyAPI_DATA}
-macros.
-
-\item The interpreter can be compiled without any docstrings for
-the built-in functions and modules by supplying
-\longprogramopt{without-doc-strings} to the \program{configure} script.
-This makes the Python executable about 10\% smaller, but will also
-mean that you can't get help for Python's built-ins. (Contributed by
-Gustavo Niemeyer.)
-
-\item The \cfunction{PyArg_NoArgs()} macro is now deprecated, and code
-that uses it should be changed. For Python 2.2 and later, the method
-definition table can specify the
-\constant{METH_NOARGS} flag, signalling that there are no arguments, and
-the argument checking can then be removed. If compatibility with
-pre-2.2 versions of Python is important, the code could use
-\code{PyArg_ParseTuple(\var{args}, "")} instead, but this will be slower
-than using \constant{METH_NOARGS}.
-
-\item \cfunction{PyArg_ParseTuple()} accepts new format characters for various sizes of unsigned integers: \samp{B} for \ctype{unsigned char},
-\samp{H} for \ctype{unsigned short int},
-\samp{I} for \ctype{unsigned int},
-and \samp{K} for \ctype{unsigned long long}.
-
-\item A new function, \cfunction{PyObject_DelItemString(\var{mapping},
-char *\var{key})} was added as shorthand for
-\code{PyObject_DelItem(\var{mapping}, PyString_New(\var{key}))}.
-
-\item File objects now manage their internal string buffer
-differently, increasing it exponentially when needed. This results in
-the benchmark tests in \file{Lib/test/test_bufio.py} speeding up
-considerably (from 57 seconds to 1.7 seconds, according to one
-measurement).
-
-\item It's now possible to define class and static methods for a C
-extension type by setting either the \constant{METH_CLASS} or
-\constant{METH_STATIC} flags in a method's \ctype{PyMethodDef}
-structure.
-
-\item Python now includes a copy of the Expat XML parser's source code,
-removing any dependence on a system version or local installation of
-Expat.
-
-\item If you dynamically allocate type objects in your extension, you
-should be aware of a change in the rules relating to the
-\member{__module__} and \member{__name__} attributes. In summary,
-you will want to ensure the type's dictionary contains a
-\code{'__module__'} key; making the module name the part of the type
-name leading up to the final period will no longer have the desired
-effect. For more detail, read the API reference documentation or the
-source.
-
-\end{itemize}
-
-
-%======================================================================
-\subsection{Port-Specific Changes}
-
-Support for a port to IBM's OS/2 using the EMX runtime environment was
-merged into the main Python source tree. EMX is a POSIX emulation
-layer over the OS/2 system APIs. The Python port for EMX tries to
-support all the POSIX-like capability exposed by the EMX runtime, and
-mostly succeeds; \function{fork()} and \function{fcntl()} are
-restricted by the limitations of the underlying emulation layer. The
-standard OS/2 port, which uses IBM's Visual Age compiler, also gained
-support for case-sensitive import semantics as part of the integration
-of the EMX port into CVS. (Contributed by Andrew MacIntyre.)
-
-On MacOS, most toolbox modules have been weaklinked to improve
-backward compatibility. This means that modules will no longer fail
-to load if a single routine is missing on the current OS version.
-Instead calling the missing routine will raise an exception.
-(Contributed by Jack Jansen.)
-
-The RPM spec files, found in the \file{Misc/RPM/} directory in the
-Python source distribution, were updated for 2.3. (Contributed by
-Sean Reifschneider.)
-
-Other new platforms now supported by Python include AtheOS
-(\url{http://www.atheos.cx/}), GNU/Hurd, and OpenVMS.
-
-
-%======================================================================
-\section{Other Changes and Fixes \label{section-other}}
-
-As usual, there were a bunch of other improvements and bugfixes
-scattered throughout the source tree. A search through the CVS change
-logs finds there were 523 patches applied and 514 bugs fixed between
-Python 2.2 and 2.3. Both figures are likely to be underestimates.
-
-Some of the more notable changes are:
-
-\begin{itemize}
-
-\item If the \envvar{PYTHONINSPECT} environment variable is set, the
-Python interpreter will enter the interactive prompt after running a
-Python program, as if Python had been invoked with the \programopt{-i}
-option. The environment variable can be set before running the Python
-interpreter, or it can be set by the Python program as part of its
-execution.
-
-\item The \file{regrtest.py} script now provides a way to allow ``all
-resources except \var{foo}.'' A resource name passed to the
-\programopt{-u} option can now be prefixed with a hyphen
-(\character{-}) to mean ``remove this resource.'' For example, the
-option `\code{\programopt{-u}all,-bsddb}' could be used to enable the
-use of all resources except \code{bsddb}.
-
-\item The tools used to build the documentation now work under Cygwin
-as well as \UNIX.
-
-\item The \code{SET_LINENO} opcode has been removed. Back in the
-mists of time, this opcode was needed to produce line numbers in
-tracebacks and support trace functions (for, e.g., \module{pdb}).
-Since Python 1.5, the line numbers in tracebacks have been computed
-using a different mechanism that works with ``python -O''. For Python
-2.3 Michael Hudson implemented a similar scheme to determine when to
-call the trace function, removing the need for \code{SET_LINENO}
-entirely.
-
-It would be difficult to detect any resulting difference from Python
-code, apart from a slight speed up when Python is run without
-\programopt{-O}.
-
-C extensions that access the \member{f_lineno} field of frame objects
-should instead call \code{PyCode_Addr2Line(f->f_code, f->f_lasti)}.
-This will have the added effect of making the code work as desired
-under ``python -O'' in earlier versions of Python.
-
-A nifty new feature is that trace functions can now assign to the
-\member{f_lineno} attribute of frame objects, changing the line that
-will be executed next. A \samp{jump} command has been added to the
-\module{pdb} debugger taking advantage of this new feature.
-(Implemented by Richie Hindle.)
-
-\end{itemize}
-
-
-%======================================================================
-\section{Porting to Python 2.3}
-
-This section lists previously described changes that may require
-changes to your code:
-
-\begin{itemize}
-
-\item \keyword{yield} is now always a keyword; if it's used as a
-variable name in your code, a different name must be chosen.
-
-\item For strings \var{X} and \var{Y}, \code{\var{X} in \var{Y}} now works
-if \var{X} is more than one character long.
-
-\item The \function{int()} type constructor will now return a long
-integer instead of raising an \exception{OverflowError} when a string
-or floating-point number is too large to fit into an integer.
-
-\item If you have Unicode strings that contain 8-bit characters, you
-must declare the file's encoding (UTF-8, Latin-1, or whatever) by
-adding a comment to the top of the file. See
-section~\ref{section-encodings} for more information.
-
-\item Calling Tcl methods through \module{_tkinter} no longer
-returns only strings. Instead, if Tcl returns other objects those
-objects are converted to their Python equivalent, if one exists, or
-wrapped with a \class{_tkinter.Tcl_Obj} object if no Python equivalent
-exists.
-
-\item Large octal and hex literals such as
-\code{0xffffffff} now trigger a \exception{FutureWarning}. Currently
-they're stored as 32-bit numbers and result in a negative value, but
-in Python 2.4 they'll become positive long integers.
-
-% The empty groups below prevent conversion to guillemets.
-There are a few ways to fix this warning. If you really need a
-positive number, just add an \samp{L} to the end of the literal. If
-you're trying to get a 32-bit integer with low bits set and have
-previously used an expression such as \code{\textasciitilde(1 <{}< 31)},
-it's probably
-clearest to start with all bits set and clear the desired upper bits.
-For example, to clear just the top bit (bit 31), you could write
-\code{0xffffffffL {\&}{\textasciitilde}(1L<{}<31)}.
-
-\item You can no longer disable assertions by assigning to \code{__debug__}.
-
-\item The Distutils \function{setup()} function has gained various new
-keyword arguments such as \var{depends}. Old versions of the
-Distutils will abort if passed unknown keywords. A solution is to check
-for the presence of the new \function{get_distutil_options()} function
-in your \file{setup.py} and only uses the new keywords
-with a version of the Distutils that supports them:
-
-\begin{verbatim}
-from distutils import core
-
-kw = {'sources': 'foo.c', ...}
-if hasattr(core, 'get_distutil_options'):
- kw['depends'] = ['foo.h']
-ext = Extension(**kw)
-\end{verbatim}
-
-\item Using \code{None} as a variable name will now result in a
-\exception{SyntaxWarning} warning.
-
-\item Names of extension types defined by the modules included with
-Python now contain the module and a \character{.} in front of the type
-name.
-
-\end{itemize}
-
-
-%======================================================================
-\section{Acknowledgements \label{acks}}
-
-The author would like to thank the following people for offering
-suggestions, corrections and assistance with various drafts of this
-article: Jeff Bauer, Simon Brunning, Brett Cannon, Michael Chermside,
-Andrew Dalke, Scott David Daniels, Fred~L. Drake, Jr., David Fraser,
-Kelly Gerber,
-Raymond Hettinger, Michael Hudson, Chris Lambert, Detlef Lannert,
-Martin von~L\"owis, Andrew MacIntyre, Lalo Martins, Chad Netzer,
-Gustavo Niemeyer, Neal Norwitz, Hans Nowak, Chris Reedy, Francesco
-Ricciardi, Vinay Sajip, Neil Schemenauer, Roman Suzi, Jason Tishler,
-Just van~Rossum.
-
-\end{document}
diff --git a/Doc/whatsnew/whatsnew24.tex b/Doc/whatsnew/whatsnew24.tex
deleted file mode 100644
index 399bc0e..0000000
--- a/Doc/whatsnew/whatsnew24.tex
+++ /dev/null
@@ -1,1757 +0,0 @@
-\documentclass{howto}
-\usepackage{distutils}
-% $Id$
-
-% Don't write extensive text for new sections; I'll do that.
-% Feel free to add commented-out reminders of things that need
-% to be covered. --amk
-
-\title{What's New in Python 2.4}
-\release{1.02}
-\author{A.M.\ Kuchling}
-\authoraddress{
- \strong{Python Software Foundation}\\
- Email: \email{amk@amk.ca}
-}
-
-\begin{document}
-\maketitle
-\tableofcontents
-
-This article explains the new features in Python 2.4.1, released on
-March~30, 2005.
-
-Python 2.4 is a medium-sized release. It doesn't introduce as many
-changes as the radical Python 2.2, but introduces more features than
-the conservative 2.3 release. The most significant new language
-features are function decorators and generator expressions; most other
-changes are to the standard library.
-
-According to the CVS change logs, there were 481 patches applied and
-502 bugs fixed between Python 2.3 and 2.4. Both figures are likely to
-be underestimates.
-
-This article doesn't attempt to provide a complete specification of
-every single new feature, but instead provides a brief introduction to
-each feature. For full details, you should refer to the documentation
-for Python 2.4, such as the \citetitle[../lib/lib.html]{Python Library
-Reference} and the \citetitle[../ref/ref.html]{Python Reference
-Manual}. Often you will be referred to the PEP for a particular new
-feature for explanations of the implementation and design rationale.
-
-
-%======================================================================
-\section{PEP 218: Built-In Set Objects}
-
-Python 2.3 introduced the \module{sets} module. C implementations of
-set data types have now been added to the Python core as two new
-built-in types, \function{set(\var{iterable})} and
-\function{frozenset(\var{iterable})}. They provide high speed
-operations for membership testing, for eliminating duplicates from
-sequences, and for mathematical operations like unions, intersections,
-differences, and symmetric differences.
-
-\begin{verbatim}
->>> a = set('abracadabra') # form a set from a string
->>> 'z' in a # fast membership testing
-False
->>> a # unique letters in a
-set(['a', 'r', 'b', 'c', 'd'])
->>> ''.join(a) # convert back into a string
-'arbcd'
-
->>> b = set('alacazam') # form a second set
->>> a - b # letters in a but not in b
-set(['r', 'd', 'b'])
->>> a | b # letters in either a or b
-set(['a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'])
->>> a & b # letters in both a and b
-set(['a', 'c'])
->>> a ^ b # letters in a or b but not both
-set(['r', 'd', 'b', 'm', 'z', 'l'])
-
->>> a.add('z') # add a new element
->>> a.update('wxy') # add multiple new elements
->>> a
-set(['a', 'c', 'b', 'd', 'r', 'w', 'y', 'x', 'z'])
->>> a.remove('x') # take one element out
->>> a
-set(['a', 'c', 'b', 'd', 'r', 'w', 'y', 'z'])
-\end{verbatim}
-
-The \function{frozenset} type is an immutable version of \function{set}.
-Since it is immutable and hashable, it may be used as a dictionary key or
-as a member of another set.
-
-The \module{sets} module remains in the standard library, and may be
-useful if you wish to subclass the \class{Set} or \class{ImmutableSet}
-classes. There are currently no plans to deprecate the module.
-
-\begin{seealso}
-\seepep{218}{Adding a Built-In Set Object Type}{Originally proposed by
-Greg Wilson and ultimately implemented by Raymond Hettinger.}
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 237: Unifying Long Integers and Integers}
-
-The lengthy transition process for this PEP, begun in Python 2.2,
-takes another step forward in Python 2.4. In 2.3, certain integer
-operations that would behave differently after int/long unification
-triggered \exception{FutureWarning} warnings and returned values
-limited to 32 or 64 bits (depending on your platform). In 2.4, these
-expressions no longer produce a warning and instead produce a
-different result that's usually a long integer.
-
-The problematic expressions are primarily left shifts and lengthy
-hexadecimal and octal constants. For example,
-\code{2 \textless{}\textless{} 32} results
-in a warning in 2.3, evaluating to 0 on 32-bit platforms. In Python
-2.4, this expression now returns the correct answer, 8589934592.
-
-\begin{seealso}
-\seepep{237}{Unifying Long Integers and Integers}{Original PEP
-written by Moshe Zadka and GvR. The changes for 2.4 were implemented by
-Kalle Svensson.}
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 289: Generator Expressions}
-
-The iterator feature introduced in Python 2.2 and the
-\module{itertools} module make it easier to write programs that loop
-through large data sets without having the entire data set in memory
-at one time. List comprehensions don't fit into this picture very
-well because they produce a Python list object containing all of the
-items. This unavoidably pulls all of the objects into memory, which
-can be a problem if your data set is very large. When trying to write
-a functionally-styled program, it would be natural to write something
-like:
-
-\begin{verbatim}
-links = [link for link in get_all_links() if not link.followed]
-for link in links:
- ...
-\end{verbatim}
-
-instead of
-
-\begin{verbatim}
-for link in get_all_links():
- if link.followed:
- continue
- ...
-\end{verbatim}
-
-The first form is more concise and perhaps more readable, but if
-you're dealing with a large number of link objects you'd have to write
-the second form to avoid having all link objects in memory at the same
-time.
-
-Generator expressions work similarly to list comprehensions but don't
-materialize the entire list; instead they create a generator that will
-return elements one by one. The above example could be written as:
-
-\begin{verbatim}
-links = (link for link in get_all_links() if not link.followed)
-for link in links:
- ...
-\end{verbatim}
-
-Generator expressions always have to be written inside parentheses, as
-in the above example. The parentheses signalling a function call also
-count, so if you want to create an iterator that will be immediately
-passed to a function you could write:
-
-\begin{verbatim}
-print sum(obj.count for obj in list_all_objects())
-\end{verbatim}
-
-Generator expressions differ from list comprehensions in various small
-ways. Most notably, the loop variable (\var{obj} in the above
-example) is not accessible outside of the generator expression. List
-comprehensions leave the variable assigned to its last value; future
-versions of Python will change this, making list comprehensions match
-generator expressions in this respect.
-
-\begin{seealso}
-\seepep{289}{Generator Expressions}{Proposed by Raymond Hettinger and
-implemented by Jiwon Seo with early efforts steered by Hye-Shik Chang.}
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 292: Simpler String Substitutions}
-
-Some new classes in the standard library provide an alternative
-mechanism for substituting variables into strings; this style of
-substitution may be better for applications where untrained
-users need to edit templates.
-
-The usual way of substituting variables by name is the \code{\%}
-operator:
-
-\begin{verbatim}
->>> '%(page)i: %(title)s' % {'page':2, 'title': 'The Best of Times'}
-'2: The Best of Times'
-\end{verbatim}
-
-When writing the template string, it can be easy to forget the
-\samp{i} or \samp{s} after the closing parenthesis. This isn't a big
-problem if the template is in a Python module, because you run the
-code, get an ``Unsupported format character'' \exception{ValueError},
-and fix the problem. However, consider an application such as Mailman
-where template strings or translations are being edited by users who
-aren't aware of the Python language. The format string's syntax is
-complicated to explain to such users, and if they make a mistake, it's
-difficult to provide helpful feedback to them.
-
-PEP 292 adds a \class{Template} class to the \module{string} module
-that uses \samp{\$} to indicate a substitution:
-
-\begin{verbatim}
->>> import string
->>> t = string.Template('$page: $title')
->>> t.substitute({'page':2, 'title': 'The Best of Times'})
-'2: The Best of Times'
-\end{verbatim}
-
-% $ Terminate $-mode for Emacs
-
-If a key is missing from the dictionary, the \method{substitute} method
-will raise a \exception{KeyError}. There's also a \method{safe_substitute}
-method that ignores missing keys:
-
-\begin{verbatim}
->>> t = string.Template('$page: $title')
->>> t.safe_substitute({'page':3})
-'3: $title'
-\end{verbatim}
-
-% $ Terminate math-mode for Emacs
-
-
-\begin{seealso}
-\seepep{292}{Simpler String Substitutions}{Written and implemented
-by Barry Warsaw.}
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 318: Decorators for Functions and Methods}
-
-Python 2.2 extended Python's object model by adding static methods and
-class methods, but it didn't extend Python's syntax to provide any new
-way of defining static or class methods. Instead, you had to write a
-\keyword{def} statement in the usual way, and pass the resulting
-method to a \function{staticmethod()} or \function{classmethod()}
-function that would wrap up the function as a method of the new type.
-Your code would look like this:
-
-\begin{verbatim}
-class C:
- def meth (cls):
- ...
-
- meth = classmethod(meth) # Rebind name to wrapped-up class method
-\end{verbatim}
-
-If the method was very long, it would be easy to miss or forget the
-\function{classmethod()} invocation after the function body.
-
-The intention was always to add some syntax to make such definitions
-more readable, but at the time of 2.2's release a good syntax was not
-obvious. Today a good syntax \emph{still} isn't obvious but users are
-asking for easier access to the feature; a new syntactic feature has
-been added to meet this need.
-
-The new feature is called ``function decorators''. The name comes
-from the idea that \function{classmethod}, \function{staticmethod},
-and friends are storing additional information on a function object;
-they're \emph{decorating} functions with more details.
-
-The notation borrows from Java and uses the \character{@} character as an
-indicator. Using the new syntax, the example above would be written:
-
-\begin{verbatim}
-class C:
-
- @classmethod
- def meth (cls):
- ...
-
-\end{verbatim}
-
-The \code{@classmethod} is shorthand for the
-\code{meth=classmethod(meth)} assignment. More generally, if you have
-the following:
-
-\begin{verbatim}
-@A
-@B
-@C
-def f ():
- ...
-\end{verbatim}
-
-It's equivalent to the following pre-decorator code:
-
-\begin{verbatim}
-def f(): ...
-f = A(B(C(f)))
-\end{verbatim}
-
-Decorators must come on the line before a function definition, one decorator
-per line, and can't be on the same line as the def statement, meaning that
-\code{@A def f(): ...} is illegal. You can only decorate function
-definitions, either at the module level or inside a class; you can't
-decorate class definitions.
-
-A decorator is just a function that takes the function to be decorated as an
-argument and returns either the same function or some new object. The
-return value of the decorator need not be callable (though it typically is),
-unless further decorators will be applied to the result. It's easy to write
-your own decorators. The following simple example just sets an attribute on
-the function object:
-
-\begin{verbatim}
->>> def deco(func):
-... func.attr = 'decorated'
-... return func
-...
->>> @deco
-... def f(): pass
-...
->>> f
-<function f at 0x402ef0d4>
->>> f.attr
-'decorated'
->>>
-\end{verbatim}
-
-As a slightly more realistic example, the following decorator checks
-that the supplied argument is an integer:
-
-\begin{verbatim}
-def require_int (func):
- def wrapper (arg):
- assert isinstance(arg, int)
- return func(arg)
-
- return wrapper
-
-@require_int
-def p1 (arg):
- print arg
-
-@require_int
-def p2(arg):
- print arg*2
-\end{verbatim}
-
-An example in \pep{318} contains a fancier version of this idea that
-lets you both specify the required type and check the returned type.
-
-Decorator functions can take arguments. If arguments are supplied,
-your decorator function is called with only those arguments and must
-return a new decorator function; this function must take a single
-function and return a function, as previously described. In other
-words, \code{@A @B @C(args)} becomes:
-
-\begin{verbatim}
-def f(): ...
-_deco = C(args)
-f = A(B(_deco(f)))
-\end{verbatim}
-
-Getting this right can be slightly brain-bending, but it's not too
-difficult.
-
-A small related change makes the \member{func_name} attribute of
-functions writable. This attribute is used to display function names
-in tracebacks, so decorators should change the name of any new
-function that's constructed and returned.
-
-\begin{seealso}
-\seepep{318}{Decorators for Functions, Methods and Classes}{Written
-by Kevin D. Smith, Jim Jewett, and Skip Montanaro. Several people
-wrote patches implementing function decorators, but the one that was
-actually checked in was patch \#979728, written by Mark Russell.}
-
-\seeurl{http://www.python.org/moin/PythonDecoratorLibrary}
-{This Wiki page contains several examples of decorators.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 322: Reverse Iteration}
-
-A new built-in function, \function{reversed(\var{seq})}, takes a sequence
-and returns an iterator that loops over the elements of the sequence
-in reverse order.
-
-\begin{verbatim}
->>> for i in reversed(xrange(1,4)):
-... print i
-...
-3
-2
-1
-\end{verbatim}
-
-Compared to extended slicing, such as \code{range(1,4)[::-1]},
-\function{reversed()} is easier to read, runs faster, and uses
-substantially less memory.
-
-Note that \function{reversed()} only accepts sequences, not arbitrary
-iterators. If you want to reverse an iterator, first convert it to
-a list with \function{list()}.
-
-\begin{verbatim}
->>> input = open('/etc/passwd', 'r')
->>> for line in reversed(list(input)):
-... print line
-...
-root:*:0:0:System Administrator:/var/root:/bin/tcsh
- ...
-\end{verbatim}
-
-\begin{seealso}
-\seepep{322}{Reverse Iteration}{Written and implemented by Raymond Hettinger.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 324: New subprocess Module}
-
-The standard library provides a number of ways to execute a
-subprocess, offering different features and different levels of
-complexity. \function{os.system(\var{command})} is easy to use, but
-slow (it runs a shell process which executes the command) and
-dangerous (you have to be careful about escaping the shell's
-metacharacters). The \module{popen2} module offers classes that can
-capture standard output and standard error from the subprocess, but
-the naming is confusing. The \module{subprocess} module cleans
-this up, providing a unified interface that offers all the features
-you might need.
-
-Instead of \module{popen2}'s collection of classes,
-\module{subprocess} contains a single class called \class{Popen}
-whose constructor supports a number of different keyword arguments.
-
-\begin{verbatim}
-class Popen(args, bufsize=0, executable=None,
- stdin=None, stdout=None, stderr=None,
- preexec_fn=None, close_fds=False, shell=False,
- cwd=None, env=None, universal_newlines=False,
- startupinfo=None, creationflags=0):
-\end{verbatim}
-
-\var{args} is commonly a sequence of strings that will be the
-arguments to the program executed as the subprocess. (If the
-\var{shell} argument is true, \var{args} can be a string which will
-then be passed on to the shell for interpretation, just as
-\function{os.system()} does.)
-
-\var{stdin}, \var{stdout}, and \var{stderr} specify what the
-subprocess's input, output, and error streams will be. You can
-provide a file object or a file descriptor, or you can use the
-constant \code{subprocess.PIPE} to create a pipe between the
-subprocess and the parent.
-
-The constructor has a number of handy options:
-
-\begin{itemize}
- \item \var{close_fds} requests that all file descriptors be closed
- before running the subprocess.
-
- \item \var{cwd} specifies the working directory in which the
- subprocess will be executed (defaulting to whatever the parent's
- working directory is).
-
- \item \var{env} is a dictionary specifying environment variables.
-
- \item \var{preexec_fn} is a function that gets called before the
- child is started.
-
- \item \var{universal_newlines} opens the child's input and output
- using Python's universal newline feature.
-
-\end{itemize}
-
-Once you've created the \class{Popen} instance,
-you can call its \method{wait()} method to pause until the subprocess
-has exited, \method{poll()} to check if it's exited without pausing,
-or \method{communicate(\var{data})} to send the string \var{data} to
-the subprocess's standard input. \method{communicate(\var{data})}
-then reads any data that the subprocess has sent to its standard output
-or standard error, returning a tuple \code{(\var{stdout_data},
-\var{stderr_data})}.
-
-\function{call()} is a shortcut that passes its arguments along to the
-\class{Popen} constructor, waits for the command to complete, and
-returns the status code of the subprocess. It can serve as a safer
-analog to \function{os.system()}:
-
-\begin{verbatim}
-sts = subprocess.call(['dpkg', '-i', '/tmp/new-package.deb'])
-if sts == 0:
- # Success
- ...
-else:
- # dpkg returned an error
- ...
-\end{verbatim}
-
-The command is invoked without use of the shell. If you really do want to
-use the shell, you can add \code{shell=True} as a keyword argument and provide
-a string instead of a sequence:
-
-\begin{verbatim}
-sts = subprocess.call('dpkg -i /tmp/new-package.deb', shell=True)
-\end{verbatim}
-
-The PEP takes various examples of shell and Python code and shows how
-they'd be translated into Python code that uses \module{subprocess}.
-Reading this section of the PEP is highly recommended.
-
-\begin{seealso}
-\seepep{324}{subprocess - New process module}{Written and implemented by Peter {\AA}strand, with assistance from Fredrik Lundh and others.}
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 327: Decimal Data Type}
-
-Python has always supported floating-point (FP) numbers, based on the
-underlying C \ctype{double} type, as a data type. However, while most
-programming languages provide a floating-point type, many people (even
-programmers) are unaware that floating-point numbers don't represent
-certain decimal fractions accurately. The new \class{Decimal} type
-can represent these fractions accurately, up to a user-specified
-precision limit.
-
-
-\subsection{Why is Decimal needed?}
-
-The limitations arise from the representation used for floating-point numbers.
-FP numbers are made up of three components:
-
-\begin{itemize}
-\item The sign, which is positive or negative.
-\item The mantissa, which is a single-digit binary number
-followed by a fractional part. For example, \code{1.01} in base-2 notation
-is \code{1 + 0/2 + 1/4}, or 1.25 in decimal notation.
-\item The exponent, which tells where the decimal point is located in the number represented.
-\end{itemize}
-
-For example, the number 1.25 has positive sign, a mantissa value of
-1.01 (in binary), and an exponent of 0 (the decimal point doesn't need
-to be shifted). The number 5 has the same sign and mantissa, but the
-exponent is 2 because the mantissa is multiplied by 4 (2 to the power
-of the exponent 2); 1.25 * 4 equals 5.
-
-Modern systems usually provide floating-point support that conforms to
-a standard called IEEE 754. C's \ctype{double} type is usually
-implemented as a 64-bit IEEE 754 number, which uses 52 bits of space
-for the mantissa. This means that numbers can only be specified to 52
-bits of precision. If you're trying to represent numbers whose
-expansion repeats endlessly, the expansion is cut off after 52 bits.
-Unfortunately, most software needs to produce output in base 10, and
-common fractions in base 10 are often repeating decimals in binary.
-For example, 1.1 decimal is binary \code{1.0001100110011 ...}; .1 =
-1/16 + 1/32 + 1/256 plus an infinite number of additional terms. IEEE
-754 has to chop off that infinitely repeated decimal after 52 digits,
-so the representation is slightly inaccurate.
-
-Sometimes you can see this inaccuracy when the number is printed:
-\begin{verbatim}
->>> 1.1
-1.1000000000000001
-\end{verbatim}
-
-The inaccuracy isn't always visible when you print the number because
-the FP-to-decimal-string conversion is provided by the C library, and
-most C libraries try to produce sensible output. Even if it's not
-displayed, however, the inaccuracy is still there and subsequent
-operations can magnify the error.
-
-For many applications this doesn't matter. If I'm plotting points and
-displaying them on my monitor, the difference between 1.1 and
-1.1000000000000001 is too small to be visible. Reports often limit
-output to a certain number of decimal places, and if you round the
-number to two or three or even eight decimal places, the error is
-never apparent. However, for applications where it does matter,
-it's a lot of work to implement your own custom arithmetic routines.
-
-Hence, the \class{Decimal} type was created.
-
-\subsection{The \class{Decimal} type}
-
-A new module, \module{decimal}, was added to Python's standard
-library. It contains two classes, \class{Decimal} and
-\class{Context}. \class{Decimal} instances represent numbers, and
-\class{Context} instances are used to wrap up various settings such as
-the precision and default rounding mode.
-
-\class{Decimal} instances are immutable, like regular Python integers
-and FP numbers; once it's been created, you can't change the value an
-instance represents. \class{Decimal} instances can be created from
-integers or strings:
-
-\begin{verbatim}
->>> import decimal
->>> decimal.Decimal(1972)
-Decimal("1972")
->>> decimal.Decimal("1.1")
-Decimal("1.1")
-\end{verbatim}
-
-You can also provide tuples containing the sign, the mantissa represented
-as a tuple of decimal digits, and the exponent:
-
-\begin{verbatim}
->>> decimal.Decimal((1, (1, 4, 7, 5), -2))
-Decimal("-14.75")
-\end{verbatim}
-
-Cautionary note: the sign bit is a Boolean value, so 0 is positive and
-1 is negative.
-
-Converting from floating-point numbers poses a bit of a problem:
-should the FP number representing 1.1 turn into the decimal number for
-exactly 1.1, or for 1.1 plus whatever inaccuracies are introduced?
-The decision was to dodge the issue and leave such a conversion out of
-the API. Instead, you should convert the floating-point number into a
-string using the desired precision and pass the string to the
-\class{Decimal} constructor:
-
-\begin{verbatim}
->>> f = 1.1
->>> decimal.Decimal(str(f))
-Decimal("1.1")
->>> decimal.Decimal('%.12f' % f)
-Decimal("1.100000000000")
-\end{verbatim}
-
-Once you have \class{Decimal} instances, you can perform the usual
-mathematical operations on them. One limitation: exponentiation
-requires an integer exponent:
-
-\begin{verbatim}
->>> a = decimal.Decimal('35.72')
->>> b = decimal.Decimal('1.73')
->>> a+b
-Decimal("37.45")
->>> a-b
-Decimal("33.99")
->>> a*b
-Decimal("61.7956")
->>> a/b
-Decimal("20.64739884393063583815028902")
->>> a ** 2
-Decimal("1275.9184")
->>> a**b
-Traceback (most recent call last):
- ...
-decimal.InvalidOperation: x ** (non-integer)
-\end{verbatim}
-
-You can combine \class{Decimal} instances with integers, but not with
-floating-point numbers:
-
-\begin{verbatim}
->>> a + 4
-Decimal("39.72")
->>> a + 4.5
-Traceback (most recent call last):
- ...
-TypeError: You can interact Decimal only with int, long or Decimal data types.
->>>
-\end{verbatim}
-
-\class{Decimal} numbers can be used with the \module{math} and
-\module{cmath} modules, but note that they'll be immediately converted to
-floating-point numbers before the operation is performed, resulting in
-a possible loss of precision and accuracy. You'll also get back a
-regular floating-point number and not a \class{Decimal}.
-
-\begin{verbatim}
->>> import math, cmath
->>> d = decimal.Decimal('123456789012.345')
->>> math.sqrt(d)
-351364.18288201344
->>> cmath.sqrt(-d)
-351364.18288201344j
-\end{verbatim}
-
-\class{Decimal} instances have a \method{sqrt()} method that
-returns a \class{Decimal}, but if you need other things such as
-trigonometric functions you'll have to implement them.
-
-\begin{verbatim}
->>> d.sqrt()
-Decimal("351364.1828820134592177245001")
-\end{verbatim}
-
-
-\subsection{The \class{Context} type}
-
-Instances of the \class{Context} class encapsulate several settings for
-decimal operations:
-
-\begin{itemize}
- \item \member{prec} is the precision, the number of decimal places.
- \item \member{rounding} specifies the rounding mode. The \module{decimal}
- module has constants for the various possibilities:
- \constant{ROUND_DOWN}, \constant{ROUND_CEILING},
- \constant{ROUND_HALF_EVEN}, and various others.
- \item \member{traps} is a dictionary specifying what happens on
-encountering certain error conditions: either an exception is raised or
-a value is returned. Some examples of error conditions are
-division by zero, loss of precision, and overflow.
-\end{itemize}
-
-There's a thread-local default context available by calling
-\function{getcontext()}; you can change the properties of this context
-to alter the default precision, rounding, or trap handling. The
-following example shows the effect of changing the precision of the default
-context:
-
-\begin{verbatim}
->>> decimal.getcontext().prec
-28
->>> decimal.Decimal(1) / decimal.Decimal(7)
-Decimal("0.1428571428571428571428571429")
->>> decimal.getcontext().prec = 9
->>> decimal.Decimal(1) / decimal.Decimal(7)
-Decimal("0.142857143")
-\end{verbatim}
-
-The default action for error conditions is selectable; the module can
-either return a special value such as infinity or not-a-number, or
-exceptions can be raised:
-
-\begin{verbatim}
->>> decimal.Decimal(1) / decimal.Decimal(0)
-Traceback (most recent call last):
- ...
-decimal.DivisionByZero: x / 0
->>> decimal.getcontext().traps[decimal.DivisionByZero] = False
->>> decimal.Decimal(1) / decimal.Decimal(0)
-Decimal("Infinity")
->>>
-\end{verbatim}
-
-The \class{Context} instance also has various methods for formatting
-numbers such as \method{to_eng_string()} and \method{to_sci_string()}.
-
-For more information, see the documentation for the \module{decimal}
-module, which includes a quick-start tutorial and a reference.
-
-\begin{seealso}
-\seepep{327}{Decimal Data Type}{Written by Facundo Batista and implemented
- by Facundo Batista, Eric Price, Raymond Hettinger, Aahz, and Tim Peters.}
-
-\seeurl{http://research.microsoft.com/\textasciitilde hollasch/cgindex/coding/ieeefloat.html}
-{A more detailed overview of the IEEE-754 representation.}
-
-\seeurl{http://www.lahey.com/float.htm}
-{The article uses Fortran code to illustrate many of the problems
-that floating-point inaccuracy can cause.}
-
-\seeurl{http://www2.hursley.ibm.com/decimal/}
-{A description of a decimal-based representation. This representation
-is being proposed as a standard, and underlies the new Python decimal
-type. Much of this material was written by Mike Cowlishaw, designer of the
-Rexx language.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 328: Multi-line Imports}
-
-One language change is a small syntactic tweak aimed at making it
-easier to import many names from a module. In a
-\code{from \var{module} import \var{names}} statement,
-\var{names} is a sequence of names separated by commas. If the sequence is
-very long, you can either write multiple imports from the same module,
-or you can use backslashes to escape the line endings like this:
-
-\begin{verbatim}
-from SimpleXMLRPCServer import SimpleXMLRPCServer,\
- SimpleXMLRPCRequestHandler,\
- CGIXMLRPCRequestHandler,\
- resolve_dotted_attribute
-\end{verbatim}
-
-The syntactic change in Python 2.4 simply allows putting the names
-within parentheses. Python ignores newlines within a parenthesized
-expression, so the backslashes are no longer needed:
-
-\begin{verbatim}
-from SimpleXMLRPCServer import (SimpleXMLRPCServer,
- SimpleXMLRPCRequestHandler,
- CGIXMLRPCRequestHandler,
- resolve_dotted_attribute)
-\end{verbatim}
-
-The PEP also proposes that all \keyword{import} statements be absolute
-imports, with a leading \samp{.} character to indicate a relative
-import. This part of the PEP was not implemented for Python 2.4,
-but was completed for Python 2.5.
-
-\begin{seealso}
-\seepep{328}{Imports: Multi-Line and Absolute/Relative}
- {Written by Aahz. Multi-line imports were implemented by
- Dima Dorfman.}
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 331: Locale-Independent Float/String Conversions}
-
-The \module{locale} modules lets Python software select various
-conversions and display conventions that are localized to a particular
-country or language. However, the module was careful to not change
-the numeric locale because various functions in Python's
-implementation required that the numeric locale remain set to the
-\code{'C'} locale. Often this was because the code was using the C library's
-\cfunction{atof()} function.
-
-Not setting the numeric locale caused trouble for extensions that used
-third-party C libraries, however, because they wouldn't have the
-correct locale set. The motivating example was GTK+, whose user
-interface widgets weren't displaying numbers in the current locale.
-
-The solution described in the PEP is to add three new functions to the
-Python API that perform ASCII-only conversions, ignoring the locale
-setting:
-
-\begin{itemize}
- \item \cfunction{PyOS_ascii_strtod(\var{str}, \var{ptr})}
-and \cfunction{PyOS_ascii_atof(\var{str}, \var{ptr})}
-both convert a string to a C \ctype{double}.
- \item \cfunction{PyOS_ascii_formatd(\var{buffer}, \var{buf_len}, \var{format}, \var{d})} converts a \ctype{double} to an ASCII string.
-\end{itemize}
-
-The code for these functions came from the GLib library
-(\url{http://developer.gnome.org/arch/gtk/glib.html}), whose
-developers kindly relicensed the relevant functions and donated them
-to the Python Software Foundation. The \module{locale} module
-can now change the numeric locale, letting extensions such as GTK+
-produce the correct results.
-
-\begin{seealso}
-\seepep{331}{Locale-Independent Float/String Conversions}
-{Written by Christian R. Reis, and implemented by Gustavo Carneiro.}
-\end{seealso}
-
-%======================================================================
-\section{Other Language Changes}
-
-Here are all of the changes that Python 2.4 makes to the core Python
-language.
-
-\begin{itemize}
-
-\item Decorators for functions and methods were added (\pep{318}).
-
-\item Built-in \function{set} and \function{frozenset} types were
-added (\pep{218}). Other new built-ins include the \function{reversed(\var{seq})} function (\pep{322}).
-
-\item Generator expressions were added (\pep{289}).
-
-\item Certain numeric expressions no longer return values restricted to 32 or 64 bits (\pep{237}).
-
-\item You can now put parentheses around the list of names in a
-\code{from \var{module} import \var{names}} statement (\pep{328}).
-
-\item The \method{dict.update()} method now accepts the same
-argument forms as the \class{dict} constructor. This includes any
-mapping, any iterable of key/value pairs, and keyword arguments.
-(Contributed by Raymond Hettinger.)
-
-\item The string methods \method{ljust()}, \method{rjust()}, and
-\method{center()} now take an optional argument for specifying a
-fill character other than a space.
-(Contributed by Raymond Hettinger.)
-
-\item Strings also gained an \method{rsplit()} method that
-works like the \method{split()} method but splits from the end of
-the string.
-(Contributed by Sean Reifschneider.)
-
-\begin{verbatim}
->>> 'www.python.org'.split('.', 1)
-['www', 'python.org']
-'www.python.org'.rsplit('.', 1)
-['www.python', 'org']
-\end{verbatim}
-
-\item Three keyword parameters, \var{cmp}, \var{key}, and
-\var{reverse}, were added to the \method{sort()} method of lists.
-These parameters make some common usages of \method{sort()} simpler.
-All of these parameters are optional.
-
-For the \var{cmp} parameter, the value should be a comparison function
-that takes two parameters and returns -1, 0, or +1 depending on how
-the parameters compare. This function will then be used to sort the
-list. Previously this was the only parameter that could be provided
-to \method{sort()}.
-
-\var{key} should be a single-parameter function that takes a list
-element and returns a comparison key for the element. The list is
-then sorted using the comparison keys. The following example sorts a
-list case-insensitively:
-
-\begin{verbatim}
->>> L = ['A', 'b', 'c', 'D']
->>> L.sort() # Case-sensitive sort
->>> L
-['A', 'D', 'b', 'c']
->>> # Using 'key' parameter to sort list
->>> L.sort(key=lambda x: x.lower())
->>> L
-['A', 'b', 'c', 'D']
->>> # Old-fashioned way
->>> L.sort(cmp=lambda x,y: cmp(x.lower(), y.lower()))
->>> L
-['A', 'b', 'c', 'D']
-\end{verbatim}
-
-The last example, which uses the \var{cmp} parameter, is the old way
-to perform a case-insensitive sort. It works but is slower than using
-a \var{key} parameter. Using \var{key} calls \method{lower()} method
-once for each element in the list while using \var{cmp} will call it
-twice for each comparison, so using \var{key} saves on invocations of
-the \method{lower()} method.
-
-For simple key functions and comparison functions, it is often
-possible to avoid a \keyword{lambda} expression by using an unbound
-method instead. For example, the above case-insensitive sort is best
-written as:
-
-\begin{verbatim}
->>> L.sort(key=str.lower)
->>> L
-['A', 'b', 'c', 'D']
-\end{verbatim}
-
-Finally, the \var{reverse} parameter takes a Boolean value. If the
-value is true, the list will be sorted into reverse order.
-Instead of \code{L.sort() ; L.reverse()}, you can now write
-\code{L.sort(reverse=True)}.
-
-The results of sorting are now guaranteed to be stable. This means
-that two entries with equal keys will be returned in the same order as
-they were input. For example, you can sort a list of people by name,
-and then sort the list by age, resulting in a list sorted by age where
-people with the same age are in name-sorted order.
-
-(All changes to \method{sort()} contributed by Raymond Hettinger.)
-
-\item There is a new built-in function
-\function{sorted(\var{iterable})} that works like the in-place
-\method{list.sort()} method but can be used in
-expressions. The differences are:
- \begin{itemize}
- \item the input may be any iterable;
- \item a newly formed copy is sorted, leaving the original intact; and
- \item the expression returns the new sorted copy
- \end{itemize}
-
-\begin{verbatim}
->>> L = [9,7,8,3,2,4,1,6,5]
->>> [10+i for i in sorted(L)] # usable in a list comprehension
-[11, 12, 13, 14, 15, 16, 17, 18, 19]
->>> L # original is left unchanged
-[9,7,8,3,2,4,1,6,5]
->>> sorted('Monty Python') # any iterable may be an input
-[' ', 'M', 'P', 'h', 'n', 'n', 'o', 'o', 't', 't', 'y', 'y']
-
->>> # List the contents of a dict sorted by key values
->>> colormap = dict(red=1, blue=2, green=3, black=4, yellow=5)
->>> for k, v in sorted(colormap.iteritems()):
-... print k, v
-...
-black 4
-blue 2
-green 3
-red 1
-yellow 5
-\end{verbatim}
-
-(Contributed by Raymond Hettinger.)
-
-\item Integer operations will no longer trigger an \exception{OverflowWarning}.
-The \exception{OverflowWarning} warning will disappear in Python 2.5.
-
-\item The interpreter gained a new switch, \programopt{-m}, that
-takes a name, searches for the corresponding module on \code{sys.path},
-and runs the module as a script. For example,
-you can now run the Python profiler with \code{python -m profile}.
-(Contributed by Nick Coghlan.)
-
-\item The \function{eval(\var{expr}, \var{globals}, \var{locals})}
-and \function{execfile(\var{filename}, \var{globals}, \var{locals})}
-functions and the \keyword{exec} statement now accept any mapping type
-for the \var{locals} parameter. Previously this had to be a regular
-Python dictionary. (Contributed by Raymond Hettinger.)
-
-\item The \function{zip()} built-in function and \function{itertools.izip()}
- now return an empty list if called with no arguments.
- Previously they raised a \exception{TypeError}
- exception. This makes them more
- suitable for use with variable length argument lists:
-
-\begin{verbatim}
->>> def transpose(array):
-... return zip(*array)
-...
->>> transpose([(1,2,3), (4,5,6)])
-[(1, 4), (2, 5), (3, 6)]
->>> transpose([])
-[]
-\end{verbatim}
-(Contributed by Raymond Hettinger.)
-
-\item Encountering a failure while importing a module no longer leaves
-a partially-initialized module object in \code{sys.modules}. The
-incomplete module object left behind would fool further imports of the
-same module into succeeding, leading to confusing errors.
-(Fixed by Tim Peters.)
-
-\item \constant{None} is now a constant; code that binds a new value to
-the name \samp{None} is now a syntax error.
-(Contributed by Raymond Hettinger.)
-
-\end{itemize}
-
-
-%======================================================================
-\subsection{Optimizations}
-
-\begin{itemize}
-
-\item The inner loops for list and tuple slicing
- were optimized and now run about one-third faster. The inner loops
- for dictionaries were also optimized, resulting in performance boosts for
- \method{keys()}, \method{values()}, \method{items()},
- \method{iterkeys()}, \method{itervalues()}, and \method{iteritems()}.
- (Contributed by Raymond Hettinger.)
-
-\item The machinery for growing and shrinking lists was optimized for
- speed and for space efficiency. Appending and popping from lists now
- runs faster due to more efficient code paths and less frequent use of
- the underlying system \cfunction{realloc()}. List comprehensions
- also benefit. \method{list.extend()} was also optimized and no
- longer converts its argument into a temporary list before extending
- the base list. (Contributed by Raymond Hettinger.)
-
-\item \function{list()}, \function{tuple()}, \function{map()},
- \function{filter()}, and \function{zip()} now run several times
- faster with non-sequence arguments that supply a \method{__len__()}
- method. (Contributed by Raymond Hettinger.)
-
-\item The methods \method{list.__getitem__()},
- \method{dict.__getitem__()}, and \method{dict.__contains__()} are
- are now implemented as \class{method_descriptor} objects rather
- than \class{wrapper_descriptor} objects. This form of
- access doubles their performance and makes them more suitable for
- use as arguments to functionals:
- \samp{map(mydict.__getitem__, keylist)}.
- (Contributed by Raymond Hettinger.)
-
-\item Added a new opcode, \code{LIST_APPEND}, that simplifies
- the generated bytecode for list comprehensions and speeds them up
- by about a third. (Contributed by Raymond Hettinger.)
-
-\item The peephole bytecode optimizer has been improved to
-produce shorter, faster bytecode; remarkably, the resulting bytecode is
-more readable. (Enhanced by Raymond Hettinger.)
-
-\item String concatenations in statements of the form \code{s = s +
-"abc"} and \code{s += "abc"} are now performed more efficiently in
-certain circumstances. This optimization won't be present in other
-Python implementations such as Jython, so you shouldn't rely on it;
-using the \method{join()} method of strings is still recommended when
-you want to efficiently glue a large number of strings together.
-(Contributed by Armin Rigo.)
-
-\end{itemize}
-
-% pystone is almost useless for comparing different versions of Python;
-% instead, it excels at predicting relative Python performance on
-% different machines.
-% So, this section would be more informative if it used other tools
-% such as pybench and parrotbench. For a more application oriented
-% benchmark, try comparing the timings of test_decimal.py under 2.3
-% and 2.4.
-
-The net result of the 2.4 optimizations is that Python 2.4 runs the
-pystone benchmark around 5\% faster than Python 2.3 and 35\% faster
-than Python 2.2. (pystone is not a particularly good benchmark, but
-it's the most commonly used measurement of Python's performance. Your
-own applications may show greater or smaller benefits from Python~2.4.)
-
-
-%======================================================================
-\section{New, Improved, and Deprecated Modules}
-
-As usual, Python's standard library received a number of enhancements and
-bug fixes. Here's a partial list of the most notable changes, sorted
-alphabetically by module name. Consult the
-\file{Misc/NEWS} file in the source tree for a more
-complete list of changes, or look through the CVS logs for all the
-details.
-
-\begin{itemize}
-
-\item The \module{asyncore} module's \function{loop()} function now
- has a \var{count} parameter that lets you perform a limited number
- of passes through the polling loop. The default is still to loop
- forever.
-
-\item The \module{base64} module now has more complete RFC 3548 support
- for Base64, Base32, and Base16 encoding and decoding, including
- optional case folding and optional alternative alphabets.
- (Contributed by Barry Warsaw.)
-
-\item The \module{bisect} module now has an underlying C implementation
- for improved performance.
- (Contributed by Dmitry Vasiliev.)
-
-\item The CJKCodecs collections of East Asian codecs, maintained
-by Hye-Shik Chang, was integrated into 2.4.
-The new encodings are:
-
-\begin{itemize}
- \item Chinese (PRC): gb2312, gbk, gb18030, big5hkscs, hz
- \item Chinese (ROC): big5, cp950
- \item Japanese: cp932, euc-jis-2004, euc-jp,
-euc-jisx0213, iso-2022-jp, iso-2022-jp-1, iso-2022-jp-2,
- iso-2022-jp-3, iso-2022-jp-ext, iso-2022-jp-2004,
- shift-jis, shift-jisx0213, shift-jis-2004
- \item Korean: cp949, euc-kr, johab, iso-2022-kr
-\end{itemize}
-
-\item Some other new encodings were added: HP Roman8,
-ISO_8859-11, ISO_8859-16, PCTP-154, and TIS-620.
-
-\item The UTF-8 and UTF-16 codecs now cope better with receiving partial input.
-Previously the \class{StreamReader} class would try to read more data,
-making it impossible to resume decoding from the stream. The
-\method{read()} method will now return as much data as it can and future
-calls will resume decoding where previous ones left off.
-(Implemented by Walter D\"orwald.)
-
-\item There is a new \module{collections} module for
- various specialized collection datatypes.
- Currently it contains just one type, \class{deque},
- a double-ended queue that supports efficiently adding and removing
- elements from either end:
-
-\begin{verbatim}
->>> from collections import deque
->>> d = deque('ghi') # make a new deque with three items
->>> 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']
->>> 'h' in d # search the deque
-True
-\end{verbatim}
-
-Several modules, such as the \module{Queue} and \module{threading}
-modules, now take advantage of \class{collections.deque} for improved
-performance. (Contributed by Raymond Hettinger.)
-
-\item The \module{ConfigParser} classes have been enhanced slightly.
- The \method{read()} method now returns a list of the files that
- were successfully parsed, and the \method{set()} method raises
- \exception{TypeError} if passed a \var{value} argument that isn't a
- string. (Contributed by John Belmonte and David Goodger.)
-
-\item The \module{curses} module now supports the ncurses extension
- \function{use_default_colors()}. On platforms where the terminal
- supports transparency, this makes it possible to use a transparent
- background. (Contributed by J\"org Lehmann.)
-
-\item The \module{difflib} module now includes an \class{HtmlDiff} class
-that creates an HTML table showing a side by side comparison
-of two versions of a text. (Contributed by Dan Gass.)
-
-\item The \module{email} package was updated to version 3.0,
-which dropped various deprecated APIs and removes support for Python
-versions earlier than 2.3. The 3.0 version of the package uses a new
-incremental parser for MIME messages, available in the
-\module{email.FeedParser} module. The new parser doesn't require
-reading the entire message into memory, and doesn't throw exceptions
-if a message is malformed; instead it records any problems in the
-\member{defect} attribute of the message. (Developed by Anthony
-Baxter, Barry Warsaw, Thomas Wouters, and others.)
-
-\item The \module{heapq} module has been converted to C. The resulting
- tenfold improvement in speed makes the module suitable for handling
- high volumes of data. In addition, the module has two new functions
- \function{nlargest()} and \function{nsmallest()} that use heaps to
- find the N largest or smallest values in a dataset without the
- expense of a full sort. (Contributed by Raymond Hettinger.)
-
-\item The \module{httplib} module now contains constants for HTTP
-status codes defined in various HTTP-related RFC documents. Constants
-have names such as \constant{OK}, \constant{CREATED},
-\constant{CONTINUE}, and \constant{MOVED_PERMANENTLY}; use pydoc to
-get a full list. (Contributed by Andrew Eland.)
-
-\item The \module{imaplib} module now supports IMAP's THREAD command
-(contributed by Yves Dionne) and new \method{deleteacl()} and
-\method{myrights()} methods (contributed by Arnaud Mazin).
-
-\item The \module{itertools} module gained a
- \function{groupby(\var{iterable}\optional{, \var{func}})} function.
- \var{iterable} is something that can be iterated over to return a
- stream of elements, and the optional \var{func} parameter is a
- function that takes an element and returns a key value; if omitted,
- the key is simply the element itself. \function{groupby()} then
- groups the elements into subsequences which have matching values of
- the key, and returns a series of 2-tuples containing the key value
- and an iterator over the subsequence.
-
-Here's an example to make this clearer. The \var{key} function simply
-returns whether a number is even or odd, so the result of
-\function{groupby()} is to return consecutive runs of odd or even
-numbers.
-
-\begin{verbatim}
->>> import itertools
->>> L = [2, 4, 6, 7, 8, 9, 11, 12, 14]
->>> for key_val, it in itertools.groupby(L, lambda x: x % 2):
-... print key_val, list(it)
-...
-0 [2, 4, 6]
-1 [7]
-0 [8]
-1 [9, 11]
-0 [12, 14]
->>>
-\end{verbatim}
-
-\function{groupby()} is typically used with sorted input. The logic
-for \function{groupby()} is similar to the \UNIX{} \code{uniq} filter
-which makes it handy for eliminating, counting, or identifying
-duplicate elements:
-
-\begin{verbatim}
->>> word = 'abracadabra'
->>> letters = sorted(word) # Turn string into a sorted list of letters
->>> letters
-['a', 'a', 'a', 'a', 'a', 'b', 'b', 'c', 'd', 'r', 'r']
->>> for k, g in itertools.groupby(letters):
-... print k, list(g)
-...
-a ['a', 'a', 'a', 'a', 'a']
-b ['b', 'b']
-c ['c']
-d ['d']
-r ['r', 'r']
->>> # List unique letters
->>> [k for k, g in groupby(letters)]
-['a', 'b', 'c', 'd', 'r']
->>> # Count letter occurrences
->>> [(k, len(list(g))) for k, g in groupby(letters)]
-[('a', 5), ('b', 2), ('c', 1), ('d', 1), ('r', 2)]
-\end{verbatim}
-
-(Contributed by Hye-Shik Chang.)
-
-\item \module{itertools} also gained a function named
-\function{tee(\var{iterator}, \var{N})} that returns \var{N} independent
-iterators that replicate \var{iterator}. If \var{N} is omitted, the
-default is 2.
-
-\begin{verbatim}
->>> L = [1,2,3]
->>> i1, i2 = itertools.tee(L)
->>> i1,i2
-(<itertools.tee object at 0x402c2080>, <itertools.tee object at 0x402c2090>)
->>> list(i1) # Run the first iterator to exhaustion
-[1, 2, 3]
->>> list(i2) # Run the second iterator to exhaustion
-[1, 2, 3]
-\end{verbatim}
-
-Note that \function{tee()} has to keep copies of the values returned
-by the iterator; in the worst case, it may need to keep all of them.
-This should therefore be used carefully if the leading iterator
-can run far ahead of the trailing iterator in a long stream of inputs.
-If the separation is large, then you might as well use
-\function{list()} instead. When the iterators track closely with one
-another, \function{tee()} is ideal. Possible applications include
-bookmarking, windowing, or lookahead iterators.
-(Contributed by Raymond Hettinger.)
-
-\item A number of functions were added to the \module{locale}
-module, such as \function{bind_textdomain_codeset()} to specify a
-particular encoding and a family of \function{l*gettext()} functions
-that return messages in the chosen encoding.
-(Contributed by Gustavo Niemeyer.)
-
-\item Some keyword arguments were added to the \module{logging}
-package's \function{basicConfig} function to simplify log
-configuration. The default behavior is to log messages to standard
-error, but various keyword arguments can be specified to log to a
-particular file, change the logging format, or set the logging level.
-For example:
-
-\begin{verbatim}
-import logging
-logging.basicConfig(filename='/var/log/application.log',
- level=0, # Log all messages
- format='%(levelname):%(process):%(thread):%(message)')
-\end{verbatim}
-
-Other additions to the \module{logging} package include a
-\method{log(\var{level}, \var{msg})} convenience method, as well as a
-\class{TimedRotatingFileHandler} class that rotates its log files at a
-timed interval. The module already had \class{RotatingFileHandler},
-which rotated logs once the file exceeded a certain size. Both
-classes derive from a new \class{BaseRotatingHandler} class that can
-be used to implement other rotating handlers.
-
-(Changes implemented by Vinay Sajip.)
-
-\item The \module{marshal} module now shares interned strings on unpacking a
-data structure. This may shrink the size of certain pickle strings,
-but the primary effect is to make \file{.pyc} files significantly smaller.
-(Contributed by Martin von~L\"owis.)
-
-\item The \module{nntplib} module's \class{NNTP} class gained
-\method{description()} and \method{descriptions()} methods to retrieve
-newsgroup descriptions for a single group or for a range of groups.
-(Contributed by J\"urgen A. Erhard.)
-
-\item Two new functions were added to the \module{operator} module,
-\function{attrgetter(\var{attr})} and \function{itemgetter(\var{index})}.
-Both functions return callables that take a single argument and return
-the corresponding attribute or item; these callables make excellent
-data extractors when used with \function{map()} or
-\function{sorted()}. For example:
-
-\begin{verbatim}
->>> L = [('c', 2), ('d', 1), ('a', 4), ('b', 3)]
->>> map(operator.itemgetter(0), L)
-['c', 'd', 'a', 'b']
->>> map(operator.itemgetter(1), L)
-[2, 1, 4, 3]
->>> sorted(L, key=operator.itemgetter(1)) # Sort list by second tuple item
-[('d', 1), ('c', 2), ('b', 3), ('a', 4)]
-\end{verbatim}
-
-(Contributed by Raymond Hettinger.)
-
-\item The \module{optparse} module was updated in various ways. The
-module now passes its messages through \function{gettext.gettext()},
-making it possible to internationalize Optik's help and error
-messages. Help messages for options can now include the string
-\code{'\%default'}, which will be replaced by the option's default
-value. (Contributed by Greg Ward.)
-
-\item The long-term plan is to deprecate the \module{rfc822} module
-in some future Python release in favor of the \module{email} package.
-To this end, the \function{email.Utils.formatdate()} function has been
-changed to make it usable as a replacement for
-\function{rfc822.formatdate()}. You may want to write new e-mail
-processing code with this in mind. (Change implemented by Anthony
-Baxter.)
-
-\item A new \function{urandom(\var{n})} function was added to the
-\module{os} module, returning a string containing \var{n} bytes of
-random data. This function provides access to platform-specific
-sources of randomness such as \file{/dev/urandom} on Linux or the
-Windows CryptoAPI. (Contributed by Trevor Perrin.)
-
-\item Another new function: \function{os.path.lexists(\var{path})}
-returns true if the file specified by \var{path} exists, whether or
-not it's a symbolic link. This differs from the existing
-\function{os.path.exists(\var{path})} function, which returns false if
-\var{path} is a symlink that points to a destination that doesn't exist.
-(Contributed by Beni Cherniavsky.)
-
-\item A new \function{getsid()} function was added to the
-\module{posix} module that underlies the \module{os} module.
-(Contributed by J. Raynor.)
-
-\item The \module{poplib} module now supports POP over SSL. (Contributed by
-Hector Urtubia.)
-
-\item The \module{profile} module can now profile C extension functions.
-(Contributed by Nick Bastin.)
-
-\item The \module{random} module has a new method called
- \method{getrandbits(\var{N})} that returns a long integer \var{N}
- bits in length. The existing \method{randrange()} method now uses
- \method{getrandbits()} where appropriate, making generation of
- arbitrarily large random numbers more efficient. (Contributed by
- Raymond Hettinger.)
-
-\item The regular expression language accepted by the \module{re} module
- was extended with simple conditional expressions, written as
- \regexp{(?(\var{group})\var{A}|\var{B})}. \var{group} is either a
- numeric group ID or a group name defined with \regexp{(?P<group>...)}
- earlier in the expression. If the specified group matched, the
- regular expression pattern \var{A} will be tested against the string; if
- the group didn't match, the pattern \var{B} will be used instead.
- (Contributed by Gustavo Niemeyer.)
-
-\item The \module{re} module is also no longer recursive, thanks to a
-massive amount of work by Gustavo Niemeyer. In a recursive regular
-expression engine, certain patterns result in a large amount of C
-stack space being consumed, and it was possible to overflow the stack.
-For example, if you matched a 30000-byte string of \samp{a} characters
-against the expression \regexp{(a|b)+}, one stack frame was consumed
-per character. Python 2.3 tried to check for stack overflow and raise
-a \exception{RuntimeError} exception, but certain patterns could
-sidestep the checking and if you were unlucky Python could segfault.
-Python 2.4's regular expression engine can match this pattern without
-problems.
-
-\item The \module{signal} module now performs tighter error-checking
-on the parameters to the \function{signal.signal()} function. For
-example, you can't set a handler on the \constant{SIGKILL} signal;
-previous versions of Python would quietly accept this, but 2.4 will
-raise a \exception{RuntimeError} exception.
-
-\item Two new functions were added to the \module{socket} module.
-\function{socketpair()} returns a pair of connected sockets and
-\function{getservbyport(\var{port})} looks up the service name for a
-given port number. (Contributed by Dave Cole and Barry Warsaw.)
-
-\item The \function{sys.exitfunc()} function has been deprecated. Code
-should be using the existing \module{atexit} module, which correctly
-handles calling multiple exit functions. Eventually
-\function{sys.exitfunc()} will become a purely internal interface,
-accessed only by \module{atexit}.
-
-\item The \module{tarfile} module now generates GNU-format tar files
-by default. (Contributed by Lars Gustaebel.)
-
-\item The \module{threading} module now has an elegantly simple way to support
-thread-local data. The module contains a \class{local} class whose
-attribute values are local to different threads.
-
-\begin{verbatim}
-import threading
-
-data = threading.local()
-data.number = 42
-data.url = ('www.python.org', 80)
-\end{verbatim}
-
-Other threads can assign and retrieve their own values for the
-\member{number} and \member{url} attributes. You can subclass
-\class{local} to initialize attributes or to add methods.
-(Contributed by Jim Fulton.)
-
-\item The \module{timeit} module now automatically disables periodic
- garbage collection during the timing loop. This change makes
- consecutive timings more comparable. (Contributed by Raymond Hettinger.)
-
-\item The \module{weakref} module now supports a wider variety of objects
- including Python functions, class instances, sets, frozensets, deques,
- arrays, files, sockets, and regular expression pattern objects.
- (Contributed by Raymond Hettinger.)
-
-\item The \module{xmlrpclib} module now supports a multi-call extension for
-transmitting multiple XML-RPC calls in a single HTTP operation.
-(Contributed by Brian Quinlan.)
-
-\item The \module{mpz}, \module{rotor}, and \module{xreadlines} modules have
-been removed.
-
-\end{itemize}
-
-
-%======================================================================
-% whole new modules get described in subsections here
-
-%=====================
-\subsection{cookielib}
-
-The \module{cookielib} library supports client-side handling for HTTP
-cookies, mirroring the \module{Cookie} module's server-side cookie
-support. Cookies are stored in cookie jars; the library transparently
-stores cookies offered by the web server in the cookie jar, and
-fetches the cookie from the jar when connecting to the server. As in
-web browsers, policy objects control whether cookies are accepted or
-not.
-
-In order to store cookies across sessions, two implementations of
-cookie jars are provided: one that stores cookies in the Netscape
-format so applications can use the Mozilla or Lynx cookie files, and
-one that stores cookies in the same format as the Perl libwww library.
-
-\module{urllib2} has been changed to interact with \module{cookielib}:
-\class{HTTPCookieProcessor} manages a cookie jar that is used when
-accessing URLs.
-
-This module was contributed by John J. Lee.
-
-
-% ==================
-\subsection{doctest}
-
-The \module{doctest} module underwent considerable refactoring thanks
-to Edward Loper and Tim Peters. Testing can still be as simple as
-running \function{doctest.testmod()}, but the refactorings allow
-customizing the module's operation in various ways
-
-The new \class{DocTestFinder} class extracts the tests from a given
-object's docstrings:
-
-\begin{verbatim}
-def f (x, y):
- """>>> f(2,2)
-4
->>> f(3,2)
-6
- """
- return x*y
-
-finder = doctest.DocTestFinder()
-
-# Get list of DocTest instances
-tests = finder.find(f)
-\end{verbatim}
-
-The new \class{DocTestRunner} class then runs individual tests and can
-produce a summary of the results:
-
-\begin{verbatim}
-runner = doctest.DocTestRunner()
-for t in tests:
- tried, failed = runner.run(t)
-
-runner.summarize(verbose=1)
-\end{verbatim}
-
-The above example produces the following output:
-
-\begin{verbatim}
-1 items passed all tests:
- 2 tests in f
-2 tests in 1 items.
-2 passed and 0 failed.
-Test passed.
-\end{verbatim}
-
-\class{DocTestRunner} uses an instance of the \class{OutputChecker}
-class to compare the expected output with the actual output. This
-class takes a number of different flags that customize its behaviour;
-ambitious users can also write a completely new subclass of
-\class{OutputChecker}.
-
-The default output checker provides a number of handy features.
-For example, with the \constant{doctest.ELLIPSIS} option flag,
-an ellipsis (\samp{...}) in the expected output matches any substring,
-making it easier to accommodate outputs that vary in minor ways:
-
-\begin{verbatim}
-def o (n):
- """>>> o(1)
-<__main__.C instance at 0x...>
->>>
-"""
-\end{verbatim}
-
-Another special string, \samp{<BLANKLINE>}, matches a blank line:
-
-\begin{verbatim}
-def p (n):
- """>>> p(1)
-<BLANKLINE>
->>>
-"""
-\end{verbatim}
-
-Another new capability is producing a diff-style display of the output
-by specifying the \constant{doctest.REPORT_UDIFF} (unified diffs),
-\constant{doctest.REPORT_CDIFF} (context diffs), or
-\constant{doctest.REPORT_NDIFF} (delta-style) option flags. For example:
-
-\begin{verbatim}
-def g (n):
- """>>> g(4)
-here
-is
-a
-lengthy
->>>"""
- L = 'here is a rather lengthy list of words'.split()
- for word in L[:n]:
- print word
-\end{verbatim}
-
-Running the above function's tests with
-\constant{doctest.REPORT_UDIFF} specified, you get the following output:
-
-\begin{verbatim}
-**********************************************************************
-File ``t.py'', line 15, in g
-Failed example:
- g(4)
-Differences (unified diff with -expected +actual):
- @@ -2,3 +2,3 @@
- is
- a
- -lengthy
- +rather
-**********************************************************************
-\end{verbatim}
-
-
-% ======================================================================
-\section{Build and C API Changes}
-
-Some of the changes to Python's build process and to the C API are:
-
-\begin{itemize}
-
- \item Three new convenience macros were added for common return
- values from extension functions: \csimplemacro{Py_RETURN_NONE},
- \csimplemacro{Py_RETURN_TRUE}, and \csimplemacro{Py_RETURN_FALSE}.
- (Contributed by Brett Cannon.)
-
- \item Another new macro, \csimplemacro{Py_CLEAR(\var{obj})},
- decreases the reference count of \var{obj} and sets \var{obj} to the
- null pointer. (Contributed by Jim Fulton.)
-
- \item A new function, \cfunction{PyTuple_Pack(\var{N}, \var{obj1},
- \var{obj2}, ..., \var{objN})}, constructs tuples from a variable
- length argument list of Python objects. (Contributed by Raymond Hettinger.)
-
- \item A new function, \cfunction{PyDict_Contains(\var{d}, \var{k})},
- implements fast dictionary lookups without masking exceptions raised
- during the look-up process. (Contributed by Raymond Hettinger.)
-
- \item The \csimplemacro{Py_IS_NAN(\var{X})} macro returns 1 if
- its float or double argument \var{X} is a NaN.
- (Contributed by Tim Peters.)
-
- \item C code can avoid unnecessary locking by using the new
- \cfunction{PyEval_ThreadsInitialized()} function to tell
- if any thread operations have been performed. If this function
- returns false, no lock operations are needed.
- (Contributed by Nick Coghlan.)
-
- \item A new function, \cfunction{PyArg_VaParseTupleAndKeywords()},
- is the same as \cfunction{PyArg_ParseTupleAndKeywords()} but takes a
- \ctype{va_list} instead of a number of arguments.
- (Contributed by Greg Chapman.)
-
- \item A new method flag, \constant{METH_COEXISTS}, allows a function
- defined in slots to co-exist with a \ctype{PyCFunction} having the
- same name. This can halve the access time for a method such as
- \method{set.__contains__()}. (Contributed by Raymond Hettinger.)
-
- \item Python can now be built with additional profiling for the
- interpreter itself, intended as an aid to people developing the
- Python core. Providing \longprogramopt{--enable-profiling} to the
- \program{configure} script will let you profile the interpreter with
- \program{gprof}, and providing the \longprogramopt{--with-tsc}
- switch enables profiling using the Pentium's Time-Stamp-Counter
- register. Note that the \longprogramopt{--with-tsc} switch is slightly
- misnamed, because the profiling feature also works on the PowerPC
- platform, though that processor architecture doesn't call that
- register ``the TSC register''. (Contributed by Jeremy Hylton.)
-
- \item The \ctype{tracebackobject} type has been renamed to \ctype{PyTracebackObject}.
-
-\end{itemize}
-
-
-%======================================================================
-\subsection{Port-Specific Changes}
-
-\begin{itemize}
-
-\item The Windows port now builds under MSVC++ 7.1 as well as version 6.
- (Contributed by Martin von~L\"owis.)
-
-\end{itemize}
-
-
-
-%======================================================================
-\section{Porting to Python 2.4}
-
-This section lists previously described changes that may require
-changes to your code:
-
-\begin{itemize}
-
-\item Left shifts and hexadecimal/octal constants that are too
- large no longer trigger a \exception{FutureWarning} and return
- a value limited to 32 or 64 bits; instead they return a long integer.
-
-\item Integer operations will no longer trigger an \exception{OverflowWarning}.
-The \exception{OverflowWarning} warning will disappear in Python 2.5.
-
-\item The \function{zip()} built-in function and \function{itertools.izip()}
- now return an empty list instead of raising a \exception{TypeError}
- exception if called with no arguments.
-
-\item You can no longer compare the \class{date} and \class{datetime}
- instances provided by the \module{datetime} module. Two
- instances of different classes will now always be unequal, and
- relative comparisons (\code{<}, \code{>}) will raise a \exception{TypeError}.
-
-\item \function{dircache.listdir()} now passes exceptions to the caller
- instead of returning empty lists.
-
-\item \function{LexicalHandler.startDTD()} used to receive the public and
- system IDs in the wrong order. This has been corrected; applications
- relying on the wrong order need to be fixed.
-
-\item \function{fcntl.ioctl} now warns if the \var{mutate}
- argument is omitted and relevant.
-
-\item The \module{tarfile} module now generates GNU-format tar files
-by default.
-
-\item Encountering a failure while importing a module no longer leaves
-a partially-initialized module object in \code{sys.modules}.
-
-\item \constant{None} is now a constant; code that binds a new value to
-the name \samp{None} is now a syntax error.
-
-\item The \function{signals.signal()} function now raises a
-\exception{RuntimeError} exception for certain illegal values;
-previously these errors would pass silently. For example, you can no
-longer set a handler on the \constant{SIGKILL} signal.
-
-\end{itemize}
-
-
-%======================================================================
-\section{Acknowledgements \label{acks}}
-
-The author would like to thank the following people for offering
-suggestions, corrections and assistance with various drafts of this
-article: Koray Can, Hye-Shik Chang, Michael Dyck, Raymond Hettinger,
-Brian Hurt, Hamish Lawson, Fredrik Lundh, Sean Reifschneider,
-Sadruddin Rejeb.
-
-\end{document}
diff --git a/Doc/whatsnew/whatsnew25.tex b/Doc/whatsnew/whatsnew25.tex
deleted file mode 100644
index b6bac49..0000000
--- a/Doc/whatsnew/whatsnew25.tex
+++ /dev/null
@@ -1,2539 +0,0 @@
-\documentclass{howto}
-\usepackage{distutils}
-% $Id$
-
-% Fix XXX comments
-
-\title{What's New in Python 2.5}
-\release{1.01}
-\author{A.M. Kuchling}
-\authoraddress{\email{amk@amk.ca}}
-
-\begin{document}
-\maketitle
-\tableofcontents
-
-This article explains the new features in Python 2.5. The final
-release of Python 2.5 is scheduled for August 2006;
-\pep{356} describes the planned release schedule.
-
-The changes in Python 2.5 are an interesting mix of language and
-library improvements. The library enhancements will be more important
-to Python's user community, I think, because several widely-useful
-packages were added. New modules include ElementTree for XML
-processing (section~\ref{module-etree}), the SQLite database module
-(section~\ref{module-sqlite}), and the \module{ctypes} module for
-calling C functions (section~\ref{module-ctypes}).
-
-The language changes are of middling significance. Some pleasant new
-features were added, but most of them aren't features that you'll use
-every day. Conditional expressions were finally added to the language
-using a novel syntax; see section~\ref{pep-308}. The new
-'\keyword{with}' statement will make writing cleanup code easier
-(section~\ref{pep-343}). Values can now be passed into generators
-(section~\ref{pep-342}). Imports are now visible as either absolute
-or relative (section~\ref{pep-328}). Some corner cases of exception
-handling are handled better (section~\ref{pep-341}). All these
-improvements are worthwhile, but they're improvements to one specific
-language feature or another; none of them are broad modifications to
-Python's semantics.
-
-As well as the language and library additions, other improvements and
-bugfixes were made throughout the source tree. A search through the
-SVN change logs finds there were 353 patches applied and 458 bugs
-fixed between Python 2.4 and 2.5. (Both figures are likely to be
-underestimates.)
-
-This article doesn't try to be a complete specification of the new
-features; instead changes are briefly introduced using helpful
-examples. For full details, you should always refer to the
-documentation for Python 2.5 at \url{http://docs.python.org}.
-If you want to understand the complete implementation and design
-rationale, refer to the PEP for a particular new feature.
-
-Comments, suggestions, and error reports for this document are
-welcome; please e-mail them to the author or open a bug in the Python
-bug tracker.
-
-%======================================================================
-\section{PEP 308: Conditional Expressions\label{pep-308}}
-
-For a long time, people have been requesting a way to write
-conditional expressions, which are expressions that return value A or
-value B depending on whether a Boolean value is true or false. A
-conditional expression lets you write a single assignment statement
-that has the same effect as the following:
-
-\begin{verbatim}
-if condition:
- x = true_value
-else:
- x = false_value
-\end{verbatim}
-
-There have been endless tedious discussions of syntax on both
-python-dev and comp.lang.python. A vote was even held that found the
-majority of voters wanted conditional expressions in some form,
-but there was no syntax that was preferred by a clear majority.
-Candidates included C's \code{cond ? true_v : false_v},
-\code{if cond then true_v else false_v}, and 16 other variations.
-
-Guido van~Rossum eventually chose a surprising syntax:
-
-\begin{verbatim}
-x = true_value if condition else false_value
-\end{verbatim}
-
-Evaluation is still lazy as in existing Boolean expressions, so the
-order of evaluation jumps around a bit. The \var{condition}
-expression in the middle is evaluated first, and the \var{true_value}
-expression is evaluated only if the condition was true. Similarly,
-the \var{false_value} expression is only evaluated when the condition
-is false.
-
-This syntax may seem strange and backwards; why does the condition go
-in the \emph{middle} of the expression, and not in the front as in C's
-\code{c ? x : y}? The decision was checked by applying the new syntax
-to the modules in the standard library and seeing how the resulting
-code read. In many cases where a conditional expression is used, one
-value seems to be the 'common case' and one value is an 'exceptional
-case', used only on rarer occasions when the condition isn't met. The
-conditional syntax makes this pattern a bit more obvious:
-
-\begin{verbatim}
-contents = ((doc + '\n') if doc else '')
-\end{verbatim}
-
-I read the above statement as meaning ``here \var{contents} is
-usually assigned a value of \code{doc+'\e n'}; sometimes
-\var{doc} is empty, in which special case an empty string is returned.''
-I doubt I will use conditional expressions very often where there
-isn't a clear common and uncommon case.
-
-There was some discussion of whether the language should require
-surrounding conditional expressions with parentheses. The decision
-was made to \emph{not} require parentheses in the Python language's
-grammar, but as a matter of style I think you should always use them.
-Consider these two statements:
-
-\begin{verbatim}
-# First version -- no parens
-level = 1 if logging else 0
-
-# Second version -- with parens
-level = (1 if logging else 0)
-\end{verbatim}
-
-In the first version, I think a reader's eye might group the statement
-into 'level = 1', 'if logging', 'else 0', and think that the condition
-decides whether the assignment to \var{level} is performed. The
-second version reads better, in my opinion, because it makes it clear
-that the assignment is always performed and the choice is being made
-between two values.
-
-Another reason for including the brackets: a few odd combinations of
-list comprehensions and lambdas could look like incorrect conditional
-expressions. See \pep{308} for some examples. If you put parentheses
-around your conditional expressions, you won't run into this case.
-
-
-\begin{seealso}
-
-\seepep{308}{Conditional Expressions}{PEP written by
-Guido van~Rossum and Raymond D. Hettinger; implemented by Thomas
-Wouters.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 309: Partial Function Application\label{pep-309}}
-
-The \module{functools} module is intended to contain tools for
-functional-style programming.
-
-One useful tool in this module is the \function{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 \code{f(a, b, c)};
-you could create a new function \code{g(b, c)} that was equivalent to
-\code{f(1, b, c)}. This is called ``partial function application''.
-
-\function{partial} takes the arguments
-\code{(\var{function}, \var{arg1}, \var{arg2}, ...
-\var{kwarg1}=\var{value1}, \var{kwarg2}=\var{value2})}. The resulting
-object is callable, so you can just call it to invoke \var{function}
-with the filled-in arguments.
-
-Here's a small but realistic example:
-
-\begin{verbatim}
-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')
-\end{verbatim}
-
-Here's another example, from a program that uses PyGTK. Here a
-context-sensitive pop-up menu is being constructed dynamically. The
-callback provided for the menu option is a partially applied version
-of the \method{open_item()} method, where the first argument has been
-provided.
-
-\begin{verbatim}
-...
-class Application:
- def open_item(self, path):
- ...
- def init (self):
- open_func = functools.partial(self.open_item, item_path)
- popup_menu.append( ("Open", open_func, 1) )
-\end{verbatim}
-
-
-Another function in the \module{functools} module is the
-\function{update_wrapper(\var{wrapper}, \var{wrapped})} function that
-helps you write well-behaved decorators. \function{update_wrapper()}
-copies the name, module, and docstring attribute to a wrapper function
-so that tracebacks inside the wrapped function are easier to
-understand. For example, you might write:
-
-\begin{verbatim}
-def my_decorator(f):
- def wrapper(*args, **kwds):
- print 'Calling decorated function'
- return f(*args, **kwds)
- functools.update_wrapper(wrapper, f)
- return wrapper
-\end{verbatim}
-
-\function{wraps()} is a decorator that can be used inside your own
-decorators to copy the wrapped function's information. An alternate
-version of the previous example would be:
-
-\begin{verbatim}
-def my_decorator(f):
- @functools.wraps(f)
- def wrapper(*args, **kwds):
- print 'Calling decorated function'
- return f(*args, **kwds)
- return wrapper
-\end{verbatim}
-
-\begin{seealso}
-
-\seepep{309}{Partial Function Application}{PEP proposed and written by
-Peter Harris; implemented by Hye-Shik Chang and Nick Coghlan, with
-adaptations by Raymond Hettinger.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 314: Metadata for Python Software Packages v1.1\label{pep-314}}
-
-Some simple dependency support was added to Distutils. The
-\function{setup()} function now has \code{requires}, \code{provides},
-and \code{obsoletes} keyword parameters. When you build a source
-distribution using the \code{sdist} command, the dependency
-information will be recorded in the \file{PKG-INFO} file.
-
-Another new keyword parameter is \code{download_url}, which should be
-set to a URL for the package's source code. This means it's now
-possible to look up an entry in the package index, determine the
-dependencies for a package, and download the required packages.
-
-\begin{verbatim}
-VERSION = '1.0'
-setup(name='PyPackage',
- version=VERSION,
- requires=['numarray', 'zlib (>=1.1.4)'],
- obsoletes=['OldPackage']
- download_url=('http://www.example.com/pypackage/dist/pkg-%s.tar.gz'
- % VERSION),
- )
-\end{verbatim}
-
-Another new enhancement to the Python package index at
-\url{http://cheeseshop.python.org} is storing source and binary
-archives for a package. The new \command{upload} Distutils command
-will upload a package to the repository.
-
-Before a package can be uploaded, you must be able to build a
-distribution using the \command{sdist} Distutils command. Once that
-works, you can run \code{python setup.py upload} to add your package
-to the PyPI archive. Optionally you can GPG-sign the package by
-supplying the \longprogramopt{sign} and
-\longprogramopt{identity} options.
-
-Package uploading was implemented by Martin von~L\"owis and Richard Jones.
-
-\begin{seealso}
-
-\seepep{314}{Metadata for Python Software Packages v1.1}{PEP proposed
-and written by A.M. Kuchling, Richard Jones, and Fred Drake;
-implemented by Richard Jones and Fred Drake.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 328: Absolute and Relative Imports\label{pep-328}}
-
-The simpler part of PEP 328 was implemented in Python 2.4: parentheses
-could now be used to enclose the names imported from a module using
-the \code{from ... import ...} statement, making it easier to import
-many different names.
-
-The more complicated part has been implemented in Python 2.5:
-importing a module can be specified to use absolute or
-package-relative imports. The plan is to move toward making absolute
-imports the default in future versions of Python.
-
-Let's say you have a package directory like this:
-\begin{verbatim}
-pkg/
-pkg/__init__.py
-pkg/main.py
-pkg/string.py
-\end{verbatim}
-
-This defines a package named \module{pkg} containing the
-\module{pkg.main} and \module{pkg.string} submodules.
-
-Consider the code in the \file{main.py} module. What happens if it
-executes the statement \code{import string}? In Python 2.4 and
-earlier, it will first look in the package's directory to perform a
-relative import, finds \file{pkg/string.py}, imports the contents of
-that file as the \module{pkg.string} module, and that module is bound
-to the name \samp{string} in the \module{pkg.main} module's namespace.
-
-That's fine if \module{pkg.string} was what you wanted. But what if
-you wanted Python's standard \module{string} module? There's no clean
-way to ignore \module{pkg.string} and look for the standard module;
-generally you had to look at the contents of \code{sys.modules}, which
-is slightly unclean.
-Holger Krekel's \module{py.std} package provides a tidier way to perform
-imports from the standard library, \code{import py ; py.std.string.join()},
-but that package isn't available on all Python installations.
-
-Reading code which relies on relative imports is also less clear,
-because a reader may be confused about which module, \module{string}
-or \module{pkg.string}, is intended to be used. Python users soon
-learned not to duplicate the names of standard library modules in the
-names of their packages' submodules, but you can't protect against
-having your submodule's name being used for a new module added in a
-future version of Python.
-
-In Python 2.5, you can switch \keyword{import}'s behaviour to
-absolute imports using a \code{from __future__ import absolute_import}
-directive. This absolute-import behaviour will become the default in
-a future version (probably Python 2.7). Once absolute imports
-are the default, \code{import string} will
-always find the standard library's version.
-It's suggested that users should begin using absolute imports as much
-as possible, so it's preferable to begin writing \code{from pkg import
-string} in your code.
-
-Relative imports are still possible by adding a leading period
-to the module name when using the \code{from ... import} form:
-
-\begin{verbatim}
-# Import names from pkg.string
-from .string import name1, name2
-# Import pkg.string
-from . import string
-\end{verbatim}
-
-This imports the \module{string} module relative to the current
-package, so in \module{pkg.main} this will import \var{name1} and
-\var{name2} from \module{pkg.string}. Additional leading periods
-perform the relative import starting from the parent of the current
-package. For example, code in the \module{A.B.C} module can do:
-
-\begin{verbatim}
-from . import D # Imports A.B.D
-from .. import E # Imports A.E
-from ..F import G # Imports A.F.G
-\end{verbatim}
-
-Leading periods cannot be used with the \code{import \var{modname}}
-form of the import statement, only the \code{from ... import} form.
-
-\begin{seealso}
-
-\seepep{328}{Imports: Multi-Line and Absolute/Relative}
-{PEP written by Aahz; implemented by Thomas Wouters.}
-
-\seeurl{http://codespeak.net/py/current/doc/index.html}
-{The py library by Holger Krekel, which contains the \module{py.std} package.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 338: Executing Modules as Scripts\label{pep-338}}
-
-The \programopt{-m} switch added in Python 2.4 to execute a module as
-a script gained a few more abilities. Instead of being implemented in
-C code inside the Python interpreter, the switch now uses an
-implementation in a new module, \module{runpy}.
-
-The \module{runpy} module implements a more sophisticated import
-mechanism so that it's now possible to run modules in a package such
-as \module{pychecker.checker}. The module also supports alternative
-import mechanisms such as the \module{zipimport} module. This means
-you can add a .zip archive's path to \code{sys.path} and then use the
-\programopt{-m} switch to execute code from the archive.
-
-
-\begin{seealso}
-
-\seepep{338}{Executing modules as scripts}{PEP written and
-implemented by Nick Coghlan.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 341: Unified try/except/finally\label{pep-341}}
-
-Until Python 2.5, the \keyword{try} statement came in two
-flavours. You could use a \keyword{finally} block to ensure that code
-is always executed, or one or more \keyword{except} blocks to catch
-specific exceptions. You couldn't combine both \keyword{except} blocks and a
-\keyword{finally} block, because generating the right bytecode for the
-combined version was complicated and it wasn't clear what the
-semantics of the combined statement should be.
-
-Guido van~Rossum spent some time working with Java, which does support the
-equivalent of combining \keyword{except} blocks and a
-\keyword{finally} block, and this clarified what the statement should
-mean. In Python 2.5, you can now write:
-
-\begin{verbatim}
-try:
- block-1 ...
-except Exception1:
- handler-1 ...
-except Exception2:
- handler-2 ...
-else:
- else-block
-finally:
- final-block
-\end{verbatim}
-
-The code in \var{block-1} is executed. If the code raises an
-exception, the various \keyword{except} blocks are tested: if the
-exception is of class \class{Exception1}, \var{handler-1} is executed;
-otherwise if it's of class \class{Exception2}, \var{handler-2} is
-executed, and so forth. If no exception is raised, the
-\var{else-block} is executed.
-
-No matter what happened previously, the \var{final-block} is executed
-once the code block is complete and any raised exceptions handled.
-Even if there's an error in an exception handler or the
-\var{else-block} and a new exception is raised, the
-code in the \var{final-block} is still run.
-
-\begin{seealso}
-
-\seepep{341}{Unifying try-except and try-finally}{PEP written by Georg Brandl;
-implementation by Thomas Lee.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 342: New Generator Features\label{pep-342}}
-
-Python 2.5 adds a simple way to pass values \emph{into} a generator.
-As introduced in Python 2.3, generators only produce 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. Sometimes the ability to pass in some information would be
-useful. Hackish solutions to this include making the generator's code
-look at a global variable and then changing the global variable's
-value, or passing in some mutable object that callers then modify.
-
-To refresh your memory of basic generators, here's a simple example:
-
-\begin{verbatim}
-def counter (maximum):
- i = 0
- while i < maximum:
- yield i
- i += 1
-\end{verbatim}
-
-When you call \code{counter(10)}, the result is an iterator that
-returns the values from 0 up to 9. On encountering the
-\keyword{yield} statement, the iterator returns the provided value and
-suspends the function's execution, preserving the local variables.
-Execution resumes on the following call to the iterator's
-\method{next()} method, picking up after the \keyword{yield} statement.
-
-In Python 2.3, \keyword{yield} was a statement; it didn't return any
-value. In 2.5, \keyword{yield} is now an expression, returning a
-value that can be assigned to a variable or otherwise operated on:
-
-\begin{verbatim}
-val = (yield i)
-\end{verbatim}
-
-I recommend that you always put parentheses around a \keyword{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
-\keyword{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 \code{val = yield i} but have to
-use parentheses when there's an operation, as in \code{val = (yield i)
-+ 12}.)
-
-Values are sent into a generator by calling its
-\method{send(\var{value})} method. The generator's code is then
-resumed and the \keyword{yield} expression returns the specified
-\var{value}. If the regular \method{next()} method is called, the
-\keyword{yield} returns \constant{None}.
-
-Here's the previous example, modified to allow changing the value of
-the internal counter.
-
-\begin{verbatim}
-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
-\end{verbatim}
-
-And here's an example of changing the counter:
-
-\begin{verbatim}
->>> 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
-\end{verbatim}
-
-\keyword{yield} will usually return \constant{None}, so you
-should always check for this case. Don't just use its value in
-expressions unless you're sure that the \method{send()} method
-will be the only method used to resume your generator function.
-
-In addition to \method{send()}, there are two other new methods on
-generators:
-
-\begin{itemize}
-
- \item \method{throw(\var{type}, \var{value}=None,
- \var{traceback}=None)} is used to raise an exception inside the
- generator; the exception is raised by the \keyword{yield} expression
- where the generator's execution is paused.
-
- \item \method{close()} raises a new \exception{GeneratorExit}
- exception inside the generator to terminate the iteration. On
- receiving this exception, the generator's code must either raise
- \exception{GeneratorExit} or \exception{StopIteration}. Catching
- the \exception{GeneratorExit} exception and returning a value is
- illegal and will trigger a \exception{RuntimeError}; if the function
- raises some other exception, that exception is propagated to the
- caller. \method{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 \exception{GeneratorExit} occurs,
- I suggest using a \code{try: ... finally:} suite instead of
- catching \exception{GeneratorExit}.
-
-\end{itemize}
-
-The cumulative effect of these changes is to turn generators from
-one-way producers of information into both producers and consumers.
-
-Generators also become \emph{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 \keyword{return}
-statement), but coroutines can be entered, exited, and resumed at
-many different points (the \keyword{yield} statements). We'll have to
-figure out patterns for using coroutines effectively in Python.
-
-The addition of the \method{close()} method has one side effect that
-isn't obvious. \method{close()} is called when a generator is
-garbage-collected, so this means the generator's code gets one last
-chance to run before the generator is destroyed. This last chance
-means that \code{try...finally} statements in generators can now be
-guaranteed to work; the \keyword{finally} clause will now always get a
-chance to run. The syntactic restriction that you couldn't mix
-\keyword{yield} statements with a \code{try...finally} suite has
-therefore been removed. This seems like a minor bit of language
-trivia, but using generators and \code{try...finally} is actually
-necessary in order to implement the \keyword{with} statement
-described by PEP 343. I'll look at this new statement in the following
-section.
-
-Another even more esoteric effect of this change: previously, the
-\member{gi_frame} attribute of a generator was always a frame object.
-It's now possible for \member{gi_frame} to be \code{None}
-once the generator has been exhausted.
-
-\begin{seealso}
-
-\seepep{342}{Coroutines via Enhanced Generators}{PEP written by
-Guido van~Rossum and Phillip J. Eby;
-implemented by Phillip J. Eby. Includes examples of
-some fancier uses of generators as coroutines.
-
-Earlier versions of these features were proposed in
-\pep{288} by Raymond Hettinger and \pep{325} by Samuele Pedroni.
-}
-
-\seeurl{http://en.wikipedia.org/wiki/Coroutine}{The Wikipedia entry for
-coroutines.}
-
-\seeurl{http://www.sidhe.org/\~{}dan/blog/archives/000178.html}{An
-explanation of coroutines from a Perl point of view, written by Dan
-Sugalski.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 343: The 'with' statement\label{pep-343}}
-
-The '\keyword{with}' statement clarifies code that previously would
-use \code{try...finally} blocks to ensure that clean-up code is
-executed. In this section, I'll discuss the statement as it will
-commonly be used. In the next section, I'll examine the
-implementation details and show how to write objects for use with this
-statement.
-
-The '\keyword{with}' statement is a new control-flow structure whose
-basic structure is:
-
-\begin{verbatim}
-with expression [as variable]:
- with-block
-\end{verbatim}
-
-The expression is evaluated, and it should result in an object that
-supports the context management protocol (that is, has \method{__enter__()}
-and \method{__exit__()} methods.
-
-The object's \method{__enter__()} is called before \var{with-block} is
-executed and therefore can run set-up code. It also may return a value
-that is bound to the name \var{variable}, if given. (Note carefully
-that \var{variable} is \emph{not} assigned the result of \var{expression}.)
-
-After execution of the \var{with-block} is finished, the object's
-\method{__exit__()} method is called, even if the block raised an exception,
-and can therefore run clean-up code.
-
-To enable the statement in Python 2.5, you need to add the following
-directive to your module:
-
-\begin{verbatim}
-from __future__ import with_statement
-\end{verbatim}
-
-The statement will always be enabled in Python 2.6.
-
-Some standard Python objects now support the context management
-protocol and can be used with the '\keyword{with}' statement. File
-objects are one example:
-
-\begin{verbatim}
-with open('/etc/passwd', 'r') as f:
- for line in f:
- print line
- ... more processing code ...
-\end{verbatim}
-
-After this statement has executed, the file object in \var{f} will
-have been automatically closed, even if the \keyword{for} loop
-raised an exception part-way through the block.
-
-\note{In this case, \var{f} is the same object created by
- \function{open()}, because \method{file.__enter__()} returns
- \var{self}.}
-
-The \module{threading} module's locks and condition variables
-also support the '\keyword{with}' statement:
-
-\begin{verbatim}
-lock = threading.Lock()
-with lock:
- # Critical section of code
- ...
-\end{verbatim}
-
-The lock is acquired before the block is executed and always released once
-the block is complete.
-
-The new \function{localcontext()} function in the \module{decimal} module
-makes it easy to save and restore the current decimal context, which
-encapsulates the desired precision and rounding characteristics for
-computations:
-
-\begin{verbatim}
-from decimal import Decimal, Context, localcontext
-
-# Displays with default precision of 28 digits
-v = Decimal('578')
-print v.sqrt()
-
-with localcontext(Context(prec=16)):
- # All code in this block uses a precision of 16 digits.
- # The original context is restored on exiting the block.
- print v.sqrt()
-\end{verbatim}
-
-\subsection{Writing Context Managers\label{context-managers}}
-
-Under the hood, the '\keyword{with}' statement is fairly complicated.
-Most people will only use '\keyword{with}' in company with existing
-objects and don't need to know these details, so you can skip the rest
-of this section if you like. Authors of new objects will need to
-understand the details of the underlying implementation and should
-keep reading.
-
-A high-level explanation of the context management protocol is:
-
-\begin{itemize}
-
-\item The expression is evaluated and should result in an object
-called a ``context manager''. The context manager must have
-\method{__enter__()} and \method{__exit__()} methods.
-
-\item The context manager's \method{__enter__()} method is called. The value
-returned is assigned to \var{VAR}. If no \code{'as \var{VAR}'} clause
-is present, the value is simply discarded.
-
-\item The code in \var{BLOCK} is executed.
-
-\item If \var{BLOCK} raises an exception, the
-\method{__exit__(\var{type}, \var{value}, \var{traceback})} is called
-with the exception details, the same values returned by
-\function{sys.exc_info()}. The method's return value controls whether
-the exception is re-raised: any false value re-raises the exception,
-and \code{True} will result in suppressing it. You'll only rarely
-want to suppress the exception, because if you do
-the author of the code containing the
-'\keyword{with}' statement will never realize anything went wrong.
-
-\item If \var{BLOCK} didn't raise an exception,
-the \method{__exit__()} method is still called,
-but \var{type}, \var{value}, and \var{traceback} are all \code{None}.
-
-\end{itemize}
-
-Let's think through an example. I won't present detailed code but
-will only sketch the methods necessary for a database that supports
-transactions.
-
-(For people unfamiliar with database terminology: a set of changes to
-the database are grouped into a transaction. Transactions can be
-either committed, meaning that all the changes are written into the
-database, or rolled back, meaning that the changes are all discarded
-and the database is unchanged. See any database textbook for more
-information.)
-
-Let's assume there's an object representing a database connection.
-Our goal will be to let the user write code like this:
-
-\begin{verbatim}
-db_connection = DatabaseConnection()
-with db_connection as cursor:
- cursor.execute('insert into ...')
- cursor.execute('delete from ...')
- # ... more operations ...
-\end{verbatim}
-
-The transaction should be committed if the code in the block
-runs flawlessly or rolled back if there's an exception.
-Here's the basic interface
-for \class{DatabaseConnection} that I'll assume:
-
-\begin{verbatim}
-class DatabaseConnection:
- # Database interface
- def cursor (self):
- "Returns a cursor object and starts a new transaction"
- def commit (self):
- "Commits current transaction"
- def rollback (self):
- "Rolls back current transaction"
-\end{verbatim}
-
-The \method {__enter__()} method is pretty easy, having only to start
-a new transaction. For this application the resulting cursor object
-would be a useful result, so the method will return it. The user can
-then add \code{as cursor} to their '\keyword{with}' statement to bind
-the cursor to a variable name.
-
-\begin{verbatim}
-class DatabaseConnection:
- ...
- def __enter__ (self):
- # Code to start a new transaction
- cursor = self.cursor()
- return cursor
-\end{verbatim}
-
-The \method{__exit__()} method is the most complicated because it's
-where most of the work has to be done. The method has to check if an
-exception occurred. If there was no exception, the transaction is
-committed. The transaction is rolled back if there was an exception.
-
-In the code below, execution will just fall off the end of the
-function, returning the default value of \code{None}. \code{None} is
-false, so the exception will be re-raised automatically. If you
-wished, you could be more explicit and add a \keyword{return}
-statement at the marked location.
-
-\begin{verbatim}
-class DatabaseConnection:
- ...
- def __exit__ (self, type, value, tb):
- if tb is None:
- # No exception, so commit
- self.commit()
- else:
- # Exception occurred, so rollback.
- self.rollback()
- # return False
-\end{verbatim}
-
-
-\subsection{The contextlib module\label{module-contextlib}}
-
-The new \module{contextlib} module provides some functions and a
-decorator that are useful for writing objects for use with the
-'\keyword{with}' statement.
-
-The decorator is called \function{contextmanager}, and lets you write
-a single generator function instead of defining a new class. The generator
-should yield exactly one value. The code up to the \keyword{yield}
-will be executed as the \method{__enter__()} method, and the value
-yielded will be the method's return value that will get bound to the
-variable in the '\keyword{with}' statement's \keyword{as} clause, if
-any. The code after the \keyword{yield} will be executed in the
-\method{__exit__()} method. Any exception raised in the block will be
-raised by the \keyword{yield} statement.
-
-Our database example from the previous section could be written
-using this decorator as:
-
-\begin{verbatim}
-from contextlib import contextmanager
-
-@contextmanager
-def db_transaction (connection):
- cursor = connection.cursor()
- try:
- yield cursor
- except:
- connection.rollback()
- raise
- else:
- connection.commit()
-
-db = DatabaseConnection()
-with db_transaction(db) as cursor:
- ...
-\end{verbatim}
-
-The \module{contextlib} module also has a \function{nested(\var{mgr1},
-\var{mgr2}, ...)} function that combines a number of context managers so you
-don't need to write nested '\keyword{with}' statements. In this
-example, the single '\keyword{with}' statement both starts a database
-transaction and acquires a thread lock:
-
-\begin{verbatim}
-lock = threading.Lock()
-with nested (db_transaction(db), lock) as (cursor, locked):
- ...
-\end{verbatim}
-
-Finally, the \function{closing(\var{object})} function
-returns \var{object} so that it can be bound to a variable,
-and calls \code{\var{object}.close()} at the end of the block.
-
-\begin{verbatim}
-import urllib, sys
-from contextlib import closing
-
-with closing(urllib.urlopen('http://www.yahoo.com')) as f:
- for line in f:
- sys.stdout.write(line)
-\end{verbatim}
-
-\begin{seealso}
-
-\seepep{343}{The ``with'' statement}{PEP written by Guido van~Rossum
-and Nick Coghlan; implemented by Mike Bland, Guido van~Rossum, and
-Neal Norwitz. The PEP shows the code generated for a '\keyword{with}'
-statement, which can be helpful in learning how the statement works.}
-
-\seeurl{../lib/module-contextlib.html}{The documentation
-for the \module{contextlib} module.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 352: Exceptions as New-Style Classes\label{pep-352}}
-
-Exception classes can now be new-style classes, not just classic
-classes, and the built-in \exception{Exception} class and all the
-standard built-in exceptions (\exception{NameError},
-\exception{ValueError}, etc.) are now new-style classes.
-
-The inheritance hierarchy for exceptions has been rearranged a bit.
-In 2.5, the inheritance relationships are:
-
-\begin{verbatim}
-BaseException # New in Python 2.5
-|- KeyboardInterrupt
-|- SystemExit
-|- Exception
- |- (all other current built-in exceptions)
-\end{verbatim}
-
-This rearrangement was done because people often want to catch all
-exceptions that indicate program errors. \exception{KeyboardInterrupt} and
-\exception{SystemExit} aren't errors, though, and usually represent an explicit
-action such as the user hitting Control-C or code calling
-\function{sys.exit()}. A bare \code{except:} will catch all exceptions,
-so you commonly need to list \exception{KeyboardInterrupt} and
-\exception{SystemExit} in order to re-raise them. The usual pattern is:
-
-\begin{verbatim}
-try:
- ...
-except (KeyboardInterrupt, SystemExit):
- raise
-except:
- # Log error...
- # Continue running program...
-\end{verbatim}
-
-In Python 2.5, you can now write \code{except Exception} to achieve
-the same result, catching all the exceptions that usually indicate errors
-but leaving \exception{KeyboardInterrupt} and
-\exception{SystemExit} alone. As in previous versions,
-a bare \code{except:} still catches all exceptions.
-
-The goal for Python 3.0 is to require any class raised as an exception
-to derive from \exception{BaseException} or some descendant of
-\exception{BaseException}, and future releases in the
-Python 2.x series may begin to enforce this constraint. Therefore, I
-suggest you begin making all your exception classes derive from
-\exception{Exception} now. It's been suggested that the bare
-\code{except:} form should be removed in Python 3.0, but Guido van~Rossum
-hasn't decided whether to do this or not.
-
-Raising of strings as exceptions, as in the statement \code{raise
-"Error occurred"}, is deprecated in Python 2.5 and will trigger a
-warning. The aim is to be able to remove the string-exception feature
-in a few releases.
-
-
-\begin{seealso}
-
-\seepep{352}{Required Superclass for Exceptions}{PEP written by
-Brett Cannon and Guido van~Rossum; implemented by Brett Cannon.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 353: Using ssize_t as the index type\label{pep-353}}
-
-A wide-ranging change to Python's C API, using a new
-\ctype{Py_ssize_t} type definition instead of \ctype{int},
-will permit the interpreter to handle more data on 64-bit platforms.
-This change doesn't affect Python's capacity on 32-bit platforms.
-
-Various pieces of the Python interpreter used C's \ctype{int} type to
-store sizes or counts; for example, the number of items in a list or
-tuple were stored in an \ctype{int}. The C compilers for most 64-bit
-platforms still define \ctype{int} as a 32-bit type, so that meant
-that lists could only hold up to \code{2**31 - 1} = 2147483647 items.
-(There are actually a few different programming models that 64-bit C
-compilers can use -- see
-\url{http://www.unix.org/version2/whatsnew/lp64_wp.html} for a
-discussion -- but the most commonly available model leaves \ctype{int}
-as 32 bits.)
-
-A limit of 2147483647 items doesn't really matter on a 32-bit platform
-because you'll run out of memory before hitting the length limit.
-Each list item requires space for a pointer, which is 4 bytes, plus
-space for a \ctype{PyObject} representing the item. 2147483647*4 is
-already more bytes than a 32-bit address space can contain.
-
-It's possible to address that much memory on a 64-bit platform,
-however. The pointers for a list that size would only require 16~GiB
-of space, so it's not unreasonable that Python programmers might
-construct lists that large. Therefore, the Python interpreter had to
-be changed to use some type other than \ctype{int}, and this will be a
-64-bit type on 64-bit platforms. The change will cause
-incompatibilities on 64-bit machines, so it was deemed worth making
-the transition now, while the number of 64-bit users is still
-relatively small. (In 5 or 10 years, we may \emph{all} be on 64-bit
-machines, and the transition would be more painful then.)
-
-This change most strongly affects authors of C extension modules.
-Python strings and container types such as lists and tuples
-now use \ctype{Py_ssize_t} to store their size.
-Functions such as \cfunction{PyList_Size()}
-now return \ctype{Py_ssize_t}. Code in extension modules
-may therefore need to have some variables changed to
-\ctype{Py_ssize_t}.
-
-The \cfunction{PyArg_ParseTuple()} and \cfunction{Py_BuildValue()} functions
-have a new conversion code, \samp{n}, for \ctype{Py_ssize_t}.
-\cfunction{PyArg_ParseTuple()}'s \samp{s\#} and \samp{t\#} still output
-\ctype{int} by default, but you can define the macro
-\csimplemacro{PY_SSIZE_T_CLEAN} before including \file{Python.h}
-to make them return \ctype{Py_ssize_t}.
-
-\pep{353} has a section on conversion guidelines that
-extension authors should read to learn about supporting 64-bit
-platforms.
-
-\begin{seealso}
-
-\seepep{353}{Using ssize_t as the index type}{PEP written and implemented by Martin von~L\"owis.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{PEP 357: The '__index__' method\label{pep-357}}
-
-The NumPy developers had a problem that could only be solved by adding
-a new special method, \method{__index__}. When using slice notation,
-as in \code{[\var{start}:\var{stop}:\var{step}]}, the values of the
-\var{start}, \var{stop}, and \var{step} indexes must all be either
-integers or long integers. NumPy defines a variety of specialized
-integer types corresponding to unsigned and signed integers of 8, 16,
-32, and 64 bits, but there was no way to signal that these types could
-be used as slice indexes.
-
-Slicing can't just use the existing \method{__int__} method because
-that method is also used to implement coercion to integers. If
-slicing used \method{__int__}, floating-point numbers would also
-become legal slice indexes and that's clearly an undesirable
-behaviour.
-
-Instead, a new special method called \method{__index__} was added. It
-takes no arguments and returns an integer giving the slice index to
-use. For example:
-
-\begin{verbatim}
-class C:
- def __index__ (self):
- return self.value
-\end{verbatim}
-
-The return value must be either a Python integer or long integer.
-The interpreter will check that the type returned is correct, and
-raises a \exception{TypeError} if this requirement isn't met.
-
-A corresponding \member{nb_index} slot was added to the C-level
-\ctype{PyNumberMethods} structure to let C extensions implement this
-protocol. \cfunction{PyNumber_Index(\var{obj})} can be used in
-extension code to call the \method{__index__} function and retrieve
-its result.
-
-\begin{seealso}
-
-\seepep{357}{Allowing Any Object to be Used for Slicing}{PEP written
-and implemented by Travis Oliphant.}
-
-\end{seealso}
-
-
-%======================================================================
-\section{Other Language Changes\label{other-lang}}
-
-Here are all of the changes that Python 2.5 makes to the core Python
-language.
-
-\begin{itemize}
-
-\item The \class{dict} type has a new hook for letting subclasses
-provide a default value when a key isn't contained in the dictionary.
-When a key isn't found, the dictionary's
-\method{__missing__(\var{key})}
-method will be called. This hook is used to implement
-the new \class{defaultdict} class in the \module{collections}
-module. The following example defines a dictionary
-that returns zero for any missing key:
-
-\begin{verbatim}
-class zerodict (dict):
- def __missing__ (self, key):
- return 0
-
-d = zerodict({1:1, 2:2})
-print d[1], d[2] # Prints 1, 2
-print d[3], d[4] # Prints 0, 0
-\end{verbatim}
-
-\item Both 8-bit and Unicode strings have new \method{partition(sep)}
-and \method{rpartition(sep)} methods that simplify a common use case.
-
-The \method{find(S)} method is often used to get an index which is
-then used to slice the string and obtain the pieces that are before
-and after the separator.
-\method{partition(sep)} condenses this
-pattern into a single method call that returns a 3-tuple containing
-the substring before the separator, the separator itself, and the
-substring after the separator. If the separator isn't found, the
-first element of the tuple is the entire string and the other two
-elements are empty. \method{rpartition(sep)} also returns a 3-tuple
-but starts searching from the end of the string; the \samp{r} stands
-for 'reverse'.
-
-Some examples:
-
-\begin{verbatim}
->>> ('http://www.python.org').partition('://')
-('http', '://', 'www.python.org')
->>> ('file:/usr/share/doc/index.html').partition('://')
-('file:/usr/share/doc/index.html', '', '')
->>> (u'Subject: a quick question').partition(':')
-(u'Subject', u':', u' a quick question')
->>> 'www.python.org'.rpartition('.')
-('www.python', '.', 'org')
->>> 'www.python.org'.rpartition(':')
-('', '', 'www.python.org')
-\end{verbatim}
-
-(Implemented by Fredrik Lundh following a suggestion by Raymond Hettinger.)
-
-\item The \method{startswith()} and \method{endswith()} methods
-of string types now accept tuples of strings to check for.
-
-\begin{verbatim}
-def is_image_file (filename):
- return filename.endswith(('.gif', '.jpg', '.tiff'))
-\end{verbatim}
-
-(Implemented by Georg Brandl following a suggestion by Tom Lynn.)
-% RFE #1491485
-
-\item The \function{min()} and \function{max()} built-in functions
-gained a \code{key} keyword parameter analogous to the \code{key}
-argument for \method{sort()}. This parameter supplies a function that
-takes a single argument and is called for every value in the list;
-\function{min()}/\function{max()} will return the element with the
-smallest/largest return value from this function.
-For example, to find the longest string in a list, you can do:
-
-\begin{verbatim}
-L = ['medium', 'longest', 'short']
-# Prints 'longest'
-print max(L, key=len)
-# Prints 'short', because lexicographically 'short' has the largest value
-print max(L)
-\end{verbatim}
-
-(Contributed by Steven Bethard and Raymond Hettinger.)
-
-\item Two new built-in functions, \function{any()} and
-\function{all()}, evaluate whether an iterator contains any true or
-false values. \function{any()} returns \constant{True} if any value
-returned by the iterator is true; otherwise it will return
-\constant{False}. \function{all()} returns \constant{True} only if
-all of the values returned by the iterator evaluate as true.
-(Suggested by Guido van~Rossum, and implemented by Raymond Hettinger.)
-
-\item The result of a class's \method{__hash__()} method can now
-be either a long integer or a regular integer. If a long integer is
-returned, the hash of that value is taken. In earlier versions the
-hash value was required to be a regular integer, but in 2.5 the
-\function{id()} built-in was changed to always return non-negative
-numbers, and users often seem to use \code{id(self)} in
-\method{__hash__()} methods (though this is discouraged).
-% Bug #1536021
-
-\item ASCII is now the default encoding for modules. It's now
-a syntax error if a module contains string literals with 8-bit
-characters but doesn't have an encoding declaration. In Python 2.4
-this triggered a warning, not a syntax error. See \pep{263}
-for how to declare a module's encoding; for example, you might add
-a line like this near the top of the source file:
-
-\begin{verbatim}
-# -*- coding: latin1 -*-
-\end{verbatim}
-
-\item A new warning, \class{UnicodeWarning}, is triggered when
-you attempt to compare a Unicode string and an 8-bit string
-that can't be converted to Unicode using the default ASCII encoding.
-The result of the comparison is false:
-
-\begin{verbatim}
->>> chr(128) == unichr(128) # Can't convert chr(128) to Unicode
-__main__:1: UnicodeWarning: Unicode equal comparison failed
- to convert both arguments to Unicode - interpreting them
- as being unequal
-False
->>> chr(127) == unichr(127) # chr(127) can be converted
-True
-\end{verbatim}
-
-Previously this would raise a \class{UnicodeDecodeError} exception,
-but in 2.5 this could result in puzzling problems when accessing a
-dictionary. If you looked up \code{unichr(128)} and \code{chr(128)}
-was being used as a key, you'd get a \class{UnicodeDecodeError}
-exception. Other changes in 2.5 resulted in this exception being
-raised instead of suppressed by the code in \file{dictobject.c} that
-implements dictionaries.
-
-Raising an exception for such a comparison is strictly correct, but
-the change might have broken code, so instead
-\class{UnicodeWarning} was introduced.
-
-(Implemented by Marc-Andr\'e Lemburg.)
-
-\item One error that Python programmers sometimes make is forgetting
-to include an \file{__init__.py} module in a package directory.
-Debugging this mistake can be confusing, and usually requires running
-Python with the \programopt{-v} switch to log all the paths searched.
-In Python 2.5, a new \exception{ImportWarning} warning is triggered when
-an import would have picked up a directory as a package but no
-\file{__init__.py} was found. This warning is silently ignored by default;
-provide the \programopt{-Wd} option when running the Python executable
-to display the warning message.
-(Implemented by Thomas Wouters.)
-
-\item The list of base classes in a class definition can now be empty.
-As an example, this is now legal:
-
-\begin{verbatim}
-class C():
- pass
-\end{verbatim}
-(Implemented by Brett Cannon.)
-
-\end{itemize}
-
-
-%======================================================================
-\subsection{Interactive Interpreter Changes\label{interactive}}
-
-In the interactive interpreter, \code{quit} and \code{exit}
-have long been strings so that new users get a somewhat helpful message
-when they try to quit:
-
-\begin{verbatim}
->>> quit
-'Use Ctrl-D (i.e. EOF) to exit.'
-\end{verbatim}
-
-In Python 2.5, \code{quit} and \code{exit} are now objects that still
-produce string representations of themselves, but are also callable.
-Newbies who try \code{quit()} or \code{exit()} will now exit the
-interpreter as they expect. (Implemented by Georg Brandl.)
-
-The Python executable now accepts the standard long options
-\longprogramopt{help} and \longprogramopt{version}; on Windows,
-it also accepts the \programopt{/?} option for displaying a help message.
-(Implemented by Georg Brandl.)
-
-
-%======================================================================
-\subsection{Optimizations\label{opts}}
-
-Several of the optimizations were developed at the NeedForSpeed
-sprint, an event held in Reykjavik, Iceland, from May 21--28 2006.
-The sprint focused on speed enhancements to the CPython implementation
-and was funded by EWT LLC with local support from CCP Games. Those
-optimizations added at this sprint are specially marked in the
-following list.
-
-\begin{itemize}
-
-\item When they were introduced
-in Python 2.4, the built-in \class{set} and \class{frozenset} types
-were built on top of Python's dictionary type.
-In 2.5 the internal data structure has been customized for implementing sets,
-and as a result sets will use a third less memory and are somewhat faster.
-(Implemented by Raymond Hettinger.)
-
-\item The speed of some Unicode operations, such as finding
-substrings, string splitting, and character map encoding and decoding,
-has been improved. (Substring search and splitting improvements were
-added by Fredrik Lundh and Andrew Dalke at the NeedForSpeed
-sprint. Character maps were improved by Walter D\"orwald and
-Martin von~L\"owis.)
-% Patch 1313939, 1359618
-
-\item The \function{long(\var{str}, \var{base})} function is now
-faster on long digit strings because fewer intermediate results are
-calculated. The peak is for strings of around 800--1000 digits where
-the function is 6 times faster.
-(Contributed by Alan McIntyre and committed at the NeedForSpeed sprint.)
-% Patch 1442927
-
-\item It's now illegal to mix iterating over a file
-with \code{for line in \var{file}} and calling
-the file object's \method{read()}/\method{readline()}/\method{readlines()}
-methods. Iteration uses an internal buffer and the
-\method{read*()} methods don't use that buffer.
-Instead they would return the data following the buffer, causing the
-data to appear out of order. Mixing iteration and these methods will
-now trigger a \exception{ValueError} from the \method{read*()} method.
-(Implemented by Thomas Wouters.)
-% Patch 1397960
-
-\item The \module{struct} module now compiles structure format
-strings into an internal representation and caches this
-representation, yielding a 20\% speedup. (Contributed by Bob Ippolito
-at the NeedForSpeed sprint.)
-
-\item The \module{re} module got a 1 or 2\% speedup by switching to
-Python's allocator functions instead of the system's
-\cfunction{malloc()} and \cfunction{free()}.
-(Contributed by Jack Diederich at the NeedForSpeed sprint.)
-
-\item The code generator's peephole optimizer now performs
-simple constant folding in expressions. If you write something like
-\code{a = 2+3}, the code generator will do the arithmetic and produce
-code corresponding to \code{a = 5}. (Proposed and implemented
-by Raymond Hettinger.)
-
-\item Function calls are now faster because code objects now keep
-the most recently finished frame (a ``zombie frame'') in an internal
-field of the code object, reusing it the next time the code object is
-invoked. (Original patch by Michael Hudson, modified by Armin Rigo
-and Richard Jones; committed at the NeedForSpeed sprint.)
-% Patch 876206
-
-Frame objects are also slightly smaller, which may improve cache locality
-and reduce memory usage a bit. (Contributed by Neal Norwitz.)
-% Patch 1337051
-
-\item Python's built-in exceptions are now new-style classes, a change
-that speeds up instantiation considerably. Exception handling in
-Python 2.5 is therefore about 30\% faster than in 2.4.
-(Contributed by Richard Jones, Georg Brandl and Sean Reifschneider at
-the NeedForSpeed sprint.)
-
-\item Importing now caches the paths tried, recording whether
-they exist or not so that the interpreter makes fewer
-\cfunction{open()} and \cfunction{stat()} calls on startup.
-(Contributed by Martin von~L\"owis and Georg Brandl.)
-% Patch 921466
-
-\end{itemize}
-
-
-%======================================================================
-\section{New, Improved, and Removed Modules\label{modules}}
-
-The standard library received many enhancements and bug fixes in
-Python 2.5. Here's a partial list of the most notable changes, sorted
-alphabetically by module name. Consult the \file{Misc/NEWS} file in
-the source tree for a more complete list of changes, or look through
-the SVN logs for all the details.
-
-\begin{itemize}
-
-\item The \module{audioop} module now supports the a-LAW encoding,
-and the code for u-LAW encoding has been improved. (Contributed by
-Lars Immisch.)
-
-\item The \module{codecs} module gained support for incremental
-codecs. The \function{codec.lookup()} function now
-returns a \class{CodecInfo} instance instead of a tuple.
-\class{CodecInfo} instances behave like a 4-tuple to preserve backward
-compatibility but also have the attributes \member{encode},
-\member{decode}, \member{incrementalencoder}, \member{incrementaldecoder},
-\member{streamwriter}, and \member{streamreader}. Incremental codecs
-can receive input and produce output in multiple chunks; the output is
-the same as if the entire input was fed to the non-incremental codec.
-See the \module{codecs} module documentation for details.
-(Designed and implemented by Walter D\"orwald.)
-% Patch 1436130
-
-\item The \module{collections} module gained a new type,
-\class{defaultdict}, that subclasses the standard \class{dict}
-type. The new type mostly behaves like a dictionary but constructs a
-default value when a key isn't present, automatically adding it to the
-dictionary for the requested key value.
-
-The first argument to \class{defaultdict}'s constructor is a factory
-function that gets called whenever a key is requested but not found.
-This factory function receives no arguments, so you can use built-in
-type constructors such as \function{list()} or \function{int()}. For
-example,
-you can make an index of words based on their initial letter like this:
-
-\begin{verbatim}
-words = """Nel mezzo del cammin di nostra vita
-mi ritrovai per una selva oscura
-che la diritta via era smarrita""".lower().split()
-
-index = defaultdict(list)
-
-for w in words:
- init_letter = w[0]
- index[init_letter].append(w)
-\end{verbatim}
-
-Printing \code{index} results in the following output:
-
-\begin{verbatim}
-defaultdict(<type 'list'>, {'c': ['cammin', 'che'], 'e': ['era'],
- 'd': ['del', 'di', 'diritta'], 'm': ['mezzo', 'mi'],
- 'l': ['la'], 'o': ['oscura'], 'n': ['nel', 'nostra'],
- 'p': ['per'], 's': ['selva', 'smarrita'],
- 'r': ['ritrovai'], 'u': ['una'], 'v': ['vita', 'via']}
-\end{verbatim}
-
-(Contributed by Guido van~Rossum.)
-
-\item The \class{deque} double-ended queue type supplied by the
-\module{collections} module now has a \method{remove(\var{value})}
-method that removes the first occurrence of \var{value} in the queue,
-raising \exception{ValueError} if the value isn't found.
-(Contributed by Raymond Hettinger.)
-
-\item New module: The \module{contextlib} module contains helper functions for use
-with the new '\keyword{with}' statement. See
-section~\ref{module-contextlib} for more about this module.
-
-\item New module: The \module{cProfile} module is a C implementation of
-the existing \module{profile} module that has much lower overhead.
-The module's interface is the same as \module{profile}: you run
-\code{cProfile.run('main()')} to profile a function, can save profile
-data to a file, etc. It's not yet known if the Hotshot profiler,
-which is also written in C but doesn't match the \module{profile}
-module's interface, will continue to be maintained in future versions
-of Python. (Contributed by Armin Rigo.)
-
-Also, the \module{pstats} module for analyzing the data measured by
-the profiler now supports directing the output to any file object
-by supplying a \var{stream} argument to the \class{Stats} constructor.
-(Contributed by Skip Montanaro.)
-
-\item The \module{csv} module, which parses files in
-comma-separated value format, received several enhancements and a
-number of bugfixes. You can now set the maximum size in bytes of a
-field by calling the \method{csv.field_size_limit(\var{new_limit})}
-function; omitting the \var{new_limit} argument will return the
-currently-set limit. The \class{reader} class now has a
-\member{line_num} attribute that counts the number of physical lines
-read from the source; records can span multiple physical lines, so
-\member{line_num} is not the same as the number of records read.
-
-The CSV parser is now stricter about 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 that
-contained carriage return characters within fields, so the code 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 that preserves the
-newline characters.
-
-(Contributed by Skip Montanaro and Andrew McNamara.)
-
-\item The \class{datetime} class in the \module{datetime}
-module now has a \method{strptime(\var{string}, \var{format})}
-method for parsing date strings, contributed by Josh Spoerri.
-It uses the same format characters as \function{time.strptime()} and
-\function{time.strftime()}:
-
-\begin{verbatim}
-from datetime import datetime
-
-ts = datetime.strptime('10:13:15 2006-03-07',
- '%H:%M:%S %Y-%m-%d')
-\end{verbatim}
-
-\item The \method{SequenceMatcher.get_matching_blocks()} method
-in the \module{difflib} module now guarantees to return a minimal list
-of blocks describing matching subsequences. Previously, the algorithm would
-occasionally break a block of matching elements into two list entries.
-(Enhancement by Tim Peters.)
-
-\item The \module{doctest} module gained a \code{SKIP} option that
-keeps an example from being executed at all. This is intended for
-code snippets that are usage examples intended for the reader and
-aren't actually test cases.
-
-An \var{encoding} parameter was added to the \function{testfile()}
-function and the \class{DocFileSuite} class to specify the file's
-encoding. This makes it easier to use non-ASCII characters in
-tests contained within a docstring. (Contributed by Bjorn Tillenius.)
-% Patch 1080727
-
-\item The \module{email} package has been updated to version 4.0.
-% XXX need to provide some more detail here
-(Contributed by Barry Warsaw.)
-
-\item The \module{fileinput} module was made more flexible.
-Unicode filenames are now supported, and a \var{mode} parameter that
-defaults to \code{"r"} was added to the
-\function{input()} function to allow opening files in binary or
-universal-newline mode. Another new parameter, \var{openhook},
-lets you use a function other than \function{open()}
-to open the input files. Once you're iterating over
-the set of files, the \class{FileInput} object's new
-\method{fileno()} returns the file descriptor for the currently opened file.
-(Contributed by Georg Brandl.)
-
-\item In the \module{gc} module, the new \function{get_count()} function
-returns a 3-tuple containing the current collection counts for the
-three GC generations. This is accounting information for the garbage
-collector; when these counts reach a specified threshold, a garbage
-collection sweep will be made. The existing \function{gc.collect()}
-function now takes an optional \var{generation} argument of 0, 1, or 2
-to specify which generation to collect.
-(Contributed by Barry Warsaw.)
-
-\item The \function{nsmallest()} and
-\function{nlargest()} functions in the \module{heapq} module
-now support a \code{key} keyword parameter similar to the one
-provided by the \function{min()}/\function{max()} functions
-and the \method{sort()} methods. For example:
-
-\begin{verbatim}
->>> import heapq
->>> L = ["short", 'medium', 'longest', 'longer still']
->>> heapq.nsmallest(2, L) # Return two lowest elements, lexicographically
-['longer still', 'longest']
->>> heapq.nsmallest(2, L, key=len) # Return two shortest elements
-['short', 'medium']
-\end{verbatim}
-
-(Contributed by Raymond Hettinger.)
-
-\item The \function{itertools.islice()} function now accepts
-\code{None} for the start and step arguments. This makes it more
-compatible with the attributes of slice objects, so that you can now write
-the following:
-
-\begin{verbatim}
-s = slice(5) # Create slice object
-itertools.islice(iterable, s.start, s.stop, s.step)
-\end{verbatim}
-
-(Contributed by Raymond Hettinger.)
-
-\item The \function{format()} function in the \module{locale} module
-has been modified and two new functions were added,
-\function{format_string()} and \function{currency()}.
-
-The \function{format()} function's \var{val} parameter could
-previously be a string as long as no more than one \%char specifier
-appeared; now the parameter must be exactly one \%char specifier with
-no surrounding text. An optional \var{monetary} parameter was also
-added which, if \code{True}, will use the locale's rules for
-formatting currency in placing a separator between groups of three
-digits.
-
-To format strings with multiple \%char specifiers, use the new
-\function{format_string()} function that works like \function{format()}
-but also supports mixing \%char specifiers with
-arbitrary text.
-
-A new \function{currency()} function was also added that formats a
-number according to the current locale's settings.
-
-(Contributed by Georg Brandl.)
-% Patch 1180296
-
-\item The \module{mailbox} module underwent a massive rewrite to add
-the capability to modify mailboxes in addition to reading them. A new
-set of classes that include \class{mbox}, \class{MH}, and
-\class{Maildir} are used to read mailboxes, and have an
-\method{add(\var{message})} method to add messages,
-\method{remove(\var{key})} to remove messages, and
-\method{lock()}/\method{unlock()} to lock/unlock the mailbox. The
-following example converts a maildir-format mailbox into an mbox-format one:
-
-\begin{verbatim}
-import mailbox
-
-# 'factory=None' uses email.Message.Message as the class representing
-# individual messages.
-src = mailbox.Maildir('maildir', factory=None)
-dest = mailbox.mbox('/tmp/mbox')
-
-for msg in src:
- dest.add(msg)
-\end{verbatim}
-
-(Contributed by Gregory K. Johnson. Funding was provided by Google's
-2005 Summer of Code.)
-
-\item New module: the \module{msilib} module allows creating
-Microsoft Installer \file{.msi} files and CAB files. Some support
-for reading the \file{.msi} database is also included.
-(Contributed by Martin von~L\"owis.)
-
-\item The \module{nis} module now supports accessing domains other
-than the system default domain by supplying a \var{domain} argument to
-the \function{nis.match()} and \function{nis.maps()} functions.
-(Contributed by Ben Bell.)
-
-\item The \module{operator} module's \function{itemgetter()}
-and \function{attrgetter()} functions now support multiple fields.
-A call such as \code{operator.attrgetter('a', 'b')}
-will return a function
-that retrieves the \member{a} and \member{b} attributes. Combining
-this new feature with the \method{sort()} method's \code{key} parameter
-lets you easily sort lists using multiple fields.
-(Contributed by Raymond Hettinger.)
-
-\item The \module{optparse} module was updated to version 1.5.1 of the
-Optik library. The \class{OptionParser} class gained an
-\member{epilog} attribute, a string that will be printed after the
-help message, and a \method{destroy()} method to break reference
-cycles created by the object. (Contributed by Greg Ward.)
-
-\item The \module{os} module underwent several changes. The
-\member{stat_float_times} variable now defaults to true, meaning that
-\function{os.stat()} will now return time values as floats. (This
-doesn't necessarily mean that \function{os.stat()} will return times
-that are precise to fractions of a second; not all systems support
-such precision.)
-
-Constants named \member{os.SEEK_SET}, \member{os.SEEK_CUR}, and
-\member{os.SEEK_END} have been added; these are the parameters to the
-\function{os.lseek()} function. Two new constants for locking are
-\member{os.O_SHLOCK} and \member{os.O_EXLOCK}.
-
-Two new functions, \function{wait3()} and \function{wait4()}, were
-added. They're similar the \function{waitpid()} function which waits
-for a child process to exit and returns a tuple of the process ID and
-its exit status, but \function{wait3()} and \function{wait4()} return
-additional information. \function{wait3()} doesn't take a process ID
-as input, so it waits for any child process to exit and returns a
-3-tuple of \var{process-id}, \var{exit-status}, \var{resource-usage}
-as returned from the \function{resource.getrusage()} function.
-\function{wait4(\var{pid})} does take a process ID.
-(Contributed by Chad J. Schroeder.)
-
-On FreeBSD, the \function{os.stat()} function now returns
-times with nanosecond resolution, and the returned object
-now has \member{st_gen} and \member{st_birthtime}.
-The \member{st_flags} member is also available, if the platform supports it.
-(Contributed by Antti Louko and Diego Petten\`o.)
-% (Patch 1180695, 1212117)
-
-\item The Python debugger provided by the \module{pdb} module
-can now store lists of commands to execute when a breakpoint is
-reached and execution stops. Once breakpoint \#1 has been created,
-enter \samp{commands 1} and enter a series of commands to be executed,
-finishing the list with \samp{end}. The command list can include
-commands that resume execution, such as \samp{continue} or
-\samp{next}. (Contributed by Gr\'egoire Dooms.)
-% Patch 790710
-
-\item The \module{pickle} and \module{cPickle} modules no
-longer accept a return value of \code{None} from the
-\method{__reduce__()} method; the method must return a tuple of
-arguments instead. The ability to return \code{None} was deprecated
-in Python 2.4, so this completes the removal of the feature.
-
-\item The \module{pkgutil} module, containing various utility
-functions for finding packages, was enhanced to support PEP 302's
-import hooks and now also works for packages stored in ZIP-format archives.
-(Contributed by Phillip J. Eby.)
-
-\item The pybench benchmark suite by Marc-Andr\'e~Lemburg is now
-included in the \file{Tools/pybench} directory. The pybench suite is
-an improvement on the commonly used \file{pystone.py} program because
-pybench provides a more detailed measurement of the interpreter's
-speed. It times particular operations such as function calls,
-tuple slicing, method lookups, and numeric operations, instead of
-performing many different operations and reducing the result to a
-single number as \file{pystone.py} does.
-
-\item The \module{pyexpat} module now uses version 2.0 of the Expat parser.
-(Contributed by Trent Mick.)
-
-\item The \class{Queue} class provided by the \module{Queue} module
-gained two new methods. \method{join()} blocks until all items in
-the queue have been retrieved and all processing work on the items
-have been completed. Worker threads call the other new method,
-\method{task_done()}, to signal that processing for an item has been
-completed. (Contributed by Raymond Hettinger.)
-
-\item The old \module{regex} and \module{regsub} modules, which have been
-deprecated ever since Python 2.0, have finally been deleted.
-Other deleted modules: \module{statcache}, \module{tzparse},
-\module{whrandom}.
-
-\item Also deleted: the \file{lib-old} directory,
-which includes ancient modules such as \module{dircmp} and
-\module{ni}, was removed. \file{lib-old} wasn't on the default
-\code{sys.path}, so unless your programs explicitly added the directory to
-\code{sys.path}, this removal shouldn't affect your code.
-
-\item The \module{rlcompleter} module is no longer
-dependent on importing the \module{readline} module and
-therefore now works on non-{\UNIX} platforms.
-(Patch from Robert Kiendl.)
-% Patch #1472854
-
-\item The \module{SimpleXMLRPCServer} and \module{DocXMLRPCServer}
-classes now have a \member{rpc_paths} attribute that constrains
-XML-RPC operations to a limited set of URL paths; the default is
-to allow only \code{'/'} and \code{'/RPC2'}. Setting
-\member{rpc_paths} to \code{None} or an empty tuple disables
-this path checking.
-% Bug #1473048
-
-\item The \module{socket} module now supports \constant{AF_NETLINK}
-sockets on Linux, thanks to a patch from Philippe Biondi.
-Netlink sockets are a Linux-specific mechanism for communications
-between a user-space process and kernel code; an introductory
-article about them is at \url{http://www.linuxjournal.com/article/7356}.
-In Python code, netlink addresses are represented as a tuple of 2 integers,
-\code{(\var{pid}, \var{group_mask})}.
-
-Two new methods on socket objects, \method{recv_into(\var{buffer})} and
-\method{recvfrom_into(\var{buffer})}, store the received data in an object
-that supports the buffer protocol instead of returning the data as a
-string. This means you can put the data directly into an array or a
-memory-mapped file.
-
-Socket objects also gained \method{getfamily()}, \method{gettype()},
-and \method{getproto()} accessor methods to retrieve the family, type,
-and protocol values for the socket.
-
-\item New module: the \module{spwd} module provides functions for
-accessing the shadow password database on systems that support
-shadow passwords.
-
-\item The \module{struct} is now faster because it
-compiles format strings into \class{Struct} objects
-with \method{pack()} and \method{unpack()} methods. This is similar
-to how the \module{re} module lets you create compiled regular
-expression objects. You can still use the module-level
-\function{pack()} and \function{unpack()} functions; they'll create
-\class{Struct} objects and cache them. Or you can use
-\class{Struct} instances directly:
-
-\begin{verbatim}
-s = struct.Struct('ih3s')
-
-data = s.pack(1972, 187, 'abc')
-year, number, name = s.unpack(data)
-\end{verbatim}
-
-You can also pack and unpack data to and from buffer objects directly
-using the \method{pack_into(\var{buffer}, \var{offset}, \var{v1},
-\var{v2}, ...)} and \method{unpack_from(\var{buffer}, \var{offset})}
-methods. This lets you store data directly into an array or a
-memory-mapped file.
-
-(\class{Struct} objects were implemented by Bob Ippolito at the
-NeedForSpeed sprint. Support for buffer objects was added by Martin
-Blais, also at the NeedForSpeed sprint.)
-
-\item The Python developers switched from CVS to Subversion during the 2.5
-development process. Information about the exact build version is
-available as the \code{sys.subversion} variable, a 3-tuple of
-\code{(\var{interpreter-name}, \var{branch-name},
-\var{revision-range})}. For example, at the time of writing my copy
-of 2.5 was reporting \code{('CPython', 'trunk', '45313:45315')}.
-
-This information is also available to C extensions via the
-\cfunction{Py_GetBuildInfo()} function that returns a
-string of build information like this:
-\code{"trunk:45355:45356M, Apr 13 2006, 07:42:19"}.
-(Contributed by Barry Warsaw.)
-
-\item Another new function, \function{sys._current_frames()}, returns
-the current stack frames for all running threads as a dictionary
-mapping thread identifiers to the topmost stack frame currently active
-in that thread at the time the function is called. (Contributed by
-Tim Peters.)
-
-\item The \class{TarFile} class in the \module{tarfile} module now has
-an \method{extractall()} method that extracts all members from the
-archive into the current working directory. It's also possible to set
-a different directory as the extraction target, and to unpack only a
-subset of the archive's members.
-
-The compression used for a tarfile opened in stream mode can now be
-autodetected using the mode \code{'r|*'}.
-% patch 918101
-(Contributed by Lars Gust\"abel.)
-
-\item The \module{threading} module now lets you set the stack size
-used when new threads are created. The
-\function{stack_size(\optional{\var{size}})} function returns the
-currently configured stack size, and supplying the optional \var{size}
-parameter sets a new value. Not all platforms support changing the
-stack size, but Windows, POSIX threading, and OS/2 all do.
-(Contributed by Andrew MacIntyre.)
-% Patch 1454481
-
-\item The \module{unicodedata} module has been updated to use version 4.1.0
-of the Unicode character database. Version 3.2.0 is required
-by some specifications, so it's still available as
-\member{unicodedata.ucd_3_2_0}.
-
-\item New module: the \module{uuid} module generates
-universally unique identifiers (UUIDs) according to \rfc{4122}. The
-RFC defines several different UUID versions that are generated from a
-starting string, from system properties, or purely randomly. This
-module contains a \class{UUID} class and
-functions named \function{uuid1()},
-\function{uuid3()}, \function{uuid4()}, and
-\function{uuid5()} to generate different versions of UUID. (Version 2 UUIDs
-are not specified in \rfc{4122} and are not supported by this module.)
-
-\begin{verbatim}
->>> import uuid
->>> # make a UUID based on the host ID and current time
->>> uuid.uuid1()
-UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')
-
->>> # make a UUID using an MD5 hash of a namespace UUID and a name
->>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
-UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')
-
->>> # make a random UUID
->>> uuid.uuid4()
-UUID('16fd2706-8baf-433b-82eb-8c7fada847da')
-
->>> # make a UUID using a SHA-1 hash of a namespace UUID and a name
->>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
-UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')
-\end{verbatim}
-
-(Contributed by Ka-Ping Yee.)
-
-\item The \module{weakref} module's \class{WeakKeyDictionary} and
-\class{WeakValueDictionary} types gained new methods for iterating
-over the weak references contained in the dictionary.
-\method{iterkeyrefs()} and \method{keyrefs()} methods were
-added to \class{WeakKeyDictionary}, and
-\method{itervaluerefs()} and \method{valuerefs()} were added to
-\class{WeakValueDictionary}. (Contributed by Fred L.~Drake, Jr.)
-
-\item The \module{webbrowser} module received a number of
-enhancements.
-It's now usable as a script with \code{python -m webbrowser}, taking a
-URL as the argument; there are a number of switches
-to control the behaviour (\programopt{-n} for a new browser window,
-\programopt{-t} for a new tab). New module-level functions,
-\function{open_new()} and \function{open_new_tab()}, were added
-to support this. The module's \function{open()} function supports an
-additional feature, an \var{autoraise} parameter that signals whether
-to raise the open window when possible. A number of additional
-browsers were added to the supported list such as Firefox, Opera,
-Konqueror, and elinks. (Contributed by Oleg Broytmann and Georg
-Brandl.)
-% Patch #754022
-
-\item The \module{xmlrpclib} module now supports returning
- \class{datetime} objects for the XML-RPC date type. Supply
- \code{use_datetime=True} to the \function{loads()} function
- or the \class{Unmarshaller} class to enable this feature.
- (Contributed by Skip Montanaro.)
-% Patch 1120353
-
-\item The \module{zipfile} module now supports the ZIP64 version of the
-format, meaning that a .zip archive can now be larger than 4~GiB and
-can contain individual files larger than 4~GiB. (Contributed by
-Ronald Oussoren.)
-% Patch 1446489
-
-\item The \module{zlib} module's \class{Compress} and \class{Decompress}
-objects now support a \method{copy()} method that makes a copy of the
-object's internal state and returns a new
-\class{Compress} or \class{Decompress} object.
-(Contributed by Chris AtLee.)
-% Patch 1435422
-
-\end{itemize}
-
-
-
-%======================================================================
-\subsection{The ctypes package\label{module-ctypes}}
-
-The \module{ctypes} package, written by Thomas Heller, has been added
-to the standard library. \module{ctypes} lets you call arbitrary functions
-in shared libraries or DLLs. Long-time users may remember the \module{dl} module, which
-provides functions for loading shared libraries and calling functions in them. The \module{ctypes} package is much fancier.
-
-To load a shared library or DLL, you must create an instance of the
-\class{CDLL} class and provide the name or path of the shared library
-or DLL. Once that's done, you can call arbitrary functions
-by accessing them as attributes of the \class{CDLL} object.
-
-\begin{verbatim}
-import ctypes
-
-libc = ctypes.CDLL('libc.so.6')
-result = libc.printf("Line of output\n")
-\end{verbatim}
-
-Type constructors for the various C types are provided: \function{c_int},
-\function{c_float}, \function{c_double}, \function{c_char_p} (equivalent to \ctype{char *}), and so forth. Unlike Python's types, the C versions are all mutable; you can assign to their \member{value} attribute
-to change the wrapped value. Python integers and strings will be automatically
-converted to the corresponding C types, but for other types you
-must call the correct type constructor. (And I mean \emph{must};
-getting it wrong will often result in the interpreter crashing
-with a segmentation fault.)
-
-You shouldn't use \function{c_char_p} with a Python string when the C function will be modifying the memory area, because Python strings are
-supposed to be immutable; breaking this rule will cause puzzling bugs. When you need a modifiable memory area,
-use \function{create_string_buffer()}:
-
-\begin{verbatim}
-s = "this is a string"
-buf = ctypes.create_string_buffer(s)
-libc.strfry(buf)
-\end{verbatim}
-
-C functions are assumed to return integers, but you can set
-the \member{restype} attribute of the function object to
-change this:
-
-\begin{verbatim}
->>> libc.atof('2.71828')
--1783957616
->>> libc.atof.restype = ctypes.c_double
->>> libc.atof('2.71828')
-2.71828
-\end{verbatim}
-
-\module{ctypes} also provides a wrapper for Python's C API
-as the \code{ctypes.pythonapi} object. This object does \emph{not}
-release the global interpreter lock before calling a function, because the lock must be held when calling into the interpreter's code.
-There's a \class{py_object()} type constructor that will create a
-\ctype{PyObject *} pointer. A simple usage:
-
-\begin{verbatim}
-import ctypes
-
-d = {}
-ctypes.pythonapi.PyObject_SetItem(ctypes.py_object(d),
- ctypes.py_object("abc"), ctypes.py_object(1))
-# d is now {'abc', 1}.
-\end{verbatim}
-
-Don't forget to use \class{py_object()}; if it's omitted you end
-up with a segmentation fault.
-
-\module{ctypes} has been around for a while, but people still write
-and distribution hand-coded extension modules because you can't rely on \module{ctypes} being present.
-Perhaps developers will begin to write
-Python wrappers atop a library accessed through \module{ctypes} instead
-of extension modules, now that \module{ctypes} is included with core Python.
-
-\begin{seealso}
-
-\seeurl{http://starship.python.net/crew/theller/ctypes/}
-{The ctypes web page, with a tutorial, reference, and FAQ.}
-
-\seeurl{../lib/module-ctypes.html}{The documentation
-for the \module{ctypes} module.}
-
-\end{seealso}
-
-
-%======================================================================
-\subsection{The ElementTree package\label{module-etree}}
-
-A subset of Fredrik Lundh's ElementTree library for processing XML has
-been added to the standard library as \module{xml.etree}. The
-available modules are
-\module{ElementTree}, \module{ElementPath}, and
-\module{ElementInclude} from ElementTree 1.2.6.
-The \module{cElementTree} accelerator module is also included.
-
-The rest of this section will provide a brief overview of using
-ElementTree. Full documentation for ElementTree is available at
-\url{http://effbot.org/zone/element-index.htm}.
-
-ElementTree represents an XML document as a tree of element nodes.
-The text content of the document is stored as the \member{.text}
-and \member{.tail} attributes of
-(This is one of the major differences between ElementTree and
-the Document Object Model; in the DOM there are many different
-types of node, including \class{TextNode}.)
-
-The most commonly used parsing function is \function{parse()}, that
-takes either a string (assumed to contain a filename) or a file-like
-object and returns an \class{ElementTree} instance:
-
-\begin{verbatim}
-from xml.etree import ElementTree as ET
-
-tree = ET.parse('ex-1.xml')
-
-feed = urllib.urlopen(
- 'http://planet.python.org/rss10.xml')
-tree = ET.parse(feed)
-\end{verbatim}
-
-Once you have an \class{ElementTree} instance, you
-can call its \method{getroot()} method to get the root \class{Element} node.
-
-There's also an \function{XML()} function that takes a string literal
-and returns an \class{Element} node (not an \class{ElementTree}).
-This function provides a tidy way to incorporate XML fragments,
-approaching the convenience of an XML literal:
-
-\begin{verbatim}
-svg = ET.XML("""<svg width="10px" version="1.0">
- </svg>""")
-svg.set('height', '320px')
-svg.append(elem1)
-\end{verbatim}
-
-Each XML element supports some dictionary-like and some list-like
-access methods. Dictionary-like operations are used to access attribute
-values, and list-like operations are used to access child nodes.
-
-\begin{tableii}{c|l}{code}{Operation}{Result}
- \lineii{elem[n]}{Returns n'th child element.}
- \lineii{elem[m:n]}{Returns list of m'th through n'th child elements.}
- \lineii{len(elem)}{Returns number of child elements.}
- \lineii{list(elem)}{Returns list of child elements.}
- \lineii{elem.append(elem2)}{Adds \var{elem2} as a child.}
- \lineii{elem.insert(index, elem2)}{Inserts \var{elem2} at the specified location.}
- \lineii{del elem[n]}{Deletes n'th child element.}
- \lineii{elem.keys()}{Returns list of attribute names.}
- \lineii{elem.get(name)}{Returns value of attribute \var{name}.}
- \lineii{elem.set(name, value)}{Sets new value for attribute \var{name}.}
- \lineii{elem.attrib}{Retrieves the dictionary containing attributes.}
- \lineii{del elem.attrib[name]}{Deletes attribute \var{name}.}
-\end{tableii}
-
-Comments and processing instructions are also represented as
-\class{Element} nodes. To check if a node is a comment or processing
-instructions:
-
-\begin{verbatim}
-if elem.tag is ET.Comment:
- ...
-elif elem.tag is ET.ProcessingInstruction:
- ...
-\end{verbatim}
-
-To generate XML output, you should call the
-\method{ElementTree.write()} method. Like \function{parse()},
-it can take either a string or a file-like object:
-
-\begin{verbatim}
-# Encoding is US-ASCII
-tree.write('output.xml')
-
-# Encoding is UTF-8
-f = open('output.xml', 'w')
-tree.write(f, encoding='utf-8')
-\end{verbatim}
-
-(Caution: the default encoding used for output is ASCII. For general
-XML work, where an element's name may contain arbitrary Unicode
-characters, ASCII isn't a very useful encoding because it will raise
-an exception if an element's name contains any characters with values
-greater than 127. Therefore, it's best to specify a different
-encoding such as UTF-8 that can handle any Unicode character.)
-
-This section is only a partial description of the ElementTree interfaces.
-Please read the package's official documentation for more details.
-
-\begin{seealso}
-
-\seeurl{http://effbot.org/zone/element-index.htm}
-{Official documentation for ElementTree.}
-
-\end{seealso}
-
-
-%======================================================================
-\subsection{The hashlib package\label{module-hashlib}}
-
-A new \module{hashlib} module, written by Gregory P. Smith,
-has been added to replace the
-\module{md5} and \module{sha} modules. \module{hashlib} adds support
-for additional secure hashes (SHA-224, SHA-256, SHA-384, and SHA-512).
-When available, the module uses OpenSSL for fast platform optimized
-implementations of algorithms.
-
-The old \module{md5} and \module{sha} modules still exist as wrappers
-around hashlib to preserve backwards compatibility. The new module's
-interface is very close to that of the old modules, but not identical.
-The most significant difference is that the constructor functions
-for creating new hashing objects are named differently.
-
-\begin{verbatim}
-# Old versions
-h = md5.md5()
-h = md5.new()
-
-# New version
-h = hashlib.md5()
-
-# Old versions
-h = sha.sha()
-h = sha.new()
-
-# New version
-h = hashlib.sha1()
-
-# Hash that weren't previously available
-h = hashlib.sha224()
-h = hashlib.sha256()
-h = hashlib.sha384()
-h = hashlib.sha512()
-
-# Alternative form
-h = hashlib.new('md5') # Provide algorithm as a string
-\end{verbatim}
-
-Once a hash object has been created, its methods are the same as before:
-\method{update(\var{string})} hashes the specified string into the
-current digest state, \method{digest()} and \method{hexdigest()}
-return the digest value as a binary string or a string of hex digits,
-and \method{copy()} returns a new hashing object with the same digest state.
-
-\begin{seealso}
-
-\seeurl{../lib/module-hashlib.html}{The documentation
-for the \module{hashlib} module.}
-
-\end{seealso}
-
-
-%======================================================================
-\subsection{The sqlite3 package\label{module-sqlite}}
-
-The pysqlite module (\url{http://www.pysqlite.org}), a wrapper for the
-SQLite embedded database, has been added to the standard library under
-the package name \module{sqlite3}.
-
-SQLite is a C library that provides a lightweight disk-based database
-that doesn't require a separate server process and allows accessing
-the database using a nonstandard variant of the SQL query language.
-Some applications can use SQLite for internal data storage. It's also
-possible to prototype an application using SQLite and then port the
-code to a larger database such as PostgreSQL or Oracle.
-
-pysqlite was written by Gerhard H\"aring and provides a SQL interface
-compliant with the DB-API 2.0 specification described by
-\pep{249}.
-
-If you're compiling the Python source yourself, note that the source
-tree doesn't include the SQLite code, only the wrapper module.
-You'll need to have the SQLite libraries and headers installed before
-compiling Python, and the build process will compile the module when
-the necessary headers are available.
-
-To use the module, you must first create a \class{Connection} object
-that represents the database. Here the data will be stored in the
-\file{/tmp/example} file:
-
-\begin{verbatim}
-conn = sqlite3.connect('/tmp/example')
-\end{verbatim}
-
-You can also supply the special name \samp{:memory:} to create
-a database in RAM.
-
-Once you have a \class{Connection}, you can create a \class{Cursor}
-object and call its \method{execute()} method to perform SQL commands:
-
-\begin{verbatim}
-c = conn.cursor()
-
-# Create table
-c.execute('''create table stocks
-(date text, trans text, symbol text,
- qty real, price real)''')
-
-# Insert a row of data
-c.execute("""insert into stocks
- values ('2006-01-05','BUY','RHAT',100,35.14)""")
-\end{verbatim}
-
-Usually your SQL operations will need to use values from Python
-variables. You shouldn't assemble your query using Python's string
-operations because doing so is insecure; it makes your program
-vulnerable to an SQL injection attack.
-
-Instead, use the DB-API's parameter substitution. Put \samp{?} as a
-placeholder wherever you want to use a value, and then provide a tuple
-of values as the second argument to the cursor's \method{execute()}
-method. (Other database modules may use a different placeholder,
-such as \samp{\%s} or \samp{:1}.) For example:
-
-\begin{verbatim}
-# Never do this -- insecure!
-symbol = 'IBM'
-c.execute("... where symbol = '%s'" % symbol)
-
-# Do this instead
-t = (symbol,)
-c.execute('select * from stocks where symbol=?', t)
-
-# Larger example
-for t in (('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
- ('2006-04-05', 'BUY', 'MSOFT', 1000, 72.00),
- ('2006-04-06', 'SELL', 'IBM', 500, 53.00),
- ):
- c.execute('insert into stocks values (?,?,?,?,?)', t)
-\end{verbatim}
-
-To retrieve data after executing a SELECT statement, you can either
-treat the cursor as an iterator, call the cursor's \method{fetchone()}
-method to retrieve a single matching row,
-or call \method{fetchall()} to get a list of the matching rows.
-
-This example uses the iterator form:
-
-\begin{verbatim}
->>> c = conn.cursor()
->>> c.execute('select * from stocks order by price')
->>> for row in c:
-... print row
-...
-(u'2006-01-05', u'BUY', u'RHAT', 100, 35.140000000000001)
-(u'2006-03-28', u'BUY', u'IBM', 1000, 45.0)
-(u'2006-04-06', u'SELL', u'IBM', 500, 53.0)
-(u'2006-04-05', u'BUY', u'MSOFT', 1000, 72.0)
->>>
-\end{verbatim}
-
-For more information about the SQL dialect supported by SQLite, see
-\url{http://www.sqlite.org}.
-
-\begin{seealso}
-
-\seeurl{http://www.pysqlite.org}
-{The pysqlite web page.}
-
-\seeurl{http://www.sqlite.org}
-{The SQLite web page; the documentation describes the syntax and the
-available data types for the supported SQL dialect.}
-
-\seeurl{../lib/module-sqlite3.html}{The documentation
-for the \module{sqlite3} module.}
-
-\seepep{249}{Database API Specification 2.0}{PEP written by
-Marc-Andr\'e Lemburg.}
-
-\end{seealso}
-
-
-%======================================================================
-\subsection{The wsgiref package\label{module-wsgiref}}
-
-% XXX should this be in a PEP 333 section instead?
-
-The Web Server Gateway Interface (WSGI) v1.0 defines a standard
-interface between web servers and Python web applications and is
-described in \pep{333}. The \module{wsgiref} package is a reference
-implementation of the WSGI specification.
-
-The package includes a basic HTTP server that will run a WSGI
-application; this server is useful for debugging but isn't intended for
-production use. Setting up a server takes only a few lines of code:
-
-\begin{verbatim}
-from wsgiref import simple_server
-
-wsgi_app = ...
-
-host = ''
-port = 8000
-httpd = simple_server.make_server(host, port, wsgi_app)
-httpd.serve_forever()
-\end{verbatim}
-
-% XXX discuss structure of WSGI applications?
-% XXX provide an example using Django or some other framework?
-
-\begin{seealso}
-
-\seeurl{http://www.wsgi.org}{A central web site for WSGI-related resources.}
-
-\seepep{333}{Python Web Server Gateway Interface v1.0}{PEP written by
-Phillip J. Eby.}
-
-\end{seealso}
-
-
-% ======================================================================
-\section{Build and C API Changes\label{build-api}}
-
-Changes to Python's build process and to the C API include:
-
-\begin{itemize}
-
-\item The Python source tree was converted from CVS to Subversion,
-in a complex migration procedure that was supervised and flawlessly
-carried out by Martin von~L\"owis. The procedure was developed as
-\pep{347}.
-
-\item Coverity, a company that markets a source code analysis tool
-called Prevent, provided the results of their examination of the Python
-source code. The analysis found about 60 bugs that
-were quickly fixed. Many of the bugs were refcounting problems, often
-occurring in error-handling code. See
-\url{http://scan.coverity.com} for the statistics.
-
-\item The largest change to the C API came from \pep{353},
-which modifies the interpreter to use a \ctype{Py_ssize_t} type
-definition instead of \ctype{int}. See the earlier
-section~\ref{pep-353} for a discussion of this change.
-
-\item The design of the bytecode compiler has changed a great deal,
-no longer generating bytecode by traversing the parse tree. Instead
-the parse tree is converted to an abstract syntax tree (or AST), and it is
-the abstract syntax tree that's traversed to produce the bytecode.
-
-It's possible for Python code to obtain AST objects by using the
-\function{compile()} built-in and specifying \code{_ast.PyCF_ONLY_AST}
-as the value of the
-\var{flags} parameter:
-
-\begin{verbatim}
-from _ast import PyCF_ONLY_AST
-ast = compile("""a=0
-for i in range(10):
- a += i
-""", "<string>", 'exec', PyCF_ONLY_AST)
-
-assignment = ast.body[0]
-for_loop = ast.body[1]
-\end{verbatim}
-
-No official documentation has been written for the AST code yet, but
-\pep{339} discusses the design. To start learning about the code, read the
-definition of the various AST nodes in \file{Parser/Python.asdl}. A
-Python script reads this file and generates a set of C structure
-definitions in \file{Include/Python-ast.h}. The
-\cfunction{PyParser_ASTFromString()} and
-\cfunction{PyParser_ASTFromFile()}, defined in
-\file{Include/pythonrun.h}, take Python source as input and return the
-root of an AST representing the contents. This AST can then be turned
-into a code object by \cfunction{PyAST_Compile()}. For more
-information, read the source code, and then ask questions on
-python-dev.
-
-% List of names taken from Jeremy's python-dev post at
-% http://mail.python.org/pipermail/python-dev/2005-October/057500.html
-The AST code was developed under Jeremy Hylton's management, and
-implemented by (in alphabetical order) Brett Cannon, Nick Coghlan,
-Grant Edwards, John Ehresman, Kurt Kaiser, Neal Norwitz, Tim Peters,
-Armin Rigo, and Neil Schemenauer, plus the participants in a number of
-AST sprints at conferences such as PyCon.
-
-\item Evan Jones's patch to obmalloc, first described in a talk
-at PyCon DC 2005, was applied. Python 2.4 allocated small objects in
-256K-sized arenas, but never freed arenas. With this patch, Python
-will free arenas when they're empty. The net effect is that on some
-platforms, when you allocate many objects, Python's memory usage may
-actually drop when you delete them and the memory may be returned to
-the operating system. (Implemented by Evan Jones, and reworked by Tim
-Peters.)
-
-Note that this change means extension modules must be more careful
-when allocating memory. Python's API has many different
-functions for allocating memory that are grouped into families. For
-example, \cfunction{PyMem_Malloc()}, \cfunction{PyMem_Realloc()}, and
-\cfunction{PyMem_Free()} are one family that allocates raw memory,
-while \cfunction{PyObject_Malloc()}, \cfunction{PyObject_Realloc()},
-and \cfunction{PyObject_Free()} are another family that's supposed to
-be used for creating Python objects.
-
-Previously these different families all reduced to the platform's
-\cfunction{malloc()} and \cfunction{free()} functions. This meant
-it didn't matter if you got things wrong and allocated memory with the
-\cfunction{PyMem} function but freed it with the \cfunction{PyObject}
-function. With 2.5's changes to obmalloc, these families now do different
-things and mismatches will probably result in a segfault. You should
-carefully test your C extension modules with Python 2.5.
-
-\item The built-in set types now have an official C API. Call
-\cfunction{PySet_New()} and \cfunction{PyFrozenSet_New()} to create a
-new set, \cfunction{PySet_Add()} and \cfunction{PySet_Discard()} to
-add and remove elements, and \cfunction{PySet_Contains} and
-\cfunction{PySet_Size} to examine the set's state.
-(Contributed by Raymond Hettinger.)
-
-\item C code can now obtain information about the exact revision
-of the Python interpreter by calling the
-\cfunction{Py_GetBuildInfo()} function that returns a
-string of build information like this:
-\code{"trunk:45355:45356M, Apr 13 2006, 07:42:19"}.
-(Contributed by Barry Warsaw.)
-
-\item Two new macros can be used to indicate C functions that are
-local to the current file so that a faster calling convention can be
-used. \cfunction{Py_LOCAL(\var{type})} declares the function as
-returning a value of the specified \var{type} and uses a fast-calling
-qualifier. \cfunction{Py_LOCAL_INLINE(\var{type})} does the same thing
-and also requests the function be inlined. If
-\cfunction{PY_LOCAL_AGGRESSIVE} is defined before \file{python.h} is
-included, a set of more aggressive optimizations are enabled for the
-module; you should benchmark the results to find out if these
-optimizations actually make the code faster. (Contributed by Fredrik
-Lundh at the NeedForSpeed sprint.)
-
-\item \cfunction{PyErr_NewException(\var{name}, \var{base},
-\var{dict})} can now accept a tuple of base classes as its \var{base}
-argument. (Contributed by Georg Brandl.)
-
-\item The \cfunction{PyErr_Warn()} function for issuing warnings
-is now deprecated in favour of \cfunction{PyErr_WarnEx(category,
-message, stacklevel)} which lets you specify the number of stack
-frames separating this function and the caller. A \var{stacklevel} of
-1 is the function calling \cfunction{PyErr_WarnEx()}, 2 is the
-function above that, and so forth. (Added by Neal Norwitz.)
-
-\item The CPython interpreter is still written in C, but
-the code can now be compiled with a {\Cpp} compiler without errors.
-(Implemented by Anthony Baxter, Martin von~L\"owis, Skip Montanaro.)
-
-\item The \cfunction{PyRange_New()} function was removed. It was
-never documented, never used in the core code, and had dangerously lax
-error checking. In the unlikely case that your extensions were using
-it, you can replace it by something like the following:
-\begin{verbatim}
-range = PyObject_CallFunction((PyObject*) &PyRange_Type, "lll",
- start, stop, step);
-\end{verbatim}
-
-\end{itemize}
-
-
-%======================================================================
-\subsection{Port-Specific Changes\label{ports}}
-
-\begin{itemize}
-
-\item MacOS X (10.3 and higher): dynamic loading of modules
-now uses the \cfunction{dlopen()} function instead of MacOS-specific
-functions.
-
-\item MacOS X: a \longprogramopt{enable-universalsdk} switch was added
-to the \program{configure} script that compiles the interpreter as a
-universal binary able to run on both PowerPC and Intel processors.
-(Contributed by Ronald Oussoren.)
-
-\item Windows: \file{.dll} is no longer supported as a filename extension for
-extension modules. \file{.pyd} is now the only filename extension that will
-be searched for.
-
-\end{itemize}
-
-
-%======================================================================
-\section{Porting to Python 2.5\label{porting}}
-
-This section lists previously described changes that may require
-changes to your code:
-
-\begin{itemize}
-
-\item ASCII is now the default encoding for modules. It's now
-a syntax error if a module contains string literals with 8-bit
-characters but doesn't have an encoding declaration. In Python 2.4
-this triggered a warning, not a syntax error.
-
-\item Previously, the \member{gi_frame} attribute of a generator
-was always a frame object. Because of the \pep{342} changes
-described in section~\ref{pep-342}, it's now possible
-for \member{gi_frame} to be \code{None}.
-
-\item A new warning, \class{UnicodeWarning}, is triggered when
-you attempt to compare a Unicode string and an 8-bit string that can't
-be converted to Unicode using the default ASCII encoding. Previously
-such comparisons would raise a \class{UnicodeDecodeError} exception.
-
-\item Library: the \module{csv} module is now stricter about multi-line quoted
-fields. If your files contain newlines embedded within fields, the
-input should be split into lines in a manner which preserves the
-newline characters.
-
-\item Library: the \module{locale} module's
-\function{format()} function's would previously
-accept any string as long as no more than one \%char specifier
-appeared. In Python 2.5, the argument must be exactly one \%char
-specifier with no surrounding text.
-
-\item Library: The \module{pickle} and \module{cPickle} modules no
-longer accept a return value of \code{None} from the
-\method{__reduce__()} method; the method must return a tuple of
-arguments instead. The modules also no longer accept the deprecated
-\var{bin} keyword parameter.
-
-\item Library: The \module{SimpleXMLRPCServer} and \module{DocXMLRPCServer}
-classes now have a \member{rpc_paths} attribute that constrains
-XML-RPC operations to a limited set of URL paths; the default is
-to allow only \code{'/'} and \code{'/RPC2'}. Setting
-\member{rpc_paths} to \code{None} or an empty tuple disables
-this path checking.
-
-\item C API: Many functions now use \ctype{Py_ssize_t}
-instead of \ctype{int} to allow processing more data on 64-bit
-machines. Extension code may need to make the same change to avoid
-warnings and to support 64-bit machines. See the earlier
-section~\ref{pep-353} for a discussion of this change.
-
-\item C API:
-The obmalloc changes mean that
-you must be careful to not mix usage
-of the \cfunction{PyMem_*()} and \cfunction{PyObject_*()}
-families of functions. Memory allocated with
-one family's \cfunction{*_Malloc()} must be
-freed with the corresponding family's \cfunction{*_Free()} function.
-
-\end{itemize}
-
-
-%======================================================================
-\section{Acknowledgements \label{acks}}
-
-The author would like to thank the following people for offering
-suggestions, corrections and assistance with various drafts of this
-article: Georg Brandl, Nick Coghlan, Phillip J. Eby, Lars Gust\"abel,
-Raymond Hettinger, Ralf W. Grosse-Kunstleve, Kent Johnson, Iain Lowe,
-Martin von~L\"owis, Fredrik Lundh, Andrew McNamara, Skip Montanaro,
-Gustavo Niemeyer, Paul Prescod, James Pryor, Mike Rovner, Scott
-Weikart, Barry Warsaw, Thomas Wouters.
-
-\end{document}
diff --git a/Doc/whatsnew/whatsnew26.tex b/Doc/whatsnew/whatsnew26.tex
deleted file mode 100644
index 5d2373f..0000000
--- a/Doc/whatsnew/whatsnew26.tex
+++ /dev/null
@@ -1,268 +0,0 @@
-\documentclass{howto}
-\usepackage{distutils}
-% $Id$
-
-% Rules for maintenance:
-%
-% * Anyone can add text to this document. Do not spend very much time
-% on the wording of your changes, because your text will probably
-% get rewritten to some degree.
-%
-% * The maintainer will go through Misc/NEWS periodically and add
-% changes; it's therefore more important to add your changes to
-% Misc/NEWS than to this file.
-%
-% * This is not a complete list of every single change; completeness
-% is the purpose of Misc/NEWS. Some changes I consider too small
-% or esoteric to include. If such a change is added to the text,
-% I'll just remove it. (This is another reason you shouldn't spend
-% too much time on writing your addition.)
-%
-% * If you want to draw your new text to the attention of the
-% maintainer, add 'XXX' to the beginning of the paragraph or
-% section.
-%
-% * It's OK to just add a fragmentary note about a change. For
-% example: "XXX Describe the transmogrify() function added to the
-% socket module." The maintainer will research the change and
-% write the necessary text.
-%
-% * You can comment out your additions if you like, but it's not
-% necessary (especially when a final release is some months away).
-%
-% * Credit the author of a patch or bugfix. Just the name is
-% sufficient; the e-mail address isn't necessary.
-%
-% * It's helpful to add the bug/patch number as a comment:
-%
-% % Patch 12345
-% XXX Describe the transmogrify() function added to the socket
-% module.
-% (Contributed by P.Y. Developer.)
-%
-% This saves the maintainer the effort of going through the SVN log
-% when researching a change.
-
-\title{What's New in Python 2.6}
-\release{0.0}
-\author{A.M. Kuchling}
-\authoraddress{\email{amk@amk.ca}}
-
-\begin{document}
-\maketitle
-\tableofcontents
-
-This article explains the new features in Python 2.6. No release date
-for Python 2.6 has been set; it will probably be released in mid 2008.
-
-% Compare with previous release in 2 - 3 sentences here.
-
-This article doesn't attempt to provide a complete specification of
-the new features, but instead provides a convenient overview. For
-full details, you should refer to the documentation for Python 2.6.
-% add hyperlink when the documentation becomes available online.
-If you want to understand the complete implementation and design
-rationale, refer to the PEP for a particular new feature.
-
-
-%======================================================================
-
-% Large, PEP-level features and changes should be described here.
-
-% Should there be a new section here for 3k migration?
-% Or perhaps a more general section describing module changes/deprecation?
-% sets module deprecated
-
-%======================================================================
-\section{Other Language Changes}
-
-Here are all of the changes that Python 2.6 makes to the core Python
-language.
-
-\begin{itemize}
-
-% Bug 1569356
-\item An obscure change: when you use the the \function{locals()}
-function inside a \keyword{class} statement, the resulting dictionary
-no longer returns free variables. (Free variables, in this case, are
-variables referred to in the \keyword{class} statement
-that aren't attributes of the class.)
-
-\end{itemize}
-
-
-%======================================================================
-\subsection{Optimizations}
-
-\begin{itemize}
-
-% Patch 1624059
-\item Internally, a bit is now set in type objects to indicate some of
-the standard built-in types. This speeds up checking if an object is
-a subclass of one of these types. (Contributed by Neal Norwitz.)
-
-\end{itemize}
-
-The net result of the 2.6 optimizations is that Python 2.6 runs the
-pystone benchmark around XX\% faster than Python 2.5.
-
-
-%======================================================================
-\section{New, Improved, and Deprecated Modules}
-
-As usual, Python's standard library received a number of enhancements and
-bug fixes. Here's a partial list of the most notable changes, sorted
-alphabetically by module name. Consult the
-\file{Misc/NEWS} file in the source tree for a more
-complete list of changes, or look through the CVS logs for all the
-details.
-
-\begin{itemize}
-
-\item New data type in the \module{collections} module:
-\class{NamedTuple(\var{typename}, \var{fieldnames})} is a factory function that
-creates subclasses of the standard tuple whose fields are accessible
-by name as well as index. For example:
-
-\begin{verbatim}
-var_type = collections.NamedTuple('variable',
- 'id name type size')
-var = var_type(1, 'frequency', 'int', 4)
-
-print var[0], var.id # Equivalent
-print var[2], var.type # Equivalent
-\end{verbatim}
-
-(Contributed by Raymond Hettinger.)
-
-\item New method in the \module{curses} module:
-for a window, \method{chgat()} changes the display characters for a
-certain number of characters on a single line.
-
-\begin{verbatim}
-# Boldface text starting at y=0,x=21
-# and affecting the rest of the line.
-stdscr.chgat(0,21, curses.A_BOLD)
-\end{verbatim}
-
-(Contributed by Fabian Kreutz.)
-
-\item The \module{gopherlib} module has been removed.
-
-\item New function in the \module{heapq} module:
-\function{merge(iter1, iter2, ...)}
-takes any number of iterables that return data
-\emph{in sorted order},
-and
-returns a new iterator that returns the contents of
-all the iterators, also in sorted order. For example:
-
-\begin{verbatim}
-heapq.merge([1, 3, 5, 9], [2, 8, 16]) ->
- [1, 2, 3, 5, 8, 9, 16]
-\end{verbatim}
-
-(Contributed by Raymond Hettinger.)
-
-\item New function in the \module{itertools} module:
-\function{izip_longest(iter1, iter2, ...\optional{, fillvalue})}
-makes tuples from each of the elements; if some of the iterables
-are shorter than others, the missing values
-are set to \var{fillvalue}. For example:
-
-\begin{verbatim}
-itertools.izip_longest([1,2,3], [1,2,3,4,5]) ->
- [(1, 1), (2, 2), (3, 3), (None, 4), (None, 5)]
-\end{verbatim}
-
-(Contributed by Raymond Hettinger.)
-
-\item The \module{macfs} module has been removed. This in turn
-required the \function{macostools.touched()} function to be removed
-because it depended on the \module{macfs} module.
-
-% Patch #1490190
-\item New functions in the \module{posix} module: \function{chflags()}
-and \function{lchflags()} are wrappers for the corresponding system
-calls (where they're available). Constants for the flag values are
-defined in the \module{stat} module; some possible values include
-\constant{UF_IMMUTABLE} to signal the file may not be changed and
-\constant{UF_APPEND} to indicate that data can only be appended to the
-file. (Contributed by M. Levinson.)
-
-\item The \module{rgbimg} module has been removed.
-
-\item The \module{smtplib} module now supports SMTP over
-SSL thanks to the addition of the \class{SMTP_SSL} class.
-This class supports an interface identical to the existing \class{SMTP}
-class. (Contributed by Monty Taylor.)
-
-\item The \module{test.test_support} module now contains a
-\function{EnvironmentVarGuard} context manager that
-supports temporarily changing environment variables and
-automatically restores them to their old values.
-(Contributed by Brett Cannon.)
-
-\end{itemize}
-
-
-%======================================================================
-% whole new modules get described in \subsections here
-
-
-% ======================================================================
-\section{Build and C API Changes}
-
-Changes to Python's build process and to the C API include:
-
-\begin{itemize}
-
-\item Detailed changes are listed here.
-
-\end{itemize}
-
-
-%======================================================================
-\subsection{Port-Specific Changes}
-
-Platform-specific changes go here.
-
-
-%======================================================================
-\section{Other Changes and Fixes \label{section-other}}
-
-As usual, there were a bunch of other improvements and bugfixes
-scattered throughout the source tree. A search through the change
-logs finds there were XXX patches applied and YYY bugs fixed between
-Python 2.5 and 2.6. Both figures are likely to be underestimates.
-
-Some of the more notable changes are:
-
-\begin{itemize}
-
-\item Details go here.
-
-\end{itemize}
-
-
-%======================================================================
-\section{Porting to Python 2.6}
-
-This section lists previously described changes that may require
-changes to your code:
-
-\begin{itemize}
-
-\item Everything is all in the details!
-
-\end{itemize}
-
-
-%======================================================================
-\section{Acknowledgements \label{acks}}
-
-The author would like to thank the following people for offering
-suggestions, corrections and assistance with various drafts of this
-article: .
-
-\end{document}
diff --git a/Doc/whatsnew/whatsnew30.tex b/Doc/whatsnew/whatsnew30.tex
deleted file mode 100644
index f52ca37..0000000
--- a/Doc/whatsnew/whatsnew30.tex
+++ /dev/null
@@ -1,178 +0,0 @@
-\documentclass{howto}
-\usepackage{distutils}
-% $Id: whatsnew26.tex 55506 2007-05-22 07:43:29Z neal.norwitz $
-
-% Rules for maintenance:
-%
-% * Anyone can add text to this document. Do not spend very much time
-% on the wording of your changes, because your text will probably
-% get rewritten to some degree.
-%
-% * The maintainer will go through Misc/NEWS periodically and add
-% changes; it's therefore more important to add your changes to
-% Misc/NEWS than to this file.
-%
-% * This is not a complete list of every single change; completeness
-% is the purpose of Misc/NEWS. Some changes I consider too small
-% or esoteric to include. If such a change is added to the text,
-% I'll just remove it. (This is another reason you shouldn't spend
-% too much time on writing your addition.)
-%
-% * If you want to draw your new text to the attention of the
-% maintainer, add 'XXX' to the beginning of the paragraph or
-% section.
-%
-% * It's OK to just add a fragmentary note about a change. For
-% example: "XXX Describe the transmogrify() function added to the
-% socket module." The maintainer will research the change and
-% write the necessary text.
-%
-% * You can comment out your additions if you like, but it's not
-% necessary (especially when a final release is some months away).
-%
-% * Credit the author of a patch or bugfix. Just the name is
-% sufficient; the e-mail address isn't necessary.
-%
-% * It's helpful to add the bug/patch number as a comment:
-%
-% % Patch 12345
-% XXX Describe the transmogrify() function added to the socket
-% module.
-% (Contributed by P.Y. Developer.)
-%
-% This saves the maintainer the effort of going through the SVN log
-% when researching a change.
-
-\title{What's New in Python 3.0}
-\release{0.0}
-\author{A.M. Kuchling}
-\authoraddress{\email{amk@amk.ca}}
-
-\begin{document}
-\maketitle
-\tableofcontents
-
-This article explains the new features in Python 3.0. No release date
-for Python 3.0 has been set; it will probably be released in mid 2008.
-
-% Compare with previous release in 2 - 3 sentences here.
-
-This article doesn't attempt to provide a complete specification of
-the new features, but instead provides a convenient overview. For
-full details, you should refer to the documentation for Python 3.0.
-% add hyperlink when the documentation becomes available online.
-If you want to understand the complete implementation and design
-rationale, refer to the PEP for a particular new feature.
-
-
-%======================================================================
-
-% Large, PEP-level features and changes should be described here.
-
-% Should there be a new section here for 3k migration?
-% Or perhaps a more general section describing module changes/deprecation?
-% sets module deprecated
-
-%======================================================================
-\section{Other Language Changes}
-
-Here are all of the changes that Python 2.6 makes to the core Python
-language.
-
-\begin{itemize}
-
-\item Detailed changes are listed here.
-
-\end{itemize}
-
-
-%======================================================================
-\subsection{Optimizations}
-
-\begin{itemize}
-
-\item Detailed changes are listed here.
-
-\end{itemize}
-
-The net result of the 3.0 optimizations is that Python 3.0 runs the
-pystone benchmark around XX\% slower than Python 2.6.
-
-
-%======================================================================
-\section{New, Improved, and Deprecated Modules}
-
-As usual, Python's standard library received a number of enhancements and
-bug fixes. Here's a partial list of the most notable changes, sorted
-alphabetically by module name. Consult the
-\file{Misc/NEWS} file in the source tree for a more
-complete list of changes, or look through the CVS logs for all the
-details.
-
-\begin{itemize}
-
-\item Detailed changes are listed here.
-
-\end{itemize}
-
-
-%======================================================================
-% whole new modules get described in \subsections here
-
-
-% ======================================================================
-\section{Build and C API Changes}
-
-Changes to Python's build process and to the C API include:
-
-\begin{itemize}
-
-\item Detailed changes are listed here.
-
-\end{itemize}
-
-
-%======================================================================
-\subsection{Port-Specific Changes}
-
-Platform-specific changes go here.
-
-
-%======================================================================
-\section{Other Changes and Fixes \label{section-other}}
-
-As usual, there were a bunch of other improvements and bugfixes
-scattered throughout the source tree. A search through the change
-logs finds there were XXX patches applied and YYY bugs fixed between
-Python 2.6 and 3.0. Both figures are likely to be underestimates.
-
-Some of the more notable changes are:
-
-\begin{itemize}
-
-\item Details go here.
-
-\end{itemize}
-
-
-%======================================================================
-\section{Porting to Python 3.0}
-
-This section lists previously described changes that may require
-changes to your code:
-
-\begin{itemize}
-
-\item Everything is all in the details!
-
-\end{itemize}
-
-
-%======================================================================
-\section{Acknowledgements \label{acks}}
-
-The author would like to thank the following people for offering
-suggestions, corrections and assistance with various drafts of this
-article: .
-
-\end{document}
