From f56181ff53ba00b7bed3997a4dccd9a1b6217b57 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 15 Aug 2007 14:26:55 +0000 Subject: Delete the LaTeX doc tree. --- Doc/ACKS | 202 -- Doc/Makefile | 736 ---- Doc/Makefile.deps | 382 -- Doc/README | 246 -- Doc/TODO | 74 - Doc/api/abstract.tex | 1057 ------ Doc/api/api.tex | 60 - Doc/api/concrete.tex | 3238 ----------------- Doc/api/exceptions.tex | 442 --- Doc/api/init.tex | 884 ----- Doc/api/intro.tex | 627 ---- Doc/api/memory.tex | 204 -- Doc/api/newtypes.tex | 1780 ---------- Doc/api/refcounting.tex | 69 - Doc/api/refcounts.dat | 1756 ---------- Doc/api/utilities.tex | 1023 ------ Doc/api/veryhigh.tex | 287 -- Doc/commontex/boilerplate.tex | 9 - Doc/commontex/copyright.tex | 14 - Doc/commontex/license.tex | 674 ---- Doc/commontex/reportingbugs.tex | 61 - Doc/commontex/typestruct.h | 76 - Doc/dist/dist.tex | 3811 -------------------- Doc/dist/sysconfig.tex | 113 - Doc/doc/doc.tex | 2129 ------------ Doc/ext/building.tex | 143 - Doc/ext/embedding.tex | 316 -- Doc/ext/ext.tex | 67 - Doc/ext/extending.tex | 1390 -------- Doc/ext/newtypes.tex | 1765 ---------- Doc/ext/noddy.c | 54 - Doc/ext/noddy2.c | 190 - Doc/ext/noddy3.c | 243 -- Doc/ext/noddy4.c | 224 -- Doc/ext/run-func.c | 68 - Doc/ext/setup.py | 8 - Doc/ext/shoddy.c | 91 - Doc/ext/test.py | 213 -- Doc/ext/windows.tex | 320 -- Doc/howto/Makefile | 84 - Doc/howto/TODO | 13 - Doc/howto/advocacy.tex | 411 --- Doc/howto/curses.tex | 486 --- Doc/howto/doanddont.tex | 344 -- Doc/howto/functional.rst | 1472 -------- Doc/howto/regex.tex | 1477 -------- Doc/howto/sockets.tex | 465 --- Doc/howto/unicode.rst | 766 ---- Doc/howto/urllib2.rst | 603 ---- Doc/html/about.dat | 24 - Doc/html/about.html | 84 - Doc/html/icons/blank.gif | Bin 1958 -> 0 bytes Doc/html/icons/blank.png | Bin 1031 -> 0 bytes Doc/html/icons/contents.gif | Bin 438 -> 0 bytes Doc/html/icons/contents.png | Bin 649 -> 0 bytes Doc/html/icons/index.gif | Bin 289 -> 0 bytes Doc/html/icons/index.png | Bin 529 -> 0 bytes Doc/html/icons/modules.gif | Bin 385 -> 0 bytes Doc/html/icons/modules.png | Bin 598 -> 0 bytes Doc/html/icons/next.gif | Bin 253 -> 0 bytes Doc/html/icons/next.png | Bin 511 -> 0 bytes Doc/html/icons/previous.gif | Bin 252 -> 0 bytes Doc/html/icons/previous.png | Bin 511 -> 0 bytes Doc/html/icons/pyfav.gif | Bin 125 -> 0 bytes Doc/html/icons/pyfav.png | Bin 240 -> 0 bytes Doc/html/icons/up.gif | Bin 316 -> 0 bytes Doc/html/icons/up.png | Bin 577 -> 0 bytes Doc/html/index.html.in | 140 - Doc/html/stdabout.dat | 54 - Doc/html/style.css | 243 -- Doc/info/Makefile | 82 - Doc/info/README | 21 - Doc/info/python.dir | 11 - Doc/inst/inst.tex | 1112 ------ Doc/lib/archiving.tex | 8 - Doc/lib/asttable.tex | 283 -- Doc/lib/caseless.py | 60 - Doc/lib/compiler.tex | 353 -- Doc/lib/custominterp.tex | 13 - Doc/lib/datatypes.tex | 10 - Doc/lib/development.tex | 13 - Doc/lib/distutils.tex | 38 - Doc/lib/email-dir.py | 115 - Doc/lib/email-mime.py | 32 - Doc/lib/email-simple.py | 25 - Doc/lib/email-unpack.py | 68 - Doc/lib/email.tex | 402 --- Doc/lib/emailcharsets.tex | 244 -- Doc/lib/emailencoders.tex | 47 - Doc/lib/emailexc.tex | 87 - Doc/lib/emailgenerator.tex | 133 - Doc/lib/emailheaders.tex | 178 - Doc/lib/emailiter.tex | 65 - Doc/lib/emailmessage.tex | 561 --- Doc/lib/emailmimebase.tex | 186 - Doc/lib/emailparser.tex | 208 -- Doc/lib/emailutil.tex | 157 - Doc/lib/fileformats.tex | 7 - Doc/lib/filesys.tex | 18 - Doc/lib/frameworks.tex | 10 - Doc/lib/i18n.tex | 11 - Doc/lib/internet.tex | 13 - Doc/lib/ipc.tex | 14 - Doc/lib/language.tex | 10 - Doc/lib/lib.tex | 480 --- Doc/lib/libaifc.tex | 202 -- Doc/lib/libal.tex | 181 - Doc/lib/liballos.tex | 9 - Doc/lib/libanydbm.tex | 85 - Doc/lib/libarray.tex | 241 -- Doc/lib/libascii.tex | 175 - Doc/lib/libast.tex | 57 - Doc/lib/libasynchat.tex | 254 -- Doc/lib/libasyncore.tex | 260 -- Doc/lib/libatexit.tex | 110 - Doc/lib/libaudioop.tex | 259 -- Doc/lib/libbase64.tex | 169 - Doc/lib/libbasehttp.tex | 245 -- Doc/lib/libbastion.tex | 57 - Doc/lib/libbinascii.tex | 147 - Doc/lib/libbinhex.tex | 55 - Doc/lib/libbisect.tex | 84 - Doc/lib/libbltin.tex | 44 - Doc/lib/libbsddb.tex | 208 -- Doc/lib/libbz2.tex | 174 - Doc/lib/libcalendar.tex | 304 -- Doc/lib/libcd.tex | 304 -- Doc/lib/libcfgparser.tex | 322 -- Doc/lib/libcgi.tex | 602 ---- Doc/lib/libcgihttp.tex | 70 - Doc/lib/libcgitb.tex | 67 - Doc/lib/libchunk.tex | 111 - Doc/lib/libcmath.tex | 149 - Doc/lib/libcmd.tex | 198 -- Doc/lib/libcmp.tex | 36 - Doc/lib/libcmpcache.tex | 21 - Doc/lib/libcode.tex | 173 - Doc/lib/libcodecs.tex | 1348 -------- Doc/lib/libcodeop.tex | 103 - Doc/lib/libcollections.tex | 402 --- Doc/lib/libcolorsys.tex | 54 - Doc/lib/libcommands.tex | 66 - Doc/lib/libcompileall.tex | 63 - Doc/lib/libconsts.tex | 31 - Doc/lib/libcontextlib.tex | 130 - Doc/lib/libcookie.tex | 260 -- Doc/lib/libcookielib.tex | 720 ---- Doc/lib/libcopy.tex | 97 - Doc/lib/libcopyreg.tex | 40 - Doc/lib/libcrypt.tex | 54 - Doc/lib/libcrypto.tex | 19 - Doc/lib/libcsv.tex | 538 --- Doc/lib/libctypes.tex | 2450 ------------- Doc/lib/libcurses.tex | 1405 -------- Doc/lib/libcursespanel.tex | 96 - Doc/lib/libdatetime.tex | 1441 -------- Doc/lib/libdbhash.tex | 88 - Doc/lib/libdbm.tex | 61 - Doc/lib/libdecimal.tex | 1313 ------- Doc/lib/libdifflib.tex | 704 ---- Doc/lib/libdircache.tex | 49 - Doc/lib/libdis.tex | 706 ---- Doc/lib/libdl.tex | 101 - Doc/lib/libdoctest.tex | 1974 ----------- Doc/lib/libdocxmlrpc.tex | 109 - Doc/lib/libdumbdbm.tex | 63 - Doc/lib/libdummythread.tex | 22 - Doc/lib/libdummythreading.tex | 22 - Doc/lib/liberrno.tex | 149 - Doc/lib/libetree.tex | 426 --- Doc/lib/libexcs.tex | 440 --- Doc/lib/libfcntl.tex | 174 - Doc/lib/libfilecmp.tex | 142 - Doc/lib/libfileinput.tex | 192 -- Doc/lib/libfl.tex | 507 --- Doc/lib/libfm.tex | 93 - Doc/lib/libfnmatch.tex | 86 - Doc/lib/libformatter.tex | 329 -- Doc/lib/libfpectl.tex | 127 - Doc/lib/libfpformat.tex | 54 - Doc/lib/libftplib.tex | 300 -- Doc/lib/libfuncs.tex | 1345 -------- Doc/lib/libfunctools.tex | 132 - Doc/lib/libfuture.tex | 69 - Doc/lib/libgc.tex | 196 -- Doc/lib/libgdbm.tex | 100 - Doc/lib/libgetopt.tex | 154 - Doc/lib/libgetpass.tex | 36 - Doc/lib/libgettext.tex | 773 ----- Doc/lib/libgl.tex | 224 -- Doc/lib/libglob.tex | 51 - Doc/lib/libgrp.tex | 49 - Doc/lib/libgzip.tex | 70 - Doc/lib/libhashlib.tex | 114 - Doc/lib/libheapq.tex | 225 -- Doc/lib/libhmac.tex | 54 - Doc/lib/libhotshot.tex | 137 - Doc/lib/libhtmllib.tex | 181 - Doc/lib/libhtmlparser.tex | 173 - Doc/lib/libhttplib.tex | 452 --- Doc/lib/libimageop.tex | 100 - Doc/lib/libimaplib.tex | 507 --- Doc/lib/libimgfile.tex | 66 - Doc/lib/libimghdr.tex | 60 - Doc/lib/libimp.tex | 292 -- Doc/lib/libinspect.tex | 393 --- Doc/lib/libintro.tex | 53 - Doc/lib/libitertools.tex | 578 ---- Doc/lib/libjpeg.tex | 80 - Doc/lib/libkeyword.tex | 20 - Doc/lib/liblinecache.tex | 50 - Doc/lib/liblocale.tex | 527 --- Doc/lib/liblogging.tex | 1768 ---------- Doc/lib/libmailbox.tex | 1443 -------- Doc/lib/libmailcap.tex | 82 - Doc/lib/libmain.tex | 16 - Doc/lib/libmarshal.tex | 117 - Doc/lib/libmath.tex | 209 -- Doc/lib/libmd5.tex | 92 - Doc/lib/libmhlib.tex | 168 - Doc/lib/libmimetools.tex | 120 - Doc/lib/libmimetypes.tex | 226 -- Doc/lib/libmimewriter.tex | 80 - Doc/lib/libmimify.tex | 94 - Doc/lib/libmisc.tex | 7 - Doc/lib/libmm.tex | 8 - Doc/lib/libmmap.tex | 171 - Doc/lib/libmodulefinder.tex | 51 - Doc/lib/libmsilib.tex | 485 --- Doc/lib/libmsvcrt.tex | 109 - Doc/lib/libmultifile.tex | 175 - Doc/lib/libmutex.tex | 57 - Doc/lib/libnetrc.tex | 68 - Doc/lib/libnew.tex | 63 - Doc/lib/libni.tex | 63 - Doc/lib/libnis.tex | 63 - Doc/lib/libnntplib.tex | 355 -- Doc/lib/libobjs.tex | 24 - Doc/lib/liboperator.tex | 530 --- Doc/lib/liboptparse.tex | 1888 ---------- Doc/lib/libos.tex | 2045 ----------- Doc/lib/libossaudiodev.tex | 401 --- Doc/lib/libparser.tex | 711 ---- Doc/lib/libpdb.tex | 464 --- Doc/lib/libpickle.tex | 888 ----- Doc/lib/libpickletools.tex | 34 - Doc/lib/libpipes.tex | 84 - Doc/lib/libpkgutil.tex | 45 - Doc/lib/libplatform.tex | 238 -- Doc/lib/libpopen2.tex | 190 - Doc/lib/libpoplib.tex | 187 - Doc/lib/libposix.tex | 97 - Doc/lib/libposixfile.tex | 174 - Doc/lib/libposixpath.tex | 300 -- Doc/lib/libpprint.tex | 210 -- Doc/lib/libprofile.tex | 722 ---- Doc/lib/libpty.tex | 44 - Doc/lib/libpwd.tex | 57 - Doc/lib/libpyclbr.tex | 102 - Doc/lib/libpycompile.tex | 53 - Doc/lib/libpydoc.tex | 67 - Doc/lib/libpyexpat.tex | 777 ----- Doc/lib/libpython.tex | 8 - Doc/lib/libqueue.tex | 145 - Doc/lib/libquopri.tex | 61 - Doc/lib/librandom.tex | 309 -- Doc/lib/libre.tex | 954 ----- Doc/lib/libreadline.tex | 196 -- Doc/lib/librepr.tex | 133 - Doc/lib/libresource.tex | 215 -- Doc/lib/librestricted.tex | 66 - Doc/lib/librexec.tex | 275 -- Doc/lib/librfc822.tex | 336 -- Doc/lib/librlcompleter.tex | 65 - Doc/lib/librobotparser.tex | 66 - Doc/lib/librunpy.tex | 76 - Doc/lib/libsched.tex | 97 - Doc/lib/libselect.tex | 132 - Doc/lib/libsets.tex | 266 -- Doc/lib/libsgi.tex | 7 - Doc/lib/libsgmllib.tex | 271 -- Doc/lib/libsha.tex | 83 - Doc/lib/libshelve.tex | 174 - Doc/lib/libshlex.tex | 279 -- Doc/lib/libshutil.tex | 152 - Doc/lib/libsignal.tex | 173 - Doc/lib/libsimplehttp.tex | 86 - Doc/lib/libsimplexmlrpc.tex | 235 -- Doc/lib/libsite.tex | 93 - Doc/lib/libsmtpd.tex | 63 - Doc/lib/libsmtplib.tex | 338 -- Doc/lib/libsndhdr.tex | 41 - Doc/lib/libsocket.tex | 921 ----- Doc/lib/libsocksvr.tex | 293 -- Doc/lib/libsomeos.tex | 10 - Doc/lib/libspwd.tex | 48 - Doc/lib/libsqlite3.tex | 648 ---- Doc/lib/libstat.tex | 157 - Doc/lib/libstatvfs.tex | 55 - Doc/lib/libstdtypes.tex | 2104 ----------- Doc/lib/libstring.tex | 452 --- Doc/lib/libstringio.tex | 125 - Doc/lib/libstringprep.tex | 136 - Doc/lib/libstrings.tex | 10 - Doc/lib/libstruct.tex | 269 -- Doc/lib/libsubprocess.tex | 407 --- Doc/lib/libsun.tex | 7 - Doc/lib/libsunau.tex | 218 -- Doc/lib/libsunaudio.tex | 146 - Doc/lib/libsymbol.tex | 30 - Doc/lib/libsys.tex | 617 ---- Doc/lib/libsyslog.tex | 76 - Doc/lib/libtabnanny.tex | 62 - Doc/lib/libtarfile.tex | 664 ---- Doc/lib/libtelnetlib.tex | 223 -- Doc/lib/libtempfile.tex | 214 -- Doc/lib/libtermios.tex | 106 - Doc/lib/libtest.tex | 311 -- Doc/lib/libtextwrap.tex | 188 - Doc/lib/libthread.tex | 173 - Doc/lib/libthreading.tex | 728 ---- Doc/lib/libtime.tex | 475 --- Doc/lib/libtimeit.tex | 249 -- Doc/lib/libtoken.tex | 44 - Doc/lib/libtokenize.tex | 119 - Doc/lib/libtrace.tex | 125 - Doc/lib/libtraceback.tex | 157 - Doc/lib/libtty.tex | 34 - Doc/lib/libturtle.tex | 268 -- Doc/lib/libtypes.tex | 215 -- Doc/lib/libundoc.tex | 113 - Doc/lib/libunicodedata.tex | 160 - Doc/lib/libunittest.tex | 978 ------ Doc/lib/libunix.tex | 8 - Doc/lib/liburllib.tex | 494 --- Doc/lib/liburllib2.tex | 872 ----- Doc/lib/liburlparse.tex | 253 -- Doc/lib/libuser.tex | 71 - Doc/lib/libuserdict.tex | 181 - Doc/lib/libuu.tex | 58 - Doc/lib/libuuid.tex | 233 -- Doc/lib/libwarnings.tex | 253 -- Doc/lib/libwave.tex | 171 - Doc/lib/libweakref.tex | 336 -- Doc/lib/libwebbrowser.tex | 173 - Doc/lib/libwhichdb.tex | 20 - Doc/lib/libwinreg.tex | 414 --- Doc/lib/libwinsound.tex | 142 - Doc/lib/libwsgiref.tex | 782 ----- Doc/lib/libxdrlib.tex | 251 -- Doc/lib/libxmllib.tex | 287 -- Doc/lib/libxmlrpclib.tex | 391 --- Doc/lib/libzipfile.tex | 371 -- Doc/lib/libzipimport.tex | 133 - Doc/lib/libzlib.tex | 197 -- Doc/lib/markup.tex | 29 - Doc/lib/mimelib.tex | 65 - Doc/lib/minidom-example.py | 64 - Doc/lib/modules.tex | 9 - Doc/lib/netdata.tex | 6 - Doc/lib/numeric.tex | 13 - Doc/lib/persistence.tex | 15 - Doc/lib/required_1.py | 20 - Doc/lib/required_2.py | 41 - Doc/lib/sqlite3/adapter_datetime.py | 14 - Doc/lib/sqlite3/adapter_point_1.py | 16 - Doc/lib/sqlite3/adapter_point_2.py | 17 - Doc/lib/sqlite3/collation_reverse.py | 15 - Doc/lib/sqlite3/complete_statement.py | 30 - Doc/lib/sqlite3/connect_db_1.py | 3 - Doc/lib/sqlite3/connect_db_2.py | 3 - Doc/lib/sqlite3/converter_point.py | 47 - Doc/lib/sqlite3/countcursors.py | 15 - Doc/lib/sqlite3/createdb.py | 28 - Doc/lib/sqlite3/execsql_fetchonerow.py | 17 - Doc/lib/sqlite3/execsql_printall_1.py | 13 - Doc/lib/sqlite3/execute_1.py | 11 - Doc/lib/sqlite3/execute_2.py | 12 - Doc/lib/sqlite3/execute_3.py | 12 - Doc/lib/sqlite3/executemany_1.py | 24 - Doc/lib/sqlite3/executemany_2.py | 15 - Doc/lib/sqlite3/executescript.py | 24 - Doc/lib/sqlite3/insert_more_people.py | 16 - Doc/lib/sqlite3/md5func.py | 11 - Doc/lib/sqlite3/mysumaggr.py | 20 - Doc/lib/sqlite3/parse_colnames.py | 8 - Doc/lib/sqlite3/pysqlite_datetime.py | 20 - Doc/lib/sqlite3/row_factory.py | 13 - Doc/lib/sqlite3/rowclass.py | 12 - Doc/lib/sqlite3/shared_cache.py | 6 - Doc/lib/sqlite3/shortcut_methods.py | 21 - Doc/lib/sqlite3/simple_tableprinter.py | 26 - Doc/lib/sqlite3/text_factory.py | 42 - Doc/lib/tkinter.tex | 1873 ---------- Doc/lib/tzinfo-examples.py | 139 - Doc/lib/windows.tex | 8 - Doc/lib/xmldom.tex | 928 ----- Doc/lib/xmldomminidom.tex | 285 -- Doc/lib/xmldompulldom.tex | 61 - Doc/lib/xmletree.tex | 27 - Doc/lib/xmlsax.tex | 143 - Doc/lib/xmlsaxhandler.tex | 381 -- Doc/lib/xmlsaxreader.tex | 351 -- Doc/lib/xmlsaxutils.tex | 81 - Doc/mac/libaepack.tex | 82 - Doc/mac/libaetools.tex | 83 - Doc/mac/libaetypes.tex | 135 - Doc/mac/libautogil.tex | 26 - Doc/mac/libcolorpicker.tex | 23 - Doc/mac/libframework.tex | 312 -- Doc/mac/libgensuitemodule.tex | 64 - Doc/mac/libmac.tex | 29 - Doc/mac/libmacic.tex | 123 - Doc/mac/libmacos.tex | 90 - Doc/mac/libmacostools.tex | 106 - Doc/mac/libmacui.tex | 266 -- Doc/mac/libminiae.tex | 65 - Doc/mac/libscrap.tex | 42 - Doc/mac/mac.tex | 88 - Doc/mac/scripting.tex | 101 - Doc/mac/toolbox.tex | 173 - Doc/mac/undoc.tex | 97 - Doc/mac/using.tex | 178 - Doc/paper-a4/pypaper.sty | 17 - Doc/perl/SynopsisTable.pm | 95 - Doc/perl/distutils.perl | 21 - Doc/perl/howto.perl | 12 - Doc/perl/isilo.perl | 12 - Doc/perl/l2hinit.perl | 801 ----- Doc/perl/ltxmarkup.perl | 67 - Doc/perl/manual.perl | 15 - Doc/perl/python.perl | 2178 ------------ Doc/python-docs.txt | 183 - Doc/ref/ref.tex | 68 - Doc/ref/ref1.tex | 136 - Doc/ref/ref2.tex | 731 ---- Doc/ref/ref3.tex | 2230 ------------ Doc/ref/ref4.tex | 215 -- Doc/ref/ref5.tex | 1325 ------- Doc/ref/ref6.tex | 928 ----- Doc/ref/ref7.tex | 544 --- Doc/ref/ref8.tex | 112 - Doc/ref/reswords.py | 23 - Doc/templates/howto.tex | 112 - Doc/templates/manual.tex | 89 - Doc/templates/module.tex | 170 - Doc/templates/whatsnewXY.tex | 149 - Doc/tests/math.tex | 16 - Doc/texinputs/distutils.sty | 33 - Doc/texinputs/fancyhdr.sty | 329 -- Doc/texinputs/fncychap.sty | 433 --- Doc/texinputs/howto.cls | 109 - Doc/texinputs/ltxmarkup.sty | 40 - Doc/texinputs/manual.cls | 155 - Doc/texinputs/pypaper.sty | 18 - Doc/texinputs/python.ist | 11 - Doc/texinputs/python.sty | 1327 ------- Doc/texinputs/underscore.sty | 232 -- Doc/tools/anno-api.py | 71 - Doc/tools/buildindex.py | 388 --- Doc/tools/checkargs.pm | 112 - Doc/tools/cklatex | 26 - Doc/tools/cmpcsyms | 157 - Doc/tools/custlib.py | 78 - Doc/tools/findcsyms | 136 - Doc/tools/findmodrefs | 63 - Doc/tools/findsyms | 128 - Doc/tools/fix_hack | 2 - Doc/tools/fix_libaux.sed | 3 - Doc/tools/fixinfo.el | 15 - Doc/tools/getpagecounts | 97 - Doc/tools/getversioninfo | 71 - Doc/tools/html2texi.pl | 1750 ---------- Doc/tools/indfix.py | 100 - Doc/tools/keywords.py | 19 - Doc/tools/listmodules | 182 - Doc/tools/listmodules.py | 126 - Doc/tools/makesec.sh | 129 - Doc/tools/mkackshtml | 66 - Doc/tools/mkhowto | 659 ---- Doc/tools/mkinfo | 65 - Doc/tools/mkmodindex | 158 - Doc/tools/mkpkglist | 85 - Doc/tools/mksourcepkg | 164 - Doc/tools/node2label.pl | 71 - Doc/tools/prechm.py | 519 --- Doc/tools/push-docs.sh | 138 - Doc/tools/py2texi.el | 970 ------ Doc/tools/refcounts.py | 98 - Doc/tools/rewrite.py | 54 - Doc/tools/sgmlconv/Makefile | 67 - Doc/tools/sgmlconv/README | 58 - Doc/tools/sgmlconv/conversion.xml | 914 ----- Doc/tools/sgmlconv/docfixer.py | 1073 ------ Doc/tools/sgmlconv/esis2sgml.py | 264 -- Doc/tools/sgmlconv/esistools.py | 312 -- Doc/tools/sgmlconv/latex2esis.py | 565 --- Doc/tools/sgmlconv/make.rules | 48 - Doc/tools/support.py | 202 -- Doc/tools/toc2bkm.py | 160 - Doc/tools/undoc_symbols.py | 94 - Doc/tools/update-docs.sh | 31 - Doc/tools/whichlibs | 2 - Doc/tut/glossary.tex | 352 -- Doc/tut/tut.tex | 5946 -------------------------------- Doc/whatsnew/Makefile | 3 - Doc/whatsnew/whatsnew20.tex | 1337 ------- Doc/whatsnew/whatsnew21.tex | 868 ----- Doc/whatsnew/whatsnew22.tex | 1466 -------- Doc/whatsnew/whatsnew23.tex | 2380 ------------- Doc/whatsnew/whatsnew24.tex | 1757 ---------- Doc/whatsnew/whatsnew25.tex | 2539 -------------- Doc/whatsnew/whatsnew26.tex | 268 -- 513 files changed, 154687 deletions(-) delete mode 100644 Doc/ACKS delete mode 100644 Doc/Makefile delete mode 100644 Doc/Makefile.deps delete mode 100644 Doc/README delete mode 100644 Doc/TODO delete mode 100644 Doc/api/abstract.tex delete mode 100644 Doc/api/api.tex delete mode 100644 Doc/api/concrete.tex delete mode 100644 Doc/api/exceptions.tex delete mode 100644 Doc/api/init.tex delete mode 100644 Doc/api/intro.tex delete mode 100644 Doc/api/memory.tex delete mode 100644 Doc/api/newtypes.tex delete mode 100644 Doc/api/refcounting.tex delete mode 100644 Doc/api/refcounts.dat delete mode 100644 Doc/api/utilities.tex delete mode 100644 Doc/api/veryhigh.tex delete mode 100644 Doc/commontex/boilerplate.tex delete mode 100644 Doc/commontex/copyright.tex delete mode 100644 Doc/commontex/license.tex delete mode 100644 Doc/commontex/reportingbugs.tex delete mode 100644 Doc/commontex/typestruct.h delete mode 100644 Doc/dist/dist.tex delete mode 100644 Doc/dist/sysconfig.tex delete mode 100644 Doc/doc/doc.tex delete mode 100644 Doc/ext/building.tex delete mode 100644 Doc/ext/embedding.tex delete mode 100644 Doc/ext/ext.tex delete mode 100644 Doc/ext/extending.tex delete mode 100644 Doc/ext/newtypes.tex delete mode 100644 Doc/ext/noddy.c delete mode 100644 Doc/ext/noddy2.c delete mode 100644 Doc/ext/noddy3.c delete mode 100644 Doc/ext/noddy4.c delete mode 100644 Doc/ext/run-func.c delete mode 100644 Doc/ext/setup.py delete mode 100644 Doc/ext/shoddy.c delete mode 100644 Doc/ext/test.py delete mode 100644 Doc/ext/windows.tex delete mode 100644 Doc/howto/Makefile delete mode 100644 Doc/howto/TODO delete mode 100644 Doc/howto/advocacy.tex delete mode 100644 Doc/howto/curses.tex delete mode 100644 Doc/howto/doanddont.tex delete mode 100644 Doc/howto/functional.rst delete mode 100644 Doc/howto/regex.tex delete mode 100644 Doc/howto/sockets.tex delete mode 100644 Doc/howto/unicode.rst delete mode 100644 Doc/howto/urllib2.rst delete mode 100644 Doc/html/about.dat delete mode 100644 Doc/html/about.html delete mode 100644 Doc/html/icons/blank.gif delete mode 100644 Doc/html/icons/blank.png delete mode 100644 Doc/html/icons/contents.gif delete mode 100644 Doc/html/icons/contents.png delete mode 100644 Doc/html/icons/index.gif delete mode 100644 Doc/html/icons/index.png delete mode 100644 Doc/html/icons/modules.gif delete mode 100644 Doc/html/icons/modules.png delete mode 100644 Doc/html/icons/next.gif delete mode 100644 Doc/html/icons/next.png delete mode 100644 Doc/html/icons/previous.gif delete mode 100644 Doc/html/icons/previous.png delete mode 100644 Doc/html/icons/pyfav.gif delete mode 100644 Doc/html/icons/pyfav.png delete mode 100644 Doc/html/icons/up.gif delete mode 100644 Doc/html/icons/up.png delete mode 100644 Doc/html/index.html.in delete mode 100644 Doc/html/stdabout.dat delete mode 100644 Doc/html/style.css delete mode 100644 Doc/info/Makefile delete mode 100644 Doc/info/README delete mode 100644 Doc/info/python.dir delete mode 100644 Doc/inst/inst.tex delete mode 100644 Doc/lib/archiving.tex delete mode 100644 Doc/lib/asttable.tex delete mode 100755 Doc/lib/caseless.py delete mode 100644 Doc/lib/compiler.tex delete mode 100644 Doc/lib/custominterp.tex delete mode 100644 Doc/lib/datatypes.tex delete mode 100644 Doc/lib/development.tex delete mode 100644 Doc/lib/distutils.tex delete mode 100644 Doc/lib/email-dir.py delete mode 100644 Doc/lib/email-mime.py delete mode 100644 Doc/lib/email-simple.py delete mode 100644 Doc/lib/email-unpack.py delete mode 100644 Doc/lib/email.tex delete mode 100644 Doc/lib/emailcharsets.tex delete mode 100644 Doc/lib/emailencoders.tex delete mode 100644 Doc/lib/emailexc.tex delete mode 100644 Doc/lib/emailgenerator.tex delete mode 100644 Doc/lib/emailheaders.tex delete mode 100644 Doc/lib/emailiter.tex delete mode 100644 Doc/lib/emailmessage.tex delete mode 100644 Doc/lib/emailmimebase.tex delete mode 100644 Doc/lib/emailparser.tex delete mode 100644 Doc/lib/emailutil.tex delete mode 100644 Doc/lib/fileformats.tex delete mode 100644 Doc/lib/filesys.tex delete mode 100644 Doc/lib/frameworks.tex delete mode 100644 Doc/lib/i18n.tex delete mode 100644 Doc/lib/internet.tex delete mode 100644 Doc/lib/ipc.tex delete mode 100644 Doc/lib/language.tex delete mode 100644 Doc/lib/lib.tex delete mode 100644 Doc/lib/libaifc.tex delete mode 100644 Doc/lib/libal.tex delete mode 100644 Doc/lib/liballos.tex delete mode 100644 Doc/lib/libanydbm.tex delete mode 100644 Doc/lib/libarray.tex delete mode 100644 Doc/lib/libascii.tex delete mode 100644 Doc/lib/libast.tex delete mode 100644 Doc/lib/libasynchat.tex delete mode 100644 Doc/lib/libasyncore.tex delete mode 100644 Doc/lib/libatexit.tex delete mode 100644 Doc/lib/libaudioop.tex delete mode 100644 Doc/lib/libbase64.tex delete mode 100644 Doc/lib/libbasehttp.tex delete mode 100644 Doc/lib/libbastion.tex delete mode 100644 Doc/lib/libbinascii.tex delete mode 100644 Doc/lib/libbinhex.tex delete mode 100644 Doc/lib/libbisect.tex delete mode 100644 Doc/lib/libbltin.tex delete mode 100644 Doc/lib/libbsddb.tex delete mode 100644 Doc/lib/libbz2.tex delete mode 100644 Doc/lib/libcalendar.tex delete mode 100644 Doc/lib/libcd.tex delete mode 100644 Doc/lib/libcfgparser.tex delete mode 100644 Doc/lib/libcgi.tex delete mode 100644 Doc/lib/libcgihttp.tex delete mode 100644 Doc/lib/libcgitb.tex delete mode 100644 Doc/lib/libchunk.tex delete mode 100644 Doc/lib/libcmath.tex delete mode 100644 Doc/lib/libcmd.tex delete mode 100644 Doc/lib/libcmp.tex delete mode 100644 Doc/lib/libcmpcache.tex delete mode 100644 Doc/lib/libcode.tex delete mode 100644 Doc/lib/libcodecs.tex delete mode 100644 Doc/lib/libcodeop.tex delete mode 100644 Doc/lib/libcollections.tex delete mode 100644 Doc/lib/libcolorsys.tex delete mode 100644 Doc/lib/libcommands.tex delete mode 100644 Doc/lib/libcompileall.tex delete mode 100644 Doc/lib/libconsts.tex delete mode 100644 Doc/lib/libcontextlib.tex delete mode 100644 Doc/lib/libcookie.tex delete mode 100644 Doc/lib/libcookielib.tex delete mode 100644 Doc/lib/libcopy.tex delete mode 100644 Doc/lib/libcopyreg.tex delete mode 100644 Doc/lib/libcrypt.tex delete mode 100644 Doc/lib/libcrypto.tex delete mode 100644 Doc/lib/libcsv.tex delete mode 100755 Doc/lib/libctypes.tex delete mode 100644 Doc/lib/libcurses.tex delete mode 100644 Doc/lib/libcursespanel.tex delete mode 100644 Doc/lib/libdatetime.tex delete mode 100644 Doc/lib/libdbhash.tex delete mode 100644 Doc/lib/libdbm.tex delete mode 100644 Doc/lib/libdecimal.tex delete mode 100644 Doc/lib/libdifflib.tex delete mode 100644 Doc/lib/libdircache.tex delete mode 100644 Doc/lib/libdis.tex delete mode 100644 Doc/lib/libdl.tex delete mode 100644 Doc/lib/libdoctest.tex delete mode 100644 Doc/lib/libdocxmlrpc.tex delete mode 100644 Doc/lib/libdumbdbm.tex delete mode 100644 Doc/lib/libdummythread.tex delete mode 100644 Doc/lib/libdummythreading.tex delete mode 100644 Doc/lib/liberrno.tex delete mode 100644 Doc/lib/libetree.tex delete mode 100644 Doc/lib/libexcs.tex delete mode 100644 Doc/lib/libfcntl.tex delete mode 100644 Doc/lib/libfilecmp.tex delete mode 100644 Doc/lib/libfileinput.tex delete mode 100644 Doc/lib/libfl.tex delete mode 100644 Doc/lib/libfm.tex delete mode 100644 Doc/lib/libfnmatch.tex delete mode 100644 Doc/lib/libformatter.tex delete mode 100644 Doc/lib/libfpectl.tex delete mode 100644 Doc/lib/libfpformat.tex delete mode 100644 Doc/lib/libftplib.tex delete mode 100644 Doc/lib/libfuncs.tex delete mode 100644 Doc/lib/libfunctools.tex delete mode 100644 Doc/lib/libfuture.tex delete mode 100644 Doc/lib/libgc.tex delete mode 100644 Doc/lib/libgdbm.tex delete mode 100644 Doc/lib/libgetopt.tex delete mode 100644 Doc/lib/libgetpass.tex delete mode 100644 Doc/lib/libgettext.tex delete mode 100644 Doc/lib/libgl.tex delete mode 100644 Doc/lib/libglob.tex delete mode 100644 Doc/lib/libgrp.tex delete mode 100644 Doc/lib/libgzip.tex delete mode 100644 Doc/lib/libhashlib.tex delete mode 100644 Doc/lib/libheapq.tex delete mode 100644 Doc/lib/libhmac.tex delete mode 100644 Doc/lib/libhotshot.tex delete mode 100644 Doc/lib/libhtmllib.tex delete mode 100644 Doc/lib/libhtmlparser.tex delete mode 100644 Doc/lib/libhttplib.tex delete mode 100644 Doc/lib/libimageop.tex delete mode 100644 Doc/lib/libimaplib.tex delete mode 100644 Doc/lib/libimgfile.tex delete mode 100644 Doc/lib/libimghdr.tex delete mode 100644 Doc/lib/libimp.tex delete mode 100644 Doc/lib/libinspect.tex delete mode 100644 Doc/lib/libintro.tex delete mode 100644 Doc/lib/libitertools.tex delete mode 100644 Doc/lib/libjpeg.tex delete mode 100644 Doc/lib/libkeyword.tex delete mode 100644 Doc/lib/liblinecache.tex delete mode 100644 Doc/lib/liblocale.tex delete mode 100644 Doc/lib/liblogging.tex delete mode 100644 Doc/lib/libmailbox.tex delete mode 100644 Doc/lib/libmailcap.tex delete mode 100644 Doc/lib/libmain.tex delete mode 100644 Doc/lib/libmarshal.tex delete mode 100644 Doc/lib/libmath.tex delete mode 100644 Doc/lib/libmd5.tex delete mode 100644 Doc/lib/libmhlib.tex delete mode 100644 Doc/lib/libmimetools.tex delete mode 100644 Doc/lib/libmimetypes.tex delete mode 100644 Doc/lib/libmimewriter.tex delete mode 100644 Doc/lib/libmimify.tex delete mode 100644 Doc/lib/libmisc.tex delete mode 100644 Doc/lib/libmm.tex delete mode 100644 Doc/lib/libmmap.tex delete mode 100644 Doc/lib/libmodulefinder.tex delete mode 100644 Doc/lib/libmsilib.tex delete mode 100644 Doc/lib/libmsvcrt.tex delete mode 100644 Doc/lib/libmultifile.tex delete mode 100644 Doc/lib/libmutex.tex delete mode 100644 Doc/lib/libnetrc.tex delete mode 100644 Doc/lib/libnew.tex delete mode 100644 Doc/lib/libni.tex delete mode 100644 Doc/lib/libnis.tex delete mode 100644 Doc/lib/libnntplib.tex delete mode 100644 Doc/lib/libobjs.tex delete mode 100644 Doc/lib/liboperator.tex delete mode 100644 Doc/lib/liboptparse.tex delete mode 100644 Doc/lib/libos.tex delete mode 100644 Doc/lib/libossaudiodev.tex delete mode 100644 Doc/lib/libparser.tex delete mode 100644 Doc/lib/libpdb.tex delete mode 100644 Doc/lib/libpickle.tex delete mode 100644 Doc/lib/libpickletools.tex delete mode 100644 Doc/lib/libpipes.tex delete mode 100644 Doc/lib/libpkgutil.tex delete mode 100644 Doc/lib/libplatform.tex delete mode 100644 Doc/lib/libpopen2.tex delete mode 100644 Doc/lib/libpoplib.tex delete mode 100644 Doc/lib/libposix.tex delete mode 100644 Doc/lib/libposixfile.tex delete mode 100644 Doc/lib/libposixpath.tex delete mode 100644 Doc/lib/libpprint.tex delete mode 100644 Doc/lib/libprofile.tex delete mode 100644 Doc/lib/libpty.tex delete mode 100644 Doc/lib/libpwd.tex delete mode 100644 Doc/lib/libpyclbr.tex delete mode 100644 Doc/lib/libpycompile.tex delete mode 100644 Doc/lib/libpydoc.tex delete mode 100644 Doc/lib/libpyexpat.tex delete mode 100644 Doc/lib/libpython.tex delete mode 100644 Doc/lib/libqueue.tex delete mode 100644 Doc/lib/libquopri.tex delete mode 100644 Doc/lib/librandom.tex delete mode 100644 Doc/lib/libre.tex delete mode 100644 Doc/lib/libreadline.tex delete mode 100644 Doc/lib/librepr.tex delete mode 100644 Doc/lib/libresource.tex delete mode 100644 Doc/lib/librestricted.tex delete mode 100644 Doc/lib/librexec.tex delete mode 100644 Doc/lib/librfc822.tex delete mode 100644 Doc/lib/librlcompleter.tex delete mode 100644 Doc/lib/librobotparser.tex delete mode 100644 Doc/lib/librunpy.tex delete mode 100644 Doc/lib/libsched.tex delete mode 100644 Doc/lib/libselect.tex delete mode 100644 Doc/lib/libsets.tex delete mode 100644 Doc/lib/libsgi.tex delete mode 100644 Doc/lib/libsgmllib.tex delete mode 100644 Doc/lib/libsha.tex delete mode 100644 Doc/lib/libshelve.tex delete mode 100644 Doc/lib/libshlex.tex delete mode 100644 Doc/lib/libshutil.tex delete mode 100644 Doc/lib/libsignal.tex delete mode 100644 Doc/lib/libsimplehttp.tex delete mode 100644 Doc/lib/libsimplexmlrpc.tex delete mode 100644 Doc/lib/libsite.tex delete mode 100644 Doc/lib/libsmtpd.tex delete mode 100644 Doc/lib/libsmtplib.tex delete mode 100644 Doc/lib/libsndhdr.tex delete mode 100644 Doc/lib/libsocket.tex delete mode 100644 Doc/lib/libsocksvr.tex delete mode 100644 Doc/lib/libsomeos.tex delete mode 100644 Doc/lib/libspwd.tex delete mode 100644 Doc/lib/libsqlite3.tex delete mode 100644 Doc/lib/libstat.tex delete mode 100644 Doc/lib/libstatvfs.tex delete mode 100644 Doc/lib/libstdtypes.tex delete mode 100644 Doc/lib/libstring.tex delete mode 100644 Doc/lib/libstringio.tex delete mode 100644 Doc/lib/libstringprep.tex delete mode 100644 Doc/lib/libstrings.tex delete mode 100644 Doc/lib/libstruct.tex delete mode 100644 Doc/lib/libsubprocess.tex delete mode 100644 Doc/lib/libsun.tex delete mode 100644 Doc/lib/libsunau.tex delete mode 100644 Doc/lib/libsunaudio.tex delete mode 100644 Doc/lib/libsymbol.tex delete mode 100644 Doc/lib/libsys.tex delete mode 100644 Doc/lib/libsyslog.tex delete mode 100644 Doc/lib/libtabnanny.tex delete mode 100644 Doc/lib/libtarfile.tex delete mode 100644 Doc/lib/libtelnetlib.tex delete mode 100644 Doc/lib/libtempfile.tex delete mode 100644 Doc/lib/libtermios.tex delete mode 100644 Doc/lib/libtest.tex delete mode 100644 Doc/lib/libtextwrap.tex delete mode 100644 Doc/lib/libthread.tex delete mode 100644 Doc/lib/libthreading.tex delete mode 100644 Doc/lib/libtime.tex delete mode 100644 Doc/lib/libtimeit.tex delete mode 100644 Doc/lib/libtoken.tex delete mode 100644 Doc/lib/libtokenize.tex delete mode 100644 Doc/lib/libtrace.tex delete mode 100644 Doc/lib/libtraceback.tex delete mode 100644 Doc/lib/libtty.tex delete mode 100644 Doc/lib/libturtle.tex delete mode 100644 Doc/lib/libtypes.tex delete mode 100644 Doc/lib/libundoc.tex delete mode 100644 Doc/lib/libunicodedata.tex delete mode 100644 Doc/lib/libunittest.tex delete mode 100644 Doc/lib/libunix.tex delete mode 100644 Doc/lib/liburllib.tex delete mode 100644 Doc/lib/liburllib2.tex delete mode 100644 Doc/lib/liburlparse.tex delete mode 100644 Doc/lib/libuser.tex delete mode 100644 Doc/lib/libuserdict.tex delete mode 100644 Doc/lib/libuu.tex delete mode 100644 Doc/lib/libuuid.tex delete mode 100644 Doc/lib/libwarnings.tex delete mode 100644 Doc/lib/libwave.tex delete mode 100644 Doc/lib/libweakref.tex delete mode 100644 Doc/lib/libwebbrowser.tex delete mode 100644 Doc/lib/libwhichdb.tex delete mode 100644 Doc/lib/libwinreg.tex delete mode 100644 Doc/lib/libwinsound.tex delete mode 100755 Doc/lib/libwsgiref.tex delete mode 100644 Doc/lib/libxdrlib.tex delete mode 100644 Doc/lib/libxmllib.tex delete mode 100644 Doc/lib/libxmlrpclib.tex delete mode 100644 Doc/lib/libzipfile.tex delete mode 100644 Doc/lib/libzipimport.tex delete mode 100644 Doc/lib/libzlib.tex delete mode 100644 Doc/lib/markup.tex delete mode 100644 Doc/lib/mimelib.tex delete mode 100644 Doc/lib/minidom-example.py delete mode 100644 Doc/lib/modules.tex delete mode 100644 Doc/lib/netdata.tex delete mode 100644 Doc/lib/numeric.tex delete mode 100644 Doc/lib/persistence.tex delete mode 100755 Doc/lib/required_1.py delete mode 100755 Doc/lib/required_2.py delete mode 100644 Doc/lib/sqlite3/adapter_datetime.py delete mode 100644 Doc/lib/sqlite3/adapter_point_1.py delete mode 100644 Doc/lib/sqlite3/adapter_point_2.py delete mode 100644 Doc/lib/sqlite3/collation_reverse.py delete mode 100644 Doc/lib/sqlite3/complete_statement.py delete mode 100644 Doc/lib/sqlite3/connect_db_1.py delete mode 100644 Doc/lib/sqlite3/connect_db_2.py delete mode 100644 Doc/lib/sqlite3/converter_point.py delete mode 100644 Doc/lib/sqlite3/countcursors.py delete mode 100644 Doc/lib/sqlite3/createdb.py delete mode 100644 Doc/lib/sqlite3/execsql_fetchonerow.py delete mode 100644 Doc/lib/sqlite3/execsql_printall_1.py delete mode 100644 Doc/lib/sqlite3/execute_1.py delete mode 100644 Doc/lib/sqlite3/execute_2.py delete mode 100644 Doc/lib/sqlite3/execute_3.py delete mode 100644 Doc/lib/sqlite3/executemany_1.py delete mode 100644 Doc/lib/sqlite3/executemany_2.py delete mode 100644 Doc/lib/sqlite3/executescript.py delete mode 100644 Doc/lib/sqlite3/insert_more_people.py delete mode 100644 Doc/lib/sqlite3/md5func.py delete mode 100644 Doc/lib/sqlite3/mysumaggr.py delete mode 100644 Doc/lib/sqlite3/parse_colnames.py delete mode 100644 Doc/lib/sqlite3/pysqlite_datetime.py delete mode 100644 Doc/lib/sqlite3/row_factory.py delete mode 100644 Doc/lib/sqlite3/rowclass.py delete mode 100644 Doc/lib/sqlite3/shared_cache.py delete mode 100644 Doc/lib/sqlite3/shortcut_methods.py delete mode 100644 Doc/lib/sqlite3/simple_tableprinter.py delete mode 100644 Doc/lib/sqlite3/text_factory.py delete mode 100644 Doc/lib/tkinter.tex delete mode 100644 Doc/lib/tzinfo-examples.py delete mode 100644 Doc/lib/windows.tex delete mode 100644 Doc/lib/xmldom.tex delete mode 100644 Doc/lib/xmldomminidom.tex delete mode 100644 Doc/lib/xmldompulldom.tex delete mode 100644 Doc/lib/xmletree.tex delete mode 100644 Doc/lib/xmlsax.tex delete mode 100644 Doc/lib/xmlsaxhandler.tex delete mode 100644 Doc/lib/xmlsaxreader.tex delete mode 100644 Doc/lib/xmlsaxutils.tex delete mode 100644 Doc/mac/libaepack.tex delete mode 100644 Doc/mac/libaetools.tex delete mode 100644 Doc/mac/libaetypes.tex delete mode 100644 Doc/mac/libautogil.tex delete mode 100644 Doc/mac/libcolorpicker.tex delete mode 100644 Doc/mac/libframework.tex delete mode 100644 Doc/mac/libgensuitemodule.tex delete mode 100644 Doc/mac/libmac.tex delete mode 100644 Doc/mac/libmacic.tex delete mode 100644 Doc/mac/libmacos.tex delete mode 100644 Doc/mac/libmacostools.tex delete mode 100644 Doc/mac/libmacui.tex delete mode 100644 Doc/mac/libminiae.tex delete mode 100644 Doc/mac/libscrap.tex delete mode 100644 Doc/mac/mac.tex delete mode 100644 Doc/mac/scripting.tex delete mode 100644 Doc/mac/toolbox.tex delete mode 100644 Doc/mac/undoc.tex delete mode 100644 Doc/mac/using.tex delete mode 100644 Doc/paper-a4/pypaper.sty delete mode 100644 Doc/perl/SynopsisTable.pm delete mode 100644 Doc/perl/distutils.perl delete mode 100644 Doc/perl/howto.perl delete mode 100644 Doc/perl/isilo.perl delete mode 100644 Doc/perl/l2hinit.perl delete mode 100644 Doc/perl/ltxmarkup.perl delete mode 100644 Doc/perl/manual.perl delete mode 100644 Doc/perl/python.perl delete mode 100644 Doc/python-docs.txt delete mode 100644 Doc/ref/ref.tex delete mode 100644 Doc/ref/ref1.tex delete mode 100644 Doc/ref/ref2.tex delete mode 100644 Doc/ref/ref3.tex delete mode 100644 Doc/ref/ref4.tex delete mode 100644 Doc/ref/ref5.tex delete mode 100644 Doc/ref/ref6.tex delete mode 100644 Doc/ref/ref7.tex delete mode 100644 Doc/ref/ref8.tex delete mode 100644 Doc/ref/reswords.py delete mode 100644 Doc/templates/howto.tex delete mode 100644 Doc/templates/manual.tex delete mode 100644 Doc/templates/module.tex delete mode 100644 Doc/templates/whatsnewXY.tex delete mode 100644 Doc/tests/math.tex delete mode 100644 Doc/texinputs/distutils.sty delete mode 100644 Doc/texinputs/fancyhdr.sty delete mode 100644 Doc/texinputs/fncychap.sty delete mode 100644 Doc/texinputs/howto.cls delete mode 100644 Doc/texinputs/ltxmarkup.sty delete mode 100644 Doc/texinputs/manual.cls delete mode 100644 Doc/texinputs/pypaper.sty delete mode 100644 Doc/texinputs/python.ist delete mode 100644 Doc/texinputs/python.sty delete mode 100644 Doc/texinputs/underscore.sty delete mode 100755 Doc/tools/anno-api.py delete mode 100755 Doc/tools/buildindex.py delete mode 100644 Doc/tools/checkargs.pm delete mode 100755 Doc/tools/cklatex delete mode 100755 Doc/tools/cmpcsyms delete mode 100644 Doc/tools/custlib.py delete mode 100755 Doc/tools/findcsyms delete mode 100755 Doc/tools/findmodrefs delete mode 100755 Doc/tools/findsyms delete mode 100755 Doc/tools/fix_hack delete mode 100755 Doc/tools/fix_libaux.sed delete mode 100644 Doc/tools/fixinfo.el delete mode 100755 Doc/tools/getpagecounts delete mode 100755 Doc/tools/getversioninfo delete mode 100755 Doc/tools/html2texi.pl delete mode 100755 Doc/tools/indfix.py delete mode 100644 Doc/tools/keywords.py delete mode 100755 Doc/tools/listmodules delete mode 100644 Doc/tools/listmodules.py delete mode 100755 Doc/tools/makesec.sh delete mode 100755 Doc/tools/mkackshtml delete mode 100755 Doc/tools/mkhowto delete mode 100755 Doc/tools/mkinfo delete mode 100755 Doc/tools/mkmodindex delete mode 100755 Doc/tools/mkpkglist delete mode 100755 Doc/tools/mksourcepkg delete mode 100755 Doc/tools/node2label.pl delete mode 100644 Doc/tools/prechm.py delete mode 100755 Doc/tools/push-docs.sh delete mode 100644 Doc/tools/py2texi.el delete mode 100644 Doc/tools/refcounts.py delete mode 100644 Doc/tools/rewrite.py delete mode 100644 Doc/tools/sgmlconv/Makefile delete mode 100644 Doc/tools/sgmlconv/README delete mode 100644 Doc/tools/sgmlconv/conversion.xml delete mode 100755 Doc/tools/sgmlconv/docfixer.py delete mode 100755 Doc/tools/sgmlconv/esis2sgml.py delete mode 100644 Doc/tools/sgmlconv/esistools.py delete mode 100755 Doc/tools/sgmlconv/latex2esis.py delete mode 100644 Doc/tools/sgmlconv/make.rules delete mode 100644 Doc/tools/support.py delete mode 100755 Doc/tools/toc2bkm.py delete mode 100644 Doc/tools/undoc_symbols.py delete mode 100755 Doc/tools/update-docs.sh delete mode 100755 Doc/tools/whichlibs delete mode 100644 Doc/tut/glossary.tex delete mode 100644 Doc/tut/tut.tex delete mode 100644 Doc/whatsnew/Makefile delete mode 100644 Doc/whatsnew/whatsnew20.tex delete mode 100644 Doc/whatsnew/whatsnew21.tex delete mode 100644 Doc/whatsnew/whatsnew22.tex delete mode 100644 Doc/whatsnew/whatsnew23.tex delete mode 100644 Doc/whatsnew/whatsnew24.tex delete mode 100644 Doc/whatsnew/whatsnew25.tex delete mode 100644 Doc/whatsnew/whatsnew26.tex 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 bda244a..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= 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 About this document... 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=whatsnew26 - -# 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 -# . - -# 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 $@ - -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 625a097..0000000 --- a/Doc/Makefile.deps +++ /dev/null @@ -1,382 +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/compiler.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/libsets.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/libposixfile.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/libmimewriter.tex \ - lib/libbinascii.tex \ - lib/libmm.tex \ - lib/libaudioop.tex \ - lib/libimageop.tex \ - lib/libaifc.tex \ - lib/libjpeg.tex \ - lib/libossaudiodev.tex \ - lib/libcrypto.tex \ - lib/libhashlib.tex \ - lib/libmd5.tex \ - lib/libsha.tex \ - lib/libhmac.tex \ - lib/libsgi.tex \ - lib/libal.tex \ - lib/libcd.tex \ - lib/libfl.tex \ - lib/libfm.tex \ - lib/libgl.tex \ - lib/libimgfile.tex \ - lib/libsun.tex \ - lib/libxdrlib.tex \ - lib/libimghdr.tex \ - lib/librestricted.tex \ - lib/librexec.tex \ - lib/libbastion.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/libmimify.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/libsunaudio.tex \ - lib/libfileinput.tex \ - lib/libimaplib.tex \ - lib/libpoplib.tex \ - lib/libcalendar.tex \ - lib/libpopen2.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 or -). - -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 ; 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 . -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 (). - -To create info files: - - Note that info support is currently being revised using new - conversion tools by Michael Ernst . - - - 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 - . - - - 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 - . - - - 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: - . - - -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 . 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.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 . (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 .) Heavily impacts one - chapter of the Python/C API manual. - -* Missing PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords(), - Py_BuildValue(). Information requested by Greg Kochanski - . 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 . - -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 . - -* 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 - . 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 5bd5a9a..0000000 --- a/Doc/api/abstract.tex +++ /dev/null @@ -1,1057 +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{apply(\var{callable_object}, \var{args}, \var{kw})} - or \samp{\var{callable_object}(*\var{args}, **\var{kw})}. - \bifuncindex{apply} - \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{apply(\var{callable_object}, \var{args})} or - \samp{\var{callable_object}(*\var{args})}. - \bifuncindex{apply} -\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{apply(\var{callable}, - \var{args})} or \samp{\var{callable}(*\var{args})}. - Note that if you only pass \ctype{PyObject *} args, - \cfunction{PyObject_CallFunctionObjArgs} is a faster alternative. - \bifuncindex{apply} -\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}{int}{PyNumber_Coerce}{PyObject **p1, PyObject **p2} - This function takes the addresses of two variables of type - \ctype{PyObject*}. If the objects pointed to by \code{*\var{p1}} - and \code{*\var{p2}} have the same type, increment their reference - count and return \code{0} (success). If the objects can be converted - to a common numeric type, replace \code{*p1} and \code{*p2} by their - converted value (with 'new' reference counts), and return \code{0}. - If no conversion is possible, or if some other error occurs, return - \code{-1} (failure) and don't increment the reference counts. The - call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python - statement \samp{\var{o1}, \var{o2} = coerce(\var{o1}, \var{o2})}. - \bifuncindex{coerce} -\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 2716db1..0000000 --- a/Doc/api/concrete.tex +++ /dev/null @@ -1,3238 +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, char **pend} - Create a \ctype{PyFloatObject} object based on the string value in - \var{str}, or \NULL{} on failure. The \var{pend} argument is ignored. It - remains only for backward compatibility. -\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}{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} - - -\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 2dabeee..0000000 --- a/Doc/api/exceptions.tex +++ /dev/null @@ -1,442 +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 -\withsubitem{(in module sys)}{ - \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}} -the Python variables \code{sys.exc_type}, \code{sys.exc_value} and -\code{sys.exc_traceback}. API functions exist to interact with the -error indicator in various ways. There is a separate error indicator -for each thread. - -% XXX Order of these should be more thoughtful. -% Either alphabetical or some kind of structure. - -\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_Warn}{PyObject *category, char *message} - Issue a warning message. The \var{category} argument is a warning - category (see below) or \NULL; the \var{message} argument is a - message string. The warning will appear to be issued from the function - calling \cfunction{PyErr_Warn()}, equivalent to calling - \cfunction{PyErr_WarnEx()} with a \var{stacklevel} of 1. - - Deprecated; use \cfunction{PyErr_WarnEx()} instead. -\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_StandardError\ttindex{PyExc_StandardError}}{\exception{StandardError}}{(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 80650fe..0000000 --- a/Doc/api/intro.tex +++ /dev/null @@ -1,627 +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{}, \code{}, \code{}, -\code{}, and \code{} (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 }; 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 -\withsubitem{(in module sys)}{ - \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}} -objects \code{sys.exc_type}, \code{sys.exc_value}, and -\code{sys.exc_traceback}; 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_type} -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 847cd87..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 b8aaad5..0000000 --- a/Doc/api/refcounts.dat +++ /dev/null @@ -1,1756 +0,0 @@ -# Created by Skip Montanaro . - -# Format: -# function ':' type ':' [param name] ':' [refcount effect] ':' [comment] -# If the param name slot is empty, that line corresponds to the function's -# return value, otherwise it's the type of the named parameter. - -# The first line of a function block gives type/refcount information for the -# function's return value. Successive lines with the same function name -# correspond to the function's parameter list and appear in the order the -# parameters appear in the function's prototype. - -# For readability, each function's lines are surrounded by a blank line. -# The blocks are sorted alphabetically by function name. - -# Refcount behavior is given for all PyObject* types: 0 (no change), +1 -# (increment) and -1 (decrement). A blank refcount field indicates the -# parameter or function value is not a PyObject* and is therefore not -# subject to reference counting. A special case for the value "null" -# (without quotes) is used for functions which return a PyObject* type but -# always return NULL. This is used by some of the PyErr_*() functions, in -# particular. - -# XXX NOTE: the 0/+1/-1 refcount information for arguments is -# confusing! Much more useful would be to indicate whether the -# function "steals" a reference to the argument or not. Take for -# example PyList_SetItem(list, i, item). This lists as a 0 change for -# both the list and the item arguments. However, in fact it steals a -# reference to the item argument! - -# The parameter names are as they appear in the API manual, not the source -# code. - -PyBool_FromLong:PyObject*::+1: -PyBool_FromLong:long:v:0: - -PyBuffer_FromObject:PyObject*::+1: -PyBuffer_FromObject:PyObject*:base:+1: -PyBuffer_FromObject:int:offset:: -PyBuffer_FromObject:int:size:: - -PyBuffer_FromReadWriteObject:PyObject*::+1: -PyBuffer_FromReadWriteObject:PyObject*:base:+1: -PyBuffer_FromReadWriteObject:int:offset:: -PyBuffer_FromReadWriteObject:int:size:: - -PyBuffer_FromMemory:PyObject*::+1: -PyBuffer_FromMemory:void*:ptr:: -PyBuffer_FromMemory:int:size:: - -PyBuffer_FromReadWriteMemory:PyObject*::+1: -PyBuffer_FromReadWriteMemory:void*:ptr:: -PyBuffer_FromReadWriteMemory:int:size:: - -PyBuffer_New:PyObject*::+1: -PyBuffer_New:int:size:: - -PyCObject_AsVoidPtr:void*::: -PyCObject_AsVoidPtr:PyObject*:self:0: - -PyCObject_FromVoidPtr:PyObject*::+1: -PyCObject_FromVoidPtr:void*:cobj:: -PyCObject_FromVoidPtr::void (* destr)(void* ):: - -PyCObject_FromVoidPtrAndDesc:PyObject*::+1: -PyCObject_FromVoidPtrAndDesc:void*:cobj:: -PyCObject_FromVoidPtrAndDesc:void*:desc:: -PyCObject_FromVoidPtrAndDesc:void(*)(void*,void*):destr:: - -PyCObject_GetDesc:void*::: -PyCObject_GetDesc:PyObject*:self:0: - -PyCell_New:PyObject*::+1: -PyCell_New:PyObject*:ob:0: - -PyCell_GET:PyObject*::0: -PyCell_GET:PyObject*:ob:0: - -PyCell_Get:PyObject*::+1: -PyCell_Get:PyObject*:cell:0: - -PyCell_SET:void::: -PyCell_SET:PyObject*:cell:0: -PyCell_SET:PyObject*:value:0: - -PyCell_Set:int::: -PyCell_Set:PyObject*:cell:0: -PyCell_Set:PyObject*:value:0: - -PyCallIter_New:PyObject*::+1: -PyCallIter_New:PyObject*:callable:: -PyCallIter_New:PyObject*:sentinel:: - -PyCallable_Check:int::: -PyCallable_Check:PyObject*:o:0: - -PyComplex_AsCComplex:Py_complex::: -PyComplex_AsCComplex:PyObject*:op:0: - -PyComplex_Check:int::: -PyComplex_Check:PyObject*:p:0: - -PyComplex_FromCComplex:PyObject*::+1: -PyComplex_FromCComplex::Py_complex v:: - -PyComplex_FromDoubles:PyObject*::+1: -PyComplex_FromDoubles::double real:: -PyComplex_FromDoubles::double imag:: - -PyComplex_ImagAsDouble:double::: -PyComplex_ImagAsDouble:PyObject*:op:0: - -PyComplex_RealAsDouble:double::: -PyComplex_RealAsDouble:PyObject*:op:0: - -PyDate_FromDate:PyObject*::+1: -PyDate_FromDate:int:year:: -PyDate_FromDate:int:month:: -PyDate_FromDate:int:day:: - -PyDate_FromTimestamp:PyObject*::+1: -PyDate_FromTimestamp:PyObject*:args:0: - -PyDateTime_FromDateAndTime:PyObject*::+1: -PyDateTime_FromDateAndTime:int:year:: -PyDateTime_FromDateAndTime:int:month:: -PyDateTime_FromDateAndTime:int:day:: -PyDateTime_FromDateAndTime:int:hour:: -PyDateTime_FromDateAndTime:int:minute:: -PyDateTime_FromDateAndTime:int:second:: -PyDateTime_FromDateAndTime:int:usecond:: - -PyDateTime_FromTimestamp:PyObject*::+1: -PyDateTime_FromTimestamp:PyObject*:args:0: - -PyDelta_FromDSU:PyObject*::+1: -PyDelta_FromDSU:int:days:: -PyDelta_FromDSU:int:seconds:: -PyDelta_FromDSU:int:useconds:: - -PyDescr_NewClassMethod:PyObject*::+1: -PyDescr_NewClassMethod:PyTypeObject*:type:: -PyDescr_NewClassMethod:PyMethodDef*:method:: - -PyDescr_NewGetSet:PyObject*::+1: -PyDescr_NewGetSet:PyTypeObject*:type:: -PyDescr_NewGetSet:PyGetSetDef*:getset:: - -PyDescr_NewMember:PyObject*::+1: -PyDescr_NewMember:PyTypeObject*:type:: -PyDescr_NewMember:PyMemberDef*:member:: - -PyDescr_NewMethod:PyObject*::+1: -PyDescr_NewMethod:PyTypeObject*:type:: -PyDescr_NewMethod:PyMethodDef*:meth:: - -PyDescr_NewWrapper:PyObject*::+1: -PyDescr_NewWrapper:PyTypeObject*:type:: -PyDescr_NewWrapper:struct wrapperbase*:base:: -PyDescr_NewWrapper:void*:wrapped:: - -PyDict_Check:int::: -PyDict_Check:PyObject*:p:0: - -PyDict_Clear:void::: -PyDict_Clear:PyObject*:p:0: - -PyDict_DelItem:int::: -PyDict_DelItem:PyObject*:p:0: -PyDict_DelItem:PyObject*:key:0: - -PyDict_DelItemString:int::: -PyDict_DelItemString:PyObject*:p:0: -PyDict_DelItemString:char*:key:: - -PyDict_GetItem:PyObject*::0:0 -PyDict_GetItem:PyObject*:p:0: -PyDict_GetItem:PyObject*:key:0: - -PyDict_GetItemString:PyObject*::0: -PyDict_GetItemString:PyObject*:p:0: -PyDict_GetItemString:char*:key:: - -PyDict_Items:PyObject*::+1: -PyDict_Items:PyObject*:p:0: - -PyDict_Keys:PyObject*::+1: -PyDict_Keys:PyObject*:p:0: - -PyDict_New:PyObject*::+1: - -PyDict_Copy:PyObject*::+1: -PyDict_Copy:PyObject*:p:0: - -PyDict_Next:int::: -PyDict_Next:PyObject*:p:0: -PyDict_Next:int:ppos:: -PyDict_Next:PyObject**:pkey:0: -PyDict_Next:PyObject**:pvalue:0: - -PyDict_SetItem:int::: -PyDict_SetItem:PyObject*:p:0: -PyDict_SetItem:PyObject*:key:+1: -PyDict_SetItem:PyObject*:val:+1: - -PyDict_SetItemString:int::: -PyDict_SetItemString:PyObject*:p:0: -PyDict_SetItemString:char*:key:: -PyDict_SetItemString:PyObject*:val:+1: - -PyDict_Size:int::: -PyDict_Size:PyObject*:p:: - -PyDict_Values:PyObject*::+1: -PyDict_Values:PyObject*:p:0: - -PyDictProxy_New:PyObject*::+1: -PyDictProxy_New:PyObject*:dict:0: - -PyErr_BadArgument:int::: - -PyErr_BadInternalCall:void::: - -PyErr_CheckSignals:int::: - -PyErr_Clear:void::: - -PyErr_ExceptionMatches:int::: -PyErr_ExceptionMatches:PyObject*:exc:0: - -PyErr_Fetch:void::: -PyErr_Fetch:PyObject**:ptype:0: -PyErr_Fetch:PyObject**:pvalue:0: -PyErr_Fetch:PyObject**:ptraceback:0: - -PyErr_GivenExceptionMatches:int::: -PyErr_GivenExceptionMatches:PyObject*:given:0: -PyErr_GivenExceptionMatches:PyObject*:exc:0: - -PyErr_NewException:PyObject*::+1: -PyErr_NewException:char*:name:: -PyErr_NewException:PyObject*:base:0: -PyErr_NewException:PyObject*:dict:0: - -PyErr_NoMemory:PyObject*::null: - -PyErr_NormalizeException:void::: -PyErr_NormalizeException:PyObject**:exc::??? -PyErr_NormalizeException:PyObject**:val::??? -PyErr_NormalizeException:PyObject**:tb::??? - -PyErr_Occurred:PyObject*::0: - -PyErr_Print:void::: - -PyErr_Restore:void::: -PyErr_Restore:PyObject*:type:-1: -PyErr_Restore:PyObject*:value:-1: -PyErr_Restore:PyObject*:traceback:-1: - -PyErr_SetExcFromWindowsErr:PyObject*::null: -PyErr_SetExcFromWindowsErr:PyObject*:type:0: -PyErr_SetExcFromWindowsErr:int:ierr:: - -PyErr_SetExcFromWindowsErrWithFilename:PyObject*::null: -PyErr_SetExcFromWindowsErrWithFilename:PyObject*:type:0: -PyErr_SetExcFromWindowsErrWithFilename:int:ierr:: -PyErr_SetExcFromWindowsErrWithFilename:char*:filename:: - -PyErr_SetFromErrno:PyObject*::null: -PyErr_SetFromErrno:PyObject*:type:0: - -PyErr_SetFromErrnoWithFilename:PyObject*::null: -PyErr_SetFromErrnoWithFilename:PyObject*:type:0: -PyErr_SetFromErrnoWithFilename:char*:filename:: - -PyErr_SetFromWindowsErr:PyObject*::null: -PyErr_SetFromWindowsErr:int:ierr:: - -PyErr_SetFromWindowsErrWithFilename:PyObject*::null: -PyErr_SetFromWindowsErrWithFilename:int:ierr:: -PyErr_SetFromWindowsErrWithFilename:char*:filename:: - -PyErr_SetInterrupt:void::: - -PyErr_SetNone:void::: -PyErr_SetNone:PyObject*:type:+1: - -PyErr_SetObject:void::: -PyErr_SetObject:PyObject*:type:+1: -PyErr_SetObject:PyObject*:value:+1: - -PyErr_SetString:void::: -PyErr_SetString:PyObject*:type:+1: -PyErr_SetString:char*:message:: - -PyErr_Format:PyObject*::null: -PyErr_Format:PyObject*:exception:+1: -PyErr_Format:char*:format:: -PyErr_Format::...:: - -PyErr_Warn:int::: -PyErr_Warn:PyObject*:category:0: -PyErr_Warn:char*:message:: - -PyErr_WarnEx:int::: -PyErr_WarnEx:PyObject*:category:0: -PyErr_WarnEx:const char*:message:: -PyErr_WarnEx:Py_ssize_t:stack_level:: - -PyEval_AcquireLock:void::: - -PyEval_AcquireThread:void::: -PyEval_AcquireThread:PyThreadState*:tstate:: - -PyEval_InitThreads:void::: - -PyEval_ReleaseLock:void::: - -PyEval_ReleaseThread:void::: -PyEval_ReleaseThread:PyThreadState*:tstate:: - -PyEval_RestoreThread:void::: -PyEval_RestoreThread:PyThreadState*:tstate:: - -PyEval_SaveThread:PyThreadState*::: - -PyEval_EvalCode:PyObject*::+1: -PyEval_EvalCode:PyCodeObject*:co:0: -PyEval_EvalCode:PyObject*:globals:0: -PyEval_EvalCode:PyObject*:locals:0: - -PyFile_AsFile:FILE*::: -PyFile_AsFile:PyFileObject*:p:0: - -PyFile_Check:int::: -PyFile_Check:PyObject*:p:0: - -PyFile_FromFile:PyObject*::+1: -PyFile_FromFile:FILE*:fp:: -PyFile_FromFile:char*:name:: -PyFile_FromFile:char*:mode:: -PyFile_FromFile:int(*:close):: - -PyFile_FromString:PyObject*::+1: -PyFile_FromString:char*:name:: -PyFile_FromString:char*:mode:: - -PyFile_GetLine:PyObject*::+1: -PyFile_GetLine:PyObject*:p:: -PyFile_GetLine:int:n:: - -PyFile_Name:PyObject*::0: -PyFile_Name:PyObject*:p:0: - -PyFile_SetBufSize:void::: -PyFile_SetBufSize:PyFileObject*:p:0: -PyFile_SetBufSize:int:n:: - -PyFile_SoftSpace:int::: -PyFile_SoftSpace:PyFileObject*:p:0: -PyFile_SoftSpace:int:newflag:: - -PyFile_WriteObject:int::: -PyFile_WriteObject:PyObject*:obj:0: -PyFile_WriteObject:PyFileObject*:p:0: -PyFile_WriteObject:int:flags:: - -PyFile_WriteString:int::: -PyFile_WriteString:const char*:s:: -PyFile_WriteString:PyFileObject*:p:0: -PyFile_WriteString:int:flags:: - -PyFloat_AS_DOUBLE:double::: -PyFloat_AS_DOUBLE:PyObject*:pyfloat:0: - -PyFloat_AsDouble:double::: -PyFloat_AsDouble:PyObject*:pyfloat:0: - -PyFloat_Check:int::: -PyFloat_Check:PyObject*:p:0: - -PyFloat_FromDouble:PyObject*::+1: -PyFloat_FromDouble:double:v:: - -PyFloat_FromString:PyObject*::+1: -PyFloat_FromString:PyObject*:str:0: -PyFloat_FromString:char**:pend:0:ignored - -PyFrozenSet_New:PyObject*::+1: -PyFrozenSet_New:PyObject*:iterable:0: - -PyFunction_GetClosure:PyObject*::0: -PyFunction_GetClosure:PyObject*:op:0: - -PyFunction_GetCode:PyObject*::0: -PyFunction_GetCode:PyObject*:op:0: - -PyFunction_GetDefaults:PyObject*::0: -PyFunction_GetDefaults:PyObject*:op:0: - -PyFunction_GetGlobals:PyObject*::0: -PyFunction_GetGlobals:PyObject*:op:0: - -PyFunction_GetModule:PyObject*::0: -PyFunction_GetModule:PyObject*:op:0: - -PyFunction_New:PyObject*::+1: -PyFunction_New:PyObject*:code:+1: -PyFunction_New:PyObject*:globals:+1: - -PyFunction_SetClosure:int::: -PyFunction_SetClosure:PyObject*:op:0: -PyFunction_SetClosure:PyObject*:closure:+1: - -PyFunction_SetDefaults:int::: -PyFunction_SetDefaults:PyObject*:op:0: -PyFunction_SetDefaults:PyObject*:defaults:+1: - -PyGen_New:PyObject*::+1: -PyGen_New:PyFrameObject*:frame:0: - -Py_InitModule:PyObject*::0: -Py_InitModule:char*:name:: -Py_InitModule:PyMethodDef[]:methods:: - -Py_InitModule3:PyObject*::0: -Py_InitModule3:char*:name:: -Py_InitModule3:PyMethodDef[]:methods:: -Py_InitModule3:char*:doc:: - -Py_InitModule4:PyObject*::0: -Py_InitModule4:char*:name:: -Py_InitModule4:PyMethodDef[]:methods:: -Py_InitModule4:char*:doc:: -Py_InitModule4:PyObject*:self:: -Py_InitModule4:int:apiver::usually provided by Py_InitModule or Py_InitModule3 - -PyImport_AddModule:PyObject*::0:reference borrowed from sys.modules -PyImport_AddModule:char*:name:: - -PyImport_Cleanup:void::: - -PyImport_ExecCodeModule:PyObject*::+1: -PyImport_ExecCodeModule:char*:name:: -PyImport_ExecCodeModule:PyObject*:co:0: - -PyImport_GetMagicNumber:long::: - -PyImport_GetModuleDict:PyObject*::0: - -PyImport_Import:PyObject*::+1: -PyImport_Import:PyObject*:name:0: - -PyImport_ImportFrozenModule:int::: -PyImport_ImportFrozenModule:char*::: - -PyImport_ImportModule:PyObject*::+1: -PyImport_ImportModule:char*:name:: - -PyImport_ImportModuleEx:PyObject*::+1: -PyImport_ImportModuleEx:char*:name:: -PyImport_ImportModuleEx:PyObject*:globals:0:??? -PyImport_ImportModuleEx:PyObject*:locals:0:??? -PyImport_ImportModuleEx:PyObject*:fromlist:0:??? - -PyImport_ReloadModule:PyObject*::+1: -PyImport_ReloadModule:PyObject*:m:0: - -PyInstance_New:PyObject*::+1: -PyInstance_New:PyObject*:klass:+1: -PyInstance_New:PyObject*:arg:0: -PyInstance_New:PyObject*:kw:0: - -PyInstance_NewRaw:PyObject*::+1: -PyInstance_NewRaw:PyObject*:klass:+1: -PyInstance_NewRaw:PyObject*:dict:+1: - -PyInt_AS_LONG:long::: -PyInt_AS_LONG:PyIntObject*:io:0: - -PyInt_AsLong:long::: -PyInt_AsLong:PyObject*:io:0: - -PyInt_Check:int::: -PyInt_Check:PyObject*:op:0: - -PyInt_FromLong:PyObject*::+1: -PyInt_FromLong:long:ival:: - -PyInt_FromString:PyObject*::+1: -PyInt_FromString:char*:str:0: -PyInt_FromString:char**:pend:0: -PyInt_FromString:int:base:0: - -PyInt_FromSsize_t:PyObject*::+1: -PyInt_FromSsize_t:Py_ssize_t:ival:: - -PyInt_GetMax:long::: - -PyInterpreterState_Clear:void::: -PyInterpreterState_Clear:PyInterpreterState*:interp:: - -PyInterpreterState_Delete:void::: -PyInterpreterState_Delete:PyInterpreterState*:interp:: - -PyInterpreterState_New:PyInterpreterState*::: - -PyIter_Check:int:o:0: - -PyIter_Next:PyObject*::+1: -PyIter_Next:PyObject*:o:0: - -PyList_Append:int::: -PyList_Append:PyObject*:list:0: -PyList_Append:PyObject*:item:+1: - -PyList_AsTuple:PyObject*::+1: -PyList_AsTuple:PyObject*:list:0: - -PyList_Check:int::: -PyList_Check:PyObject*:p:0: - -PyList_GET_ITEM:PyObject*::0: -PyList_GET_ITEM:PyObject*:list:0: -PyList_GET_ITEM:int:i:0: - -PyList_GET_SIZE:int::: -PyList_GET_SIZE:PyObject*:list:0: - -PyList_GetItem:PyObject*::0: -PyList_GetItem:PyObject*:list:0: -PyList_GetItem:int:index:: - -PyList_GetSlice:PyObject*::+1: -PyList_GetSlice:PyObject*:list:0: -PyList_GetSlice:int:low:: -PyList_GetSlice:int:high:: - -PyList_Insert:int::: -PyList_Insert:PyObject*:list:0: -PyList_Insert:int:index:: -PyList_Insert:PyObject*:item:+1: - -PyList_New:PyObject*::+1: -PyList_New:int:len:: - -PyList_Reverse:int::: -PyList_Reverse:PyObject*:list:0: - -PyList_SET_ITEM:void::: -PyList_SET_ITEM:PyObject*:list:0: -PyList_SET_ITEM:int:i:: -PyList_SET_ITEM:PyObject*:o:0: - -PyList_SetItem:int::: -PyList_SetItem:PyObject*:list:0: -PyList_SetItem:int:index:: -PyList_SetItem:PyObject*:item:0: - -PyList_SetSlice:int::: -PyList_SetSlice:PyObject*:list:0: -PyList_SetSlice:int:low:: -PyList_SetSlice:int:high:: -PyList_SetSlice:PyObject*:itemlist:0:but increfs its elements? - -PyList_Size:int::: -PyList_Size:PyObject*:list:0: - -PyList_Sort:int::: -PyList_Sort:PyObject*:list:0: - -PyLong_AsDouble:double::: -PyLong_AsDouble:PyObject*:pylong:0: - -PyLong_AsLong:long::: -PyLong_AsLong:PyObject*:pylong:0: - -PyLong_AsUnsignedLong:unsigned long::: -PyLong_AsUnsignedLong:PyObject*:pylong:0: - -PyLong_Check:int::: -PyLong_Check:PyObject*:p:0: - -PyLong_FromDouble:PyObject*::+1: -PyLong_FromDouble:double:v:: - -PyLong_FromLong:PyObject*::+1: -PyLong_FromLong:long:v:: - -PyLong_FromLongLong:PyObject*::+1: -PyLong_FromLongLong:long long:v:: - -PyLong_FromUnsignedLongLong:PyObject*::+1: -PyLong_FromUnsignedLongLong:unsigned long long:v:: - -PyLong_FromString:PyObject*::+1: -PyLong_FromString:char*:str:: -PyLong_FromString:char**:pend:: -PyLong_FromString:int:base:: - -PyLong_FromUnicode:PyObject*::+1: -PyLong_FromUnicode:Py_UNICODE:u:: -PyLong_FromUnicode:int:length:: -PyLong_FromUnicode:int:base:: - -PyLong_FromUnsignedLong:PyObject*::+1: -PyLong_FromUnsignedLong:unsignedlong:v:: - -PyLong_FromVoidPtr:PyObject*::+1: -PyLong_FromVoidPtr:void*:p:: - -PyMapping_Check:int::: -PyMapping_Check:PyObject*:o:0: - -PyMapping_DelItem:int::: -PyMapping_DelItem:PyObject*:o:0: -PyMapping_DelItem:PyObject*:key:0: - -PyMapping_DelItemString:int::: -PyMapping_DelItemString:PyObject*:o:0: -PyMapping_DelItemString:char*:key:: - -PyMapping_GetItemString:PyObject*::+1: -PyMapping_GetItemString:PyObject*:o:0: -PyMapping_GetItemString:char*:key:: - -PyMapping_HasKey:int::: -PyMapping_HasKey:PyObject*:o:0: -PyMapping_HasKey:PyObject*:key:: - -PyMapping_HasKeyString:int::: -PyMapping_HasKeyString:PyObject*:o:0: -PyMapping_HasKeyString:char*:key:: - -PyMapping_Items:PyObject*::+1: -PyMapping_Items:PyObject*:o:0: - -PyMapping_Keys:PyObject*::+1: -PyMapping_Keys:PyObject*:o:0: - -PyMapping_Length:int::: -PyMapping_Length:PyObject*:o:0: - -PyMapping_SetItemString:int::: -PyMapping_SetItemString:PyObject*:o:0: -PyMapping_SetItemString:char*:key:: -PyMapping_SetItemString:PyObject*:v:+1: - -PyMapping_Values:PyObject*::+1: -PyMapping_Values:PyObject*:o:0: - -PyMarshal_ReadLastObjectFromFile:PyObject*::+1: -PyMarshal_ReadLastObjectFromFile:FILE*:file:: - -PyMarshal_ReadObjectFromFile:PyObject*::+1: -PyMarshal_ReadObjectFromFile:FILE*:file:: - -PyMarshal_ReadObjectFromString:PyObject*::+1: -PyMarshal_ReadObjectFromString:char*:string:: -PyMarshal_ReadObjectFromString:int:len:: - -PyMarshal_WriteObjectToString:PyObject*::+1: -PyMarshal_WriteObjectToString:PyObject*:value:0: - -PyMethod_Class:PyObject*::0: -PyMethod_Class:PyObject*:im:0: - -PyMethod_Function:PyObject*::0: -PyMethod_Function:PyObject*:im:0: - -PyMethod_GET_CLASS:PyObject*::0: -PyMethod_GET_CLASS:PyObject*:im:0: - -PyMethod_GET_FUNCTION:PyObject*::0: -PyMethod_GET_FUNCTION:PyObject*:im:0: - -PyMethod_GET_SELF:PyObject*::0: -PyMethod_GET_SELF:PyObject*:im:0: - -PyMethod_New:PyObject*::+1: -PyMethod_New:PyObject*:func:0: -PyMethod_New:PyObject*:self:0: -PyMethod_New:PyObject*:class:0: - -PyMethod_Self:PyObject*::0: -PyMethod_Self:PyObject*:im:0: - -PyModule_GetDict:PyObject*::0: -PyModule_GetDict::PyObject* module:0: - -PyModule_GetFilename:char*::: -PyModule_GetFilename:PyObject*:module:0: - -PyModule_GetName:char*::: -PyModule_GetName:PyObject*:module:0: - -PyModule_New:PyObject*::+1: -PyModule_New::char* name:: - -PyNumber_Absolute:PyObject*::+1: -PyNumber_Absolute:PyObject*:o:0: - -PyNumber_Add:PyObject*::+1: -PyNumber_Add:PyObject*:o1:0: -PyNumber_Add:PyObject*:o2:0: - -PyNumber_And:PyObject*::+1: -PyNumber_And:PyObject*:o1:0: -PyNumber_And:PyObject*:o2:0: - -PyNumber_Check:PyObject*:o:0: -PyNumber_Check:int::: - -PyNumber_Coerce:int::: -PyNumber_Coerce:PyObject**:p1:+1: -PyNumber_Coerce:PyObject**:p2:+1: - -PyNumber_Divide:PyObject*::+1: -PyNumber_Divide:PyObject*:o1:0: -PyNumber_Divide:PyObject*:o2:0: - -PyNumber_Divmod:PyObject*::+1: -PyNumber_Divmod:PyObject*:o1:0: -PyNumber_Divmod:PyObject*:o2:0: - -PyNumber_Float:PyObject*::+1: -PyNumber_Float:PyObject*:o:0: - -PyNumber_FloorDivide:PyObject*::+1: -PyNumber_FloorDivide:PyObject*:v:0: -PyNumber_FloorDivide:PyObject*:w:0: - -PyNumber_InPlaceAdd:PyObject*::+1: -PyNumber_InPlaceAdd:PyObject*:v:0: -PyNumber_InPlaceAdd:PyObject*:w:0: - -PyNumber_InPlaceAnd:PyObject*::+1: -PyNumber_InPlaceAnd:PyObject*:v:0: -PyNumber_InPlaceAnd:PyObject*:w:0: - -PyNumber_InPlaceDivide:PyObject*::+1: -PyNumber_InPlaceDivide:PyObject*:v:0: -PyNumber_InPlaceDivide:PyObject*:w:0: - -PyNumber_InPlaceFloorDivide:PyObject*::+1: -PyNumber_InPlaceFloorDivide:PyObject*:v:0: -PyNumber_InPlaceFloorDivide:PyObject*:w:0: - -PyNumber_InPlaceLshift:PyObject*::+1: -PyNumber_InPlaceLshift:PyObject*:v:0: -PyNumber_InPlaceLshift:PyObject*:w:0: - -PyNumber_InPlaceMultiply:PyObject*::+1: -PyNumber_InPlaceMultiply:PyObject*:v:0: -PyNumber_InPlaceMultiply:PyObject*:w:0: - -PyNumber_InPlaceOr:PyObject*::+1: -PyNumber_InPlaceOr:PyObject*:v:0: -PyNumber_InPlaceOr:PyObject*:w:0: - -PyNumber_InPlacePower:PyObject*::+1: -PyNumber_InPlacePower:PyObject*:v:0: -PyNumber_InPlacePower:PyObject*:w:0: -PyNumber_InPlacePower:PyObject*:z:0: - -PyNumber_InPlaceRemainder:PyObject*::+1: -PyNumber_InPlaceRemainder:PyObject*:v:0: -PyNumber_InPlaceRemainder:PyObject*:w:0: - -PyNumber_InPlaceRshift:PyObject*::+1: -PyNumber_InPlaceRshift:PyObject*:v:0: -PyNumber_InPlaceRshift:PyObject*:w:0: - -PyNumber_InPlaceSubtract:PyObject*::+1: -PyNumber_InPlaceSubtract:PyObject*:v:0: -PyNumber_InPlaceSubtract:PyObject*:w:0: - -PyNumber_InPlaceTrueDivide:PyObject*::+1: -PyNumber_InPlaceTrueDivide:PyObject*:v:0: -PyNumber_InPlaceTrueDivide:PyObject*:w:0: - -PyNumber_InPlaceXor:PyObject*::+1: -PyNumber_InPlaceXor:PyObject*:v:0: -PyNumber_InPlaceXor:PyObject*:w:0: - -PyNumber_Int:PyObject*::+1: -PyNumber_Int:PyObject*:o:0: - -PyNumber_Invert:PyObject*::+1: -PyNumber_Invert:PyObject*:o:0: - -PyNumber_Long:PyObject*::+1: -PyNumber_Long:PyObject*:o:0: - -PyNumber_Lshift:PyObject*::+1: -PyNumber_Lshift:PyObject*:o1:0: -PyNumber_Lshift:PyObject*:o2:0: - -PyNumber_Multiply:PyObject*::+1: -PyNumber_Multiply:PyObject*:o1:0: -PyNumber_Multiply:PyObject*:o2:0: - -PyNumber_Negative:PyObject*::+1: -PyNumber_Negative:PyObject*:o:0: - -PyNumber_Or:PyObject*::+1: -PyNumber_Or:PyObject*:o1:0: -PyNumber_Or:PyObject*:o2:0: - -PyNumber_Positive:PyObject*::+1: -PyNumber_Positive:PyObject*:o:0: - -PyNumber_Power:PyObject*::+1: -PyNumber_Power:PyObject*:o1:0: -PyNumber_Power:PyObject*:o2:0: -PyNumber_Power:PyObject*:o3:0: - -PyNumber_Remainder:PyObject*::+1: -PyNumber_Remainder:PyObject*:o1:0: -PyNumber_Remainder:PyObject*:o2:0: - -PyNumber_Rshift:PyObject*::+1: -PyNumber_Rshift:PyObject*:o1:0: -PyNumber_Rshift:PyObject*:o2:0: - -PyNumber_Subtract:PyObject*::+1: -PyNumber_Subtract:PyObject*:o1:0: -PyNumber_Subtract:PyObject*:o2:0: - -PyNumber_TrueDivide:PyObject*::+1: -PyNumber_TrueDivide:PyObject*:v:0: -PyNumber_TrueDivide:PyObject*:w:0: - -PyNumber_Xor:PyObject*::+1: -PyNumber_Xor:PyObject*:o1:0: -PyNumber_Xor:PyObject*:o2:0: - -PyOS_GetLastModificationTime:long::: -PyOS_GetLastModificationTime:char*:filename:: - -PyObject_AsFileDescriptor:int::: -PyObject_AsFileDescriptor:PyObject*:o:0: - -PyObject_Call:PyObject*::+1: -PyObject_Call:PyObject*:callable_object:0: -PyObject_Call:PyObject*:args:0: -PyObject_Call:PyObject*:kw:0: - -PyObject_CallFunction:PyObject*::+1: -PyObject_CallFunction:PyObject*:callable_object:0: -PyObject_CallFunction:char*:format:: -PyObject_CallFunction::...:: - -PyObject_CallFunctionObjArgs:PyObject*::+1: -PyObject_CallFunctionObjArgs:PyObject*:callable:0: -PyObject_CallFunctionObjArgs::...:: - -PyObject_CallMethod:PyObject*::+1: -PyObject_CallMethod:PyObject*:o:0: -PyObject_CallMethod:char*:m:: -PyObject_CallMethod:char*:format:: -PyObject_CallMethod::...:: - -PyObject_CallMethodObjArgs:PyObject*::+1: -PyObject_CallMethodObjArgs:PyObject*:o:0: -PyObject_CallMethodObjArgs:char*:name:: -PyObject_CallMethodObjArgs::...:: - -PyObject_CallObject:PyObject*::+1: -PyObject_CallObject:PyObject*:callable_object:0: -PyObject_CallObject:PyObject*:args:0: - -PyObject_Cmp:int::: -PyObject_Cmp:PyObject*:o1:0: -PyObject_Cmp:PyObject*:o2:0: -PyObject_Cmp:int*:result:: - -PyObject_Compare:int::: -PyObject_Compare:PyObject*:o1:0: -PyObject_Compare:PyObject*:o2:0: - -PyObject_DelAttr:int::: -PyObject_DelAttr:PyObject*:o:0: -PyObject_DelAttr:PyObject*:attr_name:0: - -PyObject_DelAttrString:int::: -PyObject_DelAttrString:PyObject*:o:0: -PyObject_DelAttrString:char*:attr_name:: - -PyObject_DelItem:int::: -PyObject_DelItem:PyObject*:o:0: -PyObject_DelItem:PyObject*:key:0: - -PyObject_Dir:PyObject*::+1: -PyObject_Dir:PyObject*:o:0: - -PyObject_GetAttr:PyObject*::+1: -PyObject_GetAttr:PyObject*:o:0: -PyObject_GetAttr:PyObject*:attr_name:0: - -PyObject_GetAttrString:PyObject*::+1: -PyObject_GetAttrString:PyObject*:o:0: -PyObject_GetAttrString:char*:attr_name:: - -PyObject_GetItem:PyObject*::+1: -PyObject_GetItem:PyObject*:o:0: -PyObject_GetItem:PyObject*:key:0: - -PyObject_GetIter:PyObject*::+1: -PyObject_GetIter:PyObject*:o:0: - -PyObject_HasAttr:int::: -PyObject_HasAttr:PyObject*:o:0: -PyObject_HasAttr:PyObject*:attr_name:0: - -PyObject_HasAttrString:int::: -PyObject_HasAttrString:PyObject*:o:0: -PyObject_HasAttrString:char*:attr_name:0: - -PyObject_Hash:int::: -PyObject_Hash:PyObject*:o:0: - -PyObject_IsTrue:int::: -PyObject_IsTrue:PyObject*:o:0: - -PyObject_Init:PyObject*::0: -PyObject_Init:PyObject*:op:0: - -PyObject_InitVar:PyVarObject*::0: -PyObject_InitVar:PyVarObject*:op:0: - -PyObject_Length:int::: -PyObject_Length:PyObject*:o:0: - -PyObject_NEW:PyObject*::+1: - -PyObject_New:PyObject*::+1: - -PyObject_NEW_VAR:PyObject*::+1: - -PyObject_NewVar:PyObject*::+1: - -PyObject_Print:int::: -PyObject_Print:PyObject*:o:0: -PyObject_Print:FILE*:fp:: -PyObject_Print:int:flags:: - -PyObject_Repr:PyObject*::+1: -PyObject_Repr:PyObject*:o:0: - -PyObject_RichCompare:PyObject*::+1: -PyObject_RichCompare:PyObject*:o1:0: -PyObject_RichCompare:PyObject*:o2:0: -PyObject_RichCompare:int:opid:: - -PyObject_RichCompareBool:int::: -PyObject_RichCompareBool:PyObject*:o1:0: -PyObject_RichCompareBool:PyObject*:o2:0: -PyObject_RichCompareBool:int:opid:: - -PyObject_SetAttr:int::: -PyObject_SetAttr:PyObject*:o:0: -PyObject_SetAttr:PyObject*:attr_name:0: -PyObject_SetAttr:PyObject*:v:+1: - -PyObject_SetAttrString:int::: -PyObject_SetAttrString:PyObject*:o:0: -PyObject_SetAttrString:char*:attr_name:: -PyObject_SetAttrString:PyObject*:v:+1: - -PyObject_SetItem:int::: -PyObject_SetItem:PyObject*:o:0: -PyObject_SetItem:PyObject*:key:0: -PyObject_SetItem:PyObject*:v:+1: - -PyObject_Str:PyObject*::+1: -PyObject_Str:PyObject*:o:0: - -PyObject_Type:PyObject*::+1: -PyObject_Type:PyObject*:o:0: - -PyObject_Unicode:PyObject*::+1: -PyObject_Unicode:PyObject*:o:0: - -PyParser_SimpleParseFile:struct _node*::: -PyParser_SimpleParseFile:FILE*:fp:: -PyParser_SimpleParseFile:char*:filename:: -PyParser_SimpleParseFile:int:start:: - -PyParser_SimpleParseString:struct _node*::: -PyParser_SimpleParseString:char*:str:: -PyParser_SimpleParseString:int:start:: - -PyRun_AnyFile:int::: -PyRun_AnyFile:FILE*:fp:: -PyRun_AnyFile:char*:filename:: - -PyRun_File:PyObject*::+1:??? -- same as eval_code2() -PyRun_File:FILE*:fp:: -PyRun_File:char*:filename:: -PyRun_File:int:start:: -PyRun_File:PyObject*:globals:0: -PyRun_File:PyObject*:locals:0: - -PyRun_FileEx:PyObject*::+1:??? -- same as eval_code2() -PyRun_FileEx:FILE*:fp:: -PyRun_FileEx:char*:filename:: -PyRun_FileEx:int:start:: -PyRun_FileEx:PyObject*:globals:0: -PyRun_FileEx:PyObject*:locals:0: -PyRun_FileEx:int:closeit:: - -PyRun_FileFlags:PyObject*::+1:??? -- same as eval_code2() -PyRun_FileFlags:FILE*:fp:: -PyRun_FileFlags:char*:filename:: -PyRun_FileFlags:int:start:: -PyRun_FileFlags:PyObject*:globals:0: -PyRun_FileFlags:PyObject*:locals:0: -PyRun_FileFlags:PyCompilerFlags*:flags:: - -PyRun_FileExFlags:PyObject*::+1:??? -- same as eval_code2() -PyRun_FileExFlags:FILE*:fp:: -PyRun_FileExFlags:char*:filename:: -PyRun_FileExFlags:int:start:: -PyRun_FileExFlags:PyObject*:globals:0: -PyRun_FileExFlags:PyObject*:locals:0: -PyRun_FileExFlags:int:closeit:: -PyRun_FileExFlags:PyCompilerFlags*:flags:: - -PyRun_InteractiveLoop:int::: -PyRun_InteractiveLoop:FILE*:fp:: -PyRun_InteractiveLoop:char*:filename:: - -PyRun_InteractiveOne:int::: -PyRun_InteractiveOne:FILE*:fp:: -PyRun_InteractiveOne:char*:filename:: - -PyRun_SimpleFile:int::: -PyRun_SimpleFile:FILE*:fp:: -PyRun_SimpleFile:char*:filename:: - -PyRun_SimpleString:int::: -PyRun_SimpleString:char*:command:: - -PyRun_String:PyObject*::+1:??? -- same as eval_code2() -PyRun_String:char*:str:: -PyRun_String:int:start:: -PyRun_String:PyObject*:globals:0: -PyRun_String:PyObject*:locals:0: - -PyRun_StringFlags:PyObject*::+1:??? -- same as eval_code2() -PyRun_StringFlags:char*:str:: -PyRun_StringFlags:int:start:: -PyRun_StringFlags:PyObject*:globals:0: -PyRun_StringFlags:PyObject*:locals:0: -PyRun_StringFlags:PyCompilerFlags*:flags:: - -PySeqIter_New:PyObject*::+1: -PySeqIter_New:PyObject*:seq:: - -PySequence_Check:int::: -PySequence_Check:PyObject*:o:0: - -PySequence_Concat:PyObject*::+1: -PySequence_Concat:PyObject*:o1:0: -PySequence_Concat:PyObject*:o2:0: - -PySequence_Count:int::: -PySequence_Count:PyObject*:o:0: -PySequence_Count:PyObject*:value:0: - -PySequence_DelItem:int::: -PySequence_DelItem:PyObject*:o:0: -PySequence_DelItem:int:i:: - -PySequence_DelSlice:int::: -PySequence_DelSlice:PyObject*:o:0: -PySequence_DelSlice:int:i1:: -PySequence_DelSlice:int:i2:: - -PySequence_Fast:PyObject*::+1: -PySequence_Fast:PyObject*:v:0: -PySequence_Fast:const char*:m:: - -PySequence_Fast_GET_ITEM:PyObject*::0: -PySequence_Fast_GET_ITEM:PyObject*:o:0: -PySequence_Fast_GET_ITEM:int:i:: - -PySequence_GetItem:PyObject*::+1: -PySequence_GetItem:PyObject*:o:0: -PySequence_GetItem:int:i:: - -PySequence_GetSlice:PyObject*::+1: -PySequence_GetSlice:PyObject*:o:0: -PySequence_GetSlice:int:i1:: -PySequence_GetSlice:int:i2:: - -PySequence_In:int::: -PySequence_In:PyObject*:o:0: -PySequence_In:PyObject*:value:0: - -PySequence_Index:int::: -PySequence_Index:PyObject*:o:0: -PySequence_Index:PyObject*:value:0: - -PySequence_InPlaceConcat:PyObject*::+1: -PySequence_InPlaceConcat:PyObject*:s:0: -PySequence_InPlaceConcat:PyObject*:o:0: - -PySequence_InPlaceRepeat:PyObject*::+1: -PySequence_InPlaceRepeat:PyObject*:s:0: -PySequence_InPlaceRepeat:PyObject*:o:0: - -PySequence_ITEM:PyObject*::+1: -PySequence_ITEM:PyObject*:o:0: -PySequence_ITEM:int:i:: - -PySequence_Repeat:PyObject*::+1: -PySequence_Repeat:PyObject*:o:0: -PySequence_Repeat:int:count:: - -PySequence_SetItem:int::: -PySequence_SetItem:PyObject*:o:0: -PySequence_SetItem:int:i:: -PySequence_SetItem:PyObject*:v:+1: - -PySequence_SetSlice:int::: -PySequence_SetSlice:PyObject*:o:0: -PySequence_SetSlice:int:i1:: -PySequence_SetSlice:int:i2:: -PySequence_SetSlice:PyObject*:v:+1: - -PySequence_List:PyObject*::+1: -PySequence_List:PyObject*:o:0: - -PySequence_Tuple:PyObject*::+1: -PySequence_Tuple:PyObject*:o:0: - -PySet_Append:int::: -PySet_Append:PyObject*:set:0: -PySet_Append:PyObject*:key:+1: - -PySet_Contains:int::: -PySet_Contains:PyObject*:anyset:0: -PySet_Contains:PyObject*:key:0: - -PySet_Discard:int::: -PySet_Discard:PyObject*:set:0: -PySet_Discard:PyObject*:key:-1:no effect if key not found - -PySet_New:PyObject*::+1: -PySet_New:PyObject*:iterable:0: - -PySet_Pop:PyObject*::+1:or returns NULL and raises KeyError if set is empty -PySet_Pop:PyObject*:set:0: - -PySet_Size:int::: -PySet_Size:PyObject*:anyset:0: - -PySlice_Check:int::: -PySlice_Check:PyObject*:ob:0: - -PySlice_New:PyObject*::+1: -PySlice_New:PyObject*:start:0: -PySlice_New:PyObject*:stop:0: -PySlice_New:PyObject*:step:0: - -PyString_AS_STRING:char*::: -PyString_AS_STRING:PyObject*:string:0: - -PyString_AsDecodedObject:PyObject*::+1: -PyString_AsDecodedObject:PyObject*:str:0: -PyString_AsDecodedObject:const char*:encoding:: -PyString_AsDecodedObject:const char*:errors:: - -PyString_AsEncodedObject:PyObject*::+1: -PyString_AsEncodedObject:PyObject*:str:0: -PyString_AsEncodedObject:const char*:encoding:: -PyString_AsEncodedObject:const char*:errors:: - -PyString_AsString:char*::: -PyString_AsString:PyObject*:string:0: - -PyString_AsStringAndSize:int::: -PyString_AsStringAndSize:PyObject*:obj:0: -PyString_AsStringAndSize:char**:buffer:: -PyString_AsStringAndSize:int*:length:: - -PyString_Check:int::: -PyString_Check:PyObject*:o:0: - -PyString_Concat:void::: -PyString_Concat:PyObject**:string:0:??? -- replaces w/ new string or NULL -PyString_Concat:PyObject*:newpart:0: - -PyString_ConcatAndDel:void::: -PyString_ConcatAndDel:PyObject**:string:0:??? -- replaces w/ new string or NULL -PyString_ConcatAndDel:PyObject*:newpart:-1: - -PyString_Format:PyObject*::+1: -PyString_Format:PyObject*:format:0: -PyString_Format:PyObject*:args:0: - -PyString_FromString:PyObject*::+1: -PyString_FromString:const char*:v:: - -PyString_FromStringAndSize:PyObject*::+1: -PyString_FromStringAndSize:const char*:v:: -PyString_FromStringAndSize:int:len:: - -PyString_FromFormat:PyObject*::+1: -PyString_FromFormat:const char*:format:: -PyString_FromFormat::...:: - -PyString_FromFormatV:PyObject*::+1: -PyString_FromFormatV:const char*:format:: -PyString_FromFormatV:va_list:vargs:: - -PyString_GET_SIZE:int::: -PyString_GET_SIZE:PyObject*:string:0: - -PyString_InternFromString:PyObject*::+1: -PyString_InternFromString:const char*:v:: - -PyString_InternInPlace:void::: -PyString_InternInPlace:PyObject**:string:+1:??? - -PyString_Size:int::: -PyString_Size:PyObject*:string:0: - -PyString_Decode:PyObject*::+1: -PyString_Decode:const char*:s:: -PyString_Decode:int:size:: -PyString_Decode:const char*:encoding:: -PyString_Decode:const char*:errors:: - -PyString_Encode:PyObject*::+1: -PyString_Encode:const char*:s:: -PyString_Encode:int:size:: -PyString_Encode:const char*:encoding:: -PyString_Encode:const char*:errors:: - -PyString_AsEncodedString:PyObject*::+1: -PyString_AsEncodedString:PyObject*:str:: -PyString_AsEncodedString:const char*:encoding:: -PyString_AsEncodedString:const char*:errors:: - -PySys_SetArgv:int::: -PySys_SetArgv:int:argc:: -PySys_SetArgv:char**:argv:: - -PyThreadState_Clear:void::: -PyThreadState_Clear:PyThreadState*:tstate:: - -PyThreadState_Delete:void::: -PyThreadState_Delete:PyThreadState*:tstate:: - -PyThreadState_Get:PyThreadState*::: - -PyThreadState_GetDict:PyObject*::0: - -PyThreadState_New:PyThreadState*::: -PyThreadState_New:PyInterpreterState*:interp:: - -PyThreadState_Swap:PyThreadState*::: -PyThreadState_Swap:PyThreadState*:tstate:: - -PyTime_FromTime:PyObject*::+1: -PyTime_FromTime:int:hour:: -PyTime_FromTime:int:minute:: -PyTime_FromTime:int:second:: -PyTime_FromTime:int:usecond:: - -PyTuple_Check:int::: -PyTuple_Check:PyObject*:p:0: - -PyTuple_GET_ITEM:PyObject*::0: -PyTuple_GET_ITEM:PyTupleObject*:p:0: -PyTuple_GET_ITEM:int:pos:: - -PyTuple_GetItem:PyObject*::0: -PyTuple_GetItem:PyTupleObject*:p:0: -PyTuple_GetItem:int:pos:: - -PyTuple_GetSlice:PyObject*::+1: -PyTuple_GetSlice:PyTupleObject*:p:0: -PyTuple_GetSlice:int:low:: -PyTuple_GetSlice:int:high:: - -PyTuple_New:PyObject*::+1: -PyTuple_New:int:len:: - -PyTuple_Pack:PyObject*::+1: -PyTuple_Pack:int:len:: -PyTuple_Pack:PyObject*:...:0: - -PyTuple_SET_ITEM:void::: -PyTuple_SET_ITEM:PyTupleObject*:p:0: -PyTuple_SET_ITEM:int:pos:: -PyTuple_SET_ITEM:PyObject*:o:0: - -PyTuple_SetItem:int::: -PyTuple_SetItem:PyTupleObject*:p:0: -PyTuple_SetItem:int:pos:: -PyTuple_SetItem:PyObject*:o:0: - -PyTuple_Size:int::: -PyTuple_Size:PyTupleObject*:p:0: - -PyType_GenericAlloc:PyObject*::+1: -PyType_GenericAlloc:PyObject*:type:0: -PyType_GenericAlloc:int:nitems:0: - -PyType_GenericNew:PyObject*::+1: -PyType_GenericNew:PyObject*:type:0: -PyType_GenericNew:PyObject*:args:0: -PyType_GenericNew:PyObject*:kwds:0: - -PyUnicode_Check:int::: -PyUnicode_Check:PyObject*:o:0: - -PyUnicode_GET_SIZE:int::: -PyUnicode_GET_SIZE:PyObject*:o:0: - -PyUnicode_GET_DATA_SIZE:int::: -PyUnicode_GET_DATA_SIZE:PyObject*:o:0: - -PyUnicode_AS_UNICODE:Py_UNICODE*::: -PyUnicode_AS_UNICODE:PyObject*:o:0: - -PyUnicode_AS_DATA:const char*::: -PyUnicode_AS_DATA:PyObject*:o:0: - -Py_UNICODE_ISSPACE:int::: -Py_UNICODE_ISSPACE:Py_UNICODE:ch:: - -Py_UNICODE_ISLOWER:int::: -Py_UNICODE_ISLOWER:Py_UNICODE:ch:: - -Py_UNICODE_ISUPPER:int::: -Py_UNICODE_ISUPPER:Py_UNICODE:ch:: - -Py_UNICODE_ISTITLE:int::: -Py_UNICODE_ISTITLE:Py_UNICODE:ch:: - -Py_UNICODE_ISLINEBREAK:int::: -Py_UNICODE_ISLINEBREAK:Py_UNICODE:ch:: - -Py_UNICODE_ISDECIMAL:int::: -Py_UNICODE_ISDECIMAL:Py_UNICODE:ch:: - -Py_UNICODE_ISDIGIT:int::: -Py_UNICODE_ISDIGIT:Py_UNICODE:ch:: - -Py_UNICODE_ISNUMERIC:int::: -Py_UNICODE_ISNUMERIC:Py_UNICODE:ch:: - -Py_UNICODE_TOLOWER:Py_UNICODE::: -Py_UNICODE_TOLOWER:Py_UNICODE:ch:: - -Py_UNICODE_TOUPPER:Py_UNICODE::: -Py_UNICODE_TOUPPER:Py_UNICODE:ch:: - -Py_UNICODE_TOTITLE:Py_UNICODE::: -Py_UNICODE_TOTITLE:Py_UNICODE:ch:: - -Py_UNICODE_TODECIMAL:int::: -Py_UNICODE_TODECIMAL:Py_UNICODE:ch:: - -Py_UNICODE_TODIGIT:int::: -Py_UNICODE_TODIGIT:Py_UNICODE:ch:: - -Py_UNICODE_TONUMERIC:double::: -Py_UNICODE_TONUMERIC:Py_UNICODE:ch:: - -PyUnicode_FromUnicode:PyObject*::+1: -PyUnicode_FromUnicode:const Py_UNICODE*:u:: -PyUnicode_FromUnicode:int:size:: - -PyUnicode_AsUnicode:Py_UNICODE*::: -PyUnicode_AsUnicode:PyObject :*unicode:0: - -PyUnicode_GetSize:int::: -PyUnicode_GetSize:PyObject :*unicode:0: - -PyUnicode_FromObject:PyObject*::+1: -PyUnicode_FromObject:PyObject*:*obj:0: - -PyUnicode_FromEncodedObject:PyObject*::+1: -PyUnicode_FromEncodedObject:PyObject*:*obj:0: -PyUnicode_FromEncodedObject:const char*:encoding:: -PyUnicode_FromEncodedObject:const char*:errors:: - -PyUnicode_FromWideChar:PyObject*::+1: -PyUnicode_FromWideChar:const wchar_t*:w:: -PyUnicode_FromWideChar:int:size:: - -PyUnicode_AsWideChar:int::: -PyUnicode_AsWideChar:PyObject*:*unicode:0: -PyUnicode_AsWideChar:wchar_t*:w:: -PyUnicode_AsWideChar:int:size:: - -PyUnicode_Decode:PyObject*::+1: -PyUnicode_Decode:const char*:s:: -PyUnicode_Decode:int:size:: -PyUnicode_Decode:const char*:encoding:: -PyUnicode_Decode:const char*:errors:: - -PyUnicode_DecodeUTF16Stateful:PyObject*::+1: -PyUnicode_DecodeUTF16Stateful:const char*:s:: -PyUnicode_DecodeUTF16Stateful:int:size:: -PyUnicode_DecodeUTF16Stateful:const char*:errors:: -PyUnicode_DecodeUTF16Stateful:int*:byteorder:: -PyUnicode_DecodeUTF16Stateful:int*:consumed:: - -PyUnicode_DecodeUTF8Stateful:PyObject*::+1: -PyUnicode_DecodeUTF8Stateful:const char*:s:: -PyUnicode_DecodeUTF8Stateful:int:size:: -PyUnicode_DecodeUTF8Stateful:const char*:errors:: -PyUnicode_DecodeUTF8Stateful:int*:consumed:: - -PyUnicode_Encode:PyObject*::+1: -PyUnicode_Encode:const Py_UNICODE*:s:: -PyUnicode_Encode:int:size:: -PyUnicode_Encode:const char*:encoding:: -PyUnicode_Encode:const char*:errors:: - -PyUnicode_AsEncodedString:PyObject*::+1: -PyUnicode_AsEncodedString:PyObject*:unicode:: -PyUnicode_AsEncodedString:const char*:encoding:: -PyUnicode_AsEncodedString:const char*:errors:: - -PyUnicode_DecodeUTF8:PyObject*::+1: -PyUnicode_DecodeUTF8:const char*:s:: -PyUnicode_DecodeUTF8:int:size:: -PyUnicode_DecodeUTF8:const char*:errors:: - -PyUnicode_EncodeUTF8:PyObject*::+1: -PyUnicode_EncodeUTF8:const Py_UNICODE*:s:: -PyUnicode_EncodeUTF8:int:size:: -PyUnicode_EncodeUTF8:const char*:errors:: - -PyUnicode_AsUTF8String:PyObject*::+1: -PyUnicode_AsUTF8String:PyObject*:unicode:: - -PyUnicode_DecodeUTF16:PyObject*::+1: -PyUnicode_DecodeUTF16:const char*:s:: -PyUnicode_DecodeUTF16:int:size:: -PyUnicode_DecodeUTF16:const char*:errors:: -PyUnicode_DecodeUTF16:int*:byteorder:: - -PyUnicode_EncodeUTF16:PyObject*::+1: -PyUnicode_EncodeUTF16:const Py_UNICODE*:s:: -PyUnicode_EncodeUTF16:int:size:: -PyUnicode_EncodeUTF16:const char*:errors:: -PyUnicode_EncodeUTF16:int:byteorder:: - -PyUnicode_AsUTF16String:PyObject*::+1: -PyUnicode_AsUTF16String:PyObject*:unicode:: - -PyUnicode_DecodeUnicodeEscape:PyObject*::+1: -PyUnicode_DecodeUnicodeEscape:const char*:s:: -PyUnicode_DecodeUnicodeEscape:int:size:: -PyUnicode_DecodeUnicodeEscape:const char*:errors:: - -PyUnicode_EncodeUnicodeEscape:PyObject*::+1: -PyUnicode_EncodeUnicodeEscape:const Py_UNICODE*:s:: -PyUnicode_EncodeUnicodeEscape:int:size:: -PyUnicode_EncodeUnicodeEscape:const char*:errors:: - -PyUnicode_AsUnicodeEscapeString:PyObject*::+1: -PyUnicode_AsUnicodeEscapeString:PyObject*:unicode:: - -PyUnicode_DecodeRawUnicodeEscape:PyObject*::+1: -PyUnicode_DecodeRawUnicodeEscape:const char*:s:: -PyUnicode_DecodeRawUnicodeEscape:int:size:: -PyUnicode_DecodeRawUnicodeEscape:const char*:errors:: - -PyUnicode_EncodeRawUnicodeEscape:PyObject*::+1: -PyUnicode_EncodeRawUnicodeEscape:const Py_UNICODE*:s:: -PyUnicode_EncodeRawUnicodeEscape:int:size:: -PyUnicode_EncodeRawUnicodeEscape:const char*:errors:: - -PyUnicode_AsRawUnicodeEscapeString:PyObject*::+1: -PyUnicode_AsRawUnicodeEscapeString:PyObject*:unicode:: - -PyUnicode_DecodeLatin1:PyObject*::+1: -PyUnicode_DecodeLatin1:const char*:s:: -PyUnicode_DecodeLatin1:int:size:: -PyUnicode_DecodeLatin1:const char*:errors:: - -PyUnicode_EncodeLatin1:PyObject*::+1: -PyUnicode_EncodeLatin1:const Py_UNICODE*:s:: -PyUnicode_EncodeLatin1:int:size:: -PyUnicode_EncodeLatin1:const char*:errors:: - -PyUnicode_AsLatin1String:PyObject*::+1: -PyUnicode_AsLatin1String:PyObject*:unicode:: - -PyUnicode_DecodeASCII:PyObject*::+1: -PyUnicode_DecodeASCII:const char*:s:: -PyUnicode_DecodeASCII:int:size:: -PyUnicode_DecodeASCII:const char*:errors:: - -PyUnicode_EncodeASCII:PyObject*::+1: -PyUnicode_EncodeASCII:const Py_UNICODE*:s:: -PyUnicode_EncodeASCII:int:size:: -PyUnicode_EncodeASCII:const char*:errors:: - -PyUnicode_AsASCIIString:PyObject*::+1: -PyUnicode_AsASCIIString:PyObject*:unicode:: - -PyUnicode_DecodeCharmap:PyObject*::+1: -PyUnicode_DecodeCharmap:const char*:s:: -PyUnicode_DecodeCharmap:int:size:: -PyUnicode_DecodeCharmap:PyObject*:mapping:0: -PyUnicode_DecodeCharmap:const char*:errors:: - -PyUnicode_EncodeCharmap:PyObject*::+1: -PyUnicode_EncodeCharmap:const Py_UNICODE*:s:: -PyUnicode_EncodeCharmap:int:size:: -PyUnicode_EncodeCharmap:PyObject*:mapping:0: -PyUnicode_EncodeCharmap:const char*:errors:: - -PyUnicode_AsCharmapString:PyObject*::+1: -PyUnicode_AsCharmapString:PyObject*:unicode:0: -PyUnicode_AsCharmapString:PyObject*:mapping:0: - -PyUnicode_TranslateCharmap:PyObject*::+1: -PyUnicode_TranslateCharmap:const Py_UNICODE*:s:: -PyUnicode_TranslateCharmap:int:size:: -PyUnicode_TranslateCharmap:PyObject*:table:0: -PyUnicode_TranslateCharmap:const char*:errors:: - -PyUnicode_DecodeMBCS:PyObject*::+1: -PyUnicode_DecodeMBCS:const char*:s:: -PyUnicode_DecodeMBCS:int:size:: -PyUnicode_DecodeMBCS:const char*:errors:: - -PyUnicode_EncodeMBCS:PyObject*::+1: -PyUnicode_EncodeMBCS:const Py_UNICODE*:s:: -PyUnicode_EncodeMBCS:int:size:: -PyUnicode_EncodeMBCS:const char*:errors:: - -PyUnicode_AsMBCSString:PyObject*::+1: -PyUnicode_AsMBCSString:PyObject*:unicode:: - -PyUnicode_Concat:PyObject*::+1: -PyUnicode_Concat:PyObject*:left:0: -PyUnicode_Concat:PyObject*:right:0: - -PyUnicode_Split:PyObject*::+1: -PyUnicode_Split:PyObject*:left:0: -PyUnicode_Split:PyObject*:right:0: -PyUnicode_Split:int:maxsplit:: - -PyUnicode_Splitlines:PyObject*::+1: -PyUnicode_Splitlines:PyObject*:s:0: -PyUnicode_Splitlines:int:maxsplit:: - -PyUnicode_Translate:PyObject*::+1: -PyUnicode_Translate:PyObject*:str:0: -PyUnicode_Translate:PyObject*:table:0: -PyUnicode_Translate:const char*:errors:: - -PyUnicode_Join:PyObject*::+1: -PyUnicode_Join:PyObject*:separator:0: -PyUnicode_Join:PyObject*:seq:0: - -PyUnicode_Tailmatch:PyObject*::+1: -PyUnicode_Tailmatch:PyObject*:str:0: -PyUnicode_Tailmatch:PyObject*:substr:0: -PyUnicode_Tailmatch:int:start:: -PyUnicode_Tailmatch:int:end:: -PyUnicode_Tailmatch:int:direction:: - -PyUnicode_Find:int::: -PyUnicode_Find:PyObject*:str:0: -PyUnicode_Find:PyObject*:substr:0: -PyUnicode_Find:int:start:: -PyUnicode_Find:int:end:: -PyUnicode_Find:int:direction:: - -PyUnicode_Count:int::: -PyUnicode_Count:PyObject*:str:0: -PyUnicode_Count:PyObject*:substr:0: -PyUnicode_Count:int:start:: -PyUnicode_Count:int:end:: - -PyUnicode_Replace:PyObject*::+1: -PyUnicode_Replace:PyObject*:str:0: -PyUnicode_Replace:PyObject*:substr:0: -PyUnicode_Replace:PyObject*:replstr:0: -PyUnicode_Replace:int:maxcount:: - -PyUnicode_Compare:int::: -PyUnicode_Compare:PyObject*:left:0: -PyUnicode_Compare:PyObject*:right:0: - -PyUnicode_Format:PyObject*::+1: -PyUnicode_Format:PyObject*:format:0: -PyUnicode_Format:PyObject*:args:0: - -PyUnicode_Contains:int::: -PyUnicode_Contains:PyObject*:container:0: -PyUnicode_Contains:PyObject*:element:0: - -PyWeakref_GET_OBJECT:PyObject*::0: -PyWeakref_GET_OBJECT:PyObject*:ref:0: - -PyWeakref_GetObject:PyObject*::0: -PyWeakref_GetObject:PyObject*:ref:0: - -PyWeakref_NewProxy:PyObject*::+1: -PyWeakref_NewProxy:PyObject*:ob:0: -PyWeakref_NewProxy:PyObject*:callback:0: - -PyWeakref_NewRef:PyObject*::+1: -PyWeakref_NewRef:PyObject*:ob:0: -PyWeakref_NewRef:PyObject*:callback:0: - -PyWrapper_New:PyObject*::+1: -PyWrapper_New:PyObject*:d:0: -PyWrapper_New:PyObject*:self:0: - -Py_AtExit:int::: -Py_AtExit:void (*)():func:: - -Py_BuildValue:PyObject*::+1: -Py_BuildValue:char*:format:: - -Py_CompileString:PyObject*::+1: -Py_CompileString:char*:str:: -Py_CompileString:char*:filename:: -Py_CompileString:int:start:: - -Py_CompileStringFlags:PyObject*::+1: -Py_CompileStringFlags:char*:str:: -Py_CompileStringFlags:char*:filename:: -Py_CompileStringFlags:int:start:: -Py_CompileStringFlags:PyCompilerFlags*:flags:: - -Py_DECREF:void::: -Py_DECREF:PyObject*:o:-1: - -Py_EndInterpreter:void::: -Py_EndInterpreter:PyThreadState*:tstate:: - -Py_Exit:void::: -Py_Exit:int:status:: - -Py_FatalError:void::: -Py_FatalError:char*:message:: - -Py_FdIsInteractive:int::: -Py_FdIsInteractive:FILE*:fp:: -Py_FdIsInteractive:char*:filename:: - -Py_Finalize:void::: - -Py_FindMethod:PyObject*::+1: -Py_FindMethod:PyMethodDef[]:methods:: -Py_FindMethod:PyObject*:self:+1: -Py_FindMethod:char*:name:: - -Py_GetBuildInfoconst:char*::: - -Py_GetCompilerconst:char*::: - -Py_GetCopyrightconst:char*::: - -Py_GetExecPrefix:char*::: - -Py_GetPath:char*::: - -Py_GetPlatformconst:char*::: - -Py_GetPrefix:char*::: - -Py_GetProgramFullPath:char*::: - -Py_GetProgramName:char*::: - -Py_GetVersionconst:char*::: - -Py_INCREF:void::: -Py_INCREF:PyObject*:o:+1: - -Py_Initialize:void::: - -Py_IsInitialized:int::: - -Py_NewInterpreter:PyThreadState*::: - -Py_SetProgramName:void::: -Py_SetProgramName:char*:name:: - -Py_XDECREF:void::: -Py_XDECREF:PyObject*:o:-1:if o is not NULL - -Py_XINCREF:void::: -Py_XINCREF:PyObject*:o:+1:if o is not NULL - -_PyImport_FindExtension:PyObject*::0:??? see PyImport_AddModule -_PyImport_FindExtension:char*::: -_PyImport_FindExtension:char*::: - -_PyImport_Fini:void::: - -_PyImport_FixupExtension:PyObject*:::??? -_PyImport_FixupExtension:char*::: -_PyImport_FixupExtension:char*::: - -_PyImport_Init:void::: - -_PyObject_Del:void::: -_PyObject_Del:PyObject*:op:0: - -_PyObject_New:PyObject*::+1: -_PyObject_New:PyTypeObject*:type:0: - -_PyObject_NewVar:PyObject*::+1: -_PyObject_NewVar:PyTypeObject*:type:0: -_PyObject_NewVar:int:size:: - -_PyString_Resize:int::: -_PyString_Resize:PyObject**:string:+1: -_PyString_Resize:int:newsize:: - -_PyTuple_Resize:int::: -_PyTuple_Resize:PyTupleObject**:p:+1: -_PyTuple_Resize:int:new:: - -_Py_c_diff:Py_complex::: -_Py_c_diff:Py_complex:left:: -_Py_c_diff:Py_complex:right:: - -_Py_c_neg:Py_complex::: -_Py_c_neg:Py_complex:complex:: - -_Py_c_pow:Py_complex::: -_Py_c_pow:Py_complex:num:: -_Py_c_pow:Py_complex:exp:: - -_Py_c_prod:Py_complex::: -_Py_c_prod:Py_complex:left:: -_Py_c_prod:Py_complex:right:: - -_Py_c_quot:Py_complex::: -_Py_c_quot:Py_complex:dividend:: -_Py_c_quot:Py_complex:divisor:: - -_Py_c_sum:Py_complex::: -_Py_c_sum:Py_complex:left:: -_Py_c_sum:Py_complex:right:: diff --git a/Doc/api/utilities.tex b/Doc/api/utilities.tex deleted file mode 100644 index 93e3796..0000000 --- a/Doc/api/utilities.tex +++ /dev/null @@ -1,1023 +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{''} 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. This is best described by referring to the - built-in Python function \function{reload()}\bifuncindex{reload}, as - the standard \function{reload()} function calls this function - directly. Return a new reference to the reloaded module, or \NULL{} - with an exception set on failure (the module still exists in this - case). -\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{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{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 - . 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 . - 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 - - 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 "." */ - 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 ff5106a..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 -\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 -\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 -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 " \ - 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: -username: -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} -/ - 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} -/ - 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} -/ - 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} -/ - 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} -/ - 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} -/ - 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} -/ - 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} -/ - 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 run with \function{execfile()} -\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 - -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 53d90db..0000000 --- a/Doc/ext/extending.tex +++ /dev/null @@ -1,1390 +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 -\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{}, \code{}, \code{}, and -\code{}. 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 Python variables -\code{sys.exc_type}, \code{sys.exc_value} and \code{sys.exc_traceback} (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. -Note also that the \function{reload()} function can be used with -extension modules, and will call the module initialization function -(\cfunction{initspam()} in the example), but will not load the module -again if it was loaded from a dynamically loadable object file -(\file{.so} on \UNIX, \file{.dll} on Windows).} - -A more substantial example module is included in the Python source -distribution as \file{Modules/xxmodule.c}. This file may be used as a -template or simply read as an example. The \program{modulator.py} -script included in the source distribution or Windows install provides -a simple graphical user interface for declaring the functions and -objects which a module should implement, and can generate a template -which can be filled in. The script lives in the -\file{Tools/modulator/} directory; see the \file{README} file there -for more information. - - -\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("ss", "hello", "world") ('hello', 'world') - Py_BuildValue("s#", "hello", 4) 'hell' - Py_BuildValue("()") () - Py_BuildValue("(i)", 123) (123,) - Py_BuildValue("(ii)", 123, 456) (123, 456) - Py_BuildValue("(i,i)", 123, 456) (123, 456) - Py_BuildValue("[i,i]", 123, 456) [123, 456] - Py_BuildValue("{s:i,s:i}", - "abc", 123, "def", 456) {'abc': 123, 'def': 456} - Py_BuildValue("((ii)(ii)) (ii)", - 1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6)) -\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 5c1f0ae..0000000 --- a/Doc/ext/newtypes.tex +++ /dev/null @@ -1,1765 +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 "", 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 three ways to generate a textual representation -of an object: the \function{repr()}\bifuncindex{repr} function (or -equivalent back-tick syntax), the \function{str()}\bifuncindex{str} -function, and the \keyword{print} statement. For most objects, the -\keyword{print} statement is equivalent to the \function{str()} -function, but it is possible to special-case printing to a -\ctype{FILE*} if necessary; this should only be done if efficiency is -identified as a problem and profiling suggests that creating a -temporary string object to be written to a file is too expensive. - -These handlers are all optional, and most types at most need to -implement the \member{tp_str} and \member{tp_repr} handlers. - -\begin{verbatim} - reprfunc tp_repr; - reprfunc tp_str; - printfunc tp_print; -\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_print} or \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 - -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 -#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 -#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 -#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 - -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 - -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 "", line 1, in ? -AttributeError: first ->>> n2.number -0 ->>> n3 = noddy2.Noddy('jim', 'fulton', 'waaa') -Traceback (most recent call last): - File "", 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 "", line 1, in ? -TypeError: Cannot delete the first attribute ->>> n1.first = 42 -Traceback (most recent call last): - File "", 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 "", 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 "", line 1, in ? -AttributeError: first ->>> n2.number -0 ->>> n3 = noddy4.Noddy('jim', 'fulton', 'waaa') -Traceback (most recent call last): - File "", 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 28ef7c3..0000000 --- a/Doc/howto/doanddont.tex +++ /dev/null @@ -1,344 +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 \keyword{exec}, \function{execfile} 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! ->>> execfile("handler.py") ->>> 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={} ->>> execfile("handle.py", 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()}. Another highly useful function is -\function{reduce()}. A classical use of \function{reduce()} -is something like - -\begin{verbatim} -import sys, operator -nums = map(float, sys.argv[1:]) -print reduce(operator.add, nums)/len(nums) -\end{verbatim} - -This cute little script prints the average of all numbers given on the -command line. The \function{reduce()} adds up all the numbers, and -the rest is just some pre- and postprocessing. - -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 bfe67d1..0000000 --- a/Doc/howto/functional.rst +++ /dev/null @@ -1,1472 +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 ``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 - - >>> it.next() - 1 - >>> it.next() - 2 - >>> it.next() - 3 - >>> it.next() - Traceback (most recent call last): - File "", 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 to the generator's ``.next()`` method, -the function will resume executing. - -Here's a sample usage of the ``generate_ints()`` generator:: - - >>> gen = generate_ints(3) - >>> gen - - >>> gen.next() - 0 - >>> gen.next() - 1 - >>> gen.next() - 2 - >>> gen.next() - Traceback (most recent call last): - File "stdin", line 1, in ? - File "stdin", line 2, in generate_ints - StopIteration - -You could equally write ``for i in generate_ints(5)``, or -``a,b,c = generate_ints(3)``. - -Inside a generator function, the ``return`` statement can only be used -without a value, and signals the end of the procession of values; -after executing a ``return`` the generator cannot return any further -values. ``return`` with a value, such as ``return 5``, is a syntax -error inside a generator function. The end of the generator's results -can also be indicated by raising ``StopIteration`` manually, or by -just letting the flow of execution fall off the bottom of the -function. - -You could achieve the effect of generators manually by writing your -own class and storing all the local variables of the generator as -instance variables. For example, returning a list of integers could -be done by setting ``self.count`` to 0, and having the -``next()`` method increment ``self.count`` and return it. -However, for a moderately complicated generator, writing a -corresponding class can be much messier. - -The test suite included with Python's library, ``test_generators.py``, -contains a number of more interesting examples. Here's one generator -that implements an in-order traversal of a tree using generators -recursively. - -:: - - # A recursive generator that generates Tree leaves in in-order. - def inorder(t): - if t: - for x in inorder(t.left): - yield x - - yield t.label - - for x in inorder(t.right): - yield x - -Two other examples in ``test_generators.py`` produce -solutions for the N-Queens problem (placing N queens on an NxN -chess board so that no queen threatens another) and the Knight's Tour -(finding a route that takes a knight to every square of an NxN chessboard -without visiting any square twice). - - - -Passing values into a generator -'''''''''''''''''''''''''''''''''''''''''''''' - -In Python 2.4 and earlier, generators only produced output. Once a -generator's code was invoked to create an iterator, there was no way to -pass any new information into the function when its execution is -resumed. You could hack together this ability by making the -generator look at a global variable or by passing in some mutable object -that callers then modify, but these approaches are messy. - -In Python 2.5 there's a simple way to pass values into a generator. -``yield`` became an expression, returning a value that can be assigned -to a variable or otherwise operated on:: - - val = (yield i) - -I recommend that you **always** put parentheses around a ``yield`` -expression when you're doing something with the returned value, as in -the above example. The parentheses aren't always necessary, but it's -easier to always add them instead of having to remember when they're -needed. - -(PEP 342 explains the exact rules, which are that a -``yield``-expression must always be parenthesized except when it -occurs at the top-level expression on the right-hand side of an -assignment. This means you can write ``val = yield i`` but have to -use parentheses when there's an operation, as in ``val = (yield i) -+ 12``.) - -Values are sent into a generator by calling its -``send(value)`` method. This method resumes the -generator's code and the ``yield`` expression returns the specified -value. If the regular ``next()`` method is called, the -``yield`` returns ``None``. - -Here's a simple counter that increments by 1 and allows changing the -value of the internal counter. - -:: - - def counter (maximum): - i = 0 - while i < maximum: - val = (yield i) - # If value provided, change counter - if val is not None: - i = val - else: - i += 1 - -And here's an example of changing the counter: - - >>> it = counter(10) - >>> print it.next() - 0 - >>> print it.next() - 1 - >>> print it.send(8) - 8 - >>> print it.next() - 9 - >>> print it.next() - Traceback (most recent call last): - File ``t.py'', line 15, in ? - print it.next() - StopIteration - -Because ``yield`` will often be returning ``None``, you -should always check for this case. Don't just use its value in -expressions unless you're sure that the ``send()`` method -will be the only method used resume your generator function. - -In addition to ``send()``, there are two other new methods on -generators: - -* ``throw(type, value=None, traceback=None)`` is used to raise an exception inside the - generator; the exception is raised by the ``yield`` expression - where the generator's execution is paused. - -* ``close()`` raises a ``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 `__.) - -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 `__ for a complete -list. - - - -The functional module ---------------------- - -Collin Winter's `functional module `__ -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 `__. - -``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 `__. -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 `__, -`part 2 `__, and -`part 3 `__, - - -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 62b6daf..0000000 --- a/Doc/howto/regex.tex +++ /dev/null @@ -1,1477 +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 - -\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 - ->>> 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 - ->>> 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') - -\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, -here's an extract from \file{xmllib.py}: - -\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') - ->>> 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}') - ->>> print re.search('}$', '{block} ') -None ->>> print re.search('}$', '{block}\n') - -\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') - ->>> 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') - -\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\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[ 123][0-9])-(?P[A-Z][a-z][a-z])-' - r'(?P[0-9][0-9][0-9][0-9])' - r' (?P[0-9][0-9]):(?P[0-9][0-9]):(?P[0-9][0-9])' - r' (?P[-+])(?P[0-9][0-9])(?P[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\e b\e w+)\e s+(?P=word)}: - -\begin{verbatim} ->>> p = re.compile(r'(?P\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...)} syntax. \samp{\e g} 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 [^}]* ) }', 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}','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 = 'Title' ->>> len(s) -32 ->>> print re.match('<.*>', s).span() -(0, 32) ->>> print re.match('<.*>', s).group() -Title -\end{verbatim} - -The RE matches the \character{<} in \samp{}, 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{} -to the \character{>} in \samp{}, 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() - -\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 name - \s* : # Whitespace, and a colon - (?P.*?) # 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
[^:]+)\s*:(?P.*?)\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 has character -charts, a glossary, and PDF versions of the Unicode specification. Be -prepared for some difficult reading. - 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 . - -Roman Czyborra wrote another explanation of Unicode's basic principles; -it's at . -Czyborra has written a number of other Unicode-related documentation, -available from . - -Two other good introductory articles were written by Joel Spolsky - and Jason -Orendorff . 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" and 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) - - >>> unicode('abcdef' + chr(255)) - Traceback (most recent call last): - File "", 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 "", 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 - 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 "", 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 "", 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 - (, '\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 - -for a list of category codes. - -References -'''''''''''''' - -The Unicode and 8-bit string types are described in the Python library -reference at . - -The documentation for the ``unicodedata`` module is at -. - -The documentation for the ``codecs`` module is at -. - -Marc-André Lemburg gave a presentation at EuroPython 2002 -titled "Python and Unicode". A PDF version of his slides -is available at , -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 - -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 ce10e52..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 - `_. - -.. contents:: urllib2 Tutorial - - -Introduction -============ - -.. sidebar:: Related Articles - - You may also find useful the following article on fetching web - resources with Python : - - * `Basic Authentication `_ - - A tutorial on *Basic Authentication*, with examples in Python. - - This HOWTO is written by `Michael Foord - `_. - -**urllib2** is a `Python `_ 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 `_ , -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 `_ -for more details). - -If you do not pass the ``data`` argument, urllib2 uses a **GET** -request. One way in which GET and POST requests differ is that POST -requests often have "side-effects": they change the state of the -system in some way (for example by placing an order with the website -for a hundredweight of tinned spam to be delivered to your door). -Though the HTTP standard makes it clear that POSTs are intended to -*always* cause side-effects, and GET requests *never* to cause -side-effects, nothing prevents a GET request from having side-effects, -nor a POST requests from having no side-effects. Data can also be -passed in an HTTP GET request by encoding it in the URL itself. - -This is done as follows:: - - >>> import urllib2 - >>> import urllib - >>> data = {} - >>> data['name'] = 'Somebody Here' - >>> data['location'] = 'Northampton' - >>> data['language'] = 'Python' - >>> url_values = urllib.urlencode(data) - >>> print url_values - name=Somebody+Here&language=Python&location=Northampton - >>> url = 'http://www.example.com/example.cgi' - >>> full_url = url + '?' + url_values - >>> data = urllib2.open(full_url) - -Notice that the full URL is created by adding a ``?`` to the URL, followed by -the encoded values. - -Headers -------- - -We'll discuss here one particular HTTP header, to illustrate how to -add headers to your HTTP request. - -Some websites [#]_ dislike being browsed by programs, or send -different versions to different browsers [#]_ . By default urllib2 -identifies itself as ``Python-urllib/x.y`` (where ``x`` and ``y`` are -the major and minor version numbers of the Python release, -e.g. ``Python-urllib/2.5``), which may confuse the site, or just plain -not work. The way a browser identifies itself is through the -``User-Agent`` header [#]_. When you create a Request object you can -pass a dictionary of headers in. The following example makes the same -request as above, but identifies itself as a version of Internet -Explorer [#]_. :: - - import urllib - import urllib2 - - url = 'http://www.someserver.com/cgi-bin/register.cgi' - user_agent = 'Mozilla/4.0 (compatible; MSIE 5.5; Windows NT)' - values = {'name' : 'Michael Foord', - 'location' : 'Northampton', - 'language' : 'Python' } - headers = { 'User-Agent' : user_agent } - - data = urllib.urlencode(values) - req = urllib2.Request(url, data, headers) - response = urllib2.urlopen(req) - the_page = response.read() - -The response also has two useful methods. See the section on `info and -geturl`_ which comes after we have a look at what happens when things -go wrong. - - -Handling Exceptions -=================== - -*urlopen* raises ``URLError`` when it cannot handle a response (though -as usual with Python APIs, builtin exceptions such as ValueError, -TypeError etc. may also be raised). - -``HTTPError`` is the subclass of ``URLError`` raised in the specific -case of HTTP URLs. - -URLError --------- - -Often, URLError is raised because there is no network connection (no -route to the specified server), or the specified server doesn't exist. -In this case, the exception raised will have a 'reason' attribute, -which is a tuple containing an error code and a text error message. - -e.g. :: - - >>> req = urllib2.Request('http://www.pretend_server.org') - >>> try: urllib2.urlopen(req) - >>> except URLError, e: - >>> print e.reason - >>> - (4, 'getaddrinfo failed') - - -HTTPError ---------- - -Every HTTP response from the server contains a numeric "status -code". Sometimes the status code indicates that the server is unable -to fulfil the request. The default handlers will handle some of these -responses for you (for example, if the response is a "redirection" -that requests the client fetch the document from a different URL, -urllib2 will handle that for you). For those it can't handle, urlopen -will raise an ``HTTPError``. Typical errors include '404' (page not -found), '403' (request forbidden), and '401' (authentication -required). - -See section 10 of RFC 2616 for a reference on all the HTTP error -codes. - -The ``HTTPError`` instance raised will have an integer 'code' -attribute, which corresponds to the error sent by the server. - -Error Codes -~~~~~~~~~~~ - -Because the default handlers handle redirects (codes in the 300 -range), and codes in the 100-299 range indicate success, you will -usually only see error codes in the 400-599 range. - -``BaseHTTPServer.BaseHTTPRequestHandler.responses`` is a useful -dictionary of response codes in that shows all the response codes used -by RFC 2616. The dictionary is reproduced here for convenience :: - - # Table mapping response codes to messages; entries have the - # form {code: (shortmessage, longmessage)}. - responses = { - 100: ('Continue', 'Request received, please continue'), - 101: ('Switching Protocols', - 'Switching to new protocol; obey Upgrade header'), - - 200: ('OK', 'Request fulfilled, document follows'), - 201: ('Created', 'Document created, URL follows'), - 202: ('Accepted', - 'Request accepted, processing continues off-line'), - 203: ('Non-Authoritative Information', 'Request fulfilled from cache'), - 204: ('No Content', 'Request fulfilled, nothing follows'), - 205: ('Reset Content', 'Clear input form for further input.'), - 206: ('Partial Content', 'Partial content follows.'), - - 300: ('Multiple Choices', - 'Object has several resources -- see URI list'), - 301: ('Moved Permanently', 'Object moved permanently -- see URI list'), - 302: ('Found', 'Object moved temporarily -- see URI list'), - 303: ('See Other', 'Object moved -- see Method and URL list'), - 304: ('Not Modified', - 'Document has not changed since given time'), - 305: ('Use Proxy', - 'You must use proxy specified in Location to access this ' - 'resource.'), - 307: ('Temporary Redirect', - 'Object moved temporarily -- see URI list'), - - 400: ('Bad Request', - 'Bad request syntax or unsupported method'), - 401: ('Unauthorized', - 'No permission -- see authorization schemes'), - 402: ('Payment Required', - 'No payment -- see charging schemes'), - 403: ('Forbidden', - 'Request forbidden -- authorization will not help'), - 404: ('Not Found', 'Nothing matches the given URI'), - 405: ('Method Not Allowed', - 'Specified method is invalid for this server.'), - 406: ('Not Acceptable', 'URI not available in preferred format.'), - 407: ('Proxy Authentication Required', 'You must authenticate with ' - 'this proxy before proceeding.'), - 408: ('Request Timeout', 'Request timed out; try again later.'), - 409: ('Conflict', 'Request conflict.'), - 410: ('Gone', - 'URI no longer exists and has been permanently removed.'), - 411: ('Length Required', 'Client must specify Content-Length.'), - 412: ('Precondition Failed', 'Precondition in headers is false.'), - 413: ('Request Entity Too Large', 'Entity is too large.'), - 414: ('Request-URI Too Long', 'URI is too long.'), - 415: ('Unsupported Media Type', 'Entity body in unsupported format.'), - 416: ('Requested Range Not Satisfiable', - 'Cannot satisfy request range.'), - 417: ('Expectation Failed', - 'Expect condition could not be satisfied.'), - - 500: ('Internal Server Error', 'Server got itself in trouble'), - 501: ('Not Implemented', - 'Server does not support this operation'), - 502: ('Bad Gateway', 'Invalid responses from another server/proxy.'), - 503: ('Service Unavailable', - 'The server cannot process the request due to a high load'), - 504: ('Gateway Timeout', - 'The gateway server did not receive a timely response'), - 505: ('HTTP Version Not Supported', 'Cannot fulfill request.'), - } - -When an error is raised the server responds by returning an HTTP error -code *and* an error page. You can use the ``HTTPError`` instance as a -response on the page returned. This means that as well as the code -attribute, it also has read, geturl, and info, methods. :: - - >>> req = urllib2.Request('http://www.python.org/fish.html') - >>> try: - >>> urllib2.urlopen(req) - >>> except URLError, e: - >>> print e.code - >>> print e.read() - >>> - 404 - - - Error 404: File Not Found - ...... etc... - -Wrapping it Up --------------- - -So if you want to be prepared for ``HTTPError`` *or* ``URLError`` -there are two basic approaches. I prefer the second approach. - -Number 1 -~~~~~~~~ - -:: - - - from urllib2 import Request, urlopen, URLError, HTTPError - req = Request(someurl) - try: - response = urlopen(req) - except HTTPError, e: - print 'The server couldn\'t fulfill the request.' - print 'Error code: ', e.code - except URLError, e: - print 'We failed to reach a server.' - print 'Reason: ', e.reason - else: - # everything is fine - - -.. note:: - - The ``except HTTPError`` *must* come first, otherwise ``except URLError`` - will *also* catch an ``HTTPError``. - -Number 2 -~~~~~~~~ - -:: - - from urllib2 import Request, urlopen, URLError - req = Request(someurl) - try: - response = urlopen(req) - except URLError, e: - if hasattr(e, 'reason'): - print 'We failed to reach a server.' - print 'Reason: ', e.reason - elif hasattr(e, 'code'): - print 'The server couldn\'t fulfill the request.' - print 'Error code: ', e.code - else: - # everything is fine - - -info and geturl -=============== - -The response returned by urlopen (or the ``HTTPError`` instance) has -two useful methods ``info`` and ``geturl``. - -**geturl** - this returns the real URL of the page fetched. This is -useful because ``urlopen`` (or the opener object used) may have -followed a redirect. The URL of the page fetched may not be the same -as the URL requested. - -**info** - this returns a dictionary-like object that describes the -page fetched, particularly the headers sent by the server. It is -currently an ``httplib.HTTPMessage`` instance. - -Typical headers include 'Content-length', 'Content-type', and so -on. See the -`Quick Reference to HTTP Headers `_ -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 `_. - -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 `_. -.. [#] Like Google for example. The *proper* way to use google from a program - is to use `PyGoogle `_ of course. See - `Voidspace 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 - `_. - 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 @@ -

This document was generated using the - LaTeX2HTML translator. -

- -

- LaTeX2HTML is Copyright © - 1993, 1994, 1995, 1996, 1997, Nikos - Drakos, Computer Based Learning Unit, University of - Leeds, and Copyright © 1997, 1998, Ross - Moore, Mathematics Department, Macquarie University, - Sydney. -

- -

The application of - LaTeX2HTML to the Python - documentation has been heavily tailored by Fred L. Drake, - Jr. Original navigation icons were contributed by Christopher - Petrilli. -

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 @@ - - - - About the Python Documentation - - - - - - - - - - -
- - - - - - - - - - -
upAbout the Python Documentation
- Up: - - - Python Documentation Index -
-
-
- -

About the Python Documentation

- -

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 Python Web site. - -

A list of contributors is available. - -

Comments and Questions

- -

General comments and questions regarding this document should - be sent by email to docs@python.org. If you find specific errors in - this document, please report the bug at the Python Bug - Tracker at SourceForge. - 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. -

- -

Questions regarding how to use the information in this - document should be sent to the Python news group, comp.lang.python, or the Python mailing list (which is gated to the newsgroup and - carries the same content). -

- -

For any of these channels, please be sure not to send HTML email. - Thanks. -

- -
- - diff --git a/Doc/html/icons/blank.gif b/Doc/html/icons/blank.gif deleted file mode 100644 index 2e31f4e..0000000 Binary files a/Doc/html/icons/blank.gif and /dev/null differ diff --git a/Doc/html/icons/blank.png b/Doc/html/icons/blank.png deleted file mode 100644 index 2af5639..0000000 Binary files a/Doc/html/icons/blank.png and /dev/null differ diff --git a/Doc/html/icons/contents.gif b/Doc/html/icons/contents.gif deleted file mode 100644 index 6d299c4..0000000 Binary files a/Doc/html/icons/contents.gif and /dev/null differ diff --git a/Doc/html/icons/contents.png b/Doc/html/icons/contents.png deleted file mode 100644 index 3429be0..0000000 Binary files a/Doc/html/icons/contents.png and /dev/null differ diff --git a/Doc/html/icons/index.gif b/Doc/html/icons/index.gif deleted file mode 100644 index 32eecfb..0000000 Binary files a/Doc/html/icons/index.gif and /dev/null differ diff --git a/Doc/html/icons/index.png b/Doc/html/icons/index.png deleted file mode 100644 index cd918af..0000000 Binary files a/Doc/html/icons/index.png and /dev/null differ diff --git a/Doc/html/icons/modules.gif b/Doc/html/icons/modules.gif deleted file mode 100644 index f5860b6..0000000 Binary files a/Doc/html/icons/modules.gif and /dev/null differ diff --git a/Doc/html/icons/modules.png b/Doc/html/icons/modules.png deleted file mode 100644 index 8fa8b75..0000000 Binary files a/Doc/html/icons/modules.png and /dev/null differ diff --git a/Doc/html/icons/next.gif b/Doc/html/icons/next.gif deleted file mode 100644 index 5dcaff8..0000000 Binary files a/Doc/html/icons/next.gif and /dev/null differ diff --git a/Doc/html/icons/next.png b/Doc/html/icons/next.png deleted file mode 100644 index cfe5e51..0000000 Binary files a/Doc/html/icons/next.png and /dev/null differ diff --git a/Doc/html/icons/previous.gif b/Doc/html/icons/previous.gif deleted file mode 100644 index de1da16..0000000 Binary files a/Doc/html/icons/previous.gif and /dev/null differ diff --git a/Doc/html/icons/previous.png b/Doc/html/icons/previous.png deleted file mode 100644 index 497def4..0000000 Binary files a/Doc/html/icons/previous.png and /dev/null differ diff --git a/Doc/html/icons/pyfav.gif b/Doc/html/icons/pyfav.gif deleted file mode 100644 index 58271ed..0000000 Binary files a/Doc/html/icons/pyfav.gif and /dev/null differ diff --git a/Doc/html/icons/pyfav.png b/Doc/html/icons/pyfav.png deleted file mode 100644 index d2d8669..0000000 Binary files a/Doc/html/icons/pyfav.png and /dev/null differ diff --git a/Doc/html/icons/up.gif b/Doc/html/icons/up.gif deleted file mode 100644 index a9d3e13..0000000 Binary files a/Doc/html/icons/up.gif and /dev/null differ diff --git a/Doc/html/icons/up.png b/Doc/html/icons/up.png deleted file mode 100644 index a90e028..0000000 Binary files a/Doc/html/icons/up.png and /dev/null 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 @@ - - - Python @RELEASE@ Documentation - @DATE@ - - - - - - - - - - -
- - - - - - - - - - -
- Python DocumentationModule Index
-
-
-
-

Python Documentation

- -

- Release @RELEASE@ -
- @DATE@ -

-
- - - - - - - - - - - - - - - - -
- - - -
-   - - -   - -
-   - - -   - -
-

- -

-
- See About the Python Documentation - for information on suggesting changes. -
- - 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 @@ -

This document was generated using the - LaTeX2HTML translator. -

- -

- LaTeX2HTML is Copyright © - 1993, 1994, 1995, 1996, 1997, Nikos - Drakos, Computer Based Learning Unit, University of - Leeds, and Copyright © 1997, 1998, Ross - Moore, Mathematics Department, Macquarie University, - Sydney. -

- -

The application of - LaTeX2HTML to the Python - documentation has been heavily tailored by Fred L. Drake, - Jr. Original navigation icons were contributed by Christopher - Petrilli. -

- -
- -

Comments and Questions

- -

General comments and questions regarding this document should - be sent by email to docs@python.org. If you find specific errors in - this document, either in the content or the presentation, please - report the bug at the Python Bug - Tracker at SourceForge. - 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. -

- -

Questions regarding how to use the information in this - document should be sent to the Python news group, comp.lang.python, or the Python mailing list (which is gated to the newsgroup and - carries the same content). -

- -

For any of these channels, please be sure not to send HTML email. - Thanks. -

diff --git a/Doc/html/style.css b/Doc/html/style.css deleted file mode 100644 index 06a613c..0000000 --- a/Doc/html/style.css +++ /dev/null @@ -1,243 +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
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; } - -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 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./ - temp./ -\end{verbatim} - -where \code{} 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{} 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= -\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 abba0da..0000000 --- a/Doc/lib/asttable.tex +++ /dev/null @@ -1,283 +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{Backquote}{\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/compiler.tex b/Doc/lib/compiler.tex deleted file mode 100644 index d4f4124..0000000 --- a/Doc/lib/compiler.tex +++ /dev/null @@ -1,353 +0,0 @@ -\chapter{Python compiler package \label{compiler}} - -\sectionauthor{Jeremy Hylton}{jeremy@zope.com} - - -The Python compiler package is a tool for analyzing Python source code -and generating Python bytecode. The compiler contains libraries to -generate an abstract syntax tree from Python source code and to -generate Python bytecode from the tree. - -The \refmodule{compiler} package is a Python source to bytecode -translator written in Python. It uses the built-in parser and -standard \refmodule{parser} module to generated a concrete syntax -tree. This tree is used to generate an abstract syntax tree (AST) and -then Python bytecode. - -The full functionality of the package duplicates the builtin compiler -provided with the Python interpreter. It is intended to match its -behavior almost exactly. Why implement another compiler that does the -same thing? The package is useful for a variety of purposes. It can -be modified more easily than the builtin compiler. The AST it -generates is useful for analyzing Python source code. - -This chapter explains how the various components of the -\refmodule{compiler} package work. It blends reference material with -a tutorial. - -The following modules are part of the \refmodule{compiler} package: - -\localmoduletable - - -\section{The basic interface} - -\declaremodule{}{compiler} - -The top-level of the package defines four functions. If you import -\module{compiler}, you will get these functions and a collection of -modules contained in the package. - -\begin{funcdesc}{parse}{buf} -Returns an abstract syntax tree for the Python source code in \var{buf}. -The function raises \exception{SyntaxError} if there is an error in the -source code. The return value is a \class{compiler.ast.Module} instance -that contains the tree. -\end{funcdesc} - -\begin{funcdesc}{parseFile}{path} -Return an abstract syntax tree for the Python source code in the file -specified by \var{path}. It is equivalent to -\code{parse(open(\var{path}).read())}. -\end{funcdesc} - -\begin{funcdesc}{walk}{ast, visitor\optional{, verbose}} -Do a pre-order walk over the abstract syntax tree \var{ast}. Call the -appropriate method on the \var{visitor} instance for each node -encountered. -\end{funcdesc} - -\begin{funcdesc}{compile}{source, filename, mode, flags=None, - dont_inherit=None} -Compile the string \var{source}, a Python module, statement or -expression, into a code object that can be executed by the exec -statement or \function{eval()}. This function is a replacement for the -built-in \function{compile()} function. - -The \var{filename} will be used for run-time error messages. - -The \var{mode} must be 'exec' to compile a module, 'single' to compile a -single (interactive) statement, or 'eval' to compile an expression. - -The \var{flags} and \var{dont_inherit} arguments affect future-related -statements, but are not supported yet. -\end{funcdesc} - -\begin{funcdesc}{compileFile}{source} -Compiles the file \var{source} and generates a .pyc file. -\end{funcdesc} - -The \module{compiler} package contains the following modules: -\refmodule[compiler.ast]{ast}, \module{consts}, \module{future}, -\module{misc}, \module{pyassem}, \module{pycodegen}, \module{symbols}, -\module{transformer}, and \refmodule[compiler.visitor]{visitor}. - -\section{Limitations} - -There are some problems with the error checking of the compiler -package. The interpreter detects syntax errors in two distinct -phases. One set of errors is detected by the interpreter's parser, -the other set by the compiler. The compiler package relies on the -interpreter's parser, so it get the first phases of error checking for -free. It implements the second phase itself, and that implementation is -incomplete. For example, the compiler package does not raise an error -if a name appears more than once in an argument list: -\code{def f(x, x): ...} - -A future version of the compiler should fix these problems. - -\section{Python Abstract Syntax} - -The \module{compiler.ast} module defines an abstract syntax for -Python. In the abstract syntax tree, each node represents a syntactic -construct. The root of the tree is \class{Module} object. - -The abstract syntax offers a higher level interface to parsed Python -source code. The \refmodule{parser} -module and the compiler written in C for the Python interpreter use a -concrete syntax tree. The concrete syntax is tied closely to the -grammar description used for the Python parser. Instead of a single -node for a construct, there are often several levels of nested nodes -that are introduced by Python's precedence rules. - -The abstract syntax tree is created by the -\module{compiler.transformer} module. The transformer relies on the -builtin Python parser to generate a concrete syntax tree. It -generates an abstract syntax tree from the concrete tree. - -The \module{transformer} module was created by Greg -Stein\index{Stein, Greg} and Bill Tutt\index{Tutt, Bill} for an -experimental Python-to-C compiler. The current version contains a -number of modifications and improvements, but the basic form of the -abstract syntax and of the transformer are due to Stein and Tutt. - -\subsection{AST Nodes} - -\declaremodule{}{compiler.ast} - -The \module{compiler.ast} module is generated from a text file that -describes each node type and its elements. Each node type is -represented as a class that inherits from the abstract base class -\class{compiler.ast.Node} and defines a set of named attributes for -child nodes. - -\begin{classdesc}{Node}{} - - The \class{Node} instances are created automatically by the parser - generator. The recommended interface for specific \class{Node} - instances is to use the public attributes to access child nodes. A - public attribute may be bound to a single node or to a sequence of - nodes, depending on the \class{Node} type. For example, the - \member{bases} attribute of the \class{Class} node, is bound to a - list of base class nodes, and the \member{doc} attribute is bound to - a single node. - - Each \class{Node} instance has a \member{lineno} attribute which may - be \code{None}. XXX Not sure what the rules are for which nodes - will have a useful lineno. -\end{classdesc} - -All \class{Node} objects offer the following methods: - -\begin{methoddesc}{getChildren}{} - Returns a flattened list of the child nodes and objects in the - order they occur. Specifically, the order of the nodes is the - order in which they appear in the Python grammar. Not all of the - children are \class{Node} instances. The names of functions and - classes, for example, are plain strings. -\end{methoddesc} - -\begin{methoddesc}{getChildNodes}{} - Returns a flattened list of the child nodes in the order they - occur. This method is like \method{getChildren()}, except that it - only returns those children that are \class{Node} instances. -\end{methoddesc} - -Two examples illustrate the general structure of \class{Node} -classes. The \keyword{while} statement is defined by the following -grammar production: - -\begin{verbatim} -while_stmt: "while" expression ":" suite - ["else" ":" suite] -\end{verbatim} - -The \class{While} node has three attributes: \member{test}, -\member{body}, and \member{else_}. (If the natural name for an -attribute is also a Python reserved word, it can't be used as an -attribute name. An underscore is appended to the word to make it a -legal identifier, hence \member{else_} instead of \keyword{else}.) - -The \keyword{if} statement is more complicated because it can include -several tests. - -\begin{verbatim} -if_stmt: 'if' test ':' suite ('elif' test ':' suite)* ['else' ':' suite] -\end{verbatim} - -The \class{If} node only defines two attributes: \member{tests} and -\member{else_}. The \member{tests} attribute is a sequence of test -expression, consequent body pairs. There is one pair for each -\keyword{if}/\keyword{elif} clause. The first element of the pair is -the test expression. The second elements is a \class{Stmt} node that -contains the code to execute if the test is true. - -The \method{getChildren()} method of \class{If} returns a flat list of -child nodes. If there are three \keyword{if}/\keyword{elif} clauses -and no \keyword{else} clause, then \method{getChildren()} will return -a list of six elements: the first test expression, the first -\class{Stmt}, the second text expression, etc. - -The following table lists each of the \class{Node} subclasses defined -in \module{compiler.ast} and each of the public attributes available -on their instances. The values of most of the attributes are -themselves \class{Node} instances or sequences of instances. When the -value is something other than an instance, the type is noted in the -comment. The attributes are listed in the order in which they are -returned by \method{getChildren()} and \method{getChildNodes()}. - -\input{asttable} - - -\subsection{Assignment nodes} - -There is a collection of nodes used to represent assignments. Each -assignment statement in the source code becomes a single -\class{Assign} node in the AST. The \member{nodes} attribute is a -list that contains a node for each assignment target. This is -necessary because assignment can be chained, e.g. \code{a = b = 2}. -Each \class{Node} in the list will be one of the following classes: -\class{AssAttr}, \class{AssList}, \class{AssName}, or -\class{AssTuple}. - -Each target assignment node will describe the kind of object being -assigned to: \class{AssName} for a simple name, e.g. \code{a = 1}. -\class{AssAttr} for an attribute assigned, e.g. \code{a.x = 1}. -\class{AssList} and \class{AssTuple} for list and tuple expansion -respectively, e.g. \code{a, b, c = a_tuple}. - -The target assignment nodes also have a \member{flags} attribute that -indicates whether the node is being used for assignment or in a delete -statement. The \class{AssName} is also used to represent a delete -statement, e.g. \class{del x}. - -When an expression contains several attribute references, an -assignment or delete statement will contain only one \class{AssAttr} -node -- for the final attribute reference. The other attribute -references will be represented as \class{Getattr} nodes in the -\member{expr} attribute of the \class{AssAttr} instance. - -\subsection{Examples} - -This section shows several simple examples of ASTs for Python source -code. The examples demonstrate how to use the \function{parse()} -function, what the repr of an AST looks like, and how to access -attributes of an AST node. - -The first module defines a single function. Assume it is stored in -\file{/tmp/doublelib.py}. - -\begin{verbatim} -"""This is an example module. - -This is the docstring. -""" - -def double(x): - "Return twice the argument" - return x * 2 -\end{verbatim} - -In the interactive interpreter session below, I have reformatted the -long AST reprs for readability. The AST reprs use unqualified class -names. If you want to create an instance from a repr, you must import -the class names from the \module{compiler.ast} module. - -\begin{verbatim} ->>> import compiler ->>> mod = compiler.parseFile("/tmp/doublelib.py") ->>> mod -Module('This is an example module.\n\nThis is the docstring.\n', - Stmt([Function(None, 'double', ['x'], [], 0, - 'Return twice the argument', - Stmt([Return(Mul((Name('x'), Const(2))))]))])) ->>> from compiler.ast import * ->>> Module('This is an example module.\n\nThis is the docstring.\n', -... Stmt([Function(None, 'double', ['x'], [], 0, -... 'Return twice the argument', -... Stmt([Return(Mul((Name('x'), Const(2))))]))])) -Module('This is an example module.\n\nThis is the docstring.\n', - Stmt([Function(None, 'double', ['x'], [], 0, - 'Return twice the argument', - Stmt([Return(Mul((Name('x'), Const(2))))]))])) ->>> mod.doc -'This is an example module.\n\nThis is the docstring.\n' ->>> for node in mod.node.nodes: -... print node -... -Function(None, 'double', ['x'], [], 0, 'Return twice the argument', - Stmt([Return(Mul((Name('x'), Const(2))))])) ->>> func = mod.node.nodes[0] ->>> func.code -Stmt([Return(Mul((Name('x'), Const(2))))]) -\end{verbatim} - -\section{Using Visitors to Walk ASTs} - -\declaremodule{}{compiler.visitor} - -The visitor pattern is ... The \refmodule{compiler} package uses a -variant on the visitor pattern that takes advantage of Python's -introspection features to eliminate the need for much of the visitor's -infrastructure. - -The classes being visited do not need to be programmed to accept -visitors. The visitor need only define visit methods for classes it -is specifically interested in; a default visit method can handle the -rest. - -XXX The magic \method{visit()} method for visitors. - -\begin{funcdesc}{walk}{tree, visitor\optional{, verbose}} -\end{funcdesc} - -\begin{classdesc}{ASTVisitor}{} - -The \class{ASTVisitor} is responsible for walking over the tree in the -correct order. A walk begins with a call to \method{preorder()}. For -each node, it checks the \var{visitor} argument to \method{preorder()} -for a method named `visitNodeType,' where NodeType is the name of the -node's class, e.g. for a \class{While} node a \method{visitWhile()} -would be called. If the method exists, it is called with the node as -its first argument. - -The visitor method for a particular node type can control how child -nodes are visited during the walk. The \class{ASTVisitor} modifies -the visitor argument by adding a visit method to the visitor; this -method can be used to visit a particular child node. If no visitor is -found for a particular node type, the \method{default()} method is -called. -\end{classdesc} - -\class{ASTVisitor} objects have the following methods: - -XXX describe extra arguments - -\begin{methoddesc}{default}{node\optional{, \moreargs}} -\end{methoddesc} - -\begin{methoddesc}{dispatch}{node\optional{, \moreargs}} -\end{methoddesc} - -\begin{methoddesc}{preorder}{tree, visitor} -\end{methoddesc} - - -\section{Bytecode Generation} - -The code generator is a visitor that emits bytecodes. Each visit method -can call the \method{emit()} method to emit a new bytecode. The basic -code generator is specialized for modules, classes, and functions. An -assembler converts that emitted instructions to the low-level bytecode -format. It handles things like generator of constant lists of code -objects and calculation of jump offsets. 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 fc05d99..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, 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 f04fd54..0000000 --- a/Doc/lib/lib.tex +++ /dev/null @@ -1,480 +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{libsets} -\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{libmimewriter} -\input{libmimify} -\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{libxmllib} - -\input{fileformats} % Miscellaneous file formats -\input{libcsv} -\input{libcfgparser} -\input{librobotparser} -\input{libnetrc} -\input{libxdrlib} - -\input{libcrypto} % Cryptographic Services -\input{libhashlib} -\input{libhmac} -\input{libmd5} -\input{libsha} - -% ============= -% 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{libposixfile} -\input{libresource} -\input{libnis} -\input{libsyslog} -\input{libcommands} - - -% ============= -% NETWORK & COMMUNICATIONS -% ============= - -\input{ipc} % Interprocess communication/networking -\input{libsubprocess} -\input{libsocket} -\input{libsignal} -\input{libpopen2} -\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{libimageop} -\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{librestricted} % Restricted Execution -\input{librexec} -\input{libbastion} - - -\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{compiler} % compiler package -\input{libast} - -\input{libmisc} % Miscellaneous Services -\input{libformatter} - -% ============= -% OTHER PLATFORM-SPECIFIC STUFF -% ============= - -\input{libsgi} % SGI IRIX ONLY -\input{libal} -\input{libcd} -\input{libfl} -\input{libfm} -\input{libgl} -\input{libimgfile} -\input{libjpeg} - -\input{libsun} % SUNOS ONLY -\input{libsunaudio} - -\input{windows} % MS Windows ONLY -\input{libmsilib} -\input{libmsvcrt} -\input{libwinreg} -\input{libwinsound} - -\appendix -\input{libundoc} - -%\chapter{Obsolete Modules} -%\input{libcmpcache} -%\input{libcmp} -%\input{libni} - -\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/libal.tex b/Doc/lib/libal.tex deleted file mode 100644 index e3fdc91..0000000 --- a/Doc/lib/libal.tex +++ /dev/null @@ -1,181 +0,0 @@ -\section{\module{al} --- - Audio functions on the SGI} - -\declaremodule{builtin}{al} - \platform{IRIX} -\modulesynopsis{Audio functions on the SGI.} - - -This module provides access to the audio facilities of the SGI Indy -and Indigo workstations. See section 3A of the IRIX man pages for -details. You'll need to read those man pages to understand what these -functions do! Some of the functions are not available in IRIX -releases before 4.0.5. Again, see the manual to check whether a -specific function is available on your platform. - -All functions and methods defined in this module are equivalent to -the C functions with \samp{AL} prefixed to their name. - -Symbolic constants from the C header file \code{} are -defined in the standard module -\refmodule[al-constants]{AL}\refstmodindex{AL}, see below. - -\warning{The current version of the audio library may dump core -when bad argument values are passed rather than returning an error -status. Unfortunately, since the precise circumstances under which -this may happen are undocumented and hard to check, the Python -interface can provide no protection against this kind of problems. -(One example is specifying an excessive queue size --- there is no -documented upper limit.)} - -The module defines the following functions: - - -\begin{funcdesc}{openport}{name, direction\optional{, config}} -The name and direction arguments are strings. The optional -\var{config} argument is a configuration object as returned by -\function{newconfig()}. The return value is an \dfn{audio port -object}; methods of audio port objects are described below. -\end{funcdesc} - -\begin{funcdesc}{newconfig}{} -The return value is a new \dfn{audio configuration object}; methods of -audio configuration objects are described below. -\end{funcdesc} - -\begin{funcdesc}{queryparams}{device} -The device argument is an integer. The return value is a list of -integers containing the data returned by \cfunction{ALqueryparams()}. -\end{funcdesc} - -\begin{funcdesc}{getparams}{device, list} -The \var{device} argument is an integer. The list argument is a list -such as returned by \function{queryparams()}; it is modified in place -(!). -\end{funcdesc} - -\begin{funcdesc}{setparams}{device, list} -The \var{device} argument is an integer. The \var{list} argument is a -list such as returned by \function{queryparams()}. -\end{funcdesc} - - -\subsection{Configuration Objects \label{al-config-objects}} - -Configuration objects returned by \function{newconfig()} have the -following methods: - -\begin{methoddesc}[audio configuration]{getqueuesize}{} -Return the queue size. -\end{methoddesc} - -\begin{methoddesc}[audio configuration]{setqueuesize}{size} -Set the queue size. -\end{methoddesc} - -\begin{methoddesc}[audio configuration]{getwidth}{} -Get the sample width. -\end{methoddesc} - -\begin{methoddesc}[audio configuration]{setwidth}{width} -Set the sample width. -\end{methoddesc} - -\begin{methoddesc}[audio configuration]{getchannels}{} -Get the channel count. -\end{methoddesc} - -\begin{methoddesc}[audio configuration]{setchannels}{nchannels} -Set the channel count. -\end{methoddesc} - -\begin{methoddesc}[audio configuration]{getsampfmt}{} -Get the sample format. -\end{methoddesc} - -\begin{methoddesc}[audio configuration]{setsampfmt}{sampfmt} -Set the sample format. -\end{methoddesc} - -\begin{methoddesc}[audio configuration]{getfloatmax}{} -Get the maximum value for floating sample formats. -\end{methoddesc} - -\begin{methoddesc}[audio configuration]{setfloatmax}{floatmax} -Set the maximum value for floating sample formats. -\end{methoddesc} - - -\subsection{Port Objects \label{al-port-objects}} - -Port objects, as returned by \function{openport()}, have the following -methods: - -\begin{methoddesc}[audio port]{closeport}{} -Close the port. -\end{methoddesc} - -\begin{methoddesc}[audio port]{getfd}{} -Return the file descriptor as an int. -\end{methoddesc} - -\begin{methoddesc}[audio port]{getfilled}{} -Return the number of filled samples. -\end{methoddesc} - -\begin{methoddesc}[audio port]{getfillable}{} -Return the number of fillable samples. -\end{methoddesc} - -\begin{methoddesc}[audio port]{readsamps}{nsamples} -Read a number of samples from the queue, blocking if necessary. -Return the data as a string containing the raw data, (e.g., 2 bytes per -sample in big-endian byte order (high byte, low byte) if you have set -the sample width to 2 bytes). -\end{methoddesc} - -\begin{methoddesc}[audio port]{writesamps}{samples} -Write samples into the queue, blocking if necessary. The samples are -encoded as described for the \method{readsamps()} return value. -\end{methoddesc} - -\begin{methoddesc}[audio port]{getfillpoint}{} -Return the `fill point'. -\end{methoddesc} - -\begin{methoddesc}[audio port]{setfillpoint}{fillpoint} -Set the `fill point'. -\end{methoddesc} - -\begin{methoddesc}[audio port]{getconfig}{} -Return a configuration object containing the current configuration of -the port. -\end{methoddesc} - -\begin{methoddesc}[audio port]{setconfig}{config} -Set the configuration from the argument, a configuration object. -\end{methoddesc} - -\begin{methoddesc}[audio port]{getstatus}{list} -Get status information on last error. -\end{methoddesc} - - -\section{\module{AL} --- - Constants used with the \module{al} module} - -\declaremodule[al-constants]{standard}{AL} - \platform{IRIX} -\modulesynopsis{Constants used with the \module{al} module.} - - -This module defines symbolic constants needed to use the built-in -module \refmodule{al} (see above); they are equivalent to those defined -in the C header file \code{} except that the name prefix -\samp{AL_} is omitted. Read the module source for a complete list of -the defined names. Suggested use: - -\begin{verbatim} -import al -from AL import * -\end{verbatim} 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 9798b57..0000000 --- a/Doc/lib/libatexit.tex +++ /dev/null @@ -1,110 +0,0 @@ -\section{\module{atexit} --- - Exit handlers} - -\declaremodule{standard}{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 a single function to register -cleanup functions. Functions thus registered are automatically -executed upon normal interpreter termination. - -Note: the functions registered via this module are not called when the program is killed by a -signal, when a Python fatal internal error is detected, or when -\function{os._exit()} is called. - -This is an alternate interface to the functionality provided by the -\code{sys.exitfunc} variable. -\withsubitem{(in sys)}{\ttindex{exitfunc}} - -Note: This module is unlikely to work correctly when used with other code -that sets \code{sys.exitfunc}. In particular, other core Python modules are -free to use \module{atexit} without the programmer's knowledge. Authors who -use \code{sys.exitfunc} should convert their code to use -\module{atexit} instead. The simplest way to convert code that sets -\code{sys.exitfunc} is to import \module{atexit} and register the function -that had been bound to \code{sys.exitfunc}. - -\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{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 52c6f3d..0000000 --- a/Doc/lib/libaudioop.tex +++ /dev/null @@ -1,259 +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. This -is the same format as used by the \refmodule{al} and \refmodule{sunaudiodev} -modules. 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/libbastion.tex b/Doc/lib/libbastion.tex deleted file mode 100644 index 9f45c47..0000000 --- a/Doc/lib/libbastion.tex +++ /dev/null @@ -1,57 +0,0 @@ -\section{\module{Bastion} --- - Restricting access to objects} - -\declaremodule{standard}{Bastion} -\modulesynopsis{Providing restricted access to objects.} -\moduleauthor{Barry Warsaw}{bwarsaw@python.org} -\versionchanged[Disabled module]{2.3} - -\begin{notice}[warning] - The documentation has been left in place to help in reading old code - that uses the module. -\end{notice} - -% I'm concerned that the word 'bastion' won't be understood by people -% for whom English is a second language, making the module name -% somewhat mysterious. Thus, the brief definition... --amk - -According to the dictionary, a bastion is ``a fortified area or -position'', or ``something that is considered a stronghold.'' It's a -suitable name for this module, which provides a way to forbid access -to certain attributes of an object. It must always be used with the -\refmodule{rexec} module, in order to allow restricted-mode programs -access to certain safe attributes of an object, while denying access -to other, unsafe attributes. - -% I've punted on the issue of documenting keyword arguments for now. - -\begin{funcdesc}{Bastion}{object\optional{, filter\optional{, - name\optional{, class}}}} -Protect the object \var{object}, returning a bastion for the -object. Any attempt to access one of the object's attributes will -have to be approved by the \var{filter} function; if the access is -denied an \exception{AttributeError} exception will be raised. - -If present, \var{filter} must be a function that accepts a string -containing an attribute name, and returns true if access to that -attribute will be permitted; if \var{filter} returns false, the access -is denied. The default filter denies access to any function beginning -with an underscore (\character{_}). The bastion's string representation -will be \samp{} if a value for -\var{name} is provided; otherwise, \samp{repr(\var{object})} will be -used. - -\var{class}, if present, should be a subclass of \class{BastionClass}; -see the code in \file{bastion.py} for the details. Overriding the -default \class{BastionClass} will rarely be required. -\end{funcdesc} - - -\begin{classdesc}{BastionClass}{getfunc, name} -Class which actually implements bastion objects. This is the default -class used by \function{Bastion()}. The \var{getfunc} parameter is a -function which returns the value of an attribute which should be -exposed to the restricted execution environment when called with the -name of the attribute as the only parameter. \var{name} is used to -construct the \function{repr()} of the \class{BastionClass} instance. -\end{classdesc} 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. , with an -% example based on the PyModules FAQ entry by Aaron Watters -% . - - -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 6e86d24..0000000 --- a/Doc/lib/libbsddb.tex +++ /dev/null @@ -1,208 +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{notice} -Beginning in 2.3 some \UNIX{} versions of Python may have a \module{bsddb185} -module. This is present \emph{only} to allow backwards compatibility with -systems which ship with the old Berkeley DB 1.85 database library. The -\module{bsddb185} module should never be used directly in new code. -\end{notice} - - -\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 fe0e3af..0000000 --- a/Doc/lib/libbz2.tex +++ /dev/null @@ -1,174 +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]{xreadlines}{} -For backward compatibility. \class{BZ2File} objects now include the -performance optimizations previously implemented in the -\module{xreadlines} module. -\deprecated{2.3}{This exists only for compatibility with the method by - this name on \class{file} objects, which is - deprecated. Use \code{for line in file} instead.} -\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/libcd.tex b/Doc/lib/libcd.tex deleted file mode 100644 index 83bd2ba..0000000 --- a/Doc/lib/libcd.tex +++ /dev/null @@ -1,304 +0,0 @@ -\section{\module{cd} --- - CD-ROM access on SGI systems} - -\declaremodule{builtin}{cd} - \platform{IRIX} -\modulesynopsis{Interface to the CD-ROM on Silicon Graphics systems.} - - -This module provides an interface to the Silicon Graphics CD library. -It is available only on Silicon Graphics systems. - -The way the library works is as follows. A program opens the CD-ROM -device with \function{open()} and creates a parser to parse the data -from the CD with \function{createparser()}. The object returned by -\function{open()} can be used to read data from the CD, but also to get -status information for the CD-ROM device, and to get information about -the CD, such as the table of contents. Data from the CD is passed to -the parser, which parses the frames, and calls any callback -functions that have previously been added. - -An audio CD is divided into \dfn{tracks} or \dfn{programs} (the terms -are used interchangeably). Tracks can be subdivided into -\dfn{indices}. An audio CD contains a \dfn{table of contents} which -gives the starts of the tracks on the CD. Index 0 is usually the -pause before the start of a track. The start of the track as given by -the table of contents is normally the start of index 1. - -Positions on a CD can be represented in two ways. Either a frame -number or a tuple of three values, minutes, seconds and frames. Most -functions use the latter representation. Positions can be both -relative to the beginning of the CD, and to the beginning of the -track. - -Module \module{cd} defines the following functions and constants: - - -\begin{funcdesc}{createparser}{} -Create and return an opaque parser object. The methods of the parser -object are described below. -\end{funcdesc} - -\begin{funcdesc}{msftoframe}{minutes, seconds, frames} -Converts a \code{(\var{minutes}, \var{seconds}, \var{frames})} triple -representing time in absolute time code into the corresponding CD -frame number. -\end{funcdesc} - -\begin{funcdesc}{open}{\optional{device\optional{, mode}}} -Open the CD-ROM device. The return value is an opaque player object; -methods of the player object are described below. The device is the -name of the SCSI device file, e.g. \code{'/dev/scsi/sc0d4l0'}, or -\code{None}. If omitted or \code{None}, the hardware inventory is -consulted to locate a CD-ROM drive. The \var{mode}, if not omitted, -should be the string \code{'r'}. -\end{funcdesc} - -The module defines the following variables: - -\begin{excdesc}{error} -Exception raised on various errors. -\end{excdesc} - -\begin{datadesc}{DATASIZE} -The size of one frame's worth of audio data. This is the size of the -audio data as passed to the callback of type \code{audio}. -\end{datadesc} - -\begin{datadesc}{BLOCKSIZE} -The size of one uninterpreted frame of audio data. -\end{datadesc} - -The following variables are states as returned by -\function{getstatus()}: - -\begin{datadesc}{READY} -The drive is ready for operation loaded with an audio CD. -\end{datadesc} - -\begin{datadesc}{NODISC} -The drive does not have a CD loaded. -\end{datadesc} - -\begin{datadesc}{CDROM} -The drive is loaded with a CD-ROM. Subsequent play or read operations -will return I/O errors. -\end{datadesc} - -\begin{datadesc}{ERROR} -An error occurred while trying to read the disc or its table of -contents. -\end{datadesc} - -\begin{datadesc}{PLAYING} -The drive is in CD player mode playing an audio CD through its audio -jacks. -\end{datadesc} - -\begin{datadesc}{PAUSED} -The drive is in CD layer mode with play paused. -\end{datadesc} - -\begin{datadesc}{STILL} -The equivalent of \constant{PAUSED} on older (non 3301) model Toshiba -CD-ROM drives. Such drives have never been shipped by SGI. -\end{datadesc} - -\begin{datadesc}{audio} -\dataline{pnum} -\dataline{index} -\dataline{ptime} -\dataline{atime} -\dataline{catalog} -\dataline{ident} -\dataline{control} -Integer constants describing the various types of parser callbacks -that can be set by the \method{addcallback()} method of CD parser -objects (see below). -\end{datadesc} - - -\subsection{Player Objects} -\label{player-objects} - -Player objects (returned by \function{open()}) have the following -methods: - -\begin{methoddesc}[CD player]{allowremoval}{} -Unlocks the eject button on the CD-ROM drive permitting the user to -eject the caddy if desired. -\end{methoddesc} - -\begin{methoddesc}[CD player]{bestreadsize}{} -Returns the best value to use for the \var{num_frames} parameter of -the \method{readda()} method. Best is defined as the value that -permits a continuous flow of data from the CD-ROM drive. -\end{methoddesc} - -\begin{methoddesc}[CD player]{close}{} -Frees the resources associated with the player object. After calling -\method{close()}, the methods of the object should no longer be used. -\end{methoddesc} - -\begin{methoddesc}[CD player]{eject}{} -Ejects the caddy from the CD-ROM drive. -\end{methoddesc} - -\begin{methoddesc}[CD player]{getstatus}{} -Returns information pertaining to the current state of the CD-ROM -drive. The returned information is a tuple with the following values: -\var{state}, \var{track}, \var{rtime}, \var{atime}, \var{ttime}, -\var{first}, \var{last}, \var{scsi_audio}, \var{cur_block}. -\var{rtime} is the time relative to the start of the current track; -\var{atime} is the time relative to the beginning of the disc; -\var{ttime} is the total time on the disc. For more information on -the meaning of the values, see the man page \manpage{CDgetstatus}{3dm}. -The value of \var{state} is one of the following: \constant{ERROR}, -\constant{NODISC}, \constant{READY}, \constant{PLAYING}, -\constant{PAUSED}, \constant{STILL}, or \constant{CDROM}. -\end{methoddesc} - -\begin{methoddesc}[CD player]{gettrackinfo}{track} -Returns information about the specified track. The returned -information is a tuple consisting of two elements, the start time of -the track and the duration of the track. -\end{methoddesc} - -\begin{methoddesc}[CD player]{msftoblock}{min, sec, frame} -Converts a minutes, seconds, frames triple representing a time in -absolute time code into the corresponding logical block number for the -given CD-ROM drive. You should use \function{msftoframe()} rather than -\method{msftoblock()} for comparing times. The logical block number -differs from the frame number by an offset required by certain CD-ROM -drives. -\end{methoddesc} - -\begin{methoddesc}[CD player]{play}{start, play} -Starts playback of an audio CD in the CD-ROM drive at the specified -track. The audio output appears on the CD-ROM drive's headphone and -audio jacks (if fitted). Play stops at the end of the disc. -\var{start} is the number of the track at which to start playing the -CD; if \var{play} is 0, the CD will be set to an initial paused -state. The method \method{togglepause()} can then be used to commence -play. -\end{methoddesc} - -\begin{methoddesc}[CD player]{playabs}{minutes, seconds, frames, play} -Like \method{play()}, except that the start is given in minutes, -seconds, and frames instead of a track number. -\end{methoddesc} - -\begin{methoddesc}[CD player]{playtrack}{start, play} -Like \method{play()}, except that playing stops at the end of the -track. -\end{methoddesc} - -\begin{methoddesc}[CD player]{playtrackabs}{track, minutes, seconds, frames, play} -Like \method{play()}, except that playing begins at the specified -absolute time and ends at the end of the specified track. -\end{methoddesc} - -\begin{methoddesc}[CD player]{preventremoval}{} -Locks the eject button on the CD-ROM drive thus preventing the user -from arbitrarily ejecting the caddy. -\end{methoddesc} - -\begin{methoddesc}[CD player]{readda}{num_frames} -Reads the specified number of frames from an audio CD mounted in the -CD-ROM drive. The return value is a string representing the audio -frames. This string can be passed unaltered to the -\method{parseframe()} method of the parser object. -\end{methoddesc} - -\begin{methoddesc}[CD player]{seek}{minutes, seconds, frames} -Sets the pointer that indicates the starting point of the next read of -digital audio data from a CD-ROM. The pointer is set to an absolute -time code location specified in \var{minutes}, \var{seconds}, and -\var{frames}. The return value is the logical block number to which -the pointer has been set. -\end{methoddesc} - -\begin{methoddesc}[CD player]{seekblock}{block} -Sets the pointer that indicates the starting point of the next read of -digital audio data from a CD-ROM. The pointer is set to the specified -logical block number. The return value is the logical block number to -which the pointer has been set. -\end{methoddesc} - -\begin{methoddesc}[CD player]{seektrack}{track} -Sets the pointer that indicates the starting point of the next read of -digital audio data from a CD-ROM. The pointer is set to the specified -track. The return value is the logical block number to which the -pointer has been set. -\end{methoddesc} - -\begin{methoddesc}[CD player]{stop}{} -Stops the current playing operation. -\end{methoddesc} - -\begin{methoddesc}[CD player]{togglepause}{} -Pauses the CD if it is playing, and makes it play if it is paused. -\end{methoddesc} - - -\subsection{Parser Objects} -\label{cd-parser-objects} - -Parser objects (returned by \function{createparser()}) have the -following methods: - -\begin{methoddesc}[CD parser]{addcallback}{type, func, arg} -Adds a callback for the parser. The parser has callbacks for eight -different types of data in the digital audio data stream. Constants -for these types are defined at the \module{cd} module level (see above). -The callback is called as follows: \code{\var{func}(\var{arg}, type, -data)}, where \var{arg} is the user supplied argument, \var{type} is -the particular type of callback, and \var{data} is the data returned -for this \var{type} of callback. The type of the data depends on the -\var{type} of callback as follows: - -\begin{tableii}{l|p{4in}}{code}{Type}{Value} - \lineii{audio}{String which can be passed unmodified to -\function{al.writesamps()}.} - \lineii{pnum}{Integer giving the program (track) number.} - \lineii{index}{Integer giving the index number.} - \lineii{ptime}{Tuple consisting of the program time in minutes, -seconds, and frames.} - \lineii{atime}{Tuple consisting of the absolute time in minutes, -seconds, and frames.} - \lineii{catalog}{String of 13 characters, giving the catalog number -of the CD.} - \lineii{ident}{String of 12 characters, giving the ISRC -identification number of the recording. The string consists of two -characters country code, three characters owner code, two characters -giving the year, and five characters giving a serial number.} - \lineii{control}{Integer giving the control bits from the CD -subcode data} -\end{tableii} -\end{methoddesc} - -\begin{methoddesc}[CD parser]{deleteparser}{} -Deletes the parser and frees the memory it was using. The object -should not be used after this call. This call is done automatically -when the last reference to the object is removed. -\end{methoddesc} - -\begin{methoddesc}[CD parser]{parseframe}{frame} -Parses one or more frames of digital audio data from a CD such as -returned by \method{readda()}. It determines which subcodes are -present in the data. If these subcodes have changed since the last -frame, then \method{parseframe()} executes a callback of the -appropriate type passing to it the subcode data found in the frame. -Unlike the \C{} function, more than one frame of digital audio data -can be passed to this method. -\end{methoddesc} - -\begin{methoddesc}[CD parser]{removecallback}{type} -Removes the callback for the given \var{type}. -\end{methoddesc} - -\begin{methoddesc}[CD parser]{resetparser}{} -Resets the fields of the parser used for tracking subcodes to an -initial state. \method{resetparser()} should be called after the disc -has been changed. -\end{methoddesc} 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{
} or \code{} 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 "CGI script output" -print "

This is my first CGI script

" -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 "

Error

" - print "Please fill in the name and addr fields." - return -print "

name:", form["name"].value -print "

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} - - -\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{}. 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 6a1b0d6..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{raw_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 44103f7..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{''}; -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{''}, 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{''} 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 uses the -built-in function \function{raw_input()}; 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 aeadb1b..0000000 --- a/Doc/lib/libcodecs.tex +++ /dev/null @@ -1,1348 +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} - - -\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} - - -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{base64_codec} - {base64, base-64} - {byte string} - {Convert operand to MIME base64} - -\lineiv{bz2_codec} - {bz2} - {byte string} - {Compress the operand using bz2} - -\lineiv{hex_codec} - {hex} - {byte string} - {Convert operand to hexadecimal representation, with two - digits per byte} - -\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{quopri_codec} - {quopri, quoted-printable, quotedprintable} - {byte string} - {Convert operand to MIME quoted printable} - -\lineiv{raw_unicode_escape} - {} - {Unicode string} - {Produce a string that is suitable as raw Unicode literal in - Python source code} - -\lineiv{rot_13} - {rot13} - {Unicode string} - {Returns the Caesar-cypher encryption of the operand} - -\lineiv{string_escape} - {} - {byte string} - {Produce a string that is suitable as string 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} - -\lineiv{uu_codec} - {uu} - {byte string} - {Convert the operand using uuencode} - -\lineiv{zlib_codec} - {zip, zlib} - {byte string} - {Compress the operand using gzip} - -\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{''}. -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 c0eb6ec..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 "", 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 task.next() - except StopIteration: - continue - pending.append(task) - ->>> for value in roundrobin('abc', 'd', 'efgh'): -... print value - -a -d -e -b -f -c -g -h - -\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 \function{itertools.repeat()} which can supply -any constant value (not just zero): - -\begin{verbatim} ->>> def constant_factory(value): -... return itertools.repeat(value).next ->>> d = defaultdict(constant_factory('')) ->>> d.update(name='John', action='ran') ->>> '%(name)s %(action)s to %(object)s' % d -'John ran to ' -\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 fa9b464..0000000 --- a/Doc/lib/libcommands.tex +++ /dev/null @@ -1,66 +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} - -\begin{funcdesc}{getstatus}{file} -Return the output of \samp{ls -ld \var{file}} as a string. This -function uses the \function{getoutput()} function, and properly -escapes backslashes and dollar signs in the argument. - -\deprecated{2.6}{This function is nonobvious and useless, - also the name is misleading in the presence of - \function{getstatusoutput()}.} -\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' ->>> commands.getstatus('/bin/ls') -'-rwxr-xr-x 1 root 13352 Oct 14 1994 /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 7aa0ea0..0000000 --- a/Doc/lib/libconsts.tex +++ /dev/null @@ -1,31 +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} - Special value used in conjunction with extended slicing syntax. - % 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 "" % name - ->>> with tag("h1"): -... print "foo" -... -

-foo -

-\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 b6a1463..0000000 --- a/Doc/lib/libcrypt.tex +++ /dev/null @@ -1,54 +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 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 e965e31..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, 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 self.reader.next().encode("utf-8") - -class UnicodeReader: - """ - A CSV reader which will iterate over lines in the CSV file "f", - which is encoded in the given encoding. - """ - - def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds): - f = UTF8Recoder(f, encoding) - self.reader = csv.reader(f, dialect=dialect, **kwds) - - def next(self): - row = self.reader.next() - return [unicode(s, "utf-8") for s in row] - - def __iter__(self): - return self - -class UnicodeWriter: - """ - A CSV writer which will write rows to CSV file "f", - which is encoded in the given encoding. - """ - - def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds): - # Redirect output to a queue - self.queue = cStringIO.StringIO() - self.writer = csv.writer(self.queue, dialect=dialect, **kwds) - self.stream = f - self.encoder = codecs.getincrementalencoder(encoding)() - - def writerow(self, row): - self.writer.writerow([s.encode("utf-8") for s in row]) - # Fetch UTF-8 output from the queue ... - data = self.queue.getvalue() - data = data.decode("utf-8") - # ... and reencode it into the target encoding - data = self.encoder.encode(data) - # write to the target stream - self.stream.write(data) - # empty queue - self.queue.truncate(0) - - def writerows(self, rows): - for row in rows: - self.writerow(row) -\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 - ->>> print cdll.msvcrt # doctest: +WINDOWS - ->>> 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 - ->>> libc = CDLL("libc.so.6") # doctest: +LINUX ->>> libc # doctest: +LINUX - ->>> -\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 "", 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 "", 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 "", 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 "", 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 "", 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 "", 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 "", 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 "", 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 "", 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 "", 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 "", line 1, in ? - File "", 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 "", 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 - ->>> print POINT.y - ->>> -\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 - ->>> print Int.second_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 - ->>> 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 - ->>> PI(42) -Traceback (most recent call last): - File "", line 1, in ? -TypeError: expected c_long instead of int ->>> PI(c_int(42)) - ->>> -\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 "", 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)) - ->>> -\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 "", line 1, in ? - File "", 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 -py_cmp_func -py_cmp_func -py_cmp_func -py_cmp_func -py_cmp_func -py_cmp_func -py_cmp_func -py_cmp_func -py_cmp_func ->>> -\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 cf44707..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 xrange(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 a0a257e..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 "", 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 "", 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.StandardError) - 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. . - -\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 560cc27..0000000 --- a/Doc/lib/libdis.tex +++ /dev/null @@ -1,706 +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_CONVERT}{} -Implements \code{TOS = `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_DIVIDE}{} -Implements \code{TOS = TOS1 / TOS} when -\code{from __future__ import division} is not in effect. -\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_DIVIDE}{} -Implements in-place \code{TOS = TOS1 / TOS} when -\code{from __future__ import division} is not in effect. -\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}{PRINT_ITEM}{} -Prints TOS to the file-like object bound to \code{sys.stdout}. There -is one such instruction for each item in the \keyword{print} statement. -\end{opcodedesc} - -\begin{opcodedesc}{PRINT_ITEM_TO}{} -Like \code{PRINT_ITEM}, but prints the item second from TOS to the -file-like object at TOS. This is used by the extended print statement. -\end{opcodedesc} - -\begin{opcodedesc}{PRINT_NEWLINE}{} -Prints a new line on \code{sys.stdout}. This is generated as the -last operation of a \keyword{print} statement, unless the statement -ends with a comma. -\end{opcodedesc} - -\begin{opcodedesc}{PRINT_NEWLINE_TO}{} -Like \code{PRINT_NEWLINE}, but prints the new line on the file-like -object on the TOS. This is used by the extended print statement. -\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}{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}{EXEC_STMT}{} -Implements \code{exec TOS2,TOS1,TOS}. The compiler fills -missing optional parameters with \code{None}. -\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_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{func_closure} slot, and -pushes it on the stack. TOS is the code associated with the function. -If the code object has N free variables, the next N items on the stack -are the cells for these variables. The function also has \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 5e28c2a..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} -.__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{} in your - doctest example each place a blank line is expected. - \versionchanged[\code{} 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 "", 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 "", 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 "", 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 "", 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{}, 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 "", 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{} 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-- -> (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-- -> (2)f()->None --> g(x*2) -(Pdb) list - 1 def f(x): - 2 -> g(x*2) -[EOF] -(Pdb) print x -3 -(Pdb) step ---Return-- -> (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{execfile()} 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 b0f80b6..0000000 --- a/Doc/lib/libexcs.tex +++ /dev/null @@ -1,440 +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}{StandardError} -The base class for all built-in exceptions except -\exception{StopIteration}, \exception{GeneratorExit}, -\exception{KeyboardInterrupt} and \exception{SystemExit}. -\exception{StandardError} itself is derived from \exception{Exception}. -\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 one of the built-in functions (\function{input()} or - \function{raw_input()}) hits an end-of-file condition (\EOF) without - reading any data. -% 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. - It directly inherits from \exception{Exception} instead of - \exception{StandardError} since it is technically not an error. - \versionadded{2.5} -\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 - Interrupts typed when a built-in function \function{input()} or - \function{raw_input()} is waiting for input also raise this - exception. - 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 an iterator's \method{next()} method to signal that there - are no further values. - This is derived from \exception{Exception} rather than - \exception{StandardError}, since this is not considered an error in - its normal application. - \versionadded{2.2} -\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 an \keyword{exec} statement, in a call - to the built-in function \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{StandardError}, 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{StandardError} or \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}='.'} 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/libfl.tex b/Doc/lib/libfl.tex deleted file mode 100644 index bafb8e4..0000000 --- a/Doc/lib/libfl.tex +++ /dev/null @@ -1,507 +0,0 @@ -\section{\module{fl} --- - FORMS library for graphical user interfaces} - -\declaremodule{builtin}{fl} - \platform{IRIX} -\modulesynopsis{FORMS library for applications with graphical user - interfaces.} - - -This module provides an interface to the FORMS Library\index{FORMS -Library} by Mark Overmars\index{Overmars, Mark}. The source for the -library can be retrieved by anonymous ftp from host -\samp{ftp.cs.ruu.nl}, directory \file{SGI/FORMS}. It was last tested -with version 2.0b. - -Most functions are literal translations of their C equivalents, -dropping the initial \samp{fl_} from their name. Constants used by -the library are defined in module \refmodule[fl-constants]{FL} -described below. - -The creation of objects is a little different in Python than in C: -instead of the `current form' maintained by the library to which new -FORMS objects are added, all functions that add a FORMS object to a -form are methods of the Python object representing the form. -Consequently, there are no Python equivalents for the C functions -\cfunction{fl_addto_form()} and \cfunction{fl_end_form()}, and the -equivalent of \cfunction{fl_bgn_form()} is called -\function{fl.make_form()}. - -Watch out for the somewhat confusing terminology: FORMS uses the word -\dfn{object} for the buttons, sliders etc. that you can place in a form. -In Python, `object' means any value. The Python interface to FORMS -introduces two new Python object types: form objects (representing an -entire form) and FORMS objects (representing one button, slider etc.). -Hopefully this isn't too confusing. - -There are no `free objects' in the Python interface to FORMS, nor is -there an easy way to add object classes written in Python. The FORMS -interface to GL event handling is available, though, so you can mix -FORMS with pure GL windows. - -\strong{Please note:} importing \module{fl} implies a call to the GL -function \cfunction{foreground()} and to the FORMS routine -\cfunction{fl_init()}. - -\subsection{Functions Defined in Module \module{fl}} -\nodename{FL Functions} - -Module \module{fl} defines the following functions. For more -information about what they do, see the description of the equivalent -C function in the FORMS documentation: - -\begin{funcdesc}{make_form}{type, width, height} -Create a form with given type, width and height. This returns a -\dfn{form} object, whose methods are described below. -\end{funcdesc} - -\begin{funcdesc}{do_forms}{} -The standard FORMS main loop. Returns a Python object representing -the FORMS object needing interaction, or the special value -\constant{FL.EVENT}. -\end{funcdesc} - -\begin{funcdesc}{check_forms}{} -Check for FORMS events. Returns what \function{do_forms()} above -returns, or \code{None} if there is no event that immediately needs -interaction. -\end{funcdesc} - -\begin{funcdesc}{set_event_call_back}{function} -Set the event callback function. -\end{funcdesc} - -\begin{funcdesc}{set_graphics_mode}{rgbmode, doublebuffering} -Set the graphics modes. -\end{funcdesc} - -\begin{funcdesc}{get_rgbmode}{} -Return the current rgb mode. This is the value of the C global -variable \cdata{fl_rgbmode}. -\end{funcdesc} - -\begin{funcdesc}{show_message}{str1, str2, str3} -Show a dialog box with a three-line message and an OK button. -\end{funcdesc} - -\begin{funcdesc}{show_question}{str1, str2, str3} -Show a dialog box with a three-line message and YES and NO buttons. -It returns \code{1} if the user pressed YES, \code{0} if NO. -\end{funcdesc} - -\begin{funcdesc}{show_choice}{str1, str2, str3, but1\optional{, - but2\optional{, but3}}} -Show a dialog box with a three-line message and up to three buttons. -It returns the number of the button clicked by the user -(\code{1}, \code{2} or \code{3}). -\end{funcdesc} - -\begin{funcdesc}{show_input}{prompt, default} -Show a dialog box with a one-line prompt message and text field in -which the user can enter a string. The second argument is the default -input string. It returns the string value as edited by the user. -\end{funcdesc} - -\begin{funcdesc}{show_file_selector}{message, directory, pattern, default} -Show a dialog box in which the user can select a file. It returns -the absolute filename selected by the user, or \code{None} if the user -presses Cancel. -\end{funcdesc} - -\begin{funcdesc}{get_directory}{} -\funcline{get_pattern}{} -\funcline{get_filename}{} -These functions return the directory, pattern and filename (the tail -part only) selected by the user in the last -\function{show_file_selector()} call. -\end{funcdesc} - -\begin{funcdesc}{qdevice}{dev} -\funcline{unqdevice}{dev} -\funcline{isqueued}{dev} -\funcline{qtest}{} -\funcline{qread}{} -%\funcline{blkqread}{?} -\funcline{qreset}{} -\funcline{qenter}{dev, val} -\funcline{get_mouse}{} -\funcline{tie}{button, valuator1, valuator2} -These functions are the FORMS interfaces to the corresponding GL -functions. Use these if you want to handle some GL events yourself -when using \function{fl.do_events()}. When a GL event is detected that -FORMS cannot handle, \function{fl.do_forms()} returns the special value -\constant{FL.EVENT} and you should call \function{fl.qread()} to read -the event from the queue. Don't use the equivalent GL functions! -\end{funcdesc} - -\begin{funcdesc}{color}{} -\funcline{mapcolor}{} -\funcline{getmcolor}{} -See the description in the FORMS documentation of -\cfunction{fl_color()}, \cfunction{fl_mapcolor()} and -\cfunction{fl_getmcolor()}. -\end{funcdesc} - -\subsection{Form Objects} -\label{form-objects} - -Form objects (returned by \function{make_form()} above) have the -following methods. Each method corresponds to a C function whose -name is prefixed with \samp{fl_}; and whose first argument is a form -pointer; please refer to the official FORMS documentation for -descriptions. - -All the \method{add_*()} methods return a Python object representing -the FORMS object. Methods of FORMS objects are described below. Most -kinds of FORMS object also have some methods specific to that kind; -these methods are listed here. - -\begin{flushleft} - -\begin{methoddesc}[form]{show_form}{placement, bordertype, name} - Show the form. -\end{methoddesc} - -\begin{methoddesc}[form]{hide_form}{} - Hide the form. -\end{methoddesc} - -\begin{methoddesc}[form]{redraw_form}{} - Redraw the form. -\end{methoddesc} - -\begin{methoddesc}[form]{set_form_position}{x, y} -Set the form's position. -\end{methoddesc} - -\begin{methoddesc}[form]{freeze_form}{} -Freeze the form. -\end{methoddesc} - -\begin{methoddesc}[form]{unfreeze_form}{} - Unfreeze the form. -\end{methoddesc} - -\begin{methoddesc}[form]{activate_form}{} - Activate the form. -\end{methoddesc} - -\begin{methoddesc}[form]{deactivate_form}{} - Deactivate the form. -\end{methoddesc} - -\begin{methoddesc}[form]{bgn_group}{} - Begin a new group of objects; return a group object. -\end{methoddesc} - -\begin{methoddesc}[form]{end_group}{} - End the current group of objects. -\end{methoddesc} - -\begin{methoddesc}[form]{find_first}{} - Find the first object in the form. -\end{methoddesc} - -\begin{methoddesc}[form]{find_last}{} - Find the last object in the form. -\end{methoddesc} - -%--- - -\begin{methoddesc}[form]{add_box}{type, x, y, w, h, name} -Add a box object to the form. -No extra methods. -\end{methoddesc} - -\begin{methoddesc}[form]{add_text}{type, x, y, w, h, name} -Add a text object to the form. -No extra methods. -\end{methoddesc} - -%\begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name} -%Add a bitmap object to the form. -%\end{methoddesc} - -\begin{methoddesc}[form]{add_clock}{type, x, y, w, h, name} -Add a clock object to the form. \\ -Method: -\method{get_clock()}. -\end{methoddesc} - -%--- - -\begin{methoddesc}[form]{add_button}{type, x, y, w, h, name} -Add a button object to the form. \\ -Methods: -\method{get_button()}, -\method{set_button()}. -\end{methoddesc} - -\begin{methoddesc}[form]{add_lightbutton}{type, x, y, w, h, name} -Add a lightbutton object to the form. \\ -Methods: -\method{get_button()}, -\method{set_button()}. -\end{methoddesc} - -\begin{methoddesc}[form]{add_roundbutton}{type, x, y, w, h, name} -Add a roundbutton object to the form. \\ -Methods: -\method{get_button()}, -\method{set_button()}. -\end{methoddesc} - -%--- - -\begin{methoddesc}[form]{add_slider}{type, x, y, w, h, name} -Add a slider object to the form. \\ -Methods: -\method{set_slider_value()}, -\method{get_slider_value()}, -\method{set_slider_bounds()}, -\method{get_slider_bounds()}, -\method{set_slider_return()}, -\method{set_slider_size()}, -\method{set_slider_precision()}, -\method{set_slider_step()}. -\end{methoddesc} - -\begin{methoddesc}[form]{add_valslider}{type, x, y, w, h, name} -Add a valslider object to the form. \\ -Methods: -\method{set_slider_value()}, -\method{get_slider_value()}, -\method{set_slider_bounds()}, -\method{get_slider_bounds()}, -\method{set_slider_return()}, -\method{set_slider_size()}, -\method{set_slider_precision()}, -\method{set_slider_step()}. -\end{methoddesc} - -\begin{methoddesc}[form]{add_dial}{type, x, y, w, h, name} -Add a dial object to the form. \\ -Methods: -\method{set_dial_value()}, -\method{get_dial_value()}, -\method{set_dial_bounds()}, -\method{get_dial_bounds()}. -\end{methoddesc} - -\begin{methoddesc}[form]{add_positioner}{type, x, y, w, h, name} -Add a positioner object to the form. \\ -Methods: -\method{set_positioner_xvalue()}, -\method{set_positioner_yvalue()}, -\method{set_positioner_xbounds()}, -\method{set_positioner_ybounds()}, -\method{get_positioner_xvalue()}, -\method{get_positioner_yvalue()}, -\method{get_positioner_xbounds()}, -\method{get_positioner_ybounds()}. -\end{methoddesc} - -\begin{methoddesc}[form]{add_counter}{type, x, y, w, h, name} -Add a counter object to the form. \\ -Methods: -\method{set_counter_value()}, -\method{get_counter_value()}, -\method{set_counter_bounds()}, -\method{set_counter_step()}, -\method{set_counter_precision()}, -\method{set_counter_return()}. -\end{methoddesc} - -%--- - -\begin{methoddesc}[form]{add_input}{type, x, y, w, h, name} -Add a input object to the form. \\ -Methods: -\method{set_input()}, -\method{get_input()}, -\method{set_input_color()}, -\method{set_input_return()}. -\end{methoddesc} - -%--- - -\begin{methoddesc}[form]{add_menu}{type, x, y, w, h, name} -Add a menu object to the form. \\ -Methods: -\method{set_menu()}, -\method{get_menu()}, -\method{addto_menu()}. -\end{methoddesc} - -\begin{methoddesc}[form]{add_choice}{type, x, y, w, h, name} -Add a choice object to the form. \\ -Methods: -\method{set_choice()}, -\method{get_choice()}, -\method{clear_choice()}, -\method{addto_choice()}, -\method{replace_choice()}, -\method{delete_choice()}, -\method{get_choice_text()}, -\method{set_choice_fontsize()}, -\method{set_choice_fontstyle()}. -\end{methoddesc} - -\begin{methoddesc}[form]{add_browser}{type, x, y, w, h, name} -Add a browser object to the form. \\ -Methods: -\method{set_browser_topline()}, -\method{clear_browser()}, -\method{add_browser_line()}, -\method{addto_browser()}, -\method{insert_browser_line()}, -\method{delete_browser_line()}, -\method{replace_browser_line()}, -\method{get_browser_line()}, -\method{load_browser()}, -\method{get_browser_maxline()}, -\method{select_browser_line()}, -\method{deselect_browser_line()}, -\method{deselect_browser()}, -\method{isselected_browser_line()}, -\method{get_browser()}, -\method{set_browser_fontsize()}, -\method{set_browser_fontstyle()}, -\method{set_browser_specialkey()}. -\end{methoddesc} - -%--- - -\begin{methoddesc}[form]{add_timer}{type, x, y, w, h, name} -Add a timer object to the form. \\ -Methods: -\method{set_timer()}, -\method{get_timer()}. -\end{methoddesc} -\end{flushleft} - -Form objects have the following data attributes; see the FORMS -documentation: - -\begin{tableiii}{l|l|l}{member}{Name}{C Type}{Meaning} - \lineiii{window}{int (read-only)}{GL window id} - \lineiii{w}{float}{form width} - \lineiii{h}{float}{form height} - \lineiii{x}{float}{form x origin} - \lineiii{y}{float}{form y origin} - \lineiii{deactivated}{int}{nonzero if form is deactivated} - \lineiii{visible}{int}{nonzero if form is visible} - \lineiii{frozen}{int}{nonzero if form is frozen} - \lineiii{doublebuf}{int}{nonzero if double buffering on} -\end{tableiii} - -\subsection{FORMS Objects} -\label{forms-objects} - -Besides methods specific to particular kinds of FORMS objects, all -FORMS objects also have the following methods: - -\begin{methoddesc}[FORMS object]{set_call_back}{function, argument} -Set the object's callback function and argument. When the object -needs interaction, the callback function will be called with two -arguments: the object, and the callback argument. (FORMS objects -without a callback function are returned by \function{fl.do_forms()} -or \function{fl.check_forms()} when they need interaction.) Call this -method without arguments to remove the callback function. -\end{methoddesc} - -\begin{methoddesc}[FORMS object]{delete_object}{} - Delete the object. -\end{methoddesc} - -\begin{methoddesc}[FORMS object]{show_object}{} - Show the object. -\end{methoddesc} - -\begin{methoddesc}[FORMS object]{hide_object}{} - Hide the object. -\end{methoddesc} - -\begin{methoddesc}[FORMS object]{redraw_object}{} - Redraw the object. -\end{methoddesc} - -\begin{methoddesc}[FORMS object]{freeze_object}{} - Freeze the object. -\end{methoddesc} - -\begin{methoddesc}[FORMS object]{unfreeze_object}{} - Unfreeze the object. -\end{methoddesc} - -%\begin{methoddesc}[FORMS object]{handle_object}{} XXX -%\end{methoddesc} - -%\begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX -%\end{methoddesc} - -FORMS objects have these data attributes; see the FORMS documentation: - -\begin{tableiii}{l|l|l}{member}{Name}{C Type}{Meaning} - \lineiii{objclass}{int (read-only)}{object class} - \lineiii{type}{int (read-only)}{object type} - \lineiii{boxtype}{int}{box type} - \lineiii{x}{float}{x origin} - \lineiii{y}{float}{y origin} - \lineiii{w}{float}{width} - \lineiii{h}{float}{height} - \lineiii{col1}{int}{primary color} - \lineiii{col2}{int}{secondary color} - \lineiii{align}{int}{alignment} - \lineiii{lcol}{int}{label color} - \lineiii{lsize}{float}{label font size} - \lineiii{label}{string}{label string} - \lineiii{lstyle}{int}{label style} - \lineiii{pushed}{int (read-only)}{(see FORMS docs)} - \lineiii{focus}{int (read-only)}{(see FORMS docs)} - \lineiii{belowmouse}{int (read-only)}{(see FORMS docs)} - \lineiii{frozen}{int (read-only)}{(see FORMS docs)} - \lineiii{active}{int (read-only)}{(see FORMS docs)} - \lineiii{input}{int (read-only)}{(see FORMS docs)} - \lineiii{visible}{int (read-only)}{(see FORMS docs)} - \lineiii{radio}{int (read-only)}{(see FORMS docs)} - \lineiii{automatic}{int (read-only)}{(see FORMS docs)} -\end{tableiii} - - -\section{\module{FL} --- - Constants used with the \module{fl} module} - -\declaremodule[fl-constants]{standard}{FL} - \platform{IRIX} -\modulesynopsis{Constants used with the \module{fl} module.} - - -This module defines symbolic constants needed to use the built-in -module \refmodule{fl} (see above); they are equivalent to those defined in -the C header file \code{} except that the name prefix -\samp{FL_} is omitted. Read the module source for a complete list of -the defined names. Suggested use: - -\begin{verbatim} -import fl -from FL import * -\end{verbatim} - - -\section{\module{flp} --- - Functions for loading stored FORMS designs} - -\declaremodule{standard}{flp} - \platform{IRIX} -\modulesynopsis{Functions for loading stored FORMS designs.} - - -This module defines functions that can read form definitions created -by the `form designer' (\program{fdesign}) program that comes with the -FORMS library (see module \refmodule{fl} above). - -For now, see the file \file{flp.doc} in the Python library source -directory for a description. - -XXX A complete description should be inserted here! diff --git a/Doc/lib/libfm.tex b/Doc/lib/libfm.tex deleted file mode 100644 index 0a0c237..0000000 --- a/Doc/lib/libfm.tex +++ /dev/null @@ -1,93 +0,0 @@ -\section{\module{fm} --- - \emph{Font Manager} interface} - -\declaremodule{builtin}{fm} - \platform{IRIX} -\modulesynopsis{\emph{Font Manager} interface for SGI workstations.} - - -This module provides access to the IRIS \emph{Font Manager} library. -\index{Font Manager, IRIS} -\index{IRIS Font Manager} -It is available only on Silicon Graphics machines. -See also: \emph{4Sight User's Guide}, section 1, chapter 5: ``Using -the IRIS Font Manager.'' - -This is not yet a full interface to the IRIS Font Manager. -Among the unsupported features are: matrix operations; cache -operations; character operations (use string operations instead); some -details of font info; individual glyph metrics; and printer matching. - -It supports the following operations: - -\begin{funcdesc}{init}{} -Initialization function. -Calls \cfunction{fminit()}. -It is normally not necessary to call this function, since it is called -automatically the first time the \module{fm} module is imported. -\end{funcdesc} - -\begin{funcdesc}{findfont}{fontname} -Return a font handle object. -Calls \code{fmfindfont(\var{fontname})}. -\end{funcdesc} - -\begin{funcdesc}{enumerate}{} -Returns a list of available font names. -This is an interface to \cfunction{fmenumerate()}. -\end{funcdesc} - -\begin{funcdesc}{prstr}{string} -Render a string using the current font (see the \function{setfont()} font -handle method below). -Calls \code{fmprstr(\var{string})}. -\end{funcdesc} - -\begin{funcdesc}{setpath}{string} -Sets the font search path. -Calls \code{fmsetpath(\var{string})}. -(XXX Does not work!?!) -\end{funcdesc} - -\begin{funcdesc}{fontpath}{} -Returns the current font search path. -\end{funcdesc} - -Font handle objects support the following operations: - -\begin{methoddesc}[font handle]{scalefont}{factor} -Returns a handle for a scaled version of this font. -Calls \code{fmscalefont(\var{fh}, \var{factor})}. -\end{methoddesc} - -\begin{methoddesc}[font handle]{setfont}{} -Makes this font the current font. -Note: the effect is undone silently when the font handle object is -deleted. -Calls \code{fmsetfont(\var{fh})}. -\end{methoddesc} - -\begin{methoddesc}[font handle]{getfontname}{} -Returns this font's name. -Calls \code{fmgetfontname(\var{fh})}. -\end{methoddesc} - -\begin{methoddesc}[font handle]{getcomment}{} -Returns the comment string associated with this font. -Raises an exception if there is none. -Calls \code{fmgetcomment(\var{fh})}. -\end{methoddesc} - -\begin{methoddesc}[font handle]{getfontinfo}{} -Returns a tuple giving some pertinent data about this font. -This is an interface to \code{fmgetfontinfo()}. -The returned tuple contains the following numbers: -\code{(}\var{printermatched}, \var{fixed_width}, \var{xorig}, -\var{yorig}, \var{xsize}, \var{ysize}, \var{height}, -\var{nglyphs}\code{)}. -\end{methoddesc} - -\begin{methoddesc}[font handle]{getstrwidth}{string} -Returns the width, in pixels, of \var{string} when drawn in this font. -Calls \code{fmgetstrwidth(\var{fh}, \var{string})}. -\end{methoddesc} 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 "", 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 bff33aa..0000000 --- a/Doc/lib/libfuncs.tex +++ /dev/null @@ -1,1345 +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} and \class{unicode}. - It cannot be called or instantiated, but it can be used to test whether - an object is an instance of \class{str} or \class{unicode}. - \code{isinstance(obj, basestring)} is equivalent to - \code{isinstance(obj, (str, unicode))}. - \versionadded{2.3} -\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}{callable}{object} - Return true if the \var{object} argument appears callable, false if - not. If this returns true, it is still possible that a call fails, - but if it is false, calling \var{object} will never succeed. Note - that classes are callable (calling a class returns a new instance); - class instances are callable if they have a \method{__call__()} - method. -\end{funcdesc} - -\begin{funcdesc}{chr}{i} - Return a string of one character whose \ASCII{} code is the integer - \var{i}. For example, \code{chr(97)} returns the string \code{'a'}. - This is the inverse of \function{ord()}. The argument must be in - the range [0..255], inclusive; \exception{ValueError} will be raised - if \var{i} is outside that range. -\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 an \keyword{exec} statement 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{''} 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 - \keyword{exec} statement. Execution of statements from a file is - supported by the \function{execfile()} 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{execfile()}. -\end{funcdesc} - -\begin{funcdesc}{execfile}{filename\optional{, globals\optional{, locals}}} - This function is similar to the - \keyword{exec} statement, but parses a file instead of a string. It - is different from the \keyword{import} statement in that it does not - use the module administration --- it reads the file unconditionally - and does not create a new module.\footnote{It is used relatively - rarely so does not warrant being made into a statement.} - - The arguments are a file name and two optional dictionaries. The file is - parsed and evaluated as a sequence of Python statements (similarly to a - module) using the \var{globals} and \var{locals} dictionaries as global and - local namespace. If provided, \var{locals} can be any mapping object. - \versionchanged[formerly \var{locals} was required to be a dictionary]{2.4} - 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 \function{execfile()} is called. The return value is - \code{None}. - - \warning{The default \var{locals} act as described for function - \function{locals()} below: modifications to the default \var{locals} - dictionary should not be attempted. Pass an explicit \var{locals} - dictionary if you need to see effects of the code on \var{locals} after - function \function{execfile()} returns. \function{execfile()} cannot - be used reliably to modify a function's locals.} -\end{funcdesc} - -\begin{funcdesc}{file}{filename\optional{, mode\optional{, bufsize}}} - Constructor function for the \class{file} type, described further - in section~\ref{bltin-file-objects}, ``\ulink{File - Objects}{bltin-file-objects.html}''. The constructor's arguments - are the same as those of the \function{open()} built-in function - described below. - - When opening a file, it's preferable to use \function{open()} instead of - invoking this constructor directly. \class{file} is more suited to - type testing (for example, writing \samp{isinstance(f, file)}). - - \versionadded{2.2} -\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 (of any size) to a hexadecimal string. - The result is a valid Python expression. - \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}{input}{\optional{prompt}} - Equivalent to \code{eval(raw_input(\var{prompt}))}. - \warning{This function is not safe from user errors! It - expects a valid Python expression as input; if the input is not - syntactically valid, a \exception{SyntaxError} will be raised. - Other exceptions may be raised if there is an error during - evaluation. (On the other hand, sometimes this is exactly what you - need when writing a quick script for expert use.)} - - If the \refmodule{readline} module was loaded, then - \function{input()} will use it to provide elaborate line editing and - history features. - - Consider using the \function{raw_input()} function for general input - from users. -\end{funcdesc} - -\begin{funcdesc}{int}{\optional{x\optional{, radix}}} - Convert a string or number to a plain integer. If the argument is a - string, it must contain a possibly signed decimal number - representable as a Python integer, possibly embedded in whitespace. - The \var{radix} parameter gives the base for the - conversion and may be any integer in the range [2, 36], or zero. If - \var{radix} is zero, the proper radix is guessed based on the - contents of string; the interpretation is the same as for integer - literals. If \var{radix} is specified and \var{x} is not a string, - \exception{TypeError} is raised. - Otherwise, the argument may be a plain or - long integer or a floating point number. Conversion of floating - point numbers to integers truncates (towards zero). - If the argument is outside the integer range a long object will - be returned instead. If no arguments are given, returns \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}{long}{\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 a plain or - long integer or a floating point number, and a long integer with - the same value is returned. Conversion of floating - point numbers to integers truncates (towards zero). If no arguments - are given, returns \code{0L}. -\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}{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 (of any size) to an octal string. The - result is a valid Python expression. - \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 8-bit strings and of \function{unichr()} for unicode - objects. If a unicode argument is given and Python was built with - UCS2 Unicode, then the character's code point must be in the range - [0..65535] inclusive; otherwise the string length is two, and a - \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 lists 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} ->>> range(10) -[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] ->>> range(1, 11) -[1, 2, 3, 4, 5, 6, 7, 8, 9, 10] ->>> range(0, 30, 5) -[0, 5, 10, 15, 20, 25] ->>> range(0, 10, 3) -[0, 3, 6, 9] ->>> range(0, -10, -1) -[0, -1, -2, -3, -4, -5, -6, -7, -8, -9] ->>> range(0) -[] ->>> range(1, 0) -[] -\end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{raw_input}{\optional{prompt}} - If the \var{prompt} argument is present, it is written to standard output - without a trailing newline. The function then reads a line from input, - converts it to a string (stripping a trailing newline), and returns that. - When \EOF{} is read, \exception{EOFError} is raised. Example: - -\begin{verbatim} ->>> s = raw_input('--> ') ---> Monty Python's Flying Circus ->>> s -"Monty Python's Flying Circus" -\end{verbatim} - - If the \refmodule{readline} module was loaded, then - \function{raw_input()} will use it to provide elaborate - line editing and history features. -\end{funcdesc} - -\begin{funcdesc}{reduce}{function, iterable\optional{, initializer}} - Apply \var{function} of two arguments cumulatively to the items of - \var{iterable}, from left to right, so as to reduce the iterable 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{iterable}. If the optional - \var{initializer} is present, it is placed before the items of the - iterable in the calculation, and serves as a default when the - iterable is empty. If \var{initializer} is not given and - \var{iterable} contains only one item, the first item is returned. -\end{funcdesc} - -\begin{funcdesc}{reload}{module} - Reload a previously imported \var{module}. The - argument must be a module object, so it must have been successfully - imported before. This is useful if you have edited the module - source file using an external editor and want to try out the new - version without leaving the Python interpreter. The return value is - the module object (the same as the \var{module} argument). - - When \code{reload(module)} is executed: - -\begin{itemize} - - \item Python modules' code is recompiled and the module-level code - reexecuted, defining a new set of objects which are bound to names in - the module's dictionary. The \code{init} function of extension - modules is not called a second time. - - \item As with all other objects in Python the old objects are only - reclaimed after their reference counts drop to zero. - - \item The names in the module namespace are updated to point to - any new or changed objects. - - \item Other references to the old objects (such as names external - to the module) are not rebound to refer to the new objects and - must be updated in each namespace where they occur if that is - desired. - -\end{itemize} - - There are a number of other caveats: - - If a module is syntactically correct but its initialization fails, - the first \keyword{import} statement for it does not bind its name - locally, but does store a (partially initialized) module object in - \code{sys.modules}. To reload the module you must first - \keyword{import} it again (this will bind the name to the partially - initialized module object) before you can \function{reload()} it. - - When a module is reloaded, its dictionary (containing the module's - global variables) is retained. Redefinitions of names will override - the old definitions, so this is generally not a problem. If the new - version of a module does not define a name that was defined by the - old version, the old definition remains. This feature can be used - to the module's advantage if it maintains a global table or cache of - objects --- with a \keyword{try} statement it can test for the - table's presence and skip its initialization if desired: - -\begin{verbatim} -try: - cache -except NameError: - cache = {} -\end{verbatim} - - - It is legal though generally not very useful to reload built-in or - dynamically loaded modules, except for \refmodule{sys}, - \refmodule[main]{__main__} and \refmodule[builtin]{__builtin__}. In - many cases, however, extension modules are not designed to be - initialized more than once, and may fail in arbitrary ways when - reloaded. - - If a module imports objects from another module using \keyword{from} - \ldots{} \keyword{import} \ldots{}, calling \function{reload()} for - the other module does not redefine the objects imported from it --- - one way around this is to re-execute the \keyword{from} statement, - another is to use \keyword{import} and qualified names - (\var{module}.\var{name}) instead. - - If a module instantiates instances of a class, reloading the module - that defines the class does not affect the method definitions of the - instances --- they continue to use the old class definition. The - same is true for derived classes. -\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}} - Return a string containing a nicely printable representation of an - object. For strings, this returns the string itself. The - difference with \code{repr(\var{object})} is that - \code{str(\var{object})} does not always attempt to return a string - that is acceptable to \function{eval()}; its goal is to return a - printable string. If no argument is given, returns the empty - string, \code{''}. -\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})}. - Note that \code{sum(range(\var{n}), \var{m})} is equivalent to - \code{reduce(operator.add, range(\var{n}), \var{m})} - \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}{unichr}{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. - \versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{unicode}{\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}{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}{xrange}{\optional{start,} stop\optional{, step}} - This function is very similar to \function{range()}, but returns an - ``xrange object'' instead of a list. This is an opaque sequence - type which yields the same values as the corresponding list, without - actually storing them all simultaneously. The advantage of - \function{xrange()} over \function{range()} is minimal (since - \function{xrange()} still has to create the values when asked for - them) except when a very large range is used on a memory-starved - machine or when all of the range's elements are never used (such as - when the loop is usually terminated with \keyword{break}). - - \note{\function{xrange()} is intended to be simple and fast. - Implementations may impose restrictions to achieve this. - The C implementation of Python restricts all arguments to - native C longs ("short" Python integers), and also requires - that the number of elements fit in a native C long.} -\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}{apply}{function, args\optional{, keywords}} - The \var{function} argument must be a callable object (a - user-defined or built-in function or method, or a class object) and - the \var{args} argument must be a sequence. The \var{function} is - called with \var{args} as the argument list; the number of arguments - is the length of the tuple. - If the optional \var{keywords} argument is present, it must be a - dictionary whose keys are strings. It specifies keyword arguments - to be added to the end of the argument list. - Calling \function{apply()} is different from just calling - \code{\var{function}(\var{args})}, since in that case there is always - exactly one argument. The use of \function{apply()} is equivalent - to \code{\var{function}(*\var{args}, **\var{keywords})}. - Use of \function{apply()} is not necessary since the ``extended call - syntax,'' as used in the last example, is completely equivalent. - - \deprecated{2.3}{Use the extended call syntax instead, as described - above.} -\end{funcdesc} - -\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} - -\begin{funcdesc}{coerce}{x, y} - Return a tuple consisting of the two numeric arguments converted to - a common type, using the same rules as used by arithmetic - operations. If coercion is not possible, raise \exception{TypeError}. -\end{funcdesc} - -\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} diff --git a/Doc/lib/libfunctools.tex b/Doc/lib/libfunctools.tex deleted file mode 100644 index 9404fca..0000000 --- a/Doc/lib/libfunctools.tex +++ /dev/null @@ -1,132 +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}{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 b38fcd8..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, 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/libgl.tex b/Doc/lib/libgl.tex deleted file mode 100644 index ecf4c36..0000000 --- a/Doc/lib/libgl.tex +++ /dev/null @@ -1,224 +0,0 @@ -\section{\module{gl} --- - \emph{Graphics Library} interface} - -\declaremodule{builtin}{gl} - \platform{IRIX} -\modulesynopsis{Functions from the Silicon Graphics \emph{Graphics Library}.} - - -This module provides access to the Silicon Graphics -\emph{Graphics Library}. -It is available only on Silicon Graphics machines. - -\warning{Some illegal calls to the GL library cause the Python -interpreter to dump core. -In particular, the use of most GL calls is unsafe before the first -window is opened.} - -The module is too large to document here in its entirety, but the -following should help you to get started. -The parameter conventions for the C functions are translated to Python as -follows: - -\begin{itemize} -\item -All (short, long, unsigned) int values are represented by Python -integers. -\item -All float and double values are represented by Python floating point -numbers. -In most cases, Python integers are also allowed. -\item -All arrays are represented by one-dimensional Python lists. -In most cases, tuples are also allowed. -\item -\begin{sloppypar} -All string and character arguments are represented by Python strings, -for instance, -\code{winopen('Hi There!')} -and -\code{rotate(900, 'z')}. -\end{sloppypar} -\item -All (short, long, unsigned) integer arguments or return values that are -only used to specify the length of an array argument are omitted. -For example, the C call - -\begin{verbatim} -lmdef(deftype, index, np, props) -\end{verbatim} - -is translated to Python as - -\begin{verbatim} -lmdef(deftype, index, props) -\end{verbatim} - -\item -Output arguments are omitted from the argument list; they are -transmitted as function return values instead. -If more than one value must be returned, the return value is a tuple. -If the C function has both a regular return value (that is not omitted -because of the previous rule) and an output argument, the return value -comes first in the tuple. -Examples: the C call - -\begin{verbatim} -getmcolor(i, &red, &green, &blue) -\end{verbatim} - -is translated to Python as - -\begin{verbatim} -red, green, blue = getmcolor(i) -\end{verbatim} - -\end{itemize} - -The following functions are non-standard or have special argument -conventions: - -\begin{funcdesc}{varray}{argument} -%JHXXX the argument-argument added -Equivalent to but faster than a number of -\code{v3d()} -calls. -The \var{argument} is a list (or tuple) of points. -Each point must be a tuple of coordinates -\code{(\var{x}, \var{y}, \var{z})} or \code{(\var{x}, \var{y})}. -The points may be 2- or 3-dimensional but must all have the -same dimension. -Float and int values may be mixed however. -The points are always converted to 3D double precision points -by assuming \code{\var{z} = 0.0} if necessary (as indicated in the man page), -and for each point -\code{v3d()} -is called. -\end{funcdesc} - -\begin{funcdesc}{nvarray}{} -Equivalent to but faster than a number of -\code{n3f} -and -\code{v3f} -calls. -The argument is an array (list or tuple) of pairs of normals and points. -Each pair is a tuple of a point and a normal for that point. -Each point or normal must be a tuple of coordinates -\code{(\var{x}, \var{y}, \var{z})}. -Three coordinates must be given. -Float and int values may be mixed. -For each pair, -\code{n3f()} -is called for the normal, and then -\code{v3f()} -is called for the point. -\end{funcdesc} - -\begin{funcdesc}{vnarray}{} -Similar to -\code{nvarray()} -but the pairs have the point first and the normal second. -\end{funcdesc} - -\begin{funcdesc}{nurbssurface}{s_k, t_k, ctl, s_ord, t_ord, type} -% XXX s_k[], t_k[], ctl[][] -Defines a nurbs surface. -The dimensions of -\code{\var{ctl}[][]} -are computed as follows: -\code{[len(\var{s_k}) - \var{s_ord}]}, -\code{[len(\var{t_k}) - \var{t_ord}]}. -\end{funcdesc} - -\begin{funcdesc}{nurbscurve}{knots, ctlpoints, order, type} -Defines a nurbs curve. -The length of ctlpoints is -\code{len(\var{knots}) - \var{order}}. -\end{funcdesc} - -\begin{funcdesc}{pwlcurve}{points, type} -Defines a piecewise-linear curve. -\var{points} -is a list of points. -\var{type} -must be -\code{N_ST}. -\end{funcdesc} - -\begin{funcdesc}{pick}{n} -\funcline{select}{n} -The only argument to these functions specifies the desired size of the -pick or select buffer. -\end{funcdesc} - -\begin{funcdesc}{endpick}{} -\funcline{endselect}{} -These functions have no arguments. -They return a list of integers representing the used part of the -pick/select buffer. -No method is provided to detect buffer overrun. -\end{funcdesc} - -Here is a tiny but complete example GL program in Python: - -\begin{verbatim} -import gl, GL, time - -def main(): - gl.foreground() - gl.prefposition(500, 900, 500, 900) - w = gl.winopen('CrissCross') - gl.ortho2(0.0, 400.0, 0.0, 400.0) - gl.color(GL.WHITE) - gl.clear() - gl.color(GL.RED) - gl.bgnline() - gl.v2f(0.0, 0.0) - gl.v2f(400.0, 400.0) - gl.endline() - gl.bgnline() - gl.v2f(400.0, 0.0) - gl.v2f(0.0, 400.0) - gl.endline() - time.sleep(5) - -main() -\end{verbatim} - - -\begin{seealso} - \seetitle[http://pyopengl.sourceforge.net/] - {PyOpenGL: The Python OpenGL Binding} - {An interface to OpenGL\index{OpenGL} is also available; - see information about the - \strong{PyOpenGL}\index{PyOpenGL} project online at - \url{http://pyopengl.sourceforge.net/}. This may be a - better option if support for SGI hardware from before - about 1996 is not required.} -\end{seealso} - - -\section{\module{DEVICE} --- - Constants used with the \module{gl} module} - -\declaremodule{standard}{DEVICE} - \platform{IRIX} -\modulesynopsis{Constants used with the \module{gl} module.} - -This modules defines the constants used by the Silicon Graphics -\emph{Graphics Library} that C programmers find in the header file -\code{}. -Read the module source file for details. - - -\section{\module{GL} --- - Constants used with the \module{gl} module} - -\declaremodule[gl-constants]{standard}{GL} - \platform{IRIX} -\modulesynopsis{Constants used with the \module{gl} module.} - -This module contains constants used by the Silicon Graphics -\emph{Graphics Library} from the C header file \code{}. -Read the module source file for details. 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{}): - -\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 Franois 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 5b4bb7b..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 \keyword{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} -Evaluate an \keyword{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{

} -... \code{

}, the class should define the \method{start_\var{tag}()} -method; if a tag requires no closing tag, like \code{

}, 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{

} 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{} tag with the same
-names.  The default implementation maintains a list of hyperlinks
-(defined by the \code{HREF} attribute for \code{} 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{}, 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{}).  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{} 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{} 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{},
-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/libimageop.tex b/Doc/lib/libimageop.tex
deleted file mode 100644
index 0f732bf..0000000
--- a/Doc/lib/libimageop.tex
+++ /dev/null
@@ -1,100 +0,0 @@
-\section{\module{imageop} ---
-         Manipulate raw image data}
-
-\declaremodule{builtin}{imageop}
-\modulesynopsis{Manipulate raw image data.}
-
-
-The \module{imageop} module contains some useful operations on images.
-It operates on images consisting of 8 or 32 bit pixels stored in
-Python strings.  This is the same format as used by
-\function{gl.lrectwrite()} and the \refmodule{imgfile} module.
-
-The module defines the following variables and functions:
-
-\begin{excdesc}{error}
-This exception is raised on all errors, such as unknown number of bits
-per pixel, etc.
-\end{excdesc}
-
-
-\begin{funcdesc}{crop}{image, psize, width, height, x0, y0, x1, y1}
-Return the selected part of \var{image}, which should be
-\var{width} by \var{height} in size and consist of pixels of
-\var{psize} bytes. \var{x0}, \var{y0}, \var{x1} and \var{y1} are like
-the \function{gl.lrectread()} parameters, i.e.\ the boundary is
-included in the new image.  The new boundaries need not be inside the
-picture.  Pixels that fall outside the old image will have their value
-set to zero.  If \var{x0} is bigger than \var{x1} the new image is
-mirrored.  The same holds for the y coordinates.
-\end{funcdesc}
-
-\begin{funcdesc}{scale}{image, psize, width, height, newwidth, newheight}
-Return \var{image} scaled to size \var{newwidth} by \var{newheight}.
-No interpolation is done, scaling is done by simple-minded pixel
-duplication or removal.  Therefore, computer-generated images or
-dithered images will not look nice after scaling.
-\end{funcdesc}
-
-\begin{funcdesc}{tovideo}{image, psize, width, height}
-Run a vertical low-pass filter over an image.  It does so by computing
-each destination pixel as the average of two vertically-aligned source
-pixels.  The main use of this routine is to forestall excessive
-flicker if the image is displayed on a video device that uses
-interlacing, hence the name.
-\end{funcdesc}
-
-\begin{funcdesc}{grey2mono}{image, width, height, threshold}
-Convert a 8-bit deep greyscale image to a 1-bit deep image by
-thresholding all the pixels.  The resulting image is tightly packed and
-is probably only useful as an argument to \function{mono2grey()}.
-\end{funcdesc}
-
-\begin{funcdesc}{dither2mono}{image, width, height}
-Convert an 8-bit greyscale image to a 1-bit monochrome image using a
-(simple-minded) dithering algorithm.
-\end{funcdesc}
-
-\begin{funcdesc}{mono2grey}{image, width, height, p0, p1}
-Convert a 1-bit monochrome image to an 8 bit greyscale or color image.
-All pixels that are zero-valued on input get value \var{p0} on output
-and all one-value input pixels get value \var{p1} on output.  To
-convert a monochrome black-and-white image to greyscale pass the
-values \code{0} and \code{255} respectively.
-\end{funcdesc}
-
-\begin{funcdesc}{grey2grey4}{image, width, height}
-Convert an 8-bit greyscale image to a 4-bit greyscale image without
-dithering.
-\end{funcdesc}
-
-\begin{funcdesc}{grey2grey2}{image, width, height}
-Convert an 8-bit greyscale image to a 2-bit greyscale image without
-dithering.
-\end{funcdesc}
-
-\begin{funcdesc}{dither2grey2}{image, width, height}
-Convert an 8-bit greyscale image to a 2-bit greyscale image with
-dithering.  As for \function{dither2mono()}, the dithering algorithm
-is currently very simple.
-\end{funcdesc}
-
-\begin{funcdesc}{grey42grey}{image, width, height}
-Convert a 4-bit greyscale image to an 8-bit greyscale image.
-\end{funcdesc}
-
-\begin{funcdesc}{grey22grey}{image, width, height}
-Convert a 2-bit greyscale image to an 8-bit greyscale image.
-\end{funcdesc}
-
-\begin{datadesc}{backward_compatible}
-If set to 0, the functions in this module use a non-backward
-compatible way of representing multi-byte pixels on little-endian
-systems.  The SGI for which this module was originally written is a
-big-endian system, so setting this variable will have no effect.
-However, the code wasn't originally intended to run on anything else,
-so it made assumptions about byte order which are not universal.
-Setting this variable to 0 will cause the byte order to be reversed on
-little-endian systems, so that it then is the same as on big-endian
-systems.
-\end{datadesc}
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
-% ;
-% converted by Fred L. Drake, Jr. .
-% Revised by ESR, January 2000.
-% Changes for IMAP4_SSL by Tino Lange , March 2002 
-% Changes for IMAP4_stream by Piers Lauder
-% , 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/libimgfile.tex b/Doc/lib/libimgfile.tex
deleted file mode 100644
index 1aad965..0000000
--- a/Doc/lib/libimgfile.tex
+++ /dev/null
@@ -1,66 +0,0 @@
-\section{\module{imgfile} ---
-         Support for SGI imglib files}
-
-\declaremodule{builtin}{imgfile}
-  \platform{IRIX}
-\modulesynopsis{Support for SGI imglib files.}
-
-
-The \module{imgfile} module allows Python programs to access SGI imglib image
-files (also known as \file{.rgb} files).  The module is far from
-complete, but is provided anyway since the functionality that there is
-enough in some cases.  Currently, colormap files are not supported.
-
-The module defines the following variables and functions:
-
-\begin{excdesc}{error}
-This exception is raised on all errors, such as unsupported file type, etc.
-\end{excdesc}
-
-\begin{funcdesc}{getsizes}{file}
-This function returns a tuple \code{(\var{x}, \var{y}, \var{z})} where
-\var{x} and \var{y} are the size of the image in pixels and
-\var{z} is the number of
-bytes per pixel. Only 3 byte RGB pixels and 1 byte greyscale pixels
-are currently supported.
-\end{funcdesc}
-
-\begin{funcdesc}{read}{file}
-This function reads and decodes the image on the specified file, and
-returns it as a Python string. The string has either 1 byte greyscale
-pixels or 4 byte RGBA pixels. The bottom left pixel is the first in
-the string. This format is suitable to pass to \function{gl.lrectwrite()},
-for instance.
-\end{funcdesc}
-
-\begin{funcdesc}{readscaled}{file, x, y, filter\optional{, blur}}
-This function is identical to read but it returns an image that is
-scaled to the given \var{x} and \var{y} sizes. If the \var{filter} and
-\var{blur} parameters are omitted scaling is done by
-simply dropping or duplicating pixels, so the result will be less than
-perfect, especially for computer-generated images.
-
-Alternatively, you can specify a filter to use to smooth the image
-after scaling. The filter forms supported are \code{'impulse'},
-\code{'box'}, \code{'triangle'}, \code{'quadratic'} and
-\code{'gaussian'}. If a filter is specified \var{blur} is an optional
-parameter specifying the blurriness of the filter. It defaults to \code{1.0}.
-
-\function{readscaled()} makes no attempt to keep the aspect ratio
-correct, so that is the users' responsibility.
-\end{funcdesc}
-
-\begin{funcdesc}{ttob}{flag}
-This function sets a global flag which defines whether the scan lines
-of the image are read or written from bottom to top (flag is zero,
-compatible with SGI GL) or from top to bottom(flag is one,
-compatible with X).  The default is zero.
-\end{funcdesc}
-
-\begin{funcdesc}{write}{file, data, x, y, z}
-This function writes the RGB or greyscale data in \var{data} to image
-file \var{file}. \var{x} and \var{y} give the size of the image,
-\var{z} is 1 for 1 byte greyscale images or 3 for RGB images (which are
-stored as 4 byte values of which only the lower three bytes are used).
-These are the formats returned by \function{gl.lrectread()}.
-\end{funcdesc}
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 5379309..0000000
--- a/Doc/lib/libimp.tex
+++ /dev/null
@@ -1,292 +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 is equivalent to a
-\function{reload()}\bifuncindex{reload}!  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()}\bifuncindex{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 85651f0..0000000
--- a/Doc/lib/libinspect.tex
+++ /dev/null
@@ -1,393 +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{}{func_code}{code object containing compiled function bytecode}{}
-  \lineiv{}{func_defaults}{tuple of any default values for arguments}{}
-  \lineiv{}{func_doc}{(same as __doc__)}{}
-  \lineiv{}{func_globals}{global namespace in which this function was defined}{}
-  \lineiv{}{func_name}{(same as __name__)}{}
-  \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 362c589..0000000
--- a/Doc/lib/libitertools.tex
+++ /dev/null
@@ -1,578 +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 = xrange(0)
-        def __iter__(self):
-            return self
-        def next(self):
-            while self.currkey == self.tgtkey:
-                self.currvalue = self.it.next() # Exit on StopIteration
-                self.currkey = self.keyfunc(self.currvalue)
-            self.tgtkey = self.currkey
-            return (self.currkey, self._grouper(self.tgtkey))
-        def _grouper(self, tgtkey):
-            while self.currkey == tgtkey:
-                yield self.currvalue
-                self.currvalue = self.it.next() # Exit on StopIteration
-                self.currkey = self.keyfunc(self.currvalue)
-  \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 = [i.next() 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(xrange(s.start or 0, s.stop or sys.maxint, s.step or 1))
-         nexti = it.next()
-         for i, element in enumerate(iterable):
-             if i == nexti:
-                 yield element
-                 nexti = it.next()          
-  \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 = [it.next() 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{it.next()}).  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 xrange(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(*iterable.next())
-  \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, xrange(1,5), repeat(3)):
-...    print cube
-...
-1
-8
-27
-64
-
->>> reportlines = ['EuroPython', 'Roster', '', 'alex', '', 'laura',
-                  '', 'martin', '', 'walter', '', 'mark']
->>> for name in islice(reportlines, 3, None, 2):
-...    print name.title()
-...
-Alex
-Laura
-Martin
-Walter
-Mark
-
-# Show a dictionary sorted and grouped by value
->>> from operator import itemgetter
->>> d = dict(a=1, b=2, c=1, d=2, e=1, f=2, g=3)
->>> di = sorted(d.iteritems(), key=itemgetter(1))
->>> for k, g in groupby(di, key=itemgetter(1)):
-...     print k, map(itemgetter(0), g)
-...
-1 ['a', 'c', 'e']
-2 ['b', 'd', 'f']
-3 ['g']
-
-# Find runs of consecutive numbers using groupby.  The key to the solution
-# is differencing with a range so that consecutive numbers all appear in
-# same group.
->>> data = [ 1,  4,5,6, 10, 15,16,17,18, 22, 25,26,27,28]
->>> for k, g in groupby(enumerate(data), lambda (i,x):i-x):
-...     print map(operator.itemgetter(1), g)
-... 
-[1]
-[4, 5, 6]
-[10]
-[15, 16, 17, 18]
-[22]
-[25, 26, 27, 28]
-
-\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)
-    try:
-        b.next()
-    except StopIteration:
-        pass
-    return izip(a, b)
-
-def grouper(n, iterable, padvalue=None):
-    "grouper(3, 'abcdefg', 'x') --> ('a','b','c'), ('d','e','f'), ('g','x','x')"
-    return izip(*[chain(iterable, repeat(padvalue, n-1))]*n)
-
-
-\end{verbatim}
diff --git a/Doc/lib/libjpeg.tex b/Doc/lib/libjpeg.tex
deleted file mode 100644
index a10e06c..0000000
--- a/Doc/lib/libjpeg.tex
+++ /dev/null
@@ -1,80 +0,0 @@
-\section{\module{jpeg} ---
-         Read and write JPEG files}
-
-\declaremodule{builtin}{jpeg}
-  \platform{IRIX}
-\modulesynopsis{Read and write image files in compressed JPEG format.}
-
-
-The module \module{jpeg} provides access to the jpeg compressor and
-decompressor written by the Independent JPEG Group
-\index{Independent JPEG Group}(IJG). JPEG is a standard for
-compressing pictures; it is defined in ISO 10918.  For details on JPEG
-or the Independent JPEG Group software refer to the JPEG standard or
-the documentation provided with the software.
-
-A portable interface to JPEG image files is available with the Python
-Imaging Library (PIL) by Fredrik Lundh.  Information on PIL is
-available at \url{http://www.pythonware.com/products/pil/}.
-\index{Python Imaging Library}
-\index{PIL (the Python Imaging Library)}
-\index{Lundh, Fredrik}
-
-The \module{jpeg} module defines an exception and some functions.
-
-\begin{excdesc}{error}
-Exception raised by \function{compress()} and \function{decompress()}
-in case of errors.
-\end{excdesc}
-
-\begin{funcdesc}{compress}{data, w, h, b}
-Treat data as a pixmap of width \var{w} and height \var{h}, with
-\var{b} bytes per pixel.  The data is in SGI GL order, so the first
-pixel is in the lower-left corner. This means that \function{gl.lrectread()}
-return data can immediately be passed to \function{compress()}.
-Currently only 1 byte and 4 byte pixels are allowed, the former being
-treated as greyscale and the latter as RGB color.
-\function{compress()} returns a string that contains the compressed
-picture, in JFIF\index{JFIF} format.
-\end{funcdesc}
-
-\begin{funcdesc}{decompress}{data}
-Data is a string containing a picture in JFIF\index{JFIF} format. It
-returns a tuple \code{(\var{data}, \var{width}, \var{height},
-\var{bytesperpixel})}.  Again, the data is suitable to pass to
-\function{gl.lrectwrite()}.
-\end{funcdesc}
-
-\begin{funcdesc}{setoption}{name, value}
-Set various options.  Subsequent \function{compress()} and
-\function{decompress()} calls will use these options.  The following
-options are available:
-
-\begin{tableii}{l|p{3in}}{code}{Option}{Effect}
-  \lineii{'forcegray'}{%
-    Force output to be grayscale, even if input is RGB.}
-  \lineii{'quality'}{%
-    Set the quality of the compressed image to a value between
-    \code{0} and \code{100} (default is \code{75}).  This only affects
-    compression.}
-  \lineii{'optimize'}{%
-    Perform Huffman table optimization.  Takes longer, but results in
-    smaller compressed image.  This only affects compression.}
-  \lineii{'smooth'}{%
-    Perform inter-block smoothing on uncompressed image.  Only useful
-    for low-quality images.  This only affects decompression.}
-\end{tableii}
-\end{funcdesc}
-
-
-\begin{seealso}
-  \seetitle{JPEG Still Image Data Compression Standard}{The 
-            canonical reference for the JPEG image format, by
-            Pennebaker and Mitchell.}
-
-  \seetitle[http://www.w3.org/Graphics/JPEG/itu-t81.pdf]{Information
-            Technology - Digital Compression and Coding of
-            Continuous-tone Still Images - Requirements and
-            Guidelines}{The ISO standard for JPEG is also published as
-            ITU T.81.  This is available online in PDF form.}
-\end{seealso}
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/libmd5.tex b/Doc/lib/libmd5.tex
deleted file mode 100644
index 38105ae..0000000
--- a/Doc/lib/libmd5.tex
+++ /dev/null
@@ -1,92 +0,0 @@
-\section{\module{md5} ---
-         MD5 message digest algorithm}
-
-\declaremodule{builtin}{md5}
-\modulesynopsis{RSA's MD5 message digest algorithm.}
-
-\deprecated{2.5}{Use the \refmodule{hashlib} module instead.}
-
-This module implements the interface to RSA's MD5 message digest
-\index{message digest, MD5}
-algorithm (see also Internet \rfc{1321}).  Its use is quite
-straightforward:\ use \function{new()} to create an md5 object.
-You can now feed this object with arbitrary strings using the
-\method{update()} method, and at any point you can ask it for the
-\dfn{digest} (a strong kind of 128-bit checksum,
-a.k.a. ``fingerprint'') of the concatenation of the strings fed to it
-so far using the \method{digest()} method.
-\index{checksum!MD5}
-
-For example, to obtain the digest of the string \code{'Nobody inspects
-the spammish repetition'}:
-
-\begin{verbatim}
->>> import md5
->>> m = md5.new()
->>> 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}
->>> md5.new("Nobody inspects the spammish repetition").digest()
-'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
-\end{verbatim}
-
-The following values are provided as constants in the module and as
-attributes of the md5 objects returned by \function{new()}:
-
-\begin{datadesc}{digest_size}
-  The size of the resulting digest in bytes.  This is always
-  \code{16}.
-\end{datadesc}
-
-The md5 module provides the following functions:
-
-\begin{funcdesc}{new}{\optional{arg}}
-Return a new md5 object.  If \var{arg} is present, the method call
-\code{update(\var{arg})} is made.
-\end{funcdesc}
-
-\begin{funcdesc}{md5}{\optional{arg}}
-For backward compatibility reasons, this is an alternative name for the
-\function{new()} function.
-\end{funcdesc}
-
-An md5 object has the following methods:
-
-\begin{methoddesc}[md5]{update}{arg}
-Update the md5 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}[md5]{digest}{}
-Return the digest of the strings passed to the \method{update()}
-method so far.  This is a 16-byte string which may contain
-non-\ASCII{} characters, including null bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[md5]{hexdigest}{}
-Like \method{digest()} except the digest is returned as a string of
-length 32, containing only hexadecimal digits.  This may 
-be used to exchange the value safely in email or other non-binary
-environments.
-\end{methoddesc}
-
-\begin{methoddesc}[md5]{copy}{}
-Return a copy (``clone'') of the md5 object.  This can be used to
-efficiently compute the digests of strings that share a common initial
-substring.
-\end{methoddesc}
-
-
-\begin{seealso}
-  \seemodule{sha}{Similar module implementing the Secure Hash
-                  Algorithm (SHA).  The SHA algorithm is considered a
-                  more secure hash.}
-\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
-% .
-
-\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/libmimewriter.tex b/Doc/lib/libmimewriter.tex
deleted file mode 100644
index 74bd9bb..0000000
--- a/Doc/lib/libmimewriter.tex
+++ /dev/null
@@ -1,80 +0,0 @@
-\section{\module{MimeWriter} ---
-         Generic MIME file writer}
-
-\declaremodule{standard}{MimeWriter}
-
-\modulesynopsis{Generic MIME file writer.}
-\sectionauthor{Christopher G. Petrilli}{petrilli@amber.org}
-
-\deprecated{2.3}{The \refmodule{email} package should be used in
-                 preference to the \module{MimeWriter} module.  This
-                 module is present only to maintain backward
-                 compatibility.}
-
-This module defines the class \class{MimeWriter}.  The
-\class{MimeWriter} class implements a basic formatter for creating
-MIME multi-part files.  It doesn't seek around the output file nor
-does it use large amounts of buffer space. You must write the parts
-out in the order that they should occur in the final
-file. \class{MimeWriter} does buffer the headers you add, allowing you 
-to rearrange their order.
-
-\begin{classdesc}{MimeWriter}{fp}
-Return a new instance of the \class{MimeWriter} class.  The only
-argument passed, \var{fp}, is a file object to be used for
-writing. Note that a \class{StringIO} object could also be used.
-\end{classdesc}
-
-
-\subsection{MimeWriter Objects \label{MimeWriter-objects}}
-
-
-\class{MimeWriter} instances have the following methods:
-
-\begin{methoddesc}[MimeWriter]{addheader}{key, value\optional{, prefix}}
-Add a header line to the MIME message. The \var{key} is the name of
-the header, where the \var{value} obviously provides the value of the
-header. The optional argument \var{prefix} determines where the header 
-is inserted; \samp{0} means append at the end, \samp{1} is insert at
-the start. The default is to append.
-\end{methoddesc}
-
-\begin{methoddesc}[MimeWriter]{flushheaders}{}
-Causes all headers accumulated so far to be written out (and
-forgotten). This is useful if you don't need a body part at all,
-e.g.\ for a subpart of type \mimetype{message/rfc822} that's (mis)used
-to store some header-like information.
-\end{methoddesc}
-
-\begin{methoddesc}[MimeWriter]{startbody}{ctype\optional{, plist\optional{, prefix}}}
-Returns a file-like object which can be used to write to the
-body of the message.  The content-type is set to the provided
-\var{ctype}, and the optional parameter \var{plist} provides
-additional parameters for the content-type declaration. \var{prefix}
-functions as in \method{addheader()} except that the default is to
-insert at the start.
-\end{methoddesc}
-
-\begin{methoddesc}[MimeWriter]{startmultipartbody}{subtype\optional{,
-                               boundary\optional{, plist\optional{, prefix}}}}
-Returns a file-like object which can be used to write to the
-body of the message.  Additionally, this method initializes the
-multi-part code, where \var{subtype} provides the multipart subtype,
-\var{boundary} may provide a user-defined boundary specification, and
-\var{plist} provides optional parameters for the subtype.
-\var{prefix} functions as in \method{startbody()}.  Subparts should be
-created using \method{nextpart()}.
-\end{methoddesc}
-
-\begin{methoddesc}[MimeWriter]{nextpart}{}
-Returns a new instance of \class{MimeWriter} which represents an
-individual part in a multipart message.  This may be used to write the 
-part as well as used for creating recursively complex multipart
-messages. The message must first be initialized with
-\method{startmultipartbody()} before using \method{nextpart()}.
-\end{methoddesc}
-
-\begin{methoddesc}[MimeWriter]{lastpart}{}
-This is used to designate the last part of a multipart message, and
-should \emph{always} be used when writing multipart messages.
-\end{methoddesc}
diff --git a/Doc/lib/libmimify.tex b/Doc/lib/libmimify.tex
deleted file mode 100644
index d99567a..0000000
--- a/Doc/lib/libmimify.tex
+++ /dev/null
@@ -1,94 +0,0 @@
-\section{\module{mimify} ---
-         MIME processing of mail messages}
-
-\declaremodule{standard}{mimify}
-\modulesynopsis{Mimification and unmimification of mail messages.}
-
-\deprecated{2.3}{The \refmodule{email} package should be used in
-                 preference to the \module{mimify} module.  This
-                 module is present only to maintain backward
-                 compatibility.}
-
-The \module{mimify} module defines two functions to convert mail messages to
-and from MIME format.  The mail message can be either a simple message
-or a so-called multipart message.  Each part is treated separately.
-Mimifying (a part of) a message entails encoding the message as
-quoted-printable if it contains any characters that cannot be
-represented using 7-bit \ASCII.  Unmimifying (a part of) a message
-entails undoing the quoted-printable encoding.  Mimify and unmimify
-are especially useful when a message has to be edited before being
-sent.  Typical use would be:
-
-\begin{verbatim}
-unmimify message
-edit message
-mimify message
-send message
-\end{verbatim}
-
-The modules defines the following user-callable functions and
-user-settable variables:
-
-\begin{funcdesc}{mimify}{infile, outfile}
-Copy the message in \var{infile} to \var{outfile}, converting parts to
-quoted-printable and adding MIME mail headers when necessary.
-\var{infile} and \var{outfile} can be file objects (actually, any
-object that has a \method{readline()} method (for \var{infile}) or a
-\method{write()} method (for \var{outfile})) or strings naming the files.
-If \var{infile} and \var{outfile} are both strings, they may have the
-same value.
-\end{funcdesc}
-
-\begin{funcdesc}{unmimify}{infile, outfile\optional{, decode_base64}}
-Copy the message in \var{infile} to \var{outfile}, decoding all
-quoted-printable parts.  \var{infile} and \var{outfile} can be file
-objects (actually, any object that has a \method{readline()} method (for
-\var{infile}) or a \method{write()} method (for \var{outfile})) or strings
-naming the files.  If \var{infile} and \var{outfile} are both strings,
-they may have the same value.
-If the \var{decode_base64} argument is provided and tests true, any
-parts that are coded in the base64 encoding are decoded as well.
-\end{funcdesc}
-
-\begin{funcdesc}{mime_decode_header}{line}
-Return a decoded version of the encoded header line in \var{line}.
-This only supports the ISO 8859-1 charset (Latin-1).
-\end{funcdesc}
-
-\begin{funcdesc}{mime_encode_header}{line}
-Return a MIME-encoded version of the header line in \var{line}.
-\end{funcdesc}
-
-\begin{datadesc}{MAXLEN}
-By default, a part will be encoded as quoted-printable when it
-contains any non-\ASCII{} characters (characters with the 8th bit
-set), or if there are any lines longer than \constant{MAXLEN} characters
-(default value 200).  
-\end{datadesc}
-
-\begin{datadesc}{CHARSET}
-When not specified in the mail headers, a character set must be filled
-in.  The string used is stored in \constant{CHARSET}, and the default
-value is ISO-8859-1 (also known as Latin1 (latin-one)).
-\end{datadesc}
-
-This module can also be used from the command line.  Usage is as
-follows:
-\begin{verbatim}
-mimify.py -e [-l length] [infile [outfile]]
-mimify.py -d [-b] [infile [outfile]]
-\end{verbatim}
-to encode (mimify) and decode (unmimify) respectively.  \var{infile}
-defaults to standard input, \var{outfile} defaults to standard output.
-The same file can be specified for input and output.
-
-If the \strong{-l} option is given when encoding, if there are any lines
-longer than the specified \var{length}, the containing part will be
-encoded.
-
-If the \strong{-b} option is given when decoding, any base64 parts will
-be decoded as well.
-
-\begin{seealso}
-  \seemodule{quopri}{Encode and decode MIME quoted-printable files.}
-\end{seealso}
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 d0394d1..0000000
--- a/Doc/lib/libnew.tex
+++ /dev/null
@@ -1,63 +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}{instance}{class\optional{, dict}}
-This function creates an instance of \var{class} with dictionary
-\var{dict} without calling the \method{__init__()} constructor.  If
-\var{dict} is omitted or \code{None}, a new, empty dictionary is
-created for the new instance.  Note that there are no guarantees that
-the object will be in a consistent state.
-\end{funcdesc}
-
-\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 5ba3209..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{__nonzero__()} 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}
- --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}
- -f outfile --quiet
- --quiet --file outfile
- -q -foutfile
- -qfoutfile
-\end{verbatim}
-
-Additionally, users can run one of
-\begin{verbatim}
- -h
- --help
-\end{verbatim}
-
-and \code{optparse} will print out a brief summary of your script's
-options:
-\begin{verbatim}
-usage:  [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:  [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 2454e57..0000000
--- a/Doc/lib/libos.tex
+++ /dev/null
@@ -1,2045 +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  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}
-
-There are a number of different \function{popen*()} functions that
-provide slightly different ways to create subprocesses.
-\deprecated{2.6}{All of the \function{popen*()} functions are obsolete.
-                 Use the \module{subprocess} module.}
-
-For each of the \function{popen*()} variants, if \var{bufsize} is
-specified, it specifies the buffer size for the I/O pipes.
-\var{mode}, if provided, should be the string \code{'b'} or
-\code{'t'}; on Windows this is needed to determine whether the file
-objects should be opened in binary or text mode.  The default value
-for \var{mode} is \code{'t'}.
-
-Also, for each of these variants, on \UNIX, \var{cmd} may be a sequence, in
-which case arguments will be passed directly to the program without shell
-intervention (as with \function{os.spawnv()}). If \var{cmd} is a string it will
-be passed to the shell (as with \function{os.system()}).
-
-These methods do not make it possible to retrieve the exit status from
-the child processes.  The only way to control the input and output
-streams and also retrieve the return codes is to use the
-\refmodule{subprocess} module; these are only available on \UNIX.
-
-For a discussion of possible deadlock conditions related to the use
-of these functions, see ``\ulink{Flow Control
-Issues}{popen2-flow-control.html}''
-(section~\ref{popen2-flow-control}).
-
-\begin{funcdesc}{popen2}{cmd\optional{, mode\optional{, bufsize}}}
-Executes \var{cmd} as a sub-process.  Returns the file objects
-\code{(\var{child_stdin}, \var{child_stdout})}.
-\deprecated{2.6}{All of the \function{popen*()} functions are obsolete.
-                 Use the \module{subprocess} module.}
-Availability: Macintosh, \UNIX, Windows.
-\versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{popen3}{cmd\optional{, mode\optional{, bufsize}}}
-Executes \var{cmd} as a sub-process.  Returns the file objects
-\code{(\var{child_stdin}, \var{child_stdout}, \var{child_stderr})}.
-\deprecated{2.6}{All of the \function{popen*()} functions are obsolete.
-                 Use the \module{subprocess} module.}
-Availability: Macintosh, \UNIX, Windows.
-\versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{popen4}{cmd\optional{, mode\optional{, bufsize}}}
-Executes \var{cmd} as a sub-process.  Returns the file objects
-\code{(\var{child_stdin}, \var{child_stdout_and_stderr})}.
-\deprecated{2.6}{All of the \function{popen*()} functions are obsolete.
-                 Use the \module{subprocess} module.}
-Availability: Macintosh, \UNIX, Windows.
-\versionadded{2.0}
-\end{funcdesc}
-
-(Note that \code{\var{child_stdin}, \var{child_stdout}, and
-\var{child_stderr}} are named from the point of view of the child
-process, so \var{child_stdin} is the child's standard input.)
-
-This functionality is also available in the \refmodule{popen2} module
-using functions of the same names, but the return values of those
-functions have a different order.
-
-
-\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{}) determines which segments are locked.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdescni}{popen}{\unspecified}
-\funclineni{popen2}{\unspecified}
-\funclineni{popen3}{\unspecified}
-\funclineni{popen4}{\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 :
-% >  * 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{} 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 15b46ae..0000000
--- a/Doc/lib/libparser.tex
+++ /dev/null
@@ -1,711 +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{ = ''}}}
-The Python byte compiler can be invoked on an AST object to produce
-code objects which can be used as part of an \keyword{exec} statement or
-a call to the built-in \function{eval()}\bifuncindex{eval} function.
-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 1edae64..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()')
-> (0)?()
-(Pdb) continue
-> (1)?()
-(Pdb) continue
-NameError: 'spam'
-> (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 "", 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 \keyword{exec} statement or the
-\function{eval()} built-in function.)
-\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 .
-% Rewritten by Barry Warsaw 
-
-\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/libpopen2.tex b/Doc/lib/libpopen2.tex
deleted file mode 100644
index 5d40e1a..0000000
--- a/Doc/lib/libpopen2.tex
+++ /dev/null
@@ -1,190 +0,0 @@
-\section{\module{popen2} ---
-         Subprocesses with accessible I/O streams}
-
-\declaremodule{standard}{popen2}
-\modulesynopsis{Subprocesses with accessible standard I/O streams.}
-\sectionauthor{Drew Csillag}{drew_csillag@geocities.com}
-
-\deprecated{2.6}{This module is obsolete.  Use the \module{subprocess} module.}
-
-This module allows you to spawn processes and connect to their
-input/output/error pipes and obtain their return codes under
-\UNIX{} and Windows.
-
-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{popen2}
-module.
-
-The primary interface offered by this module is a trio of factory
-functions.  For each of these, if \var{bufsize} is specified, 
-it specifies the buffer size for the I/O pipes.  \var{mode}, if
-provided, should be the string \code{'b'} or \code{'t'}; on Windows
-this is needed to determine whether the file objects should be opened
-in binary or text mode.  The default value for \var{mode} is
-\code{'t'}.
-
-On \UNIX, \var{cmd} may be a sequence, in which case arguments will be passed
-directly to the program without shell intervention (as with
-\function{os.spawnv()}). If \var{cmd} is a string it will be passed to the
-shell (as with \function{os.system()}).
-
-The only way to retrieve the return codes for the child processes is
-by using the \method{poll()} or \method{wait()} methods on the
-\class{Popen3} and \class{Popen4} classes; these are only available on
-\UNIX.  This information is not available when using the
-\function{popen2()}, \function{popen3()}, and \function{popen4()}
-functions, or the equivalent functions in the \refmodule{os} module.
-(Note that the tuples returned by the \refmodule{os} module's functions
-are in a different order from the ones returned by the \module{popen2}
-module.)
-
-\begin{funcdesc}{popen2}{cmd\optional{, bufsize\optional{, mode}}}
-Executes \var{cmd} as a sub-process.  Returns the file objects
-\code{(\var{child_stdout}, \var{child_stdin})}.
-\end{funcdesc}
-
-\begin{funcdesc}{popen3}{cmd\optional{, bufsize\optional{, mode}}}
-Executes \var{cmd} as a sub-process.  Returns the file objects
-\code{(\var{child_stdout}, \var{child_stdin}, \var{child_stderr})}.
-\end{funcdesc}
-
-\begin{funcdesc}{popen4}{cmd\optional{, bufsize\optional{, mode}}}
-Executes \var{cmd} as a sub-process.  Returns the file objects
-\code{(\var{child_stdout_and_stderr}, \var{child_stdin})}.
-\versionadded{2.0}
-\end{funcdesc}
-
-
-On \UNIX, a class defining the objects returned by the factory
-functions is also available.  These are not used for the Windows
-implementation, and are not available on that platform.
-
-\begin{classdesc}{Popen3}{cmd\optional{, capturestderr\optional{, bufsize}}}
-This class represents a child process.  Normally, \class{Popen3}
-instances are created using the \function{popen2()} and
-\function{popen3()} factory functions described above.
-
-If not using one of the helper functions to create \class{Popen3}
-objects, the parameter \var{cmd} is the shell command to execute in a
-sub-process.  The \var{capturestderr} flag, if true, specifies that
-the object should capture standard error output of the child process.
-The default is false.  If the \var{bufsize} parameter is specified, it
-specifies the size of the I/O buffers to/from the child process.
-\end{classdesc}
-
-\begin{classdesc}{Popen4}{cmd\optional{, bufsize}}
-Similar to \class{Popen3}, but always captures standard error into the
-same file object as standard output.  These are typically created
-using \function{popen4()}.
-\versionadded{2.0}
-\end{classdesc}
-
-\subsection{Popen3 and Popen4 Objects \label{popen3-objects}}
-
-Instances of the \class{Popen3} and \class{Popen4} classes have the
-following methods:
-
-\begin{methoddesc}[Popen3]{poll}{}
-Returns \code{-1} if child process hasn't completed yet, or its return 
-code otherwise.
-\end{methoddesc}
-
-\begin{methoddesc}[Popen3]{wait}{}
-Waits for and returns the status code of the child process.  The
-status code encodes both the return code of the process and
-information about whether it exited using the \cfunction{exit()}
-system call or died due to a signal.  Functions to help interpret the
-status code are defined in the \refmodule{os} module; see section
-\ref{os-process} for the \function{W\var{*}()} family of functions.
-\end{methoddesc}
-
-
-The following attributes are also available: 
-
-\begin{memberdesc}[Popen3]{fromchild}
-A file object that provides output from the child process.  For
-\class{Popen4} instances, this will provide both the standard output
-and standard error streams.
-\end{memberdesc}
-
-\begin{memberdesc}[Popen3]{tochild}
-A file object that provides input to the child process.
-\end{memberdesc}
-
-\begin{memberdesc}[Popen3]{childerr}
-A file object that provides error output from the child process, if
-\var{capturestderr} was true for the constructor, otherwise
-\code{None}.  This will always be \code{None} for \class{Popen4}
-instances.
-\end{memberdesc}
-
-\begin{memberdesc}[Popen3]{pid}
-The process ID of the child process.
-\end{memberdesc}
-
-
-\subsection{Flow Control Issues \label{popen2-flow-control}}
-
-Any time you are working with any form of inter-process communication,
-control flow needs to be carefully thought out.  This remains the case
-with the file objects provided by this module (or the \refmodule{os}
-module equivalents).
-
-% Example explanation and suggested work-arounds substantially stolen
-% from Martin von Lwis:
-% http://mail.python.org/pipermail/python-dev/2000-September/009460.html
-
-When reading output from a child process that writes a lot of data to
-standard error while the parent is reading from the child's standard
-output, a deadlock can occur.  A similar situation can occur with other
-combinations of reads and writes.  The essential factors are that more
-than \constant{_PC_PIPE_BUF} bytes are being written by one process in
-a blocking fashion, while the other process is reading from the other
-process, also in a blocking fashion.
-
-There are several ways to deal with this situation.
-
-The simplest application change, in many cases, will be to follow this
-model in the parent process:
-
-\begin{verbatim}
-import popen2
-
-r, w, e = popen2.popen3('python slave.py')
-e.readlines()
-r.readlines()
-r.close()
-e.close()
-w.close()
-\end{verbatim}
-
-with code like this in the child:
-
-\begin{verbatim}
-import os
-import sys
-
-# note that each of these print statements
-# writes a single long string
-
-print >>sys.stderr, 400 * 'this is a test\n'
-os.close(sys.stderr.fileno())
-print >>sys.stdout, 400 * 'this is another test\n'
-\end{verbatim}
-
-In particular, note that \code{sys.stderr} must be closed after
-writing all data, or \method{readlines()} won't return.  Also note
-that \function{os.close()} must be used, as \code{sys.stderr.close()}
-won't close \code{stderr} (otherwise assigning to \code{sys.stderr}
-will silently close it, so no further errors can be printed).
-
-Applications which need to support a more general approach should
-integrate I/O over pipes with their \function{select()} loops, or use
-separate threads to read each of the individual files provided by
-whichever \function{popen*()} function or \class{Popen*} class was
-used.
-
-\begin{seealso}
-  \seemodule{subprocess}{Module for spawning and managing subprocesses.}
-\end{seealso}
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/libposixfile.tex b/Doc/lib/libposixfile.tex
deleted file mode 100644
index 5c86f3e..0000000
--- a/Doc/lib/libposixfile.tex
+++ /dev/null
@@ -1,174 +0,0 @@
-% Manual text and implementation by Jaap Vermeulen
-\section{\module{posixfile} ---
-         File-like objects with locking support}
-
-\declaremodule{builtin}{posixfile}
-  \platform{Unix}
-\modulesynopsis{A file-like object with support for locking.}
-\moduleauthor{Jaap Vermeulen}{}
-\sectionauthor{Jaap Vermeulen}{}
-
-
-\indexii{\POSIX}{file object}
-
-\deprecated{1.5}{The locking operation that this module provides is
-done better and more portably by the
-\function{\refmodule{fcntl}.lockf()} call.
-\withsubitem{(in module fcntl)}{\ttindex{lockf()}}}
-
-This module implements some additional functionality over the built-in
-file objects.  In particular, it implements file locking, control over
-the file flags, and an easy interface to duplicate the file object.
-The module defines a new file object, the posixfile object.  It
-has all the standard file object methods and adds the methods
-described below.  This module only works for certain flavors of
-\UNIX, since it uses \function{fcntl.fcntl()} for file locking.%
-\withsubitem{(in module fcntl)}{\ttindex{fcntl()}}
-
-To instantiate a posixfile object, use the \function{open()} function
-in the \module{posixfile} module.  The resulting object looks and
-feels roughly the same as a standard file object.
-
-The \module{posixfile} module defines the following constants:
-
-
-\begin{datadesc}{SEEK_SET}
-Offset is calculated from the start of the file.
-\end{datadesc}
-
-\begin{datadesc}{SEEK_CUR}
-Offset is calculated from the current position in the file.
-\end{datadesc}
-
-\begin{datadesc}{SEEK_END}
-Offset is calculated from the end of the file.
-\end{datadesc}
-
-The \module{posixfile} module defines the following functions:
-
-
-\begin{funcdesc}{open}{filename\optional{, mode\optional{, bufsize}}}
- Create a new posixfile object with the given filename and mode.  The
- \var{filename}, \var{mode} and \var{bufsize} arguments are
- interpreted the same way as by the built-in \function{open()}
- function.
-\end{funcdesc}
-
-\begin{funcdesc}{fileopen}{fileobject}
- Create a new posixfile object with the given standard file object.
- The resulting object has the same filename and mode as the original
- file object.
-\end{funcdesc}
-
-The posixfile object defines the following additional methods:
-
-\begin{methoddesc}[posixfile]{lock}{fmt, \optional{len\optional{, start\optional{, whence}}}}
- Lock the specified section of the file that the file object is
- referring to.  The format is explained
- below in a table.  The \var{len} argument specifies the length of the
- section that should be locked. The default is \code{0}. \var{start}
- specifies the starting offset of the section, where the default is
- \code{0}.  The \var{whence} argument specifies where the offset is
- relative to. It accepts one of the constants \constant{SEEK_SET},
- \constant{SEEK_CUR} or \constant{SEEK_END}.  The default is
- \constant{SEEK_SET}.  For more information about the arguments refer
- to the \manpage{fcntl}{2} manual page on your system.
-\end{methoddesc}
-
-\begin{methoddesc}[posixfile]{flags}{\optional{flags}}
- Set the specified flags for the file that the file object is referring
- to.  The new flags are ORed with the old flags, unless specified
- otherwise.  The format is explained below in a table.  Without
- the \var{flags} argument
- a string indicating the current flags is returned (this is
- the same as the \samp{?} modifier).  For more information about the
- flags refer to the \manpage{fcntl}{2} manual page on your system.
-\end{methoddesc}
-
-\begin{methoddesc}[posixfile]{dup}{}
- Duplicate the file object and the underlying file pointer and file
- descriptor.  The resulting object behaves as if it were newly
- opened.
-\end{methoddesc}
-
-\begin{methoddesc}[posixfile]{dup2}{fd}
- Duplicate the file object and the underlying file pointer and file
- descriptor.  The new object will have the given file descriptor.
- Otherwise the resulting object behaves as if it were newly opened.
-\end{methoddesc}
-
-\begin{methoddesc}[posixfile]{file}{}
- Return the standard file object that the posixfile object is based
- on.  This is sometimes necessary for functions that insist on a
- standard file object.
-\end{methoddesc}
-
-All methods raise \exception{IOError} when the request fails.
-
-Format characters for the \method{lock()} method have the following
-meaning:
-
-\begin{tableii}{c|l}{samp}{Format}{Meaning}
-  \lineii{u}{unlock the specified region}
-  \lineii{r}{request a read lock for the specified section}
-  \lineii{w}{request a write lock for the specified section}
-\end{tableii}
-
-In addition the following modifiers can be added to the format:
-
-\begin{tableiii}{c|l|c}{samp}{Modifier}{Meaning}{Notes}
-  \lineiii{|}{wait until the lock has been granted}{}
-  \lineiii{?}{return the first lock conflicting with the requested lock, or
-              \code{None} if there is no conflict.}{(1)} 
-\end{tableiii}
-
-\noindent
-Note:
-
-\begin{description}
-\item[(1)] The lock returned is in the format \code{(\var{mode}, \var{len},
-\var{start}, \var{whence}, \var{pid})} where \var{mode} is a character
-representing the type of lock ('r' or 'w').  This modifier prevents a
-request from being granted; it is for query purposes only.
-\end{description}
-
-Format characters for the \method{flags()} method have the following
-meanings:
-
-\begin{tableii}{c|l}{samp}{Format}{Meaning}
-  \lineii{a}{append only flag}
-  \lineii{c}{close on exec flag}
-  \lineii{n}{no delay flag (also called non-blocking flag)}
-  \lineii{s}{synchronization flag}
-\end{tableii}
-
-In addition the following modifiers can be added to the format:
-
-\begin{tableiii}{c|l|c}{samp}{Modifier}{Meaning}{Notes}
-  \lineiii{!}{turn the specified flags 'off', instead of the default 'on'}{(1)}
-  \lineiii{=}{replace the flags, instead of the default 'OR' operation}{(1)}
-  \lineiii{?}{return a string in which the characters represent the flags that
-  are set.}{(2)}
-\end{tableiii}
-
-\noindent
-Notes:
-
-\begin{description}
-\item[(1)] The \samp{!} and \samp{=} modifiers are mutually exclusive.
-
-\item[(2)] This string represents the flags after they may have been altered
-by the same call.
-\end{description}
-
-Examples:
-
-\begin{verbatim}
-import posixfile
-
-file = posixfile.open('/tmp/test', 'w')
-file.lock('w|')
-...
-file.lock('u')
-file.close()
-\end{verbatim}
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)
-[,
- '',
- '/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{}.  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)
-"[, '', '/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 179b396..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
-\keyword{exec} statement, and an optional file name.  In all cases this
-routine attempts to \keyword{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{}):
-
-\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.
-% 
-
-\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 a0ea8a1..0000000
--- a/Doc/lib/libpyexpat.tex
+++ /dev/null
@@ -1,777 +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}
-
-
-  
-  
-
-\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},
-\member{returns_unicode} 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]{returns_unicode} 
-If this attribute is set to a non-zero integer, the handler functions
-will be passed Unicode strings.  If \member{returns_unicode} is
-\constant{False}, 8-bit strings containing UTF-8 encoded data will be
-passed to the handlers.  This is \constant{True} by default when
-Python is built with Unicode support.
-\versionchanged[Can be changed at any time to affect the result
-  type]{1.6}
-\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 of the type dictated by the \member{returns_unicode}
-attribute, 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{}'.
-\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("""
-Text goes here
-More text
-""", 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 78c536b..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{xrange()}
-  object as an argument.  This is especially fast and space efficient for
-  sampling from a large population:  \code{sample(xrange(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{'
title
'}, it will match the entire string, and not just
-\code{'
'}.  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{'
'}.
-
-\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[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}).
-
-\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{(?)} is a poor email matching
-pattern, which will match with \code{''} as well as
-\code{'user@host.com'}, but not with \code{'>> 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} will use the substring matched by the group
-  named \samp{name}, as defined by the \regexp{(?P...)} syntax.
-  \samp{\e g} 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}) 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\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 "", 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="",
-                 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 ['', '', '']:
-            return obj.name
-        else:
-            return `obj`
-
-aRepr = MyRepr()
-print aRepr.repr(sys.stdin)          # prints ''
-\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/librestricted.tex b/Doc/lib/librestricted.tex
deleted file mode 100644
index 5d4b157..0000000
--- a/Doc/lib/librestricted.tex
+++ /dev/null
@@ -1,66 +0,0 @@
-\chapter{Restricted Execution \label{restricted}}
-
-\begin{notice}[warning]
-   In Python 2.3 these modules have been disabled due to various known
-   and not readily fixable security holes.  The modules are still
-   documented here to help in reading old code that uses the
-   \module{rexec} and \module{Bastion} modules.
-\end{notice}
-
-\emph{Restricted execution} is the basic framework in Python that allows
-for the segregation of trusted and untrusted code.  The framework is based on the
-notion that trusted Python code (a \emph{supervisor}) can create a
-``padded cell' (or environment) with limited permissions, and run the
-untrusted code within this cell.  The untrusted code cannot break out
-of its cell, and can only interact with sensitive system resources
-through interfaces defined and managed by the trusted code.  The term
-``restricted execution'' is favored over ``safe-Python''
-since true safety is hard to define, and is determined by the way the
-restricted environment is created.  Note that the restricted
-environments can be nested, with inner cells creating subcells of
-lesser, but never greater, privilege.
-
-An interesting aspect of Python's restricted execution model is that
-the interfaces presented to untrusted code usually have the same names
-as those presented to trusted code.  Therefore no special interfaces
-need to be learned to write code designed to run in a restricted
-environment.  And because the exact nature of the padded cell is
-determined by the supervisor, different restrictions can be imposed,
-depending on the application.  For example, it might be deemed
-``safe'' for untrusted code to read any file within a specified
-directory, but never to write a file.  In this case, the supervisor
-may redefine the built-in \function{open()} function so that it raises
-an exception whenever the \var{mode} parameter is \code{'w'}.  It
-might also perform a \cfunction{chroot()}-like operation on the
-\var{filename} parameter, such that root is always relative to some
-safe ``sandbox'' area of the filesystem.  In this case, the untrusted
-code would still see an built-in \function{open()} function in its
-environment, with the same calling interface.  The semantics would be
-identical too, with \exception{IOError}s being raised when the
-supervisor determined that an unallowable parameter is being used.
-
-The Python run-time determines whether a particular code block is
-executing in restricted execution mode based on the identity of the
-\code{__builtins__} object in its global variables: if this is (the
-dictionary of) the standard \refmodule[builtin]{__builtin__} module,
-the code is deemed to be unrestricted, else it is deemed to be
-restricted.
-
-Python code executing in restricted mode faces a number of limitations
-that are designed to prevent it from escaping from the padded cell.
-For instance, the function object attribute \member{func_globals} and
-the class and instance object attribute \member{__dict__} are
-unavailable.
-
-Two modules provide the framework for setting up restricted execution
-environments:
-
-\localmoduletable
-
-\begin{seealso}
-  \seetitle[http://grail.sourceforge.net/]{Grail Home Page}
-           {Grail, an Internet browser written in Python, uses these
-            modules to support Python applets.  More
-            information on the use of Python's restricted execution
-            mode in Grail is available on the Web site.}
-\end{seealso}
diff --git a/Doc/lib/librexec.tex b/Doc/lib/librexec.tex
deleted file mode 100644
index eb8c896..0000000
--- a/Doc/lib/librexec.tex
+++ /dev/null
@@ -1,275 +0,0 @@
-\section{\module{rexec} ---
-         Restricted execution framework}
-
-\declaremodule{standard}{rexec}
-\modulesynopsis{Basic restricted execution framework.}
-\versionchanged[Disabled module]{2.3}
-
-\begin{notice}[warning]
-  The documentation has been left in place to help in reading old code
-  that uses the module.
-\end{notice}
-
-This module contains the \class{RExec} class, which supports
-\method{r_eval()}, \method{r_execfile()}, \method{r_exec()}, and
-\method{r_import()} methods, which are restricted versions of the standard
-Python functions \method{eval()}, \method{execfile()} and
-the \keyword{exec} and \keyword{import} statements.
-Code executed in this restricted environment will
-only have access to modules and functions that are deemed safe; you
-can subclass \class{RExec} to add or remove capabilities as desired.
-
-\begin{notice}[warning]
-  While the \module{rexec} module is designed to perform as described
-  below, it does have a few known vulnerabilities which could be
-  exploited by carefully written code.  Thus it should not be relied
-  upon in situations requiring ``production ready'' security.  In such
-  situations, execution via sub-processes or very careful
-  ``cleansing'' of both code and data to be processed may be
-  necessary.  Alternatively, help in patching known \module{rexec}
-  vulnerabilities would be welcomed.
-\end{notice}
-
-\begin{notice}
-  The \class{RExec} class can prevent code from performing unsafe
-  operations like reading or writing disk files, or using TCP/IP
-  sockets.  However, it does not protect against code using extremely
-  large amounts of memory or processor time.
-\end{notice}
-
-\begin{classdesc}{RExec}{\optional{hooks\optional{, verbose}}}
-Returns an instance of the \class{RExec} class.  
-
-\var{hooks} is an instance of the \class{RHooks} class or a subclass of it.
-If it is omitted or \code{None}, the default \class{RHooks} class is
-instantiated.
-Whenever the \module{rexec} module searches for a module (even a
-built-in one) or reads a module's code, it doesn't actually go out to
-the file system itself.  Rather, it calls methods of an \class{RHooks}
-instance that was passed to or created by its constructor.  (Actually,
-the \class{RExec} object doesn't make these calls --- they are made by
-a module loader object that's part of the \class{RExec} object.  This
-allows another level of flexibility, which can be useful when changing
-the mechanics of \keyword{import} within the restricted environment.)
-
-By providing an alternate \class{RHooks} object, we can control the
-file system accesses made to import a module, without changing the
-actual algorithm that controls the order in which those accesses are
-made.  For instance, we could substitute an \class{RHooks} object that
-passes all filesystem requests to a file server elsewhere, via some
-RPC mechanism such as ILU.  Grail's applet loader uses this to support
-importing applets from a URL for a directory.
-
-If \var{verbose} is true, additional debugging output may be sent to
-standard output.
-\end{classdesc}
-
-It is important to be aware that code running in a restricted
-environment can still call the \function{sys.exit()} function.  To
-disallow restricted code from exiting the interpreter, always protect
-calls that cause restricted code to run with a
-\keyword{try}/\keyword{except} statement that catches the
-\exception{SystemExit} exception.  Removing the \function{sys.exit()}
-function from the restricted environment is not sufficient --- the
-restricted code could still use \code{raise SystemExit}.  Removing
-\exception{SystemExit} is not a reasonable option; some library code
-makes use of this and would break were it not available.
-
-
-\begin{seealso}
-  \seetitle[http://grail.sourceforge.net/]{Grail Home Page}{Grail is a
-            Web browser written entirely in Python.  It uses the
-            \module{rexec} module as a foundation for supporting
-            Python applets, and can be used as an example usage of
-            this module.}
-\end{seealso}
-
-
-\subsection{RExec Objects \label{rexec-objects}}
-
-\class{RExec} instances support the following methods:
-
-\begin{methoddesc}[RExec]{r_eval}{code}
-\var{code} must either be a string containing a Python expression, or
-a compiled code object, which will be evaluated in the restricted
-environment's \module{__main__} module.  The value of the expression or
-code object will be returned.
-\end{methoddesc}
-
-\begin{methoddesc}[RExec]{r_exec}{code}
-\var{code} must either be a string containing one or more lines of
-Python code, or a compiled code object, which will be executed in the
-restricted environment's \module{__main__} module.
-\end{methoddesc}
-
-\begin{methoddesc}[RExec]{r_execfile}{filename}
-Execute the Python code contained in the file \var{filename} in the
-restricted environment's \module{__main__} module.
-\end{methoddesc}
-
-Methods whose names begin with \samp{s_} are similar to the functions
-beginning with \samp{r_}, but the code will be granted access to
-restricted versions of the standard I/O streams \code{sys.stdin},
-\code{sys.stderr}, and \code{sys.stdout}.
-
-\begin{methoddesc}[RExec]{s_eval}{code}
-\var{code} must be a string containing a Python expression, which will
-be evaluated in the restricted environment.  
-\end{methoddesc}
-
-\begin{methoddesc}[RExec]{s_exec}{code}
-\var{code} must be a string containing one or more lines of Python code,
-which will be executed in the restricted environment.  
-\end{methoddesc}
-
-\begin{methoddesc}[RExec]{s_execfile}{code}
-Execute the Python code contained in the file \var{filename} in the
-restricted environment.
-\end{methoddesc}
-
-\class{RExec} objects must also support various methods which will be
-implicitly called by code executing in the restricted environment.
-Overriding these methods in a subclass is used to change the policies
-enforced by a restricted environment.
-
-\begin{methoddesc}[RExec]{r_import}{modulename\optional{, globals\optional{,
-                                    locals\optional{, fromlist}}}}
-Import the module \var{modulename}, raising an \exception{ImportError}
-exception if the module is considered unsafe.
-\end{methoddesc}
-
-\begin{methoddesc}[RExec]{r_open}{filename\optional{, mode\optional{, bufsize}}}
-Method called when \function{open()} is called in the restricted
-environment.  The arguments are identical to those of \function{open()},
-and a file object (or a class instance compatible with file objects)
-should be returned.  \class{RExec}'s default behaviour is allow opening
-any file for reading, but forbidding any attempt to write a file.  See
-the example below for an implementation of a less restrictive
-\method{r_open()}.
-\end{methoddesc}
-
-\begin{methoddesc}[RExec]{r_reload}{module}
-Reload the module object \var{module}, re-parsing and re-initializing it.  
-\end{methoddesc}
-
-\begin{methoddesc}[RExec]{r_unload}{module}
-Unload the module object \var{module} (remove it from the
-restricted environment's \code{sys.modules} dictionary).
-\end{methoddesc}
-
-And their equivalents with access to restricted standard I/O streams:
-
-\begin{methoddesc}[RExec]{s_import}{modulename\optional{, globals\optional{,
-                                    locals\optional{, fromlist}}}}
-Import the module \var{modulename}, raising an \exception{ImportError}
-exception if the module is considered unsafe.
-\end{methoddesc}
-
-\begin{methoddesc}[RExec]{s_reload}{module}
-Reload the module object \var{module}, re-parsing and re-initializing it.  
-\end{methoddesc}
-
-\begin{methoddesc}[RExec]{s_unload}{module}
-Unload the module object \var{module}.   
-% XXX what are the semantics of this?  
-\end{methoddesc}
-
-
-\subsection{Defining restricted environments \label{rexec-extension}}
-
-The \class{RExec} class has the following class attributes, which are
-used by the \method{__init__()} method.  Changing them on an existing
-instance won't have any effect; instead, create a subclass of
-\class{RExec} and assign them new values in the class definition.
-Instances of the new class will then use those new values.  All these
-attributes are tuples of strings.
-
-\begin{memberdesc}[RExec]{nok_builtin_names}
-Contains the names of built-in functions which will \emph{not} be
-available to programs running in the restricted environment.  The
-value for \class{RExec} is \code{('open', 'reload', '__import__')}.
-(This gives the exceptions, because by far the majority of built-in
-functions are harmless.  A subclass that wants to override this
-variable should probably start with the value from the base class and
-concatenate additional forbidden functions --- when new dangerous
-built-in functions are added to Python, they will also be added to
-this module.)
-\end{memberdesc}
-
-\begin{memberdesc}[RExec]{ok_builtin_modules}
-Contains the names of built-in modules which can be safely imported.
-The value for \class{RExec} is \code{('audioop', 'array', 'binascii',
-'cmath', 'errno', 'imageop', 'marshal', 'math', 'md5', 'operator',
-'parser', 'regex', 'select', 'sha', '_sre', 'strop',
-'struct', 'time')}.  A similar remark about overriding this variable
-applies --- use the value from the base class as a starting point.
-\end{memberdesc}
-
-\begin{memberdesc}[RExec]{ok_path}
-Contains the directories which will be searched when an \keyword{import}
-is performed in the restricted environment.  
-The value for \class{RExec} is the same as \code{sys.path} (at the time
-the module is loaded) for unrestricted code.
-\end{memberdesc}
-
-\begin{memberdesc}[RExec]{ok_posix_names}
-% Should this be called ok_os_names?
-Contains the names of the functions in the \refmodule{os} module which will be
-available to programs running in the restricted environment.  The
-value for \class{RExec} is \code{('error', 'fstat', 'listdir',
-'lstat', 'readlink', 'stat', 'times', 'uname', 'getpid', 'getppid',
-'getcwd', 'getuid', 'getgid', 'geteuid', 'getegid')}.
-\end{memberdesc}
-
-\begin{memberdesc}[RExec]{ok_sys_names}
-Contains the names of the functions and variables in the \refmodule{sys}
-module which will be available to programs running in the restricted
-environment.  The value for \class{RExec} is \code{('ps1', 'ps2',
-'copyright', 'version', 'platform', 'exit', 'maxint')}.
-\end{memberdesc}
-
-\begin{memberdesc}[RExec]{ok_file_types}
-Contains the file types from which modules are allowed to be loaded.
-Each file type is an integer constant defined in the \refmodule{imp} module.
-The meaningful values are \constant{PY_SOURCE}, \constant{PY_COMPILED}, and
-\constant{C_EXTENSION}.  The value for \class{RExec} is \code{(C_EXTENSION,
-PY_SOURCE)}.  Adding \constant{PY_COMPILED} in subclasses is not recommended;
-an attacker could exit the restricted execution mode by putting a forged
-byte-compiled file (\file{.pyc}) anywhere in your file system, for example
-by writing it to \file{/tmp} or uploading it to the \file{/incoming}
-directory of your public FTP server.
-\end{memberdesc}
-
-
-\subsection{An example}
-
-Let us say that we want a slightly more relaxed policy than the
-standard \class{RExec} class.  For example, if we're willing to allow
-files in \file{/tmp} to be written, we can subclass the \class{RExec}
-class:
-
-\begin{verbatim}
-class TmpWriterRExec(rexec.RExec):
-    def r_open(self, file, mode='r', buf=-1):
-        if mode in ('r', 'rb'):
-            pass
-        elif mode in ('w', 'wb', 'a', 'ab'):
-            # check filename : must begin with /tmp/
-            if file[:5]!='/tmp/': 
-                raise IOError, "can't write outside /tmp"
-            elif (string.find(file, '/../') >= 0 or
-                 file[:3] == '../' or file[-3:] == '/..'):
-                raise IOError, "'..' in filename forbidden"
-        else: raise IOError, "Illegal open() mode"
-        return open(file, mode, buf)
-\end{verbatim}
-%
-Notice that the above code will occasionally forbid a perfectly valid
-filename; for example, code in the restricted environment won't be
-able to open a file called \file{/tmp/foo/../bar}.  To fix this, the
-\method{r_open()} method would have to simplify the filename to
-\file{/tmp/bar}, which would require splitting apart the filename and
-performing various operations on it.  In cases where security is at
-stake, it may be preferable to write simple code which is sometimes
-overly restrictive, instead of more general code that is also more
-complex and may harbor a subtle security hole.
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 '} 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"  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. 
-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/libsets.tex b/Doc/lib/libsets.tex
deleted file mode 100644
index e02a7f5..0000000
--- a/Doc/lib/libsets.tex
+++ /dev/null
@@ -1,266 +0,0 @@
-\section{\module{sets} ---
-         Unordered collections of unique elements}
-
-\declaremodule{standard}{sets}
-\modulesynopsis{Implementation of sets of unique elements.}
-\moduleauthor{Greg V. Wilson}{gvwilson@nevex.com}
-\moduleauthor{Alex Martelli}{aleax@aleax.it}
-\moduleauthor{Guido van Rossum}{guido@python.org}
-\sectionauthor{Raymond D. Hettinger}{python@rcn.com}
-
-\versionadded{2.3}
-\deprecated{2.6}{The built-in \code{set}/\code{frozenset} types replace this
-module.}
-
-The \module{sets} module provides classes for constructing and manipulating
-unordered collections of unique elements.  Common uses include membership
-testing, removing duplicates from a sequence, and computing standard math
-operations on sets such as intersection, union, difference, and symmetric
-difference.
-
-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.
-
-Most set applications use the \class{Set} class which provides every set
-method except for \method{__hash__()}. For advanced applications requiring
-a hash method, the \class{ImmutableSet} class adds a \method{__hash__()}
-method but omits methods which alter the contents of the set. Both
-\class{Set} and \class{ImmutableSet} derive from \class{BaseSet}, an
-abstract class useful for determining whether something is a set:
-\code{isinstance(\var{obj}, BaseSet)}.
-
-The set classes are implemented using dictionaries.  Accordingly, the
-requirements for set elements are the same as those for dictionary keys;
-namely, that the element defines both \method{__eq__} and \method{__hash__}.
-As a result, sets
-cannot contain mutable elements such as lists or dictionaries.
-However, they can contain immutable collections such as tuples or
-instances of \class{ImmutableSet}.  For convenience in implementing
-sets of sets, inner sets are automatically converted to immutable
-form, for example, \code{Set([Set(['dog'])])} is transformed to
-\code{Set([ImmutableSet(['dog'])])}.
-
-\begin{classdesc}{Set}{\optional{iterable}}
-Constructs a new empty \class{Set} object.  If the optional \var{iterable}
-parameter is supplied, updates the set with elements obtained from iteration.
-All of the elements in \var{iterable} should be immutable or be transformable
-to an immutable using the protocol described in
-section~\ref{immutable-transforms}.
-\end{classdesc}
-
-\begin{classdesc}{ImmutableSet}{\optional{iterable}}
-Constructs a new empty \class{ImmutableSet} object.  If the optional
-\var{iterable} parameter is supplied, updates the set with elements obtained
-from iteration.  All of the elements in \var{iterable} should be immutable or
-be transformable to an immutable using the protocol described in
-section~\ref{immutable-transforms}.
-
-Because \class{ImmutableSet} objects provide a \method{__hash__()} method,
-they can be used as set elements or as dictionary keys.  \class{ImmutableSet}
-objects do not have methods for adding or removing elements, so all of the
-elements must be known when the constructor is called.
-\end{classdesc}
-
-
-\subsection{Set Objects \label{set-objects}}
-
-Instances of \class{Set} and \class{ImmutableSet} both 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} \textbar{} \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()} 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')}.
-\versionchanged[Formerly all arguments were required to be sets]{2.3.1}
-
-In addition, both \class{Set} and \class{ImmutableSet}
-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).
-
-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.
-
-The following table lists operations available in \class{ImmutableSet}
-but not found in \class{Set}:
-
-\begin{tableii}{c|l}{code}{Operation}{Result}
-  \lineii{hash(\var{s})}{returns a hash value for \var{s}}
-\end{tableii}
-
-The following table lists operations available in \class{Set}
-but not found in \class{ImmutableSet}:
-
-\begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result}
-  \lineiii{\var{s}.update(\var{t})}
-         {\var{s} \textbar= \var{t}}
-         {return set \var{s} with elements added from \var{t}}
-  \lineiii{\var{s}.intersection_update(\var{t})}
-         {\var{s} \&= \var{t}}
-         {return set \var{s} keeping only elements also found in \var{t}}
-  \lineiii{\var{s}.difference_update(\var{t})}
-         {\var{s} -= \var{t}}
-         {return set \var{s} after removing elements found in \var{t}}
-  \lineiii{\var{s}.symmetric_difference_update(\var{t})}
-         {\var{s} \textasciicircum= \var{t}}
-         {return set \var{s} with elements from \var{s} or \var{t}
-          but not 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 \method{update()},
-\method{intersection_update()}, \method{difference_update()}, and
-\method{symmetric_difference_update()} will accept any iterable as
-an argument.
-\versionchanged[Formerly all arguments were required to be sets]{2.3.1}
-
-Also note, the module also includes a \method{union_update()} method
-which is an alias for \method{update()}.  The method is included for
-backwards compatibility.  Programmers should prefer the
-\method{update()} method because it is supported by the builtin
-\class{set()} and \class{frozenset()} types.
-
-\subsection{Example \label{set-example}}
-
-\begin{verbatim}
->>> from sets import Set
->>> engineers = Set(['John', 'Jane', 'Jack', 'Janice'])
->>> programmers = Set(['Jack', 'Sam', 'Susan', 'Janice'])
->>> managers = Set(['Jane', 'Jack', 'Susan', 'Zack'])
->>> employees = engineers | programmers | managers           # union
->>> engineering_management = engineers & managers            # intersection
->>> fulltime_management = managers - engineers - programmers # difference
->>> engineers.add('Marvin')                                  # add element
->>> print engineers
-Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
->>> employees.issuperset(engineers)     # superset test
-False
->>> employees.update(engineers)         # update from another set
->>> employees.issuperset(engineers)
-True
->>> for group in [engineers, programmers, managers, employees]:
-...     group.discard('Susan')          # unconditionally remove element
-...     print group
-...
-Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
-Set(['Janice', 'Jack', 'Sam'])
-Set(['Jane', 'Zack', 'Jack'])
-Set(['Jack', 'Sam', 'Jane', 'Marvin', 'Janice', 'John', 'Zack'])
-\end{verbatim}
-
-
-\subsection{Protocol for automatic conversion to immutable
-            \label{immutable-transforms}}
-
-Sets can only contain immutable elements.  For convenience, mutable
-\class{Set} objects are automatically copied to an \class{ImmutableSet}
-before being added as a set element.
-
-The mechanism is to always add a hashable element, or if it is not
-hashable, the element is checked to see if it has an
-\method{__as_immutable__()} method which returns an immutable equivalent.
-
-Since \class{Set} objects have a \method{__as_immutable__()} method
-returning an instance of \class{ImmutableSet}, it is possible to
-construct sets of sets.
-
-A similar mechanism is needed by the \method{__contains__()} and
-\method{remove()} methods which need to hash an element to check
-for membership in a set.  Those methods check an element for hashability
-and, if not, check for a \method{__as_temporarily_immutable__()} method
-which returns the element wrapped by a class that provides temporary
-methods for \method{__hash__()}, \method{__eq__()}, and \method{__ne__()}.
-
-The alternate mechanism spares the need to build a separate copy of
-the original mutable object.
-
-\class{Set} objects implement the \method{__as_temporarily_immutable__()}
-method which returns the \class{Set} object wrapped by a new class
-\class{_TemporarilyImmutableSet}.
-
-The two mechanisms for adding hashability are normally invisible to the
-user; however, a conflict can arise in a multi-threaded environment
-where one thread is updating a set while another has temporarily wrapped it
-in \class{_TemporarilyImmutableSet}.  In other words, sets of mutable sets
-are not thread-safe.
-
-
-\subsection{Comparison to the built-in \class{set} types
-            \label{comparison-to-builtin-set}}
-
-The built-in \class{set} and \class{frozenset} types were designed based
-on lessons learned from the \module{sets} module.  The key differences are:
-
-\begin{itemize}
-\item \class{Set} and \class{ImmutableSet} were renamed to \class{set} and
-      \class{frozenset}.
-\item There is no equivalent to \class{BaseSet}.  Instead, use
-      \code{isinstance(x, (set, frozenset))}.
-\item The hash algorithm for the built-ins performs significantly better
-      (fewer collisions) for most datasets.
-\item The built-in versions have more space efficient pickles.
-\item The built-in versions do not have a \method{union_update()} method.
-      Instead, use the \method{update()} method which is equivalent.
-\item The built-in versions do not have a \method{_repr(sorted=True)} method.
-      Instead, use the built-in \function{repr()} and \function{sorted()}
-      functions:  \code{repr(sorted(s))}.
-\item The built-in version does not have a protocol for automatic conversion
-      to immutable.  Many found this feature to be confusing and no one
-      in the community reported having found real uses for it.
-\end{itemize}    
diff --git a/Doc/lib/libsgi.tex b/Doc/lib/libsgi.tex
deleted file mode 100644
index ca17ad0..0000000
--- a/Doc/lib/libsgi.tex
+++ /dev/null
@@ -1,7 +0,0 @@
-\chapter{SGI IRIX Specific Services}
-\label{sgi}
-
-The modules described in this chapter provide interfaces to features
-that are unique to SGI's IRIX operating system (versions 4 and 5).
-
-\localmoduletable
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{}, 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{}.  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{} 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{\&amp;}, \code{\&apos}, \code{\&gt;}, \code{\&lt;}, and
-\code{\&quot;}.
-\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/libsha.tex b/Doc/lib/libsha.tex
deleted file mode 100644
index 6d1da68..0000000
--- a/Doc/lib/libsha.tex
+++ /dev/null
@@ -1,83 +0,0 @@
-\section{\module{sha} ---
-         SHA-1 message digest algorithm}
-
-\declaremodule{builtin}{sha}
-\modulesynopsis{NIST's secure hash algorithm, SHA.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-\deprecated{2.5}{Use the \refmodule{hashlib} module instead.}
-
-
-This module implements the interface to NIST's\index{NIST} secure hash 
-algorithm,\index{Secure Hash Algorithm} known as SHA-1.  SHA-1 is an
-improved version of the original SHA hash algorithm.  It is used in
-the same way as the \refmodule{md5} module:\ use \function{new()}
-to create an sha object, then feed this object with arbitrary strings
-using the \method{update()} method, and at any point you can ask it
-for the \dfn{digest} of the concatenation of the strings fed to it
-so far.\index{checksum!SHA}  SHA-1 digests are 160 bits instead of
-MD5's 128 bits.
-
-
-\begin{funcdesc}{new}{\optional{string}}
-  Return a new sha object.  If \var{string} is present, the method
-  call \code{update(\var{string})} is made.
-\end{funcdesc}
-
-
-The following values are provided as constants in the module and as
-attributes of the sha objects returned by \function{new()}:
-
-\begin{datadesc}{blocksize}
-  Size of the blocks fed into the hash function; this is always
-  \code{1}.  This size is used to allow an arbitrary string to be
-  hashed.
-\end{datadesc}
-
-\begin{datadesc}{digest_size}
-  The size of the resulting digest in bytes.  This is always
-  \code{20}.
-\end{datadesc}
-
-
-An sha object has the same methods as md5 objects:
-
-\begin{methoddesc}[sha]{update}{arg}
-Update the sha 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}[sha]{digest}{}
-Return the digest of the strings passed to the \method{update()}
-method so far.  This is a 20-byte string which may contain
-non-\ASCII{} characters, including null bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[sha]{hexdigest}{}
-Like \method{digest()} except the digest is returned as a string of
-length 40, containing only hexadecimal digits.  This may 
-be used to exchange the value safely in email or other non-binary
-environments.
-\end{methoddesc}
-
-\begin{methoddesc}[sha]{copy}{}
-Return a copy (``clone'') of the sha object.  This can be used to
-efficiently compute the digests of strings that share a common initial
-substring.
-\end{methoddesc}
-
-\begin{seealso}
-  \seetitle[http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf]
-    {Secure Hash Standard}
-    {The Secure Hash Algorithm is defined by NIST document FIPS
-     PUB 180-2:
-     \citetitle[http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf]
-        {Secure Hash Standard}, published in August 2002.}
-
-  \seetitle[http://csrc.nist.gov/encryption/tkhash.html]
-           {Cryptographic Toolkit (Secure Hashing)}
-           {Links from NIST to various information on secure hashing.}
-\end{seealso}
-
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 c5a28a0..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), 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 a76799b..0000000
--- a/Doc/lib/libsmtplib.tex
+++ /dev/null
@@ -1,338 +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 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 d9b3b79..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, msg:
-	s = None
-	continue
-    try:
-	s.bind(sa)
-	s.listen(1)
-    except socket.error, 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, msg:
-	s = None
-	continue
-    try:
-	s.connect(sa)
-    except socket.error, 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 66e10a3..0000000
--- a/Doc/lib/libstdtypes.tex
+++ /dev/null
@@ -1,2104 +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{__nonzero__()} 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}{(1)}
-  \lineiii{<>}{not equal}{(1)}
-  \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}
-
-\noindent
-Notes:
-
-\begin{description}
-
-\item[(1)]
-\code{<>} and \code{!=} are alternate spellings for the same operator.
-\code{!=} is the preferred spelling; \code{<>} is obsolescent.
-
-\end{description}
-
-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{xrange}
-	    \label{typesseq}}
-
-There are six sequence types: strings, Unicode strings, lists,
-tuples, buffers, and xrange 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{xrange()}
-function.\bifuncindex{xrange}  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{xrange}
-
-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]{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-xrange}}
-
-The \class{xrange}\obindex{xrange} type is an immutable sequence which
-is commonly used for looping.  The advantage of the \class{xrange}
-type is that an \class{xrange} 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.
-
-The design of the set types was based on lessons learned from the
-\module{sets} module.
-     
-\begin{seealso}     
-  \seelink{comparison-to-builtin-set.html}
-          {Comparison to the built-in set types}
-          {Differences between the \module{sets} module and the
-           built-in set types.}					      
-\end{seealso}
-     
-
-\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]{xreadlines}{}
-  This method returns the same thing as \code{iter(f)}.
-  \versionadded{2.1}
-  \deprecated{2.3}{Use \samp{for \var{line} in \var{file}} instead.}
-\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{func_code}
-attribute.
-\bifuncindex{compile}
-\withsubitem{(function object attribute)}{\ttindex{func_code}}
-
-A code object can be executed or evaluated by passing it (instead of a
-source string) to the \keyword{exec} statement or the built-in
-\function{eval()} function.
-\stindex{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 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}.
-
-\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}[object]{__methods__}
-\deprecated{2.2}{Use the built-in function \function{dir()} to get a
-list of an object's attributes.  This attribute is no longer available.}
-\end{memberdesc}
-
-\begin{memberdesc}[object]{__members__}
-\deprecated{2.2}{Use the built-in function \function{dir()} to get a
-list of an object's attributes.  This attribute is no longer available.}
-\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 055ac0c..0000000
--- a/Doc/lib/libstring.tex
+++ /dev/null
@@ -1,452 +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}{letters}
-  The concatenation of the strings \constant{lowercase} and
-  \constant{uppercase} described below.  The specific value is
-  locale-dependent, and will be updated when
-  \function{locale.setlocale()} is called.
-\end{datadesc}
-
-\begin{datadesc}{lowercase}
-  A string containing all the characters that are considered lowercase
-  letters.  On most systems this is the string
-  \code{'abcdefghijklmnopqrstuvwxyz'}.  Do not change its definition ---
-  the effect on the routines \function{upper()} and
-  \function{swapcase()} is undefined.  The specific value is
-  locale-dependent, and will be updated when
-  \function{locale.setlocale()} is called.
-\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}{uppercase}
-  A string containing all the characters that are considered uppercase
-  letters.  On most systems this is the string
-  \code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.  Do not change its definition ---
-  the effect on the routines \function{lower()} and
-  \function{swapcase()} is undefined.  The specific value is
-  locale-dependent, and will be updated when
-  \function{locale.setlocale()} is called.
-\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 a569c91..0000000
--- a/Doc/lib/libsubprocess.tex
+++ /dev/null
@@ -1,407 +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*
-os.popen*
-popen2.*
-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, 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}
-
-\begin{verbatim}
-(child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
-==>
-p = Popen(cmd, shell=True, bufsize=bufsize,
-          stdin=PIPE, stdout=PIPE, close_fds=True)
-(child_stdin, child_stdout) = (p.stdin, p.stdout)
-\end{verbatim}
-
-\begin{verbatim}
-(child_stdin,
- child_stdout,
- child_stderr) = os.popen3(cmd, mode, bufsize)
-==>
-p = Popen(cmd, shell=True, bufsize=bufsize,
-          stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
-(child_stdin,
- child_stdout,
- child_stderr) = (p.stdin, p.stdout, p.stderr)
-\end{verbatim}
-
-\begin{verbatim}
-(child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
-==>
-p = Popen(cmd, shell=True, bufsize=bufsize,
-          stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
-(child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
-\end{verbatim}
-
-\subsubsection{Replacing popen2.*}
-
-\note{If the cmd argument to popen2 functions is a string, the command
-is executed through /bin/sh.  If it is a list, the command is directly
-executed.}
-
-\begin{verbatim}
-(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
-==>
-p = Popen(["somestring"], shell=True, bufsize=bufsize,
-          stdin=PIPE, stdout=PIPE, close_fds=True)
-(child_stdout, child_stdin) = (p.stdout, p.stdin)
-\end{verbatim}
-
-\begin{verbatim}
-(child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
-==>
-p = Popen(["mycmd", "myarg"], bufsize=bufsize,
-          stdin=PIPE, stdout=PIPE, close_fds=True)
-(child_stdout, child_stdin) = (p.stdout, p.stdin)
-\end{verbatim}
-
-The popen2.Popen3 and popen2.Popen4 basically works as subprocess.Popen,
-except that:
-
-\begin{itemize}
-\item subprocess.Popen raises an exception if the execution fails
-
-\item the \var{capturestderr} argument is replaced with the \var{stderr}
-      argument.
-
-\item stdin=PIPE and stdout=PIPE must be specified.
-
-\item popen2 closes all file descriptors by default, but you have to
-      specify close_fds=True with subprocess.Popen.
-\end{itemize}
diff --git a/Doc/lib/libsun.tex b/Doc/lib/libsun.tex
deleted file mode 100644
index 8fcfb6a..0000000
--- a/Doc/lib/libsun.tex
+++ /dev/null
@@ -1,7 +0,0 @@
-\chapter{SunOS Specific Services}
-\label{sunos}
-
-The modules described in this chapter provide interfaces to features
-that are unique to SunOS 5 (also known as Solaris version 2).
-
-\localmoduletable
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/libsunaudio.tex b/Doc/lib/libsunaudio.tex
deleted file mode 100644
index ec70437..0000000
--- a/Doc/lib/libsunaudio.tex
+++ /dev/null
@@ -1,146 +0,0 @@
-\section{\module{sunaudiodev} ---
-         Access to Sun audio hardware}
-
-\declaremodule{builtin}{sunaudiodev}
-  \platform{SunOS}
-\modulesynopsis{Access to Sun audio hardware.}
-
-
-This module allows you to access the Sun audio interface. The Sun
-audio hardware is capable of recording and playing back audio data
-in u-LAW\index{u-LAW} format with a sample rate of 8K per second. A
-full description can be found in the \manpage{audio}{7I} manual page.
-
-The module
-\refmodule[sunaudiodev-constants]{SUNAUDIODEV}\refstmodindex{SUNAUDIODEV} 
-defines constants which may be used with this module.
-
-This module defines the following variables and functions:
-
-\begin{excdesc}{error}
-This exception is raised on all errors. The argument is a string
-describing what went wrong.
-\end{excdesc}
-
-\begin{funcdesc}{open}{mode}
-This function opens the audio device and returns a Sun audio device
-object. This object can then be used to do I/O on. The \var{mode} parameter
-is one of \code{'r'} for record-only access, \code{'w'} for play-only
-access, \code{'rw'} for both and \code{'control'} for access to the
-control device. Since only one process is allowed to have the recorder
-or player open at the same time it is a good idea to open the device
-only for the activity needed. See \manpage{audio}{7I} for details.
-
-As per the manpage, this module first looks in the environment
-variable \code{AUDIODEV} for the base audio device filename.  If not
-found, it falls back to \file{/dev/audio}.  The control device is
-calculated by appending ``ctl'' to the base audio device.
-\end{funcdesc}
-
-
-\subsection{Audio Device Objects \label{audio-device-objects}}
-
-The audio device objects are returned by \function{open()} define the
-following methods (except \code{control} objects which only provide
-\method{getinfo()}, \method{setinfo()}, \method{fileno()}, and
-\method{drain()}):
-
-\begin{methoddesc}[audio device]{close}{}
-This method explicitly closes the device. It is useful in situations
-where deleting the object does not immediately close it since there
-are other references to it. A closed device should not be used again.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{fileno}{}
-Returns the file descriptor associated with the device.  This can be
-used to set up \code{SIGPOLL} notification, as described below.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{drain}{}
-This method waits until all pending output is processed and then returns.
-Calling this method is often not necessary: destroying the object will
-automatically close the audio device and this will do an implicit drain.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{flush}{}
-This method discards all pending output. It can be used avoid the
-slow response to a user's stop request (due to buffering of up to one
-second of sound).
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{getinfo}{}
-This method retrieves status information like input and output volume,
-etc. and returns it in the form of
-an audio status object. This object has no methods but it contains a
-number of attributes describing the current device status. The names
-and meanings of the attributes are described in
-\code{<sun/audioio.h>} and in the \manpage{audio}{7I}
-manual page.  Member names
-are slightly different from their C counterparts: a status object is
-only a single structure. Members of the \cdata{play} substructure have
-\samp{o_} prepended to their name and members of the \cdata{record}
-structure have \samp{i_}. So, the C member \cdata{play.sample_rate} is
-accessed as \member{o_sample_rate}, \cdata{record.gain} as \member{i_gain}
-and \cdata{monitor_gain} plainly as \member{monitor_gain}.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{ibufcount}{}
-This method returns the number of samples that are buffered on the
-recording side, i.e.\ the program will not block on a
-\function{read()} call of so many samples.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{obufcount}{}
-This method returns the number of samples buffered on the playback
-side. Unfortunately, this number cannot be used to determine a number
-of samples that can be written without blocking since the kernel
-output queue length seems to be variable.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{read}{size}
-This method reads \var{size} samples from the audio input and returns
-them as a Python string. The function blocks until enough data is available.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{setinfo}{status}
-This method sets the audio device status parameters. The \var{status}
-parameter is an device status object as returned by \function{getinfo()} and
-possibly modified by the program.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{write}{samples}
-Write is passed a Python string containing audio samples to be played.
-If there is enough buffer space free it will immediately return,
-otherwise it will block.
-\end{methoddesc}
-
-The audio device supports asynchronous notification of various events,
-through the SIGPOLL signal.  Here's an example of how you might enable
-this in Python:
-
-\begin{verbatim}
-def handle_sigpoll(signum, frame):
-    print 'I got a SIGPOLL update'
-
-import fcntl, signal, STROPTS
-
-signal.signal(signal.SIGPOLL, handle_sigpoll)
-fcntl.ioctl(audio_obj.fileno(), STROPTS.I_SETSIG, STROPTS.S_MSG)
-\end{verbatim}
-
-
-\section{\module{SUNAUDIODEV} ---
-         Constants used with \module{sunaudiodev}}
-
-\declaremodule[sunaudiodev-constants]{standard}{SUNAUDIODEV}
-  \platform{SunOS}
-\modulesynopsis{Constants for use with \refmodule{sunaudiodev}.}
-
-
-This is a companion module to
-\refmodule{sunaudiodev}\refbimodindex{sunaudiodev} which defines
-useful symbolic constants like \constant{MIN_GAIN},
-\constant{MAX_GAIN}, \constant{SPEAKER}, etc. The names of the
-constants are the same names as used in the C include file
-\code{<sun/audioio.h>}, with the leading string \samp{AUDIO_}
-stripped.
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 396c91a..0000000
--- a/Doc/lib/libsys.tex
+++ /dev/null
@@ -1,617 +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}
-
-  If \function{exc_clear()} is called, this function will return three
-  \code{None} values until either another exception is raised in the
-  current thread or the execution stack returns to a frame where
-  another exception is being handled.
-
-  \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{funcdesc}{exc_clear}{}
-  This function clears all information relating to the current or last
-  exception that occurred in the current thread.  After calling this
-  function, \function{exc_info()} will return three \code{None} values until
-  another exception is raised in the current thread or the execution stack
-  returns to a frame where another exception is being handled.
-
-  This function is only needed in only a few obscure situations.  These
-  include logging and error handling systems that report information on the
-  last or current exception.  This function can also be used to try to free
-  resources and trigger object finalization, though no guarantee is made as
-  to what objects will be freed, if any.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{datadesc}{exc_type}
-\dataline{exc_value}
-\dataline{exc_traceback}
-\deprecated {1.5}
-            {Use \function{exc_info()} instead.}
-  Since they are global variables, they are not specific to the
-  current thread, so their use is not safe in a multi-threaded
-  program.  When no exception is being handled, \code{exc_type} is set
-  to \code{None} and the other two are undefined.
-\end{datadesc}
-
-\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{datadesc}{exitfunc}
-  This value is not actually defined by the module, but can be set by
-  the user (or by a program) to specify a clean-up action at program
-  exit.  When set, it should be a parameterless function.  This
-  function will be called when the interpreter exits.  Only one
-  function may be installed in this way; to allow multiple functions
-  which will be called at termination, use the \refmodule{atexit}
-  module.  \note{The exit function is not called when the program is
-  killed by a signal, when a Python fatal internal error is detected,
-  or when \code{os._exit()} is called.}
-  \deprecated{2.4}{Use \refmodule{atexit} instead.}
-\end{datadesc}
-
-\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{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.  Note that removing a module from this
-  dictionary is \emph{not} the same as calling
-  \function{reload()}\bifuncindex{reload} on the corresponding module
-  object.
-\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 but including calls to
-  \function{input()}\bifuncindex{input} and
-  \function{raw_input()}\bifuncindex{raw_input}.  \code{stdout} is
-  used for the output of \keyword{print} and expression statements and
-  for the prompts of \function{input()} and \function{raw_input()}.
-  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 5b32a5f..0000000
--- a/Doc/lib/libtelnetlib.tex
+++ /dev/null
@@ -1,223 +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
-
-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 ef99cf9..0000000
--- a/Doc/lib/libtermios.tex
+++ /dev/null
@@ -1,106 +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 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 2e3bb61..0000000
--- a/Doc/lib/libtest.tex
+++ /dev/null
@@ -1,311 +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}{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}}
-Instances are a  context manager that raises \class{ResourceDenied} if the
-specified exception type is raised.  Any keyword arguments are treated as
-attribute/value pairs to be compared against any exception raised within the
-\code{with} statement.  Only if all pairs match properly against attributes on
-the exception 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 8a45bfcc..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 5dcb89e..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 xrange(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.__nonzero__' 'except AttributeError:' '  pass'
-100000 loops, best of 3: 15.7 usec per loop
-% timeit.py 'if hasattr(str, "__nonzero__"): pass'
-100000 loops, best of 3: 4.26 usec per loop
-% timeit.py 'try:' '  int.__nonzero__' 'except AttributeError:' '  pass'
-1000000 loops, best of 3: 1.43 usec per loop
-% timeit.py 'if hasattr(int, "__nonzero__"): pass'
-100000 loops, best of 3: 2.23 usec per loop
-\end{verbatim}
-
-\begin{verbatim}
->>> import timeit
->>> s = """\
-... try:
-...     str.__nonzero__
-... 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, '__nonzero__'): pass
-... """
->>> t = timeit.Timer(stmt=s)
->>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
-4.85 usec/pass
->>> s = """\
-... try:
-...     int.__nonzero__
-... 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, '__nonzero__'): 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 b7f61ac..0000000
--- a/Doc/lib/libtraceback.tex
+++ /dev/null
@@ -1,157 +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 variables \code{sys.exc_traceback} (deprecated) and
-\code{sys.last_traceback} 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(sys.exc_type,
-sys.exc_value, sys.exc_traceback, \var{limit}, \var{file})}.  (In
-fact, it uses \function{sys.exc_info()} to retrieve the same
-information in a thread-safe way instead of using the deprecated
-variables.)
-\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 in 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 5e0c5a6..0000000
--- a/Doc/lib/libtypes.tex
+++ /dev/null
@@ -1,215 +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}{InstanceType}
-The type of instances 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}{XRangeType}
-The type of range objects returned by
-\function{xrange()}\bifuncindex{xrange}.
-\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_traceback}.
-\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 e7d388f..0000000
--- a/Doc/lib/libundoc.tex
+++ /dev/null
@@ -1,113 +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.
-
-\item[\module{bsddb185}]
---- Backwards compatibility module for systems which still use the Berkeley
-    DB 1.85 module.  It is normally only available on certain BSD \UNIX-based
-    systems.  It should never be used directly.
-\end{description}
-
-
-\section{Multimedia}
-
-\begin{description}
-\item[\module{audiodev}]
---- Platform-independent API for playing audio data.
-
-\item[\module{linuxaudiodev}]
---- Play audio data on the Linux audio device.  Replaced in Python 2.3
-    by the \module{ossaudiodev} module.
-
-\item[\module{sunaudio}]
---- Interpret Sun audio headers (may become obsolete or a tool/demo).
-
-\item[\module{toaiff}]
---- Convert "arbitrary" sound files to AIFF files; should probably
-    become a tool or demo.  Requires the external program \program{sox}.
-\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[\module{timing}]
---- Measure time intervals to high resolution (use \function{time.clock()}
-    instead).
-\end{description}
-
-\section{SGI-specific Extension modules}
-
-The following are SGI specific, and may be out of touch with the
-current version of reality.
-
-\begin{description}
-\item[\module{cl}]
---- Interface to the SGI compression library.
-
-\item[\module{sv}]
---- Interface to the ``simple video'' board on SGI Indigo
-    (obsolete hardware).
-\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 4e915a2..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{execfile()}\bifuncindex{execfile}) 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 1df8f38..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{__nonzero__()} - 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 d0863d9..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, instance:
-    print 'packing the double failed:', instance.msg
-\end{verbatim}
diff --git a/Doc/lib/libxmllib.tex b/Doc/lib/libxmllib.tex
deleted file mode 100644
index f7197ca..0000000
--- a/Doc/lib/libxmllib.tex
+++ /dev/null
@@ -1,287 +0,0 @@
-\section{\module{xmllib} ---
-         A parser for XML documents}
-
-\declaremodule{standard}{xmllib}
-\modulesynopsis{A parser for XML documents.}
-\moduleauthor{Sjoerd Mullender}{Sjoerd.Mullender@cwi.nl}
-\sectionauthor{Sjoerd Mullender}{Sjoerd.Mullender@cwi.nl}
-
-
-\index{XML}
-\index{Extensible Markup Language}
-
-\deprecated{2.0}{Use \refmodule{xml.sax} instead.  The newer XML
-                 package includes full support for XML 1.0.}
-
-\versionchanged[Added namespace support]{1.5.2}
-
-This module defines a class \class{XMLParser} which serves as the basis 
-for parsing text files formatted in XML (Extensible Markup Language).
-
-\begin{classdesc}{XMLParser}{}
-The \class{XMLParser} class must be instantiated without
-arguments.\footnote{Actually, a number of keyword arguments are
-recognized which influence the parser to accept certain non-standard
-constructs.  The following keyword arguments are currently
-recognized.  The defaults for all of these is \code{0} (false) except
-for the last one for which the default is \code{1} (true).
-\var{accept_unquoted_attributes} (accept certain attribute values
-without requiring quotes), \var{accept_missing_endtag_name} (accept
-end tags that look like \code{</>}), \var{map_case} (map upper case to
-lower case in tags and attributes), \var{accept_utf8} (allow UTF-8
-characters in input; this is required according to the XML standard,
-but Python does not as yet deal properly with these characters, so
-this is not the default), \var{translate_attribute_references} (don't
-attempt to translate character and entity references in attribute values).}
-\end{classdesc}
-
-This class provides the following interface methods and instance variables:
-
-\begin{memberdesc}{attributes}
-A mapping of element names to mappings.  The latter mapping maps
-attribute names that are valid for the element to the default value of 
-the attribute, or if there is no default to \code{None}.  The default
-value is the empty dictionary.  This variable is meant to be
-overridden, not extended since the default is shared by all instances
-of \class{XMLParser}.
-\end{memberdesc}
-
-\begin{memberdesc}{elements} 
-A mapping of element names to tuples.  The tuples contain a function
-for handling the start and end tag respectively of the element, or
-\code{None} if the method \method{unknown_starttag()} or
-\method{unknown_endtag()} is to be called.  The default value is the
-empty dictionary.  This variable is meant to be overridden, not
-extended since the default is shared by all instances of
-\class{XMLParser}.
-\end{memberdesc}
-
-\begin{memberdesc}{entitydefs}
-A mapping of entitynames to their values.  The default value contains
-definitions for \code{'lt'}, \code{'gt'}, \code{'amp'}, \code{'quot'}, 
-and \code{'apos'}.
-\end{memberdesc}
-
-\begin{methoddesc}{reset}{}
-Reset the instance.  Loses all unprocessed data.  This is called
-implicitly at the instantiation time.
-\end{methoddesc}
-
-\begin{methoddesc}{setnomoretags}{}
-Stop processing tags.  Treat all following input as literal input
-(CDATA).
-\end{methoddesc}
-
-\begin{methoddesc}{setliteral}{}
-Enter literal mode (CDATA mode).  This mode is automatically exited
-when the close tag matching the last unclosed open tag is encountered.
-\end{methoddesc}
-
-\begin{methoddesc}{feed}{data}
-Feed some text to the parser.  It is processed insofar as it consists
-of complete tags; 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}{translate_references}{data}
-Translate all entity and character references in \var{data} and
-return the translated string.
-\end{methoddesc}
-
-\begin{methoddesc}{getnamespace}{}
-Return a mapping of namespace abbreviations to namespace URIs that are
-currently in effect.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_xml}{encoding, standalone}
-This method is called when the \samp{<?xml ...?>} tag is processed.
-The arguments are the values of the encoding and standalone attributes 
-in the tag.  Both encoding and standalone are optional.  The values
-passed to \method{handle_xml()} default to \code{None} and the string
-\code{'no'} respectively.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_doctype}{tag, pubid, syslit, data}
-This\index{DOCTYPE declaration} method is called when the
-\samp{<!DOCTYPE...>} declaration is processed.  The arguments are the
-tag name of the root element, the Formal Public\index{Formal Public
-Identifier} Identifier (or \code{None} if not specified), the system
-identifier, and the uninterpreted contents of the internal DTD subset
-as a string (or \code{None} if not present).
-\end{methoddesc}
-
-\begin{methoddesc}{handle_starttag}{tag, method, attributes}
-This method is called to handle start tags for which a start tag
-handler is defined in the instance variable \member{elements}.  The
-\var{tag} argument is the name of the tag, and the
-\var{method} argument is the function (method) which should be used to
-support semantic interpretation of the start tag.  The
-\var{attributes} argument is a dictionary of attributes, the key being
-the \var{name} and the value being the \var{value} of the attribute
-found inside the tag's \code{<>} brackets.  Character and entity
-references in the \var{value} have been interpreted.  For instance,
-for the start tag \code{<A HREF="http://www.cwi.nl/">}, this method
-would be called as \code{handle_starttag('A', self.elements['A'][0],
-\{'HREF': 'http://www.cwi.nl/'\})}.  The base implementation simply
-calls \var{method} with \var{attributes} as the only argument.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_endtag}{tag, method}
-This method is called to handle endtags for which an end tag handler
-is defined in the instance variable \member{elements}.  The \var{tag}
-argument is the name of the tag, and the \var{method} argument is the
-function (method) which should be used to support semantic
-interpretation of the end tag.  For instance, for the endtag
-\code{</A>}, this method would be called as \code{handle_endtag('A',
-self.elements['A'][1])}.  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};}.  \var{ref} can either be a decimal number,
-or a hexadecimal number when preceded by an \character{x}.
-In the base implementation, \var{ref} must be a number in the
-range 0-255.  It translates the character to \ASCII{} and calls the
-method \method{handle_data()} with the character as argument.  If
-\var{ref} is invalid or out of range, the method
-\code{unknown_charref(\var{ref})} is called to handle the error.  A
-subclass must override this method to provide support for character
-references outside of the \ASCII{} range.
-\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_cdata}{data}
-This method is called when a CDATA element is encountered.  The
-\var{data} argument is a string containing the text between the
-\samp{<![CDATA[} and \samp{]]>} delimiters, but not the delimiters
-themselves.  For example, the entity \samp{<![CDATA[text]]>} will
-cause this method to be called with the argument \code{'text'}.  The
-default method does nothing, and is intended to be overridden.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_proc}{name, data}
-This method is called when a processing instruction (PI) is
-encountered.  The \var{name} is the PI target, and the \var{data}
-argument is a string containing the text between the PI target and the
-closing delimiter, but not the delimiter itself.  For example, the
-instruction \samp{<?XML text?>} will cause this method to be called
-with the arguments \code{'XML'} and \code{'text'}.  The default method
-does nothing.  Note that if a document starts with \samp{<?xml
-..?>}, \method{handle_xml()} is called to handle it.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_special}{data}
-This method is called when a declaration is encountered.  The
-\var{data} argument is a string containing the text between the
-\samp{<!} and \samp{>} delimiters, but not the delimiters
-themselves.  For example, the \index{ENTITY declaration}entity
-declaration \samp{<!ENTITY text>} will cause this method to be called
-with the argument \code{'ENTITY text'}.  The default method does
-nothing.  Note that \samp{<!DOCTYPE ...>} is handled separately if it
-is located at the start of the document.
-\end{methoddesc}
-
-\begin{methoddesc}{syntax_error}{message}
-This method is called when a syntax error is encountered.  The
-\var{message} is a description of what was wrong.  The default method 
-raises a \exception{RuntimeError} exception.  If this method is
-overridden, it is permissible for it to return.  This method is only
-called when the error can be recovered from.  Unrecoverable errors
-raise a \exception{RuntimeError} without first calling
-\method{syntax_error()}.
-\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.  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 calls \method{syntax_error()} to signal an error.
-\end{methoddesc}
-
-
-\begin{seealso}
-  \seetitle[http://www.w3.org/TR/REC-xml]{Extensible Markup Language
-            (XML) 1.0}{The XML specification, published by the World
-            Wide Web Consortium (W3C), defines the syntax and
-            processor requirements for XML.  References to additional
-            material on XML, including translations of the
-            specification, are available at
-            \url{http://www.w3.org/XML/}.}
-
-  \seetitle[http://www.python.org/topics/xml/]{Python and XML
-            Processing}{The Python XML Topic Guide provides a great
-            deal of information on using XML from Python and links to
-            other sources of information on XML.}
-
-  \seetitle[http://www.python.org/sigs/xml-sig/]{SIG for XML
-            Processing in Python}{The Python XML Special Interest
-            Group is developing substantial support for processing XML
-            from Python.}
-\end{seealso}
-
-
-\subsection{XML Namespaces \label{xml-namespace}}
-
-This module has support for XML namespaces as defined in the XML
-Namespaces proposed recommendation.
-\indexii{XML}{namespaces}
-
-Tag and attribute names that are defined in an XML namespace are
-handled as if the name of the tag or element consisted of the
-namespace (the URL that defines the namespace) followed by a
-space and the name of the tag or attribute.  For instance, the tag
-\code{<html xmlns='http://www.w3.org/TR/REC-html40'>} is treated as if 
-the tag name was \code{'http://www.w3.org/TR/REC-html40 html'}, and
-the tag \code{<html:a href='http://frob.com'>} inside the above
-mentioned element is treated as if the tag name were
-\code{'http://www.w3.org/TR/REC-html40 a'} and the attribute name as
-if it were \code{'http://www.w3.org/TR/REC-html40 href'}.
-
-An older draft of the XML Namespaces proposal is also recognized, but
-triggers a warning.
-
-\begin{seealso}
-  \seetitle[http://www.w3.org/TR/REC-xml-names/]{Namespaces in XML}{
-           This World Wide Web Consortium recommendation describes the
-           proper syntax and processing requirements for namespaces in
-           XML.}
-\end{seealso}
diff --git a/Doc/lib/libxmlrpclib.tex b/Doc/lib/libxmlrpclib.tex
deleted file mode 100644
index fdd4e72..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{__nonzero__()} 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, 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 098e788..0000000
--- a/Doc/lib/libzipimport.tex
+++ /dev/null
@@ -1,133 +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.
-
-Using the built-in \function{reload()} function will
-fail if called on a module loaded from a ZIP archive; it is unlikely that
-\function{reload()} would be needed, since this would imply that the ZIP
-has been altered during runtime.
-
-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 0d923a72..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 3460498..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 a741f6c..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 200a064..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 e956402..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 22525e3..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 = raw_input()
-    if line == "":
-        break
-    buffer += line
-    if sqlite3.complete_statement(buffer):
-        try:
-            buffer = buffer.strip()
-            cur.execute(buffer)
-
-            if buffer.lstrip().upper().startswith("SELECT"):
-                print cur.fetchall()
-        except sqlite3.Error, e:
-            print "An error occurred:", e.args[0]
-        buffer = ""
-
-con.close()
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 f9728b36..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 e220e9b..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 = 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 df04cad..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 8044ecf..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 d27d735..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 fb3784f..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 df6c894..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 b64621f..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 24357c5..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 05857c0..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 5769687..0000000
--- a/Doc/lib/sqlite3/md5func.py
+++ /dev/null
@@ -1,11 +0,0 @@
-import sqlite3
-import md5
-
-def md5sum(t):
-    return md5.md5(t).hexdigest()
-
-con = sqlite3.connect(":memory:")
-con.create_function("md5", 1, md5sum)
-cur = con.cursor()
-cur.execute("select md5(?)", ("foo",))
-print cur.fetchone()[0]
diff --git a/Doc/lib/sqlite3/mysumaggr.py b/Doc/lib/sqlite3/mysumaggr.py
deleted file mode 100644
index 6d0cd55..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 fcded00..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 efa4b06..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 64676c8..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 72ed4b3..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 67ea6a2..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) ,
-print # Finish the header with a newline.
-print '-' * 78
-
-# For each row, print the value of each field left-justified within
-# the maximum possible width of that field.
-fieldIndices = range(len(cur.description))
-for row in cur:
-    for fieldIndex in fieldIndices:
-        fieldValue = str(row[fieldIndex])
-        print fieldValue.ljust(FIELD_MAX_WIDTH) ,
-
-    print # Finish the row with a newline.
diff --git a/Doc/lib/sqlite3/text_factory.py b/Doc/lib/sqlite3/text_factory.py
deleted file mode 100644
index 3e157a8..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 = u"\xd6sterreich"
-
-# by default, rows are returned as Unicode
-cur.execute("select ?", (AUSTRIA,))
-row = cur.fetchone()
-assert row[0] == AUSTRIA
-
-# but we can make pysqlite always return bytestrings ...
-con.text_factory = str
-cur.execute("select ?", (AUSTRIA,))
-row = cur.fetchone()
-assert type(row[0]) == str
-# the bytestrings will be encoded in UTF-8, unless you stored garbage in the
-# database ...
-assert row[0] == AUSTRIA.encode("utf-8")
-
-# we can also implement a custom text_factory ...
-# here we implement one that will ignore Unicode characters that cannot be
-# decoded from UTF-8
-con.text_factory = lambda x: unicode(x, "utf-8", "ignore")
-cur.execute("select ?", ("this is latin1 and would normally create errors" + u"\xe4\xf6\xfc".encode("latin1"),))
-row = cur.fetchone()
-assert type(row[0]) == unicode
-
-# pysqlite offers a builtin optimized text_factory that will return bytestring
-# objects, if the data is in ASCII only, and otherwise return unicode objects
-con.text_factory = sqlite3.OptimizedUnicode
-cur.execute("select ?", (AUSTRIA,))
-row = cur.fetchone()
-assert type(row[0]) == unicode
-
-cur.execute("select ?", ("Germany",))
-row = cur.fetchone()
-assert type(row[0]) == str
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{\&amp;}, \character{\&lt;}, and \character{\&gt;}
-  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 &quot; 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 96e4900..0000000
--- a/Doc/mac/undoc.tex
+++ /dev/null
@@ -1,97 +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{cfmfile} --- Code Fragment Resource module}
-\declaremodule{standard}{cfmfile}
-  \platform{Mac}
-\modulesynopsis{Code Fragment Resource module.}
-
-\module{cfmfile} is a module that understands Code Fragments and the
-accompanying ``cfrg'' resources. It can parse them and merge them, and is
-used by BuildApplication to combine all plugin modules to a single
-executable.
-
-\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>/\&amp;/g;
-        $data .= ('  <tr'
-                  . ($oddrow ? " class='oddrow'>\n      " : '>')
-                  . "<td><b><tt class='module'>$link$name</a></tt></b></td>\n"
-                  . "      <td>\&nbsp;</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/ *~/&nbsp;/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'>&#92;$macro</tt>" . $_;
-}
-
-sub do_cmd_env{
-    local($_) = @_;
-    my $env = ltx_next_argument();
-    return "<tt class='environment'>&#92;$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'>&#92;$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>&#92;begin{<b class='environment'>$env</b>}</tt>"
-         . "\n    $params"
-         . "\n<br /><tt>&#92;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 cf0301e..0000000
--- a/Doc/perl/python.perl
+++ /dev/null
@@ -1,2178 +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{ '&#126;' . $_[0]; }
-sub do_cmd_textasciicircum{ '^' . $_[0]; }
-sub do_cmd_textbar{ '|' . $_[0]; }
-sub do_cmd_texteuro { '&#8364;' . $_[0]; }
-sub do_cmd_textgreater{ '&gt;' . $_[0]; }
-sub do_cmd_textless{ '&lt;' . $_[0]; }
-sub do_cmd_textunderscore{ '_' . $_[0]; }
-sub do_cmd_infinity{ '&infin;' . $_[0]; }
-sub do_cmd_plusminus{ '&plusmn;' . $_[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> &gt; <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{ '&#92;' . $_[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/--/-\&#45;/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/~/&#126;/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 $text = "$type in version $release.";
-    if ($explanation) {
-        $text = "$type in version $release:\n$explanation.";
-    }
-    return "\n<span class=\"versionnote\">$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/^( +)/'&nbsp;' 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>&nbsp;';
-
-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\&nbsp;<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 .= "&nbsp;&nbsp;&nbsp;&nbsp;<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/\&/\&amp;/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/<</\&lt;\&\#60;/g;
-        $text =~ s/>>/\&gt;\&\#62;/g;
-        # Just normal re-writes...
-        $text =~ s/</\&lt;/g;
-        $text =~ s/>/\&gt;/g;
-        # These last isn't needed for the HTML, but is needed to get
-        # past LaTeX2HTML processing TeX macros.  We use &#92; instead
-        # of &sol; 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 bad4609..0000000
--- a/Doc/ref/ref2.tex
+++ /dev/null
@@ -1,731 +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       del       from      not       while    
-as        elif      global    or        with     
-assert    else      if        pass      yield    
-break     except    import    print              
-class     exec      in        raise              
-continue  finally   is        return             
-def       for       lambda    try 
-\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{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 and long integer literals\label{integers}}
-
-Integer and long integer literals are described by the following
-lexical definitions:
-
-\begin{productionlist}
-  \production{longinteger}
-             {\token{integer} ("l" | "L")}
-  \production{integer}
-             {\token{decimalinteger} | \token{octinteger} | \token{hexinteger}}
-  \production{decimalinteger}
-             {\token{nonzerodigit} \token{digit}* | "0"}
-  \production{octinteger}
-             {"0" \token{octdigit}+}
-  \production{hexinteger}
-             {"0" ("x" | "X") \token{hexdigit}+}
-  \production{nonzerodigit}
-             {"1"..."9"}
-  \production{octdigit}
-             {"0"..."7"}
-  \production{hexdigit}
-             {\token{digit} | "a"..."f" | "A"..."F"}
-\end{productionlist}
-
-Although both lower case \character{l} and upper case \character{L} are
-allowed as suffix for long integers, it is strongly recommended to always
-use \character{L}, since the letter \character{l} looks too much like the
-digit \character{1}.
-
-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.
-
-Some examples of plain integer literals (first row) and long integer
-literals (second and third rows):
-
-\begin{verbatim}
-7     2147483647                        0177
-3L    79228162514264337593543950336L    0377L   0x100000000L
-      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 of floating point numbers
-can look like octal integers, but are 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}
-
-The comparison operators \code{<>} and \code{!=} are alternate
-spellings of the same operator.  \code{!=} is the preferred spelling;
-\code{<>} is obsolescent.
-
-
-\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 14b2594..0000000
--- a/Doc/ref/ref3.tex
+++ /dev/null
@@ -1,2230 +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 built-in name \code{Ellipsis}.
-It is used to indicate the presence of the \samp{...} syntax in a
-slice.  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{func_doc}{The function's documentation string, or
-    \code{None} if unavailable}{Writable}
-
-  \lineiii{__doc__}{Another way of spelling
-    \member{func_doc}}{Writable}
-
-  \lineiii{func_name}{The function's name}{Writable}
-
-  \lineiii{__name__}{Another way of spelling
-    \member{func_name}}{Writable}
-
-  \lineiii{__module__}{The name of the module the function was defined
-    in, or \code{None} if unavailable.}{Writable}
-
-  \lineiii{func_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{func_code}{The code object representing the compiled
-    function body.}{Writable}
-
-  \lineiii{func_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{func_dict}{The namespace supporting arbitrary function
-    attributes.}{Writable}
-
-  \lineiii{func_closure}{\code{None} or a tuple of cells that contain
-    bindings for the function's free variables.}{Read-only}
-\end{tableiii}
-
-Most of the attributes labelled ``Writable'' check the type of the
-assigned value.
-
-\versionchanged[\code{func_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{func_doc}
-  \ttindex{__doc__}
-  \ttindex{__name__}
-  \ttindex{__module__}
-  \ttindex{__dict__}
-  \ttindex{func_defaults}
-  \ttindex{func_closure}
-  \ttindex{func_code}
-  \ttindex{func_globals}
-  \ttindex{func_dict}}
-\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 func_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_restricted} is a flag indicating whether the function is
-executing in restricted execution mode; \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}
-  \ttindex{f_restricted}}
-
-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 \code{sys.exc_traceback}, and also as the third
-item of the tuple returned by \code{sys.exc_info()}.  The latter is
-the preferred interface, since it works correctly when the program is
-using multiple threads.
-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.exc_traceback}
-\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_traceback} 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.exc_traceback} or \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}} and \code{\var{x}<>\var{y}} call
-\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]{__nonzero__}{self}
-Called to implement truth value testing, and the built-in operation
-\code{bool()}; should return \code{False} or \code{True}, or their
-integer equivalents \code{0} or \code{1}.
-When this method is not defined, \method{__len__()} is
-called, if it is defined (see below).  If a class defines neither
-\method{__len__()} nor \method{__nonzero__()}, 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 \method{__coerce__()} or 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__()}}
-\withsubitem{(numeric object method)}{\ttindex{__coerce__()}}
-
-\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{__nonzero__()} method and whose \method{__len__()} method
-returns zero is considered to be false in a Boolean context.
-\withsubitem{(object method)}{\ttindex{__nonzero__()}}
-\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]{__oct__}{self}
-\methodline[numeric object]{__hex__}{self}
-Called to implement the built-in functions
-\function{oct()}\bifuncindex{oct} and
-\function{hex()}\bifuncindex{hex}.  Should return a string value.
-\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).  Must return an
-integer (int or long).
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[numeric object]{__coerce__}{self, other}
-Called to implement ``mixed-mode'' numeric arithmetic.  Should either
-return a 2-tuple containing \var{self} and \var{other} converted to
-a common numeric type, or \code{None} if conversion is impossible.  When
-the common type would be the type of \code{other}, it is sufficient to
-return \code{None}, since the interpreter will also ask the other
-object to attempt a coercion (but sometimes, if the implementation of
-the other type cannot be changed, it is useful to do the conversion to
-the other type here).  A return value of \code{NotImplemented} is
-equivalent to returning \code{None}.
-\end{methoddesc}
-
-\subsection{Coercion rules\label{coercion-rules}}
-
-This section used to document the rules for coercion.  As the language
-has evolved, the coercion rules have become hard to document
-precisely; documenting what one version of one particular
-implementation does is undesirable.  Instead, here are some informal
-guidelines regarding coercion.  In Python 3.0, coercion will not be
-supported.
-
-\begin{itemize}
-
-\item
-
-If the left operand of a \% operator is a string or Unicode object, no
-coercion takes place and the string formatting operation is invoked
-instead.
-
-\item
-
-It is no longer recommended to define a coercion operation.
-Mixed-mode operations on types that don't define coercion pass the
-original arguments to the operation.
-
-\item
-
-New-style classes (those derived from \class{object}) never invoke the
-\method{__coerce__()} method in response to a binary operator; the only
-time \method{__coerce__()} is invoked is when the built-in function
-\function{coerce()} is called.
-
-\item
-
-For most intents and purposes, an operator that returns
-\code{NotImplemented} is treated the same as one that is not
-implemented at all.
-
-\item
-
-Below, \method{__op__()} and \method{__rop__()} are used to signify
-the generic method names corresponding to an operator;
-\method{__iop__()} is used for the corresponding in-place operator.  For
-example, for the operator `\code{+}', \method{__add__()} and
-\method{__radd__()} are used for the left and right variant of the
-binary operator, and \method{__iadd__()} for the in-place variant.
-
-\item
-
-For objects \var{x} and \var{y}, first \code{\var{x}.__op__(\var{y})}
-is tried.  If this is not implemented or returns \code{NotImplemented},
-\code{\var{y}.__rop__(\var{x})} is tried.  If this is also not
-implemented or returns \code{NotImplemented}, a \exception{TypeError}
-exception is raised.  But see the following exception:
-
-\item
-
-Exception to the previous item: if the left operand is an instance of
-a built-in type or a new-style class, and the right operand is an instance
-of a proper subclass of that type or class and overrides the base's
-\method{__rop__()} method, the right operand's \method{__rop__()} method
-is tried \emph{before} the left operand's \method{__op__()} method.
-
-This is done so that a subclass can completely override binary operators.
-Otherwise, the left operand's \method{__op__()} method would always
-accept the right operand: when an instance of a given class is expected,
-an instance of a subclass of that class is always acceptable.
-
-\item
-
-When either operand type defines a coercion, this coercion is called
-before that type's \method{__op__()} or \method{__rop__()} method is
-called, but no sooner.  If the coercion returns an object of a
-different type for the operand whose coercion is invoked, part of the
-process is redone using the new object.
-
-\item
-
-When an in-place operator (like `\code{+=}') is used, if the left
-operand implements \method{__iop__()}, it is invoked without any
-coercion.  When the operation falls back to \method{__op__()} and/or
-\method{__rop__()}, the normal coercion rules apply.
-
-\item
-
-In \var{x}\code{+}\var{y}, if \var{x} is a sequence that implements
-sequence concatenation, sequence concatenation is invoked.
-
-\item
-
-In \var{x}\code{*}\var{y}, if one operator is a sequence that
-implements sequence repetition, and the other is an integer
-(\class{int} or \class{long}), sequence repetition is invoked.
-
-\item
-
-Rich comparisons (implemented by methods \method{__eq__()} and so on)
-never use coercion.  Three-way comparison (implemented by
-\method{__cmp__()}) does use coercion under the same conditions as
-other binary operations use it.
-
-\item
-
-In the current implementation, the built-in numeric types \class{int},
-\class{long} and \class{float} do not use coercion; the type
-\class{complex} however does use it.  The difference can become
-apparent when subclassing these types.  Over time, the type
-\class{complex} may be fixed to avoid coercion.  All these types
-implement a \method{__coerce__()} method, for use by the built-in
-\function{coerce()} function.
-
-\end{itemize}
-
-\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 f38b948..0000000
--- a/Doc/ref/ref4.tex
+++ /dev/null
@@ -1,215 +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 file read by the built-in function \function{execfile()}
-is a code block.  The string argument passed to the built-in function
-\function{eval()} and to the \keyword{exec} statement 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}.
-
-If \keyword{exec} is used in a function and the function contains or
-is a nested block with free variables, the compiler will raise a
-\exception{SyntaxError} unless the exec explicitly specifies the local
-namespace for the \keyword{exec}.  (In other words, \samp{exec obj}
-would be illegal, but \samp{exec obj in ns} would be legal.)
-
-The \function{eval()}, \function{execfile()}, and \function{input()}
-functions and the \keyword{exec} statement 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 \keyword{exec} statement and the \function{eval()} and
-\function{execfile()} 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 73015aa..0000000
--- a/Doc/ref/ref5.tex
+++ /dev/null
@@ -1,1325 +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{String conversions\label{string-conversions}}
-\indexii{string}{conversion}
-\indexii{reverse}{quotes}
-\indexii{backward}{quotes}
-\index{back-quotes}
-
-A string conversion is an expression list enclosed in reverse (a.k.a.
-backward) quotes:
-
-\begin{productionlist}
-  \production{string_conversion}
-             {"`" \token{expression_list} "`"}
-\end{productionlist}
-
-A string conversion evaluates the contained expression list and
-converts the resulting object into a string according to rules
-specific to its type.
-
-If the object is a string, a number, \code{None}, or a tuple, list or
-dictionary containing only objects whose type is one of these, the
-resulting string is a valid Python expression which can be passed to
-the built-in function \function{eval()} to yield an expression with the
-same value (or an approximation, if floating point numbers are
-involved).
-
-(In particular, converting a string adds quotes around it and converts
-``funny'' characters to escape sequences that are safe to print.)
-
-Recursive objects (for example, lists or dictionaries that contain a
-reference to themselves, directly or indirectly) use \samp{...} to
-indicate a recursive reference, and the result cannot be passed to
-\function{eval()} to get an equal value (\exception{SyntaxError} will
-be raised instead).
-\obindex{recursive}
-
-The built-in function \function{repr()} performs exactly the same
-conversion in its argument as enclosing it in parentheses and reverse
-quotes does.  The built-in function \function{str()} performs a
-similar but more user-friendly conversion.
-\bifuncindex{repr}
-\bifuncindex{str}
-
-
-\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 an ellipsis slice
-item is the built-in \code{Ellipsis} object.  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.  Formal parameters using the syntax
-\samp{(sublist)} cannot be used as keyword argument names; the
-outermost sublist corresponds to a single unnamed argument slot, and
-the argument value is assigned to the sublist using the usual tuple
-assignment rules after all other parameter processing is done.
-
-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 forms \code{<>} and \code{!=} are equivalent; for consistency with
-C, \code{!=} is preferred; where \code{!=} is mentioned below
-\code{<>} is also accepted.  The \code{<>} spelling is considered
-obsolescent.
-
-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.
-\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{!=}, \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 1fc885e..0000000
--- a/Doc/ref/ref6.tex
+++ /dev/null
@@ -1,928 +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{print_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}}
-  \productioncont{| \token{exec_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{print} statement \label{print}}
-\stindex{print}
-
-\begin{productionlist}
-  \production{print_stmt}
-             {"print" ([\token{expression} ("," \token{expression})* [","]}
-  \productioncont{| ">>" \token{expression}
-                  [("," \token{expression})+ [","])}
-\end{productionlist}
-
-\keyword{print} evaluates each expression in turn and writes the
-resulting object to standard output (see below).  If an object is not
-a string, it is first converted to a string using the rules for string
-conversions.  The (resulting or original) string is then written.  A
-space is written before each object is (converted and) written, unless
-the output system believes it is positioned at the beginning of a
-line.  This is the case (1) when no characters have yet been written
-to standard output, (2) when the last character written to standard
-output is \character{\e n}, or (3) when the last write operation on
-standard output was not a \keyword{print} statement.  (In some cases
-it may be functional to write an empty string to standard output for
-this reason.)  \note{Objects which act like file objects but which are
-not the built-in file objects often do not properly emulate this
-aspect of the file object's behavior, so it is best not to rely on
-this.}
-\index{output}
-\indexii{writing}{values}
-
-A \character{\e n} character is written at the end, unless the
-\keyword{print} statement ends with a comma.  This is the only action
-if the statement contains just the keyword \keyword{print}.
-\indexii{trailing}{comma}
-\indexii{newline}{suppression}
-
-Standard output is defined as the file object named \code{stdout}
-in the built-in module \module{sys}.  If no such object exists, or if
-it does not have a \method{write()} method, a \exception{RuntimeError}
-exception is raised.
-\indexii{standard}{output}
-\refbimodindex{sys}
-\withsubitem{(in module sys)}{\ttindex{stdout}}
-\exindex{RuntimeError}
-
-\keyword{print} also has an extended\index{extended print statement}
-form, defined by the second portion of the syntax described above.
-This form is sometimes referred to as ``\keyword{print} chevron.''
-In this form, the first expression after the \code{>>} must
-evaluate to a ``file-like'' object, specifically an object that has a
-\method{write()} method as described above.  With this extended form,
-the subsequent expressions are printed to this file object.  If the
-first expression evaluates to \code{None}, then \code{sys.stdout} is
-used as the file for output.
-
-
-\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 an \keyword{exec} statement or calls to the builtin functions
-\function{compile()} and \function{execfile()} 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 an
-\keyword{exec} statement does not affect the code block \emph{containing}
-the \keyword{exec} statement, and code contained in an \keyword{exec}
-statement is unaffected by \keyword{global} statements in the code
-containing the \keyword{exec} statement.  The same applies to the
-\function{eval()}, \function{execfile()} and \function{compile()} functions.
-\stindex{exec}
-\bifuncindex{eval}
-\bifuncindex{execfile}
-\bifuncindex{compile}
-
-
-\section{The \keyword{exec} statement \label{exec}}
-\stindex{exec}
-
-\begin{productionlist}
-  \production{exec_stmt}
-             {"exec" \token{or_expr}
-              ["in" \token{expression} ["," \token{expression}]]}
-\end{productionlist}
-
-This statement supports dynamic execution of Python code.  The first
-expression should evaluate to 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 section~\ref{file-input}, ``File input'').  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 \keyword{exec} statement.
-
-In all cases, if the optional parts are omitted, the code is executed
-in the current scope.  If only the first expression after \keyword{in}
-is specified, it should be a dictionary, which will be used for both
-the global and the local variables.  If two expressions are given,
-they are used for the global and local variables, respectively.
-If provided, \var{locals} can be any mapping object.
-\versionchanged[formerly \var{locals} was required to be a dictionary]{2.4}
-
-As a side effect, an implementation may insert additional keys into
-the dictionaries given besides those corresponding to variable names
-set by the executed code.  For example, the current implementation
-may add a reference to the dictionary of the built-in module
-\module{__builtin__} under the key \code{__builtins__} (!).
-\ttindex{__builtins__}
-\refbimodindex{__builtin__}
-
-\strong{Programmer's hints:}
-dynamic evaluation of expressions is supported by the built-in
-function \function{eval()}.  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 by \keyword{exec}.
-\bifuncindex{eval}
-\bifuncindex{globals}
-\bifuncindex{locals}
-
-  
-
-
-
diff --git a/Doc/ref/ref7.tex b/Doc/ref/ref7.tex
deleted file mode 100644
index c9e07fb..0000000
--- a/Doc/ref/ref7.tex
+++ /dev/null
@@ -1,544 +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 assigned to three variables in the
-\module{sys}\refbimodindex{sys} module: \code{sys.exc_type} receives
-the object identifying the exception; \code{sys.exc_value} receives
-the exception's parameter; \code{sys.exc_traceback} receives a
-traceback object\obindex{traceback} (see section~\ref{traceback})
-identifying the point in the program where the exception occurred.
-These details are also available through the \function{sys.exc_info()}
-function, which returns a tuple \code{(\var{exc_type}, \var{exc_value},
-\var{exc_traceback})}.  Use of the corresponding variables is
-deprecated in favor of this function, since their use is unsafe in a
-threaded program.  As of Python 1.5, the variables are restored to
-their previous values (before the call) when returning from a function
-that handled an exception.
-\withsubitem{(in module sys)}{\ttindex{exc_type}
-  \ttindex{exc_value}\ttindex{exc_traceback}}
-
-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{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{identifier} [, "**" \token{identifier}]}
-  \productioncont{ | "**" \token{identifier}}
-  \productioncont{ | \token{defparameter} [","] )}
-  \production{defparameter}
-             {\token{parameter} ["=" \token{expression}]}
-  \production{sublist}
-             {\token{parameter} ("," \token{parameter})* [","]}
-  \production{parameter}
-             {\token{identifier} | "(" \token{sublist} ")"}
-  \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 top-level 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 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.
-
-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.
-\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 b77789f..0000000
--- a/Doc/ref/ref8.tex
+++ /dev/null
@@ -1,112 +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 \keyword{exec} statement;
-
-\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
-built-in function \function{raw_input()} or the \method{readline()} method
-of file objects.
-\obindex{file}
-\index{input!raw}
-\index{raw input}
-\bifuncindex{raw_input}
-\withsubitem{(file method)}{\ttindex{readline()}}
diff --git a/Doc/ref/reswords.py b/Doc/ref/reswords.py
deleted file mode 100644
index 68862bb..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 5870462..0000000
--- a/Doc/tools/buildindex.py
+++ /dev/null
@@ -1,388 +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 = split_entry_key(str)
-
-    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 15f07ba..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 modules.has_key('types'):
-    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 = modules.keys()
-mlist = filter(lambda x, docs=docs: docs.has_key(x), 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 ac9b754..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, 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 d22c16d..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 5bab0fb..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 StringIO
-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 = StringIO.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 9f32056..0000000
--- a/Doc/tools/keywords.py
+++ /dev/null
@@ -1,19 +0,0 @@
-#! /usr/bin/env python
-
-# This Python program sorts and reformats the table of keywords in ref2.tex
-
-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),
-    print
diff --git a/Doc/tools/listmodules b/Doc/tools/listmodules
deleted file mode 100755
index ad4d95e..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, 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 5f3ea02..0000000
--- a/Doc/tools/listmodules.py
+++ /dev/null
@@ -1,126 +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 = modules.keys()
-    keys.sort()
-
-    # 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 2c79f5e..0000000
--- a/Doc/tools/mkackshtml
+++ /dev/null
@@ -1,66 +0,0 @@
-#! /usr/bin/env python
-#  -*- Python -*-
-
-import string
-import support
-import sys
-
-
-def collect(fp):
-    names = []
-    while 1:
-        line = fp.readline()
-        if not line:
-            break
-        line = string.strip(line)
-        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(string.rstrip(options.get_header()) + "\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(string.rstrip(options.get_footer()) + "\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 21cd6fb..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 >>file, __doc__ % options
-
-def error(options, message, err=2):
-    print >>sys.stderr, message
-    print >>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."
-                        % `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, 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 8e869f9..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>&nbsp;</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 4b21f77..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, 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 57a43fd..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&reg; 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, 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, 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 >> f, word
-        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 ccfc8c6..0000000
--- a/Doc/tools/refcounts.py
+++ /dev/null
@@ -1,98 +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 = d.items()
-    items.sort()
-    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>&gt;</text>
-    </macro>
-  <macro name="textless" outputname="">
-    <text>&lt;</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 81519ee..0000000
--- a/Doc/tools/sgmlconv/docfixer.py
+++ /dev/null
@@ -1,1073 +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 wsmap.has_key(node.nodeName):
-            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 d.has_key(key):
-            del d[key]
-    knownempty = d.has_key
-    #
-    try:
-        write_esis(fragment, ofp, knownempty)
-    except IOError, (err, msg):
-        # 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 StringIO
-        ofp = StringIO.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 b6f9a44..0000000
--- a/Doc/tools/sgmlconv/esis2sgml.py
+++ /dev/null
@@ -1,264 +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 = attrs.items()
-    attrs.sort()
-    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("---", "&mdash;")
-            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 = d.keys()
-    gilist.sort()
-    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, (err, msg):
-        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 833fea1..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 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, 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 self._attrs.has_key(name):
-            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 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 643ef2c..0000000
--- a/Doc/tools/sgmlconv/latex2esis.py
+++ /dev/null
@@ -1,565 +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, (err, msg):
-        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 attrs.has_key("outputname"):
-            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 attrs.has_key("outputname"):
-            self.__current.outputname = attrs.get("outputname")
-    def end_macro(self):
-        name = self.__current.name
-        if self.__table.has_key(name):
-            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 3d776fa..0000000
--- a/Doc/tools/undoc_symbols.py
+++ /dev/null
@@ -1,94 +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.xreadlines():
-        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 = dict.keys()
-    names.sort()
-    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 17cc767..0000000
--- a/Doc/tut/glossary.tex
+++ /dev/null
@@ -1,352 +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{coercion}
-\item[coercion]
-The implicit conversion of an instance of one type to another during an
-operation which involves two arguments of the same type.  For example,
-{}\code{int(3.15)} converts the floating point number to the integer
-{}\code{3}, but in {}\code{3+4.5}, each argument is of a different type (one
-int, one float), and both must be converted to the same type before they can
-be added or it will raise a {}\code{TypeError}.  Coercion between two
-operands can be performed with the {}\code{coerce} builtin function; thus,
-{}\code{3+4.5} is equivalent to calling {}\code{operator.add(*coerce(3,
-4.5))} and results in {}\code{operator.add(3.0, 4.5)}.  Without coercion,
-all arguments of even compatible types would have to be normalized to the
-same value by the programmer, e.g., {}\code{float(3)+4.5} rather than just
-{}\code{3+4.5}.
-
-\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.  For
-example, the expression \code{11/4} currently evaluates to \code{2}.
-If the module in which it is executed had enabled \emph{true division}
-by executing:
-
-\begin{verbatim}
-from __future__ import division
-\end{verbatim}
-
-the expression \code{11/4} would evaluate to \code{2.75}.  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 discarding any remainder.  For example, the
-expression \code{11/4} currently evaluates to \code{2} in contrast
-to the \code{2.75} returned by float division.  Also called
-{}\emph{floor division}.  When dividing two integers the outcome will
-always be another integer (having the floor function applied to it).
-However, if one of the operands is another numeric type (such as a
-{}\class{float}), the result will be coerced (see \emph{coercion}) to
-a common type.  For example, an integer divided by a float will result
-in a float value, possibly with a decimal fraction.  Integer division
-can be forced by using the \code{//} operator instead of the \code{/}
-operator.  See also \emph{__future__}.
-
-\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 c875979..0000000
--- a/Doc/tut/tut.tex
+++ /dev/null
@@ -1,5946 +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 Python26}, 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:\python26
-\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 calls to \function{input()} and \function{raw_input()}, 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'):
-execfile('.pythonrc.py')}.  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):
-    execfile(filename)
-\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}
->>> 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 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 three built-in functions that are very useful when used with
-lists: \function{filter()}, \function{map()}, and \function{reduce()}.
-
-\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}
-
-\samp{reduce(\var{function}, \var{sequence})} returns a single value
-constructed by calling the binary function \var{function} on the first two
-items of the sequence, then on the result and the next item, and so
-on.  For example, to compute the sum of the numbers 1 through 10:
-
-\begin{verbatim}
->>> def add(x,y): return x+y
-...
->>> reduce(add, range(1, 11))
-55
-\end{verbatim}
-
-If there's only one item in the sequence, its value is returned; if
-the sequence is empty, an exception is raised.
-
-A third argument can be passed to indicate the starting value.  In this
-case the starting value is returned for an empty sequence, and the
-function is first applied to the starting value and the first sequence
-item, then to the result and the next item, and so on.  For example,
-
-\begin{verbatim}
->>> def sum(seq):
-...     def add(x,y): return x+y
-...     return reduce(add, seq, 0)
-... 
->>> sum(range(1, 11))
-55
->>> sum([])
-0
-\end{verbatim}
-
-Don't use this example's definition of \function{sum()}: since summing
-numbers is such a common need, a built-in function
-\code{sum(\var{sequence})} is already provided, and works exactly like
-this.
-\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(xrange(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_clear', 'exc_info', 'exc_type', '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', 'StandardError', 'StopIteration', 'SyntaxError',
- 'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError', 'True',
- 'TypeError', 'UnboundLocalError', 'UnicodeDecodeError',
- 'UnicodeEncodeError', 'UnicodeError', 'UnicodeTranslateError',
- 'UserWarning', 'ValueError', 'Warning', 'WindowsError',
- 'ZeroDivisionError', '_', '__debug__', '__doc__', '__import__',
- '__name__', 'abs', 'apply', 'basestring', 'bool', 'buffer',
- 'callable', 'chr', 'classmethod', 'cmp', 'coerce', 'compile',
- 'complex', 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod',
- 'enumerate', 'eval', 'execfile', 'exit', 'file', 'filter', 'float',
- 'frozenset', 'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex',
- 'id', 'input', 'int', 'intern', 'isinstance', 'issubclass', 'iter',
- 'len', 'license', 'list', 'locals', 'long', 'map', 'max', 'min',
- 'object', 'oct', 'open', 'ord', 'pow', 'property', 'quit', 'range',
- 'raw_input', 'reduce', 'reload', 'repr', 'reversed', 'round', 'set',
- 'setattr', 'slice', 'sorted', 'staticmethod', 'str', 'sum', 'super',
- 'tuple', 'type', 'unichr', 'unicode', 'vars', 'xrange', '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}
->>> 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, (errno, strerror):
-    print "I/O error(%s): %s" % (errno, 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, 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 'exceptions.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, 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, 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}, \code{eval()} or
-\code{execfile()} 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.  This example shows how it all works:
-
-\begin{verbatim}
->>> s = 'abc'
->>> it = iter(s)
->>> it
-<iterator object at 0x00A1DB50>
->>> it.next()
-'a'
->>> it.next()
-'b'
->>> it.next()
-'c'
->>> it.next()
-
-Traceback (most recent call last):
-  File "<stdin>", line 1, in ?
-    it.next()
-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 \method{next()} is called, 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:\\Python26'
->>> 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(xrange(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
->>> 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:/python26/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/Makefile b/Doc/whatsnew/Makefile
deleted file mode 100644
index d11f97b..0000000
--- a/Doc/whatsnew/Makefile
+++ /dev/null
@@ -1,3 +0,0 @@
-
-check:
-	../../python.exe ../../Tools/scripts/texcheck.py whatsnew25.tex
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}
-- 
cgit v0.12